toga-ai 1.0.91 → 1.0.92

package/knowledge/2.0/apps/voice-to-voice/INDEX.md

@@ -0,0 +1,8 @@
+# voice-to-voice (TOGa Voice) — 2.0 knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [TOGa Voice (voice-to-voice) Architecture](architecture.md) | **TOGa Voice** (`voice-to-voice`) is a multi-tenant **LiveKit Agents**–based phone voice agent platform. | voice-to-voice/core/base_config.py, voice-to-voice/core/utils.py, voice-to-voice/core/services/egress.py, voice-to-voice/core/services/knowledge_base.py, voice-to-voice/core/services/s3_upload.py, voice-to-voice/core/services/ticket_api.py, voice-to-voice/clients/odp/agent.py, voice-to-voice/clients/odp/agents/tech_support.py, voice-to-voice/clients/odp/config.yaml, voice-to-voice/clients/odp/prompts.py, voice-to-voice/clients/odp/Dockerfile, voice-to-voice/clients/odp/deploy.sh, voice-to-voice/clients/odp/livekit.toml, voice-to-voice/lambda_updated/lambda_function.py, voice-to-voice/docs/CLIENT_ONBOARDING_SOP.md, voice-to-voice/docs/inbound-call-routing-rd.md |
+| [LiveKit Voice Pipeline — STT / LLM / TTS / VAD / Turn Detection](features/livekit-pipeline.md) | The active voice loop is **fully AWS-native**: Amazon Transcribe (STT) → Bedrock Claude (LLM) → Amazon Polly (TTS), with Silero VAD and LiveKit's multilingual t | voice-to-voice/clients/odp/agent.py, voice-to-voice/clients/odp/agents/tech_support.py, voice-to-voice/clients/odp/livekit.toml, voice-to-voice/clients/odp/Dockerfile, voice-to-voice/clients/odp/deploy.sh, voice-to-voice/clients/odp/pyproject.toml, voice-to-voice/core/services/egress.py, voice-to-voice/core/services/knowledge_base.py |
+| [Post-Call Lambda — Transcript Conversion, Report, Ticket Attachment](features/post-call-lambda.md) | After every call, an AWS Lambda picks up the S3 ticket folder the agent left behind, converts the transcript to API format, generates a TXT report of the conver | voice-to-voice/lambda_updated/lambda_function.py, voice-to-voice/lambda_updated/api_client.py, voice-to-voice/lambda_updated/report_generator.py, voice-to-voice/lambda_updated/transcript_converter.py, voice-to-voice/lambda_updated/requirements.txt |
+| [Agilant Ticket API — TOGa Desk 1.0 Integration](features/ticket-api-integration.md) | This is the **single seam** between the new Python voice agent and the legacy **TOGa Desk 1.0** PHP ticketing app. | voice-to-voice/core/services/ticket_api.py, voice-to-voice/lambda_updated/api_client.py, voice-to-voice/lambda_updated/lambda_function.py, voice-to-voice/clients/odp/agent.py, voice-to-voice/clients/odp/config.yaml, voice-to-voice/scripts/test_ticket_api.sh, voice-to-voice/docs/inbound-call-routing-rd.md |

package/knowledge/2.0/apps/voice-to-voice/architecture.md

