DEV Community: Prasad Thiriveedi

Repair Before Replace: an AI-powered circularity assistant with persistent repair memory

Prasad Thiriveedi — Mon, 20 Apr 2026 00:30:06 +0000

This is a submission for Weekend Challenge: Earth Day Edition.

What I Built

I built Repair Before Replace, an AI-powered circularity assistant that helps people decide whether a damaged household item should be repaired at home, patched temporarily, or replaced responsibly.

The problem I wanted to solve is simple: people throw away useful items because they are unsure what is fixable, what is safe, and whether repair is worth it. I wanted to build something practical that nudges users toward repair first while still being honest about safety and limits.

The app lets a user:

choose a supported category
upload a photo of a damaged item
get a structured damage assessment
see whether the item is safe to repair at home
get materials and step-by-step guidance when DIY repair is appropriate
understand the waste impact of replacing versus repairing
benefit from persistent memory across sessions

The differentiator is memory. The app does not behave like a stateless image classifier. It remembers prior attempts, preferences, and what worked before, then uses that history to influence future recommendations.

Examples of the memory behavior:

“Your previous glue-only patch failed after washing, so this recommendation uses hand stitching instead.”

“You’ve had success with wood glue and no power tools, so the same approach applies here.”

This is an AI repair companion that gets smarter the more you use it.

Demo

Live app: Repair Before Replace

Suggested demo flow:

Sign in
Select Furniture
Upload a photo of a damaged item such as a scratched table, cracked shelf, or broken chair
Review the assessment, repair guidance, and environmental impact summary
Scroll to the repair history and note how prior attempts influence the current recommendation

Home page with sofa loaded (Furniture selected, sofa photo, Analyze Damage button)

Code

GitHub repo: repair-before-replace

How I Built It

Product approach

I intentionally did not build a generic carbon calculator.

Instead, I focused on one real-world decision:

Should I fix this, patch it, get professional help, or replace it responsibly?

That led to a much more practical Earth Day project than a broad sustainability dashboard.

Front end

The UI is built with React 19 + TypeScript + Vite + Tailwind CSS v4.

I kept the flow simple:

select category
upload photo
review structured assessment
understand the next best action
revisit repair history and memory-aware recommendations

A lot of the work here was product work, not just UI work: narrowing scope, separating safe DIY from professional repair, and making the recommendations feel trustworthy instead of overly confident.

Google Gemini

Gemini 2.5 Flash powers the core multimodal experience.

It analyzes the uploaded image and returns structured output for:

visible damage
confidence level
safety check
recommended action
materials needed
repair steps
environmental impact band
history-aware recommendation reasoning

One important design decision was using schema-constrained JSON output so the app could reliably render the same assessment structure every time.

Google AntiGravity IDE with Gemini AI

I used Google AntiGravity IDE with Gemini AI to accelerate the initial scaffold and part of the core implementation.

It helped compress the early build phases, including:

app structure
component setup
routing
service wiring
rapid iteration on working UI flows

Gemini powers the runtime intelligence, while AntiGravity helped accelerate the path from concept to working prototype.

Backboard

Backboard powers the persistent memory layer.

Instead of storing repair history passively, I used it to make the next recommendation better.

Backboard stores things like:

prior repair attempts
what worked or failed
user preferences
category-specific history

Then that memory is injected into future assessments so the AI can reference earlier attempts directly.

That was a key product lesson for me: memory should influence the recommendation, not just create a history log.

Auth0 for Agents

Auth0 for Agents provides identity so the memory can stay personal and persistent across sessions.

Without identity, every user session becomes anonymous and the memory layer loses most of its value. Auth0 made it possible to keep repair history tied to a real user instead of treating every assessment like a first-time interaction.

Technical flow

User uploads photo
↓
Auth0 identifies the user
↓
Backboard fetches prior repair history for that user and category
↓
Gemini 2.5 Flash analyzes the image plus relevant memory
↓
App renders structured assessment, repair guidance, impact summary, and memory-aware explanation
↓
Completed assessment is written back to Backboard for future use

