pinecall 0.1.0__tar.gz

pinecall-0.1.0/.claude/skills/add-a-vendor/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: add-a-vendor
+description: Add an LLM, STT or TTS vendor the way this tree does it — a catalog row, a key, and the four places that are still by hand. Use when adding a provider, a model row, a price, or a provider key.
+---
+
+# Adding a vendor
+
+**Almost always, there is nothing to add.** `providers/catalog.py` already holds every vendor
+livekit-agents ships a plugin for, `providers/plugin.py` builds any of them out of the plugin's own
+constructor signature, and `_vendor_keys.py` holds a field for each. Check first:
+
+```bash
+uv run pinecall-runtime providers --does tts | grep -i <the vendor>
+```
+
+- **`ready`** — it runs today. Nothing to do.
+- **`install`** — the row is right and the plugin is not on this box: add its extra to
+  `[project.optional-dependencies] providers` in `pyproject.toml`, `uv lock`, deploy. Use
+  `providers-big` when it drags a cloud SDK (boto3, azure-cognitiveservices-speech,
+  google-cloud-*, onnxruntime) — that is a decision a box makes, never a default.
+- **`no key`** — `printf '%s' <the key> | make secret NAME=<ITS_VARIABLE>` from the checkout, then
+  `make restart`. The variable is in the `providers` table's own column.
+- **not listed at all** — livekit added a plugin since. One row, below.
+
+## A row in the catalog
+
+`providers/catalog.py`, alphabetical, positional in the order the fields are declared:
+
+```python
+(Provider("acme", ("stt", "tts"), "ACME_API_KEY", ("acmeai",), "what a person is choosing"),)
+```
+
+- `does` is what the plugin's own `__all__` exports — `tests/providers/test_catalog.py` checks the
+  row against the plugin and fails if they disagree.
+- `env` is the variable **the plugin itself reads**, spelled the vendor's way. `None` when the
+  vendor has no single-string credential (AWS's chain, Google's service account, RTZR's pair):
+  BYOK then does not apply to it and nothing anywhere asks for one.
+- An alias must **never** also be a model name of that vendor. A bare word that names a vendor IS
+  the vendor at the pipeline door, so `sonic`, `octave`, `sonar`, `mist`, `nova` and `aura` are
+  deliberately not aliases — every one of them is something a person could type meaning the model.
+
+Then **one field in `_vendor_keys.py`**, named the variable lowercased. That rule is the whole of
+the key wiring: `catalog.settings_field_of` reads it, the doctor reads it, the vault accepts the
+vendor, `.env.example` and the box's units list it. `tests/providers/test_provider_keys.py` fails
+while a row has no field.
+
+## A tuned file — only when this build has an OPINION
+
+A file under `providers/llm/`, `stt/` or `tts/` exists to **override a plugin default**: a model a
+phone line should not wait for, an endpointing number, a model this build forbids. Five of them do.
+If there is nothing to override, do not write one — the generic path is not a fallback, it is the
+normal case, and a file that only forwards `model=` and `api_key=` is one more thing to go stale.
+
+```python
+"""Acme: one line saying what the plugin is, and the one default this repo overrides."""
+
+from livekit.plugins import acme
+
+from pinecall.providers.llm import VENDORS
+from pinecall.providers.registry import Asked, Chat, a_key
+
+DEFAULT_MODEL = "acme-fast"  # the plugin's own is acme-large (acme/llm.py:67)
+
+
+@VENDORS.registers("acme")
+def build(asked: Asked) -> Chat:
+    return acme.LLM(model=asked.model or DEFAULT_MODEL, api_key=a_key("acme", asked))
+```
+
+## The four places that are still by hand
+
+1. `providers/knocks.py` — the vendor's cheapest authenticated GET, so `doctor` knocks and
+   `make deploy` refuses a dead key by name. **Only a URL you have opened with a live key and
+   watched answer 200.** A guessed one 404s a perfectly good key and refuses a box that was fine;
+   a vendor with no row is simply not knocked, which is honest.
+2. `providers/prices.py` — a row only where you read the vendor's own page, with `AS_OF` beside
+   it. Everything else is priced by `published_prices.json`
+   (`scripts/refresh-prices`, mahimailabs/voice-prices), and the hand-read table wins where the
+   two disagree — Soniox is the row that says why.
+3. `infra/box/*.service` and `WORKER_CREDENTIALS` in the `Makefile` — one `ImportCredential=` line
+   each and one name, when the vendor has an env.
+4. `tests/conftest.py` — a dead sentinel, if a suite needs to construct that vendor.
+
+Then `scripts/generate-env-example` (a test fails while it drifts), and `CHANGELOG.md`.
+
+## What the tests will refuse
+
+- A vendor SDK import anywhere but `providers/` (`tests/test_isolation.py`, `VENDOR_SDKS`).
+- A catalog row that disagrees with its plugin's `__all__` (`tests/providers/test_catalog.py`).
+- A catalogued vendor with no settings field (`tests/providers/test_provider_keys.py`).
+- A second definition of a default model, a header name, a URL: `grep` first
+  (`tests/test_one_definition_per_thing.py`).
+- Two files in one directory one letter apart (`openai.py` next to `openia.py`).
+- A public name added to `pinecall.providers` without editing `tests/test_the_public_surface.py`.
+
+## Verify
+
+```bash
+scripts/format && scripts/lint && uv run pytest -m unit -q        # three times: it is shuffled
+uv run pinecall-runtime providers --does stt                      # the row, and what it wants
+uv run pinecall-runtime doctor                                    # the knock, with a real key in .env
+```
+
+An STT vendor is verified on a spoken call (`debug-a-call`): the transcript entries name the
+vendor in `metrics.stt`. A TTS vendor: `tts_node_ttfb` on `turn.agent`.

pinecall-0.1.0/.claude/skills/debug-a-call/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: debug-a-call
+description: Read a call's log to find what went wrong, and drive a simulated voice or text call at a gateway (local or a box) to reproduce it. Use for "the agent said nothing", a 503 from simulate, a slow turn, a tool that never answered, or proving a worker takes calls.
+---
+
+# Debugging a call
+
+The log is the truth: every event of a call, with a `seq`, in `call_log`. Read it before reading
+any process's stdout.
+
+## Read the log
+
+```bash
+uv run pinecall-runtime sessions list                 # newest first, off Postgres, gateway up or not
+uv run pinecall-runtime sessions show <call>          # entry by entry, every metric under its turn
+uv run pinecall-runtime sessions tail <call>          # as it happens (polls)
+uv run pinecall-runtime sessions recording <call>     # where the audio went (RECORD=1)
+```
+
+What to look for, in order: `call.started` (channel, direction) → `turn.user` / `turn.agent`
+with their metrics (`e2e_latency`, `llm_node_ttft`, `tts_node_ttfb`) → `tool.call` /
+`tool.result` (did the app answer? `timeout_s` on the ToolSpec) → `metrics.*` errors, the
+session's own `error` entries → `call.summary` (usage, cost) → `call.score` (the judges: `panel`
+is who RAN, `judges` who ANSWERED; `not_judged` means the session was built without a Scorer).
+
+A call with `turn.user` and no `turn.agent`: the LLM or TTS — see the worker's journal. A call
+with no `turn.user`: the STT, or the seat (`worker/seat.py`: which participant is the caller).
+
+## Drive a call
+
+From an example in the agents repo, against whichever gateway you name:
+
+```bash
+cd ~/pinecall-v2/agents/examples/clinica-norte
+PINECALL_URL=https://box.pinecall.io node ../../bin/pinecall.js whoami        # which key, from where
+PINECALL_URL=… node ../../bin/pinecall.js simulate --persona apurado --turns 3            # text
+PINECALL_URL=… node ../../bin/pinecall.js simulate --persona apurado --voice --judge      # voice
+node ../../bin/pinecall.js personas list
+```
+
+`--voice` mounts the class in THIS terminal (it serves the call the runtime opens), asks the
+gateway to put a synthetic caller on a real line, and prints each turn with its latencies; with
+`--judge`, `call.score` read back. The key comes from `PINECALL_API_KEY` in the env or
+`~/.pinecall/credentials`; `PINECALL_URL` picks the gateway (otherwise the local dev file).
+
+What a `503` from simulate means:
+- `this box has no speech tool` — the GATEWAY's box lacks `espeak-ng` (macOS: `say`). It is in
+  `PACKAGES`; `make deploy` installs it.
+- `no agent joined room … in 20s: is pinecall-runtime worker up?` — no worker took the job:
+  none registered on the SFU, or the one that did crashed on the job (its journal has a traceback:
+  `NoProvider: <vendor> has no API key in this process` is a missing or empty credential).
+
+## Which worker took it
+
+```bash
+ssh <hub> 'sudo podman logs --since 10m pinecall-livekit 2>&1 | grep -E "worker registered|job"'
+ssh <worker> "sudo journalctl -u pinecall-worker --since '$START' -o cat" \
+  | grep -iE "received job|pipeline is live|error|exception" \
+  | sed -E 's/(key|secret|token)[=:] *[^ ]+/\1=***/Ig'
+```
+
+`received job request` names `job_id`, `dispatch_id`, `room`; `the pipeline is live N s after
+the job arrived` is the number to watch (0.5 s on the box). To prove a call lands on ONE worker,
+stop the others first (`sudo systemctl stop pinecall-worker` on the hub), never guess from load.
+
+## Local
+
+`uv run pinecall-runtime doctor` first. `unset PINECALL_API_KEY` before `pinecall run` against a
+dev-key gateway (it is ignored out loud; a bare 403 is that). Native Postgres on the laptop:
+`DATABASE_URL=…@[::1]:5432/…`. A `.env` the runtime ignored is never silent: the doctor's first
+line says which file it read.
+
+## Never
+
+Print a key or a token from a journal, a `.env`, or `~/.pinecall/credentials` (the `sed` above
+on every journal read). Run `simulate` against production with a persona that books: `consent`
+is judged, but the tool still runs in the app you mounted.

