README.md

metadata

title: RootCauseArena
emoji: 🛠️
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
tags:
  - openenv
pinned: false
license: mit

Repair Strategy System V3 (Hidden State & Reasoning)

A deterministic incident-response simulator where an agent must infer hidden root causes from ambiguous symptoms and repair a distributed system under cascading failures.

Think of this as a "SRE Training Ground." Unlike basic simulations where you see exactly what's broken, V3 implements a Hidden State architecture. The agent never sees the true health of a component—only the metrics and logs it produces.

This shifts the challenge from simple state-mapping to Root-Cause Inference + Sequential Decision-Making.

---

🎯 Why This Matters

In production systems, failures rarely announce themselves with a clear "Down" label. You see latency spikes, 503 errors, and misleading logs that pull you in the wrong direction.

This environment captures the messiness of real-world debugging:

• Cascades: A database failure will cause the API to fail.
• Ambiguity: A "Service Unavailable" log could mean the API is dead or its upstream dependency is gone.
• Costs: Every inspection and repair action has a price. Blindly restarting everything will tank your score.

---

⚙️ Environment Loop

       Agent Action (Inspect / Repair)
                  │
                  ▼
       ┌──────────────────────────┐
       │     1. Apply Action      │  ← Repair root or patch symptom
       │   2. Cascade Engine      │  ← DB failure travels to API
       │ 3. Passive Degradation   │  ← System worsens if root is active
       │ 4. Recovery Cooldowns    │  ← Critical repairs take 2 steps
       └──────────┬───────────────┘
                  │
       ┌──────────▼───────────────┐
       │    5. Symptom Engine     │  ← Generates random, ambiguous logs
       │    6. Reward Signal      │  ← Deducts action costs + health
       └──────────┬───────────────┘
                  │
       Agent receives Observation
        (Metrics + Overlapping Logs)

---

🏗️ Components (Hidden State)

The system models 4 components: database, api, cache, queue. While the agent only sees symptoms, the environment tracks these internal fields:

Field	Type	Description
status	`healthy	degraded
latency	int (ms)	Response time
error_rate	float [0.0–1.0]	Probability of request failure
queue_load	float	Buffer pressure
cpu_usage	float	Simulated resource consumption

---

⚡ Action Space (With Decision Costs)

Every action carries a cost, forcing the agent to be precise.

🔍 Inspection Actions

Action	Purpose	Cost
inspect_[component]	Gather clues about a specific node	Free (First 3) / -0.1 (After)

🔧 Repair Actions

Action	Effect	Cost
repair_database	2-step restore for DB only	-0.5
scale_up	Restores degraded -> healthy only	-0.5
restart_service	2-step restore for any service	-0.2
clear_cache	Immediate down -> healthy	-0.2
no_op	Do nothing (waits for cooldowns)	0

---

👁️ Observation Space (Symptoms)

Instead of the true state, the agent receives a SymptomObservation:

{
  "metrics": {
    "database": {"latency": 9999, "error_rate": 1.0, "cpu_usage": 100},
    "api":      {"latency": 500, "error_rate": 0.9, "cpu_usage": 45},
    "cache":    {"latency": 20, "error_rate": 0.0, "cpu_usage": 10}
  },
  "logs": [
    "Connection timeout on socket 9934...",  // Could be DB or Cache!
    "CRITICAL: Application unresponsive",     // Ambiguous symptom
    "HTTP 503 Service Unavailable"           // Cascade result
  ],
  "step_count": 2,
  "inspections_remaining": 1
}

---

📏 V3 Grading Strategy

Composite Health + Efficiency Scoring. The grader doesn't just check if the system is healthy; it checks how you got there.

Metric	weight	Description
Health Ratio	50%	Final operational health of all components
Efficiency	30%	Steps vs Optimal steps (Penalty for wasted turns)
Root Fix Ratio	20%	Successful identification and repair of the true root cause

---

🧪 Tasks

Task 1 — Easy

• Initial: DB down. Simple cascade.
• Goal: Identify DB as root via logs and fix it.
• Optimal steps: 3 (Inspect + Repair + 2 cooldown steps)

Task 2 — Hard (Full Cascade)

• Initial: DB down. API down. Queue degraded.
• Rule: If you fix the API first, it will immediately break again on the next step because the DB is still down.
• Optimal steps: 7 (Avg over seeds)

Task 3 — Multi-Root (V3 Exclusive)

• Initial: Database AND Queue have failed independently.
• Goal: The agent must solve both. Terminal rewards only trigger once all independent root causes are healthy.
• Optimal steps: 10 (Avg over 20-seed stress test)

---

📊 Baseline Performance (Deterministic)

Verified stability across 20 distinct random seeds (42–61).

Mission	Success Rate	Avg Score	Avg Steps
All V3 Tasks	100%	0.8373	6.8

---

🚀 Setup & Running

Requirements

pip install fastapi uvicorn pydantic

Start the V3 Server

python server_v2.py   # Runs on http://localhost:7860

Verify Logic & Constraints

python test_v2.py     # Verifies 18 hard constraints

API Endpoints

Endpoint	Method	Result
/tasks	GET	Mission list + V3 Action Schema
/grader	POST	Composite Health/Efficiency score
/baseline	GET	Runs Inspect-Filter-Fix agent
/diagnose	POST	Theoretical root-cause validation

---

Built for the OpenEnv Hackathon — Strictly deterministic and reasoning-heavy.