Section-routing architecture in src/parsers/: rather than sending the whole document to an LLM, the text is split into named sections and each one is handled by whichever strategy actually fits it — deterministic regex where the shape of the data is predictable (a medication list, a header line), a focused local-LLM call only where it isn't (freeform vitals prose, referral mentions).

SectionSplitter (src/parsers/agent/section_splitter.py) is what turns raw PDF text into the named chunks the router hands off — a table of regexes (SECTION_HEADERS) matched against the text to find where each section starts, covering two structurally different export formats side by side:

• Order matters — SECTION_HEADERS is a list, not a dict; earlier patterns are matched first when two headers could plausibly overlap on section boundaries.
• Truncated to MAX_SECTION_CHARS = 2000 chars per section — this, not just the section-routing split itself, is what keeps each LLM call small and focused rather than re-feeding a bloated chunk of the document.
• Cached after first access — .get()/.all_sections() only run the regex table once per document, even though multiple router stages (e.g. vitals pulls from todays_visit, vitals_section, and physical_exam) request overlapping sections.
• A section can feed more than one router stage, and a stage can pull from more than one section — the split and the routing are deliberately decoupled layers; SectionSplitter doesn't know which stage strategy is deterministic vs. LLM, it just answers "give me the text under header X."

The router's strategy per section is a fixed table, decided up front by a human reading real Sutter Health and Tebra export samples — not inferred at runtime:

Each llm/hybrid section only receives the specific chunk(s) of text it needs (from SectionSplitter, capped at 2000 chars each) — never the full document — via a focused system prompt (src/parsers/agent/prompts.py) and a single direct_chat() call (src/parsers/agent/ollama_chat.py).

