Metadata-Version: 2.4
Name: ragviz
Version: 0.1.1
Summary: Decorator-First RAG Visualizer
Author: AI Developer Friendly
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: uvicorn>=0.23.0
Requires-Dist: websockets>=11.0.3
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# ragviz (RAG Wizard)

`ragviz` is a local-first RAG tracing dashboard for Python applications.
It helps you inspect pipeline runs, step latency, inputs/outputs, and execution flow without sending data to the cloud.

This README is the user manual for installing, running, and troubleshooting `ragviz`.

## What You Get

- Decorator mode for explicit tracing (`@visualize_rag`, `trace_step`)
- Zero-code-change LangChain mode (`ragviz run -- python app.py`)
- Local SQLite event storage
- FastAPI API + WebSocket backend
- React dashboard for runs, flow graph, and event timeline

## Requirements

- Python `>=3.9`
- Node.js (only needed if you want to build the frontend locally)

## Installation

### Install From Source (Recommended for local development)

```bash
git clone <repo-url>
cd ragviz
pip install -e .
```

### Build Frontend Assets (optional, for local UI build)

```bash
cd frontend
npm install
npm run build
cd ..
```

If `frontend/dist` exists, the backend serves it automatically.

## Quickstart

You can use `ragviz` in two ways:

1. Decorator-based tracing for custom Python pipelines
2. Zero-code-change LangChain auto-instrumentation via CLI wrapper

---

## Mode 1: Decorator-Based Tracing

Use this when you control the code and want explicit, stable step boundaries.

```python
import time
from ragviz import visualize_rag, trace_step

@visualize_rag
def answer_question(query: str) -> str:
    with trace_step("retrieve"):
        chunks = retrieve(query)

    with trace_step("generate"):
        answer = generate(query, chunks)

    return answer

def retrieve(query: str):
    time.sleep(0.2)
    return ["chunk1", "chunk2"]

def generate(query: str, chunks: list[str]):
    time.sleep(0.4)
    return f"Answer for {query} using {len(chunks)} chunks"

if __name__ == "__main__":
    answer_question("What is ragviz?")
```

Run your script, then start the UI server:

```bash
ragviz serve --port 8787
```

Open [http://localhost:8787](http://localhost:8787).

---

## Mode 2: Zero-Code-Change LangChain Tracing

Use this when you do not want to edit application code.

```bash
ragviz run -- python your_langchain_app.py
```

What this does:

- installs LangChain callback auto-instrumentation
- runs your script in-process so callbacks are active
- starts the ragviz UI server (unless `--no-server` is passed)

Smoke example:

```bash
ragviz run -- python examples/langchain_smoke.py
```

---

## Dashboard Guide

### Left Panel: Pipeline Runs

- Lists recent runs ordered by time
- Shows run status and total duration
- Click a run to open details

### Top Right: Execution Flow

- DAG-like flow rendered from parent-child step relationships
- Shows step type (`step_started`, `step_completed`, `step_failed`)
- Dashed fallback edges connect orphan root nodes

### Bottom Right: Event Timeline

- Full step log in chronological order
- Inputs and outputs shown as JSON blocks
- Errors shown inline with highlighting

---

## CLI Reference

### `ragviz serve`

Starts only the backend/dashboard server.

```bash
ragviz serve --port 8787
```

### `ragviz run`

Runs a Python script with optional auto-instrumentation.

```bash
ragviz run -- python app.py
ragviz run --no-server -- python app.py
```

Arguments:

- `--port <int>`: UI server port (default `8787`)
- `--no-server`: do not run the FastAPI UI server
- `--`: separator before Python command

---

## API Endpoints

- `GET /api/health` - health probe
- `GET /api/runs` - list recent runs
- `GET /api/runs/{run_id}/steps` - list steps for one run
- `WS /api/ws` - live event stream

---

## Project Structure

```text
ragviz/
├── ragviz/
│   ├── __init__.py
│   ├── cli.py
│   ├── decorator.py
│   ├── langchain_integration.py
│   ├── event_bus.py
│   ├── storage.py
│   ├── server.py
│   └── redaction.py
├── frontend/
│   ├── src/
│   └── dist/               # generated
├── examples/
│   └── langchain_smoke.py
├── pyproject.toml
└── README.md
```

---

## Troubleshooting

### No runs appear in UI

- Ensure your script actually executed traced code.
- For decorator mode, confirm `@visualize_rag` is applied to the top-level pipeline function.
- For LangChain mode, run with:
  - `ragviz run -- python your_script.py`

### WebSocket updates not live

- Refresh page and check `ws://localhost:8787/api/ws`.
- If using HTTPS, ensure browser uses `wss://`.

### LangChain auto mode says not detected

- Install compatible packages:
  - `pip install langchain langchain-core`

### Data file location

- SQLite DB defaults to `ragviz.db` in current working directory.
- Override with:
  - `RAGVIZ_DB_PATH=/path/to/db.sqlite`

### UI missing or blank

- Build frontend assets:
  - `cd frontend && npm install && npm run build`

---

## FAQ

### Is data sent to any cloud service?

No. Data stays local unless your own pipeline sends data externally.

### Do I need decorators for LangChain?

No. `ragviz run` supports zero-code-change instrumentation for LangChain.

### Can I use both decorator and LangChain auto mode?

Yes, but you may capture overlapping traces. Prefer one approach per run for cleaner timelines.

### Is this production telemetry?

This is currently a developer observability tool focused on local debugging and UX.

---

## Local Development

```bash
pip install -e .
cd frontend
npm install
npm run dev
```

In another terminal:

```bash
ragviz serve --port 8787
```

---

## Release Notes for Maintainers

- Package metadata and wheel/sdist configuration live in `pyproject.toml`.
- Keep root clean (no duplicate top-level package modules).
- Validate before release:

```bash
python3 -m build
python3 -m twine check dist/*
```

Happy hacking with `ragviz`.
