1. Copy .env.example to .env.
2. Fill in:
   • MONGODB_URI
   • MONGODB_DB_NAME
   • OPENAI_API_KEY
   • OPENAI_MODEL (default: gpt-5-mini)
   • OPENAI_SNAPSHOT_MODEL (optional; fallback to OPENAI_MODEL)
   • GOOGLE_GEOCODING_API_KEY
   • GOOGLE_CIVIC_API_KEY (optional; falls back to GOOGLE_GEOCODING_API_KEY)

• CIVIC_SNAPSHOT_TTL_HOURS (default: 24)
• CIVIC_PIPELINE_VERSION (default: v1)
• DC_PULSE_PIPELINE_VERSION (default: v1)
• DC_PULSE_FEED_TTL_MINUTES (default: 45)
• DC_PULSE_THREAD_TTL_HOURS (default: 24)
• OPENAI_PULSE_MODEL (default: OPENAI_MODEL)
• OPENAI_PULSE_TEMPERATURE (default: 0.1)

3. Install dependencies:
   • pip install -r requirements.txt

• MongoDB config: data/config.py
• MongoDB client/db helpers: data/db.py

• Start server: uvicorn main:app --reload
• Health check: GET /health
• Start onboarding: POST /api/onboarding/start
• Send user message: POST /api/onboarding/turn
• Add onboarding memory entry: POST /api/onboarding/memory
• Get memory for one session: GET /api/onboarding/memory/{session_id}
• Build civic snapshot: POST /api/civic/snapshot
• Interactive chat test (auto-terminates on completion):
  • ./scripts/chat_onboarding.sh
• New Civic Pulse endpoints:
  • GET /api/dc/pulse?limit=5
  • POST /api/dc/pulse/chat/start
  • POST /api/dc/pulse/chat/message

• Always present:
  • session_id
  • assistant_message
  • options
  • is_complete
  • terminate

POST /api/civic/snapshot

{
  "address": "3500 16th St NW Washington DC",
  "force_refresh": false
}

{
  "normalized_address": {
    "formatted_address": "3500 16th St NW, Washington, DC 20010, USA",
    "city": "Washington",
    "state": "DC",
    "zip": "20010",
    "lat": 38.933,
    "lng": -77.035
  },
  "cards": [
    {
      "slot": "president",
      "role": "President",
      "jurisdiction": "United States",
      "name": "Example Name",
      "source_url": "https://www.whitehouse.gov/administration/president-biden/",
      "office_phone": "202-456-1111",
      "office_email": null,
      "official_website": "https://www.whitehouse.gov/",
      "official_photo_url": "https://www.whitehouse.gov/wp-content/uploads/example.jpg",
      "source_domain": "whitehouse.gov",
      "evidence_quote": "President Joe Biden ...",
      "confidence": 0.93,
      "status": "confirmed"
    }
  ],
  "cache_hit": false,
  "pipeline_version": "v1",
  "generated_at": "2026-02-22T00:00:00+00:00"
}

• confirmed: has name, source_url, evidence_quote; quote includes both name and role; source is not fallback-only.
• uncertain: partial evidence exists but does not meet confirmation rules.
• not_found: no verifiable source-backed result.

• Fallback-only sources (wikipedia.org / ballotpedia.org) are never returned as confirmed.
• Every slot is always returned so UI can render fixed cards.
• Contact fields and photo field are best-effort and return null when not explicitly found in source content.