toga-ai 1.0.91 → 1.0.93

package/knowledge/2.0/apps/talos/INDEX.md

@@ -2,9 +2,9 @@
 
 | Doc | Summary | Files |
 |-----|---------|-------|
-| [TOGa IQ (talos) Architecture](architecture.md) | **TOGa IQ** is TOGA Technology's AI agent platform. | talos/libs/aegra-api/src/aegra_api/main.py, talos/libs/aegra-api/src/aegra_api/settings.py, talos/libs/aegra-api/src/aegra_api/config.py, talos/libs/aegra-api/src/aegra_api/core/tenant_router.py, talos/libs/aegra-api/src/aegra_api/core/control_plane_db.py, talos/libs/aegra-api/src/aegra_api/core/auth_middleware.py, talos/libs/aegra-api/src/aegra_api/services/run_executor.py, talos/libs/aegra-api/src/aegra_api/services/langgraph_service.py, talos/libs/aegra-api/src/aegra_api/services/graph_factory.py, talos/libs/aegra-api/src/aegra_api/services/streaming_service.py, talos/examples/react_agent/graph.py, talos/docker-compose.yml, talos/deployments/docker/Dockerfile |
+| [TOGa IQ (talos) Architecture](architecture.md) | **TOGa IQ** is TOGA Technology's AI agent platform. | talos/libs/aegra-api/src/aegra_api/main.py, talos/libs/aegra-api/src/aegra_api/settings.py, talos/libs/aegra-api/src/aegra_api/config.py, talos/libs/aegra-api/src/aegra_api/core/tenant_router.py, talos/libs/aegra-api/src/aegra_api/core/control_plane_db.py, talos/libs/aegra-api/src/aegra_api/core/auth_middleware.py, talos/libs/aegra-api/src/aegra_api/services/run_executor.py, talos/libs/aegra-api/src/aegra_api/services/langgraph_service.py, talos/libs/aegra-api/src/aegra_api/services/graph_factory.py, talos/libs/aegra-api/src/aegra_api/services/streaming_service.py, talos/agents/talos_agent/graph.py, talos/docker-compose.yml, talos/deployments/docker/Dockerfile |
 | [aegra-api — Agent Protocol HTTP + Execution Pipeline](features/aegra-api.md) | `aegra-api` is the **FastAPI Agent Protocol server** at the heart of TOGa IQ. | talos/libs/aegra-api/src/aegra_api/main.py, talos/libs/aegra-api/src/aegra_api/settings.py, talos/libs/aegra-api/src/aegra_api/config.py, talos/libs/aegra-api/src/aegra_api/api/assistants.py, talos/libs/aegra-api/src/aegra_api/api/threads.py, talos/libs/aegra-api/src/aegra_api/api/runs.py, talos/libs/aegra-api/src/aegra_api/api/store.py, talos/libs/aegra-api/src/aegra_api/api/mcp.py, talos/libs/aegra-api/src/aegra_api/api/knowledge_bases.py, talos/libs/aegra-api/src/aegra_api/core/auth_middleware.py, talos/libs/aegra-api/src/aegra_api/core/auth_deps.py, talos/libs/aegra-api/src/aegra_api/core/tenant_router.py, talos/libs/aegra-api/src/aegra_api/core/control_plane_db.py, talos/libs/aegra-api/src/aegra_api/core/redis_manager.py, talos/libs/aegra-api/src/aegra_api/core/encryption.py, talos/libs/aegra-api/src/aegra_api/middleware/content_type_fix.py, talos/libs/aegra-api/src/aegra_api/middleware/rate_limiter.py, talos/libs/aegra-api/src/aegra_api/middleware/logger_middleware.py, talos/libs/aegra-api/src/aegra_api/services/broker.py, talos/libs/aegra-api/src/aegra_api/services/redis_broker.py, talos/libs/aegra-api/src/aegra_api/services/executor.py, talos/libs/aegra-api/src/aegra_api/services/local_executor.py, talos/libs/aegra-api/src/aegra_api/services/worker_executor.py, talos/libs/aegra-api/src/aegra_api/services/run_executor.py, talos/libs/aegra-api/src/aegra_api/services/langgraph_service.py, talos/libs/aegra-api/src/aegra_api/services/graph_factory.py, talos/libs/aegra-api/src/aegra_api/services/graph_streaming.py, talos/libs/aegra-api/src/aegra_api/services/streaming_service.py, talos/libs/aegra-api/src/aegra_api/services/event_store.py, talos/libs/aegra-api/alembic/env.py |
 | [Deployment — Docker, Compose, Entrypoint, External PG/Redis](features/deployment.md) | TOGa IQ ships as a **single container** (`aegra` service) wrapping the `aegra-api` FastAPI server. | talos/docker-compose.yml, talos/deployments/docker/Dockerfile, talos/deployments/docker/entrypoint.sh |
 | [MCP Servers — clickup-mcp and toga-db-mcp](features/mcp-servers.md) | Two internal **FastMCP** servers exposed over **HTTP** with API-key auth and PM2 process management: - **`clickup-mcp`** — ClickUp workspace surface (spaces / f | talos/mcp-servers/clickup-mcp/src, talos/mcp-servers/clickup-mcp/ecosystem.config.js, talos/mcp-servers/clickup-mcp/ecosystem.dev.config.js, talos/mcp-servers/clickup-mcp/pyproject.toml, talos/mcp-servers/clickup-mcp/.env.example, talos/mcp-servers/toga-db-mcp/src, talos/mcp-servers/toga-db-mcp/clusters.yaml, talos/mcp-servers/toga-db-mcp/ecosystem.config.js, talos/mcp-servers/toga-db-mcp/pyproject.toml, talos/mcp-servers/toga-db-mcp/.env.example |
 | [Observability — Langfuse, OTEL, Prometheus, OneUptime](features/observability.md) | TOGa IQ uses **two complementary tracing planes** plus optional Prometheus metrics and external uptime monitoring: - **Langfuse (native v3 SDK)** — LLM-shaped t | talos/libs/aegra-api/src/aegra_api/observability/__init__.py, talos/libs/aegra-api/src/aegra_api/observability/setup.py, talos/libs/aegra-api/src/aegra_api/observability/base.py, talos/libs/aegra-api/src/aegra_api/observability/langfuse_provider.py, talos/libs/aegra-api/src/aegra_api/observability/langfuse_client.py, talos/libs/aegra-api/src/aegra_api/observability/otel.py, talos/libs/aegra-api/src/aegra_api/observability/metrics.py, talos/libs/aegra-api/src/aegra_api/observability/span_enrichment.py, talos/libs/aegra-api/src/aegra_api/observability/targets |
-| [react_agent — LangGraph ReAct Agent with Plan, BLP, MCP, Canvas](features/react-agent.md) | `react_agent` is the **reference LangGraph agent** shipped under `examples/react_agent/`. | talos/examples/react_agent/graph.py, talos/examples/react_agent/state.py, talos/examples/react_agent/context.py, talos/examples/react_agent/prompts.py, talos/examples/react_agent/tool_router.py, talos/examples/react_agent/model_helpers.py, talos/examples/react_agent/config/context.py, talos/examples/react_agent/config/model_config.py, talos/examples/react_agent/config/tool_config.py, talos/examples/react_agent/config/plan_config.py, talos/examples/react_agent/config/memory_config.py, talos/examples/react_agent/config/mcp_config.py, talos/examples/react_agent/config/blp_config.py, talos/examples/react_agent/config/interrupt_config.py, talos/examples/react_agent/config/artifact_config.py, talos/examples/react_agent/plan/planner.py, talos/examples/react_agent/plan/nodes.py, talos/examples/react_agent/llm/system_prompt.py, talos/examples/react_agent/llm/tool_binding.py, talos/examples/react_agent/llm/message_ops.py, talos/examples/react_agent/mcp/client.py, talos/examples/react_agent/mcp/security.py, talos/examples/react_agent/mcp/session_manager.py, talos/examples/react_agent/blp/registry.py, talos/examples/react_agent/blp/embedder.py, talos/examples/react_agent/blp/nodes.py, talos/examples/react_agent/tools/__init__.py, talos/examples/react_agent/tools/code_interpreter.py, talos/examples/react_agent/tools/canvas.py, talos/examples/react_agent/tools/knowledge_base.py, talos/examples/react_agent/tools/skill_injector.py, talos/examples/react_agent/thread_name/nodes.py |
+| [talos_agent — LangGraph ReAct Agent with Plan, BLP, MCP, Canvas](features/talos-agent.md) | `talos_agent` is the **reference LangGraph agent** shipped under `agents/talos_agent/`. | talos/agents/talos_agent/graph.py, talos/agents/talos_agent/state.py, talos/agents/talos_agent/context.py, talos/agents/talos_agent/prompts.py, talos/agents/talos_agent/tool_router.py, talos/agents/talos_agent/model_helpers.py, talos/agents/talos_agent/config/context.py, talos/agents/talos_agent/config/model_config.py, talos/agents/talos_agent/config/tool_config.py, talos/agents/talos_agent/config/plan_config.py, talos/agents/talos_agent/config/memory_config.py, talos/agents/talos_agent/config/mcp_config.py, talos/agents/talos_agent/config/blp_config.py, talos/agents/talos_agent/config/interrupt_config.py, talos/agents/talos_agent/config/artifact_config.py, talos/agents/talos_agent/plan/planner.py, talos/agents/talos_agent/plan/nodes.py, talos/agents/talos_agent/llm/system_prompt.py, talos/agents/talos_agent/llm/tool_binding.py, talos/agents/talos_agent/llm/message_ops.py, talos/agents/talos_agent/mcp/client.py, talos/agents/talos_agent/mcp/security.py, talos/agents/talos_agent/mcp/session_manager.py, talos/agents/talos_agent/blp/registry.py, talos/agents/talos_agent/blp/embedder.py, talos/agents/talos_agent/blp/nodes.py, talos/agents/talos_agent/tools/__init__.py, talos/agents/talos_agent/tools/code_interpreter.py, talos/agents/talos_agent/tools/canvas.py, talos/agents/talos_agent/tools/knowledge_base.py, talos/agents/talos_agent/tools/skill_injector.py, talos/agents/talos_agent/thread_name/nodes.py |

package/knowledge/2.0/apps/talos/architecture.md

@@ -19,12 +19,12 @@ files:
   - talos/libs/aegra-api/src/aegra_api/services/langgraph_service.py
   - talos/libs/aegra-api/src/aegra_api/services/graph_factory.py
   - talos/libs/aegra-api/src/aegra_api/services/streaming_service.py
-  - talos/examples/react_agent/graph.py
+  - talos/agents/talos_agent/graph.py
   - talos/docker-compose.yml
   - talos/deployments/docker/Dockerfile
 related:
   - features/aegra-api.md
-  - features/react-agent.md
+  - features/talos-agent.md
   - features/mcp-servers.md
   - features/observability.md
   - features/deployment.md
@@ -56,7 +56,7 @@ talos/
 │   │   ├── observability/ # Langfuse native + OTEL providers, Prometheus
 │   │   └── main.py        # FastAPI app factory + lifespan
 │   └── alembic/           # 20 schema migrations (Jan 2025 → Mar 2026)
-├── examples/react_agent/  # Reference LangGraph agent (graph, plan, tools, blp, mcp)
+├── agents/talos_agent/  # Reference LangGraph agent (graph, plan, tools, blp, mcp)
 ├── mcp-servers/
 │   ├── clickup-mcp/       # ClickUp HTTP MCP (PM2-managed, ports 8200/8201)
 │   └── toga-db-mcp/       # Multi-cluster MySQL read MCP (port 8000)
@@ -75,10 +75,10 @@ talos/
    Redis BLPOP worker queue with lease-based crash recovery. SSE replay is
    backed by an in-memory ring + Postgres `run_events` table. See
    `features/aegra-api.md`.
-3. **Reference agent (LangGraph)** — `examples/react_agent`. A ReAct graph with
+3. **Reference agent (LangGraph)** — `agents/talos_agent`. A ReAct graph with
    optional planner gate, tool router, BLP semantic context selection,
    running-summary memory, canvas artifacts, code-interpreter offload, and MCP
-   passthrough. See `features/react-agent.md`.
+   passthrough. See `features/talos-agent.md`.
 4. **MCP fleet** — `clickup-mcp` and `toga-db-mcp`. Both FastMCP servers
    exposed over HTTP, API-key gated, PM2-managed, with OneUptime heartbeats.
    `toga-db-mcp` is the canonical read-only data plane across 4 prod clusters

package/knowledge/2.0/apps/talos/features/mcp-servers.md

@@ -21,7 +21,7 @@ files:
   - talos/mcp-servers/toga-db-mcp/.env.example
 related:
   - ../architecture.md
-  - react-agent.md
+  - talos-agent.md
   - deployment.md
 ---
 
@@ -36,7 +36,7 @@ PM2 process management:
   legacy, and 16 non-prod environments. The **canonical** path for the agent
   to read TOGa data.
 
-Both are consumed by the `react_agent` via the standard MCP loader and by
+Both are consumed by the `talos_agent` via the standard MCP loader and by
 external clients (Claude Desktop, internal tooling) via API-key auth.
 
 ## Key files / entry points

package/knowledge/2.0/apps/talos/features/{react-agent.md → talos-agent.md}

@@ -1,5 +1,5 @@
 ---
-title: react_agent — LangGraph ReAct Agent with Plan, BLP, MCP, Canvas
+title: talos_agent — LangGraph ReAct Agent with Plan, BLP, MCP, Canvas
 framework: "2.0"
 repo: talos
 project: TOGa IQ
@@ -9,38 +9,38 @@ status: active
 updated: 2026-06-16
 owners: [akhokhani]
 files:
-  - talos/examples/react_agent/graph.py
-  - talos/examples/react_agent/state.py
-  - talos/examples/react_agent/context.py
-  - talos/examples/react_agent/prompts.py
-  - talos/examples/react_agent/tool_router.py
-  - talos/examples/react_agent/model_helpers.py
-  - talos/examples/react_agent/config/context.py
-  - talos/examples/react_agent/config/model_config.py
-  - talos/examples/react_agent/config/tool_config.py
-  - talos/examples/react_agent/config/plan_config.py
-  - talos/examples/react_agent/config/memory_config.py
-  - talos/examples/react_agent/config/mcp_config.py
-  - talos/examples/react_agent/config/blp_config.py
-  - talos/examples/react_agent/config/interrupt_config.py
-  - talos/examples/react_agent/config/artifact_config.py
-  - talos/examples/react_agent/plan/planner.py
-  - talos/examples/react_agent/plan/nodes.py
-  - talos/examples/react_agent/llm/system_prompt.py
-  - talos/examples/react_agent/llm/tool_binding.py
-  - talos/examples/react_agent/llm/message_ops.py
-  - talos/examples/react_agent/mcp/client.py
-  - talos/examples/react_agent/mcp/security.py
-  - talos/examples/react_agent/mcp/session_manager.py
-  - talos/examples/react_agent/blp/registry.py
-  - talos/examples/react_agent/blp/embedder.py
-  - talos/examples/react_agent/blp/nodes.py
-  - talos/examples/react_agent/tools/__init__.py
-  - talos/examples/react_agent/tools/code_interpreter.py
-  - talos/examples/react_agent/tools/canvas.py
-  - talos/examples/react_agent/tools/knowledge_base.py
-  - talos/examples/react_agent/tools/skill_injector.py
-  - talos/examples/react_agent/thread_name/nodes.py
+  - talos/agents/talos_agent/graph.py
+  - talos/agents/talos_agent/state.py
+  - talos/agents/talos_agent/context.py
+  - talos/agents/talos_agent/prompts.py
+  - talos/agents/talos_agent/tool_router.py
+  - talos/agents/talos_agent/model_helpers.py
+  - talos/agents/talos_agent/config/context.py
+  - talos/agents/talos_agent/config/model_config.py
+  - talos/agents/talos_agent/config/tool_config.py
+  - talos/agents/talos_agent/config/plan_config.py
+  - talos/agents/talos_agent/config/memory_config.py
+  - talos/agents/talos_agent/config/mcp_config.py
+  - talos/agents/talos_agent/config/blp_config.py
+  - talos/agents/talos_agent/config/interrupt_config.py
+  - talos/agents/talos_agent/config/artifact_config.py
+  - talos/agents/talos_agent/plan/planner.py
+  - talos/agents/talos_agent/plan/nodes.py
+  - talos/agents/talos_agent/llm/system_prompt.py
+  - talos/agents/talos_agent/llm/tool_binding.py
+  - talos/agents/talos_agent/llm/message_ops.py
+  - talos/agents/talos_agent/mcp/client.py
+  - talos/agents/talos_agent/mcp/security.py
+  - talos/agents/talos_agent/mcp/session_manager.py
+  - talos/agents/talos_agent/blp/registry.py
+  - talos/agents/talos_agent/blp/embedder.py
+  - talos/agents/talos_agent/blp/nodes.py
+  - talos/agents/talos_agent/tools/__init__.py
+  - talos/agents/talos_agent/tools/code_interpreter.py
+  - talos/agents/talos_agent/tools/canvas.py
+  - talos/agents/talos_agent/tools/knowledge_base.py
+  - talos/agents/talos_agent/tools/skill_injector.py
+  - talos/agents/talos_agent/thread_name/nodes.py
 related:
   - ../architecture.md
   - aegra-api.md
@@ -49,8 +49,8 @@ related:
 
 ## Summary
 
-`react_agent` is the **reference LangGraph agent** shipped under
-`examples/react_agent/`. It is a production-grade ReAct loop with an optional
+`talos_agent` is the **reference LangGraph agent** shipped under
+`agents/talos_agent/`. It is a production-grade ReAct loop with an optional
 **planner** gate, an LLM-driven **tool router**, **BLP** semantic context
 selection, running-summary memory compaction, a versioned **canvas** artifact,
 **code-interpreter** offload (Bedrock AgentCore), and transparent **MCP**
@@ -202,4 +202,5 @@ Add a client override by configuring its assistant, not by forking the graph.
   recursion limit. Raise the limit in graph build before raising expectations.
 
 ## Change history
-- 2026-06-16 — Initial react_agent feature doc. (akhokhani)
+- 2026-06-16 — Renamed `examples/react_agent/` → `agents/talos_agent/`; sibling example dirs (`react_agent_hitl`, `subgraph_agent`, `subgraph_hitl_agent`) and example scripts removed. `aegra.json` now points `dependencies: ["./agents"]`; graph entry is `./agents/talos_agent/graph.py:graph`. Module import is `from talos_agent.graph import graph`. (akhokhani)
+- 2026-06-16 — Initial feature doc. (akhokhani)

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)