ejzhu2026/video-agent-hero

POST /plan                POST /execute             POST /modify
     │                         │                         │
     ▼                         ▼                         ▼
intent_parser          executor_pipeline         change_classifier
memory_loader          caption_agent              ├─ local → partial_executor
clarification_planner  layout_branding            └─ global → planner_llm
planner_llm ◄──────    quality_gate                            │
plan_checker (loop)    qc_diagnose                    music_mixer
     │                 render_export              result_summarizer
     ▼                 music_mixer                memory_writer → END
  Plan JSON            result_summarizer
  saved to DB          memory_writer → END

{
  # Identity
  "project_id": "a1b2c3d4",
  "brief": "Summer promo for Tong Sui Coconut Watermelon",
  "brand_id": "tong_sui",

  # Plan (output of planner_llm)
  "plan": {
    "platform": "tiktok", "duration_sec": 10,
    "concept": { "mood": "fresh", "visual_style": "..." },
    "script": { "hook": "...", "body": [...], "cta": "..." },
    "storyboard": [{ "scene": 1, "desc": "...", "duration": 2.5 }, ...],
    "shot_list":  [{ "shot_id": "S1", "text_overlay": "...", "duration": 2.5 }, ...],
    "_quality": "turbo"          # written after execute
  },

  # Execution
  "scene_clips": [{ "shot_id": "S1", "clip_path": "...", "duration": 2.5 }],
  "branded_clip_path": "data/projects/.../branded.mp4",
  "output_path": "data/exports/a1b2c3d4_9x16_....mp4",

  # Quality
  "quality": "turbo",            # "turbo" | "hd"
  "quality_result": { "passed": true, "issues": [] },

  # Partial re-render
  "change_type": "local",
  "affected_shot_indices": [1],
  "shot_updates": { "1": { "desc": "...", "text_overlay": "..." } },

  # Control
  "needs_replan": false,
  "plan_version": 1,
  "messages": [...]
}

idle ──[Send brief]──► planning ──[done]──► plan_ready
                                                │
                                    Edit storyboard cards
                                    ⚡ Turbo / ✦ HD quality chip
                                    ~X credits estimate shown
                                                │
                                    [▶ Approve & Generate]
                                                │
                                           executing ──[done]──► done
                                                                   │
                                              ⚡ Turbo preview shown
                                              [✦ Upgrade to HD] button
                                                                   │
                                              [chat: "modify..."] ─┘
                                                     smart re-render

video-agent-hero/
├── web/
│   ├── server.py              # FastAPI + SSE streaming + inline HTML/JS frontend
│   ├── auth/                  # Google OAuth (router, models, deps)
│   └── billing/               # Stripe checkout + credit operations
├── agent/
│   ├── graph.py               # 4 LangGraph compiled graphs
│   ├── state.py               # AgentState TypedDict
│   ├── deps.py                # DB + VectorStore singletons
│   └── nodes/                 # 15 node functions (one file each)
├── render/
│   ├── fal_t2v.py             # fal.ai T2V wrapper (turbo/hd quality tiers)
│   ├── ffmpeg_composer.py     # concat, subtitles, watermark, trim/scale, music mix
│   ├── caption_renderer.py    # SRT/ASS subtitle file writer
│   └── frame_generator.py     # PIL placeholder frames (no-key fallback)
├── memory/
│   ├── db.py                  # SQLite (projects, brand_kits, user_prefs, feedback)
│   ├── vector_store.py        # ChromaDB semantic search
│   └── schemas.py             # Pydantic v2 models
├── cli/main.py                # Typer CLI (vah init/new/run/feedback/demo)
├── assets/                    # Brand assets (auto-generated on startup)
├── data/                      # Runtime data — gitignored
│   ├── vah.db                 # SQLite (projects + users + billing)
│   ├── chroma/                # ChromaDB
│   ├── projects/{id}/clips/   # Per-shot MP4s (reused on partial re-render)
│   └── exports/               # Final deliverable MP4s
├── Dockerfile                 # HuggingFace Spaces deployment
└── requirements.txt

brew install ffmpeg        # macOS
# sudo apt install ffmpeg  # Ubuntu
python3.11 -m venv .venv && source .venv/bin/activate

git clone https://github.com/ejzhu2025/video-agent-hero
cd video-agent-hero
pip install -r requirements.txt
uvicorn web.server:app --host 0.0.0.0 --port 7860 --reload
# Open http://localhost:7860

pip install -e .   # installs `vah` command

vah init           # seed DB with Tong Sui brand kit
vah new --brief "..." [--brand X] [--user Y]
vah run --project ID [--yes]
vah feedback --project ID --text "..."
vah list
vah demo           # full end-to-end Tong Sui demo

ANTHROPIC_API_KEY
FAL_KEY
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
REPLICATE_API_TOKEN   # optional, for background music
SESSION_SECRET        # any random string