SynapseHealer 🧠⚡

Autonomous Dead-Letter & Schema Healer for InterSystems IRIS Interoperability
InterSystems Programming Contest: AI Agents in Interoperability Workflows

🌟 Executive Summary

In enterprise healthcare and commerce, the Dead-Letter Queue (DLQ) is notoriously known as the graveyard of critical transactions. When third-party vendors update formats without notice, emit malformed dates, swap HL7 segments, or stringify numeric fields, integration engines reject the messages. In traditional workflows, these messages sit in the DLQ until an engineer manually reviews, edits, and re-injects them days or weeks later.

SynapseHealer transforms the dead-letter queue into an autonomous, self-healing interoperability pipeline:

1. Intercepts & Ingests: A Custom Inbound Adapter with Embedded Python captures or synthetically generates realistic anomalies.
2. Vector Similarity Diagnosis: Native IRIS Vector Search (VECTOR_COSINE) queries a 384-dimensional %AI.RAG knowledge base of validated repair runbooks in < 45ms.
3. Governed Decision Agent: An InterSystems %AI.Agent with governed tools (SearchRunbookRAG, ValidateRepairedPayload, CalculateRiskScore) diagnoses root causes, repairs corrupted schemas, and validates compliance.
4. Tri-Branch Delivery: High-confidence repairs (Confidence >= 88%, Risk = LOW) are automatically dispatched downstream; ambiguous or risky payloads are escalated to the InterSystems Workflow Engine for Human-in-the-Loop (HITL) approval; unrecoverable corruption is safely isolated in the Quarantine Vault.
5. Real-Time Observability: A Next.js 14 dashboard provides live telemetry, 1-click chaos scenario injection, side-by-side diffing, and one-click operator task approvals.

🎥 Live Video Walkthrough & Interactive Demo

📹 Watch Full HD Video: https://github.com/Josephjbassey/synapse-healer/blob/main/docs/demo/synapse-healer-walkthrough.mp4 (1080p 25fps) showing real-time chaos injection, automatic HL7 segment re-ordering, JSON type coercion, and Human Workflow task approval.

🏆 Contest Scorecard & Bonus Points

SynapseHealer was architected specifically to maximize all technical criteria and bonus opportunities of the AI Agents in Interoperability Workflows programming contest:

🏗️ Architecture & Pipeline Flow

