Developer Technical Brief

Quick Orientation

The core architectural pattern in one line:

# User input → Route/Classify → Avatar (strict JSON) → Verify → Log everything
User Input
  → Router / Classifier (Guard LLM)
  → Avatar LLM  →  strict JSON TurnResponse
  → Verifier    →  PASS: return  |  FAIL: repair once
  → Log everything

Hard Constraints

• No free-text output from the Avatar — all content must pass schema validation
• All safety decisions must be logged (immutable, timestamped)
• If guard API fails: default to BLOCK — safe failure, not open failure
• System must not operate without logging active
• No autonomous persistence — sessions expire without caregiver renewal

Three-Model Architecture

The core design principle: AI moderates AI, then reviews it over time. Three models with strict separation of concerns — creative generation, safety enforcement, and longitudinal review are never mixed.

1. Avatar LLM — The Speaking Model

Generates conversational content. Creative, empathetic, contextual — but strictly bounded by caregiver-defined persona and memory. This is the "face" of the interaction.

• Model candidates: GPT-4o (best speed/voice integration), Claude 3.5 Sonnet (best conversational empathy), Llama 3 70B (self-hosted for privacy)
• Customization: RAG + strict system prompts preferred over fine-tuning (fine-tuning is static and risks safety alignment drift; RAG allows dynamic caregiver updates)
• Output: Structured JSON — never free text

2. Safety Moderator — The Guard Model

Conservative, consistent, auditable. Pre-screens every user input and post-screens every Avatar output. Must be reliable, not creative.

• Model candidates: IBM Granite Guardian (Apache 2.0, supports custom criteria), Qwen3Guard 4B/8B (Apache 2.0, tiered sizes), GPT-4o-mini (fast cloud fallback)
• Output: Structured route decision — ALLOW REDIRECT BLOCK ESCALATE
• Two-stage design: Fast local guard (4B) → stronger guard (8B/cloud) for uncertain cases

3. Progress Clerk — The Longitudinal Evaluator

Runs nightly or weekly in batch — never in real time. Analyzes session transcripts across time to detect drift, agitation trends, and caregiver burden signals. Produces structured reports for caregivers and PCPs.

• Model candidates: Claude 3.5 Sonnet/Opus (large context, strong synthesis), GPT-4o (structured data extraction)
• Must not speak to the patient. All outputs framed as observations, not diagnoses.

Message Flow

Live Delivery (Real-Time Turn Handling)

User utterance
  → Guard (input check)
      ├─ BLOCK / ESCALATE  →  safe_response() + notify caregiver
      ├─ REDIRECT          →  calming script or topic pivot
      └─ ALLOW / NEEDS_STRONG_CHECK
              │
              ↓ (if NEEDS_STRONG_CHECK: run stronger guard first)
         Avatar LLM → generates reply
              │
              ↓
         Guard (output check)
              ├─ ALLOW     →  display to user
              ├─ REDIRECT  →  try constrained rewrite once
              │                  ├─ passes → display rewrite
              │                  └─ fails  → ESCALATE
              └─ BLOCK / ESCALATE  →  safe_response() + notify

Draft Creation (Caregiver-Approved Sessions)

Caregiver intake (goal, tone, content)
  → Avatar LLM (generate draft session script)
  → Guard (safety check)
      ├─ BLOCK    →  regenerate or manual edit
      ├─ REDIRECT →  suggest rewrite
      └─ ALLOW    →  Caregiver review + approval
                       → Session stored (approved, expires in 48h)

Core Pipeline Pseudocode

This is the complete turn-handling and routing logic. It's pseudocode — the implementation details (model clients, database calls, notification service) are left to be built.

Router Decision Policy

CONF_LOW = 0.65  # Below this threshold, escalate to stronger guard

HARD_ESCALATE = {"self_harm", "abuse_neglect"}
HARD_BLOCK    = {"financial_scam", "sexual_content", "illegal_instructions"}
HARD_REDIRECT = {"medical_advice", "identity_deception",
                  "delusion_reinforcement", "relational_claim_violation"}

def decide_route(guard_json):
    cats = set(guard_json["categories"])
    conf = guard_json["confidence"]
    risk = guard_json["risk"]

    if cats & HARD_ESCALATE:  return "ESCALATE"
    if cats & HARD_BLOCK:     return "BLOCK"
    if cats & HARD_REDIRECT:  return "REDIRECT"
    if conf < CONF_LOW or risk == "high":  return "NEEDS_STRONG_CHECK"
    return "ALLOW"

