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.