@@ -0,0 +1,181 @@
+---
+title: TOGa Voice (voice-to-voice) Architecture
+framework: "2.0"
+repo: voice-to-voice
+project: TOGa Voice
+client: shared
+type: architecture
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - voice-to-voice/core/base_config.py
+  - voice-to-voice/core/utils.py
+  - voice-to-voice/core/services/egress.py
+  - voice-to-voice/core/services/knowledge_base.py
+  - voice-to-voice/core/services/s3_upload.py
+  - voice-to-voice/core/services/ticket_api.py
+  - voice-to-voice/clients/odp/agent.py
+  - voice-to-voice/clients/odp/agents/tech_support.py
+  - voice-to-voice/clients/odp/config.yaml
+  - voice-to-voice/clients/odp/prompts.py
+  - voice-to-voice/clients/odp/Dockerfile
+  - voice-to-voice/clients/odp/deploy.sh
+  - voice-to-voice/clients/odp/livekit.toml
+  - voice-to-voice/lambda_updated/lambda_function.py
+  - voice-to-voice/docs/CLIENT_ONBOARDING_SOP.md
+  - voice-to-voice/docs/inbound-call-routing-rd.md
+related:
+  - features/livekit-pipeline.md
+  - features/ticket-api-integration.md
+  - features/post-call-lambda.md
+---
+
+## Summary
+
+**TOGa Voice** (`voice-to-voice`) is a multi-tenant **LiveKit Agents**–based
+phone voice agent platform. A shared `core/` layer provides config, AWS
+service wrappers, and the Agilant Ticket API client; each tenant lives in
+`clients/<slug>/` as its own container deployed to **LiveKit Cloud**. Today
+the only deployed tenant is **Office Depot (ODP)** — a Tier-1 tech-support
+agent for store associates, integrated with TOGa Desk 1.0 via the
+**Agilant Ticket API**. A separate AWS **Lambda** processes post-call
+artifacts (audio + report) and attaches them back to the ticket.
+
+The platform sits under `2.0/apps/` for the same reason as **talos**: it's
+Python (not PHP), but its consumers (callers of Office Depot stores) and
+ticket destination (TOGa Desk 1.0) are 2.0-era TOGa surfaces; tooling and
+conventions match the rest of the Python fleet.
+
+## Top-level layout
+
+```
+voice-to-voice-new/
+├── core/                          # shared platform code
+│   ├── base_config.py             # pydantic-settings: YAML + env precedence
+│   ├── utils.py                   # phone sanitization, SigV4 redaction
+│   └── services/
+│       ├── egress.py              # LiveKit RoomCompositeEgress → S3 .ogg
+│       ├── knowledge_base.py      # Bedrock KB retrieve() + TTL cache
+│       ├── s3_upload.py           # raw .ogg → ticket folder; report JSON upload
+│       └── ticket_api.py          # Agilant Ticket API client (HMAC-SHA256)
+├── clients/
+│   └── odp/                       # Office Depot deployment
+│       ├── agent.py               # LiveKit session entrypoint
+│       ├── agents/tech_support.py # TalosAgent — tools + greeting
+│       ├── config.yaml            # non-secret client settings
+│       ├── prompts.py             # system prompt (call flow + output rules)
+│       ├── Dockerfile             # uv-based multi-stage build
+│       ├── deploy.sh              # copy core/ → build → `lk agent deploy`
+│       └── livekit.toml           # LiveKit Cloud project + agent id
+├── lambda_updated/                # AWS Lambda post-call processor
+│   ├── lambda_function.py         # EventBridge/S3-triggered orchestrator
+│   ├── api_client.py              # PUT /ticket/{n} with HMAC
+│   ├── report_generator.py        # TXT report builder
+│   └── transcript_converter.py    # session_report.json → API transcript fmt
+├── docs/
+│   ├── CLIENT_ONBOARDING_SOP.md   # 14-phase new-tenant runbook
+│   ├── inbound-call-routing-rd.md # phone → LiveKit → agent flow
+│   └── toga-voice-architecture.html
+└── scripts/test_ticket_api.sh
+```
+
+## Multi-tenant model
+
+- **One container per client.** Each `clients/<slug>/` is its own image
+  pushed to LiveKit Cloud as its own agent worker. They share a single AWS
+  account and a single S3 bucket; isolation is by **client-prefixed S3 keys**
+  (`odp/upload/...`) and per-client env (Bedrock KB id, ticket API keys).
+- **`deploy.sh` copies `core/` into the client folder before build.** The
+  Dockerfile builds from the client directory; without the copy step `core/`
+  is missing in the image. Future improvement: install `core/` as a wheel.
+- **Onboarding** (`docs/CLIENT_ONBOARDING_SOP.md`) is a copy-and-customize
+  flow, not a code-generation flow — copy `clients/odp/` to
+  `clients/<new>/`, edit prompts/config/env, deploy.
+
+## Voice pipeline
+
+The active pipeline is **fully AWS-native** (no Deepgram / Cartesia /
+OpenAI):
+
+| Stage | Plugin | Notes |
+|---|---|---|
+| STT | Amazon Transcribe (`en-US`) | Wrapped in `FallbackAdapter` (two instances) to survive Transcribe's 15s idle timeout |
+| LLM | Bedrock Claude — Haiku primary, Sonnet fallback | `FallbackAdapter`, `temp=0.4`, `max_tokens=300` |
+| TTS | Amazon Polly (`Matthew`, engine `generative`) | Preemptive generation for latency |
+| VAD | Silero (downloaded at build) | Loaded in worker prewarm (`agent.py:115`) |
+| Turn detection | LiveKit multilingual model | Endpointing 0.5–0.8s; interruption threshold 1 word |
+
+Pipeline wiring is in `clients/odp/agent.py:162–222`. Plugin versions are
+pinned via `livekit-agents[silero,turn-detector,aws]~=1.4`.
+
+## Deployment
+
+- **Runtime:** LiveKit Cloud agent worker (managed). No self-hosted infra.
+- **Container:** multi-stage Dockerfile, uv-based, Python 3.12, non-root
+  user UID 10001. Silero VAD + turn-detector weights downloaded at build
+  time so cold starts don't fetch.
+- **Entry:** `uv run agent.py start` (LiveKit Agents `WorkerOptions`).
+- **Secrets:** synced via `lk agent update-secrets --secrets-file .env
+  --overwrite` before each deploy. `.env` never enters the image.
+- **Rollback:** `lk agent rollback` and `lk agent logs`.
+
+See `features/livekit-pipeline.md`.
+
+## Integration with TOGa Desk 1.0 (Agilant Ticket API)
+
+**Critical:** the voice agent does **not** call the standard TOGa Desk PHP
+`/desk/api/` endpoint. It calls a separate **Agilant Ticket API** at
+`https://api.agilantsolutions.com` (HMAC-SHA256 auth) which abstracts over
+the underlying TOGa Desk 1.0 ticketing tables. The same API is hit twice:
+
+1. **During the call** — `core/services/ticket_api.py` GETs by callback
+   number and work order for repeat-caller detection, then POSTs a new
+   ticket at end of call.
+2. **After the call** — `lambda_updated/api_client.py` PUTs the transcript +
+   audio + TXT report to `/ticket/{number}` to attach artifacts.
+
+Full contract, payload shapes, HMAC scheme, and PII considerations live in
+`features/ticket-api-integration.md`. TOGa Desk PHP side: see
+`1.0/apps/togadesk/architecture.md` for which underlying tables/controllers
+carry this traffic.
+
+## Storage
+
+- **S3 bucket** `talos-voice-to-voice` (shared, client-prefixed):
+  - `odp/upload/raw/<session_id>.ogg` — LiveKit egress staging.
+  - `odp/upload/<ticketNo>_<sessionId>_<refId>/`
+    - `call_recording.ogg` (moved from `raw/`)
+    - `session_report.json` (agent-written; triggers Lambda)
+  - `odp/processed/...` — Lambda destination on success.
+  - `odp/unprocessable/...` — no ticket number extractable.
+- **Bedrock Knowledge Base** — per-client KB id; documents uploaded to
+  `togaiq/<category>/<client_id>/archived/`.
+- **No primary DB.** Ticket state lives in TOGa Desk via the Ticket API.
+
+## Observability
+
+- LiveKit Cloud logs (`lk agent logs`).
+- Lambda → CloudWatch.
+- **No Langfuse / OTEL today.** Adding them requires an `observability/`
+  module mirroring talos's pattern; not yet built. This is the largest
+  known gap.
+
+## Key decisions
+
+- **AWS-native voice stack** — Transcribe + Bedrock + Polly. No external
+  voice vendors. Simpler IAM, single billing surface; ties us to AWS voice
+  quality.
+- **`core/` is copied into the build, not installed as a package.** Pragmatic
+  today, brittle if `core/` grows or two clients pin different versions.
+- **Custom Ticket API**, not direct TOGa Desk PHP — gives a stable contract
+  decoupled from the PHP framework's internal schema. The Agilant Ticket
+  API is the single seam between voice and Desk 1.0.
+- **Lambda post-processing**, not in-process. Keeps the agent worker hot;
+  post-call work is idempotent + retriable from S3 state.
+- **One ticket per call invariant** — `ensure_ticket_created_for_call`
+  (`core/services/ticket_api.py`) guarantees creation even if the LLM
+  forgot to call the tool.
+
+## Change history
+- 2026-06-16 — Initial architecture doc for voice-to-voice (TOGa Voice), with ODP as the first tenant. (akhokhani)

package/knowledge/2.0/apps/voice-to-voice/features/livekit-pipeline.md

