Autonomous API Failure Debugger

A CLI-based API debugger that reads an API failure and tells you what broke, why it broke, and how to fix it — like a senior backend engineer in your terminal.

What It Does

When an API fails, this tool:

• Classifies the failure type (auth, validation, database, etc.)
• Explains the root cause
• Suggests actionable fixes
• Scores its confidence in the diagnosis

Quick Start

1. Install Dependencies

pip install -r requirements.txt

2. Run with Sample Data

python app.py --file samples/auth_error.txt

3. Interactive Mode

python app.py

4. Command-line Mode

python app.py --endpoint /api/users --method POST --status 401 --error "JWT token expired"

Project Structure

api-debugger/
│
├── app.py                    # CLI runner
│
├── agent/
│   ├── state.py              # AgentState definition
│   ├── classifier.py         # Failure type classification
│   ├── hypothesis.py         # Hypothesis generation
│   ├── evidence_matcher.py   # Evidence matching engine
│   ├── eliminator.py         # Hypothesis elimination logic
│   ├── reasoner.py           # Hypothesis-based reasoning
│   ├── fixer.py              # Fix suggestions
│   ├── graph.py              # LangGraph workflow
│
├── rules/
│   ├── auth_rules.py      # Authentication rules
│   ├── db_rules.py        # Database rules
│   ├── validation_rules.py # Validation rules
│
├── samples/               # Sample error files
│   ├── auth_error.txt
│   ├── db_error.txt
│   ├── validation_error.txt
│
└── requirements.txt

How It Works

User Input
   ↓
Parse Error & Stack Trace
   ↓
Classify Failure Type (status code, keywords)
   ↓
Generate Multiple Hypotheses (3-5 possible causes)
   ↓
Match Evidence (support/weaken each hypothesis)
   ↓
Eliminate Unlikely Causes (absence of key signals)
   ↓
Rank Hypotheses by Score
   ↓
Structured Response (primary + alternatives)

Reasoning Approach

Hypothesis Generation: Instead of one answer, generates 3-5 competing hypotheses

Evidence Matching: For each hypothesis, collects supporting and contradicting evidence

Elimination Logic: Rules out unlikely causes (e.g., no timeout signal = not network issue)

Ranked Output: Shows most likely cause + alternatives with probability scores

Failure Categories

1. Authentication - 401, JWT expired, missing tokens
2. Authorization - 403, permission denied
3. Validation - 400, missing fields, type errors
4. Database - Constraint violations, connection failures
5. External Service - Timeouts, 3rd-party API down
6. Business Logic - Invalid state, condition checks
7. Server Error - 500, null pointer, undefined variables

Example Output

Autonomous API Failure Debugger
══════════════════════════════════════════════════════════════════════

Step 1: Classifying failure type...
Step 2: Generating hypotheses...
  Generated 5 hypotheses
Step 3: Matching evidence...
Step 4: Eliminating unlikely causes...
  3 hypotheses remain after elimination
Step 5: Ranking hypotheses...
Step 6: Generating fix suggestions...
Step 7: Analysis complete!

ANALYSIS RESULTS
──────────────────────────────────────────────────────────────────────

Failure Category:
   AUTHENTICATION

Most Likely Cause (85%):
   JWT token has expired

Supporting Evidence:
   + Pattern 'jwt_expired' found in error
   + HTTP 401 status code strongly indicates auth issue

Alternative Causes:
   • Authorization header is missing or malformed (10%)
   • Token signature verification failed (5%)

Suggested Fixes:
   1. Regenerate authentication token if expired
   2. Verify the token has not expired (check exp claim in JWT)
   3. Check if the authentication token is included in the Authorization header
   4. Ensure token format is correct: 'Bearer <token>'

All Hypotheses Considered:
   1. JWT token has expired (85%)
   2. Authorization header is missing or malformed (10%)
   3. Token signature verification failed (5%)

──────────────────────────────────────────────────────────────────────

Tech Stack

• Language: Python
• Agent Framework: LangGraph
• LLM: Optional (uses rule-based + heuristics)
• Interface: CLI
• Storage: In-memory

Features

• Rule-based + AI reasoning
• Works offline
• Deterministic classification
• Colored CLI output
• Sample error files included

Usage Examples

Example 1: Authentication Error

python app.py --file samples/auth_error.txt

Example 2: Database Error

python app.py --file samples/db_error.txt

Example 3: Validation Error

python app.py --file samples/validation_error.txt

Example 4: Quick Diagnosis

python app.py --endpoint /api/login --status 401 --error "Token expired"

Future Extensions

• Multi-step debugging (follow-up questions)
• Integration with API logs
• Custom rule definitions
• Export reports to JSON/HTML
• Plugin system for custom failure types

License

MIT License - feel free to use and modify!

Contributing

This is a learning project. Feel free to extend it with:

• New failure categories
• Better pattern matching
• LLM integration (OpenAI, Anthropic, local models)
• Web interface

---

Built with LangGraph