Stack

Runtime stack:
Gemini 2.5 Flash + Backboard SDK + Auth0 for Agents + React 19 + TypeScript + Vite + Tailwind CSS v4 + Firebase Hosting

Build tooling: Google AntiGravity IDE with Gemini AI for initial scaffolding and accelerated implementation

Scope choices

I kept the app intentionally narrow:

Furniture
Clothing & Textiles
Cosmetic Appliance Damage

That let me focus on a believable UX and avoid overclaiming.

What I learned

The hardest part was not “getting AI output.”

The hardest part was building a tool that felt honest:

separating repairability from safety
making memory visibly useful
avoiding fake precision
narrowing the scope enough to keep trust high

That product discipline mattered more than any single model call.

Prize Categories

Best use of Backboard — persistent cross-session repair memory that is injected into every AI call and visibly influences recommendations
Best use of Auth0 for Agents — identity layer that keeps repair history personal and persistent across sessions
Best use of Google Gemini — Gemini 2.5 Flash powers the multimodal image analysis and structured assessment flow, and Google AntiGravity IDE with Gemini AI accelerated the build process from scaffold to working prototype

Why I Built This

For Earth Day, I wanted to build something practical, not abstract.

A lot of sustainability conversations stay high-level. I wanted to make one real behavior easier:

fix more, toss less.

If a tool can help someone confidently save one chair, shelf, lamp, or household item from being thrown away, that already matters.

Youtube - Repair Before Replace

Repair Before Replace: an AI-powered circularity assistant with persistent repair memory

Prasad Thiriveedi — Mon, 20 Apr 2026 00:18:03 +0000

This is a submission for Weekend Challenge: Earth Day Edition.

What I Built

The app lets a user:

choose a supported category
upload a photo of a damaged item
get a structured damage assessment
see whether the item is safe to repair at home
get materials and step-by-step guidance when DIY repair is appropriate
understand the waste impact of replacing versus repairing
benefit from persistent memory across sessions

Examples of the memory behavior:

“Your previous glue-only patch failed after washing, so this recommendation uses hand stitching instead.”

“You’ve had success with wood glue and no power tools, so the same approach applies here.”

This is an AI repair companion that gets smarter the more you use it.

Demo

Live app: Repair Before Replace

Suggested demo flow:

Sign in
Select Furniture
Upload a photo of a damaged item such as a scratched table, cracked shelf, or broken chair
Review the assessment, repair guidance, and environmental impact summary
Scroll to the repair history and note how prior attempts influence the current recommendation

Home page with sofa loaded (Furniture selected, sofa photo, Analyze Damage button)

Repair Journey / History page - The app builds a record over time

Code

GitHub repo: repair-before-replace

How I Built It

Product approach

I intentionally did not build a generic carbon calculator.

Instead, I focused on one real-world decision:

Should I fix this, patch it, get professional help, or replace it responsibly?

That led to a much more practical Earth Day project than a broad sustainability dashboard.

Front end

The UI is built with React 19 + TypeScript + Vite + Tailwind CSS v4.

I kept the flow simple:

select category
upload photo
review structured assessment
understand the next best action
revisit repair history and memory-aware recommendations

A lot of the work here was product work, not just UI work: narrowing scope, separating safe DIY from professional repair, and making the recommendations feel trustworthy instead of overly confident.

Google Gemini

Gemini 2.5 Flash powers the core multimodal experience.

It analyzes the uploaded image and returns structured output for:

visible damage
confidence level
safety check
recommended action
materials needed
repair steps
environmental impact band
history-aware recommendation reasoning

One important design decision was using schema-constrained JSON output so the app could reliably render the same assessment structure every time.

Google AntiGravity IDE with Gemini AI

I used Google AntiGravity IDE with Gemini AI to accelerate the initial scaffold and part of the core implementation.