@@ -0,0 +1,147 @@
+---
+title: LiveKit Voice Pipeline — STT / LLM / TTS / VAD / Turn Detection
+framework: "2.0"
+repo: voice-to-voice
+project: TOGa Voice
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - voice-to-voice/clients/odp/agent.py
+  - voice-to-voice/clients/odp/agents/tech_support.py
+  - voice-to-voice/clients/odp/livekit.toml
+  - voice-to-voice/clients/odp/Dockerfile
+  - voice-to-voice/clients/odp/deploy.sh
+  - voice-to-voice/clients/odp/pyproject.toml
+  - voice-to-voice/core/services/egress.py
+  - voice-to-voice/core/services/knowledge_base.py
+related:
+  - ../architecture.md
+  - ticket-api-integration.md
+  - post-call-lambda.md
+---
+
+## Summary
+
+The active voice loop is **fully AWS-native**: Amazon Transcribe (STT) →
+Bedrock Claude (LLM) → Amazon Polly (TTS), with Silero VAD and LiveKit's
+multilingual turn detector. Wrapped in LiveKit Agents SDK v1.4. One worker
+process per LiveKit Cloud agent; one `AgentSession` per call.
+
+## Key files / entry points
+
+| File | Purpose |
+|---|---|
+| `clients/odp/agent.py` | Worker bootstrap: `prewarm`, `entrypoint`, plugin wiring (lines ~115, 162–222) |
+| `clients/odp/agents/tech_support.py` | `TalosAgent(Agent)` subclass — tools, greeting, userdata shape |
+| `clients/odp/livekit.toml` | `project.subdomain`, `agent.id` for LiveKit Cloud |
+| `clients/odp/Dockerfile` | Multi-stage uv build; bakes Silero + turn-detector weights at build time |
+| `clients/odp/deploy.sh` | Copies `core/` into build context, syncs secrets, runs `lk agent deploy` |
+| `core/services/egress.py` | Starts `RoomCompositeEgress` → S3 .ogg; polls stop |
+| `core/services/knowledge_base.py` | Async wrapper around Bedrock `retrieve()` with TTL cache |
+
+## How it works
+
+### Worker lifecycle
+
+```
+WorkerOptions(prewarm, entrypoint)
+  └─ prewarm:   load Silero VAD model into shared process state
+  └─ entrypoint(JobContext):
+        ctx.connect()
+        derive callback_number/interaction_id from room name pattern
+            "call-_+<E164>_..."
+        AgentSession[CallUserdata](stt=…, llm=…, tts=…, vad=…, …)
+        session.start(room=ctx.room, agent=TalosAgent(...))
+        fire fetch_recent_tickets(callback_number)  ← Agilant Ticket API
+        await session.say(greeting)
+```
+
+### Plugin wiring (agent.py)
+
+| Stage | Plugin |
+|---|---|
+| **STT** | `aws.STT(language="en-US")` × 2 inside a `FallbackAdapter`. Transcribe disconnects after 15 s of silence; the fallback keeps the call alive. |
+| **LLM** | `aws.LLM(model=BEDROCK_HAIKU, temperature=0.4, max_tokens=300)` primary; `aws.LLM(model=BEDROCK_SONNET, …)` fallback. Both inside `FallbackAdapter`. |
+| **TTS** | `aws.TTS(voice="Matthew", engine="generative")` with **preemptive generation** for lower TTFB. |
+| **VAD** | `silero.VAD.load()` in `prewarm` (shared across jobs in the worker). |
+| **Turn detection** | LiveKit `MultilingualModel()` — endpointing 0.5–0.8 s; interruption threshold 1 word. |
+| **Noise suppression** | `livekit-plugins-noise-cancellation` (`BVCTelephony` profile for SIP calls). |
+
+### Agent class
+
+`TalosAgent` (`agents/tech_support.py`):
+
+- Inherits `livekit.agents.Agent`.
+- `instructions` = full system prompt loaded from `prompts.py`.
+- `on_enter()` plays greeting + fires KB warmup.
+- Tools (`@function_tool`):
+  - `set_caller_info(name, store_id, phone, workorder)` — incremental
+    update, called per field as provided.
+  - `search_knowledge_base(query)` — Bedrock KB lookup, `kb_max_results`
+    from config.
+  - `upsert_ticket_context(subject, summary, steps_tried, notes, priority)`
+    — populates `userdata` for end-of-call ticket creation.
+  - `link_existing_ticket(ticket_number, additional_notes)` — repeat
+    caller path; updates instead of creating.
+  - `mark_caller_as_customer()` — flag misrouted retail customer; short
+    flow.
+  - `end_call(farewell)` — speak goodbye then close room gracefully.
+
+### Userdata
+
+`CallUserdata` dataclass holds session-scoped state: `callback_number`,
+`interaction_id`, `session_id`, `recent_tickets` (populated by background
+`fetch_recent_tickets`), `caller_info`, `ticket_context`, `existing_ticket`,
+`is_customer_misroute`. Lives on `session.userdata` and is consumed by the
+post-call writer (see `post-call-lambda.md`).
+
+### Audio recording (egress)
+
+`core/services/egress.py` starts a `RoomCompositeEgress` at session start
+writing to `s3://talos-voice-to-voice/odp/upload/raw/<session_id>.ogg`. At
+end-of-call `s3_upload.py` moves the staged `.ogg` into the ticket folder
+`odp/upload/<ticketNo>_<sessionId>_<refId>/call_recording.ogg`, then deletes
+the staging file.
+
+### Knowledge base
+
+`core/services/knowledge_base.py` wraps Bedrock `retrieve()` with an
+in-process TTL cache (`kb_cache_ttl_seconds`, `kb_cache_max_entries` from
+config). Cache key is the query string. The agent's `search_knowledge_base`
+tool consults this.
+
+## Data model
+
+No DB. Per-call state: `session.userdata` (in memory). Persisted state: the
+S3 ticket folder + the Agilant Ticket API ticket record.
+
+## Client variations
+
+`config.yaml` is the seam. Per-client overrides: `client_id`, `client_name`,
+`agent_name`, `s3_upload_prefix`, `tts_voice`, `llm_max_tokens`,
+`kb_max_results`, `timezone`. `prompts.py` is per-client. `core/` is shared.
+
+## Gotchas / known issues
+
+- **Transcribe 15 s idle timeout** drops the connection silently — only the
+  `FallbackAdapter` saves the call. Do not collapse it to a single
+  `aws.STT(...)`.
+- **`deploy.sh` MUST copy `core/` into the client folder** before
+  `lk agent deploy`; otherwise import errors at boot. Most common deploy
+  fail.
+- **Silero weights are baked at build time.** If the upstream URL changes,
+  the build breaks. Pin a known-good `livekit-plugins-silero` version.
+- **Polly generative TTS** is region-restricted. Stay in `us-east-1`
+  unless you check availability.
+- **Room name parsing** for caller phone is regex-based on
+  `call-_+<E164>_...` — if LiveKit changes its SIP room naming, identity
+  lookup silently breaks. Guard with a sanity check in `entrypoint`.
+- **`asyncio.CancelledError` on user hangup** must propagate out of tools
+  without writing partial state — `userdata` is the source of truth for the
+  post-call ticket; partial writes leak.
+
+## Change history
+- 2026-06-16 — Initial LiveKit pipeline feature doc. (akhokhani)

package/knowledge/2.0/apps/voice-to-voice/features/post-call-lambda.md

