_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.

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.
• 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.

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).

Hybrid approach in src/utils/anonymization.py: structured fields get deterministic replacement (patient name → "Patient", DOB → exact age, doctor name → "your [specialty]"), 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.
• 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.

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.
2. Local LLM relevance scoring (Ollama) — only runs if more than 5 visits remain after stage 1; scores each 1-10, keeps ≥7. Skipped if Ollama is unavailable, falling back to rules + truncation.
3. Token budget check — summarizes older visits with the local LLM if still over budget.
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.

Section-routing architecture in src/parsers/: deterministic parsers handle structured sections (patient info, medication changes, follow-ups, appointments, diagnoses with ICD codes); local Ollama handles unstructured sections (vitals, lab orders, notes, referrals, diagnoses without a structured Assessment section).

• 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.
• 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.

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.