• Local-only, enforced not just documented — ollama_chat.py has a safety check that blocks any non-localhost URL, so a misconfiguration can't silently route PHI externally.
• Two document formats, one pipeline — the deterministic regexes carry parallel fallback chains for Sutter Health AVS exports and Tebra clinical-note exports, since the two look structurally different (e.g. header parsing tries the Sutter header-line pattern first, then falls back to Tebra's "Visited on:" / "MRN :" patterns).
• Review before apply — parsed items are always presented for user confirmation with per-section checkboxes; nothing is auto-applied to the profile.
• Deduplication — diagnoses dedupe by name on apply (existing conditions get ICD-10 backfilled if missing); medication stops match by name.

Before generating visit-prep questions, relevant past-visit history is selected via a 4-stage pipeline in src/utils/context_selection.py:

1. Rules-based filter (instant, free) — always include same-doctor's last visit and PCP/Internal Medicine visits; apply a specialty-relevance mapping (e.g. Endocrinology ↔ Cardiology, Nephrology); exclude doctors flagged out of prep context. The same-doctor visit is pinned — its id is tracked through stages 2 and 3 so it can't be capped, score-filtered, or budget-dropped later, unlike every other candidate.
2. Local LLM relevance scoring (Ollama) — only runs if more than 5 visits remain after stage 1; scores each 1-10, keeps ≥7 (pinned visit kept regardless). Candidates beyond context_stage2_max_candidates (default 15, the pinned visit exempt) are cut before scoring even happens — one sequential, unbatched Ollama call per candidate makes this a real cost, not just a formality.
3. Token budget check — packs visits by priority: pinned first, then stage 2's relevance score (highest first), then recency as a fallback when no score exists (stage 2 was skipped). Visits that don't fit are dropped, not summarized — see the callout below.
4. Anonymize — the only stage where data crosses into what the external-capable backend will see.

Stage 2's relevance scoring deliberately runs on raw, pre-anonymization text — it's a local-only call, so there's no privacy reason to anonymize before it, and doing so first would degrade the local model's ability to judge relevance from real names/context.

Hybrid approach in src/utils/anonymization.py: structured fields get deterministic handling (patient name omitted entirely — not substituted, just never included in AnonymizedProfile; DOB → exact age; doctor name → "your [specialty]"; prescribing doctor → "Prescribing physician"; doctor phone/email dropped, clinic kept), free text goes through regex (phone/email/SSN patterns) plus spaCy NER for names.

• Documented as best-effort on free text, not a guarantee — NER can miss names in unusual phrasing. This is stated explicitly rather than implied, since silently overstating a privacy guarantee is worse than none.
• The free-text date regex is deliberately over-inclusive — it redacts anything MM/DD/YYYY-shaped, not just birthdates, so a visit date mentioned inside notes prose gets swept up too. Same safe-by-default philosophy as this doc's other fail-open designs: better to over-redact than risk a real date slipping through.
• Applies uniformly regardless of provider — even when running fully local Ollama (where anonymization is technically unnecessary since nothing leaves the machine), the same code path is used for consistency and to avoid two divergent implementations.
• Tool results are anonymized too, not just the initial context — a result from lookup_past_visits mid-loop goes through the same Anonymizer before re-entering the conversation.

_run_agentic_loop in src/agents/visit_prep.py: send context + tool specs to the backend → if it returns tool calls, execute each against the DB, anonymize the result, append to the conversation, repeat → if it returns final text with no tool calls, that's the answer → if agent_max_turns is exhausted first, raise and let the caller fall back to single-shot.

• Why bounded, not open-ended: an unbounded loop against a small/unreliable local model can spin. A hard turn cap makes worst-case latency and cost predictable.
• Why Ollama as default, not Claude API (DEC-016, superseding DEC-009's default): the dev machine (Apple M3, 8GB RAM) can only run 4-bit quantized 7-8B models, and small quantized models produce unreliable tool-calling — malformed JSON, wrong tool selection, non-convergence — which is still true and exactly why the fallback-to-single-shot behavior below matters. But defaulting the primary, most-used flow to an external API sat awkwardly next to the project's local-first pitch. Claude (and any custom OpenAI-compatible provider) remain fully supported, now as explicit opt-ins from Settings rather than the default.
• Two tools today, deliberately bounded scope for v1 — a real drug-interaction checker and a user-facing pause-to-ask-clarifying-questions flow were explicitly descoped as separate, bigger features.
• This loop's fallback isn't the last line of defense — if single-shot generation fails too (or anything else in prepare_visit() raises), an outer catch-all returns a fixed set of generic questions rather than an error. See Reliability Design in System Design for the full three-layer chain.

Before DEC-011, visit prep generated the same questions regardless of which specialist the appointment was with — it would suggest discussing a dermatology cream with a cardiologist. Fixed with two system prompt templates (SYSTEM_PROMPT_TEMPLATE, SYSTEM_PROMPT_GENERIC in src/agents/visit_prep.py) plus data enrichment that tags conditions and medications with the specialty that actually manages them.

• ICD-10 → specialty mapping (ICD10_SPECIALTY_MAP, prefix and range matching via _icd10_to_specialties()) — exact prefixes checked before ranges, so a specific code like E28 doesn't get swallowed by the broader E20–E35 range.
• Medication → prescriber specialty tagging — matches a medication's free-text prescribing_doctor against the profile's Doctor records to label it (e.g. "prescribed for Dermatology"), so the model can tell which meds are actually this specialist's business.
• Clinic-name inference fallback (_infer_specialty_from_clinic()) — keyword-matches the clinic name (e.g. "Sutter Endocrinology") when doctor.specialty is null.
• The prompt itself draws the line explicitly: don't suggest unrelated-specialty medications, but do surface real cross-condition interactions relevant to this specialty (its own worked example: Hashimoto's and PCOS interact hormonally, which matters for an endocrinologist even if a gynecologist made the original diagnosis).

src/agents/llm_backend.py: an LLMBackend ABC with three implementations — ClaudeBackend (wraps AsyncAnthropic, uses Claude's native tools= parameter), OllamaBackend (calls Ollama's /api/chat with OpenAI-style function-calling tool specs), and CustomOpenAICompatibleBackend (DEC-016 — any endpoint speaking OpenAI's /chat/completions + tool-calling format: OpenAI, OpenRouter, Groq, Together, a self-hosted vLLM/LM Studio server, etc.). All three normalize into the same ToolCall/LLMTurnResult shape, so _run_agentic_loop never branches on which provider it's talking to — it just calls backend.call(...) and reads a uniform result.

• One canonical tool spec, reused wire format: src/agents/tools.py defines TOOL_SPECS once, then claude_tools() adapts it for Claude and ollama_tools() covers both Ollama and the custom provider — Ollama's /api/chat already mirrors OpenAI's function-calling shape, so the custom backend needed no third adapter.
• One classification, shared by both call sites: uses_openai_style_wire_format(provider) is the single source of truth for the Ollama/custom-vs-Claude split, used by both get_llm_backend() (which class to instantiate) and get_tools_for_provider() (which tool-spec shape to build). Two independent == "ollama" checks could drift out of sync if a provider were added later; one shared function can't disagree with itself.
• Why this matters beyond the agentic loop: it's what makes LLM_PROVIDER=ollama a real, fully-local default rather than a stub — the same tool-use loop, same tools, same anonymization boundary, just a different backend underneath.
• Selected via a factory, get_llm_backend(settings), keyed off settings.llm_provider. DEC-016 also consolidated dispatch inside visit_prep.py itself — it previously checked llm_provider == "ollama" via string equality in three separate places; all three now route through get_llm_backend()/get_tools_for_provider().
• Runtime-editable, not just env-configured: settings.llm_provider is now overlaid from a DB-backed AppSettings singleton row (src/services/settings_service.py), so switching providers from the Settings page takes effect on the next request — no .env edit or restart needed.

Closes the loop between "document parsed" and "patient acts on what the doctor ordered." Two surfaces: a post-AVS action panel (fires at the moment of highest engagement, right after confirming a parsed document) and a persistent "Needs Attention" overview section (catches items accumulated from past visits, always visible).

• Snooze (1w/2w/1m) and completion state persist via snoozed_until/completed_at on FollowUp/LabOrder/Referral, plus a NudgeState table for computed nudges that have no natural row to attach state to (e.g. "past-due appointment").
• Five computed nudge types drive the overview section: past-due appointments (scheduled_date passed, status still scheduled), upcoming appointments without prep (scheduled within the next 30 days, no VisitPrep row yet), completed visits with no AVS uploaded within 14 days of the appointment date, adverse vitals trends (meaningful directional change in weight/BMI/blood pressure/heart rate across ≥2 recorded visits), and follow-ups, lab orders, and referrals that remain active (not yet completed) since they were logged. All five respect per-item snooze state so a dismissed nudge doesn't resurface until it expires.
• Scheduled push notifications for genuinely disengaged patients — reaching someone who isn't currently in the app — were considered and explicitly deferred; it's new infrastructure (a scheduler + notification channel) that arguably conflicts with the local-first architecture, not a pure addition on existing data like the two shipped surfaces are.

src/data/models.py: HealthProfile at the root, with Condition, Medication, Doctor, and Appointment hanging off it. AVS-parsed data nests under Document — Vitals (1:1), LabOrder/Referral/FollowUp (1:many) — so every parsed item traces back to the source PDF it came from. VisitPrep and ConversationLog record generated output and (anonymized) LLM call history; NudgeState persists snooze/dismiss state for the nudges that have no natural row of their own.

• UUID primary keys, not auto-increment integers (DEC-004) — a sequential ID leaks how many records exist and lets rows be enumerated by guessing. UUIDs cost a little storage/perf, which is a fine trade for health data specifically.
• Profile-nested API routes (/api/profiles/{id}/conditions/, etc.) — ownership is enforced by the URL structure itself, not left to an ad-hoc check in each handler.
• Condition.icd_10 was added specifically to enable specialty-aware prompting (DEC-010/DEC-011) — the schema changed because a feature needed it, not speculatively ahead of time.
• Async throughout — SQLAlchemy 2.0 async sessions, aiosqlite, matching the async FastAPI route handlers end to end rather than mixing sync DB calls into an async app.