vocero-client/docs/client/development.md

Backend development and compatibility

The FastAPI project lives entirely in vocero-api/. It uses uv 0.12.5, Python 3.12, and a committed uv.lock. The frontend and speech pipeline keep their own tooling. Runtime dependency versions match the environment used to capture the pre-migration server; framework upgrades require a separate compatibility review.

The Python distribution is named vocero-api, and its import package is vocero_api. The browser package and directory are both named vocero-frontend. start_ui.sh creates the API environment at its current path on the next start; do not move an existing virtual environment because its executables contain absolute paths. Reinstall optional Git hooks after a project-directory rename with make -C vocero-api hooks-install.

Pytest filters only the known anyio.abc.BlockingPortal deprecation emitted by Starlette's test client (upstream issue). The filter matches the exact message, warning category, and module; other warnings remain visible. Remove it when a compatible Starlette upgrade replaces the deprecated alias. Runtime dependencies and warning handling are unchanged.

Commands

From the repository root:

make -C vocero-api install       # uv sync --locked, including development tools
make -C vocero-api format        # Ruff safe fixes and formatting
make -C vocero-api check         # lock freshness, format, lint, mypy, pytest
make -C vocero-api test-launcher # Bash supervisor integration fixtures
make -C vocero-api test-image    # Docker build and isolated runtime smoke test

Run uv lock inside vocero-api/ when intentionally changing dependencies. Do not install server packages into a shared root environment. The launcher syncs vocero-api/.venv and retains root .env loading, port defaults, readiness checks, and process-group shutdown. Offline starts require the locked packages and Python runtime to have been installed or cached already.

Optional hooks use make -C vocero-api hooks-install; the configuration stays in vocero-api/.pre-commit-config.yaml. make -C vocero-api hooks-run runs the same hooks without installing them. Hooks and Python quality checks apply only to the client service. The server entry points are vocero_api.main:app and the retained server:app shim; use --app-dir vocero-api from the root.

Schema boundaries

models/requests.py retains the existing search, reasoning, and ApiPilot request models, including their defaults, coercion, and ignored extra fields. The queue beacon still accepts malformed JSON and non-object bodies as before; its Pydantic view is applied only after the original object check, and queueId remains unconstrained.

models/responses.py validates structure constructed by this server. Fields owned by external services remain Any where the old parser imposed no type constraint. Object models allow extra fields. Caller profiles can be arbitrary JSON; load-balancer fields remain optional; execution results and error details remain open. Existing provider parsing, authentication precedence, argument filtering, environment parsing, and WebSocket frames are unchanged.

HTTP handlers call validated_json_response: Pydantic validates the payload, then JSONResponse serializes the original object. Returning a dumped model would insert defaults or change values/key order, so do not replace this helper with model serialization without a contract review. Route response_model declarations publish the new response schemas in OpenAPI. Existing request schemas and validation errors remain unchanged. HTTP exceptions retain their existing error shapes; there is no new common error envelope.

Compatibility evidence

tests/fixtures/legacy-contracts.json was captured from the original monolithic server at commit 3d42df5, before refactoring. Tests compare 82 HTTP scenarios, including exact response text, statuses, selected headers, and outgoing mock HTTP requests. They also compare request OpenAPI definitions and representative realtime frames. Additional tests cover response validation and permissive upstream values; the original local HTTP/WebSocket tests remain in the suite. Four captures belonging exclusively to the retired workflow reasoning service were removed with that integration; all retained captures are unchanged.

The captures deliberately preserve unknown fields, omitted fields, unusual JSON values, queue beacon edge cases, permissive tool arguments, and known failures. Examples include reasoning's existing uninitialized local variables in certain configuration combinations, API-key-only tool precheck behavior, the catalog cache's existing key, and relay termination after a suppressed invalid session.update error. Fix those in separately reviewed behavior changes; do not regenerate golden captures to make a refactor pass.

These checks use local fixtures and do not claim exhaustive coverage of all provider responses, live speech models, or production configuration. No deployed services or real credentials are needed. The Docker check verifies the actual runtime image, API configuration, documentation, OpenAPI, and the backend's existing root 404; it removes its temporary container and image afterward.