Python Server Role
Last reviewed: 2026-07-05
Purpose
The Anuva Python Server is the local orchestration worker that runs beside the Unity Video Creator. It bridges the Anuva Web App/CMS worker API and Unity rendering runtime by claiming render jobs, preparing local job workspaces, coordinating ZeroMQ messages, validating rendered MP4 output, uploading results, and exposing local operator tools.
Status: Partial. The repository implements worker configuration, local workspace preparation, Web App client abstractions, simulator flows, dashboard/manual claim flows, Unity ZeroMQ protocol handling, Unity EXE process control, output validation, upload strategies, and tests. The long-running production worker loop is still a skeleton command.
Owned By This Repository
| Area | Status | Evidence |
|---|---|---|
| Worker configuration and secret-free YAML loading | Implemented | src/anuva_python_server/config/settings.py |
| Web App worker API client and models | Implemented | src/anuva_python_server/webapp/client.py, src/anuva_python_server/webapp/models.py |
| Job workspace, asset download, config rewriting, manifest writing | Implemented | src/anuva_python_server/jobs/ |
| Manual job claiming and single-active-job guardrails | Implemented | src/anuva_python_server/jobs/runner.py, tests/unit/test_manual_claim.py |
| ZeroMQ command/event protocol and client | Implemented | src/anuva_python_server/unity/protocol.py, src/anuva_python_server/unity/zmq_client.py |
| Unity EXE process and supervisor assumptions | Partial | src/anuva_python_server/unity/process.py, src/anuva_python_server/unity/supervisor.py |
| Local content server for Unity/Vuplex assets | Implemented | src/anuva_python_server/servers/content.py |
| Dashboard and simulator operator flows | Partial | src/anuva_python_server/servers/dashboard.py, src/anuva_python_server/simulator/ |
| Output validation, thumbnail artifact, upload completion | Implemented | src/anuva_python_server/jobs/output.py, src/anuva_python_server/webapp/uploads.py |
Not Owned Here
The Python Server does not own presentation creation, Payload CMS internals, Unity scene/camera/rendering semantics, AI generation, TTS, timeline decisions, user-facing Web App product workflows, or cross-repository Anuva engineering policy.
When a change needs a Web App endpoint, Unity renderer behavior, or shared process decision that is not already documented locally, keep the Python-side boundary abstract and record a follow-up rather than encoding the contract here.
Relationship To Web App And Unity
| System | Relationship |
|---|---|
| Anuva Web App/CMS | Source of truth for render jobs, job state, packages, signed upload targets, and final media records. The Python Server talks to it through webapp/ client boundaries. |
| Unity Video Creator | Rendering runtime. The Python Server starts or waits for Unity, sends render.start, listens for status/completion/failure events, and validates the output Unity writes. |
| Local operator | Uses dashboard and CLI commands for smoke tests, manual claiming, Unity launch/restart/stop, diagnostics, and simulator workflows. |
Runtime Orientation
Current behavior is both local-dev oriented and production-worker oriented, but unevenly:
| Mode | Status | Notes |
|---|---|---|
| Local simulator plus dashboard | Implemented | FastAPI simulator, dashboard routes, launcher scripts, and tests exist. |
| Local Web App plus Unity Editor | Partial | Documented and supported by launchers; depends on external Web App and Unity Editor behavior. |
| Local Web App plus Unity EXE | Partial | Process launch and dashboard controls exist; real Unity render behavior is external. |
| Cloud or Windows service worker | Planned/Partial | NSSM command generation and operations docs exist. Session 0 caveats are documented. |
| Continuous production polling loop | Stubbed | anuva-worker run initializes config/workspace and points users to poll-once; it does not run an infinite orchestrator loop. |
Source Files To Inspect
AGENTS.mddocs/Anuva_Python_Server_Requirements.mddocs/AnuvaPythonServer_SystemDescription.mddocs/Operations.mddocs/User_Guide.mdsrc/anuva_python_server/cli.pysrc/anuva_python_server/jobs/runner.pysrc/anuva_python_server/unity/src/anuva_python_server/webapp/
Related state maps: CurrentImplementationMap, KnownGaps.