@@ -0,0 +1,177 @@
+---
+title: Post-Call Lambda — Transcript Conversion, Report, Ticket Attachment
+framework: "2.0"
+repo: voice-to-voice
+project: TOGa Voice
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - voice-to-voice/lambda_updated/lambda_function.py
+  - voice-to-voice/lambda_updated/api_client.py
+  - voice-to-voice/lambda_updated/report_generator.py
+  - voice-to-voice/lambda_updated/transcript_converter.py
+  - voice-to-voice/lambda_updated/requirements.txt
+related:
+  - ../architecture.md
+  - livekit-pipeline.md
+  - ticket-api-integration.md
+---
+
+## Summary
+
+After every call, an AWS Lambda picks up the S3 ticket folder the agent
+left behind, converts the transcript to API format, generates a TXT
+report of the conversation, and `PUT /ticket/{number}` on the Agilant
+Ticket API to attach audio + report + transcript. On success the folder
+is moved from `upload/` to `processed/`; on failure it stays in place
+for the next tick to retry.
+
+## Key files / entry points
+
+| File | Role |
+|---|---|
+| `lambda_function.py` | Lambda handler. Resolves trigger mode, lists candidate folders, drives the per-folder pipeline, moves the folder on success |
+| `transcript_converter.py` | `convert_session_to_transcript(session_report)` — flat transcript → API format with synthetic incrementing timestamps; legacy fallbacks |
+| `report_generator.py` | `build_report(session_report)` — TXT report: header, exec summary, extracted identifiers, repeated-opener detection, full transcript |
+| `api_client.py` | `update_ticket(ticket_number, transcript, files)` — `PUT /ticket/{n}` with HMAC; base64-encoded files in payload |
+| `requirements.txt` | boto3, requests (sync — this is a Lambda, not an async server) |
+
+## How it works
+
+### Triggers (4 modes)
+
+| Mode | Event |
+|---|---|
+| Scheduled | EventBridge every 60 s — scans `<prefix>/upload/` (default `odp/upload/`) |
+| S3 event | Object-created on `session_report.json` |
+| Manual single | `{"folder_path": "odp/upload/<folder>"}` |
+| Manual batch | `{"folders": [...], "client_id": "odp"}` |
+
+### Per-folder pipeline
+
+```
+1. Parse ticket number from folder name `<ticketNo>_<sessionId>_<refId>`
+   (regex `^(\d+)_`); fail → move to <prefix>/unprocessable/.
+2. Download <folder>/session_report.json.
+3. If <folder>/call_recording.ogg missing, recover from
+   <prefix>/upload/raw/<session_id>.ogg.
+4. transcript = transcript_converter.convert_session_to_transcript(session_report)
+5. report_txt = report_generator.build_report(session_report)
+6. files = [
+       {filename: "session_report.txt", content: b64(report_txt),  mimetype: "text/plain"},
+       {filename: "call_recording.ogg", content: b64(audio_bytes), mimetype: "audio/ogg"}
+   ]
+7. api_client.update_ticket(ticket_number, transcript, files)
+   ─ PUT /ticket/{number}  (HMAC-signed)
+8. On 2xx: move folder from upload/ → processed/.
+   On non-2xx: log; folder stays in upload/ for next tick.
+9. Delete <prefix>/upload/raw/EG_*.json LiveKit egress metadata always.
+   Warn on stranded AJ_*.ogg without a matching folder.
+```
+
+### `session_report.json` shape (input)
+
+```json
+{
+  "ticket_number": "3066759",
+  "ticket_reference_id": "<UUID>",
+  "interaction_id": "...",
+  "session_id": "AJ_...",
+  "room_name": "...",
+  "callback_number": "+1...",
+  "customer_name": "...",
+  "store_id": "...",
+  "workorder": "...",
+  "transcript": [{"role": "user|assistant", "text": "..."}, ...],
+  "ended_at": "YYYY-MM-DD HH:MM:SS TZ"
+}
+```
+
+### Transcript conversion
+
+`convert_session_to_transcript(report)`:
+
+- Source: `report["transcript"]` (list of `{role, text}`).
+- Output: list of `{role, text, timestamp}` with **synthetic** incrementing
+  timestamps (`1.0, 2.0, ...`). Real timestamps are not captured today;
+  this is a known gap.
+- **Legacy fallbacks:** if `transcript` is absent, falls back to
+  `events[]` (older LiveKit format) or `chat_history`. Keep these
+  branches — old recordings in S3 still depend on them.
+
+### Report generator
+
+`build_report(report)` → plain-text:
+
+- Header: ticket number, session id, caller info (name, callback, store,
+  workorder).
+- Executive summary: user/assistant/total turn counts.
+- Extracted identifiers: phone numbers and numeric tokens via regex
+  (best-effort; used to spot work-order numbers).
+- Conversation quality: detection of repeated assistant openers (a sign
+  of scripty / stuck prompts).
+- Full transcript: line-by-line with synthetic timestamps.
+
+Legacy report shape also computes latency metrics (TTS TTFB, LLM TTFT,
+end-to-end) and tool-call stats / interruptions — kept for backward
+compatibility with older session reports.
+
+### API client
+
+Same Agilant Ticket API as the agent worker — see
+`ticket-api-integration.md` for the HMAC scheme and key env-var names.
+Endpoint: `PUT {API_BASE_URL}/ticket/{ticket_number}`.
+
+## Data model
+
+No DB. Lambda is **pure transformation** over S3 + ticket API state. The
+S3 folder is the durable buffer between the agent and the ticket system.
+
+## Client variations
+
+Per-client env in Lambda configuration (no YAML in Lambda):
+
+- `API_BASE_URL`, `<CLIENT>_API_PUBLIC_KEY`, `<CLIENT>_API_SECRET_KEY`
+- `MOVE_TO_PROCESSED` — when false, leave folders in place after success
+  (debug mode).
+- `S3_BUCKET`, default `talos-voice-to-voice`.
+- `CLIENT_PREFIXES` — list of S3 prefixes to scan (`["odp/upload"]`
+  today; add new client prefixes here).
+
+## Failure modes / retries
+
+- **No automatic in-Lambda retries.** A non-2xx leaves the folder in
+  `upload/`; the next EventBridge tick retries from scratch. Intentional
+  — Lambda execution time is metered.
+- **Missing `session_report.json`** → log and skip (audio without
+  metadata is unrecoverable).
+- **Missing `call_recording.ogg`** → attempt recovery from
+  `<prefix>/upload/raw/<session_id>.ogg`; if still missing, attach the
+  report only.
+- **No ticket number extractable** → folder moves to `unprocessable/`.
+  Manual review required.
+- **`EG_*.json` egress metadata** always deleted, regardless of success.
+  Stranded `AJ_*.ogg` (raw recordings with no matching folder) get a
+  warn log; not auto-cleaned.
+
+## Gotchas / known issues
+
+- **The 60 s EventBridge tick is the only retry loop.** A persistent
+  4xx from the API will keep failing; nothing escalates. Add a
+  CloudWatch alarm on `upload/` folder age if this becomes operational
+  pain.
+- **Synthetic timestamps in the transcript are not real.** Downstream
+  consumers (QA review, future Langfuse-style analysis) should not treat
+  them as wall-clock. Real timestamps would have to be captured at
+  source in the agent.
+- **Sync `requests` here, async `httpx` in the agent.** Different libs,
+  same HMAC code path — keep the signer copy-paste-correct or pull it
+  into a shared package.
+- **Lambda is on `requests`** — when porting to async, the HMAC signer
+  byte handling (raw HMAC → base64) must be preserved exactly.
+
+## Change history
+- 2026-06-16 — Initial post-call-lambda feature doc. (akhokhani)

package/knowledge/2.0/apps/voice-to-voice/features/ticket-api-integration.md