pinecall-0.1.0/.claude/skills/deploy/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: deploy
+description: Deploy this checkout to a box (hub, worker, or one machine) and verify it, without a secret ever reaching a screen. Use for make deploy, a second box, rotating a vendor key, or when the doctor refuses a key.
+---
+
+# Deploying a box
+
+The deploy is the root `Makefile`: rsync + ssh + make + curl, from a checkout, to the account
+cloud-init made. Nothing on the box can clone; nothing here uses shipway. The box's identity is
+`deploy.local.mk` beside the Makefile (git-ignored): `BOX`, `DOMAIN`, optional `SSH_KEY`.
+
+## NEVER
+
+- Print a secret: not a credential's value, not a key from the shell, not a line of a journal
+  that carries one. Compare credentials by fingerprint (below). Pipe every journal read through
+  `sed -E 's/(key|secret|token)[=:] *[^ ]+/\1=***/Ig'`.
+- Fix the box by hand and stop there. An `apt install`, a credential rewritten with
+  `systemd-creds`, a unit edited in `/etc`: each is at most a probe. The same fix goes in the
+  tree (`PACKAGES` in `infra/box/Makefile`, `make secret`, a doctor check, the unit file) and the
+  box re-converges through `make deploy` before the turn ends.
+- Restart a container (`pinecall-livekit`, `-sip`, `-postgres`, `-redis`) during a call. The
+  deploy never does; a changed `.container` is restarted between two calls, by a person.
+- Run `shipway deploy` anywhere near this tree. `~/pinecall/v2/shipway.yml` points at the same box.
+- Leave `PINECALL_API_KEY` exported while running the deploy or anything that opens a socket:
+  `unset PINECALL_API_KEY` first.
+
+## The path
+
+```bash
+unset PINECALL_API_KEY
+make deploy                                  # sync → install → restart → doctor
+make deploy BOX=deploy@<ip> DOMAIN=<domain>   # another box, same tree
+```
+
+What each step proves: `sync` — the two directories the box needs; `install` — every file of
+`infra/box/` where systemd reads it, the packages the box is missing, the role's units enabled and
+the others' disabled, `uv sync --frozen` as the service user; `restart` — by role: `all` restarts
+gateway → health through Caddy → worker; `hub` restarts the gateway only (`systemctl restart`
+would START a worker the role disabled); `worker` restarts its one unit; `doctor` — the runtime's
+doctor as the units see the box, every vendor knocked with the key the box holds.
+
+A deploy that ends in `✗ provider keys answer  refused ELEVEN_API_KEY (HTTP 401)` is a dead key,
+not a deploy failure: rotate it (below), `make restart`, `make doctor`.
+
+## Fingerprints, never values
+
+```bash
+ssh <box> "sudo systemd-creds decrypt --name=$N /etc/credstore.encrypted/$N - | sha256sum | cut -c1-12; \
+           sudo systemd-creds decrypt --name=$N /etc/credstore.encrypted/$N - | wc -c"
+```
+
+Two boxes agree when the twelve characters and the byte count agree. `e3b0c44298fc` is the
+sha256 of the EMPTY string: a credential written from an unset shell variable. The shell may call
+a key differently from the runtime (`ELEVENLABS_API_KEY` vs `ELEVEN_API_KEY`); `.env.example`
+is the runtime's list.
+
+## Rotating a vendor key
+
+```bash
+printf '%s' "$ELEVENLABS_API_KEY" | make secret NAME=ELEVEN_API_KEY   # the value on stdin, on no screen
+make restart && make doctor
+make worker-secrets WORKER=deploy@<worker-ip>                          # every worker takes the hub's copy
+```
+
+`box secrets` (the generated ones: LiveKit pair, Postgres, ops, vault) never rotates; `box secret
+<NAME>` replaces in place.
+
+## A second box
+
+The hub keeps the gateway and the media plane (`PINECALL_ROLE=hub` in its `/etc/pinecall/box.env`);
+each worker is `PINECALL_ROLE=worker` with `LIVEKIT_URL=wss://<hub-domain>`,
+`PINECALL_GATEWAY_URL=https://<hub-domain>`, `PINECALL_MAX_JOBS=<measured>` — cloud-init writes
+those lines. Order: `make worker-secrets WORKER=…` · `make deploy BOX=<worker> DOMAIN=<hub>` · the
+hub's SFU log says `worker registered` with a new `AW_` id · one voice call lands there (the
+`debug-a-call` skill) · only then the hub's role flips to `hub` and `make deploy` runs on it.
+
+## Reading the box
+
+```bash
+make status                                   # every unit and container, one line each
+make logs UNIT=worker                         # gateway (default) · worker · caddy
+ssh <box> 'sudo podman logs --since 5m pinecall-livekit 2>&1 | grep -E "worker registered|job"'
+ssh <box> "sudo journalctl -u pinecall-worker --since '$START' -o cat" | sed -E 's/(key|secret|token)[=:] *[^ ]+/\1=***/Ig'
+```
+
+## Gotchas
+
+- A fresh box has `/opt/pinecall/app` and nothing under it; `sync` makes the two directories.
+- The fence lives in `prerouting` (raw priority) because DNAT'd container traffic never hits
+  `input`, and it must accept udp/tcp 53 from `podman*` or containers cannot resolve each other.
+- A credential file is named EXACTLY as the credential, no extension; `ImportCredential=` accepts
+  a trailing glob only (`PINECALL_*`).
+- The units run `/opt/pinecall/venv/bin/pinecall-runtime`, never `uv run`.
+- `livekit` on the hub reads a worker's load every 0.5 s and stops routing at 0.7 of it:
+  `PINECALL_MAX_JOBS` is one under the measured ceiling.

