← Back to Index

Carmee Pathway API - Full Specification v2.1

Version: 2.1 (REVISED with Intent Sensing + Conversational Discovery)
Date: 2026-02-18
Purpose: Automate 60-70% of Carmee's pathway coordination work (10-18 hrs/week savings)
Expected ROI: ~10,000x (API costs <$50/month, saves ~$3,000/month in Carmee time)

🚨 CRITICAL CHANGE FROM V2.0

V2.0 PROBLEM:

V2.1 SOLUTION:

Golden rule:

"Never unlock anything from what they said. Only from what they've done."

Architecture (Now Correct)

Inquiry
  ↓
Sense Intent (NL exploration, hypothesis generation)
  ↓
Ask Follow-Ups (Carmee conversation, 1-2 questions)
  ↓
Gate (verify integrity/authority/escalation with PROOF)
  ↓
Unlock Pathways (based on verified gates)
  ↓
Route (deterministic pathway selection)
  ↓
Quote / Pilot Overlay

Key distinction:

API Endpoints (Revised)

1. POST /api/pathway/sense-intent (NEW - THE SORTING HAT)

Purpose: Conversational inference, signal detection, hypothesis generation (NOT permission)

Request:

{
  "inquiry_text": "We're exploring options for our after-school program serving 200 kids. Interested in learning more about ZTAG.",
  "organization_name": "Lincoln Elementary PTA",
  "email_domain": "lincolnpta.org",
  "contact_name": "Sarah Johnson",
  "contact_email": "sarah@lincolnpta.org",
  "previous_messages": []
}

Response:

{
  "intent_hypothesis": {
    "likely_tracks": [
      {"pathway": 2, "confidence": 0.72, "reasoning": "PTA + after-school + 200 kids → 3rd-party nonprofit"},
      {"pathway": 1, "confidence": 0.41, "reasoning": "Could be district-funded if PTA partners with school"}
    ],
    "pilot_interest_detected": true,
    "district_scale_language": true,
    "budget_constraint_language": true,
    "supervision_signals": {
      "supervised": "UNKNOWN",
      "keywords_found": [],
      "confidence": 0.0
    }
  },
  "missing_signals": [
    "authority_level (site vs district)",
    "supervision_model (staff-led vs drop-off)",
    "district_engagement (PTA operating independently or with school partnership?)"
  ],
  "suggested_questions": [
    "Would this program be supervised by PTA volunteers or school staff?",
    "Is this something the PTA is exploring independently, or would the school district be involved?",
    "What does success look like for your program this year?"
  ],
  "energy_classification": "exploratory",
  "next_mode": "discover_authority",
  "ui_state": "EXPLORING"
}

Key features:

UI state: EXPLORING

2. POST /api/pathway/gate (REVISED - Requires Verification Sources)

Purpose: Verify Integrity → Authority → Escalation with PROOF

Request:

{
  "inquiry_text": "...",
  "organization_name": "Lincoln Elementary PTA",
  "context": {
    "supervised_use": {
      "value": true,
      "source": "conversation_claim",
      "evidence": "Sarah confirmed: 'PTA volunteers supervise kids during games'"
    },
    "educational_setting": {
      "value": true,
      "source": "website_verification",
      "evidence": "lincolnpta.org mission: educational enrichment for students"
    },
    "playmaker_present": {
      "value": true,
      "source": "conversation_claim",
      "evidence": "Confirmed Playmaker model in follow-up"
    },
    "purchasing_authority": {
      "value": "site",
      "source": "email_signature",
      "evidence": "Sarah's title: 'PTA President, Lincoln Elementary'"
    },
    "district_intro_sent": {
      "value": false,
      "source": null
    },
    "ztag_included_in_thread": {
      "value": false,
      "source": null
    },
    "district_reply_received": {
      "value": false,
      "source": null
    },
    "monthly_playmaker_commitment": {
      "value": false,
      "source": null
    }
  }
}

Verification sources (ranked by strength):

Response:

{
  "gates": {
    "integrity_pass": true,
    "integrity_proof_level": "conversation_claim",
    "authority_level": "site",
    "authority_proof_level": "email_signature",
    "escalation_verified": false,
    "escalation_proof_level": null
  },
  "unlocked_pathways": [1, 2, 3, 4],
  "locked_pathways": [5, 6, 7],
  "pilot_unlock": "LOCKED",
  "pilot_unlock_requirements": [
    {
      "gate": "authority",
      "current": "site (email_signature)",
      "required": "district (district_reply or manual_override)",
      "action": "Request district introduction"
    },
    {
      "gate": "escalation",
      "current": "not verified",
      "required": "district_reply received",
      "action": "Send district intro email, include ZTAG in thread"
    },
    {
      "gate": "commitment",
      "current": "not verified",
      "required": "monthly_playmaker_commitment confirmed",
      "action": "Clarify program duration (one-time vs ongoing)"
    }
  ],
  "next_action": {
    "action": "quote_edu_pricing",
    "mode": "DEPLOYABLE",
    "message": "Integrity verified. Site-level authority confirmed. Proceed with EDU quote."
  },
  "ui_state": "DEPLOYABLE"
}

Critical rule:

UI states:

3. POST /api/pathway/route (REVISED - Runs After Gating)

Purpose: Deterministic pathway selection AFTER gating

