{"id":49289066,"url":"https://github.com/tvprasad/dead-letter-oracle","last_synced_at":"2026-04-25T23:38:28.631Z","repository":{"id":347834149,"uuid":"1195426635","full_name":"tvprasad/dead-letter-oracle","owner":"tvprasad","description":"Governed MCP agent for DLQ incident resolution with closed-loop reasoning, multi-factor governance, and BlackBox reasoning trace","archived":false,"fork":false,"pushed_at":"2026-03-29T18:26:05.000Z","size":2359,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T19:27:29.886Z","etag":null,"topics":["agent","anthropic","dead-letter-queue","event-driven","governance","hackathon","llm","mcp","ollama","openai","pydantic","python"],"latest_commit_sha":null,"homepage":"https://github.com/tvprasad/dead-letter-oracle","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tvprasad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":"governance/__init__.py","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T16:58:59.000Z","updated_at":"2026-03-29T18:26:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tvprasad/dead-letter-oracle","commit_stats":null,"previous_names":["tvprasad/dead-letter-oracle"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tvprasad/dead-letter-oracle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tvprasad%2Fdead-letter-oracle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tvprasad%2Fdead-letter-oracle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tvprasad%2Fdead-letter-oracle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tvprasad%2Fdead-letter-oracle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tvprasad","download_url":"https://codeload.github.com/tvprasad/dead-letter-oracle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tvprasad%2Fdead-letter-oracle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","anthropic","dead-letter-queue","event-driven","governance","hackathon","llm","mcp","ollama","openai","pydantic","python"],"created_at":"2026-04-25T23:38:27.144Z","updated_at":"2026-04-25T23:38:28.622Z","avatar_url":"https://github.com/tvprasad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Dead Letter Oracle\n\n**Governed MCP Agent for DLQ Incident Resolution**\n\n[![CI](https://github.com/tvprasad/dead-letter-oracle/actions/workflows/ci.yml/badge.svg)](https://github.com/tvprasad/dead-letter-oracle/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE-2.0.txt)\n[![Release](https://img.shields.io/github/v/release/tvprasad/dead-letter-oracle)](https://github.com/tvprasad/dead-letter-oracle/releases)\n[![MCP](https://img.shields.io/badge/protocol-MCP%20stdio-purple)](https://modelcontextprotocol.io)\n[![AgentGateway](https://img.shields.io/badge/gateway-AgentGateway-blue)](https://github.com/agentgateway/agentgateway)\n[![LLM](https://img.shields.io/badge/LLM-Azure%20OpenAI%20%7C%20Anthropic%20%7C%20Ollama-orange)](https://github.com/tvprasad/dead-letter-oracle#llm-provider)\n\n![Dead Letter Oracle](docs/poster.png)\n\nDead Letter Oracle is an MCP-based agent that analyzes failed dead-letter queue messages, explains root causes, proposes and simulates fixes, and makes governed replay decisions, with a full reasoning trace.\n\n---\n\n## Problem\n\nIn event-driven systems, failed messages require manual debugging:\n\n- Root cause is unclear from the error alone\n- Schema mismatches are hard to diagnose without tooling\n- Replay decisions are made without confidence scoring or governance\n\n---\n\n## Solution\n\nDead Letter Oracle automates the full incident loop:\n\n1. Reads the failed DLQ message via `dlq_read_message`\n2. Validates the payload via `schema_validate`\n3. LLM proposes an initial fix (high-level direction)\n4. `replay_simulate` tests the fix and returns a confidence score\n5. If confidence is low, LLM revises with a concrete, operational fix\n6. `replay_simulate` re-evaluates the revised fix\n7. Gatekeeper issues ALLOW / WARN / BLOCK with multi-factor reasoning\n8. BlackBox renders the full 7-step reasoning trace\n\n---\n\n## Architecture\n\n```\nUser → CLI (main.py)\n     → Agent API (POST /run-incident, port 8000)\n     → AgentGateway Playground (agent_run_incident tool, port 3000)\n                │\n                ▼\n        AgentGateway (port 3000)\n        CORS, session tracking, web UI\n                │\n                ▼\n          MCP Server (mcp_server/)\n          ├── dlq_read_message       deterministic\n          ├── schema_validate        deterministic\n          ├── replay_simulate        deterministic\n          └── agent_run_incident     orchestration\n                    ├── calls above tool functions (in-process)\n                    ├── LLM  (propose → simulate → revise)\n                    ├── Gatekeeper  (ALLOW / WARN / BLOCK)\n                    └── BlackBox    (reasoning trace)\n```\n\nAll four tools are accessible via AgentGateway at port 3000. The MCP protocol boundary is real. The three deterministic tools have no LLM dependency. `agent_run_incident` composes them with LLM interpretation and governance — one protocol surface, all capabilities.\n\n---\n\n## Running with AgentGateway\n\nDead Letter Oracle ships with an [AgentGateway](https://github.com/agentgateway/agentgateway) configuration that exposes both the MCP tools and the governed agent API behind a single proxy with built-in CORS, session tracking, and a live web UI.\n\nDead Letter Oracle exposes two surfaces:\n\n- **MCP tools** via AgentGateway (port 3000) — `dlq_read_message`, `schema_validate`, `replay_simulate`\n- **Agent API** (port 8000) — `POST /run-incident` runs the full 7-step governed pipeline and returns the reasoning trace and gatekeeper decision as JSON\n\n```bash\n# Install agentgateway (Linux/macOS)\ncurl -sL https://agentgateway.dev/install | bash\n\n# Windows: download binary from https://github.com/agentgateway/agentgateway/releases\n# then run:\nagentgateway-windows-amd64.exe -f agentgateway/config.yaml\n\n# Start the gateway (MCP tools)\nagentgateway -f agentgateway/config.yaml\n\n# Start the agent API (full governed pipeline)\npython -m agent.api\n```\n\n| Endpoint | URL |\n|----------|-----|\n| MCP proxy | http://localhost:3000/ |\n| Agent API | http://localhost:8000/run-incident |\n| Agent docs | http://localhost:8000/docs |\n| Web UI | http://localhost:15000/ui |\n| Playground | http://localhost:15000/ui/playground/ |\n\nOpen the Playground, connect to `http://localhost:3000/`, and invoke `dlq_read_message`, `schema_validate`, or `replay_simulate` directly from the browser. To run the full governed pipeline via HTTP, `POST http://localhost:8000/run-incident` with `{\"file_path\": \"data/sample_dlq.json\"}`.\n\nThe gateway config is at [`agentgateway/config.yaml`](agentgateway/config.yaml).\n\n---\n\n## Quickstart\n\n```bash\npip install -r requirements.txt\ncp .env.example .env\n# fill in LLM credentials (see .env.example)\npython main.py\n```\n\n### LLM Provider\n\nSet `LLM_PROVIDER` in `.env`:\n\n| Value | Required vars |\n|-------|--------------|\n| `azure_openai` (default) | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT` |\n| `anthropic` | `ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL` |\n| `ollama` | `OLLAMA_BASE_URL`, `OLLAMA_MODEL` |\n\n\u003e Tested with Ollama (llama3) for local and air-gapped deployment, relevant for enterprise and federal environments where cloud API calls are restricted.\n\n### Running tests\n\n```bash\npython -m pytest tests/ -v\n```\n\n---\n\n## MCP Tools\n\n| Tool | Type | Input | Output |\n|------|------|-------|--------|\n| `dlq_read_message` | Deterministic | `file_path` | Parsed DLQ message |\n| `schema_validate` | Deterministic | `payload`, `expected_schema` | `valid`, `errors[]` |\n| `replay_simulate` | Deterministic | `original_message`, `proposed_fix` | `confidence`, `success_likelihood`, `reason` |\n| `agent_run_incident` | Orchestration | `file_path` | Gatekeeper decision + 7-step BlackBox trace |\n\n---\n\n## Gatekeeper Factors\n\nMulti-factor evaluation, not a simple if/else:\n\n- **Schema** — mismatch detected / resolved\n- **Simulation** — confidence score from `replay_simulate`\n- **Fix** — whether a confirmed fix was applied\n- **Environment** — prod requires higher confidence threshold\n\n---\n\n## Project Structure\n\n```\nmcp_server/      MCP server + tools (deterministic)\nagent/           Agent runtime, planner, LLM integration, HTTP API\ngovernance/      Gatekeeper — multi-factor replay evaluation\nobservability/   BlackBox — structured reasoning trace\nagentgateway/    AgentGateway config (MCP proxy + agent API, web UI, playground)\ndata/            Sample DLQ message (local, no Kafka)\nadr/             Architecture Decision Records (ADR-001 through ADR-009)\ntests/           22 unit + integration tests\ndocs/            Architecture poster (poster.png)\n```\n\n---\n\n## Hackathon Context\n\nDeveloped during the AI Hackathon submission period (Feb 2 – Apr 3, 2026).\n\nBuilt ADR-first: each phase locked decisions before implementation. The deliberate first-fix failure (confidence 0.28 → 0.91) is the core demo moment. It proves the agent reasons, not just formats.\n\n---\n\n## Author\n\n**Prasad Tiruveedi** — [linkedin.com/in/-prasad](https://www.linkedin.com/in/-prasad/) | VPL Solutions LLC\n\n---\n\n## Acknowledgements\n\n**Design review:** Venkat, Satish, and Vijaya — feedback on system positioning and poster design.\n\n**Development approach:** Built using an agent team orchestrated by a human architect — each tool assigned a distinct role, mirroring the multi-component design of the system itself.\n\n**AI tools used during development:**\n- Claude Code — implementation, architecture, and testing\n- ChatGPT — ideation, prompt refinement, and poster generation\n- Gemini — ideation and design feedback\n- GitHub Copilot — ideation and testing\n- Ollama (llama3) — local LLM validation and air-gap testing\n\n## License\n\nApache License 2.0 — see [LICENSE-2.0.txt](LICENSE-2.0.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftvprasad%2Fdead-letter-oracle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftvprasad%2Fdead-letter-oracle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftvprasad%2Fdead-letter-oracle/lists"}