pinecall-0.1.0/.env.example

@@ -0,0 +1,256 @@
+# The only .env ever committed, and it is GENERATED: `scripts/generate-env-example` renders it
+# from the aliases src/pinecall/_settings.py declares, and a test fails when the two drift.
+# Copy it to .env and fill what you have. A real environment variable wins over the file,
+# and a name this runtime does not read is ignored, never an error.
+
+# Anthropic, llm. Every provider key keeps the vendor's own variable name.
+ANTHROPIC_API_KEY=
+
+# OpenAI, llm, stt and tts. The other LLM a call may run on.
+OPENAI_API_KEY=
+
+# Soniox, stt and tts. A call needs one key of each role: llm, stt, tts.
+SONIOX_API_KEY=
+
+# Deepgram, stt and tts. Flux and Nova for the ears, Aura for the voice.
+DEEPGRAM_API_KEY=
+
+# ElevenLabs, stt and tts. The voice this runtime speaks with by default.
+ELEVEN_API_KEY=
+
+# AssemblyAI, stt. Universal-Streaming.
+ASSEMBLYAI_API_KEY=
+
+# Async AI, tts.
+ASYNCAI_API_KEY=
+
+# Azure Speech, stt and tts. Needs AZURE_SPEECH_REGION beside the key.
+AZURE_SPEECH_KEY=
+
+# Baseten, llm, stt and tts. Open models on Baseten's own endpoints.
+BASETEN_API_KEY=
+
+# Bland, tts.
+BLAND_API_KEY=
+
+# Camb.ai, tts.
+CAMB_API_KEY=
+
+# Cartesia, stt and tts. Sonic, and Ink-Whisper for the ears.
+CARTESIA_API_KEY=
+
+# Cerebras, llm.
+CEREBRAS_API_KEY=
+
+# Naver CLOVA, stt. Needs CLOVA_STT_INVOKE_URL beside the secret.
+CLOVA_STT_SECRET_KEY=
+
+# fal, stt. Wizper. Batch, not a live socket.
+FAL_KEY=
+
+# Fireworks AI, stt.
+FIREWORKS_API_KEY=
+
+# Fish Audio, tts.
+FISH_API_KEY=
+
+# Gladia, stt.
+GLADIA_API_KEY=
+
+# Gnani, stt and tts.
+GNANI_API_KEY=
+
+# Google, llm, stt and tts. Gemini on the key; Speech-to-Text and Text-to-Speech want a service account.
+GOOGLE_API_KEY=
+
+# Gradium, stt and tts.
+GRADIUM_API_KEY=
+
+# Groq, llm, stt and tts. Whisper and open models, fast.
+GROQ_API_KEY=
+
+# Hume, tts.
+HUME_API_KEY=
+
+# Inworld, stt and tts.
+INWORLD_API_KEY=
+
+# LMNT, tts.
+LMNT_API_KEY=
+
+# MiniMax, tts.
+MINIMAX_API_KEY=
+
+# Mistral AI, llm, stt and tts.
+MISTRAL_API_KEY=
+
+# Murf, tts.
+MURF_API_KEY=
+
+# Neuphonic, tts.
+NEUPHONIC_API_KEY=
+
+# NVIDIA Riva, stt and tts.
+NVIDIA_API_KEY=
+
+# Palabra, stt and tts.
+PALABRA_API_KEY=
+
+# Perplexity, llm. Sonar, and the embedder: the contextual model and the flat.
+PERPLEXITY_API_KEY=
+
+# Resemble AI, tts.
+RESEMBLE_API_KEY=
+
+# Respeecher, tts.
+RESPEECHER_API_KEY=
+
+# Rime, tts.
+RIME_API_KEY=
+
+# Sarvam AI, llm, stt and tts. The Indian languages, all three jobs on one account.
+SARVAM_API_KEY=
+
+# Simplismart, stt and tts.
+SIMPLISMART_API_KEY=
+
+# slng, stt and tts.
+SLNG_API_KEY=
+
+# Smallest AI, stt and tts.
+SMALLEST_API_KEY=
+
+# Speechify, tts.
+SPEECHIFY_API_KEY=
+
+# Speechmatics, stt and tts.
+SPEECHMATICS_API_KEY=
+
+# Spitch, stt and tts. The African languages.
+SPITCH_API_KEY=
+
+# Upliftai, tts.
+UPLIFTAI_API_KEY=
+
+# Vakyam, tts.
+VAKYAM_API_KEY=
+
+# xAI, stt and tts. Grok speaks and hears here; Grok the LLM is reached through livekit or openai.
+XAI_API_KEY=
+
+# OpenRouter, an embedder: the other way to the flat model, no contextual door.
+OPENROUTER_API_KEY=
+
+# The box's own WhatsApp Cloud API token, used for an org that brought none.
+WHATSAPP_ACCESS_TOKEN=
+
+# LiveKit: the media plane both processes talk to. One port serves ws and http.
+LIVEKIT_URL=ws://127.0.0.1:7880
+
+# The LiveKit API key, as the LiveKit server's own config declares it.
+LIVEKIT_API_KEY=
+
+# Its secret. It also signs the call tokens, so there is no second one.
+LIVEKIT_API_SECRET=
+
+# The LiveKit URL a browser is told to join. Unset, it hears LIVEKIT_URL.
+LIVEKIT_PUBLIC_URL=
+
+# The box's Twilio account, for the numbers it buys for a tenant.
+TWILIO_ACCOUNT_SID=
+
+# An API key SID on that account, revocable on its own; else the account SID.
+TWILIO_API_KEY=
+
+# The API key's secret, or the account's auth token when no key is set.
+TWILIO_API_SECRET=
+
+# The box's public name: where a carrier sends a call. Unset, nothing imports.
+PINECALL_DOMAIN=
+
+# Postgres 17 with pgvector and pg_textsearch: the one stateful service.
+DATABASE_URL=postgresql://pinecall:pinecall@127.0.0.1:5432/pinecall
+
+# TEI, the embedder. 8081, because the gateway serves 8080 on the same host.
+TEI_URL=http://127.0.0.1:8081
+
+# Who embeds: tei · perplexity · openrouter. The other two need their API key.
+EMBED_PROVIDER=tei
+
+# The embedding model. Unset: BAAI/bge-m3 · pplx-embed-context-v1-0.6b · perplexity/pplx-embed-v1-0.6b, by provider.
+EMBED_MODEL=
+
+# Where it is asked. Unset: the provider's own door, and TEI_URL for TEI.
+EMBED_BASE_URL=
+
+# The Meta app's App Secret: every webhook body is HMAC-SHA256-signed with it. Unset, the WhatsApp door is closed.
+PINECALL_WHATSAPP_APP_SECRET=
+
+# The word Meta echoes back when the webhook is subscribed. Choose it; type it in the Meta app.
+PINECALL_WHATSAPP_VERIFY_TOKEN=
+
+# Whether a call's audio is kept at all. 0, false, no and off all mean no.
+RECORD=true
+
+# Where a kept recording lands, absolute or relative to the working directory.
+PINECALL_RECORDINGS=recordings
+
+# The gateway a worker's job asks. Read in the job process, never the parent.
+PINECALL_GATEWAY_URL=http://127.0.0.1:8080
+
+# The agent a job that names none is for.
+PINECALL_AGENT=
+
+# Calls this worker holds at once, measured on its machine. Unset: gate on CPU.
+PINECALL_MAX_JOBS=
+
+# Where the worker's own health server binds, on loopback. Not 8080 or 8081.
+PINECALL_WORKER_HTTP_PORT=8082
+
+# What this worker is called in its heartbeats. Unset: the short hostname.
+PINECALL_WORKER_NAME=
+
+# What the overflow agent says when the fleet is full, before it hangs up.
+PINECALL_OVERFLOW_SAYS=En este momento todas nuestras líneas están ocupadas. Hemos tomado nota de su número y le devolveremos la llamada en cuanto se libere una. Gracias por su paciencia.
+
+# The app socket a job's call claims. Unset, the call takes the newest holder.
+PINECALL_APP=
+
+# What this box runs: all · hub · worker. The doctor asks after what it has.
+PINECALL_ROLE=all
+
+# How short a member's password may be. 0 is no rule.
+PINECALL_MIN_PASSWORD=8
+
+# The key /v1/ops/* is authenticated by. Unset, the operator API is closed.
+PINECALL_OPS_KEY=
+
+# Pinecall's hosted gateway: a plan, billed.
+PINECALL_CLOUD=false
+
+# Whether a stranger may make an org at this gateway. Off unless you say.
+PINECALL_SIGNUP=false
+
+# Packages that plug a policy into the runtime's points, comma separated.
+PINECALL_EXTENSIONS=
+
+# The org key the worker knocks its gateway with, as `keys issue` printed it.
+PINECALL_WORKER_KEY=
+
+# A Fernet key, generated once on the box by `pinecall-runtime box secrets`: a tenant's own provider keys are encrypted under it. Unset, the provider-key doors answer 503.
+PINECALL_VAULT_KEY=
+
+# How much both processes say: DEBUG, INFO, WARNING or ERROR.
+PINECALL_LOG_LEVEL=INFO
+
+# What judging one call may spend on a model, in euros. Zero: no judge asks.
+PINECALL_JUDGE_CEILING_EUR=0.002
+
+# What a spoken turn waits for the recall and search it started while the caller was still talking, in ms. It is silence on the line, so it is small.
+PINECALL_VOICE_LOOKUP_BUDGET_MS=250
+
+# What a written turn waits for recall and search, in ms. A written caller sends a whole message, so the lookup only starts at the end — and nobody hears the wait.
+PINECALL_TEXT_LOOKUP_BUDGET_MS=3000
+
+# What a hang-up waits for memory to be written, in s. Past it the call seals.
+PINECALL_REMEMBER_BUDGET_S=8.0

