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)

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

Build Frontend Assets (optional, for local UI build)

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.

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:

ragviz serve --port 8787

Open http://localhost:8787.

---

Mode 2: Zero-Code-Change LangChain Tracing

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

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:

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.

ragviz serve --port 8787

ragviz run

Runs a Python script with optional auto-instrumentation.

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

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

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

In another terminal:

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:

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

Happy hacking with ragviz.