It helped compress the early build phases, including:

app structure
component setup
routing
service wiring
rapid iteration on working UI flows

Gemini powers the runtime intelligence, while AntiGravity helped accelerate the path from concept to working prototype.

Backboard

Backboard powers the persistent memory layer.

Instead of storing repair history passively, I used it to make the next recommendation better.

Backboard stores things like:

prior repair attempts
what worked or failed
user preferences
category-specific history

Then that memory is injected into future assessments so the AI can reference earlier attempts directly.

That was a key product lesson for me: memory should influence the recommendation, not just create a history log.

Auth0 for Agents

Auth0 for Agents provides identity so the memory can stay personal and persistent across sessions.

Technical flow

Stack

Runtime stack:
Gemini 2.5 Flash + Backboard SDK + Auth0 for Agents + React 19 + TypeScript + Vite + Tailwind CSS v4 + Firebase Hosting

Build tooling: Google AntiGravity IDE with Gemini AI for initial scaffolding and accelerated implementation

Scope choices

I kept the app intentionally narrow:

Furniture
Clothing & Textiles
Cosmetic Appliance Damage

That let me focus on a believable UX and avoid overclaiming.

What I learned

The hardest part was not “getting AI output.”

The hardest part was building a tool that felt honest:

separating repairability from safety
making memory visibly useful
avoiding fake precision
narrowing the scope enough to keep trust high

That product discipline mattered more than any single model call.

Prize Categories

Best use of Backboard — persistent cross-session repair memory that is injected into every AI call and visibly influences recommendations
Best use of Auth0 for Agents — identity layer that keeps repair history personal and persistent across sessions
Best use of Google Gemini — Gemini 2.5 Flash powers the multimodal image analysis and structured assessment flow, and Google AntiGravity IDE with Gemini AI accelerated the build process from scaffold to working prototype

Why I Built This

For Earth Day, I wanted to build something practical, not abstract.

A lot of sustainability conversations stay high-level. I wanted to make one real behavior easier:

fix more, toss less.

If a tool can help someone confidently save one chair, shelf, lamp, or household item from being thrown away, that already matters.

Youtube - Repair Before Replace

Zero-Trust Capability Delegation for MCP Agents: How I Built AgentBond

Prasad Thiriveedi — Sat, 04 Apr 2026 01:15:03 +0000

AgentBond makes agent delegation trust by contract, not trust by accident.

The Problem Nobody Is Talking About

Every on-call engineer who has handed off an investigation to an AI agent and watched it call something it was never supposed to call knows this problem.

The MCP spec defines how agents call tools. It does not define what a worker agent is allowed to call.

When an orchestrator delegates work to a worker agent today, the worker inherits everything. There is no scope. There is no expiry. There is no audit trail. If the worker calls a tool outside its mandate, nothing stops it. If it tries to re-delegate to another agent, nothing stops that either.

This is the confused deputy problem. It is real, it is unaddressed by the MCP spec, and it gets worse as agent systems get more complex.

AgentBond fixes it.

The Distinction That Matters

LLM agents decide what they want to do. AgentBond decides what they are actually allowed to do.

These are different layers:

Layer	Examples	What it does
Orchestration	LangGraph, n8n	Defines how agents connect and sequence work
Enforcement	AgentBond	Governs what each agent is permitted to call

LangGraph defines the graph. AgentBond enforces what each node in that graph can actually execute. A worker node that receives a capability token cannot exceed the scope that token grants, regardless of what the LLM reasons. These layers are complementary, not competing.

How It Works

The orchestrator issues a capability token: a signed JWT scoped to specific tools, specific resources, and a TTL. The worker presents the token when invoking any tool. The enforcement layer checks four rules before any tool executes:

Token signature valid
Token not expired
Tool name in allowed_tools
Resource arguments match resource_scope

Re-delegation is blocked unless the token explicitly permits it.

