pavo-ai-agent

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Pavo_AI_Agent-1B1B2F?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNDAiIGhlaWdodD0iNDAiIHZpZXdCb3g9IjAgMCA0MCA0MCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIyMCIgY3k9IjIwIiByPSIyMCIgZmlsbD0iI0E4QjNGRiIvPjxwYXRoIGQ9Ik0xMiAyMGwxNiAweiIgc3Ryb2tlPSIjMjIyIiBzdHJva2Utd2lkdGg9IjIiLz48cGF0aCBkPSJNMTggMTJsMCAxNiIgc3Ryb2tlPSIjMjIyIiBzdHJva2Utd2lkdGg9IjIiLz48L3N2Zz4="/> <img src="https://img.shields.io/badge/Pavo_AI_Agent-1B1B2F?style=for-the-badge&logo=openai&logoColor=white" alt="Pavo AI Agent" width="220"> </picture> </p> <p align="center"><b>Turn story inspiration into professional video storyboards — Zero dependency, AI native, MCP protocol driven</b></p> <p align="center"> <a href="docs/technical-architecture-report.md"><img src="https://img.shields.io/badge/Architecture_Report-v2.3-8A2BE2?logo=readme" alt="Architecture Report"></a> </p> <p align="center"> <a href="#"><img src="https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white" alt="Python"></a> <a href="#"><img src="https://img.shields.io/badge/SQLite-003B57?logo=sqlite&logoColor=white" alt="SQLite"></a> <a href="#"><img src="https://img.shields.io/badge/MCP-1.0-6C47FF?logo=protocol&logoColor=white" alt="MCP"></a> <a href="#"><img src="https://img.shields.io/badge/Zero_Dep-✓_No_Docker-10B981" alt="Zero Dep"></a> <a href="README_EN.md"><img src="https://img.shields.io/badge/EN-Readme-0A66C2?logo=readme" alt="English"></a> </p> <hr> <h2 align="center">✨ Two commands to get started</h2> <pre align="center"><code>pip install . pavo-mcp-server</code></pre> <p align="center">No Docker · No PostgreSQL · No Redis · No Celery · No MinIO</p> --- <h2>🚀 Project Overview</h2> <p><b>Pavo AI Agent</b> is an open-source AI video storyboard generation platform. Input natural language stories, and through the collaboration of 7 dedicated AI agents, automatically output professional shot-by-shot storyboards. Supports MCP protocol integration, personalized creation memory, and film and television professional knowledge injection.</p> <table> <tr><td width="33%"><b>🎬 Input</b><br><code>A father comes home from work, and his 5-year-old son brings him a foot bath...</code></td> <td width="33%"><b>📋 Output</b><br>Character + Scene + Props + Shot-by-shot Storyboard + BGM</td> <td width="33%"><b>📡 MCP</b><br>Cursor / Claude Code / Any MCP Client</td> </tr> </table> <h2>🏗️ System Architecture</h2> <pre> ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Cursor/MCP │ │ Claude Code │ │ Web Browser │ │ (MCP Client) │ │ (MCP Client) │ │ (Next.js) │ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │ │ │ ▼ ▼ │ ┌──────────────────┐ │ │ MCP Server │ ┌─────────────────┘ │ · 12 Tools │ │ │ · 5 Resources │ ▼ │ · 2 Prompts │ ┌──────────────┐ └────────┬─────────┘ │ FastAPI │ │ │ (port 18080)│ └─────┬──────┘ │ ▼ │ ┌──────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────┐ │ ProjectService (Core Orchestration) │ │ run_workflow() → 7 Agent Pipeline │ └────┬────┬────┬────┬────┬────┬────┬────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ┌────────────────────────────────────────┐ │ Planner → Character → Scene → Prop │ │ → Storyboard → Reviewer │ │ → Fixer │ └────────────────────────────────────────┘ │ │ ▼ ▼ ┌──────────┐ ┌──────────────────────┐ │ Memory │ │ RAG Knowledge Base │ │ · Long-term │ │ · 60+ Film & TV Knowledge Entries │ │ · Session-based │ │ · Vector Search + Re-ranking │ └──────────┘ └──────────────────────┘> 📄 Complete Architecture Analysis: <a href="docs/technical-architecture-report.md">Technical Architecture Report</a> </pre> <h2>🆕 v2.3 Core Features</h2> <table> <tr><th>Category</th><th>Feature</th><th>Description</th></tr> <tr><td><b>📡 MCP Server</b></td><td>12 Tools · 5 Resources · 2 Prompts</td><td>Standardized protocol, compatible with Cursor/Claude Desktop</td></tr> <tr><td><b>🧠 Memory + RAG</b></td><td>Dual-layer Memory · 60+ Film & TV Knowledge Entries</td><td>Cross-session style consistency + Professional knowledge injection</td></tr> <tr><td><b>👁️ Workflow Visualization</b></td><td>SVG Pipeline Diagram · Details Panel · Timeline</td><td>7 Agent real-time execution status at a glance</td></tr> <tr><td><b>♻️ Zero Dependency</b></td><td>SQLite · TTLCache · asyncio Queue · Local Storage</td><td><code>pip install .</code> Run directly, no Docker required</td></tr> <tr><td><b>🔐 Unified Security</b></td><td>API Key Guard · Environment Variable Check</td><td>User-friendly prompts when configuration is missing</td></tr> </table> <h2>📦 Installation and Launch</h2> <h3>MCP Server Mode (Recommended)</h3> <p>Integrated use in Cursor or Claude Desktop.</p> <pre><code>pip install . pavo-mcp-server</code></pre> <p>Cursor Configuration (<code>.cursor/mcp.json</code>):</p> <pre><code>{ "mcpServers": { "pavo": { "command": "pavo-mcp-server", "env": { "AGNES_API_KEY": "sk-xxx" } } } }</code></pre> <h3>Web Mode (Complete Experience)</h3> <p>Launch complete front-end + MCP environment.</p> <pre><code>pavo-start</code></pre> <p>Open <b>http://localhost:3000</b> to use.</p> <h3>Environment Variables</h3> <table> <tr><th>Variable</th><th>Description</th><th>Default Value</th></tr> <tr><td><code>AGNES_API_KEY</code></td><td>AI Service API Key (Required)</td><td>—</td></tr> <tr><td><code>AGNES_API_BASE_URL</code></td><td>API Service Address</td><td><code>https://apihub.agnes-ai.com/v1</code></td></tr> <tr><td><code>LOG_LEVEL</code></td><td>Log Level</td><td><code>INFO</code></td></tr> </table> <p>Copy <code>.env.example</code> to <code>.env</code> and set <code>AGNES_API_KEY</code> to use.</p> <h2>📡 MCP Tool List</h2> <table> <tr><th>Tool</th><th>Description</th></tr> <tr><td><code>pavo_tool_create_project</code></td><td>Create project and launch Agent pipeline</td></tr> <tr><td><code>pavo_tool_get_project</code></td><td>Get complete project data</td></tr> <tr><td><code>pavo_tool_list_projects</code></td><td>Get project list</td></tr> <tr><td><code>pavo_tool_generate_storyboard</code></td><td>Re-generate storyboard/character/scene</td></tr> <tr><td><code>pavo_tool_save_memory</code></td><td>Save user preferences to long-term memory</td></tr> <tr><td><code>pavo_tool_search_memory</code></td><td>Retrieve historical memories</td></tr> <tr><td><code>pavo_tool_list_memories</code></td><td>List all memories</td></tr> <tr><td><code>pavo_tool_delete_memory</code></td><td>Delete specified memory</td></tr> <tr><td><code>pavo_tool_render_video</code></td><td>Trigger video rendering</td></tr> <tr><td><code>pavo_tool_export_project</code></td><td>Export project</td></tr> <tr><td><code>pavo_tool_auth_login</code></td><td>Get authentication token</td></tr> </table> <h2>📖 Documentation</h2> <table> <tr><th>Document</th><th>Description</th><th>Language</th></tr> <tr><td><a href="docs/user-guide-en.md">📘 User Guide</a></td><td>Product usage workflow, interface guide, features</td><td>English</td></tr> <tr><td><a href="docs/technical-documentation-en.md">📙 Technical Docs</a></td><td>Architecture, code walkthrough, API reference</td><td>English</td></tr> </table> <h2>🧠 Agent Pipeline</h2> <pre> User Story ──► Planner ──► Character ──► Scene ──► Prop ──► Storyboard ──► Reviewer ──► Fixer ──► Done! ↑ ↑ Memory Injection RAG Knowledge Injection</pre> <p>7 Agents collaborate to complete the transformation from story to storyboard, executed in series.</p> <table> <tr><th>#</th><th>Agent</th><th>Input</th><th>Output</th></tr> <tr><td>1</td><td><b>Planner</b></td><td>User Story</td><td>Character, Scene, Theme, Emotion, Duration Analysis</td></tr> <tr><td>2</td><td><b>Character</b></td><td>Story Text</td><td>Character Setting (Name, Age, Appearance, Personality, Voice, Consistency Key)</td></tr> <tr><td>3</td><td><b>Scene</b></td><td>Story + Character</td><td>Scene Setting (Environment, Lighting, Atmosphere)</td></tr> <tr><td>4</td><td><b>Prop</b></td><td>Story + Character + Scene</td><td>Prop List (Appearance, Interaction, Significance)</td></tr> <tr><td>5</td><td><b>Storyboard</b></td><td>Story + Character + Scene + Prop</td><td>Shot-by-shot Storyboard (Scene, Camera Movement, Angle, Dialogue, BGM)</td></tr> <tr><td>6</td><td><b>Reviewer</b></td><td>Complete Project</td><td>Quality Review Report (Whether Needs Fixing)</td></tr> <tr><td>7</td><td><b>Fixer</b></td><td>Review Report</td><td>Fixed Storyboard</td></tr> </table> <p>v2.3 adds Memory + RAG Injection Layer: Memory injects user historical preferences at the <b>Planner</b> stage, and RAG injects film and television professional knowledge at the <b>Storyboard</b> stage, making storyboards more user-understanding and professional.</p> <h2>♻️ Zero Dependency Architecture</h2> <table> <tr><th>Component</th><th>Old Solution</th><th>New Solution</th><th>Savings</th></tr> <tr><td>Database</td><td>PostgreSQL + pgvector (Docker)</td><td>SQLite + sqlite-vec</td><td>~500MB</td></tr> <tr><td>Cache</td><td>Redis (Docker)</td><td>TTLCache (Memory)</td><td>~150MB</td></tr> <tr><td>Task Queue</td><td>Celery + Redis (Docker)</td><td>asyncio.Queue</td><td>~350MB</td></tr> <tr><td>File Storage</td><td>MinIO (Docker)</td><td>Local File System</td><td>~500MB</td></tr> <tr><td><b>Total</b></td><td><b>4 Docker Containers</b></td><td><b>Zero External Dependencies</b></td><td><b>~1.5GB</b></td></tr> </table> <h2>🛤️ Version Roadmap</h2> <table> <tr><th>Version</th><th>Core Features</th><th>Status</th></tr> <tr><td><b>v1.0</b></td><td>7 Agent Pipeline + Front-end Interface + Basic Export</td><td>✅ Completed</td></tr> <tr><td><b>v2.0</b></td><td>MCP Server Standardized Interface</td><td>✅ Completed</td></tr> <tr><td><b>v2.3</b></td><td>Memory + RAG + MCP Extension + Workflow Visualization + Zero Dependency</td><td>✅ Released ⬅</td></tr> <tr><td><b>v3.0</b></td><td>Complete Video Agent (Prompt Optimization + Multi-version Management)</td><td>📅 Planned</td></tr> </table> <hr> <p align="center"> Built with ❤️ by <a href="https://github.com/yanzhao77">yanzhao77</a> · <a href="https://github.com/yanzhao77/pavo-ai-agent">GitHub</a> · <a href="README_EN.md">English README</a> </p>