← Back to Index

Carmee Pathway API - Full Specification v2.2

Version: 2.2 (FINAL - Intent Inference + State Machine Gating)
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.1

V2.1 PROBLEM:

V2.2 SOLUTION:

Mental model shift:

v2.1: "Has this inquiry earned the right to proceed?"
v2.2: "What future is this org leaning toward — and what must they do to earn it?"

Architecture (Final)

Inquiry
  ↓
Intent Inference (NL, probabilistic - THE SORTING HAT)
  ↓
Conversation Support (guide toward requirements)
  ↓
Gate State Tracker (state machine, not pass/fail)
  ↓
Unlocks (pathways accessible based on state)
  ↓
Route (deterministic pathway selection)
  ↓
Quote / Pilot Overlay

Key principle:

API Endpoints (Final)

1. POST /api/pathway/intent (NEW - RUNS FIRST)

Purpose: Infer what future this org is leaning toward (conversational, probabilistic)

Request:

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

Response:

{
  "likely_track": "pilot_candidate",
  "confidence": 0.62,
  "reasoning": "PTA + 200 kids + 'exploring' language suggests district-scale intent",
  "alternate_tracks": [
    {"track": "site_deployment", "confidence": 0.31},
    {"track": "3rd_party_nonprofit", "confidence": 0.18}
  ],
  "signals_detected": {
    "scale_language": true,
    "budget_conscious": false,
    "supervision_mentioned": false,
    "district_involvement": "UNKNOWN"
  },
  "missing_requirements": [
    "district_authority (currently site-level PTA)",
    "monthly_playmaker_commitment (duration unclear)",
    "supervision_model (staff vs volunteers)"
  ],
  "suggested_questions": [
    "Would your district be open to evaluating this across other sites if Lincoln is successful?",
    "Is the PTA working independently or partnering with the school administration?",
    "What does success look like for your program this year?"
  ],
  "pilot_state": "NURTURE",
  "ui_state": "EXPLORING"
}

Pilot states (progression):

Meaning for Carmee:

2. POST /api/pathway/gate (REVISED - State Machine, Not Binary)

