Skip to content

SETUP.md

Latest commit

 

History

History
319 lines (225 loc) · 6.33 KB

SETUP.md

File metadata and controls

319 lines (225 loc) · 6.33 KB
Raw

Setup Guide — Cradle AI

Complete walkthrough from zero to functional prototype in ~30 minutes.

🔧 Prerequisites

  • Python 3.10+ (check with python3 --version)
  • Node.js 16+ (optional, if using Next.js instead of plain HTML)
  • Git (for version control)
  • API Keys:
    • OpenAI (https://platform.openai.com) — GPT-5.6 (vision + language)

Step 1: Clone / Initialize

cd /home/samarine/Desktop/coding
mkdir -p cradleAI
cd cradleAI

# Or if using git:
# git clone https://github.com/your-team/cradleAI.git
# cd cradleAI

Step 2: Backend Setup

2.1 Initialize Virtual Environment

cd backend

# Create venv
python3 -m venv venv

# Activate
source venv/bin/activate  # macOS/Linux
# or
venv\Scripts\activate  # Windows

2.2 Install Dependencies

pip install -r requirements.txt

# This installs:
# - FastAPI + Uvicorn (server)
# - SQLAlchemy + SQLite (database)
# - OpenCV (video processing)
# - librosa (audio features)
# - openai (GPT-5.6 vision + language)

❗ Note: Depending on your system, some packages (OpenCV, librosa) may require additional dependencies:

macOS:

brew install ffmpeg libsndfile

Linux (Debian/Ubuntu):

sudo apt-get install ffmpeg libsndfile1

Windows: Most packages include pre-built wheels; FFmpeg must be installed separately.

2.3 Environment Configuration

# Copy example
cp .env.example .env

# Edit .env with your keys
nano .env
# or
code .env  # VS Code

Required:

OPENAI_API_KEY=sk-...   (GPT-5.6)
DATABASE_URL=sqlite:///./cradle_ai.db
CORS_ORIGINS=http://localhost:3000,http://localhost:8000,http://localhost:8001,http://localhost:5173

2.4 Initialize Database

# FastAPI will auto-create tables on first startup
# OR manually:
python -c "from app.database.db import init_db; init_db()"

2.5 Start Backend Server

python app/main.py

# Or with auto-reload:
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

✅ Success: Visit http://localhost:8000/docs (Swagger UI)

Step 3: Frontend Setup

3.1 Simple HTTP Server (Recommended for Hackathon)

cd ../frontend

# Python 3
python -m http.server 8001

# Or Python 2
python -m SimpleHTTPServer 8001

✅ Success: Visit http://localhost:8001

3.2 (Optional) Next.js Setup

If you prefer a modern JS framework:

# Create Next.js app
npx create-next-app@latest --typescript

# Copy our design into app/page.tsx
# Update API calls to use Next.js fetch

# npm run dev

Step 4: Test End-to-End

4.1 Upload a Test Video

  1. Visit http://localhost:8001 (frontend)
  2. Click "Choose file" → Select a short MP4 (30s–2min)
  3. Watch progress in browser console

4.2 Monitor Backend

In a separate terminal:

cd backend
# Watch for processing logs
tail -f /tmp/cradle_ai.log  # or wherever your logs go

4.3 Check Database

# View SQLite directly
sqlite3 cradle_ai.db

# Inside SQLite:
.tables  # List tables
SELECT COUNT(*) FROM videos;  # Check uploads
SELECT * FROM analyses LIMIT 1;  # View results
.quit

🚀 Deployment

Backend → Render

  1. Prepare repo (if using GitHub):

    git init
git add .
git commit -m "Initial commit"
git push origin main

  2. Create Render service:

    • Go to https://render.com
    • "New" → "Web Service"
    • Connect GitHub repo
    • Settings:
      • Build Command: pip install -r backend/requirements.txt
      • Start Command: cd backend && uvicorn app.main:app --host 0.0.0.0 --port 10000
    • Environment: Add env vars (OPENAI_API_KEY, etc.)
    • Deploy

  3. Test:

    curl https://your-service.onrender.com/health

Frontend → Vercel

  1. Update API endpoint in frontend/js/api.js:

    const API_BASE = 'https://your-service.onrender.com';

  2. Deploy:

    • Go to https://vercel.com
    • Import project
    • Set Framework: None (static files)
    • Deploy

🐛 Troubleshooting

Backend won't start

Issue: ModuleNotFoundError: No module named 'cv2'

Fix:

pip install opencv-python --upgrade

Issue: ffmpeg not found

Fix: Install ffmpeg for your OS (see prerequisites)

Frontend can't reach backend

Issue: CORS error in browser console

Fix:

  1. Check backend is running: curl http://localhost:8000/health
  2. Verify CORS_ORIGINS in .env includes frontend URL
  3. Restart backend after changing .env

API keys not working

Issue: 401 Unauthorized from OpenAI

Fix:

  1. Verify key in .env (check for typos, leading/trailing spaces)
  2. Test key directly: curl -H "Authorization: Bearer YOUR_KEY" https://api.openai.com/v1/models
  3. Regenerate key if needed

📝 Development Workflow

Terminal 1 — Backend:

cd backend && source venv/bin/activate && python app/main.py

Terminal 2 — Frontend:

cd frontend && python -m http.server 8001

Terminal 3 — Git (optional):

cd /path/to/cradleAI && git status

Terminal 4 — Debug:

curl http://localhost:8000/api/videos

✅ Checklist Before Submission

  • Backend running locally without errors
  • Frontend loads at http://localhost:8001
  • Can drag & drop video → status updates
  • Analysis completes without crashing
  • Results dashboard populates
  • API keys not committed to repo (in .env, ignored by git)
  • UI works on mobile (responsive CSS)
  • No console errors
  • README updated with your team info
  • Deployed to Render + Vercel (or similar)

🎯 Remaining Before Submission

  1. Run a 5–30 second sample video through the full upload flow with a real API key.
  2. Implement the GPT-5.6 summary generator (generate_summary is the last remaining stub).
  3. Fill the README Codex Session ID, truthful Codex contribution notes, team names, and demo URL.
  4. Share the private repository with the two hackathon judging addresses.
  5. Verify the demo on a clean machine before submitting.

📚 Resources

  • FastAPI docs: https://fastapi.tiangolo.com
  • OpenAI API: https://platform.openai.com/docs
  • OpenCV: https://docs.opencv.org
  • Render deployment: https://render.com/docs
  • Vercel deployment: https://vercel.com/docs

Good luck! You've got 6 days. Ship it! 🚀