flowchart TD
    subgraph Inbound ["1. Chaos & Dead-Letter Ingestion"]
        A["Inbound DLQ / Malformed Messages"] --> B["Synapse.Adapter.DeadLetterInbound
(Custom Adapter + Embedded Python)"]
        B --> C["Synapse.Service.ChaosIngestService
(Business Service)"]
        C -->|Audit to ^Synapse.DLQ| D["Synapse.Msg.DeadLetterRequest"]
    end
subgraph Process ["2. Governed Decision & Repair"]
    D --> E["Synapse.Process.DeadLetterHealerBP<br/>(Business Process / Arbitrator)"]
    E --> F["Synapse.RAG.SchemaKnowledgeBase<br/>(IRIS Vector Search: VECTOR_COSINE)"]
    F -.->|Cosine Similarity >= 0.85| E
    E --> G["Synapse.Agent.DeadLetterHealerAgent<br/>(%AI.Agent / Replay Engine)"]
    G --> H["Synapse.Agent.HealerToolSet<br/>(Governed HealerTools)"]
    H -.->|ValidateRepairedPayload| G
    G --> I["Synapse.Msg.HealResponse"]
end

subgraph Outbound ["3. Tri-Branch Delivery & HITL"]
    I --> J{Confidence & Risk Evaluation}
    J -->|Confidence >= 0.88<br/>Risk LOW| K["Synapse.Operation.ResubmitDeliveryOp<br/>(Downstream Dispatch -> /tmp/synapse/delivered)"]
    J -->|Risk HIGH / Confidence < 0.88| L["Synapse.Operation.WorkflowEscalationOp<br/>(InterSystems Workflow Engine -> TaskQueue)"]
    J -->|Corrupt / Critical Risk| M["Synapse.Operation.QuarantineVaultOp<br/>(Isolated Vault -> /tmp/synapse/quarantine)"]
end

subgraph UI ["4. Next.js Observability & HITL Workspace"]
    N["Synapse.REST.Dispatch (/api/synapse)"] <---> O["Next.js 14 Dashboard (ui/)"]
    O -.->|Operator APPROVE / REJECT| L
    O -.->|Inject 7 Canonical Scenarios| B
end

⚡ The 7 Canonical Chaos Scenarios

SynapseHealer includes ready-to-test runbooks and regression handlers for 7 canonical enterprise failure patterns:

🚀 Quick-Start Guide for Judges

1. Prerequisites & InterSystems IRIS AI Hub Container Image

SynapseHealer runs on the official InterSystems IRIS Community AI Hub Early Access Program (EAP) build:

• EAP Download Portal: https://evaluation.intersystems.com/Eval/early-access/AIHub
• Supported builds: 2027.1.0AI.109.0 or 2026.3.0AI.154.0.

Loading the Docker Tarball

# For x86_64:
docker load -i iris-community-2027.1.0AI.109.0-docker.tar.gz
(Optional) Tag image if using standard tag:
docker tag iris-community:2027.1.0AI.109.0 iris-community:2026.3.0AI.154.0
For ARM64 (Apple Silicon):
docker load -i iris-community-arm64-2027.1.0AI.109.0-docker.tar.gz

2. Zero-Key Replay Mode vs. Live AI Hub Mode

SynapseHealer offers two seamless operating modes:

Mode A: Zero-Key Replay Mode (Default — Zero API Keys Required)

Judges can test 100% of the functionality, vector similarity search, governed tool call sequences, side-by-side payload transformations, and human workflow approvals immediately without providing an external API key:

# 1. Start the IRIS container (iris.script auto-configures SYNAPSE and starts the production)
docker compose up -d
2. Start the Observability UI
cd ui
npm install
npm run dev

Open http://localhost:3000 in your browser!

Mode B: Live AI Hub Mode (Gemini or OpenAI)

To enable live LLM reasoning via %AI.Agent:

# Copy environment configuration
cp .env.example .env
Edit .env:
SYNAPSE_MODE=live
LLM_PROVIDER=gemini           # or openai
LLM_API_KEY=your_gemini_or_openai_key
LLM_MODEL=gemini-1.5-flash    # or gpt-4o-mini
Restart container
docker compose up -d

Credentials are saved into the secure InterSystems IRIS Wallet (%Wallet.KeyValue) without ever exposing secrets in plaintext logs.

🖥️ Next.js Observability & HITL Dashboard (ui/)

The web UI is built with Next.js 14 (App Router), TypeScript, and Tailwind CSS:

cd ui
npm run dev

Dashboard Features:

1. Top Telemetry Ribbon: Real-time status badge (REPLAY MODE vs LIVE AI HUB), Interoperability production online indicator, Auto-Heal Rate KPI (90%+), cumulative token counters, inference cost tracker (USD), and average latency monitor.
2. Panel 1 (Chaos Injector): 1-click execution for all 7 canonical error scenarios, plus a Custom Payload Injection Modal allowing judges to paste any raw HL7 or JSON message.
3. Panel 2 (Side-by-Side Diff & Agent Reasoning):
   • Left: Malformed inbound payload with exact validation error.
   • Center: Matched %AI.RAG runbook, narrative agent diagnosis, and step-by-step governed tool execution trace (SearchRunbookRAG -> ValidateRepairedPayload -> CalculateRiskScore).
   • Right: Schema-validated healed payload marked for automated downstream dispatch.
4. Panel 3 (Multi-Tab Inspector):
   • Human Workflow Queue: Review pending tasks escalated by WorkflowEscalationOp. Click Approve (routes to ResubmitDeliveryOp) or Reject (routes to QuarantineVaultOp) with operator notes.
   • IRIS Vector Search Runbooks: Live inspector of all 10 vector-indexed schema repair patterns.
   • Live Telemetry Traces: Chronological audit ledger stored in Synapse_Data.AuditTelemetry.

📡 Live REST API Reference (/api/synapse)

All endpoints are hosted natively by Synapse.REST.Dispatch under the /api/synapse CSP web application on port 52773:

1. System Health & Aggregate Telemetry

curl -u _SYSTEM:SYS http://localhost:52773/api/synapse/status

Sample Response:

{
  "mode": "replay",
  "llmProvider": "gemini",
  "llmModel": "gemini-1.5-flash",
  "hasApiKey": 0,
  "productionRunning": 1,
  "runbookCount": 10,
  "totalProcessed": 10,
  "autoHealedCount": 9,
  "workflowPendingCount": 0,
  "quarantinedCount": 0,
  "totalTokens": 6631,
  "estimatedCostUSD": 0.0018,
  "avgLatencyMs": 145,
  "autoHealRate": 90.0
}

2. Inject Chaos Scenario Live

# Inject Scenario 4 (Stringified numbers in JSON order)
curl -X POST -u _SYSTEM:SYS http://localhost:52773/api/synapse/inject \
  -H "Content-Type: application/json" \
  -d '{"scenarioId": 4}'
Inject Scenario 1 (HL7 PID/PV1 swapped fields)
curl -X POST -u _SYSTEM:SYS http://localhost:52773/api/synapse/inject 

-H "Content-Type: application/json" 

-d '{"scenarioId": 1}'

3. Query Active Workflow Tasks

curl -u _SYSTEM:SYS http://localhost:52773/api/synapse/workflow/tasks

4. Approve or Reject a Workflow Task

curl -X POST -u _SYSTEM:SYS http://localhost:52773/api/synapse/workflow/resolve \
  -H "Content-Type: application/json" \
  -d '{
    "payloadId": "SYN-HL7-D9B31D3B",
    "action": "APPROVE",
    "reviewerNotes": "Approved by contest judge"
  }'

📦 InterSystems Package Manager (IPM / ZPM)

SynapseHealer is packaged as an official IPM module certified for InterSystems IRIS:

• Manifest: https://github.com/Josephjbassey/synapse-healer/blob/main/module.xml
• Declared dependencies: <SystemRequirements Version=">=2026.3" Interoperability="enabled"/>

Installation via IPM:

// Inside IRIS terminal or container:
zpm "install synapse-healer"
// Or test load from source:
zpm "load /opt/irisapp -v"

The module automatically executes <Invoke Method="SetupAll" Class="Synapse.Config.AIHubSetup"/> upon installation, configuring AI Hub credentials, seeding the 10 vector runbooks, loading historical telemetry, and auto-starting the Interoperability Production Synapse.Production.

📂 Source Code Map

📄 License & Acknowledgements

• Built for the InterSystems Programming Contest: AI Agents in Interoperability Workflows (2026).
• Licensed under the MIT License.