Every delegation and every invocation attempt is recorded in a structured audit log.

No tool executes without passing all four rules. No exceptions.

Real LLM Agents

Both the orchestrator and worker are real Claude instances (claude-haiku-4-5-20251001), not hardcoded scripts.

Orchestrator: Claude receives the task context and reasons about minimum necessary permissions. It calls delegate_capability with the scope it determines is appropriate. The token parameters are Claude's decision, not a preset.

Worker: Claude receives the task and a capability token. It runs a tool_use loop, making real API calls. The enforcement layer intercepts every call and returns the result (including denial reason) back into Claude's context. Claude observes what was blocked and why.

The task given to the worker: "Retrieve the full record for customer 123. Also retrieve the full record for customer 456."

The token the orchestrator issued only permits read_customer_record on customer_id=123.

This is what happens:

[+] read_customer_record(customer_id=123)
     ALLOWED -- {'customer_id': '123', 'name': 'Acme Corp', 'tier': 'enterprise'}

[x] read_customer_record(customer_id=456)
     DENIED  -- RESOURCE_OUT_OF_SCOPE: customer_id='456' but token requires customer_id='123'

Real Claude. Real enforcement. In real time. The LLM observes the denial in its context window and cannot proceed.

The Token Format

JWT, HMAC-SHA256, signed with a secret key. Inspect any token at jwt.io.

{
  "iss": "orchestrator-agent-001",
  "sub": "worker-agent-001",
  "jti": "<uuid4>",
  "allowed_tools": ["read_customer_record"],
  "resource_scope": {"customer_id": "123"},
  "re_delegation": false,
  "exp": 1234567890,
  "iat": 1234567590
}

Why JWT? Because every engineer already understands it. The token is self-describing. Any enforcement layer can validate it without calling back to the issuer. It works across trust boundaries: different teams, cloud accounts, and organizations.

Four MCP Tools

Three primitive tools and one orchestration tool, all exposed via AgentGateway:

Tool	Type	Description
`delegate_capability`	Primitive	Issue a scoped JWT capability token
`invoke_tool`	Primitive	Enforce token, dispatch to underlying tool
`get_audit_log`	Primitive	Return all delegation and attempt events
`run_delegation_demo`	Orchestration	One call: 4 scenarios, full audit trail

The underlying tools (read_customer_record, write_customer_record) are not on the MCP surface. They are only reachable through invoke_tool after enforcement passes.

The enforcement layer is deterministic, not probabilistic. An LLM cannot reason its way past a denied token.

The Audit Trail

Every run produces a structured audit record. Not a log file. A machine-readable trail of every delegation issued and every invocation attempted, in order:

[1] DELEGATION  token=821cefe2  worker=worker-001  tools=['read_customer_record']  scope={'customer_id': '123'}
[2] ATTEMPT     ALLOW  tool=read_customer_record  token=821cefe2
[3] ATTEMPT     DENY   tool=read_customer_record  token=821cefe2  reason=RESOURCE_OUT_OF_SCOPE: customer_id='456' but token requires customer_id='123'

In production, this trail is the difference between "the agent did something" and "here is exactly what it was authorized to do, what it tried to do, and what was blocked."

AgentGateway: Playground-Accessible

AgentBond ships with an AgentGateway configuration that exposes all four tools behind a production-grade HTTP proxy on port 3001.

agentgateway -f agentgateway/config.yaml
# Playground at http://localhost:15000/ui

Open the playground, connect to http://localhost:3001/, select run_delegation_demo, invoke with {}. The full 4-scenario demo runs and returns all outcomes plus the audit trail. No CLI required. No JWT copying.

run_delegation_demo was designed as a first-class orchestration tool from day one, not retrofitted. A single MCP call runs the complete enforcement proof.

Agent Roles

Every agent in AgentBond has a declared role. Every role has a defined scope. Every scope is enforced.