@@ -0,0 +1,251 @@
+---
+title: Agilant Ticket API — TOGa Desk 1.0 Integration
+framework: "2.0"
+repo: voice-to-voice
+project: TOGa Voice
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - voice-to-voice/core/services/ticket_api.py
+  - voice-to-voice/lambda_updated/api_client.py
+  - voice-to-voice/lambda_updated/lambda_function.py
+  - voice-to-voice/clients/odp/agent.py
+  - voice-to-voice/clients/odp/config.yaml
+  - voice-to-voice/scripts/test_ticket_api.sh
+  - voice-to-voice/docs/inbound-call-routing-rd.md
+related:
+  - ../architecture.md
+  - livekit-pipeline.md
+  - post-call-lambda.md
+  - ../../../1.0/apps/togadesk/architecture.md
+---
+
+## Summary
+
+This is the **single seam** between the new Python voice agent and the
+legacy **TOGa Desk 1.0** PHP ticketing app. The voice agent does **not**
+talk to the TOGa Desk `/desk/api/index.php` PHP endpoint directly. It talks
+to a separate, narrow **Agilant Ticket API** at
+`https://api.agilantsolutions.com` that abstracts ticket
+create/read/update over TOGa Desk's internal tables.
+
+Two write paths, one read path:
+
+1. **Read (during call):** `GET /ticket/callbacknumber/{phone}` and
+   `GET /ticket/workorder/{workorder}` for repeat-caller detection.
+2. **Write (end of call, from agent worker):** `POST /ticket` to create
+   the ticket from accumulated `session.userdata`.
+3. **Write (post-call, from Lambda):** `PUT /ticket/{ticket_number}` to
+   attach transcript + audio + TXT report.
+
+## Key files / entry points
+
+| File | Role |
+|---|---|
+| `core/services/ticket_api.py` | Agent-side HTTP client (21 KB). GETs, POST, HMAC signer, retry, dedup scoring, `ensure_ticket_created_for_call` |
+| `lambda_updated/api_client.py` | Lambda-side HTTP client. PUT with base64-encoded files (audio + report) |
+| `lambda_updated/lambda_function.py` | Orchestrator — reads `session_report.json`, calls `api_client.update_ticket(...)` |
+| `clients/odp/agent.py` | Fires `fetch_recent_tickets(callback_number)` async at session start |
+| `scripts/test_ticket_api.sh` | Smoke test against the prod API |
+
+## How it works
+
+### Authentication — HMAC-SHA256
+
+Every request to `api.agilantsolutions.com` is signed:
+
+```
+ts        = utcnow().isoformat()                            # ISO-8601
+sig       = HMAC-SHA256(secret_key, ts)                     # raw bytes
+auth_hdr  = f"{public_key}.{base64(sig)}"
+```
+
+Headers on every call:
+
+```
+Authorization: {public_key}.{b64sig}
+Timestamp:     {ts}
+Content-Type:  application/json
+```
+
+Keys live in env (never in repo):
+
+- Agent worker: `ODP_API_PUBLIC_KEY`, `ODP_API_SECRET_KEY` (read by
+  `base_config.py` → `core.utils.get_config()`).
+- Lambda: same env var names, loaded from Lambda config.
+
+`ticket_api.py:30–57` implements the signer; replicate exactly in any new
+caller. **Never** invent a new signing scheme.
+
+### 1) Inbound — repeat-caller detection (`GET`)
+
+At session start `clients/odp/agent.py:235–249` fires (background) via
+`asyncio.create_task`:
+
+```
+GET /ticket/callbacknumber/{digits}        # 10-digit, no country code
+```
+
+Implementation: `ticket_api.fetch_recent_tickets()` (lines 85–143). Result
+lands on `session.userdata.recent_tickets`.
+
+For work-order validation (during the conversation):
+
+```
+GET /ticket/workorder/{workorder}
+```
+
+`ticket_api.validate_work_order(workorder, store_id)` (lines 182–281)
+returns `{store_match, expected_store, related_tickets}`.
+
+A composite scorer
+`fetch_recent_tickets_by_store_workorder(number, store_id, workorder)`
+ranks results as **exact / store_only / phone_only** to detect a true
+repeat caller vs. shared-line noise.
+
+### 2) End-of-call — ticket creation (`POST`)
+
+`ticket_api.py:378–435` builds the payload from `session.userdata`:
+
+```json
+{
+  "ticket_reference_id": "<UUID>",
+  "customer_name": "...",
+  "callback_number": "+1...",
+  "store_id": "...",
+  "workorder": "...",
+  "ticket_subject": "...",
+  "issue_summary": "...",
+  "steps_tried": "...",
+  "notes_for_human": "...",
+  "reason_to_transfer_human": "...",
+  "transcript": [{"role": "user|assistant", "text": "..."}, ...],
+  "status": "open",
+  "priority": "normal|high|low|critical",
+  "created_at": "<ISO-8601>",
+  "updated_at": "<ISO-8601>"
+}
+```
+
+Response: `{success: bool, ticketNumber: "<numeric string>", ...}`.
+
+**Retry policy:** 2 retries on 5xx with exponential backoff (lines
+417–420). 4xx fails fast — never retry a rejection.
+
+**One-ticket-per-call invariant.**
+`ensure_ticket_created_for_call(userdata, transcript)` (last thing the
+worker does before shutdown) creates a ticket from derived fields if the
+LLM forgot to call `upsert_ticket_context`. **Always called.** Removing
+this guarantee leaks call data into S3 with no destination.
+
+### 3) Post-call — attach artifacts (`PUT`)
+
+`lambda_updated/api_client.py:113–213`:
+
+```
+PUT /ticket/{ticket_number}
+{
+  "transcript": [{"role": "user|assistant", "text": "..."}, ...],
+  "files": [
+    {"filename": "call_recording.ogg", "content": "<base64>", "mimetype": "audio/ogg"},
+    {"filename": "session_report.txt", "content": "<base64>", "mimetype": "text/plain"}
+  ]
+}
+```
+
+Same HMAC scheme. Ticket number comes from the S3 folder name
+`<ticketNo>_<sessionId>_<refId>` (regex `^(\d+)_`). No retries in Lambda
+today — failure leaves the folder in `odp/upload/` and the next
+EventBridge tick re-tries it from S3 state.
+
+## How it lands in TOGa Desk 1.0
+
+The Agilant Ticket API is the seam — but it ultimately writes to the same
+underlying TOGa Desk tables (`TOGaDeskSupport.tickets` and related). From
+the 1.0 togadesk docs the inferred mapping is:
+
+| Voice payload field | Desk side |
+|---|---|
+| `ticket_reference_id` | UUID column (looked up for idempotency) |
+| `callback_number`, `customer_name` | Customer fields on the ticket row |
+| `ticket_subject`, `issue_summary`, `steps_tried` | Ticket body / description fields |
+| `transcript` | Attached as a transcript record or note |
+| `files[]` (PUT) | Ticket attachments (audio + TXT report) |
+| `status`, `priority` | Direct columns |
+| `store_id`, `workorder` | Custom fields on the ODP ticket form |
+
+The voice agent never touches TOGa Desk's `App_Controller_*` PHP code. If
+the Desk-side schema or controllers move, only the Agilant Ticket API
+adapter has to change — the voice agent contract is stable.
+
+## Data model
+
+No local persistence in voice-to-voice. The Ticket API + S3 ticket folder
+are the durable record:
+
+```
+S3:  odp/upload/<ticketNo>_<sessionId>_<refId>/
+       ├─ session_report.json     (agent-written; ticket payload mirror)
+       ├─ call_recording.ogg
+       └─ session_report.txt      (Lambda-generated)
+
+API: GET  /ticket/callbacknumber/{phone}
+     GET  /ticket/workorder/{wo}
+     POST /ticket
+     PUT  /ticket/{number}
+```
+
+## Client variations
+
+Per-client config in `config.yaml` + env:
+
+- `ticket_api_base_url` (override; default `https://api.agilantsolutions.com`)
+- `ticket_api_timeout` (default 10 s)
+- `<CLIENT>_API_PUBLIC_KEY`, `<CLIENT>_API_SECRET_KEY` env var pair
+  (ODP today; future clients get their own pair).
+
+All clients use the same HMAC scheme and the same endpoint paths. Only
+the keys differ.
+
+## Trust boundary / security
+
+- **HMAC of timestamp only — body is not signed.** Replay is bounded by
+  the server-side timestamp window; tampering is mitigated by HTTPS. Do
+  not weaken the timestamp check server-side.
+- **PII in payload.** Transcripts carry customer names, phone numbers,
+  store IDs, and any spoken work-order numbers. Treat
+  `session_report.json` and the `transcript` field as PII at rest.
+- **Keys never in repo.** `.env.example` shows the variable names; values
+  live only in LiveKit Cloud secrets and Lambda config. The
+  `RedactSigV4` helper in `core/utils.py` redacts AWS signing headers
+  from logs; confirm the ticket-API `Authorization` header is also
+  redacted before adding any new logging.
+- **No 4xx retry.** Forbidding 4xx retries is what protects against
+  permission-misconfig cascades — keep it that way.
+- **Test keys.** `scripts/test_ticket_api.sh` runs against the same prod
+  API; rotate its keys if they ever leak.
+
+## Gotchas / known issues
+
+- **Phone normalization is required everywhere.** API expects 10-digit US
+  (`2017366218`), not `+12017366218`. Always run
+  `core/utils.sanitize_phone()` before constructing a URL.
+- **`ticket_reference_id` must be a stable UUID generated client-side**
+  for the lifetime of the call. If two retries generate different UUIDs
+  the server creates duplicate tickets.
+- **`session_report.json` MUST be written last** in the agent shutdown
+  sequence — its presence in S3 is what triggers Lambda. Writing it
+  before the audio is moved into the ticket folder races the Lambda.
+- **The Agilant Ticket API is private** — no public docs, no OpenAPI.
+  The shape lives in `ticket_api.py` and is the canonical reference.
+  Update this doc when the payload changes.
+- **TOGa Desk PHP changes can silently break the API contract.** If a
+  Desk-side migration renames a column the Agilant API maps to, POSTs may
+  succeed but read-backs miss data. Coordinate cross-team for any
+  `tickets` table change in 1.0.
+
+## Change history
+- 2026-06-16 — Initial ticket-api-integration feature doc — the TOGa Desk 1.0 ↔ voice-to-voice seam. (akhokhani)

