Skip to content

Steer-07: Explanation Agent & Multilingual Output

Read first: specs/sdd-mvp/04-agent-pipeline.md, specs/sdd-mvp/06-matching-engine.md

Context & Goal

Implement the Explanation Agent that generates natural language match reasoning in the patient's preferred locale (Arabic for Aisha). Includes template fallback for when LLM is unavailable.

Backend (curaway-ai/curaway-backend)

Step 1: Explanation Agent Implementation

Create/update app/agents/explanation/agent.py: - Input: ProviderMatch object (scores, domain breakdown, provider data, patient context) - Prompt: "Explain why {provider_name} is ranked #{rank} for this patient. Include clinical, cultural, and cost factors. Write in {locale}." - Model: Claude Haiku 4.5 (fast, cheap for generation) - Output: Natural language paragraph (200–400 words) in requested locale - Store explanation in match_results table alongside scores

Step 2: Template Fallback

Create app/agents/explanation/templates.py: - Template-based explanations for when LLM is down - Templates per locale (en, ar) with placeholder substitution - Template: "{provider_name} in {city}, {country} is recommended for your {procedure_name}. Their {specialty} department has {volume}+ procedures with {success_rate}% success rate. Cost: {cost_range}." - Feature flag llm_explanations — disable → use templates

Step 3: Locale Detection & Output

  • Read patient.preferred_locale (stored on patient profile)
  • If locale = 'ar': instruct Claude to respond in Arabic
  • If locale not set: default to 'en'
  • Store explanation_locale on match result for frontend rendering

Step 4: Tests

  • Test LLM explanation generates coherent text for Aisha (Arabic)
  • Test template fallback produces valid output
  • Test feature flag toggle between LLM and template
  • Test explanation stored on match result

Backend Verification

python -m pytest tests/test_explanation_agent.py -v

Frontend (curaway-ai/curaway-frontend)

Step 1: Match Reasoning Display

Update ProviderMatchCard.tsx: - Show explanation paragraph below score breakdown - Detect explanation_locale — set dir="rtl" and appropriate font for Arabic - Expandable: show first 2 lines, "Read more" expands

Step 2: Locale-Aware Rendering

Create src/utils/locale.ts: - isRTL(locale) → returns true for 'ar', 'he', 'fa' - getLocaleFont(locale) → returns appropriate font stack - Apply to explanation text rendering

Frontend Verification

npm run build
npx tsc --noEmit
# Manual: trigger match for Aisha, verify Arabic text renders RTL in provider cards

Checklist

  • [ ] Error codes: EXPLAIN_LLM_001, EXPLAIN_TEMPLATE_001
  • [ ] Feature flag: llm_explanations
  • [ ] Langfuse: explanation prompt version managed
  • [ ] Unit tests: LLM output, template fallback, locale handling
  • [ ] PostHog: explanation_expanded, explanation_locale
  • [ ] Accessibility: RTL text properly rendered, screen reader compatible
  • [ ] CLAUDE.md: update explanation agent description
  • [ ] Rollback: disable llm_explanations → template explanations