Section-routing architecture: 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 parsing 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).

The document is split into named sections (visit summary, medications, labs, assessment, vitals, and so on) using structural cues — headers, layout patterns — that hold across the two clinical-export formats this has been built and tested against so far. Each section is then capped to a focused chunk of text, so a downstream LLM call never has to search a bloated block of the document for the one fact it needs.

• Section boundaries are found once per document and reused — several parsing steps read overlapping sections (vitals data, for instance, can appear in more than one place in a visit note), so the split only has to run one pass.
• Splitting and routing are decoupled layers — the piece that finds section boundaries doesn't know or care which sections get handled deterministically vs. by the local model; it just answers "give me the text under this header."

The strategy per section is a fixed table, decided up front by a human reading real export samples from the clinical systems this app has actually been tested against — not inferred at runtime:

Each section that needs the LLM only receives the specific chunk of text it needs — never the full document — kept small and focused rather than re-feeding a bloated block of the visit note.

• Local-only, enforced not just documented — a hard safety check blocks any non-localhost model endpoint, so a misconfiguration can't silently route health data externally.
• Two document formats, one pipeline — parsing carries parallel fallback logic for the two clinical-export formats it's been tested against, since they're structured differently.
• 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:

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). Only the most recent 15 candidates (pinned visit exempt) are even considered at this stage — one 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.

Why is this a separate deterministic pipeline instead of an agentic-loop tool call? Small local models are unreliable at multi-turn tool-calling, so anything load-bearing for output quality — like which past visits matter — shouldn't depend on the agent choosing to call it correctly within its turn budget; it runs deterministically before the loop starts instead. The loop also needs some context in its first prompt to reason from at all, so full agent-driven retrieval would still need a bootstrapping mechanism of its own. The agentic loop's history-lookup tool exists to go beyond this baseline, not duplicate it — it excludes whatever this pipeline already selected, so the two layers can't redundantly re-fetch the same visit.

Hybrid approach: structured fields get deterministic handling (patient name omitted entirely — not substituted, just never included; 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.

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 the turn budget is exhausted, or the model calls a tool name that doesn't exist, fall back to single-shot generation instead.

• 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 an external API: constrained hardware (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 exactly why the fallback-to-single-shot behavior 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 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, 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.

Early on, 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 (a specialty-aware one and a generic fallback) plus data enrichment that tags conditions and medications with the specialty that actually manages them.

• ICD-10 → specialty mapping — exact codes checked before broader ranges, so a specific code like E28 doesn't get swallowed by a wider range it happens to fall inside.
• Medication → prescriber specialty tagging — matches a medication's 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 — keyword-matches the clinic name (e.g. "Endocrinology Associates") when a doctor's specialty isn't set explicitly.
• 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).

A common backend interface with three implementations — one wrapping Claude's native tool-use API, one calling Ollama's chat API with OpenAI-style function-calling tool specs, and one for any endpoint speaking OpenAI's chat-completion + tool-calling format (OpenAI, OpenRouter, Groq, Together, a self-hosted server, etc.). All three normalize into the same result shape, so the agentic loop never branches on which provider it's talking to — it just calls the backend and reads a uniform result.

• One canonical tool spec, reused wire format: tool definitions are declared once and adapted per provider — Ollama's chat API already mirrors OpenAI's function-calling shape, so the custom-provider backend needed no separate adapter.
• Why this matters beyond the agentic loop: it's what makes the local-Ollama default a real, fully-local path rather than a stub — the same tool-use loop, same tools, same anonymization boundary, just a different backend underneath.
• Selected via a factory keyed off the configured provider, with one shared classification used everywhere that split matters — instead of the same string-equality check duplicated in multiple places, which could quietly drift out of sync if a provider were added later.
• Runtime-editable, not just env-configured: the active provider is stored in the database, not just a startup environment variable, so switching providers from the Settings page takes effect on the next request — no config 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 per item, plus a shared table for computed nudges that have no natural record of their own to attach state to (e.g. "past-due appointment").
• Five computed nudge types drive the overview section: past-due appointments, upcoming appointments without prep (scheduled within the next 30 days, no prep generated 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 two or more recorded visits), and follow-ups, lab orders, and referrals that remain active since they were logged. All five respect per-item snooze state so a dismissed nudge doesn't resurface until it expires.
• Snoozing is recoverable and visible, not a silent hide: a dedicated view lets a patient see everything they've snoozed, an "Un-snooze now" action reverses it early, and an undo banner appears for 8 seconds after any snooze action.
• 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.

HealthProfile sits 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 — 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.
• ICD-10 coding on conditions was added specifically to enable specialty-aware prompting — 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.