pinecall-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+# The gate: lint, then both test rings, on every push and every pull request. One job, because the
+# whole check is a few minutes and a matrix would only make a failure harder to read.
+#
+# Two repositories, laid out the way a laptop has them: `pyproject.toml` names
+# `../protocol/python` as an editable path dependency, so the second checkout is what makes the
+# wire resolvable — until pinecall-protocol is published and the line becomes a version range.
+name: ci
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+  # release.yml corre ESTE archivo como su gate, en vez de repetir los pasos: el gate del release
+  # y el de cada push son el mismo, o uno de los dos miente.
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    # Most of these minutes are the Postgres image: pgvector and pg_textsearch are compiled from
+    # source, because the image with both is this repository's own and is built, not published.
+    #
+    # `max_connections=300` on that container: pytest-xdist opens a worker per core and each one
+    # of them a pool, and a runner has more cores than a laptop — the default hundred ran out and
+    # answered `sorry, too many clients already`.
+    timeout-minutes: 30
+
+    env:
+      DATABASE_URL: postgresql://pinecall:pinecall@127.0.0.1:5432/pinecall
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: runtime
+
+      - uses: actions/checkout@v4
+        with:
+          repository: pinecall/protocol
+          path: protocol
+
+      # What a person does with `docker compose -f infra/compose/dev.yml up -d`, in one step.
+      #
+      # The schema needs BOTH extensions — `halfvec` in 0008 and 0009, a `bm25` index in 0009 —
+      # so the stock image cannot run a migration at all: it stops at `type "halfvec" does not
+      # exist`. It is started as a STEP and not as a service, because a `services:` block starts
+      # before any step runs and so cannot wait for a build. The two CREATE EXTENSIONs are here
+      # because no migration creates one — the same two a person types once by hand.
+      - name: postgres with the two extensions the schema needs
+        run: |
+          docker build -q -t pinecall/postgres:ci runtime/infra/compose/postgres
+          docker run -d --name postgres -p 5432:5432 \
+            -e POSTGRES_USER=pinecall -e POSTGRES_PASSWORD=pinecall -e POSTGRES_DB=pinecall \
+            pinecall/postgres:ci -c max_connections=300
+          # NOT pg_isready: postgres's entrypoint runs initdb behind a TEMPORARY server on the
+          # same socket, so `accepting connections` is true a second before POSTGRES_DB exists
+          # and the next line dies with `database "pinecall" does not exist`. Wait for the thing
+          # that actually matters — the database answering a query as the user.
+          for _ in $(seq 1 90); do
+            docker exec postgres psql -U pinecall -d pinecall -c 'select 1' >/dev/null 2>&1 && break
+            sleep 1
+          done
+          docker exec postgres psql -U pinecall -d pinecall \
+            -c "CREATE EXTENSION IF NOT EXISTS vector" \
+            -c "CREATE EXTENSION IF NOT EXISTS pg_textsearch"
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: runtime/uv.lock
+
+      # `--extra runtime` carries livekit-agents and its plugins; `--extra providers` the vendor
+      # SDKs the provider tables construct. The dev group holds the checkers and squawk.
+      - run: uv sync --locked --extra runtime --extra providers --group dev
+        working-directory: runtime
+
+      # ruff, pyright, mypy, then squawk over the migrations that have not landed.
+      - run: scripts/lint
+        working-directory: runtime
+
+      # `public`, migrated, which is what a dev box has and what the app's own pool reads. The
+      # Postgres ring gives itself a schema per worker and migrates that; the API tests do not —
+      # they build the real app, whose lifespan opens a pool the moment DATABASE_URL answers, and
+      # a database that answers with no tables in it is `relation "pipeline_overrides" does not
+      # exist` a hundred and sixty times. On a laptop this is invisible: `public` was migrated
+      # months ago, or nothing answers at all.
+      - run: uv run pinecall-runtime migrate up
+        working-directory: runtime
+
+      # Ring 0 and the Postgres ring: no key, no model, no network. A test that needs a real
+      # ANTHROPIC_API_KEY skips itself by name rather than failing.
+      - run: scripts/test
+        working-directory: runtime