alvaro
e0304b2bdb
BREAKING CHANGE: NODE_RED reasoning is no longer supported. Unsupported mode values fall back to PROXY. PROXY and OPENAI remain available.
86 lines
4.8 KiB
Markdown
86 lines
4.8 KiB
Markdown
# Backend development and compatibility
|
|
|
|
The FastAPI project lives entirely in `s2s-client/`. 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.
|
|
|
|
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 s2s-client install # uv sync --locked, including development tools
|
|
make -C s2s-client format # Ruff safe fixes and formatting
|
|
make -C s2s-client check # lock freshness, format, lint, mypy, pytest
|
|
make -C s2s-client test-launcher # Bash supervisor integration fixtures
|
|
make -C s2s-client test-image # Docker build and isolated runtime smoke test
|
|
```
|
|
|
|
Run `uv lock` inside `s2s-client/` when intentionally changing dependencies.
|
|
Do not install server packages into a shared root environment. The launcher
|
|
syncs `s2s-client/.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 s2s-client hooks-install`; the configuration stays
|
|
in `s2s-client/.pre-commit-config.yaml`. `make -C s2s-client 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 `s2s_client.main:app`
|
|
and the retained `server:app` shim; use `--app-dir s2s-client` 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.
|