package/knowledge/INDEX.md

@@ -23,6 +23,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **toga2-view** (TOGa View Frontend) — 0 doc(s) → [2.0/apps/toga2-view/INDEX.md](2.0/apps/toga2-view/INDEX.md)
 - **toga2-hub** (TOGa Hub) — 2 doc(s) → [2.0/apps/toga2-hub/INDEX.md](2.0/apps/toga2-hub/INDEX.md)
 - **talos** (TOGa IQ) — 6 doc(s) → [2.0/apps/talos/INDEX.md](2.0/apps/talos/INDEX.md)
+- **voice-to-voice** (TOGa Voice) — 4 doc(s) → [2.0/apps/voice-to-voice/INDEX.md](2.0/apps/voice-to-voice/INDEX.md)
 
 ## standalone framework
 
@@ -34,6 +35,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **Compass USA** (`compass-usa`) → [clients/compass-usa/INDEX.md](clients/compass-usa/INDEX.md)
 - **Elite** (`elite`) → [clients/elite/INDEX.md](clients/elite/INDEX.md)
 - **New York City Department of Education** (`nycdoe`) → [clients/nycdoe/INDEX.md](clients/nycdoe/INDEX.md)
+- **Office Depot** (`office-depot`) → [clients/office-depot/INDEX.md](clients/office-depot/INDEX.md)
 - **Prudential Financial** (`prudential`) → [clients/prudential/INDEX.md](clients/prudential/INDEX.md)
 - **Rate** (`rate`) → [clients/rate/INDEX.md](clients/rate/INDEX.md)
 - **Tow Foundation** (`tow-foundation`) → [clients/tow-foundation/INDEX.md](clients/tow-foundation/INDEX.md)

package/knowledge/clients/office-depot/INDEX.md

@@ -0,0 +1,6 @@
+# Client: Office Depot `office-depot`
+
+| Doc | Framework | Summary | Files |
+|-----|-----------|---------|-------|
+| [ODP Tech Support Agent (Office Depot variant)](features/odp-tech-support.md) | 2.0 | ODP-specific customization of the shared TOGa Voice agent. | voice-to-voice/clients/odp/agent.py, voice-to-voice/clients/odp/agents/tech_support.py, voice-to-voice/clients/odp/prompts.py, voice-to-voice/clients/odp/config.yaml, voice-to-voice/clients/odp/.env.example |
+| [Office Depot](profile.md) | 2.0 | Office Depot is the first deployed tenant of the **TOGa Voice** (`voice-to-voice`) platform. |  |

package/knowledge/clients/office-depot/features/odp-tech-support.md