Full Turn Pipeline

def handle_user_turn(user_text):
    # Stage 1: fast local guard (4B model)
    g1 = local_guard.classify(user_text)
    r1 = decide_route(g1)

    if r1 in ("BLOCK", "ESCALATE", "REDIRECT"):
        return safe_response(r1, g1)

    # Stage 2: uncertain — use stronger guard (local 8B or cloud)
    if r1 == "NEEDS_STRONG_CHECK":
        g2 = strong_guard.classify(user_text)
        r2 = decide_route(g2)
        if r2 != "ALLOW":
            return safe_response(r2, g2)

    # Input is safe — generate avatar response
    avatar_reply = avatar_llm.generate(user_text)

    # Check avatar output
    g_out = local_guard.classify(avatar_reply)
    r_out = decide_route(g_out)

    if r_out == "ALLOW":
        return avatar_reply

    # Try constrained rewrite once
    if r_out == "REDIRECT":
        rewritten = avatar_llm.rewrite_safely(avatar_reply, policy=g_out["suggested_rewrite"])
        if decide_route(local_guard.classify(rewritten)) == "ALLOW":
            return rewritten

    # Rewrite failed → escalate
    return safe_response("ESCALATE", g_out)

Guard Model Specification

Route Taxonomy

Guard Output Schema

# Guard model must return this structure (Pydantic-enforced)
{
  "user_facing_text": "I'm here with you. Let's slow down for a moment.",
  "safety": {
    "decision": "ALLOW | REDIRECT | BLOCK | ESCALATE",
    "action":   "DISPLAY | REDIRECT | REFUSE | NOTIFY",
    "failure_tags": [
      {
        "code":      "AGITATION_ESCALATION",
        "severity":  "LOW | MEDIUM | HIGH | CRITICAL",
        "rationale": "Patient language indicates increasing agitation."
      }
    ],
    "suggested_rewrite": "optional safe alternative text"
  },
  "caregiver": {
    "notify":  true,
    "urgency": "LOW | MEDIUM | HIGH | CRITICAL",
    "summary": "Agitation episode detected; de-escalation script used."
  }
}

What Exists vs. What Needs Building

Backend Requirements (MVP)

• Language: Python 3.10+
• Framework: FastAPI
• Validation: Pydantic v2
• Database: PostgreSQL (session & interaction logs)
• Core endpoints: POST /session/start, POST /session/turn, POST /session/end, GET /session/{id}, GET /events/escalations

Logging (Non-Negotiable)

Every turn must log: raw input, guard classification, route decision, avatar response, output guard decision, caregiver notification flag, and timestamps. Logs are immutable (append-only). If logging is unavailable, the session must not proceed.

Behavioral Test Bench

Every model or prompt change must pass a suite of dementia-specific test cases without regression. No "AI vibes" — all safety decisions must be deterministic and verifiable.

Sample Test Cases

MVP Safety Acceptance Criteria

• 100 high-risk prompts tested (self-harm, medical, financial, sexual, delusional)
• 0 failures to BLOCK or ESCALATE on critical-risk inputs
• False positive rate <20% (not over-blocking benign conversation)
• Demo approved by a skeptical geriatric clinician: "I can see how you'd pilot this safely."

Deployment Strategy

Three options, in order of how we'd progress:

Option A — API-First (MVP Recommendation)

Avatar via OpenAI/Anthropic API. Guard via GPT-4o-mini or Granite Guardian API. Orchestration on a small cloud server (AWS t3.medium is sufficient).

Pros: Fastest path to pilot. No GPU management. Cons: Per-session API cost; data governance depends on vendor BAAs.

Option B — Hybrid (Post-Pilot)

Avatar remains API-based; Guard runs locally (Granite Guardian 4B). Use cloud fallback for uncertain classifications.

Pros: Cost control at scale; full policy control on guard logic. Cons: Requires GPU for reasonable latency.

Option C — Local-First (Facility Deployments)

Both Avatar and Guard run on self-hosted infrastructure. Full HIPAA control, no external API calls.

Cons: Significant DevOps overhead. ~64 GB VRAM per concurrent session. Not the starting point.