alvaro
dfed03ac7c
Vocero now retrieves AquaPortal content through authenticated MCP. This removes the obsolete ApiPilot integration from the API and browser while preserving the separately deployed speech pipeline. Release notes: - Removed ApiPilot endpoints, configuration, credential overrides, and HTTP/realtime tool execution. - Removed browser ApiPilot catalog loading and prompt generation while retaining authenticated MCP discovery. - Updated regression coverage and operating documentation for the retired routes and settings. Reviewed-on: AquaPortal/s2s#3
102 lines
5.7 KiB
Markdown
102 lines
5.7 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 and reasoning
|
|
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. Existing provider parsing,
|
|
authentication precedence, environment parsing, and WebSocket frames are
|
|
preserved outside explicitly retired integrations. Authenticated conversation
|
|
and MCP contracts live in `models/mcp.py` and `models/content.py`.
|
|
|
|
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 66 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. ApiPilot retirement removed another 16 HTTP
|
|
captures, its two OpenAPI operations, and its request model. The four bootstrap
|
|
captures now omit the retired `apipilot` flag. One reasoning failure case was
|
|
renamed because removing ApiPilot eliminated its token access; it still exposes
|
|
the existing uninitialized profile failure. All other retained capture values
|
|
are unchanged.
|
|
|
|
The captures deliberately preserve unknown fields, omitted fields, unusual JSON
|
|
values, queue beacon edge cases, and known failures. Examples include reasoning's
|
|
existing uninitialized profile in certain non-MCP configuration combinations
|
|
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.
|
|
|
|
ApiPilot removal deliberately excludes `speech_to_speech/`. The MCP orchestration
|
|
test still exercises its existing pure marker sanitizer without importing model
|
|
dependencies, verifying that `VOCERO_MCP_CALL` reaches the Vocero relay unchanged.
|