Skip to content

Bootstrap Context

Last generated: 2026-07-06

This page gives Codex and maintainers a product-aware starting point for work in anuva-python-server. It summarizes repository boundaries, integration points, verification expectations, docs parity rules, and product-main handoff expectations for Anuva Video Creator.

For implementation details, prefer the repository docs listed here over this summary. When sources conflict, follow this order:

  1. docs/Anuva_Python_Server_Requirements.md
  2. Explicit user instructions in the current task
  3. Existing code and tests in this repository
  4. AGENTS.md
  5. This bootstrap context

Product Role

anuva-python-server is the Python implementation repository for render orchestration in Anuva Video Creator. It runs as a local or VM-side worker next to the Unity renderer. Its product role is to execute already-planned render jobs deterministically, keep Unity and the Web App coordinated, preserve useful diagnostics, and report progress/completion/failure back to the Web App.

In the end-to-end product flow:

  1. anuvax-cms gathers user intent, knowledge, media, and AI planning output.
  2. anuvax-cms creates render jobs and compiled PresentationConfig payloads.
  3. anuva-python-server claims jobs, prepares local workspaces, serves local content, supervises Unity, validates output, uploads MP4 artifacts, and reports status.
  4. anuva-unity-video-creator renders the final video from the config and assets.
  5. anuvax-cms presents the completed video to the user.

Repository Boundary

This repository owns:

  • Python worker configuration, CLI entry points, and local workspace layout.
  • Web App worker API client boundaries and typed worker-facing models.
  • Render job discovery, atomic claim delegation, single-active-job V1 guardrails, manual claim support, job preparation, and local job manifests.
  • Asset downloading, checksum handling, local URL rewriting, and local HTTPS content serving for Unity/Vuplex assets.
  • Unity EXE process launch/stop/readiness assumptions and Unity Editor Play Mode connection support on the Python side.
  • ZeroMQ command/event protocol handling between Python and Unity.
  • Render progress forwarding, cancellation handling, output validation, thumbnail artifact generation, uploads, completion, failure reports, and retry-safety diagnostics.
  • Local dashboard, local Web App simulator, operator scripts, health snapshots, system/GPU metrics, log redaction, and Windows/NSSM operational helpers.
  • Repository-local docs, tests, and completion reports for Python server work.

This repository does not own:

  • User-facing Web App behavior, Payload CMS internals, billing, RAG, AI planning, PresentationConfig compilation, or final media records.
  • Unity scene setup, cameras, bot presenter behavior, virtual screen rendering, capture implementation, or presentation semantics.
  • Product-level roadmap, feature acceptance criteria, repository registry, capability ownership, GitHub Project coordination, or release review.
  • Shared Anuva engineering process, templates, or publishing mechanics.

Keep unresolved Web App and Unity contracts behind explicit webapp/ and unity/ boundaries. If a task requires a new cross-repository contract that is not already documented locally, record the follow-up instead of hardcoding an assumption here.

Owned Capabilities

The product capability map identifies anuva-python-server as a primary owner for automated rendering and a supporting repository for PresentationConfig execution and render queue management.

Repository-owned capabilities include:

  • Automated render orchestration from queued/claimed job to uploaded MP4.
  • Worker-side render queue participation, including polling/listing, claiming, status updates, heartbeats, completion, failure, and cancellation.
  • Deterministic job workspace creation under the configured worker root.
  • Preservation of original and renderer-local PresentationConfig JSON files.
  • Asset localization and local content serving for Unity.
  • Unity lifecycle supervision and ZeroMQ protocol mediation.
  • Output validation, upload strategy selection, completion reporting, and operational diagnostics.
  • Local simulation and QA surfaces for worker behavior before or without the real Web App.

Supported But Not Owned Capabilities

