SOW Technical Study Guide

0.6 EAII in context

The bet behind EAII: modern LLMs are stateless about emotion. They can sound empathetic in any single response but have no representation of where the user is in an emotional trajectory across turns. EAII fills that gap as an infrastructure layer: an API any AI system can call to get a structured emotional state on each user message. Anthropic's April 2026 interpretability research is supporting evidence that emotion concepts are a meaningful internal representation in modern models; EAII externalizes that representation into a standardized format any downstream AI can consume programmatically.

0.7 The two-phase build

Phase 1 ends. Phase 2 begins. The architecture is built so the transition is just swapping the engine file behind a stable interface, not redesigning anything around it.

0.8 The 12 deliverable groups (just the list)

1. Investor Demo App (public-facing React app)
2. Internal Tools (admin web app: 5 sub-tools)
3. Modular Backend / API Service (FastAPI)
4. Event Schema and Data Pipeline (canonical envelope, 7 event types)
5. Engine v0 (placeholder thin LLM wrapper)
6. Safety Framework (deterministic crisis-keyword override)
7. Infrastructure (AWS, Docker, observability, retention)
8. Developer Interface (OpenAPI spec, Python shadow-mode reference)
9. Documentation and Handover (runbooks, ADRs, replacement guide)
10. UI Design Pattern Selection (3 design tiles)
11. Prototype Evaluation Framework (synthetic corpus, baselines, summary)
12. External-LLM-Output Scoring (additive workstream, added Apr 28)

0.9 The architecture in 3 boxes

The frontend is two React apps (public demo, internal tools). The backend is a containerized FastAPI service that does input validation, runs a safety check, calls the engine, and writes events. The storage layer holds events, cache, and async queue. All of it runs on AWS.

0.10 The timeline at a glance

About 2 months in, the team is roughly between foundation and internal tools.

0.11 The technology stack at a glance

Python (FastAPI) for the backend. React for both frontends. PostgreSQL for the event store (originally MongoDB, swapping for technical reasons). Valkey for cache (originally Redis, drop-in replacement). RabbitMQ for async queue. Azure OpenAI as the LLM provider (gpt-4.1-mini in East US). AWS for cloud hosting (EC2, ECS, S3, CloudWatch). Docker plus Docker Compose for local dev. GitHub Actions for CI/CD. OpenTofu for infrastructure-as-code (originally Terraform, drop-in replacement).

0.12 Why it matters strategically

0.13 What you need to walk into Monday with

Confident command of: what each of the 12 deliverables is, the request flow through the system end to end, the engine boundary and how it makes the Phase 2 swap clean, the taxonomy shape (~30 fields in 10 layers), the 7 event types and how they link, the safety pipeline running before the engine, the technology stack and why three components are being changed, and the technical questions David might raise with answers ready. Those are all built out in Tabs 3, 4, and 5.

1.1 What Pivot is building, in one paragraph

Pivot is building the scaffolding for the EAII platform: an API service, a data pipeline, a placeholder "Engine v0" (a thin LLM wrapper), an investor-facing demo app, internal tools (debugger, dashboard, labeling, simulator, research playground), a deterministic safety pipeline, and the cloud infrastructure to run it all. The output of the system is a structured emotional state representation that downstream AI applications can consume through a standardized API. Phase 1 deliberately stops short of real emotional intelligence so Phase 2 (the actual engine) can plug in cleanly later.

1.2 Phase 1 vs Phase 2 (the most important framing)

Phase 1's whole purpose is to build the infrastructure so Phase 2 can plug in cleanly. The SOW says this in §3.5.1, §3.7.7, and §9.1: Engine v0 is "explicitly replaceable and not a long-term EAII intelligence system." The real intelligence comes later.

1.3 The 12 deliverable groups

1.4 The timeline (9 milestones, 14-week core build)

~2 months in, we are most likely between M2 and M5 (orange-highlighted). M6 (Demo App alpha) and M7 (Internal Tools) are the biggest remaining workstreams.

