{"id":49574694,"url":"https://github.com/neopen/story-shot-agent","last_synced_at":"2026-05-21T11:04:16.274Z","repository":{"id":320589249,"uuid":"1081756953","full_name":"neopen/story-shot-agent","owner":"neopen","description":"剧本分镜智能体（PenShot）：电影/动漫/短剧/小说/剧本→分镜→片段→prompt | 基于 LangGraph+LLM，自动解析任意格式剧本，生成 Sora/Veo/Runway 等模型可用的连贯text-to-video提示词。保持角色/剧情跨片段一致，支持 MCP/REST API/函数调用 | Python库 + A2A集成。（LLM-powered screenplay-to-video-prompt agent. Break scripts into Sora/Veo-ready shots with character consistency）","archived":false,"fork":false,"pushed_at":"2026-05-14T11:07:48.000Z","size":2693,"stargazers_count":63,"open_issues_count":0,"forks_count":11,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-05-14T13:09:03.721Z","etag":null,"topics":["agent-to-agent","ai-filmmaking","ai-video-generation","character-consistency","function-calling","kling-ai","langgraph-agent","llm-agent","pika-labs","prompt-engineering","rag","screenplay","screenplay-parser","script-to-prompt","sora-prompts","storyboard-script","text-to-video","video-consistency","video-production"],"latest_commit_sha":null,"homepage":"https://shot.helpenx.com/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neopen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T08:41:36.000Z","updated_at":"2026-05-14T11:02:37.000Z","dependencies_parsed_at":"2025-10-24T17:43:29.356Z","dependency_job_id":null,"html_url":"https://github.com/neopen/story-shot-agent","commit_stats":null,"previous_names":["hengline/tool-shot-agent","hengline/video-shot-agent","neopen/video-shot-agent","neopen/story-shot-agent"],"tags_count":12,"template":true,"template_full_name":null,"purl":"pkg:github/neopen/story-shot-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neopen%2Fstory-shot-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neopen%2Fstory-shot-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neopen%2Fstory-shot-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neopen%2Fstory-shot-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neopen","download_url":"https://codeload.github.com/neopen/story-shot-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neopen%2Fstory-shot-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33298278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T02:57:32.698Z","status":"ssl_error","status_checked_at":"2026-05-21T02:57:31.990Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-to-agent","ai-filmmaking","ai-video-generation","character-consistency","function-calling","kling-ai","langgraph-agent","llm-agent","pika-labs","prompt-engineering","rag","screenplay","screenplay-parser","script-to-prompt","sora-prompts","storyboard-script","text-to-video","video-consistency","video-production"],"created_at":"2026-05-03T16:05:57.693Z","updated_at":"2026-05-21T11:04:16.268Z","avatar_url":"https://github.com/neopen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PenShot：Script → Storyboard → AI Video Prompt\n\nA multi-agent collaborative screenplay storyboarding system that splits scripts in various formats into script units optimized for AI text-to-video generation durations. It outputs high-quality storyboard fragment descriptions while ensuring narrative continuity. Built on LangChain and LangGraph, the system leverages LLMs to parse any script format into \"Text-to-Video\" prompt fragments compatible with mainstream AI video models. It supports task pool priority queuing, multi-level memory management, and Chroma vector retrieval.\n\n\u003e **One-Click Conversion**: Any screenplay format → Shot-level descriptions → Sora/Veo/Runway/Kling-ready prompts  \n\u003e **Continuity Guaranteed**: Multi-level memory + vector retrieval ensures character/scene/plot consistency across shots  \n\u003e **Get Started in 5 Minutes**: `pip install penshot` + 3 lines of code\n\n[中文](./README_zh.md) | English | [Documentation](https://pengline.cn/2026/02/7e6cd67dd5ee45248f2276ac145555f5/) | [PyPI](https://pypi.org/project/penshot/)  | [WebSite](https://shot.helpenx.com) |  [RAG Knowledge](https://pengline.cn/2026/04/1e7f1f2a5a184427b4711cc7c1903027/) · [MCP Service](https://pengline.cn/2026/02/b027d930c0b84ba6abd24bbef7d78afc/)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/) [![LangGraph](https://img.shields.io/badge/built_with-LangGraph-purple)](https://langchain-ai.github.io/langgraph/) [![PyPI](https://img.shields.io/pypi/v/penshot.svg)](https://pypi.org/project/penshot/) [![Downloads](https://static.pepy.tech/badge/penshot)](https://pepy.tech/project/penshot) ![GitHub stars](https://img.shields.io/github/stars/neopen/story-shot-agent)\n\n**From Story to Shot** - Transform your scripts into AI-powered storyboards.\n\n\u003e Named \"penshot\" on PyPI - because every story starts with a pen.\n\n\n\n---\n\n## Why PenShot?\n\n| Pain Point                                              | PenShot Solution                                             |\n| ------------------------------------------------------- | ------------------------------------------------------------ |\n| Scripts too long for AI video models                    | Smart chunking + precise duration planning for model-friendly fragments |\n| Character outfit changes / scene jumps break continuity | Multi-level memory + Chroma vector retrieval auto-maintains context |\n| Manual prompt engineering is time-consuming             | Auto-generates bilingual visual descriptions + negative prompts + audio cues |\n| Complex multi-model adaptation                          | One codebase, supports OpenAI/Qwen/DeepSeek/Ollama \u0026 more    |\n\n\n\n\n---\n\n## Core Features\n\n| Feature | Description |\n|---|---|\n| Intelligent Script Parsing | Automatically identifies scenes, dialogue, and action cues; understands narrative structure; supports long-text chunking. |\n| Precise Temporal Planning | Intelligently segments content at the shot level, allocating optimal durations that strictly comply with AI video model constraints. |\n| Continuity Guard | Leverages task pool priority queuing, multi-level memory (short/mid/long-term), and Chroma vector retrieval to ensure high consistency in character states, scenes, and plot across adjacent shots. |\n| High-Quality Prompt Output | Generates detailed bilingual (Chinese/English) visual descriptions, negative prompts, and audio prompts, ready for immediate use. |\n| Multi-Model Compatibility | Supports OpenAI, Qwen, DeepSeek, Ollama, and other major LLM providers with plug-and-play switching. |\n| Multi-Protocol Integration | Provides Python SDK, REST API, LangGraph nodes, A2A collaboration protocol, and standard MCP interfaces. |\n| Robustness \u0026 Traceability | Built-in auto-retry and error fallback mechanisms. Every storyboard fragment is bidirectionally traceable to its original script location. |\n\n\n\n---\n\n## System Architecture \u0026 Workflow\n\n![penshot-Roadmap](./assets/imgs/penshot-Roadmap.webp)\n\n**Architectural UML:**\n\n![penshot](./assets/imgs/penshot.webp)\n\nThis system is a typical Natural Language Processing (NLP) application that achieves end-to-end storyboard transcoding through multi-agent collaboration and memory mechanisms. For detailed architectural design, memory pool implementation, and continuity assurance, please refer to: [Architecture Design \u0026 Implementation](https://pengline.cn/2026/02/7e6cd67dd5ee45248f2276ac145555f5/)\n\n\n\n------\n\n## Quick Start\n\n### 1. Environment Setup\n\n```bash\n# Install via PyPI\npip install penshot\n```\n\n\u003e Note: `penshot` is the PyPI package name, while `story-shot-agent` is the GitHub repository name. Both refer to the same project.\n\n### 2. Configuration\n\n```bash\ncp .env.example .env\n```\n\nEdit the `.env` file to configure the required LLM and Embedding parameters:\n\n```properties\n########################## LLM Configuration #########################\nPENSHOT_LLM__DEFAULT__BASE_URL=https://api.openai.com/v1\nPENSHOT_LLM__DEFAULT__API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nPENSHOT_LLM__DEFAULT__MODEL_NAME=gpt-4o\nPENSHOT_LLM__DEFAULT__TIMEOUT=30\n\n########################## Embedding Model Configuration #########################\nPENSHOT_EMBED__DEFAULT__BASE_URL=https://api.openai.com/v1\nPENSHOT_EMBED__DEFAULT__API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nPENSHOT_EMBED__DEFAULT__MODEL_NAME=text-embedding-v4\n\n########################## Redis Configuration ##########################\nPENSHOT_REDIS_URL=redis://:123456@localhost:6379/0\n```\n\n### 3.Usage Methods\n\n#### 1. Python SDK\n\n```python\nfrom penshot.api import create_penshot_agent\n\nagent = create_penshot_agent(max_concurrent=5)\n\nscript = \"Morning, a girl reading in a cafe, sunlight streaming through the window...\"\ntask_id = agent.breakdown_script_async(\n    script,\n    callback=lambda r: print(f\"Task {r.task_id} completed\")\n)\n\nstatus = agent.get_task_status(task_id)\nresult = await agent.wait_for_result_async(task_id)\n```\n\nFull example: [direct_usage.py](https://github.com/neopen/story-shot-agent/blob/main/example/direct_usage.py)\n\n#### 2. FastAPI Web Application Integration\n\nIntegrate into existing systems via standard HTTP endpoints:\n\n```python\nfrom fastapi import FastAPI, HTTPException\nfrom penshot.api import create_penshot_agent\n\napp = FastAPI(title=\"Penshot API\", version=\"0.1.0\")\nagent = create_penshot_agent(max_concurrent=5)\n\n@app.post(\"/api/generate\")\nasync def generate(script_text: str):\n    task_id = agent.breakdown_script_async(script_text)\n    return {\"task_id\": task_id, \"status\": \"PENDING\"}\n```\n\nFull example: [web_app.py](https://github.com/neopen/story-shot-agent/blob/main/example/web_app.py)\n\n#### 3. LangGraph Node Integration\n\nCan be embedded as an independent node in LangChain/LangGraph workflows for end-to-end automation. Full example: [langgraph_integration.py](https://github.com/neopen/story-shot-agent/blob/main/example/langgraph_integration.py)\n\n#### 4. A2A Protocol Collaboration\n\nSupports context passing and task orchestration with upstream scriptwriting agents and downstream text-to-video/editing agents. Full example: [a2a_integration.py](https://github.com/neopen/story-shot-agent/blob/main/example/a2a_integration.py)\n\n#### 5. MCP (Model Context Protocol) Support\n\nStart the MCP Server:\n\n```bash\npython -m penshot.mcp_server --max-concurrent 5 --queue-size 500\n```\n\nClients can call the `breakdown_script` and `get_task_result` tools to seamlessly integrate with MCP-compatible IDEs or agent frameworks. Full example: [mcp_client.py](https://github.com/neopen/story-shot-agent/blob/main/example/mcp_client.py)\n\n\n\n------\n\n## Output Data Structure\n\nThe system returns standardized JSON containing video prompts, negative prompts, duration estimates, style parameters, and accompanying audio prompts:\n\n```json\n{\n  \"fragments\": [\n    {\n      \"fragment_id\": \"frag_001\",\n      \"prompt\": \"Cinematic wide shot: midnight 11 PM in a compact urban apartment living room...\",\n      \"negative_prompt\": \"cartoon, anime, 3D render, bright lighting, text, watermark...\",\n      \"duration\": 4.2,\n      \"model\": \"runway_gen2\",\n      \"style\": \"cinematic 35mm film, moody realism, shallow depth of field...\",\n      \"audio_prompt\": {\n        \"audio_id\": \"audio_001\",\n        \"prompt\": \"Low-frequency rain ambience (intensity 0.95), distant muffled TV static...\",\n        \"model_type\": \"AudioLDM_3\",\n        \"audio_style\": \"cinematic\"\n      }\n    }\n  ]\n}\n```\n\n\n\n------\n\n## System Notes \u0026 Considerations\n\n| Category              | Description                                                  |\n| --------------------- | ------------------------------------------------------------ |\n| Network Dependency    | Requires stable access to external LLM APIs. Proxy or domestic mirrors are recommended. |\n| Long Text Processing  | For extremely long scripts, segmented input is advised. The system includes built-in context memory and RAG mechanisms. |\n| Generation Duration   | AI video models may output clips with ±10% duration variance, which is industry-standard. |\n| Multilingual Support  | Currently optimized for Chinese scripts. Support for other languages is under active iteration. |\n| Audio Synchronization | Audio prompts are provided. Lip-sync and environmental sound fusion require downstream tooling. |\n| Error Handling        | Auto-retry and fallback mechanisms are built-in. Extreme edge cases may require manual intervention. |\n\n\n\n------\n\n## Development Roadmap\n\n### Short-Term\n\n- Optimize long-shot segmentation logic for action continuity\n- Implement consistency validators for character clothing, positioning, and props\n- Specialized prompt format adaptation for Sora, Pika, and other models\n- Hybrid architecture combining rule-based engines and LLMs\n- Full English script support and intelligent node failure fallback\n- Fragment confidence scoring and debug mode (intermediate result persistence)\n\n### Mid-Term\n\n- Advanced camera language support (pan, tilt, zoom, tracking, follow)\n- Emotion-driven automatic visual style adjustment\n- Ultra-long script chunking + vector DB context memory\n- Multi-script batch queue processing \u0026 Web visualization interface\n- Character/scene reference image integration \u0026 multi-format export (XML/EDL/JSON)\n\n### Long-Term\n\n- Multimodal input (image + audio + text hybrid)\n- Real-time low-resolution preview \u0026 automatic continuity repair\n- Professional editing software plugins (Premiere/FCP/DaVinci)\n- Multi-user collaboration, version control, \u0026 autonomous learning from feedback\n- Bidirectional script-fragment traceability, semantic alignment detection, \u0026 multi-round correction mechanisms\n\n### Ultimate Goal\n\nAchieve zero-information-loss visualization for scripts of any length, language, or genre, delivering a standardized workflow that meets professional director-level storyboarding standards. The system will feature customizable styles, full traceability, automatic optimization loops, and cross-modal high consistency.\n\n\n\n------\n\n## Contributing\n\nWe welcome contributions via Issues or Pull Requests:\n\n- **Bug Reports:** Please provide reproduction steps, environment details, and error logs.\n- **Feature Requests:** Use the `enhancement` label.\n- **Code Optimization:** Performance tuning, architectural refactoring, or adding test cases.\n- **Documentation:** Translations, example additions, or technical corrections.\n\nQuick dev environment setup:\n\n```bash\ngit clone https://github.com/neopen/story-shot-agent.git\ncd story-shot-agent\npip install -e \".[dev]\"\npytest tests/\n```\n\n\n\n------\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](https://chat.qwen.ai/c/LICENSE) file for details. Copyright (c) 2025 HiPeng\n\n\n\n------\n\n## Contact\n\n- Project Homepage: https://github.com/neopen/story-shot-agent\n- Documentation: https://pengline.cn/2026/02/7e6cd67dd5ee45248f2276ac145555f5/\n\nSpecial thanks to LangChain, LangGraph, Chroma, Ollama, and the open-source community for their technical support. If this project has been helpful to your work, please consider starring the repository and sharing your feedback.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneopen%2Fstory-shot-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneopen%2Fstory-shot-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneopen%2Fstory-shot-agent/lists"}