ResolveIT AI — Smart Runbook Resolution Assistant

AI-powered semantic search for IT runbooks. Describe your problem in plain English, get precise troubleshooting steps instantly.

---

Architecture

resolveit/
├── runbooks/              ← .txt runbook files (your knowledge base)
│   ├── server_errors.txt
│   ├── app_crashes.txt
│   └── network_issues.txt
├── backend/
│   ├── main.py            ← FastAPI app (REST API + static serving)
│   ├── indexer.py         ← TF-IDF + FAISS vector engine
│   ├── faiss_index.bin    ← Built vector index (auto-generated)
│   ├── metadata.pkl       ← Runbook section metadata
│   └── vectorizer.pkl     ← TF-IDF model
├── frontend/
│   └── index.html         ← Single-page UI (served by FastAPI)
├── requirements.txt
├── start.sh
└── README.md

How It Works

1. Indexing: Each runbook is parsed into sections (one per ERROR type). Each section's title + symptoms + steps are combined into a text document.
2. Vectorization: TF-IDF with trigrams converts text to high-dimensional vectors (dim ~3000). Vectors are L2-normalized for cosine similarity.
3. FAISS: Facebook AI Similarity Search indexes vectors using IndexFlatIP (inner product = cosine after normalization). Search is sub-millisecond.
4. Query: User question is vectorized with the same TF-IDF model, then top-K nearest neighbors are retrieved.
5. Result: Matched sections (with symptoms + steps) are returned and rendered in the UI.

Quick Start

# 1. Clone / unzip the project
cd resolveit

# 2. Run (creates venv, installs deps, starts server)
bash start.sh

# 3. Open browser
open http://localhost:8000

API Reference

POST /api/search

Search the runbook index with a natural language query.

// Request
{ "query": "server out of disk space", "top_k": 3 }

// Response
{
  "query": "server out of disk space",
  "results": [
    {
      "title": "ERROR: Disk Space Full (>95%)",
      "category": "Infrastructure",
      "symptoms": "Write errors, application crashes...",
      "steps": ["1. Check disk usage: df -h", "2. Find large files..."],
      "resolution_time": "10-20 minutes",
      "source_file": "server_errors.txt",
      "score": 0.82
    }
  ],
  "total_found": 3
}

GET /api/health

{ "status": "healthy", "indexed_sections": 15, "runbook_files": 3 }

GET /api/runbooks

List all indexed sections.

POST /api/upload

Upload a new .txt runbook file. Automatically rebuilds the index.

curl -X POST http://localhost:8000/api/upload \
  -F "file=@my_runbook.txt"

POST /api/rebuild

Force-rebuild the FAISS index from all runbooks in the runbooks/ directory.

Runbook Format

Structure your .txt runbooks like this:

RUNBOOK: My Runbook Title
Category: Infrastructure

=== ERROR: Short Error Title ===
Symptoms: Brief description of symptoms here
Steps:
1. First step with commands like: df -h
2. Second step
3. Third step
Resolution Time: 10-20 minutes

=== ERROR: Another Error ===
...

Extending the System

Add more runbooks

Drop any .txt file following the format above into runbooks/, then call POST /api/rebuild or use the Upload button in the UI.

Upgrade to dense embeddings

Replace the TF-IDF vectorizer in indexer.py with sentence-transformers (e.g. all-MiniLM-L6-v2) for better semantic understanding. The FAISS index and search logic remain unchanged.

Add Claude AI summarization

Call the Anthropic API to summarize and rerank results before returning them:

import anthropic
client = anthropic.Anthropic()
summary = client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": f"Summarize these resolution steps for: {query}\n\n{steps}"}]
)

Tech Stack

Component	Technology
Vector Search	FAISS (IndexFlatIP)
Embeddings	TF-IDF + trigrams (scikit-learn)
Backend	FastAPI + Uvicorn
Frontend	Vanilla JS + HTML/CSS
Language	Python 3.10+