1.5 The architecture in 30,000 ft view

USER ACTION (typing in the demo app)
        |
        v
[Frontend: React] sends JSON request with API key
        |
        v
[API Gateway: Kong] checks API key, applies rate limit
        |
        v
[Backend: FastAPI Service]
   1. Validates and normalizes input
   2. Runs Safety Pipeline check (BEFORE any LLM call)
   3. Calls engine.analyze() at the engine interface boundary
   4. Engine v0 calls Azure OpenAI, validates the JSON output
   5. Optionally calls engine.respond() to generate a response
   6. Writes Message Event, Analysis Event, Response Event
        |
        v
[Event Store: MongoDB or Postgres] persists every event
        |
        v
[Internal Tools] reads from event store

1.6 What the system actually DOES (one user request, walked through)

A user types: "I'm so frustrated with this, nothing is working and I don't know what to do."

That is one round trip through the entire Phase 1 system. Every component in the architecture earned its place in those 12 steps.

1.7 The technology stack at a glance

1.8 Why three stack components are being changed (technical reasoning)

The technical case for these swaps is clean: same or better functionality for the EAII workload, no operational regression. They are pragmatic choices.

1.9 The engine boundary (where Phase 1 ends, Phase 2 begins)

This is the single most important architectural concept in the whole SOW. Pivot is building Phase 1 with a stable interface around the engine:

engine.analyze(canonical_input) -> analysis_output
engine.respond(canonical_input, analysis_output?) -> response_output

Technical mechanisms enforcing this boundary:

• The engine interface contract (§3.3.9): two stable function signatures.
• Engine version routing (§3.3.9): server default DEFAULT_ENGINE_VERSION plus optional X-Engine-Version header for internal-tool overrides.
• Microservice readiness (§3.7.7): engine isolation boundary required, horizontal scaling readiness.

1.10 What success looks like for Phase 1

When Pivot finishes, you should have:

• A FastAPI service running in AWS staging and production with /v1/emotions/analyze, /v1/emotions/respond, /health, /ready endpoints.
• A working Investor Demo App at a public URL where Patrick can take an investor through a live conversation and see the emotional visualization update in real time.
• An admin internal tools site where the team can debug interactions, see dashboards, label data, run the simulator, and use the research playground.
• An event store containing every Message, Analysis, Response, and Feedback event in canonical envelope format.
• A safety pipeline that deterministically intercepts crisis-pattern inputs.
• An evaluation summary document showing the EAII structured output beats simple sentiment on illustrative scenarios.
• A handover package: runbooks, ADRs, env vars, deployment instructions, an "engine replacement guide" describing how Phase 2 will plug in.

2.1 The architecture, drawn

2.2 The 12 deliverable groups, deeper

2.3 Key technical concepts, simplified

class AnalysisOutput(BaseModel):
    emotion: str
    valence: Literal["positive", "neutral", "negative"]
    intensity: Literal["low", "medium", "high"]
    confidence: float

# At validation time:
parsed = AnalysisOutput.model_validate_json(raw_llm_response)
# Throws ValidationError if the LLM returned malformed JSON
# or a value outside the allowed Literal range.

CREATE TABLE events (
  id UUID PRIMARY KEY,
  event_type VARCHAR(50),
  occurred_at TIMESTAMP,
  payload JSONB
);

SELECT * FROM events
WHERE event_type = 'analysis'
  AND payload->>'emotion' = 'frustrated'
  AND (payload->>'overall_confidence')::float > 0.8;

2.4 Engine v0 walkthrough (the disposable LLM wrapper)

Engine v0 is roughly:

