alvaro
abd03ed07d
Rename the project directories, Python distribution and import package, and npm package. Update launcher, Docker, tooling, tests, lockfiles, and documentation while preserving existing API contracts. Make AGENTS.md self-contained and remove external skill and workflow references.
93 lines
5.2 KiB
Markdown
93 lines
5.2 KiB
Markdown
# 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](https://github.com/Kludex/starlette/issues/3497)).
|
|
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:
|
|
|
|
```bash
|
|
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.
|