Appearance
Florence AI — architecture
Status: Living document. v0.1, 2026-04-22. Tracking issue: #61 — Florence AI architecture + infrastructure design. Input brief (input-of-record):
/briefs/BRIEF_FLORENCE_AI_ARCHITECTURE.Naming note: the brand "Florence" has trademark exposure. In all new work use Florence AI or AskFlorence AI until legal clears the final brand. This directory is the settled-architecture home; the input brief above is preserved verbatim for fidelity to the original hand-off document.
Florence AI is the universal conversational interface to AskFlorence. Every user interaction — pre-enrollment plan discovery, intake, enrollment hand-holding, post-enrollment support, renewal, appointment assistance — flows through Florence.
The UI (plan cards, filters, forms, dashboards) and Florence are two faces of the same state machine: both drive the same deterministic application functions. Intercom-style support tools cannot exist in our Phase 3 EDE posture; Florence absorbs that role by design, not as an add-on.
The one sentence that governs everything
Florence is a natural-language interface over the deterministic AskFlorence platform. She never computes a fact. Every factual claim she makes traces to a tool call in the current turn.
That sentence is the north star. Every downstream decision in this directory derives from it.
How to navigate this directory
| Doc | What it covers |
|---|---|
| Principles | The invariants. Deterministic grounding, no-compute, text-as-source-of-truth, unit-economics targets, camouflage posture. Read first. |
| Runtime | FlorenceRuntime on Claude Agent SDK. Model routing, prompt caching, streaming, state persistence, context compression. |
| Tool surface | How tools work. api_* vs ui_* families. Auth context. The deterministic-integration pattern every tool follows. |
| Adding a tool | Playbook. Lifecycle from proposal → schema → classification → eval coverage → ship → monitor → deprecate. Security review required at each stage. |
| Tool registry | Living inventory. Every Florence-callable tool, its backing deterministic endpoint, data classification, auth scope, eval coverage, status. |
| Knowledge: SBC scenarios & CSR | Tool-callable reference for the plan-detail Year Scenarios block: CMS standardized totals, where puf.csrVariants[tier] lives in MongoDB, why CSR-94 patient cost can still be meaningful (AV ≠ per-scenario), dataset distribution, worked walkthrough Florence can quote, ENG-365 Option C provenance. |
| Voice | Three-stream architecture. Vendor strategy through Phase 3. EN + ES from day one. Quality-preserving paths to EDE. |
| Evals & observability | Eval harness design. Audit log + cost dashboard + alert policy. How we hold the unit-economics targets in practice. |
| Provider risk & portability | Vendor concentration risk, the four tiers of switch (Tier 0 transport → Tier 1 model → Tier 2 cross-vendor → Tier 3 self-hosted), capability matrix, warm-standby operational plan. |
| Outage playbook | Operational companion to provider-risk. Failure-domain analysis, the 6-tier quality-preserving cascade, circuit breakers + thresholds, request hedging, Tier 6 deterministic-only mode, chaos drills. Validated against recent Anthropic incident history. |
| Roadmap | Phase 1 → 1.5 → 3 sequencing. Dependencies on AWS migration (#47), compliance work (#55, #56, #57), data-classification rollout. |
| Build plan | Concrete staged build: A0 spike → A1 foundation → A2 beta on staging. Stream A (runtime), Stream B (tool PRs), Stream C (data-classification retrofit), Stream D (infra). Parallel-safe branch discipline + handoff prompt for the first Stream A session. |
| WOW flow research | ENG-356. Clicky teardown (incl. their ElevenLabs wiring + rendering craft), Cartesia vs ElevenLabs eval with the demo-acceptable vs production-BAA-signable distinction + transcript-as-PHI, the proposed voice-synced rendered WOW flow (beats x scene x tool x spotlight + state machine + edges), demo-vs-prod brain wiring, and the local demo. |
What this directory is NOT
- Not the deterministic platform's architecture (see system architecture and data sources).
- Not the agent portal (see agent platform).
- Not the infrastructure runbooks (see infrastructure).
- Not an input brief. Input briefs live in
/briefs/; this directory holds the settled architecture they informed.
Relationship to the rest of the system
The UI and Florence operate on the same deterministic platform. Florence can drive the UI via ui_* tools (filter a search, open a plan, highlight a form field). This is the co-pilot register that separates Florence from a chat widget.
