🚨 OpsPilot

AI-Powered Incident Triage & Change Planning Agent

OpsPilot turns a plain-English incident description into a structured, auditable change plan in seconds — backed by runbook evidence, not guesswork.

---

The Problem

When production goes down, engineers waste precious minutes hunting through runbooks, Slack threads, and wikis to figure out what to do. The knowledge exists — it's just scattered and slow to retrieve under pressure.

The Solution

OpsPilot is an agentic triage system that:

1. Receives an incident message (e.g. "/login returns 500 after deploy")
2. Retrieves relevant runbook evidence from a vector database (Astra DB)
3. Reasons through the evidence using a Langflow agent with MCP tools
4. Returns a human-readable triage response + a validated CHANGE_PLAN JSON object
5. Persists a ticket and session memory for continuity across the incident lifecycle

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Nginx (TLS)                          │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│              FastAPI Gateway  (api/)                         │
│  • API key auth  • Rate limiting  • CORS  • Request sizing  │
└──────────┬────────────────────────────────────┬─────────────┘
           │ vector search                       │ orchestration
┌──────────▼──────────┐               ┌──────────▼──────────┐
│     Astra DB        │               │      Langflow        │
│  • runbook_chunks   │◄──────────────│  Agent + MCP tools  │
│  • tickets          │               └─────────────────────┘
│  • sessions         │
└─────────────────────┘

Key design decisions:

• Astra DB serves double duty: vector store for RAG and persistent operational records
• CHANGE_PLAN is Pydantic-validated JSON — no freeform LLM output reaches downstream systems
• All containers run as non-root; secrets are never committed

---

Tech Stack

Layer	Technology
Agent Orchestration	Langflow + MCP tools
LLM	OpenAI / Groq (configurable)
Vector Store + Persistence	DataStax Astra DB
API Gateway	FastAPI + Nginx
Embeddings	OpenAI text-embedding-3-small (1536d)
Infrastructure	Docker Compose
Testing	pytest + Schemathesis (contract tests)

---

Quickstart

# 1. Clone and configure
git clone https://github.com/Sylesh29/OpsPilot.git
cd OpsPilot

# 2. Set secrets
cp langflow/.env.example langflow/.env
cp api/.env.example api/.env
# → add OPENAI_API_KEY, ASTRA_DB_* credentials, GATEWAY_API_KEY

# 3. Start the stack
docker compose up --build

# 4. Seed the vector store
python scripts/astra_setup.py
python scripts/seed_astra.py

# 5. Verify
curl http://localhost:8088/healthz

Trigger a triage

curl -X POST http://localhost:8088/v1/triage \
  -H "Content-Type: application/json" \
  -H "x-api-key: gw-demo-key-change-me" \
  -d '{
    "session_id": "demo-001",
    "message": "We deployed 30 minutes ago and now /login returns 500. Create a triage plan.",
    "severity_hint": "SEV2"
  }'

Response includes:

• Plain-English triage narrative
• Structured CHANGE_PLAN JSON (validated by Pydantic)
• Ticket ID persisted in Astra for continuity

---

Security Posture

• API key authentication on all endpoints
• Rate limiting + CORS allowlist + request size cap at the gateway
• Structured JSON logging with request IDs for full auditability
• All containers run as non-root
• Zero secrets committed — .env.example files only

---

Testing

# Unit tests
cd api && pytest

# Integration tests (requires live stack + credentials)
RUN_INTEGRATION_TESTS=1 pytest tests/test_integration_e2e.py

Contract tests run via Schemathesis against the live OpenAPI spec.

---

LLM Provider Configuration

Switch providers without changing application code:

# Groq (fast, great for dev)
LLM_PROVIDER=groq
GROQ_API_KEY=your_key
GROQ_MODEL=llama-3.3-70b-versatile

# OpenAI (default)
LLM_PROVIDER=openai
OPENAI_MODEL=gpt-4o

---

Astra DB Schema

Collection	Type	Purpose
opspilot_runbook_chunks	Vector (1536d)	RAG knowledge base
opspilot_tickets	Non-vector	Incident ticket records
opspilot_sessions	Non-vector	Session memory across incidents

---

Built for the IBM WatsonX Challenge · Langflow + Astra DB + FastAPI