This repository supports these product capabilities without owning their primary implementation:

  • PresentationConfig compilation: consume, preserve, and localize compiled config; do not generate or reinterpret creative semantics.
  • Virtual Screens: serve local assets and HTML content needed by Unity/Vuplex; do not own Unity display behavior.
  • Bot Presenter and camera delivery: pass through config and Unity events; do not choose scripts, timings, gestures, or shots.
  • Brand Sets and media assets: download and serve referenced assets; do not own brand management or asset authoring.
  • Render queue management: participate as a worker; the Web App remains the source of truth for durable job state.
  • Product task coordination: report implementation status back through issues, PRs, project fields, and product-main progress docs; do not treat chat as the durable execution record.

Integration Points

Upstream

anuvax-cms is upstream for:

  • Worker API routes under the real /api/worker/v1 namespace.
  • Render job summaries, packages, statuses, claim semantics, and cancellation state.
  • Compiled PresentationConfig data and asset metadata.
  • Worker bearer token configuration through ANUVA_WORKER_API_TOKEN by default.
  • Signed upload targets, upload confirmation, direct upload fallback, and final media record ownership.

The local simulator can stand in for the Web App in development and QA. It must remain aligned with worker-facing route behavior where implemented, while gaps are tracked in docs rather than hidden in code.

Downstream

anuva-unity-video-creator is downstream for:

  • Local config paths and local HTTPS content URLs.
  • Unity startup arguments, readiness messages, heartbeat/status events, and ZeroMQ socket topology.
  • render.start, render.cancel, unity.shutdown, and unity.ping commands.
  • unity.ready, unity.heartbeat, render.accepted, render.progress, render.completed, and render.failed events.
  • Final output file conventions, especially final.mp4 or the outputPath reported by Unity.

Python owns the worker side of the protocol. Unity owns the renderer behavior, capture pipeline, scene semantics, and correctness of the generated MP4.

Local Runtime

Local services default to localhost:

  • Dashboard: http://127.0.0.1:7080
  • Content server: https://127.0.0.1:7443
  • Simulator: http://127.0.0.1:7090
  • ZeroMQ command/status/heartbeat: 127.0.0.1:5560/5561/5562

The default worker root is C:\Anuva\Worker, with config at C:\Anuva\Worker\config\worker.yaml and per-job workspaces under C:\Anuva\Worker\jobs\<job-id>.

Current Implementation Orientation

Current docs describe the implementation as partial but substantial:

  • Implemented: typed config loading, safe local workspace creation, Web App client models, simulator state/client/app, job preparation, asset download, config rewriting, manifests, content server, ZeroMQ protocol/client, output validation, upload strategies, health snapshots, redaction, and broad tests.
  • Partial: dashboard/operator workflows, Unity EXE process/supervisor behavior, Unity Editor/EXE real render flows, production Windows service behavior, and continuous worker orchestration.
  • Stubbed: anuva-worker run initializes config/workspace and points users to one-shot/manual commands; it is not a full infinite production polling loop.

When changing implementation, preserve the package boundaries under src/anuva_python_server/: config, webapp, jobs, unity, servers, simulator, monitoring, and utils.

Local Docs Map

Read these docs before making changes:

  • AGENTS.md: repository operating contract and required checks.
  • docs/Anuva_Python_Server_Requirements.md: canonical requirements, milestones, acceptance criteria, and open questions.
  • docs/AnuvaPythonServer_SystemDescription.md: system boundaries, endpoint semantics, data structures, status transitions, and call sequences.
  • docs/AnuvaWeb_API_Doc.md: worker API route catalog and Web App contract expectations.
  • docs/Operations.md: config, secrets, certificates, simulator, dashboard, Unity modes, NSSM, and troubleshooting.
  • docs/User_Guide.md: manual Web App, simulator, Unity Editor, and Unity EXE smoke flows.
  • docs/process/ChangeWorkflow.md: repository-local change process.
  • docs/core/: durable role, architecture, protocol, lifecycle, integration, configuration, recovery, simulation, and verification concepts.
  • docs/state/: current implementation map, module map, commands, environment, test map, known gaps, recent decisions, and docs update checklist.