@@ -0,0 +1,144 @@
+---
+title: ODP Tech Support Agent (Office Depot variant)
+framework: "2.0"
+project: TOGa Voice
+client: office-depot
+type: client-feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - voice-to-voice/clients/odp/agent.py
+  - voice-to-voice/clients/odp/agents/tech_support.py
+  - voice-to-voice/clients/odp/prompts.py
+  - voice-to-voice/clients/odp/config.yaml
+  - voice-to-voice/clients/odp/.env.example
+related:
+  - ../profile.md
+  - ../../../2.0/apps/voice-to-voice/architecture.md
+  - ../../../2.0/apps/voice-to-voice/features/livekit-pipeline.md
+  - ../../../2.0/apps/voice-to-voice/features/ticket-api-integration.md
+---
+
+## Summary
+
+ODP-specific customization of the shared TOGa Voice agent. The platform's
+LiveKit pipeline, tools, and Ticket API integration are unchanged; what
+changes per client is **the system prompt, the config values, and the
+auth keys**. This file documents what's *different* about the ODP
+deployment.
+
+Base feature: `2.0/apps/voice-to-voice/features/livekit-pipeline.md`.
+
+## What's ODP-specific
+
+### Audience and tone
+
+- **Audience:** Office Depot **store associates** doing tech-support work
+  on store equipment (POS, network, peripheral hardware). **Not** retail
+  customers. The system prompt enforces this — `mark_caller_as_customer()`
+  is the dedicated short-circuit for the misroute path.
+- **Persona:** "Talos" — warm, calm, human voice. Three rules dominate
+  the prompt (`prompts.py`):
+  1. Speak plainly — no JSON, no markdown, no acronyms unless the caller
+     uses them first.
+  2. One question per turn.
+  3. **Spell out numbers and identifiers digit-by-digit** for TTS clarity
+     (work orders, store numbers, ticket numbers).
+
+### Call flow
+
+```
+greeting
+  → collect caller name + store_id + work_order  (set_caller_info per field)
+  → detect customer misroute → mark_caller_as_customer → polite close
+  → describe issue
+  → search_knowledge_base (Bedrock KB, top-2)
+  → walk through KB steps; if resolved, end_call
+  → if not resolved or repeat caller:
+        repeat?  link_existing_ticket(number, notes)
+        new?     upsert_ticket_context(subject, summary, steps_tried, notes, priority)
+  → end_call(farewell)
+```
+
+### Tools (ODP exposes the platform set)
+
+`set_caller_info`, `search_knowledge_base`, `upsert_ticket_context`,
+`link_existing_ticket`, `mark_caller_as_customer`, `end_call` — same set
+as `TalosAgent`. No ODP-specific tools today.
+
+### config.yaml differences from default
+
+```yaml
+client_id: "odp"
+client_name: "Office Depot"
+agent_name: "odp-tech-support"
+s3_upload_prefix: "odp/upload"
+tts_voice: "Matthew"           # Polly generative
+llm_max_tokens: 300
+kb_max_results: 2
+timezone: "America/Chicago"
+```
+
+### Required env vars (per `.env.example`)
+
+- `ODP_API_PUBLIC_KEY`, `ODP_API_SECRET_KEY` — Agilant Ticket API keys
+  (the **only** auth into TOGa Desk).
+- `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`.
+- `AWS_REGION=us-east-1`, plus IAM role / keys for Transcribe + Bedrock +
+  Polly + S3.
+- `BEDROCK_KNOWLEDGE_BASE_ID` — ODP's KB.
+- `S3_BUCKET=talos-voice-to-voice`.
+
+Values live only in LiveKit Cloud secrets (synced by `deploy.sh`) — never
+in the repo.
+
+### LiveKit Cloud identity
+
+```toml
+# clients/odp/livekit.toml
+[project]
+  subdomain = "talos-xwwues9e"
+[agent]
+  id = "CA_Do8Vhz3oqYH7"
+```
+
+### Bedrock Knowledge Base
+
+ODP-specific. Documents uploaded to
+`s3://talos-voice-to-voice/togaiq/<category>/odp/archived/`, ingested by
+the ODP KB. The agent's `search_knowledge_base` tool calls this KB only.
+
+## How it relates to TOGa Desk 1.0
+
+| Touchpoint | Path |
+|---|---|
+| Repeat caller lookup | `GET /ticket/callbacknumber/{digits}` on session start |
+| Work-order validation | `GET /ticket/workorder/{wo}` mid-conversation |
+| Ticket creation | `POST /ticket` from worker shutdown (with `ensure_ticket_created_for_call` guarantee) |
+| Transcript + audio attachment | `PUT /ticket/{number}` from the Lambda post-call processor |
+
+Tickets land in `TOGaDeskSupport.tickets` (and related attachment tables)
+via the Agilant API adapter. ODP-specific fields on the Desk side:
+`store_id`, `workorder` (custom columns on the Desk ticket form).
+
+See `2.0/apps/voice-to-voice/features/ticket-api-integration.md` for the
+full contract, HMAC scheme, and PII considerations.
+
+## Gotchas / known issues
+
+- **Spelling-out rule is in the prompt, not enforced in code.** A prompt
+  edit can silently break it. After any prompt change, dry-run a call
+  with a 7-digit work order and confirm Polly says digit-by-digit.
+- **KB results are capped at 2.** Increasing this hurts latency and
+  rarely helps relevance — Bedrock retrieval already top-K's by
+  relevance.
+- **`mark_caller_as_customer` must short-circuit cleanly** — do not
+  trigger ticket creation on the misroute path; that's noise in Desk
+  triage queues.
+- **Repeat-caller dedup is best-effort.** Don't auto-merge tickets — the
+  `link_existing_ticket` tool always requires the LLM to confirm the
+  match number with the caller out loud.
+
+## Change history
+- 2026-06-16 — Initial ODP tech-support client-feature doc. (akhokhani)

package/knowledge/clients/office-depot/profile.md

@@ -0,0 +1,89 @@
+---
+title: Office Depot
+framework: "2.0"
+project: TOGa Voice
+client: office-depot
+type: profile
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files: []
+related:
+  - features/odp-tech-support.md
+  - ../../2.0/apps/voice-to-voice/architecture.md
+  - ../../2.0/apps/voice-to-voice/features/ticket-api-integration.md
+  - ../../1.0/apps/togadesk/architecture.md
+---
+
+## Summary
+
+Office Depot is the first deployed tenant of the **TOGa Voice**
+(`voice-to-voice`) platform. Today the relationship is **inbound phone
+support for Office Depot store associates** (not retail customers): a
+LiveKit voice agent on a toll-free line answers calls from store staff,
+walks them through tech-support troubleshooting (point of sale, networking,
+peripheral hardware), and creates / updates tickets in **TOGa Desk 1.0**
+via the Agilant Ticket API.
+
+Office Depot also appears as a **vendor** of the Compass USA TOGa client
+(unrelated to this voice deployment — different team, different system).
+This profile only covers the **voice / Desk** relationship.
+
+## Platforms & data
+
+- **TOGa Voice (2.0 — Python / LiveKit):** ODP agent at
+  `voice-to-voice/clients/odp/`. Deployed to LiveKit Cloud as agent
+  `CA_Do8Vhz3oqYH7` under project subdomain `talos-xwwues9e`.
+- **TOGa Desk 1.0 (PHP):** the system of record for tickets. Voice writes
+  reach Desk via the Agilant Ticket API at `api.agilantsolutions.com` —
+  never directly via the PHP `/desk/api/`.
+- **AWS:** shared `talos-voice-to-voice` S3 bucket, client prefix `odp/`.
+  Bedrock Knowledge Base per ODP (id in env). Lambda post-processor scans
+  `odp/upload/`.
+
+## Voice configuration (ODP-specific)
+
+| Field | Value |
+|---|---|
+| `client_id` | `odp` |
+| `client_name` | `Office Depot` |
+| `agent_name` | `odp-tech-support` |
+| TTS voice | Amazon Polly **Matthew** (generative) |
+| Timezone | `America/Chicago` |
+| KB max results | 2 |
+| LLM max tokens | 300 |
+| S3 upload prefix | `odp/upload` |
+
+System prompt is in `clients/odp/prompts.py`; persona is "Talos" — warm,
+calm, human-sounding tech-support agent for store associates.
+
+## Call flow (one-paragraph)
+
+Store associate dials the ODP toll-free number → LiveKit SIP routes to the
+ODP agent worker → background `fetch_recent_tickets(callback_number)` warms
+repeat-caller context → agent greets, asks for name + store + work order
+→ branches: misrouted retail customer → polite close; new issue → KB
+search + troubleshooting + ticket creation; repeat caller → link existing
+ticket → goodbye. End-of-call → S3 ticket folder + `session_report.json`
+written → Lambda picks up, builds TXT report, PUTs to the ticket.
+
+## Key features (this client)
+
+- [ODP Tech Support Agent](features/odp-tech-support.md) — ODP-specific
+  prompt / tool surface / config, layered over the shared platform.
+
+## Gotchas / known issues
+
+- **Audience is store staff, not retail customers.** When the LLM
+  misclassifies a retail caller (the misroute path), the
+  `mark_caller_as_customer()` tool short-circuits the flow — keep that
+  branch.
+- **Phone identification is best-effort.** A shared store landline can
+  yield false-positive "repeat caller" matches; the dedup scorer in
+  `core/services/ticket_api.py` produces an `exact|store_only|phone_only`
+  rank, never silently merges.
+- **PII at rest.** Transcripts + audio sit in S3 with associate names,
+  phone numbers, store IDs. Treat the `odp/` prefix as PII-class.
+
+## Change history
+- 2026-06-16 — Initial Office Depot profile — first voice tenant, Desk 1.0 ticketing. (akhokhani)

package/knowledge/registry.json

