ContextIQ

Turning escalation noise into a clear signal.

An AI pipeline that ingests messy customer escalation artifacts and produces decision-ready context with a full audit trail in under 1 minute.

Overview

ContextIQ is a 5-agent escalation context synthesis pipeline. It ingests raw artifacts from multiple systems (email, Zendesk, Slack, Jira, telemetry, postmortems) and produces:

• A structured triage brief with confirmed facts and timeline
• A root cause analysis (5-Whys causal chain)
• A conflict detection report (contradictions between sources)
• Three stakeholder-specific communications (customer update, executive brief, engineering handoff)
• A 100% citation-covered audit manifest tracing every claim back to its source

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Configure your LLM endpoint

Copy .env.example to .env and fill in your credentials:

cp .env.example .env
# Edit .env with your FOUNDRY_ENDPOINT + FOUNDRY_API_KEY, or OPENAI_API_KEY

Then export the variables (or use a tool like python-dotenv):

# On Windows (PowerShell)
$env:OPENAI_API_KEY = "your-key-here"

# On Mac/Linux
export OPENAI_API_KEY="your-key-here"

3. Run the demo

python demo.py --scenario northwind
python demo.py --scenario contoso
python demo.py --scenario fabrikam

4. Run the benchmark

python benchmark.py

Outputs are saved to outputs/<run_id>/.

Architecture

                    ┌─────────────────────────────────┐
                    │     Escalation Artifacts (7)     │
                    │  email · ticket · slack · jira   │
                    │  telemetry · postmortem · CRM    │
                    └────────────────┬────────────────┘
                                     │
                              ┌──────▼──────┐
                              │  Agent 1:   │
                              │  Ingestion  │
                              └──────┬──────┘
                                     │ EscalationContext
                              ┌──────▼──────┐
                              │  Agent 2:   │
                              │  Synthesis  │
                              └──────┬──────┘
                                     │ SynthesisReport
                              ┌──────▼──────┐
                              │  Agent 3:   │
                              │    RCA      │
                              └──────┬──────┘
                                     │ RCAReport
                              ┌──────▼──────┐
                              │  Agent 4:   │
                              │  Conflict   │
                              │  Detector   │
                              └──────┬──────┘
                                     │ ConflictReport
                              ┌──────▼──────┐
                              │  Agent 5:   │
                              │   Comms     │
                              │  Generator  │
                              └──────┬──────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │         Pipeline Outputs         │
                    │  customer_update.md              │
                    │  executive_brief.md              │
                    │  engineering_handoff.md          │
                    │  audit_manifest.json             │
                    │  rca_chain.json                  │
                    │  conflict_report.json            │
                    └─────────────────────────────────┘

The 5 Agents

Agent	File	Role
1. Ingestion	agents/ingestion.py	Reads and validates all JSON artifacts from the scenario directory into a unified EscalationContext
2. Synthesis	agents/synthesis.py	Extracts confirmed facts, builds a chronological timeline, identifies key metrics, and forms an initial hypothesis
3. RCA	agents/rca.py	Two-pass root cause analysis: first inventories all evidence, then builds a 5-Whys causal chain distinguishing active from resolved issues
4. Conflict Detector	agents/conflict_detector.py	Identifies contradictions between sources (e.g., engineering says fixed; customer says still broken) and uses RCA to determine which conflicts are resolved
5. Comms Generator	agents/comms_generator.py	Generates three stakeholder-specific Markdown documents with a 100% citation-covered audit manifest

Scenarios

Northwind Logistics — Shipment Visibility Dashboard (7 artifacts)

A strategic account ($1.8M ARR, renewal March 31) is experiencing recurring data mismatches on their shipment visibility dashboard. Engineering closed the incident (INC-4471) after a currency fix in release 4.8.2, but mismatches persist — concentrated in international/multi-leg shipments. A related Jira ticket (ENG-3321) covering general cache invalidation for international routes is sitting at medium priority in the backlog.

Key tension: Engineering believes the fix resolved the issue. Telemetry shows 23 stale cache detections post-4.8.2 and a 24x error rate differential between international and domestic shipments.

Contoso Cloud Services — API Rate Limiting (5 artifacts)

An enterprise customer ($2M ARR) is receiving HTTP 429 errors during peak hours despite operating within their documented 1000 req/min limit. Engineering initially blamed client-side request bursts. Internal investigation reveals the API gateway applies an aggregate rate limit of 1000 req/min across ALL enterprise clients for the data-pipeline service — a misconfiguration inherited from a single-tenant setup (ENG-5501, backlog).

Key tension: Support team told the customer to fix their client for a week while the root cause was a known server-side configuration bug.

Fabrikam Financial — Data Migration Duplicates (6 artifacts)

A financial services customer discovered 847 duplicate transaction records after a migration. Engineering initially claimed the duplicates were in the source data. Migration log analysis reveals 3 batch retries (batches 7, 12, 19) where the retry logic re-ran entire batches without idempotency checks — duplicating any records that had partially committed before timeout. A known Jira ticket (ENG-7890) describing exactly this risk had been assigned low priority.

Key tension: Engineering said "migration completed successfully." The migration log shows "Records processed: 94,847" against a source count of 94,000 — a discrepancy the tool logged but did not flag as an error.

Running demo.py

# Run the default Northwind scenario
python demo.py

# Run a specific scenario
python demo.py --scenario contoso
python demo.py --scenario fabrikam

# Use a custom scenarios directory
python demo.py --scenario northwind --scenarios-dir /path/to/scenarios

Sample output:

============================================================
  ContextIQ — Escalation Context Synthesizer
  Scenario: NORTHWIND
  Run ID: northwind_20240315T083000
============================================================

Step 1/5: Artifact Ingestion
  [ingestion] completed in 0.01s
  Loaded 7 artifacts

Step 2/5: Context Synthesis
  [synthesis] completed in 12.45s
  Extracted 12 confirmed facts
...

Running benchmark.py

python benchmark.py

Runs all 3 scenarios × 3 runs each (9 total runs) and produces a comparison report.

KPI Targets

KPI	Target	Description
Total pipeline time	< 60 seconds	End-to-end for a single scenario
Context assembly	< 300 seconds	Ingestion + Synthesis combined
Conflict detection	< 30 seconds	Agent 4 execution time
Audit trail coverage	100%	Every claim cited to a source artifact

Configuration

All configuration is via environment variables:

Variable	Default	Description
FOUNDRY_ENDPOINT	(none)	Azure AI Foundry endpoint URL
FOUNDRY_API_KEY	(none)	Azure AI Foundry API key
OPENAI_API_KEY	(none)	OpenAI API key (alternative to Foundry)
MODEL_NAME	gpt-4o-mini	Model to use for all agents
LOG_LEVEL	INFO	Logging level

Output Files

Each run produces a directory at outputs/<run_id>/:

File	Description
triage_brief.json	Synthesis report: facts, timeline, metrics, hypothesis
rca_chain.json	Full causal chain with dead branches and root cause
conflict_report.json	All detected contradictions between sources
audit_manifest.json	Citation index for all claims in communications
customer_update.md	Non-technical customer-facing update
executive_brief.md	One-page executive summary
engineering_handoff.md	Technical handoff with acceptance criteria
run_metrics.json	Timing and configuration for this run