valenti/vocero-client
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: rename API and frontend projects to Vocero

Browse Source 
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.
This commit is contained in:
alvaro
2026-10-06 19:26:55 -03:00
parent e0304b2bdb
commit abd03ed07d
105 changed files with 353 additions and 312 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+52 -52
View File
@@ -3,12 +3,13 @@
## Scope and working conventions
This repository is Vocero: a browser voice client, its FastAPI integration
server, and a speech pipeline. Use the code, commands,
configuration, and documentation within this checkout. Do not assume other
repositories or developer-specific directories are available.
server, and a speech pipeline. Keep this guide self-contained and base its
instructions on this checkout's code, configuration, documentation, and tools.
All file and directory references in this guide are relative to the repository
root. HTTP routes mentioned below are URLs, not filesystem paths.
All file and directory references in this guide must point within the repository
and be relative to its root. Commands may use the project's command-line tools,
such as `rg`, `git`, `uv`, `npm`, Docker, and PM2. HTTP routes mentioned below are
URLs, not filesystem paths.
- Check the current branch, worktree, and working-tree changes before editing.
Honor the checkout requested by the user, including direct work on `main`.
@@ -23,35 +24,34 @@ root. HTTP routes mentioned below are URLs, not filesystem paths.
assuming a tool is missing. Do not install system-wide packages unnecessarily.
- When commits are requested, make coherent, scoped Conventional Commits as work
progresses. Avoid excessive micro-commits and unrelated cleanup.
- Invoke `work-on-feature` only when explicitly requested. For a requested PR,
follow the available `pr-description` skill exactly and put verification
details in the handoff when its format excludes them. Issues are optional;
create native Gitea issues or post comments only when requested.
- For a requested pull request, describe the problem, resulting behavior,
validation, and relevant limitations. Create issues or post comments only
when requested.
- When asked to merge locally, use the requested rebase/fast-forward flow;
preserve a recovery ref before rewriting and verify retained patches. A local
merge does not imply a push, deployment, or restart. Report those separately.
- Treat old conversations and proposals as context. Verify claims against the
current code and distinguish proposed authentication/deployment changes from
implemented behavior.
- Treat historical proposals in `docs/proposals/` as context. Verify their
claims against current code and distinguish proposed authentication or
deployment changes from implemented behavior.
## Project map
| Location | Responsibility |
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
| `s2s-client/` | The complete uv project: manifests, environment, Python tooling, tests, and FastAPI package |
| `s2s-client/s2s_client/main.py` | Application assembly, documentation mount, and retained redirects |
| `s2s-client/s2s_client/api/` | HTTP routes, route registration, and response validation helper |
| `s2s-client/s2s_client/models/` | Pydantic request and response contracts |
| `s2s-client/s2s_client/core/` | Environment parsing, logging, public URLs, and startup diagnostics |
| `s2s-client/s2s_client/providers/` | ApiPilot and caller/profile/report HTTP integrations |
| `s2s-client/s2s_client/services/` | Prompt/context construction, reasoning, and tool-context rendering |
| `s2s-client/s2s_client/realtime/` | WebSocket relay, event handling, marker filtering, and audio forwarding |
| `s2s-frontend/` | React, TypeScript, Tailwind, and Vite browser application |
| `vocero-api/` | The complete uv project: manifests, environment, Python tooling, tests, and FastAPI package |
| `vocero-api/vocero_api/main.py` | Application assembly, documentation mount, and retained redirects |
| `vocero-api/vocero_api/api/` | HTTP routes, route registration, and response validation helper |
| `vocero-api/vocero_api/models/` | Pydantic request and response contracts |
| `vocero-api/vocero_api/core/` | Environment parsing, logging, public URLs, and startup diagnostics |
| `vocero-api/vocero_api/providers/` | ApiPilot and caller/profile/report HTTP integrations |
| `vocero-api/vocero_api/services/` | Prompt/context construction, reasoning, and tool-context rendering |
| `vocero-api/vocero_api/realtime/` | WebSocket relay, event handling, marker filtering, and audio forwarding |
| `vocero-frontend/` | React, TypeScript, Tailwind, and Vite browser application |
| `speech_to_speech/` | Separately run VAD → STT → LLM → TTS pipeline and realtime API |
| `start_ui.sh` | Dependency sync and supervision of FastAPI plus Vite |
| `docs/` | Maintained technical documentation, examples, and historical proposals |
`s2s-client/server.py` is a compatibility shim for `server:app`; new backend
`vocero-api/server.py` is a compatibility shim for `server:app`; new backend
implementation belongs in the package. Keep HTTP handlers focused on transport
and reuse providers/services for shared behavior.
@@ -62,37 +62,37 @@ Load-balancer allocation/queues and upstream caller authentication remain.
## Tooling and checks
The uv project must stay inside `s2s-client/`, including
`s2s-client/pyproject.toml`, `s2s-client/uv.lock`, `s2s-client/.python-version`,
`s2s-client/.venv/`, `s2s-client/Makefile`, and
`s2s-client/.pre-commit-config.yaml`.
The uv project must stay inside `vocero-api/`, including
`vocero-api/pyproject.toml`, `vocero-api/uv.lock`, `vocero-api/.python-version`,
`vocero-api/.venv/`, `vocero-api/Makefile`, and
`vocero-api/.pre-commit-config.yaml`.
Use Python 3.12 and the uv version required by `tool.uv.required-version`
(currently 0.12.5). Update dependencies through uv and commit the lockfile;
do not use pip to modify this environment or move it to the repository root.
Keep uv pins in `s2s-client/Dockerfile` and setup documentation aligned when
Keep uv pins in `vocero-api/Dockerfile` and setup documentation aligned when
changing the required version.
The frontend uses npm and `s2s-frontend/package-lock.json`. Its Node requirement is
`^22.18.0 || >=24.0.0`; consult `s2s-frontend/package.json` for current scripts.
The frontend uses npm and `vocero-frontend/package-lock.json`. Its Node requirement is
`^22.18.0 || >=24.0.0`; consult `vocero-frontend/package.json` for current scripts.
Keep application code and supported configuration files in TypeScript.
Commands below run from the repository root:
| Command | Purpose |
| ------------------------------------- | --------------------------------------------------------------------- |
| `make -C s2s-client install` | Sync the locked Python environment and development tools |
| `make -C s2s-client format` | Apply Ruff fixes and formatting |
| `make -C s2s-client check` | Check lock freshness, formatting, Ruff lint, mypy, and pytest |
| `make -C s2s-client test-launcher` | Test readiness, failures, dependency sync, and process-group shutdown |
| `make -C s2s-client test-image` | Build and smoke-test the actual backend Docker image |
| `npm --prefix s2s-frontend ci` | Install locked frontend dependencies |
| `npm --prefix s2s-frontend run check` | Check formatting, lint, TypeScript, Vitest, and launcher integration |
| `npm --prefix s2s-frontend run build` | Type-check and build frontend assets |
| `make -C vocero-api install` | Sync the locked Python environment and development tools |
| `make -C vocero-api format` | Apply Ruff fixes and formatting |
| `make -C vocero-api check` | Check lock freshness, formatting, Ruff lint, mypy, and pytest |
| `make -C vocero-api test-launcher` | Test readiness, failures, dependency sync, and process-group shutdown |
| `make -C vocero-api test-image` | Build and smoke-test the actual backend Docker image |
| `npm --prefix vocero-frontend ci` | Install locked frontend dependencies |
| `npm --prefix vocero-frontend run check` | Check formatting, lint, TypeScript, Vitest, and launcher integration |
| `npm --prefix vocero-frontend run build` | Type-check and build frontend assets |
Python uses Ruff with a 120-character line limit, double quotes, import ordering,
and typed application functions checked by mypy. Frontend formatting and lint
rules live in `s2s-frontend/prettier.config.ts` and
`s2s-frontend/eslint.config.ts`; use those tools rather than introducing
rules live in `vocero-frontend/prettier.config.ts` and
`vocero-frontend/eslint.config.ts`; use those tools rather than introducing
competing conventions.
Run checks appropriate to the change: backend checks for Python/API work,
@@ -126,7 +126,7 @@ evidence; do not bundle them into tooling or structural refactors.
- Response models validate fields constructed by this service. Upstream-owned
values remain permissive where the old parser was permissive: `Any`, optional
fields, open objects, and arbitrary profile JSON are deliberate boundaries.
- `validated_json_response` in `s2s-client/s2s_client/api/responses.py` validates
- `validated_json_response` in `vocero-api/vocero_api/api/responses.py` validates
with Pydantic, then serializes the original payload. Do not substitute
`model_dump()` or automatic response-model serialization: those can insert
defaults, filter unknown keys,
@@ -135,8 +135,8 @@ evidence; do not bundle them into tooling or structural refactors.
- Preserve environment/dotenv parsing, default flags, and import-time behavior
during refactors. Do not introduce stricter configuration validation or change
authentication behavior as part of a tooling change.
- `s2s-client/tests/fixtures/legacy-contracts.json` captures the server before the
migration at `3d42df5`. `s2s-client/tests/test_compatibility.py` compares HTTP
- `vocero-api/tests/fixtures/legacy-contracts.json` captures the server before the
migration at `3d42df5`. `vocero-api/tests/test_compatibility.py` compares HTTP
response bytes, statuses, selected headers, outgoing requests, request schemas,
and realtime frames. Do not regenerate captures merely to make a refactor pass.
- Known reasoning failures, ApiPilot authentication/cache quirks, and relay
@@ -148,9 +148,9 @@ evidence; do not bundle them into tooling or structural refactors.
## Browser and realtime behavior
- React renders the UI; `s2s-frontend/src/realtime/controller.ts` owns observable
application state, `s2s-frontend/src/realtime/client.ts` owns protocol/session
lifecycle, and `s2s-frontend/src/audio/` owns the audio graph and worklets.
- React renders the UI; `vocero-frontend/src/realtime/controller.ts` owns observable
application state, `vocero-frontend/src/realtime/client.ts` owns protocol/session
lifecycle, and `vocero-frontend/src/audio/` owns the audio graph and worklets.
Keep high-frequency audio/WebSocket work outside React rendering and preserve
cleanup across unmounts and reconnects.
- Preserve the existing 16 kHz PCM16 audio path, worklet registration, interruption
@@ -164,11 +164,11 @@ evidence; do not bundle them into tooling or structural refactors.
server/provider calls; do not assume a vector database or a completed magic-link
authentication flow exists.
- Assistant Markdown is parsed with Marked and sanitized with DOMPurify in
`s2s-frontend/src/lib/messages.ts`. User text stays literal, and exports retain
`vocero-frontend/src/lib/messages.ts`. User text stays literal, and exports retain
raw message text. Keep sanitization and unsafe-link regression coverage when
changing it.
- Reuse the existing design tokens, Tailwind integration, and
`s2s-frontend/src/styles/legacy-theme.css`. Verify both light and dark themes,
`vocero-frontend/src/styles/legacy-theme.css`. Verify both light and dark themes,
narrow screens, keyboard focus, dialog dismissal, and voice-state feedback for
UI changes.
Preserve intentional `?debug=true` controls and browser audio-permission flows.
@@ -178,8 +178,8 @@ evidence; do not bundle them into tooling or structural refactors.
## Startup and deployment boundaries
`./start_ui.sh` sources `.env`, syncs `s2s-client/.venv/` with
`uv sync --project s2s-client --locked`, and installs frontend packages when the
`./start_ui.sh` loads the optional root `.env`, syncs `vocero-api/.venv/` with
`uv sync --project vocero-api --locked`, and installs frontend packages when the
manifests change.
It starts Vite on `0.0.0.0:8420` and FastAPI on `127.0.0.1:8421`, with
`UI_HOST`, `UI_PORT`, and `S2S_BACKEND_PORT` overrides. Use distinct ports for
@@ -207,7 +207,7 @@ the local relay. Either disables load-balancer mode. Reasoning supports `PROXY`
and `OPENAI`; unknown `S2S_REASONING_TYPE` values fall back to `PROXY`.
The backend Docker image serves APIs, WebSockets, and root `docs/`, not the React
UI. Build with the repository root as context and `s2s-client/Dockerfile`; the
UI. Build with the repository root as context and `vocero-api/Dockerfile`; the
image listens on 7860. FastAPI's root remains 404, `/docs` is the API explorer,
and project documentation is served below `/docs/` with retained legacy redirects.
@@ -223,10 +223,10 @@ and project documentation is served below `/docs/` with retained legacy redirect
without language suffixes. Historical proposals do not define current behavior.
- Reserve root Markdown for established files such as `README.md` and `AGENTS.md`.
Keep task summaries in the conversation unless a saved artifact is requested.
Record notable changes under `Unreleased` in `s2s-client/CHANGELOG.md`.
Record notable changes under `Unreleased` in `vocero-api/CHANGELOG.md`.
- Keep credentials and deployment values out of commits and examples. Never copy
the root `.env` into the frontend or expose backend secrets through `VITE_*`.
The launcher sources `.env` before startup, so it can override shell values;
The launcher loads `.env` when present, so its values can override shell values;
direct Python startup uses `load_dotenv(..., override=False)`. Preserve both
behaviors and avoid importing live configuration when a test can isolate it.