release: CineAgent v4 runtime architecture - #1
Open
Lucien-1127 wants to merge 18 commits into
Open
Conversation
…models + SQLite storage (WAL) with tests (15 passing)
… + Script Engine (planner/hooks/writer/critic/fact_check) + PromptCompiler (vendor gate). 21 tests passing
… MasterTimeline + captions/SRT + ffmpeg utils). 25 tests passing
…ne (text-matched scene timing, negative constraints propagation). 28 tests passing
…Router (reuse->stock->generate priority). 34 tests passing
… idempotent remote jobs) + Model Capability Registry + cost-aware ModelRouter. 42 tests passing
…ssembly) + Remotion primary (planned). 44 tests incl. render smoke
…/audio/aspect/size) + VisualQAProvider/Mock. 49 tests passing
…persist) + Analytics (collector + sample-gated content learning). 55 tests passing
…>Render->MP4) + GitHub Actions CI (tests + git-history secret scan). 56 tests passing
…ost-model / production-modes / README sync. Final DoD: 0 Agnes refs in cineagent/, 56 tests, clean secret scan
…ed, only implemented features claimed; planned items marked planned)
…lows/orcarouter-code-review.yml)
…view authors to trusted org roles toward public-repo API-cost exposure)
…ain history and stay intact in working set; re-added once workflow scope available)
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Owner
Author
|
/orcacode-review |
There was a problem hiding this comment.
🟡 Changes recommended
There are several verified correctness and maintainability issues (timeline scene mapping with duplicate narration, duplicated asset search iteration, overly broad exception handling, a tautological test, and QA duration guard) that should be addressed before approval.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR packages and documents the CineAgent v4 release-candidate runtime architecture: a provider-neutral, shot-based, reference-first, audio-first pipeline with durable state (SQLite+WAL), offline-capable mock providers, rendering, QA, publishing (dry-run), and analytics, plus an expanded test suite to validate the mainline end-to-end.
Changes:
- Introduces the
cineagent/v4 package: canonical Pydantic domain models, provider contracts + mocks, orchestration (audio-first timeline), assets (reuse-first routing), renderer (FFmpeg implemented, Remotion planned), QA, publishing, analytics, and SQLite repositories. - Adds a comprehensive pytest suite (unit + integration + renderer/QA smokes + full offline E2E) and basic packaging metadata (
pyproject.toml). - Refreshes and adds v4 documentation/README/AGENTS and removes the deferred OrcaRouter code review workflow.
File summaries
| File | Description |
|---|---|
| tests/test_timeline.py | Tests audio-first master timeline + captions + timestamp gating. |
| tests/test_storyboard.py | Tests storyboard shot timing driven by audio timeline + VisualBible propagation. |
| tests/test_storage.py | Tests SQLite schema, state recovery, idempotency, ledger aggregations, asset dedup. |
| tests/test_script_engine.py | Tests ScriptEngine + PromptCompiler vendor gate behavior via mock provider. |
| tests/test_render.py | Smoke tests FFmpeg rendering and Remotion planned gate. |
| tests/test_qa.py | Tests TechnicalQA (ffprobe) and mock Visual QA behavior. |
| tests/test_publish_analytics.py | Tests publishing (dry-run/failed) persistence + analytics learning thresholds. |
| tests/test_providers.py | Tests capability registry/router and mock image/video provider idempotency. |
| tests/test_e2e_smoke.py | Offline E2E: topic → script → timeline → shots → assets → render → QA. |
| tests/test_domain_schemas.py | Validates domain model defaults and schema strictness. |
| tests/test_assets.py | Tests asset library dedup/semantic matching and router priority decisions. |
| tests/README.md | Documents offline E2E smoke testing scope. |
| README.md | Rewrites project README for v4 architecture, scope, and statuses. |
| pyproject.toml | Adds packaging metadata and pytest config. |
| docs/video-project-schema.md | Documents canonical domain schemas (v4). |
| docs/state-machine.md | Documents shot/job state machines + recovery/idempotency principles. |
| docs/provider-contract.md | Documents provider abstraction + error taxonomy + structured output contract. |
| docs/production-modes.md | Documents production modes (draft/auto/cinematic) and gating status. |
| docs/migration-plan.md | Documents v4 strangler migration phases and verification. |
| docs/cost-model.md | Documents usage ledger semantics and budget enforcement expectations. |
| docs/audit-v4.md | Adds repository audit report capturing v3 drift and migration rationale. |
| docs/architecture-v4.md | Adds v4 architecture proposal and layering model. |
| cineagent/storage/repositories.py | Implements SQLite repositories + cost ledger aggregations. |
| cineagent/storage/database.py | Adds SQLite wrapper with WAL + schema DDL. |
| cineagent/storage/init.py | Exposes storage primitives via package API. |
| cineagent/renderer/remotion.py | Adds planned Remotion renderer gate. |
| cineagent/renderer/ffmpeg.py | Implements FFmpeg renderer and test media generator. |
| cineagent/renderer/base.py | Defines renderer contract models. |
| cineagent/renderer/init.py | Exposes renderer providers and composition types. |
| cineagent/qa/visual.py | Defines VisualQAProvider interface + deterministic mock. |
| cineagent/qa/technical.py | Implements TechnicalQA checks via ffprobe output. |
| cineagent/qa/init.py | Exposes QA interfaces. |
| cineagent/publish/providers/init.py | Declares publishers with planned API integrations. |
| cineagent/publish/base.py | Implements publishing contract, dry-run default, and persistence hook. |
| cineagent/publish/init.py | Exposes publish API surface. |
| cineagent/providers/video/mock.py | Adds durable/idempotent mock video provider. |
| cineagent/providers/video/base.py | Defines video provider contract + request/result shapes. |
| cineagent/providers/video/init.py | Exposes video provider types. |
| cineagent/providers/text/mock.py | Adds deterministic structured-output mock text provider. |
| cineagent/providers/text/init.py | Adds text provider package marker. |
| cineagent/providers/image/mock.py | Adds mock image provider producing stub images. |
| cineagent/providers/image/base.py | Defines image provider contract + request/result shapes. |
| cineagent/providers/image/init.py | Exposes image provider types. |
| cineagent/providers/capability.py | Adds model capability registry + cost-aware model router. |
| cineagent/providers/base.py | Defines provider error taxonomy + TextProvider contract. |
| cineagent/providers/audio/mock.py | Adds mock TTS provider with word timestamps. |
| cineagent/providers/audio/base.py | Defines AudioProvider contract + TTS request/result types. |
| cineagent/providers/audio/init.py | Exposes audio provider types. |
| cineagent/providers/init.py | Adds providers package marker. |
| cineagent/orchestration/timeline.py | Implements audio-first master timeline builder + scene timing mapping. |
| cineagent/orchestration/init.py | Exposes orchestration timeline API. |
| cineagent/media/ffmpeg.py | Adds ffmpeg/ffprobe utilities (probe + frame extract). |
| cineagent/media/captions.py | Adds caption grouping + SRT building from word timings. |
| cineagent/media/init.py | Exposes media utilities. |
| cineagent/domain/visual.py | Adds VisualBible + VisualCharacter canonical models. |
| cineagent/domain/usage.py | Adds UsageEvent ledger model. |
| cineagent/domain/timeline.py | Adds canonical master timeline + word/caption primitives. |
| cineagent/domain/shot.py | Adds ShotSpec canonical model. |
| cineagent/domain/script.py | Adds CreativeBrief/Scene/ScriptPackage + hook/critique models. |
| cineagent/domain/project.py | Adds VideoProject canonical model. |
| cineagent/domain/job.py | Adds GenerationJob + QAReport canonical models. |
| cineagent/domain/enums.py | Adds canonical enums for platform/strategy/state/assets/jobs. |
| cineagent/domain/asset.py | Adds Asset model for reuse-first routing and embedding metadata. |
| cineagent/domain/init.py | Re-exports domain models/enums for stable imports. |
| cineagent/creative/storyboard.py | Implements StoryboardDirector generating canonical ShotSpecs. |
| cineagent/creative/script_writer.py | Implements ScriptWriter producing ScriptPackage via structured output. |
| cineagent/creative/prompt_compiler.py | Implements provider-neutral prompt payload + vendor gate. |
| cineagent/creative/planner.py | Implements topic → CreativeBrief planning step. |
| cineagent/creative/hook.py | Implements hook generation and best-candidate selection. |
| cineagent/creative/fact_check.py | Adds experimental fact verification pass-through. |
| cineagent/creative/engine.py | Orchestrates the script engine phases and critic loop. |
| cineagent/creative/critic.py | Adds structured critique step and fact-check gating. |
| cineagent/creative/init.py | Exposes creative layer API. |
| cineagent/assets/stock.py | Defines stock provider abstraction (planned adapters). |
| cineagent/assets/router.py | Implements reuse-before-generate routing decision logic. |
| cineagent/assets/library.py | Implements asset library over repo + embedder, dedup + semantic search. |
| cineagent/assets/embeddings.py | Adds experimental deterministic embedder interface + implementation. |
| cineagent/assets/init.py | Exposes assets API surface. |
| cineagent/analytics/learning.py | Implements learning store with min-samples guardrail. |
| cineagent/analytics/collector.py | Implements analytics collector writing into learning store. |
| cineagent/analytics/init.py | Exposes analytics API surface. |
| cineagent/init.py | Adds package version and top-level marker. |
| AGENTS.md | Updates repo-wide v4 operational rules, status vocabulary, and test commands. |
| .github/workflows/orcarouter-code-review.yml | Removes deferred OrcaRouter workflow requiring credentials. |
Review details
Suppressed comments (1)
AGENTS.md:32
- Several bullets have doubled closing parentheses "））" and a likely typo "执". Cleaning these up will keep the v4 docs consistent and easier to read.
- AnalyticsCollector + ContentLearningStore（min_samples gate，analytics/））.
- CI（.github/workflows/ci.yml：tests + secret scan）执 E2E smoke（tests/test_e2e_smoke.py））.
- Files reviewed: 84/84 changed files
- Comments generated: 10
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+34
to
+38
| q = self.embedder.embed(text) | ||
| hits: List[Tuple[Asset, float]] = [] | ||
| for asset in self.repo.assets_for(project_id) + self.repo.assets_for(""): | ||
| if not asset.meta.get("embedding"): | ||
| continue |
Comment on lines
+78
to
+86
| by_text: Dict[str, Tuple[float, float]] = {} | ||
| for seg in timeline.segments: | ||
| if seg.kind == TimelineKind.NARRATION and seg.text: | ||
| by_text.setdefault(seg.text, (seg.start, seg.end)) | ||
| mapping: Dict[str, Tuple[float, float]] = {} | ||
| for scene in scenes: | ||
| if scene.narration and scene.narration in by_text: | ||
| mapping[scene.scene_id] = by_text[scene.narration] | ||
| return mapping |
Comment on lines
+46
to
+50
| from ..media.ffmpeg import probe_video | ||
| try: | ||
| info = probe_video(video_path) | ||
| except Exception as e: # noqa: BLE001 - surfaced as a violation list | ||
| return [f"cannot probe video: {e}"] |
Comment on lines
+39
to
+40
| assert res.status == "dry_run" | ||
| assert "not published" in "dry-run: not published" |
Comment on lines
+27
to
+28
| - FFmpegRenderer（組出可播放 MP4，《renderer/`）; RemotionRenderer=planned。 | ||
| - TechnicalQA（ffprobe）; VisualQAProvider 介面 + Mock（真實模型 planned））. |
| @@ -0,0 +1,58 @@ | |||
| # CineAgent v4 — 遷移計畫 (Migration Plan) | |||
|
|
|||
| - 狀態：`in_progress`（Phase 0–11 已完成，Phase 8 Remotion、真實 vendor、真實發布為 `planned`） | |||
|
|
||
| def test_technical_qa_output_file_exists(): | ||
| path = _render("/tmp/cineagent-qa-smoke/qa_exists.mp4", with_audio=False) | ||
| # renderer muxes a silent audio track, so the file should still decode/avaudio |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
CineAgent v4 release candidate — Provider-neutral, shot-based, reference-first, audio-timeline-driven AI video production system.
Local verification: 56 tests passed, E2E MP4 smoke passed, secrets scan clean, 0 Agnes runtime refs. CI / orca workflow files are deferred in branch (kept intact on main history) pending a workflow-scope credential.