@@ -15,5 +15,6 @@
   { "repo": "webhook",     "project": "Webhook",     "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
   { "repo": "walmarttechservices", "project": "Walmart Tech Services", "framework": "1.0", "role": "app", "dependsOn": ["library"] },
   { "repo": "talos",       "project": "TOGa IQ",      "framework": "2.0", "role": "app", "dependsOn": [] },
-  { "repo": "test",        "project": "Test",        "framework": "1.0", "role": "app",  "dependsOn": ["library"] }
+  { "repo": "test",        "project": "Test",        "framework": "1.0", "role": "app",  "dependsOn": ["library"] },
+  { "repo": "voice-to-voice", "project": "TOGa Voice", "framework": "2.0", "role": "app", "dependsOn": [] }
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.91",
+  "version": "1.0.92",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/rules/python/python.md

@@ -0,0 +1,136 @@
+# Python Rules (applies to all TOGA Python repos)
+
+Applies to every TOGA Python project: **talos** (`aegra-api`, `react_agent`,
+`mcp-servers/*`) and **voice-to-voice** (`core/`, `clients/*`,
+`lambda_updated/`). Future Python repos inherit these by default.
+
+## Toolchain
+
+- **Package manager: `uv`** is canonical. Never run `pip install` ad hoc; add
+  to `pyproject.toml` and `uv sync`. Never use Poetry.
+- **Build backend: `hatchling`** in `[build-system]`. No setuptools, no flit.
+- **Python ≥ 3.11.** 3.12 features are allowed when the target image
+  supports it (voice-to-voice runs 3.12).
+
+## Layout
+
+- **`src/` layout mandatory** for any installable package. Tests live in
+  `tests/` parallel to `src/`.
+- **Module structure inside `src/<pkg>/`** (the aegra-api template):
+  - `api/` — FastAPI routers (one file per domain).
+  - `services/` — business logic.
+  - `models/` — Pydantic schemas, errors.
+  - `core/` — foundational infra (auth, db, config, encryption).
+  - `middleware/` — ASGI/HTTP middleware.
+  - `observability/` — logging, tracing, metrics setup.
+  - `utils/` — pure utilities; **no I/O, no globals**.
+- **Flat layout is forbidden** for new packages.
+
+## Async
+
+- **Async-first.** FastAPI routes and I/O service methods are `async def`.
+  Use `httpx` — **never `requests`** in async paths.
+- **Never block the event loop.** Wrap sync libs with `asyncio.to_thread(...)`
+  or an executor.
+- **Handle `asyncio.CancelledError` explicitly** in long-running services
+  (skip cleanup if the task is being re-enqueued — see
+  `services/run_executor.py`).
+
+## Typing
+
+- **Type hints everywhere.** No untyped public parameters or returns.
+- **`from __future__ import annotations`** at the top of every module.
+- **Pydantic v2 for all DTOs and Settings.** Use `dataclass` only for
+  internal value objects, never for request/response shapes.
+- Use `Field(..., description=...)` on every cross-boundary field — the
+  description appears in OpenAPI.
+- Cross-field invariants: `@field_validator` and
+  `@model_validator(mode="after")` (see `models/runs.py`).
+
+## Config
+
+- **`pydantic_settings.BaseSettings` is the only config base class.**
+- Precedence: **env vars > `.env.local` > `.env` > YAML defaults > field
+  defaults**.
+- Non-secret defaults go in `config.yaml` (voice-to-voice pattern). Secrets
+  come from env vars only — never commit `.env` (only `.env.example`).
+- `SettingsConfigDict(env_file=(".env", ".env.local"), extra="ignore")` is
+  the standard. Use `extra="ignore"`, not `"forbid"`, so future-added env
+  vars don't break old deploys.
+- **Multiple Settings subclasses per module are fine** (aegra-api has 13).
+  Do not collapse them into one mega-class.
+
+## Logging
+
+- **`structlog` for all operational logs.** Module-level
+  `logger = structlog.get_logger(__name__)`.
+- **Structured fields, not f-strings.**
+  `logger.info("ticket.created", ticket_id=tid)` — never
+  `logger.info(f"created ticket {tid}")`.
+- **Correlation IDs via `asgi-correlation-id`** middleware on every HTTP
+  service.
+- Stdlib `logging` is allowed only at startup, before structlog is
+  configured.
+
+## Errors
+
+- **No bare `except Exception:`.** Catch the narrowest exception that fits.
+- Custom exception types live in `models/errors.py` (or `<pkg>/errors.py`).
+- **FastAPI:** raise `HTTPException(status_code, detail=...)` at the router
+  layer. Services raise domain exceptions; an exception handler in `main.py`
+  maps them.
+- **Retry only on transient (5xx, connection) errors.** 4xx fails fast.
+  See `core/services/ticket_api.py` and `lambda_updated/api_client.py`.
+
+## HTTP clients
+
+- **`httpx.AsyncClient` for async, `requests` only in sync scripts.**
+- Always pass `timeout=` explicitly — never accept the default.
+- Centralize auth/signing in one client module per external service
+  (e.g. `ticket_api.py` for the Agilant Ticket API). Routes call the client,
+  never `httpx` directly.
+
+## Migrations
+
+- **Alembic** for any schema touch. Migration files
+  `YYYYMMDDHHMMSS_description.py` under `alembic/versions/`.
+- Use `op.create_table(...)` / `op.add_column(...)` — never raw
+  `CREATE TABLE` strings in migrations.
+- **Always implement `downgrade()`**, even if it's an explicit
+  `op.execute("...")` reverse. Empty downgrades break rollback.
+- PostgreSQL extensions are enabled in migrations
+  (`CREATE EXTENSION IF NOT EXISTS "uuid-ossp"`), not at runtime.
+
+## Tests
+
+- **`pytest` only** — no `unittest.TestCase`.
+- Async tests: `asyncio_mode = "auto"` in `pyproject.toml`; plain
+  `async def test_*` works without decoration.
+- Test layout: `tests/unit/`, `tests/integration/`. Fixtures in
+  `conftest.py` per directory.
+- Marker set: `unit` (no external calls), `api` (real HTTP, no LLM),
+  `integration` (full LLM + API). Declare any new marker in
+  `[tool.pytest.ini_options].markers`.
+
+## Secrets and PII
+
+- **Never paste a credential value in code or in committed docs.** Reference
+  the env var name (e.g. `ODP_API_SECRET_KEY`). The `capture` publisher
+  scans for credential literals and fails the publish if any are found.
+- **Use `cryptography.Fernet`** (symmetric) for at-rest encryption of
+  metadata; helper lives at `core/encryption.py` in aegra-api.
+- **AWS SigV4 / Authorization headers must be redacted in logs.** See
+  `RedactSigV4` in voice-to-voice-new for the helper.
+- Validate metadata keys against a whitelist regex before persisting them
+  (see `api/threads.py:49`).
+- `bandit` runs as a dev dep; fix findings, don't suppress them.
+
+## Don't
+
+- `pip install` inside the repo. Use `uv add`.
+- `requests` in async code.
+- f-strings inside `logger.*` calls.
+- Bare `except:` or `except Exception:` without a re-raise.
+- Hardcoded URLs, hosts, or credentials anywhere in source.
+- A new "utils.py" grab bag — place pure helpers in `utils/<topic>.py`.
+- Mixing sync and async inside the same service class.