def analyze(canonical_input):
    text = canonical_input.text

    # Deterministic normalization
    normalized = trim_and_collapse_whitespace(text)
    norm_hash = hash(normalized)

    # Cache check (for demo stability)
    if cache.has(norm_hash):
        return cache.get(norm_hash)

    # Build prompt
    prompt = render_prompt(
        prompt_version="v0.1",
        text=normalized,
        recent_context=canonical_input.context
    )

    # Call LLM via AI gateway
    raw_response = ai_gateway.chat(
        provider="azure_openai",
        model="gpt-4.1-mini",
        messages=[{"role": "user", "content": prompt}],
        response_format={"type": "json_object"}
    )

    # Validate output against schema
    try:
        parsed = AnalysisOutput.model_validate_json(raw_response)
    except ValidationError as e:
        return fallback_response(reason="parse_error", error=e)

    # Confidence gating
    if parsed.overall_confidence < CONFIDENCE_THRESHOLD:
        return fallback_response(reason="low_confidence")

    # Stamp trace fields
    parsed.trace.model_id = "gpt-4.1-mini"
    parsed.trace.prompt_version = "v0.1"
    parsed.trace.normalization_hash = norm_hash
    parsed.trace.engine_version = "v0"
    parsed.trace.engine_config_id = "v0:strict-thresholds"
    parsed.trace.cache_status = "miss"
    parsed.trace.latency_ms = elapsed_ms()

    # Cache for stability
    cache.set(norm_hash, parsed)

    return parsed

That is roughly 30 lines of pseudocode capturing what Engine v0 actually does. Not magical, not ML, just disciplined glue around an LLM call.

In Phase 2, Engine v2.0 will replace this file. The analyze function will load a fine-tuned model with torch.load() and run inference locally instead of calling Azure. Same function signature, same return shape, same caller.

3.1 The taxonomy fields, deeply

The shape of every Analysis Event. Approximately 30 fields organized into 10 layers.

3.2 The 7 event types

3.3 Causal links (how Debugger reconstructs a session)

Message Event   { event_id: M1, message_id: msg-abc }
   |
   | message_event_id=M1
   v
Analysis Event  { event_id: A1, message_event_id: M1 }
   |
   | message_event_id=M1, analysis_event_id=A1
   v
Response Event  { event_id: R1, message_event_id: M1, analysis_event_id: A1 }
   |
   | analysis_event_id=A1, response_event_id=R1
   v
Feedback Event  { analysis_event_id: A1, response_event_id: R1 }

This is also what makes the export endpoint work: pull all events with the same session_id, reassemble by causal IDs.

3.4 The two endpoints flow

POST /v1/emotions/analyze:
   text -> analysis (taxonomy, no response generated)

POST /v1/emotions/respond:
   text + optional analysis ->
   1. If analysis not provided, run engine.analyze() first
   2. Run safety check; if triggered, return safety template
   3. Pick response_strategy + response_mode from analysis
   4. Generate response text via LLM (or template)
   5. Return both analysis AND response

Why two endpoints: a shadow-mode partner only needs /analyze (they keep their own response). A full integration uses /respond to get EAII-generated text.

3.5 Sample Message Event shape

{
  "event_id": "evt-001",
  "event_type": "message",
  "schema_version": "1.0",
  "occurred_at": "2026-05-08T14:30:00Z",
  "ingested_at": "2026-05-08T14:30:00.123Z",
  "environment": "production",
  "request_id": "req-abc-123",
  "session_id": "ses-hmac-xyz",
  "conversation_id": "conv-456",
  "actor": { "type": "user", "id": "user-hmac-pseudo" },
  "client_context": { "platform": "web" },
  "engine_context": {
    "engine": "v0",
    "version": "0.1",
    "config_hash": "..."
  },
  "message_id": "msg-001",
  "text": "I'm so frustrated, nothing is working",
  "normalized_text": "i'm so frustrated, nothing is working",
  "language_hint": "en",
  "input_modality": "text",
  "text_hash": "sha256-abc",
  "contains_sensitive_markers": false
}

3.6 Technical questions David might raise (and the answers ready)

David's framing of "are you sure you can handle this?" will probably come as specific technical questions. Drill these.

3.7 Glossary

End of guide. Now go drill it Friday.