refactor: rename API and frontend projects to Vocero
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:
+21
-21
@@ -1,7 +1,7 @@
|
||||
# Client architecture
|
||||
|
||||
The [React browser client](../../s2s-frontend) uses the
|
||||
[FastAPI backend](../../s2s-client) for HTTP APIs and a speech WebSocket relay.
|
||||
The [React browser client](../../vocero-frontend) uses the
|
||||
[FastAPI backend](../../vocero-api) for HTTP APIs and a speech WebSocket relay.
|
||||
`start_ui.sh` serves Vite on the existing public port `8420` and FastAPI on
|
||||
loopback port `8421`. Vite forwards backend routes and provides hot reload;
|
||||
Uvicorn reloads Python edits. The launcher supervises both processes.
|
||||
@@ -42,22 +42,22 @@ audio. It is not an unconditional byte-for-byte tunnel.
|
||||
|
||||
| Source | Responsibility |
|
||||
|---|---|
|
||||
| [server.py](../../s2s-client/server.py) | Compatibility entry point for existing `server:app` commands |
|
||||
| [main.py](../../s2s-client/s2s_client/main.py) | FastAPI assembly, documentation serving and redirects |
|
||||
| [api](../../s2s-client/s2s_client/api) | HTTP route registration, handlers and compatible response validation |
|
||||
| [models](../../s2s-client/s2s_client/models) | Pydantic request and response contracts |
|
||||
| [core](../../s2s-client/s2s_client/core) | Existing environment parsing, logging, URL helpers and diagnostics |
|
||||
| [providers](../../s2s-client/s2s_client/providers) | Caller context and ApiPilot HTTP integrations |
|
||||
| [services](../../s2s-client/s2s_client/services) | Context construction, reasoning and tool-context rendering |
|
||||
| [realtime](../../s2s-client/s2s_client/realtime) | WebSocket relay, events, markers and audio handling |
|
||||
| [server.py](../../vocero-api/server.py) | Compatibility entry point for existing `server:app` commands |
|
||||
| [main.py](../../vocero-api/vocero_api/main.py) | FastAPI assembly, documentation serving and redirects |
|
||||
| [api](../../vocero-api/vocero_api/api) | HTTP route registration, handlers and compatible response validation |
|
||||
| [models](../../vocero-api/vocero_api/models) | Pydantic request and response contracts |
|
||||
| [core](../../vocero-api/vocero_api/core) | Existing environment parsing, logging, URL helpers and diagnostics |
|
||||
| [providers](../../vocero-api/vocero_api/providers) | Caller context and ApiPilot HTTP integrations |
|
||||
| [services](../../vocero-api/vocero_api/services) | Context construction, reasoning and tool-context rendering |
|
||||
| [realtime](../../vocero-api/vocero_api/realtime) | WebSocket relay, events, markers and audio handling |
|
||||
| [start_ui.sh](../../start_ui.sh) | Dependency setup, ports, readiness, reload processes, and shutdown |
|
||||
| [vite.config.ts](../../s2s-frontend/vite.config.ts) | Public development endpoint, HMR, allowed hosts, and backend routing |
|
||||
| [App.tsx](../../s2s-frontend/src/App.tsx) | React layout, voice controls, dialogs, profile and reports sidebar |
|
||||
| [controller.ts](../../s2s-frontend/src/realtime/controller.ts) | Application state, settings, context, queue, tools and external reasoning |
|
||||
| [client.ts](../../s2s-frontend/src/realtime/client.ts) | Realtime protocol, session lifecycle, audio and transcript events |
|
||||
| [components](../../s2s-frontend/src/components) | Chat, caller profile, settings and voice components |
|
||||
| [audio](../../s2s-frontend/src/audio) | TypeScript capture/playback worklets, PCM codec, and visualizer |
|
||||
| [legacy-theme.css](../../s2s-frontend/src/styles/legacy-theme.css) | Retained themes and responsive visual styles alongside Tailwind |
|
||||
| [vite.config.ts](../../vocero-frontend/vite.config.ts) | Public development endpoint, HMR, allowed hosts, and backend routing |
|
||||
| [App.tsx](../../vocero-frontend/src/App.tsx) | React layout, voice controls, dialogs, profile and reports sidebar |
|
||||
| [controller.ts](../../vocero-frontend/src/realtime/controller.ts) | Application state, settings, context, queue, tools and external reasoning |
|
||||
| [client.ts](../../vocero-frontend/src/realtime/client.ts) | Realtime protocol, session lifecycle, audio and transcript events |
|
||||
| [components](../../vocero-frontend/src/components) | Chat, caller profile, settings and voice components |
|
||||
| [audio](../../vocero-frontend/src/audio) | TypeScript capture/playback worklets, PCM codec, and visualizer |
|
||||
| [legacy-theme.css](../../vocero-frontend/src/styles/legacy-theme.css) | Retained themes and responsive visual styles alongside Tailwind |
|
||||
|
||||
## Server routes
|
||||
|
||||
@@ -79,9 +79,9 @@ explorer, while project documentation files are served in the `/docs/`
|
||||
subdirectories. Markdown remains
|
||||
source text, and directories without `index.html` are not browsable pages.
|
||||
FastAPI serves backend and documentation routes only. The frontend source and
|
||||
assets live in `s2s-frontend` and are served by Vite.
|
||||
assets live in `vocero-frontend` and are served by Vite.
|
||||
|
||||
The uv project and its Python tools are scoped to `s2s-client/`. Response models
|
||||
The uv project and its Python tools are scoped to `vocero-api/`. Response models
|
||||
describe service-owned structure and retain loose upstream values. See
|
||||
[development and compatibility](development.md) before tightening a contract.
|
||||
|
||||
@@ -89,11 +89,11 @@ describe service-owned structure and retain loose upstream values. See
|
||||
|
||||
1. The browser captures microphone audio with echo cancellation, noise
|
||||
suppression and automatic gain-control settings.
|
||||
2. [mic-capture.worklet.ts](../../s2s-frontend/src/audio/mic-capture.worklet.ts) resamples to 16 kHz
|
||||
2. [mic-capture.worklet.ts](../../vocero-frontend/src/audio/mic-capture.worklet.ts) resamples to 16 kHz
|
||||
mono PCM16. The browser sends base64 `input_audio_buffer.append` frames.
|
||||
3. The backend processes VAD → STT → LLM → TTS and emits realtime events.
|
||||
4. Assistant PCM16 audio at the current 16 kHz protocol rate is decoded and sent to
|
||||
[audio-playback.worklet.ts](../../s2s-frontend/src/audio/audio-playback.worklet.ts), which buffers,
|
||||
[audio-playback.worklet.ts](../../vocero-frontend/src/audio/audio-playback.worklet.ts), which buffers,
|
||||
resamples and fades playback edges. Input speech can clear playback for barge-in.
|
||||
|
||||
Audio worklets are loaded through `AudioWorklet.addModule`; keep their processor
|
||||
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
Context reaches the assistant through browser-built instructions, server-patched
|
||||
realtime session instructions, and HTTP reasoning context. The implementation is
|
||||
in the server's [context services](../../s2s-client/s2s_client/services/context.py),
|
||||
[realtime proxy](../../s2s-client/s2s_client/realtime/proxy.py),
|
||||
[context.ts](../../s2s-frontend/src/lib/context.ts), and the
|
||||
[WebSocket client](../../s2s-frontend/src/realtime/client.ts).
|
||||
in the server's [context services](../../vocero-api/vocero_api/services/context.py),
|
||||
[realtime proxy](../../vocero-api/vocero_api/realtime/proxy.py),
|
||||
[context.ts](../../vocero-frontend/src/lib/context.ts), and the
|
||||
[WebSocket client](../../vocero-frontend/src/realtime/client.ts).
|
||||
|
||||
## Independent controls
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Design language
|
||||
|
||||
This guide describes the current browser UI. Use
|
||||
[legacy-theme.css](../../s2s-frontend/src/styles/legacy-theme.css) as the token/selector
|
||||
reference and [App.tsx](../../s2s-frontend/src/App.tsx) for the theme-specific structure.
|
||||
[legacy-theme.css](../../vocero-frontend/src/styles/legacy-theme.css) as the token/selector
|
||||
reference and [App.tsx](../../vocero-frontend/src/App.tsx) for the theme-specific structure.
|
||||
Earlier documentation described a monochrome-only dark UI; the current design
|
||||
also uses aurora gradients, glass surfaces, and a separate light theme.
|
||||
|
||||
|
||||
+19
-12
@@ -1,11 +1,18 @@
|
||||
# Backend development and compatibility
|
||||
|
||||
The FastAPI project lives entirely in `s2s-client/`. It uses uv 0.12.5, Python
|
||||
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
|
||||
@@ -17,24 +24,24 @@ the deprecated alias. Runtime dependencies and warning handling are unchanged.
|
||||
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
|
||||
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 `s2s-client/` when intentionally changing dependencies.
|
||||
Run `uv lock` inside `vocero-api/` 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,
|
||||
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 s2s-client hooks-install`; the configuration stays
|
||||
in `s2s-client/.pre-commit-config.yaml`. `make -C s2s-client hooks-run` runs the
|
||||
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 `s2s_client.main:app`
|
||||
and the retained `server:app` shim; use `--app-dir s2s-client` from the root.
|
||||
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
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ The mode is normalized case-insensitively. Unknown values resolve to `PROXY`.
|
||||
|
||||
## Shared instruction assembly
|
||||
|
||||
In [context.ts](../../s2s-frontend/src/lib/context.ts), `buildInstructions()` starts
|
||||
In [context.ts](../../vocero-frontend/src/lib/context.ts), `buildInstructions()` starts
|
||||
with `config.primaryPrompt || settings.instructions`. `/api/config` pins
|
||||
`S2S_PRIMARY_PROMPT` when non-empty; otherwise the settings prompt or
|
||||
`DEFAULT_INSTRUCTIONS` is used. The current server does not fetch a remote agent
|
||||
@@ -50,7 +50,7 @@ OPENAI_REASONING_MODEL=gpt-4.1-mini
|
||||
`OPENAI_ORGANIZATION` and `OPENAI_PROJECT` are optional headers. The model value
|
||||
is a runtime default, not a recommendation about provider availability.
|
||||
|
||||
`VoiceController.reason()` in [controller.ts](../../s2s-frontend/src/realtime/controller.ts)
|
||||
`VoiceController.reason()` in [controller.ts](../../vocero-frontend/src/realtime/controller.ts)
|
||||
runs after a complete user transcript and posts a body with `transcript`,
|
||||
`instructions`, `language`, `user_context`, `phoneNumber`, and `episode_id`.
|
||||
The server combines instructions and context into model messages, requests a
|
||||
@@ -76,7 +76,7 @@ realtime backend instead.
|
||||
| Goal | Source |
|
||||
|---|---|
|
||||
| Change the base agent prompt | `S2S_PRIMARY_PROMPT` or browser settings when unpinned |
|
||||
| Change browser context assembly | `buildInstructions()` in `s2s-frontend/src/lib/context.ts` |
|
||||
| Change HTTP provider messages | `reasoning()` in `s2s-client/s2s_client/services/reasoning.py` |
|
||||
| Change browser context assembly | `buildInstructions()` in `vocero-frontend/src/lib/context.ts` |
|
||||
| Change HTTP provider messages | `reasoning()` in `vocero-api/vocero_api/services/reasoning.py` |
|
||||
| Change external-answer rendering | `VoiceController.reason()` and `RealtimeClient.renderExternalAnswer()` |
|
||||
| Change native model/tool generation | `speech_to_speech/LLM` and realtime handlers |
|
||||
|
||||
@@ -48,8 +48,8 @@ For a native call, the backend emits:
|
||||
```
|
||||
|
||||
`arguments` is a JSON-encoded string. The
|
||||
[WebSocket client](../../s2s-frontend/src/realtime/client.ts) validates the event and
|
||||
dispatches `tool`; [controller.ts](../../s2s-frontend/src/realtime/controller.ts)
|
||||
[WebSocket client](../../vocero-frontend/src/realtime/client.ts) validates the event and
|
||||
dispatches `tool`; [controller.ts](../../vocero-frontend/src/realtime/controller.ts)
|
||||
parses the arguments and runs the supported executor.
|
||||
Web search uses `POST /api/search`, keeping the deployment's Serper key on the
|
||||
server. Tool output returns to the model as:
|
||||
|
||||
@@ -37,7 +37,7 @@ the separate `/v1/realtime` WebSocket on the same public origin.
|
||||
|
||||
For a startup dependency error, check uv 0.12.5 and Node/npm on the process
|
||||
manager's PATH, plus `setsid`/`curl`. uv manages Python 3.12 in
|
||||
`s2s-client/.venv` and checks the committed lock on every start. Frontend
|
||||
`vocero-api/.venv` and checks the committed lock on every start. Frontend
|
||||
dependencies are reused until their manifests change. Changes to root
|
||||
`.env` or launcher settings require a restart.
|
||||
|
||||
@@ -123,9 +123,9 @@ without evidence.
|
||||
From the repository root, run the frontend checks and local backend fixtures:
|
||||
|
||||
```bash
|
||||
npm --prefix s2s-frontend run check
|
||||
npm --prefix s2s-frontend run build
|
||||
make -C s2s-client check
|
||||
npm --prefix vocero-frontend run check
|
||||
npm --prefix vocero-frontend run build
|
||||
make -C vocero-api check
|
||||
```
|
||||
|
||||
These checks cover frontend contracts and local session/queue/WebSocket
|
||||
|
||||
+11
-11
@@ -12,8 +12,8 @@ From the repository root:
|
||||
S2S_PROXY_TARGET=ws://localhost:8765/v1/realtime ./start_ui.sh
|
||||
```
|
||||
|
||||
The launcher loads the root `.env`, syncs `s2s-client/.venv` from the committed
|
||||
`s2s-client/uv.lock`, and installs the locked
|
||||
The launcher loads the root `.env`, syncs `vocero-api/.venv` from the committed
|
||||
`vocero-api/uv.lock`, and installs the locked
|
||||
frontend dependencies when needed. Vite serves the React frontend on port
|
||||
8420 and proxies the backend routes to Uvicorn on `127.0.0.1:8421`.
|
||||
`UI_PORT` overrides the public port; `S2S_BACKEND_PORT` overrides the internal
|
||||
@@ -24,21 +24,21 @@ the script, values in that file can replace variables supplied on the command li
|
||||
Use Node.js 22.18+ on the 22.x line or Node.js 24+, npm, uv 0.12.5,
|
||||
Bash 4.4+, `setsid`, and `curl`. Remote staging access also needs the exact
|
||||
hostname in `S2S_DEV_ALLOWED_HOSTS`, HTTPS, and WebSocket forwarding for speech
|
||||
and Vite HMR. See [frontend development setup](../../s2s-frontend/README.md).
|
||||
and Vite HMR. See [frontend development setup](../../vocero-frontend/README.md).
|
||||
|
||||
To install and start the backend manually:
|
||||
|
||||
```bash
|
||||
uv sync --project s2s-client --locked
|
||||
uv sync --project vocero-api --locked
|
||||
S2S_PROXY_TARGET=ws://localhost:8765/v1/realtime \
|
||||
uv run --project s2s-client --locked uvicorn --app-dir s2s-client s2s_client.main:app \
|
||||
--host 127.0.0.1 --port 8421 --reload --reload-dir s2s-client
|
||||
uv run --project vocero-api --locked uvicorn --app-dir vocero-api vocero_api.main:app \
|
||||
--host 127.0.0.1 --port 8421 --reload --reload-dir vocero-api
|
||||
```
|
||||
|
||||
Then, in a second terminal, run `cd s2s-frontend`, `npm ci`, and `npm run dev`.
|
||||
Then, in a second terminal, run `cd vocero-frontend`, `npm ci`, and `npm run dev`.
|
||||
|
||||
uv provisions Python 3.12 when needed. The Python environment belongs only to
|
||||
`s2s-client`; an existing root `.venv` for speech dependencies is left alone.
|
||||
`vocero-api`; an existing root `.venv` for speech dependencies is left alone.
|
||||
See [development and compatibility](development.md) for checks and schema rules.
|
||||
|
||||
Open <http://localhost:8420/>, tap the orb/microphone control, grant microphone
|
||||
@@ -94,9 +94,9 @@ backend address. The image does not run the development launcher or serve a UI.
|
||||
Use the project root as the build context:
|
||||
|
||||
```bash
|
||||
docker build -f s2s-client/Dockerfile -t s2s-client .
|
||||
docker build -f vocero-api/Dockerfile -t vocero-api .
|
||||
docker run --rm -p 7860:7860 \
|
||||
-e SPEECH_TO_SPEECH_URL=ws://localhost:8765/v1/realtime s2s-client
|
||||
-e SPEECH_TO_SPEECH_URL=ws://localhost:8765/v1/realtime vocero-api
|
||||
```
|
||||
|
||||
For the proxy path, replace the direct setting with a server-reachable
|
||||
@@ -104,7 +104,7 @@ For the proxy path, replace the direct setting with a server-reachable
|
||||
appropriate existing network and use that service's hostname. An upstream
|
||||
bound only to host loopback is not reachable via an arbitrary container name.
|
||||
|
||||
The image includes `s2s-client` and root `docs`. `/docs` is still the FastAPI API
|
||||
The image includes `vocero-api` and root `docs`. `/docs` is still the FastAPI API
|
||||
explorer; documentation lives under `/docs/client/`, `/docs/speech/`,
|
||||
`/docs/adr/`, `/docs/examples/`, and `/docs/proposals/`. Legacy `/project/` and
|
||||
`/public/docs.html` redirect to the historical proposal. Markdown is served as a
|
||||
|
||||
Reference in New Issue
Block a user