Use docs/state/DocsUpdateChecklist.md to decide which docs need parity updates for a behavior change.

Verification Expectations

Always run:

git diff --check

Run the lightest relevant checks for the change:

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m pytest tests\unit
.\.venv\Scripts\python.exe -m pytest tests\integration
.\.venv\Scripts\python.exe -m mkdocs build --strict

Use focused unit tests for config validation, worker models, path safety, asset download behavior, manifest/config rewriting, protocol serialization, simulator state, dashboard/manual claim behavior, output validation, uploads, health, and redaction.

Use integration tests for simulator HTTP flows, fake Web App/client behavior, fake Unity ZeroMQ flows, dashboard manual claim paths, lifecycle completion, and upload/completion flows.

Real end-to-end verification may require external prerequisites not available in a local Codex run:

  • Real or local Web App worker API and worker token.
  • Unity Editor Play Mode or built Unity EXE.
  • Local HTTPS certificate for content serving.
  • FFmpeg/ffprobe when strict media validation or thumbnail generation matters.
  • S3 or compatible storage for real signed upload verification.
  • Windows interactive session and NSSM for service validation.

If any prerequisite is unavailable, state exactly what was not verified.

GitHub Issue And PR Expectations

GitHub issues are the durable handoff packet for implementation work. For non-trivial tasks, issue bodies should include:

  • Product Feature ID and product source folder when the task comes from anuva-main-video-creator.
  • Target repository: anuva-python-server.
  • Repository-owned scope and explicit non-goals.
  • Dependencies on Web App, Unity, product-main, handbook, or docs publisher.
  • Acceptance criteria and local verification expectations.
  • Docs impact and product-main sync requirements.

Implementation PRs should include a completion report with:

  • Product Feature ID and product change folder, if applicable.
  • Linked GitHub issue.
  • Implementation summary.
  • Docs updated.
  • Verification run and verification skipped.
  • Integration notes for anuva-main-video-creator.
  • Open questions and follow-ups.

When a Python server task affects product behavior, repository responsibility, cross-repository contracts, or release readiness, report that back through the issue, PR, GitHub Project fields, and product-main progress docs. Codex chat is not the source of truth for cross-repository execution state.

Docs Publishing Impact

This repository owns its local source docs. anuva-dev-docs owns aggregated docs publishing output.

When local docs change:

  • Keep mkdocs.yml navigation aligned with new pages.
  • Run or request mkdocs build --strict in this repository.
  • Record whether anuva-dev-docs needs a refresh.
  • Do not edit generated publisher output from this repository unless the user explicitly opens that repository and asks for publishing work.

When product-main docs, GitHub Project status, or implementation docs change as part of one product feature, keep product-main GitHubTasks.md, Progress.md, implementation issues, PR reports, project fields, and docs publishing notes in sync.

Open Questions For Maintainers

Known open or externally validated areas include:

  • Which real Web App worker endpoints and payload shapes are final versus still evolving, especially where local docs mirror Web App repository paths.
  • Whether the simulator should implement signed upload create/confirm endpoints in addition to direct upload fallback.
  • How the full continuous production polling loop should be scheduled, supervised, and recovered.
  • How automatic retry queues/backoff should work beyond current retry-safety classification.
  • What final diagnostics bundle shape should be uploaded or linked from failed jobs.
  • Which Unity startup arguments, readiness payload fields, and render event payload fields are now stable across Unity Editor and EXE modes.
  • What the validated Windows service model is for Unity graphics in an interactive user session, including NSSM recovery behavior.
  • Whether multiple workers on one VM are still future scope or need earlier contract changes.
  • Which FFmpeg/ffprobe installation and bundling assumptions are production requirements versus operator setup steps.

Mark any unresolved contract explicitly in the relevant local docs and, if it crosses repository boundaries, route it back through product-main planning or a GitHub issue for the owning repository.