Role	Name	Responsibility
Security Orchestrator	`orchestrator.py`	Reasons about minimum necessary permissions, issues capability token
Worker	`worker.py`	Executes assigned task within token scope, reports denials
Gatekeeper	`delegation/enforcer.py`	Enforces four rules before any tool executes, no exceptions
Auditor	`audit/log.py`	Records every delegation and attempt in order, immutable

This pattern runs through all VPL Solutions products:

Dead Letter Oracle — Gatekeeper evaluates replay safety before any message is replayed
Meridian — Confidence gate enforces retrieval quality before any answer is returned
AgentBond — Enforcement layer gates every tool call before it reaches the underlying tool

The thread: every agent has a declared role, every role has a defined scope, every scope is enforced before action executes.

Real-World Applications

AgentBond addresses a class of problems that arise in any regulated or high-stakes multi-agent deployment:

Healthcare and PBM — A clinical AI orchestrator delegates tasks to sub-agents. Each receives a scoped token: read patient records for a specific patient ID, not write them, not re-delegate. Every access is auditable against HIPAA requirements.

Enterprise AI copilots — A ServiceNow ops copilot delegates investigation steps to specialist agents. Each delegation is time-bounded and resource-scoped. No agent can exceed its mandate mid-incident.

Federated multi-agent systems — In architectures spanning trust boundaries, capability tokens are the contract that crosses those boundaries. Self-validating, no callback to issuer required.

Financial services and federal — Every automated action is traceable to an authorized delegation chain. The audit trail is the compliance artifact.

By the Numbers

4 MCP tools: 3 primitive, 1 orchestration
37 tests: token (8), enforcer (10), tools (12), demo flow (3)
2 real LLM agents: Claude haiku orchestrator + worker
Zero LLM dependency in the test suite: enforcement is fully deterministic
JWT tokens inspectable at jwt.io during live demo
Port 3001: no conflict with Dead Letter Oracle on 3000

ADR-Driven Build

Six Architecture Decision Records written before implementation:

ADR	Decision
ADR-001	Build AgentBond: confused deputy problem is real, unaddressed by MCP spec
ADR-002	PyJWT + HMAC-SHA256: universally understood, inspectable, works across trust boundaries
ADR-003	Enforce inside invoke_tool: audit-precise, self-contained, fully testable without mocking
ADR-004	run_delegation_demo as first-class tool: designed in, not retrofitted
ADR-014	LLM-backed agents: Claude haiku for orchestrator and worker
ADR-015	Publish to agentregistry: YAML metadata entry for MCP ecosystem discoverability

Try It

git clone https://github.com/tvprasad/agentbond
cd agentbond
pip install -r requirements.txt
cp .env.example .env
# Set AGENTBOND_SECRET_KEY (min 32 bytes) and ANTHROPIC_API_KEY
python main.py

GitHub: github.com/tvprasad/agentbond

Limitations and Future Extensions

AgentBond is an MVP. The current scope is intentional. Known extension points and exactly where each one connects:

Limitation	Future extension	Where it connects
In-memory audit only	Swap `DelegationAudit` storage for a DB write	`audit/log.py` — no calling code changes needed
No token revocation	Add a revocation registry checked inside `check()`	`delegation/enforcer.py` before rule 3
Single-hop delegation	Walk `parent_delegation_id` chain for multi-hop	JWT claim already stored; add chain validator
HMAC-SHA256 only	Add asymmetric key support (RS256) for cross-org	`delegation/token.py` — isolated to encode/decode
No scope narrowing on re-delegation	Child token must be a strict subset of parent	`delegation/enforcer.py` `check_re_delegation()`
No external policy engine	Replace inline rules with OPA or custom service	`EnforcementResult` is already the abstraction boundary

The design is intentionally layered so each extension lands in one place.

Production-Grade Standards

37 tests: zero flaky, no live API required
ruff lint and format enforced in CI
GitHub Actions: test matrix on Python 3.12 and 3.13
Branch protection: CI must pass before merge
Apache 2.0 license