Purpose: Track progression state (what's known, what's missing, what's next)

Request:

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

Response:

{
  "gate_state": {
    "integrity": {
      "state": "VERIFIED",
      "confidence": 0.85,
      "proof_level": "conversation_claim",
      "ready_to_quote": true,
      "blockers": []
    },
    "authority": {
      "state": "KNOWN",
      "level": "site",
      "confidence": 0.7,
      "proof_level": "email_signature",
      "escalation_needed": true,
      "next_action": "Request district introduction"
    },
    "pilot_requirements": {
      "state": "POTENTIAL",
      "met_requirements": ["integrity_verified", "supervised_model_confirmed"],
      "unmet_requirements": [
        {
          "requirement": "district_authority",
          "current_state": "site-level only",
          "needed_proof": "district_reply or forwarded_email",
          "action": "Send district intro email template"
        },
        {
          "requirement": "monthly_commitment",
          "current_state": "UNKNOWN",
          "needed_proof": "conversation_claim or contract",
          "action": "Clarify program duration (one-time vs ongoing)"
        }
      ],
      "pilot_state": "POTENTIAL"
    }
  },
  "unlocked_pathways": [1, 2, 3, 4],
  "locked_pathways": [5, 6, 7],
  "deployment_permissions": {
    "can_quote": true,
    "can_send_proposal": true,
    "can_route_to_pilot": false,
    "pilot_state": "POTENTIAL",
    "pilot_state_message": "Pilot track identified. Request district introduction to advance to ELIGIBLE."
  },
  "next_actions": [
    {
      "action": "generate_quote",
      "priority": "HIGH",
      "reasoning": "Integrity verified, site authority confirmed. EDU pricing quote ready."
    },
    {
      "action": "request_district_intro",
      "priority": "MEDIUM",
      "reasoning": "Pilot interest detected. District intro would advance to ELIGIBLE state."
    }
  ],
  "ui_state": "DEPLOYABLE"
}

Gate states (not binary):

Pilot states within gate:

3. POST /api/pathway/route (Same as v2.1)

Purpose: Deterministic pathway selection AFTER intent + gating

(No changes from v2.1)

4. Reroute Layer (Same as v2.1)

Purpose: Integrity failures suggest alternatives (not STOP)

(No changes from v2.1)

5. POST /api/pathway/generate-quote (Same as v2.1)

Purpose: Calculate pricing, apply discounts, generate quote PDF

(No changes from v2.1)

Pilot State Machine (Detailed)

State: NURTURE

State: POTENTIAL

State: ELIGIBLE

State: DEPLOYABLE

UI State Modes (User-Facing)

UI State Meaning to Carmee Backend State Pilot State Actions Available
EXPLORING Still sensing intent, ask follow-ups Intent inference only NURTURE Ask questions, gather signals
ESCALATING Request district intro Gate: authority=site POTENTIAL Send district intro email
DEPLOYABLE Quote allowed (non-Pilot) Gate: integrity verified POTENTIAL Generate quote, send proposal
PILOT_ELIGIBLE Route to Kris/Quan Gate: full requirements met ELIGIBLE Route to Kris/Quan for Pilot
PILOT_ACTIVE Kris/Quan approved Manual override or approval DEPLOYABLE Negotiate Pilot terms

Key: Pilot progression is visible but not unlock/lock language. Carmee sees state (NURTURE → POTENTIAL → ELIGIBLE → DEPLOYABLE).

Example Flow (Discovery → State Progression → Deployment)

Inquiry:

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

Step 1: Intent Inference

{
  "likely_track": "pilot_candidate",
  "confidence": 0.62,
  "pilot_state": "NURTURE",
  "suggested_questions": [
    "Would your district be open to evaluating this across sites?",
    "Is the PTA working independently or with school administration?"
  ],
  "ui_state": "EXPLORING"
}

Carmee asks: "Is the PTA working independently or partnering with the school district?"

Response:

"We're independent, but the principal is supportive. If this works, other schools might be interested."

Step 2: Gate (State Tracking)

{
  "gate_state": {
    "integrity": {"state": "KNOWN", "confidence": 0.7},
    "authority": {"state": "KNOWN", "level": "site"},
    "pilot_requirements": {"state": "POTENTIAL"}
  },
  "deployment_permissions": {
    "can_quote": true,
    "can_route_to_pilot": false,
    "pilot_state": "POTENTIAL"
  },
  "next_actions": [
    {"action": "generate_quote", "priority": "HIGH"},
    {"action": "request_district_intro", "priority": "MEDIUM"}
  ],
  "ui_state": "DEPLOYABLE"
}

Carmee: Generates EDU quote for Lincoln (Pathway 2), sends proposal.

2 weeks later, Sarah emails:

"Lincoln loved it! The district superintendent wants to explore rolling this out to 5 more schools next year."

Step 3: Gate State Update (Escalation Detected)

{
  "gate_state": {
    "authority": {"state": "ESCALATING", "level": "district_engaged"},
    "pilot_requirements": {"state": "POTENTIAL → advancing to ELIGIBLE"}
  },
  "next_actions": [
    {"action": "request_district_intro_email", "priority": "URGENT"}
  ],
  "ui_state": "ESCALATING"
}

Carmee: Sends district intro email template, includes ZTAG in thread.

District replies (ZTAG in thread):

"We're interested. Let's schedule a call to discuss district-wide implementation."

Step 4: Gate State Update (ELIGIBLE)

{
  "gate_state": {
    "authority": {"state": "VERIFIED", "level": "district", "proof_level": "district_reply"},
    "pilot_requirements": {
      "state": "ELIGIBLE",
      "met_requirements": ["district_reply_received", "ztag_in_thread"],
      "unmet_requirements": ["monthly_commitment (clarify on call)"]
    }
  },
  "deployment_permissions": {
    "can_route_to_pilot": true,
    "pilot_state": "ELIGIBLE"
  },
  "next_actions": [
    {"action": "route_to_kristin", "priority": "URGENT"}
  ],
  "ui_state": "PILOT_ELIGIBLE"
}

Carmee: Routes to Kristin/Quan for Pilot terms discussion.

After call, Kris/Quan approve Pilot:

Step 5: Pilot DEPLOYABLE

{
  "pilot_requirements": {"state": "DEPLOYABLE"},
  "deployment_permissions": {
    "can_negotiate_pilot": true,
    "pilot_state": "DEPLOYABLE"
  },
  "ui_state": "PILOT_ACTIVE"
}

Carmee: Negotiates Pilot pricing with district (with Kris/Quan guidance).

Proof Levels (Unchanged from v2.1)

What they SAID (low proof):

What they DID (high proof):

Pilot ELIGIBLE requires: High-proof sources ONLY

Implementation Plan (3 Phases - REVISED)

Phase 1: Intent + State Machine Gating (Week 1-2)

Build:

  1. POST /api/pathway/intent (sorting hat, probabilistic NL inference)
  2. POST /api/pathway/gate (state machine, not binary pass/fail)
  3. POST /api/pathway/route (deterministic pathway selection)
  4. POST /api/pathway/generate-quote (pricing + PDF)
  5. Simple web UI with Pilot state progression (NURTURE → POTENTIAL → ELIGIBLE → DEPLOYABLE)

Test:

Success metrics:

Phase 2 & 3: Same as v2.1

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

Success Metrics (90 Days)

Conversational quality:

Governance compliance:

Efficiency:

Critical Changes from v2.1

Added:

Changed:

Mental model shift:

v2.1: "Has this inquiry earned the right to proceed?"
v2.2: "What future is this org leaning toward — and what must they do to earn it?"

Golden Rule (Reinforced)

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

State machine enforces this:

Status: Ready for final review. Spec revised with Intent layer + state machine gating.

File: plans/carmee-pathway-api-spec-v2.2.md
Created: 2026-02-18
Based on: Quan's feedback (Intent inference, state machine, conversational support, Pilot states)

Ready to build Phase 1? (4-6 hours today)

If this aligns → I can start implementation immediately.
If adjustments needed → Let me know what to refine!

🔒 Pilot Pricing Isolation Rule (CRITICAL)

Problem: Even when pilot_state = POTENTIAL and can_quote = true, Carmee could accidentally reference district-scale language that creates expectations before requirements are met.

Real leakage happens at:

"If this works, we could look at rolling this out across the district."

That sentence creates:

Rule: When pilot_state = POTENTIAL:

{
  "deployment_permissions": {
    "can_quote": true,
    "can_send_proposal": true,
    "limit_quote_scope": "site_level_only",
    "pilot_pricing_access": false,
    "district_rollout_language": "DISABLED"
  }
}

Meaning:

Carmee CAN:

Carmee CANNOT:

Until: pilot_state >= ELIGIBLE AND proof_level >= district_reply

Why: Prevents enthusiasm from becoming perceived commitment before district engagement is verified.

Deployment Permission Matrix (Updated)

Pilot State Can Quote Site Can Reference District Can Offer Pilot Proof Required
NURTURE No No No None
POTENTIAL Yes (site-level EDU) NO (isolation rule) No Conversation claims
ELIGIBLE Yes Yes (exploratory) Via Kris/Quan only district_reply
DEPLOYABLE Yes Yes (operational) Yes (negotiation) Manual override

Key: POTENTIAL state allows site-level quoting but blocks district-scale language entirely.