(Same as v2.0, but now runs AFTER /sense-intent + /gate)

Request:

{
  "unlocked_pathways": [1, 2, 3, 4],
  "organization_type": "nonprofit_pta",
  "program_type": "after_school",
  "funding_source": "pta_fundraising",
  "location_type": "in_school"
}

Response:

{
  "recommended_pathway": 2,
  "pathway_name": "3rd-Party After-School (PTA/Nonprofit)",
  "pricing_tier": "EDU",
  "confidence": 0.9,
  "reasoning": "PTA nonprofit + supervised + in-school → EDU pricing",
  "next_steps": [
    "Verify 501(c)(3) status (if applicable)",
    "Generate EDU pricing quote",
    "Prepare funding packet if grant-funded"
  ]
}

4. Reroute Layer (REVISED - No More STOP)

OLD (v2.0): Integrity FAIL → STOP (dead-end)

NEW (v2.1): Integrity FAIL → Reroute Recommendation

Example:

{
  "integrity_pass": false,
  "integrity_failure_reason": "Drop-off model detected (unsupervised)",
  "reroute": {
    "recommended_pathway": 5,
    "pathway_name": "Operator Partnership (Exposure)",
    "message": "This sounds like a great opportunity for your students to experience ZTAG through an authorized operator.",
    "next_action": "Route to Quan for operator partnership discussion",
    "ui_state": "REROUTE_TO_QUAN"
  }
}

Reroute options:

Now: Exposure still happens, just not vapor installs (unsupervised EDU pricing)

UI State Modes (User-Facing)

UI State Meaning to Carmee Backend State Actions Available
EXPLORING Still sensing intent, ask follow-ups Pre-gate (sense-intent only) Ask questions, gather signals
ESCALATING Request district intro Gate: integrity PASS, authority=site Send district intro email
DEPLOYABLE Quote allowed Gate: integrity PASS, authority verified Generate quote, send proposal
PILOT_ELIGIBLE Kristin route allowed Full gate pass (high-proof sources) Route to Kristin/Quan for Pilot
REROUTE_TO_QUAN Integrity fail, suggest operator Integrity FAIL Route to Quan (Pathway 5/7)

Key: Carmee never sees "locked" or "permission denied" language. She sees modes that guide next action.

Proof Levels (Verification Sources)

What they SAID (low proof):

What they DID (high proof):

Pilot unlock requires: High-proof sources ONLY (district_reply or manual_override)

Example Flow (Discovery → Gating → Deployment)

Inquiry:

"We're a PTA exploring after-school enrichment for 200 kids at Lincoln Elementary."

Step 1: Sense Intent

{
  "likely_tracks": [{"pathway": 2, "confidence": 0.72}],
  "missing_signals": ["supervision_model", "authority_level"],
  "suggested_questions": [
    "Would this be supervised by PTA volunteers or school staff?",
    "Is the PTA working independently or partnering with the school district?"
  ],
  "ui_state": "EXPLORING"
}

Carmee asks: "Would this be supervised by PTA volunteers or school staff?"

Response:

"PTA volunteers will supervise, with games led by a trained Playmaker."

Step 2: Gate (After Discovery)

{
  "gates": {
    "integrity_pass": true,
    "integrity_proof_level": "conversation_claim",
    "authority_level": "site",
    "authority_proof_level": "email_signature"
  },
  "unlocked_pathways": [1, 2, 3, 4],
  "pilot_unlock": "LOCKED",
  "ui_state": "DEPLOYABLE"
}

Step 3: Route

{
  "recommended_pathway": 2,
  "pathway_name": "3rd-Party After-School (PTA)",
  "pricing_tier": "EDU"
}

Step 4: Quote

If Sarah later says: "The district is interested if this works at Lincoln."

Step 5: Escalate

{
  "next_action": "request_district_intro",
  "message": "Request district introduction email",
  "ui_state": "ESCALATING"
}

If district replies + ZTAG in thread:

Step 6: Pilot Eligible

{
  "pilot_unlock": "ELIGIBLE",
  "ui_state": "PILOT_ELIGIBLE",
  "next_action": "Route to Kristin/Quan for Pilot terms"
}

Implementation Plan (3 Phases - REVISED)

Phase 1: Conversational Discovery + Gating (Week 1-2)

Build:

  1. POST /api/pathway/sense-intent (NL exploration, hypothesis generation)
  2. POST /api/pathway/gate (with verification sources)
  3. POST /api/pathway/route (deterministic pathway selection)
  4. POST /api/pathway/generate-quote (pricing + PDF)
  5. Simple web UI with state modes (Exploring → Escalating → Deployable)

Test:

Success metrics:

Phase 2 & 3: Same as v2.0

(No changes - eligibility verification, funding packets, Battle Kits, Zoho integration)

Success Metrics (90 Days)

Conversational quality:

Governance compliance:

Efficiency:

Critical Changes from v2.0

Added:

Changed:

Removed:

Golden Rule (Repeat for Emphasis)

"Never let the model unlock anything from what they said. Only from what they've done."

What this means:

Why it matters:

Status: Ready for review. Spec revised with conversational discovery + proof-based gating.

File: plans/carmee-pathway-api-spec-v2.1.md
Created: 2026-02-18
Based on: Quan's feedback (sense-intent layer, verification sources, UI states, reroute not stop)