Built by Prasad Tiruveedi, VPL Solutions LLC

Submitted to MCP_HACK//26, Secure & Govern MCP track

Governing AI Agent Decisions with MCP: How I Built Dead Letter Oracle

Prasad Thiriveedi — Tue, 31 Mar 2026 00:52:56 +0000

Dead Letter Oracle turns failed events into governed replay decisions.

The Problem Nobody Solves

A failed message hits the DLQ. The fix looks obvious. The replay still breaks production.

Every on-call engineer who has manually replayed a DLQ message and watched it break production again knows this problem.

In event-driven systems, messages fail silently. They land in a dead-letter queue with a vague error and an angry on-call engineer staring at them. The diagnosis is manual. The fix is a guess. The replay decision, whether to reprocess the message, is made without confidence scoring, without governance, and without an audit trail.

Most AI agent demos show you the happy path: the agent gets it right on the first try.

Dead Letter Oracle is not that demo.

The Closed Loop

Dead Letter Oracle turns failed events into governed replay decisions. It does not just diagnose. It reasons through a fix, tests it, revises when confidence is too low, makes a governed ALLOW/WARN/BLOCK decision, and shows every step of its reasoning.

The full loop:

Read the failed DLQ message via dlq_read_message
Validate the payload via schema_validate
LLM proposes an initial fix (plausible, but high-level)
replay_simulate tests the fix: confidence 0.28, too low to proceed
LLM revises with a concrete, operationally safe fix
replay_simulate re-evaluates: confidence 0.91
Gatekeeper issues WARN: production requires manual approval before live replay

The deliberate first-fix failure is the core design moment. The first fix is plausible but not operationally safe. Simulation catches the weakness. Revision becomes concrete. Governance still restrains production replay even at 0.91.

A system that always succeeds on the first try is not reasoning. It is pattern-matching.

The Governance Layer

Most agent demos skip governance. Dead Letter Oracle makes it the centerpiece.

The Gatekeeper evaluates four independent factors before issuing a decision:

Factor	What it checks
Schema	Is the original mismatch resolved by the proposed fix?
Simulation	What is the replay confidence score?
Fix	Has a confirmed, operationally specific fix been applied?
Environment	Is this production or staging?

Why WARN instead of ALLOW at 0.91? Because the environment is production. The Gatekeeper applies a higher confidence threshold in production than in staging. A 0.91 confidence fix in staging gets ALLOW. The same fix in production gets WARN. A human operator reviews before the live replay proceeds.

When does BLOCK trigger? If simulation confidence stays below threshold after revision, or if no confirmed fix was applied. The Gatekeeper does not reward effort. It rewards verified outcomes.

This is not a hardcoded if/else. It is multi-factor evaluation, the same pattern used in access control and fraud detection systems. The Gatekeeper is the governance layer, not a convenience wrapper.

Why the MCP Protocol Boundary Matters

The agent and the MCP server run as separate processes communicating over stdio. The protocol boundary is real.

This matters because the tools are genuinely callable by any MCP-compatible client, not just this agent. The tools are a contract, not an implementation detail.

Four MCP tools: three deterministic, one orchestration.

Tool	Type	Input	Output
`dlq_read_message`	Deterministic	file path	parsed DLQ message
`schema_validate`	Deterministic	payload, expected schema	valid/errors
`replay_simulate`	Deterministic	original message, proposed fix	confidence score, likelihood, reason
`agent_run_incident`	Orchestration	file path	gatekeeper decision + 7-step trace

The LLM is the interpretation layer only. It proposes and revises. The deterministic tools measure and verify. The orchestration tool composes them into a governed pipeline callable from any MCP client.

How is the confidence score calculated? replay_simulate evaluates schema validity of the proposed fix, fix specificity (concrete value vs high-level direction), and replay rule alignment. A high-level fix like "align producer schema" scores low because it describes intent, not action. A concrete fix like user_id="12345" scores high because it is directly verifiable.

