Metadata-Version: 2.5
Name: rag-hub
Version: 0.1.0
Summary: A visual debugger for RAG pipelines — see exactly where your pipeline breaks
Project-URL: Homepage, https://github.com/yourusername/rag-debugger
Project-URL: Documentation, https://github.com/yourusername/rag-debugger/docs
Project-URL: Issues, https://github.com/yourusername/rag-debugger/issues
Author: kanhaiya
License: MIT License
        
        Copyright (c) 2026 Kanhaiya
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: debugger,langchain,llama-index,llm,observability,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: websockets>=11.0
Provides-Extra: all
Requires-Dist: langchain>=0.1.0; extra == 'all'
Requires-Dist: llama-index>=0.10.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == 'langchain'
Provides-Extra: llama-index
Requires-Dist: llama-index>=0.10.0; extra == 'llama-index'
Description-Content-Type: text/markdown

# RAG Debugger 🔍

**Visualize exactly where your RAG pipeline breaks.**

Most RAG problems are invisible — wrong chunks retrieved, 
LLM given bad context, silent failures at retrieval. 
RAG Debugger makes every step visible so you can fix it fast.

```
QUERY  "What is the cancellation policy?"

  ✏️  Query Rewriter    success    0.014ms
  🔍  Vector Search     success    0.025ms    3 chunks  top score 0.94
  🤖  GPT-4o            error      0.012ms    ← broke here

💥 Pipeline broke at: llm
   RuntimeError: OpenAI API rate limit exceeded
```

---

## What It Does

- **Traces every step** — query transform, embedding, retrieval, rerank, LLM
- **Shows your chunks** — see exactly what context your LLM received
- **Catches breaks** — know immediately which stage failed and why
- **Visual UI** — pipeline flowchart at `localhost:7384`, opens automatically
- **Terminal output** — rich summary printed after every trace
- **Works with anything** — LangChain, LlamaIndex, or raw Python

---

## Install

```bash
pip install rag-debugger
```

With framework support:

```bash
pip install rag-debugger[langchain]
pip install rag-debugger[llama-index]
pip install rag-debugger[all]
```

---

## Quickstart

### Generic pipeline (works with anything)

```python
from rag_debugger import init, StepType, Chunk

debugger = init()   # starts UI at localhost:7384

with debugger.trace("What is the refund policy?") as t:

    with debugger.step(StepType.RETRIEVAL, "My Retriever") as s:
        chunks = my_retriever.search(t.query)
        s.chunks = chunks

    with debugger.step(StepType.LLM, "GPT-4o") as s:
        answer = my_llm.generate(t.query, chunks)
        s.model = "gpt-4o"

    t.answer = answer
```

### LangChain

```python
from rag_debugger import init

debugger = init(framework="langchain")

# pass handler to any LangChain component
chain.invoke(
    {"query": "What is the refund policy?"},
    config={"callbacks": [debugger.handler]}
)
```

### Decorator style

```python
from rag_debugger import init, StepType

debugger = init()

@debugger.trace_step(StepType.RETRIEVAL, "My Retriever")
def retrieve(query):
    return vector_store.search(query)
```

---

## What You See

### Terminal

```
╭─────────────────────────────────────────╮
│  RAG Debugger — Trace a1b2c3d4          │
╰─────────────────────────────────────────╯

QUERY  "What is the refund policy?"

  ✏️   Query Rewriter    success    0.014ms
  🔍   Vector Search     success    0.025ms    3 chunks  top score 0.94
  🤖   GPT-4o            success    0.012ms    312→52 tokens

ANSWER  "You have 30 days to request a refund."

Total: 0.051ms  |  framework: custom  |  steps: 3
```

### Browser UI — `localhost:7384`

- Left panel — all traces with status and timing
- Right panel — full pipeline flowchart
- Click any step — see chunks, tokens, errors, input/output
- Live updates — new traces appear instantly as pipeline runs

---

## How It Works

```
Your RAG pipeline
      │
      ▼
import rag_debugger       ← wraps each stage
      │
      ├── records every step (timing, chunks, tokens, errors)
      │
      ├── terminal summary (rich)
      │
      └── FastAPI server  ← localhost:7384
              │
              └── pipeline flowchart UI
```

No external services. No API keys. Runs entirely on your machine.

---

## Examples

```bash
# see a working pipeline
python examples/basic_usage.py

# see the debugger catching errors
python examples/broken_pipeline.py
```

---

## Project Structure

```
rag_debugger/
├── core/           ← tracer, store, models
├── integrations/   ← langchain, llama_index, generic
├── server/         ← fastapi + websocket
├── ui/             ← browser interface
└── cli/            ← terminal output
```

---

## Contributing

Pull requests welcome. See `CONTRIBUTING.md` to get started.

Areas that need work:
- Haystack integration
- LlamaIndex deeper event coverage  
- Embedding step visualization
- Trace export to JSON/CSV

---

## License

MIT