toga-ai 1.0.89 → 1.0.90

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

@@ -0,0 +1,10 @@
+# talos (TOGa IQ) — 2.0 knowledge
+
+| 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 |
+| [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 |

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

@@ -0,0 +1,169 @@
+---
+title: TOGa IQ (talos) Architecture
+framework: "2.0"
+repo: talos
+project: TOGa IQ
+client: shared
+type: architecture
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - 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
+related:
+  - features/aegra-api.md
+  - features/react-agent.md
+  - features/mcp-servers.md
+  - features/observability.md
+  - features/deployment.md
+---
+
+## Summary
+
+**TOGa IQ** is TOGA Technology's AI agent platform. The on-disk repo is **`talos`**
+(the "talos backend"). It is a Python/FastAPI implementation of the **Agent Protocol**
+spec, multi-tenant, with a LangGraph **ReAct agent** as the reference agent and a
+fleet of internal **MCP servers** for ClickUp and the TOGa MySQL clusters.
+
+Unlike the PHP 2.0 apps (`_underscore`, `api2`, `worker2`), TOGa IQ has **no PHP
+dependency** — it is a self-contained Python product that consumes TOGa data
+read-only via the `toga-db-mcp` server. It lives under `2.0/apps/talos/` because
+its consumers are 2.0-era TOGa apps (TOGa Hub, TOGa View) and TogaHub auth.
+
+## Top-level layout
+
+```
+talos/
+├── libs/aegra-api/        # FastAPI server (Agent Protocol)
+│   ├── src/aegra_api/
+│   │   ├── api/           # ~40 route modules (assistants, threads, runs, …)
+│   │   ├── core/          # auth, db, tenant routing, redis, encryption
+│   │   ├── services/      # broker, executor, langgraph, streaming, event store
+│   │   ├── middleware/    # logger, correlation id, rate limit, content-type
+│   │   ├── models/        # Pydantic schemas (one file per API group)
+│   │   ├── 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)
+├── mcp-servers/
+│   ├── clickup-mcp/       # ClickUp HTTP MCP (PM2-managed, ports 8200/8201)
+│   └── toga-db-mcp/       # Multi-cluster MySQL read MCP (port 8000)
+├── deployments/docker/    # Dockerfile + entrypoint.sh
+└── docker-compose.yml     # Single `aegra` service (external PG + Redis)
+```
+
+## Five subsystems
+
+1. **HTTP / Agent Protocol** — `libs/aegra-api`. FastAPI app exposes ~40 routers
+   covering Assistants, Threads, Runs, Crons, Store, Files/Folders, Knowledge
+   Bases, MCP, Sandboxes, Teams, BLP, admin/tenants. Pluggable auth via
+   `AUTH_TYPE` ∈ {`togahub`, `entra`, `noop`}. See `features/aegra-api.md`.
+2. **Execution pipeline** — Broker → Executor → LangGraph → Streaming. Local
+   mode uses an in-memory queue + asyncio. Prod uses a Redis pub/sub broker +
+   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
+   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`.
+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
+   + legacy + 16 non-prod environments (see `clusters.yaml`). See
+   `features/mcp-servers.md`.
+5. **Observability** — Langfuse (native v3 SDK) for LLM traces, OTEL (Phoenix /
+   Langfuse OTLP / generic OTLP / console) for spans, optional Prometheus
+   `/metrics`, plus OneUptime for uptime + heartbeats on MCP servers. See
+   `features/observability.md`.
+
+## Multi-tenancy
+
+A **control plane DB** (`core/control_plane_db.py`, `control_plane_orm.py`) holds
+the organization → tenant-DB mapping. `core/tenant_router.py` keeps an LRU
+cache (max 100) of per-tenant `DatabaseManager` instances keyed by `org_id`.
+Requests without a registered tenant return HTTP 403; tenant provisioning is
+explicit (no auto-create). When `CONTROL_PLANE_DATABASE_URL` is unset the
+service operates in **zero-overhead single-DB mode**.
+
+At startup the lifespan handler migrates every registered tenant DB and seeds
+base infrastructure before the health-check loop opens — slow first boot but
+guarantees readiness.
+
+## Auth
+
+`AUTH_TYPE` selects the backend:
+
+- **togahub** — validates JWTs against TogaHub (`core/togahub_auth.py`).
+- **entra** — Microsoft Entra ID JWT validation (`core/entra_auth.py`).
+- **noop** — local-dev bypass; **never** ship to prod.
+
+Auth is implemented as a FastAPI **dependency** (`require_auth` in
+`core/auth_deps.py`), not middleware — so OpenAPI sees `401` correctly and
+public routes (`/health`, `/ready`, `/live`, `/info`, `/docs`) cleanly skip it.
+API-key auth (`core/api_key_auth.py`) supplements user auth for service-to-service.
+
+## Run lifecycle (mental model)
+
+A client POSTs to `/threads/{id}/runs` (or stateless `/runs`). `run_preparation`
+materializes the run, the **broker** publishes a `run_created` event, the
+**executor** (local or worker) picks it up, `run_executor.py` calls
+`langgraph_service` to compile the graph for this tenant/assistant, streams
+events through `graph_streaming.py` into the broker, and the streaming endpoint
+(`streaming_service.py`) replays from the broker buffer + Postgres event store
+to the SSE consumer with 15s keepalive comments. Interrupts (HITL) surface as
+`interrupt` events; resume re-enters via `Command(resume=…)`.
+
+## Storage
+
+- **Postgres** (with `pgvector`) — primary store: assistants, threads, runs,
+  checkpoints, `run_events`, `store` namespace KV + embeddings, knowledge bases.
+- **Redis** — broker pub/sub + replay buffer, worker BLPOP queue, sequence
+  counters, optional rate-limit windows.
+- **S3** — file uploads (presigned URL flow via `api/files.py`).
+- **Bedrock AgentCore sandbox** — code-interpreter session + large-output offload.
+
+## Encryption
+
+A single global `MCP_ENCRYPTION_KEY` (Fernet) encrypts MCP server headers
+before DB storage (`core/encryption.py` → `encrypt_headers` / `decrypt_headers`).
+**Not per-tenant** — all tenants share one key. Document *where* a credential
+lives (env var name, config key) but never the value itself.
+
+## Deployment
+
+- **Container** — multi-stage `python:3.11-slim-bookworm` build with `uv`,
+  WeasyPrint runtime deps for HTML→PDF. Non-root `app:app`.
+- **Entrypoint** — loads `.env.${ENV_NAME}` then runs
+  `alembic upgrade head && uvicorn aegra_api.main:app --host 0.0.0.0 --port 8000 --workers 2`.
+- **Compose** — single `aegra` service; **PostgreSQL and Redis are
+  user-managed** (external). Health check hits `/live`. See
+  `features/deployment.md`.
+
+## Key decisions
+
+- **Agent Protocol over a custom shape** — clients (TOGa Hub, TOGa View, third-party)
+  share one wire format; LangGraph Studio works out of the box.
+- **Pluggable executors** — `LocalExecutor` for dev/CI, `WorkerExecutor` with
+  Redis lease + reaper for prod horizontal scaling.
+- **Native Langfuse + OTEL side-by-side** — Langfuse for LLM-shaped traces
+  (token/cost), OTEL for everything else; the OTEL Langfuse target is skipped
+  when native mode is on to avoid duplicate spans.
+- **MCP for data access** — `toga-db-mcp` is the *only* sanctioned path into
+  TOGa MySQL for the agent; query enforcement (read-only, LIMIT 1–1000) lives
+  inside the MCP, not the agent.
+
+## Change history
+- 2026-06-16 — Initial architecture doc for talos / TOGa IQ under 2.0/apps. (akhokhani)

package/knowledge/2.0/apps/talos/features/aegra-api.md

@@ -0,0 +1,206 @@
+---
+title: aegra-api — Agent Protocol HTTP + Execution Pipeline
+framework: "2.0"
+repo: talos
+project: TOGa IQ
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - 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
+related:
+  - ../architecture.md
+  - mcp-servers.md
+  - observability.md
+---
+
+## Summary
+
+`aegra-api` is the **FastAPI Agent Protocol server** at the heart of TOGa IQ. It
+exposes ~40 routers, runs LangGraph agents per-tenant, streams SSE events with
+replay, and persists checkpoints + runs in Postgres (+ pgvector for the `store`
+namespace).
+
+## Key files / entry points
+
+| File | Purpose |
+|---|---|
+| `main.py` | App factory `create_app()`; lifespan: migrations → DB → control-plane → Redis → broker/executor/lease-reaper → cron scheduler → seed → health |
+| `settings.py` | Env-derived config (DB URL, Redis URL, AUTH_TYPE, observability toggles) |
+| `config.py` | Loads `aegra.json` / `langgraph.json` — graph factory paths, CORS, custom apps |
+| `core/auth_middleware.py` + `core/auth_deps.py` | Pluggable auth backend (togahub / entra / noop) + `require_auth` FastAPI dependency |
+| `core/tenant_router.py` | LRU pool (≤100) of per-tenant `DatabaseManager`s keyed by `org_id` |
+| `core/control_plane_db.py` | Org/tenant registry (separate DB; `create_all` — no Alembic) |
+| `services/broker.py` / `redis_broker.py` | In-memory vs Redis pub/sub broker with replay buffer |
+| `services/executor.py` | Factory: `LocalExecutor` (asyncio) or `WorkerExecutor` (Redis BLPOP + lease) |
+| `services/run_executor.py` | Single source of truth for run lifecycle: stream → broker → status update |
+| `services/langgraph_service.py` | Compiles the graph for this tenant/assistant with checkpointer + store injected |
+| `services/graph_factory.py` | Inspects 0–2-param factory signatures and invokes with coerced `ServerRuntime[T]` |
+| `services/streaming_service.py` | SSE replay loop with 15s keepalive + 30-min wall-clock deadline |
+| `services/event_store.py` | Postgres-backed `run_events` table (sequence-numbered) for persistent replay |
+
+## How it works
+
+### 1 — Bootstrap
+
+`create_app()` in `main.py` (~line 579):
+
+1. Instantiates `FastAPI(...)` with tags for Assistants / Threads / Runs / Crons / Store / Health.
+2. Optional **custom apps** mounted from `aegra.json` config (`main.py:590`).
+3. Registers ~35 routers (`main.py:536–575`). All routers attach
+   `dependencies=auth_dependency` except `health` and `admin_ui`.
+4. Middleware stack (outer → inner): `ContentTypeFixMiddleware` → `CORSMiddleware`
+   → `CorrelationIdMiddleware` (asgi-correlation-id) → `StructLogMiddleware`.
+5. Optional `RateLimiterMiddleware` (Redis sliding window with Lua; falls back
+   to in-memory; exempts `/health`, `/ready`, `/live`, `/info`, `/docs`, `/redoc`).
+6. Lifespan (`main.py:146–327`): Alembic migrate → DB init → control-plane init →
+   Redis → broker/executor/lease-reaper → cron scheduler → base seeding →
+   health-check loop. Shutdown is reverse order.
+
+### 2 — Route surface
+
+| Cluster | Routers |
+|---|---|
+| Agents/Assistants | `assistants`, `assistant_config`, `model_presets` |
+| Threads & Runs | `threads`, `runs`, `stateless_runs`, `thread_forks` |
+| Async | `crons` |
+| Persistence | `store` (pgvector-backed namespace KV + semantic search) |
+| Knowledge/Files | `knowledge_bases`, `files`, `folders` |
+| MCP | `mcp`, `mcp_servers` |
+| Sandbox | `sandbox_configs`, `sandbox_sessions`, `sandbox_artifacts`, `code_interpreters` |
+| Admin/Ops | `admin_ui`, `tenants`, `system_config`, `tours`, `export` |
+| Collaboration | `chat_shares`, `group_chat`, `group_events`, `message_feedback` |
+| AI helpers | `ai_chat`, `ai_generate` |
+| Integrations | `teams`, `blp`, `api_keys` |
+
+### 3 — Auth
+
+`AUTH_TYPE` selects the backend: **togahub** (TogaHub JWTs via
+`core/togahub_auth.py`) / **entra** (Microsoft Entra ID via `core/entra_auth.py`)
+/ **noop** (dev only). `require_auth` in `auth_deps.py` injects a `User` with
+`org_id` (default `"default"`). Public routes skip auth: `/health`, `/ready`,
+`/live`, `/info`, `/docs`, `/openapi.json`.
+
+### 4 — Multi-tenancy
+
+When `CONTROL_PLANE_DATABASE_URL` is set, a `default` tenant is auto-registered,
+every registered tenant DB is migrated/seeded inside the lifespan, and
+`tenant_router.get_db_manager(org_id)` returns or creates the per-tenant
+`DatabaseManager` (LRU eviction at 100). Missing org → HTTP 403. Single-DB mode
+(no control plane) uses the global `db_manager` singleton with zero overhead.
+
+### 5 — Run / execution pipeline
+
+```
+POST /threads/{id}/runs
+   → run_preparation creates the Run row
+   → broker.publish("run_created")
+   → executor picks up
+       LocalExecutor → asyncio task in-process
+       WorkerExecutor → Redis BLPOP, lease + heartbeat, reaper re-enqueues on crash
+   → run_executor.execute():
+        langgraph_service.compile(tenant, assistant)
+        graph_streaming.stream(graph, input) → broker
+        update run status (running → success/error/interrupted)
+   → streaming_service.stream(run_id) replays broker buffer + event_store
+      to SSE consumer (15s keepalive comments; 30-min default deadline)
+```
+
+### 6 — Event replay (dual storage)
+
+- **Broker buffer** — last ~10k events per run in memory (TTL auto-evict in
+  Redis mode). Cheap reconnect.
+- **`event_store` Postgres table** — sequence-numbered persistent log for
+  longer-window replay or post-hoc analysis.
+
+### 7 — Graph factory
+
+`graph_factory.classify_factory()` inspects the factory's signature (0, 1, or 2
+params; either order) and registers a dispatch hook. `invoke_factory()` builds
+a `ServerRuntime[T]` from the per-request context and invokes the factory.
+Base graphs are cached; factory graphs rebuild fresh with checkpointer/store
+injected — thread-safe by construction (no locks).
+
+### 8 — Alembic
+
+`alembic/env.py` reads the URL via `config.attributes` (not the configparser
+section) to dodge ConfigParser's `%`-interpolation choking on password
+characters. 20 migrations to date (Jan 2025 → Mar 2026): initial schema, run
+status transitions, performance indexes, sandbox configs, normalized config
+tables.
+
+### 9 — Redis usage
+
+`core/redis_manager.py` is a singleton with connection pooling. Roles: broker
+pub/sub + replay (Redis Lists, ~10-min TTL); worker BLPOP queue; sequence
+counters (`INCR` for cross-instance ordering); rate-limit windows (optional).
+Disable via `REDIS_BROKER_ENABLED=false` for pure local mode.
+
+### 10 — Notable middleware
+
+- **`ContentTypeFixMiddleware`** — rewrites `text/plain` → `application/json`
+  on POST/PUT/PATCH so LangGraph Studio's quirky client works.
+- **`RateLimiterMiddleware`** — Redis sliding window with Lua atomicity; falls
+  back to in-memory if Redis is offline.
+- **`StructLogMiddleware`** — structured logs with correlation IDs (status,
+  method, duration, client IP).
+
+## Data model
+
+Primary tables (Postgres): `assistants`, `assistant_versions`,
+`assistant_configs`, `model_presets`; `threads`, `thread_forks`, `runs`,
+`run_events` (sequenced), `crons`; `store` (pgvector embeddings + namespace KV);
+`knowledge_bases`, `files`, `folders`; `mcp_servers` (Fernet-encrypted headers);
+`sandbox_configs`, `sandbox_sessions`, `sandbox_artifacts`. Control-plane DB:
+`organizations`, `tenants`.
+
+## Client variations
+
+None — uniform across clients. Per-tenant data isolation is enforced by
+`tenant_router`, not at the client level.
+
+## Gotchas / known issues
+
+- **First boot is slow** — lifespan migrates every registered tenant DB before
+  opening the health-check loop. Plan for >30s startup with many tenants.
+- **`MCP_ENCRYPTION_KEY` is global**, not per-tenant. Rotating it requires
+  decrypt-then-re-encrypt for all `mcp_servers` rows.
+- **`noop` AUTH_TYPE leaks everything** — never deploy with it set.
+- **LangGraph Studio sends `text/plain`** — relying on `ContentTypeFixMiddleware`.
+  Removing that middleware breaks Studio.
+- **Alembic password chars** — keep the `config.attributes` URL passing pattern
+  in `env.py`; configparser interpolation will mangle `%` in passwords.
+
+## Change history
+- 2026-06-16 — Initial aegra-api feature doc (HTTP layer + execution pipeline). (akhokhani)

package/knowledge/2.0/apps/talos/features/deployment.md

@@ -0,0 +1,115 @@
+---
+title: Deployment — Docker, Compose, Entrypoint, External PG/Redis
+framework: "2.0"
+repo: talos
+project: TOGa IQ
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - talos/docker-compose.yml
+  - talos/deployments/docker/Dockerfile
+  - talos/deployments/docker/entrypoint.sh
+related:
+  - ../architecture.md
+  - aegra-api.md
+  - mcp-servers.md
+  - observability.md
+---
+
+## Summary
+
+TOGa IQ ships as a **single container** (`aegra` service) wrapping the
+`aegra-api` FastAPI server. Postgres + Redis are **user-managed externally**
+(not in compose). Migrations run on every container start. MCP servers ship
+separately and are PM2-managed (see `mcp-servers.md`).
+
+## Key files / entry points
+
+| File | Purpose |
+|---|---|
+| `docker-compose.yml` | Single `aegra` service, env-file driven, resource limits, health check on `/live` |
+| `deployments/docker/Dockerfile` | Multi-stage build: `python:3.11-slim-bookworm` + `uv`, lean runtime image, non-root user |
+| `deployments/docker/entrypoint.sh` | Loads `.env.${ENV_NAME}` then runs `alembic upgrade head && uvicorn aegra_api.main:app ...` |
+
+## How it works
+
+### Dockerfile — multi-stage
+
+**Builder stage:**
+
+- Base: `python:3.11-slim-bookworm`.
+- Installs `uv` (v0.9.26) + build deps (`libpq-dev`, `build-essential`).
+- Freezes deps from `uv.lock` and **exports the `aegra-api` package only**
+  (no dev deps).
+- Pre-compiles bytecode for faster cold start.
+
+**Final stage:**
+
+- Lightweight runtime base (no build tools).
+- Installs runtime libs: `ca-certificates`, `libglib2.0`, `libpango`,
+  `libcairo` (for WeasyPrint HTML→PDF).
+- Copies pre-built wheels + assets: `alembic.ini`, migrations, skills,
+  examples, BLP models.
+- Copies fallback env files: `.env.prod`, `.env.beta`.
+- **Entrypoint:** `/app/entrypoint.sh`.
+- **Default CMD:** `alembic upgrade head && uvicorn aegra_api.main:app
+  --host 0.0.0.0 --port 8000 --workers 2`
+- **Security:** runs as non-root `app:app`; `rwx` only on
+  `/app/{examples,alembic,skills,blp}`.
+
+### entrypoint.sh
+
+Loads `.env.${ENV_NAME}` if present; falls back to vars already set in the
+process environment. Then `exec`s the CMD. Migration on every start is
+intentional — keeps containers self-healing on schema drift.
+
+### docker-compose.yml
+
+Single `aegra` service:
+
+- **Ports:** `${PORT:-8000}:${PORT:-8000}` (overrideable).
+- **Env file:** `.env.prod` (default) or `${ENV_FILE}`.
+- **Resources:** limits `4 CPU / 4 GiB`; reservations `1 CPU / 1 GiB`.
+- **Health check:** `GET /live` every 30 s, 3 retries, 40 s start grace.
+- **Restart policy:** `unless-stopped`.
+- **External deps (user-managed, not in compose):**
+  - PostgreSQL with `pgvector` (primary DB + control-plane DB).
+  - Redis (broker / worker queue / rate limit).
+- **Volumes:** none in compose; persistence lives on external PG/Redis.
+
+## Data model
+
+No new schema introduced by deployment. `alembic upgrade head` reconciles
+the existing schema; control-plane DB uses `create_all` (idempotent).
+
+## Client variations
+
+`.env.${ENV_NAME}` is the per-environment seam:
+
+- `.env.prod` — production.
+- `.env.beta` — beta / staging.
+- Any `.env.<name>` works — entrypoint loads by `ENV_NAME`.
+
+Clients themselves are tenants inside one deployment, not separate compose
+stacks (see `aegra-api.md` §4 multi-tenancy).
+
+## Gotchas / known issues
+
+- **External PG / Redis are NOT in compose.** Set the URLs in `.env.${ENV_NAME}`
+  *before* `docker compose up` or migrations crash the container into a
+  restart loop.
+- **Migrations on every start** — long migrations delay first-request
+  readiness. The compose `start_period: 40 s` is a generous default; raise
+  it if rolling out a heavy migration.
+- **WeasyPrint libs are runtime, not build, deps** — removing them shrinks
+  the image but breaks any HTML→PDF feature (PDF tools / canvas exports).
+- **`--workers 2`** is the default. Set `WORKERS=N` to override. Multi-worker
+  + `LocalExecutor` is fine; multi-worker + `WorkerExecutor` requires Redis.
+- **Image must be non-root.** Some legacy code paths assumed root file
+  ownership; fix the code path, don't chown back to root.
+
+## Change history
+- 2026-06-16 — Initial deployment feature doc. (akhokhani)

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

@@ -0,0 +1,142 @@
+---
+title: MCP Servers — clickup-mcp and toga-db-mcp
+framework: "2.0"
+repo: talos
+project: TOGa IQ
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - 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
+related:
+  - ../architecture.md
+  - react-agent.md
+  - deployment.md
+---
+
+## Summary
+
+Two internal **FastMCP** servers exposed over **HTTP** with API-key auth and
+PM2 process management:
+
+- **`clickup-mcp`** — ClickUp workspace surface (spaces / folders / lists /
+  tasks / comments / attachments) with allowlist-scoped access.
+- **`toga-db-mcp`** — Read-only multi-cluster MySQL access across TOGa's prod,
+  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
+external clients (Claude Desktop, internal tooling) via API-key auth.
+
+## Key files / entry points
+
+| Server | File | Purpose |
+|---|---|---|
+| clickup-mcp | `src/clickup_mcp/server.py` | FastMCP app, Starlette + APIKeyMiddleware |
+| clickup-mcp | `ecosystem.config.js` | PM2 prod + dev instances (ports 8200, 8201) |
+| toga-db-mcp | `src/toga_db_mcp/server.py` | FastMCP app, AuthMiddleware (X-API-Key) |
+| toga-db-mcp | `clusters.yaml` | Cluster ↔ environment ↔ schema-group map (22 envs) |
+| toga-db-mcp | `src/toga_db_mcp/pool.py` | aiomysql lazy per-cluster async pools |
+
+## How it works
+
+### clickup-mcp
+
+- **Transport:** HTTP (Uvicorn). Ports **8200 prod**, **8201 dev**.
+- **Auth:** `X-API-Key` validated by `APIKeyMiddleware`.
+- **Tools (18):**
+  - `clickup_discover_hierarchy` — scans workspace tree to enumerate IDs for
+    allowlist config (the only unrestricted tool).
+  - `clickup_list_teams`
+  - `clickup_list_spaces`, `clickup_list_folders`, `clickup_list_lists` —
+    filtered by `ALLOWED_SPACE_IDS`, `ALLOWED_FOLDER_IDS`, `ALLOWED_LIST_IDS`.
+  - `clickup_list_tasks`, `clickup_get_task`, `clickup_create_task`,
+    `clickup_update_task` — guarded by list-membership check.
+  - `clickup_list_comments`, `clickup_create_comment`,
+    `clickup_upload_attachment`.
+- **PM2:** 2 instances (prod, dev) with `max_memory_restart: 500M`,
+  `restart_delay: 5000`, `max_restarts: 10`, 30 s request timeout.
+- **Observability:** OneUptime heartbeat + incident open on 2 consecutive
+  ClickUp API health-check failures (60 s interval).
+
+### toga-db-mcp
+
+- **Transport:** HTTP (Uvicorn). Port **8000**.
+- **Auth:** `X-API-Key`; optional soft User-Agent filter for claude.ai-only
+  dev mode.
+- **Multi-cluster topology (`clusters.yaml`):**
+  - **Prod (4 dedicated clusters):**
+    - `prod-core` → platform schemas (Core, Forecast, Team) — authoritative
+      client lookup.
+    - `prod-client` → `Client_<Name>` (active per-client data).
+    - `prod-archive` → `Archive_<Name>` (historical snapshots, separate host).
+    - `prod-logs` → Logs + `Logs_<Name>` (activity / transaction logs).
+  - **Legacy (1 all-in-one):** `TOGA_<Name>`, `TOGaLogs_<Name>`, `Vision*`,
+    `TOGaDesk*` schemas.
+  - **Non-Prod (16 envs, all-in-one):** dev-sandbox, client-sandbox,
+    client-alpha/beta/gamma, qa-*, qc-*, stage, demo — V2 naming throughout.
+- **Schema classification** (`clusters.yaml`): 8 groups — `platform`,
+  `tenants`, `archive`, `tenant_logs`, `support`, `vision`, `standalone`,
+  `system`. System schemas (`mysql`, `information_schema`, etc.) excluded.
+- **Tools (10, all read-only):**
+  - `toga_health` — pool status per cluster (connected/failed, free conns).
+  - `toga_list_environments` — 22 envs with aliases.
+  - `toga_list_clusters(env)` — clusters + schema groups serving an env.
+  - `toga_list_schemas(env, group?)` — case-sensitive schema names.
+  - `toga_list_tables(env, schema_name)` — tables + row counts.
+  - `toga_describe_table(env, schema_name, table_name)` — column metadata.
+  - `toga_search_tables(env, keyword)`, `toga_search_columns(env, keyword)`
+    — fuzzy lookup.
+  - `toga_query(env, schema_name, sql, limit=100)` — read-only with **LIMIT
+    enforcement (1–1000)**.
+  - `toga_sample_data(env, schema_name, table_name, limit)` — preview rows.
+- **Connection pool:** `aiomysql` async manager per cluster. Defaults
+  `min=1, max=5`. Lazy init on first tool call.
+- **PM2:** single instance, `max_memory_restart: 500M`, log files in
+  `/home/ubuntu/.pm2/logs/`, auto-restart enabled.
+- **Observability:** OneUptime heartbeat + per-cluster health monitoring
+  (60 s); incident on prod env only.
+
+## Data model
+
+`toga-db-mcp` is **read-only** by contract. No schema of its own — reads flow
+through the per-environment pool to MySQL clusters defined in `clusters.yaml`.
+`clickup-mcp` is a stateless thin wrapper over the ClickUp v2 REST API; no DB.
+
+## Client variations
+
+`toga-db-mcp`'s prod-vs-non-prod split is intentional: one MCP exposes 22
+environments; the agent picks via `env` parameter on every tool call.
+`clickup-mcp` is workspace-singular — different workspaces deploy separate PM2
+instances (separate ports + ALLOWED_* envs).
+
+## Gotchas / known issues
+
+- **Schema names are case-sensitive** in `toga-db-mcp` — must match MySQL
+  literal exactly. Pass a search tool result; don't hand-type.
+- **`toga_query` LIMIT clamp** silently truncates at 1000. If you need more,
+  page via WHERE/keyset — do not bypass.
+- **ClickUp allowlist must be explicit** — every list/folder/space ID enters
+  via env var. `clickup_discover_hierarchy` is the only way to enumerate them
+  on first setup; lock it down once the allowlist is populated.
+- **PM2 logs path is hard-coded** (`/home/ubuntu/.pm2/logs/`). On non-ubuntu
+  hosts override via `PM2_HOME` before `pm2 start`.
+- **API keys** are required everywhere — no anonymous mode. Lost key =
+  redeploy with a new key; no rotation endpoint.
+- **OneUptime heartbeats** open prod incidents on 2 consecutive failures —
+  add the heartbeat URL to `.env` before first start or you get false-positive
+  pages.
+
+## Change history
+- 2026-06-16 — Initial mcp-servers feature doc (clickup-mcp + toga-db-mcp). (akhokhani)

package/knowledge/2.0/apps/talos/features/observability.md

@@ -0,0 +1,132 @@
+---
+title: Observability — Langfuse, OTEL, Prometheus, OneUptime
+framework: "2.0"
+repo: talos
+project: TOGa IQ
+client: shared
+type: feature
+status: active
+updated: 2026-06-16
+owners: [akhokhani]
+files:
+  - 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
+related:
+  - ../architecture.md
+  - aegra-api.md
+  - mcp-servers.md
+---
+
+## Summary
+
+TOGa IQ uses **two complementary tracing planes** plus optional Prometheus
+metrics and external uptime monitoring:
+
+- **Langfuse (native v3 SDK)** — LLM-shaped traces with token counts, cost,
+  prompt linking. Best signal-to-noise for agent debugging.
+- **OpenTelemetry** — application + LangChain spans for everything else,
+  multi-target export (Phoenix, Langfuse OTLP, generic OTLP, console).
+- **Prometheus** (optional) — HTTP + Python runtime metrics on `/metrics`.
+- **OneUptime** — heartbeats + incident management for the MCP fleet.
+
+## Key files / entry points
+
+| File | Purpose |
+|---|---|
+| `observability/setup.py` | Registers OTEL + Langfuse native with the central `ObservabilityManager` and calls `setup()` |
+| `observability/base.py` | `ObservabilityManager` and provider interface |
+| `observability/langfuse_provider.py` | Native Langfuse v3 callback handler (enabled by `LANGFUSE_NATIVE_MODE=true`) |
+| `observability/langfuse_client.py` | Singleton client wrapping the SDK |
+| `observability/otel.py` | Global `TracerProvider` + `BatchSpanProcessor` + `LangChainInstrumentor` (OpenInference) |
+| `observability/metrics.py` | Prometheus exporter (`ENABLE_PROMETHEUS_METRICS=true`) |
+| `observability/span_enrichment.py` | Adds tenant / user / run attributes to spans |
+| `observability/targets/` | Exporter target adapters (Phoenix, Langfuse OTLP, generic OTLP, console) |
+
+## How it works
+
+### 1 — Setup ordering
+
+`setup.py` reads env and registers providers in order:
+
+1. `otel_provider.setup()` — global instrumentation if `OTEL_TARGETS` is set.
+2. `langfuse_provider` — native mode if `LANGFUSE_NATIVE_MODE=true` and creds
+   present.
+3. `metrics.install()` — Prometheus exporter mounted at `/metrics` if enabled.
+
+Active providers are logged on startup so a misconfigured environment is
+visible from the first log line.
+
+### 2 — Langfuse native
+
+`langfuse_provider.py` wires a `CallbackHandler` into every LangChain/LangGraph
+call. Token counts, cost, and prompt-linking come from the SDK. Enable
+conditions (all three required):
+
+- `LANGFUSE_NATIVE_MODE=true`
+- `LANGFUSE_PUBLIC_KEY` + `LANGFUSE_SECRET_KEY` set
+- `LANGFUSE` listed in `OTEL_TARGETS`
+
+LangChain `config` metadata (`user_id`, `session_id`, `tags`) is picked up
+automatically — attach it once and traces are filterable by it end-to-end.
+
+### 3 — OpenTelemetry
+
+`otel.py` builds a global `TracerProvider` with a `BatchSpanProcessor` and
+attaches `span_enrichment.enrich(span)` for tenant / user / run-id attribution.
+LangChain instrumentation is via OpenInference (`LangChainInstrumentor`).
+
+Multi-target export — set `OTEL_TARGETS` to a comma-separated list:
+
+- **PHOENIX** — live trace visualization at the Phoenix endpoint.
+- **LANGFUSE** — Langfuse OTLP. **Skipped** when native mode is on, to avoid
+  duplicate spans.
+- **GENERIC** — any OTLP endpoint (Jaeger, Tempo, etc.).
+- **CONSOLE** — debug printing if `OTEL_CONSOLE_EXPORT=true`.
+
+### 4 — Prometheus
+
+Optional. Enable with `ENABLE_PROMETHEUS_METRICS=true`. Exposes `/metrics` in
+Prometheus exposition format. Auto-excludes `/health`, `/ready`, `/live`,
+`/metrics`, `/docs`, `/openapi.json` from HTTP histograms.
+
+### 5 — OneUptime
+
+External — not in the codebase. Both MCP servers (clickup-mcp, toga-db-mcp)
+post heartbeats every 60 s; two consecutive failures open an incident.
+Configure via the heartbeat URL in each MCP's `.env`.
+
+## Data model
+
+No persistent storage in TOGa IQ itself — traces / spans / metrics ship to
+external systems (Langfuse, Phoenix, Prometheus pull, OneUptime).
+
+## Client variations
+
+None. Observability is global; per-tenant filtering is applied at query time
+in Langfuse / Phoenix via the `user_id` / `tenant` attributes attached by
+`span_enrichment.py`.
+
+## Gotchas / known issues
+
+- **Double-counted tokens** if both Langfuse native AND the OTEL-Langfuse
+  target are on. `otel.py` skips the Langfuse OTLP target when native mode is
+  on — do not undo this guard.
+- **`OTEL_TARGETS` is comma-separated** — extra whitespace silently disables a
+  target. Use `"PHOENIX,LANGFUSE"`, not `"PHOENIX, LANGFUSE"`.
+- **`/metrics` is unauthenticated** — never expose to the public internet.
+  Put it behind the VPC or an ALB-level auth rule.
+- **OneUptime heartbeats are required for MCP prod incidents.** Missing
+  heartbeat URL = no monitoring; a failing MCP is invisible until users
+  report it.
+- **Langfuse v3 SDK uses different env vars** than v2 — `LANGFUSE_HOST`,
+  not `LANGFUSE_BASE_URL`. Use v3 names.
+
+## Change history
+- 2026-06-16 — Initial observability feature doc. (akhokhani)

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

@@ -0,0 +1,205 @@
+---
+title: react_agent — LangGraph ReAct Agent with Plan, BLP, MCP, Canvas
+framework: "2.0"
+repo: talos
+project: TOGa IQ
+client: shared
+type: feature
+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
+related:
+  - ../architecture.md
+  - aegra-api.md
+  - mcp-servers.md
+---
+
+## Summary
+
+`react_agent` is the **reference LangGraph agent** shipped under
+`examples/react_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**
+passthrough with credential resolution and session keepalive.
+
+## Key files / entry points
+
+| Layer | File |
+|---|---|
+| Graph entry | `graph.py` (build_graph, route_model_output) |
+| State schema | `state.py` |
+| Per-run context | `context.py` |
+| System prompt | `llm/system_prompt.py` (BLP XML injection, prompt-cache anchor) |
+| Tool binding | `llm/tool_binding.py` |
+| Planner | `plan/planner.py` + `plan/nodes.py` |
+| Tool router | `tool_router.py` |
+| BLP | `blp/registry.py`, `blp/embedder.py`, `blp/nodes.py` |
+| MCP | `mcp/client.py`, `mcp/security.py`, `mcp/session_manager.py` |
+| Memory | `thread_name/nodes.py`, `tools/user_memory.py`, `tools/folder_memory.py` |
+| Tools | `tools/__init__.py`, `tools/providers/*` |
+
+## How it works
+
+### 1 — Graph topology
+
+```
+__start__
+  → generate_thread_name      (side-effect only; runs once on first human msg)
+  → summarize_if_needed        (compress old messages → state.summary)
+  → select_blp_context         (semantic BLP domain selection)
+  → create_plan                (optional HITL plan gate; bypassed in tool loop)
+  → call_model                 (ReAct: bind tools, call LLM)
+       ├─ no tool calls → __end__
+       └─ tool_calls   → tools (execute_tools)
+                       → tool_loop_summarize
+                       → call_model           (loop)
+```
+
+`route_model_output` (`graph.py:808`) routes to `tools` if the LLM emitted tool
+calls **and** `remaining_steps > 1`; otherwise `__end__`. The tool loop bypasses
+`create_plan` via `Command(goto=…)` — plans only fire on `__start__`.
+
+### 2 — State schema (`state.py`)
+
+- `messages` — `Annotated[..., add_messages]` (merge by ID).
+- `summary` — running compressed summary of older turns, re-injected as a
+  `SystemMessage` on each model call.
+- `summary_through_count` — last index already summarized.
+- `active_tool_categories` / `pending_tool_categories` — router output.
+- `artifact` — versioned canvas (`type`, `title`, `language`, `contents[]`).
+- `active_blp_domains` — pinned BLP domains (survives checkpoint restore).
+- `plan` — status ∈ {draft, pending_approval, approved, executing, completed,
+  just_completed}.
+- `remaining_steps` — LangGraph-managed; guarded at ≤3.
+
+### 3 — Configurable pieces (`config/`)
+
+Each `*_config.py` is `from_dict`-deserializable (flat or nested JSON):
+
+- `model_config` — model id, extended thinking, thinking budget tokens, prompt
+  caching, max output tokens.
+- `memory_config` — max context tokens, summarization model, thresholds.
+- `tool_config` — `code_interpreter_enabled`, max search results, session
+  timeout, nested `code_interpreter_config`.
+- `plan_config` — `enabled`, `auto_approve`, planning model.
+- `mcp_config` — server list with connection + credentials resolution.
+- `blp_config` — directories to scan, embedding model, top-K.
+- `artifact_config`, `interrupt_config` (`autonomy_level` ∈ {`full_auto`,
+  `interactive`}), `thread_config`.
+
+### 4 — Tool ecosystem
+
+| Category | Tools |
+|---|---|
+| `user_memory` (always on) | `remember_user_info`, `recall_user_info`, `update_user_info` |
+| `folder_memory` | save/recall/update workspace-shared context |
+| `web_search` | `search_web`, `get_website` (SearxNG) |
+| `knowledge_base` | `list_knowledge_bases`, `search_knowledge_base`, `retrieve_source_document` (Bedrock KB) |
+| `code_interpreter` | Dynamic toolkit from Bedrock AgentCore sandbox |
+| `canvas` | `create/update/rewrite/delete_artifact` |
+| `visualization` | `generate_chart`, `generate_table`, `generate_metric` |
+| `blp` | `query_business_logic`, `refresh_blp_context` |
+| `request_input` (always on) | `interrupt()` for HITL |
+
+Dynamic loaders: **MCP tools** via `load_mcp_tools_per_server` (keyed
+`mcp:<server>`); **skills** via `skill_injector` (pre-loaded into the CI
+sandbox at session start); **file injector** for workspace/file context.
+
+**Tool router** (`tool_router.py`) — LLM-based category selection unless the
+user pre-selects `selected_tool_categories`. Routes on the last human message
+(cache key excludes `active_tool_categories` so the prompt cache survives the
+tool loop). On router failure → bind all categories.
+
+### 5 — MCP integration
+
+- **Credential resolution** (`mcp/security.py` → `MCPCredentialResolver`):
+  LangGraph Store → user context (`${user_id}`, `${user_email}`) → env vars.
+  Validates `allowed_commands`, `blocked_url_patterns`, `allowed_env_vars`,
+  `env_mode` against the DB-stored security config.
+- **Session persistence** (`mcp/session_manager.py`): keyed by
+  `(server_name, user_id, connection_hash)`. TTL 45 s (below the ALB 60 s
+  idle timeout); liveness ping every 25 s. Lazy init; transparent reconnect.
+- **Circuit breaker** (`mcp/client.py`): per-server failure counters open the
+  breaker for `cooldown_seconds`.
+
+### 6 — BLP (Business Logic Platform)
+
+Declarative rules engine. `.blp` files hold CONSTRAINT / TERMS / CONTEXT /
+ROLE / RULES blocks classified into **Tier 1** (always loaded) and **Tier 2**
+(on-demand via `query_business_logic`). `blp/registry.py` scans configured
+directories; `blp/embedder.py` embeds domains + blocks with **Amazon Titan
+Embeddings V2** (1024 dims). `select_blp_context` picks top-K domains on the
+first human message and pins them to `state.active_blp_domains`.
+
+### 7 — Thread naming & memory
+
+- `generate_thread_name` runs once on the first human message via fast Bedrock
+  model (boto3 direct), persists the title to thread metadata, returns `{}`.
+- `summarize_if_needed` compresses older messages past a threshold; summary is
+  injected as a `SystemMessage` before each model call.
+- User & folder memory tools persist facts across threads / within a folder.
+
+## Data model
+
+State persists via the LangGraph checkpointer (Postgres) injected by
+`aegra-api`'s `langgraph_service`. Long-term storage: LangGraph **Store**
+namespace (user/folder memory, MCP credentials per user); Bedrock
+**AgentCore sandbox** (CI session state, large-output blobs; LLM sees a stub
+path, not the bytes).
+
+## Client variations
+
+Graph is **client-agnostic by construction**; per-tenant differences enter via
+the assistant `config` row: `mcp_config.servers`, BLP directories, KB IDs.
+Add a client override by configuring its assistant, not by forking the graph.
+
+## Gotchas / known issues
+
+- **Tool loop must skip planner** — re-enter `call_model` via
+  `Command(goto="call_model")` from the tool node, else `create_plan` fires
+  mid-loop and the LLM re-plans every step.
+- **Router cache key** must exclude `active_tool_categories` or the same user
+  message produces different cache keys across the loop and you lose the hit.
+- **MCP session TTL < ALB idle timeout** — 45 s vs 60 s. If the ALB tightens,
+  drop the session TTL to match or you get spurious `ConnectionResetError`s.
+- **Large-output offload threshold** ~20 KB. Raise it carefully: the LLM still
+  re-reads the offloaded path on retrieval (token cost).
+- **`remaining_steps ≤ 3` guard** forces no-tools on the next call near the
+  recursion limit. Raise the limit in graph build before raising expectations.
+
+## Change history
+- 2026-06-16 — Initial react_agent feature doc. (akhokhani)

package/knowledge/INDEX.md

@@ -21,6 +21,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **saml** (SAML SSO Gateway) — 2 doc(s) → [2.0/apps/saml/INDEX.md](2.0/apps/saml/INDEX.md)
 - **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)
 
 ## standalone framework
 

package/knowledge/registry.json

@@ -13,5 +13,6 @@
   { "repo": "toga2-hub",   "project": "TOGa Hub",    "framework": "2.0", "role": "app",  "dependsOn": ["api2"] },
   { "repo": "togatech",    "project": "TOGA Technology Website", "framework": "standalone", "role": "app", "dependsOn": [] },
   { "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": "walmarttechservices", "project": "Walmart Tech Services", "framework": "1.0", "role": "app", "dependsOn": ["library"] },
+  { "repo": "talos",       "project": "TOGa IQ",      "framework": "2.0", "role": "app", "dependsOn": [] }
 ]

package/package.json

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