Agentic platform¶

Design dossier for the LLM agent platform: how we call models, wire tools, orchestrate multi-agent swarms, and connect to the analytical data layer. Start with the review doc if you're evaluating; start with the index below if you're implementing.

Document index¶

File	What it covers	~Lines
REVIEW.md	Start here for review. Shareable overview with 16 decision points for colleague input	250
01-insertion-points.md	Four LLM layers (A–D): where they live, what they do, rollout order, cost, risk	200
02-gateway-and-providers.md	Platform comparison (Anthropic direct, LiteLLM, Azure AI Foundry, Bedrock), recommended two-phase architecture, LiteLLM config, compose service	200
03-client-wrappers.md	Go + Python HTTP wrappers for both Anthropic-native and OpenAI-compatible APIs, unified adapter interface	400
04-tool-use.md	Schema generation from Go structs + Pydantic, tool dispatch loops (both wire formats, both languages), ML model wrappers as tools	450
05-data-layer.md	ClickHouse over parquet, NFS mount (dev) / ADLS + Dagster (prod), guardrails, compose service, DDL examples	250
06-agentic-swarms.md	Orchestration patterns, Temporal as swarm backbone, bespoke + UW triage worked examples, config structs, parallel execution	300
07-cost-safety-audit.md	Per-execution budgets, LiteLLM spend tracking, Langfuse, structured logging, API key management, prompt injection, audit trail	200

Core principle¶

LLMs earn their keep on free-text parsing and tool-call reasoning, NOT on hard mathematics. The deterministic margin-equalising allocator (D1) owns the math. Every LLM-proposed allocation is validated by the deterministic simulate endpoint. This is ADR D18.

Dependency graph¶

01-insertion-points         (what the LLM layers are)
    │
    ├──▶ 02-gateway-and-providers   (how we reach the models)
    │         │
    │         └──▶ 03-client-wrappers   (Go + Python HTTP code)
    │
    ├──▶ 04-tool-use                (how agents call services + ML models)
    │         │
    │         └──▶ 05-data-layer        (ClickHouse + parquet as a tool)
    │
    └──▶ 06-agentic-swarms          (multi-agent orchestration via Temporal)
              │
              └──▶ 07-cost-safety-audit (spend caps, guardrails, audit)

REVIEW.md — reads across all of the above; entry point for colleagues

Relationship to other docs¶

ADR D18 (docs/reference/key-decisions.md) — the guardrails decision that governs everything here.
Bespoke telemetry (docs/research/bespoke-telemetry.md) — Layer 2/3 data that feeds the get_partner_history tool.
Bespoke allocator (docs/research/bespoke-allocator.md) — the deterministic math engine that agents must not replace.
UW queue blueprint (docs/research/uwe-queue-temporal-blueprint.md) — the underwriting domain where agents also plug in.
Phase 8 sessions (docs/sessions/phase-08-bespoke-platform/) — the shipping sessions that implement the bespoke platform.