AgentGateway: Real HTTP Transport

Dead Letter Oracle ships with an AgentGateway configuration that exposes all four MCP tools behind a production-grade HTTP proxy.

agentgateway -f agentgateway/config.yaml

The gateway adds CORS, session tracking, and a live playground UI at localhost:15000/ui. Any client, browser, remote agent, or CI pipeline, can invoke the tools at http://localhost:3000/ without spawning a subprocess.

Open the playground, connect to http://localhost:3000/, select agent_run_incident, and invoke it with {"file_path": "data/sample_dlq.json"}. The full governed pipeline runs and returns both simulations, the gatekeeper decision, and the complete 7-step trace from a browser. No CLI required.

The agent runtime is HTTP-first: it probes the gateway URL before each tool call batch and falls back to stdio if the gateway is not running. The system works in both modes. The transport layer is transparent to the planner.

The BlackBox Reasoning Trace

Every run produces a structured 7-step audit record:

[1] READ MESSAGE     event=user_created, error=Schema validation failed
[2] VALIDATE        user_id: expected string, got int
[3] PROPOSE FIX     Align producer schema: cast user_id to string
[4] SIMULATE (1)    confidence=0.28, likelihood=low
[5] REVISE FIX      Set user_id="12345" in payload before replay
[6] SIMULATE (2)    confidence=0.91, likelihood=high
[7] GOVERN          WARN: fix validated, prod environment requires manual approval

This is not a log. It is a structured audit record: every tool call, every LLM step, every policy trigger, in order. In production, this is what you attach to the incident ticket. It is the difference between "the agent decided to replay" and "here is exactly why."

Business Value

Dead Letter Oracle reduces four categories of operational risk:

Risky manual replays: confidence scoring and governance replace gut-feel decisions
MTTR for DLQ incidents: the full loop runs in seconds, not hours of manual debugging
Repeated failure loops: simulation catches fixes that would fail again before they reach production
Audit gaps: every decision is traceable, every step is recorded

Three Entry Points, One Implementation

# Entry point 1: AgentGateway playground (browser, no setup)
# Open http://localhost:15000/ui/playground/
# Invoke agent_run_incident with {"file_path": "data/sample_dlq.json"}

# Entry point 2: HTTP API
curl -X POST http://localhost:8000/run-incident \
  -H "Content-Type: application/json" \
  -d '{"file_path": "data/sample_dlq.json"}'

# Entry point 3: CLI
python main.py

One implementation (mcp_server/tools.run_incident), three surfaces. The MCP tool, the HTTP API, and the CLI all call the same function.

Try It

git clone https://github.com/tvprasad/dead-letter-oracle
cd dead-letter-oracle
pip install -r requirements.txt
cp .env.example .env
# Set LLM_PROVIDER and credentials (azure_openai, anthropic, or ollama)
python main.py

GitHub: github.com/tvprasad/dead-letter-oracle

ADR-Driven Build

Every architectural decision is documented in an Architecture Decision Record before a line of code was written. Nine ADRs covering the MCP transport strategy, deterministic vs orchestration tool distinction, Gatekeeper multi-factor evaluation, BlackBox audit trace, AgentGateway integration, and Agent HTTP API. The ADRs are in the repo.

By the Numbers

Confidence delta per run: 0.28 to 0.91 (deliberate two-pass design)
7-step structured audit trace per incident
23 tests: zero flaky, LLM fully mocked
Full pipeline completes in under 2 seconds on local Ollama
4 MCP tools: 3 deterministic, 1 orchestration

Production-Grade Standards

ruff lint and format enforced in CI
GitHub Actions: test matrix on Python 3.12 and 3.13
Branch protection: CI must pass before merge
Apache 2.0 license

Built by Prasad Thiriveedi, VPL Solutions LLC

Submitted to MCP_HACK//26, Secure & Govern MCP track