rag-debugger 1.0.0__tar.gz

rag_debugger-1.0.0/.gitignore

@@ -0,0 +1,70 @@
+# IDE
+.idea
+*.iml
+.vscode/settings.json
+
+# misc
+.DS_Store
+npm-debug*
+**/*.tsbuildinfo
+
+# Node
+**/node_modules/
+**/.pnpm-store/
+
+# Next.js
+**/.next/
+**/out/
+
+# Build
+**/build/
+**/dist/
+
+# Python
+**/__pycache__/
+**/*.pyc
+**/*.pyo
+**/.venv/
+**/venv/
+*.egg-info/
+**/*.egg-info/
+**/.pytest_cache/
+
+# DuckDB
+*.duckdb
+*.duckdb.wal
+
+# Env
+*.swp
+*.env
+*.env.*
+*.env.local
+
+# Certs
+*.pem
+
+# Turbo
+.turbo
+
+# Firebase
+**/.firebase/
+
+# Configs
+**/public/conf.js
+
+# Archives
+*.zip
+
+# Testing
+**/test-results/
+**/playwright-report/
+**/blob-report/
+**/playwright/.cache/
+
+# Million Lint
+.million
+
+# Sentence-transformers cache
+**/sentence_transformers/
+**/*.duckdb
+**/*.duckdb.wal

rag_debugger-1.0.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: rag-debugger
+Version: 1.0.0
+Summary: Real-time debugging SDK for RAG pipelines
+Project-URL: Homepage, https://github.com/ChanduBobbili/rag-debugger
+Project-URL: Repository, https://github.com/ChanduBobbili/rag-debugger
+Project-URL: Issues, https://github.com/ChanduBobbili/rag-debugger/issues
+Author: Chandu Bobbili
+License: MIT
+Keywords: debugging,llm,observability,rag,tracing
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
+Requires-Dist: openai>=1.0.0; extra == 'all'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# RAG Debugger SDK 🔍
+
+[![PyPI version](https://img.shields.io/pypi/v/rag-debugger.svg)](https://pypi.org/project/rag-debugger/)
+[![Python](https://img.shields.io/pypi/pyversions/rag-debugger.svg)](https://pypi.org/project/rag-debugger/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**One-line decorator to debug your RAG pipelines in real time.**
+
+Instrument any Python RAG pipeline with `@rag_trace` — captures inputs, outputs, timing, and errors for every stage (embed → retrieve → rerank → generate) and streams them to the [RAG Debugger Dashboard](https://github.com/ChanduBobbili/rag-debugger).
+
+## Features
+
+- 🔗 **One decorator** — `@rag_trace("retrieve")` on your existing functions
+- ⚡ **Non-blocking** — async background worker, never slows your pipeline
+- 🧵 **Auto-correlation** — `trace_id` / `query_id` via `ContextVar` (no manual threading)
+- 🔒 **PII scrubbing** — emails, phone numbers, SSNs, API keys automatically redacted
+- 🔌 **Framework adapters** — LangChain, LlamaIndex, and OpenAI out of the box
+- 🛡️ **Safe** — errors in the SDK never crash your application
+
+## Installation
+
+```bash
+pip install rag-debugger
+```
+
+With framework adapters:
+
+```bash
+pip install rag-debugger[langchain]    # LangChain
+pip install rag-debugger[llamaindex]   # LlamaIndex
+pip install rag-debugger[openai]       # OpenAI
+pip install rag-debugger[all]          # All adapters
+```
+
+## Quick Start
+
+```python
+from rag_debugger import init, rag_trace
+
+# 1. Point to your RAG Debugger server
+init(dashboard_url="http://localhost:7777")
+
+# 2. Decorate your pipeline functions
+@rag_trace("embed")
+async def embed_query(query: str) -> list[float]:
+    return await my_embedder.embed(query)
+
+@rag_trace("retrieve")
+async def retrieve_chunks(vector: list[float], k: int = 10):
+    return await vector_store.query(vector, k)
+
+@rag_trace("rerank")
+async def rerank(query: str, chunks: list) -> list:
+    return await reranker.rerank(query, chunks)
+
+@rag_trace("generate")
+async def generate(query: str, context: str) -> str:
+    return await llm.complete(query, context)
+
+# 3. Call your pipeline — traces appear in the dashboard
+answer = await generate(query, context)
+```
+
+The decorator automatically:
+
+- Generates `trace_id` and `query_id` per request
+- Captures function inputs and outputs
+- Measures `duration_ms` for each stage
+- Emits a `session_complete` summary after the generate stage
+- Scrubs PII before sending
+
+## Framework Adapters
+
+### LangChain
+
+```python
+from rag_debugger.adapters.langchain import RAGDebuggerCallback
+
+handler = RAGDebuggerCallback()
+chain.invoke({"query": "..."}, config={"callbacks": [handler]})
+```
+
+### LlamaIndex
+
+```python
+from rag_debugger.adapters.llamaindex import RAGDebuggerLlamaIndex
+from llama_index.core.callbacks import CallbackManager
+
+handler = RAGDebuggerLlamaIndex()
+callback_manager = CallbackManager([handler])
+index = VectorStoreIndex.from_documents(docs, callback_manager=callback_manager)
+```
+
+### OpenAI
+
+```python
+from rag_debugger.adapters.openai import RAGDebuggerOpenAI
+
+client = RAGDebuggerOpenAI(openai.AsyncOpenAI())
+embedding = await client.embed("What is RAG?")
+response = await client.complete("Explain RAG")
+```
+
+## Advanced Usage
+
+### Explicit Trace Control
+
+```python
+from rag_debugger import new_trace, reset_context
+
+# Group events under a custom trace
+new_trace(trace_id="my-trace-123", query_id="q-001")
+await embed_query("What is RAG?")
+await retrieve_chunks(vector)
+
+# Reset for the next request
+reset_context()
+```
+
+### Async Context Manager
+
+```python
+import rag_debugger
+
+async with rag_debugger.trace(trace_id="req-123") as t:
+    print(t.trace_id)
+    result = await my_rag_pipeline(query)
+# Context is automatically restored after the block
+```
+
+## Documentation
+
+- [Full SDK Documentation](https://github.com/ChanduBobbili/rag-debugger/blob/main/docs/SDK.md)
+- [Server Documentation](https://github.com/ChanduBobbili/rag-debugger/blob/main/docs/SERVER.md)
+- [Dashboard Documentation](https://github.com/ChanduBobbili/rag-debugger/blob/main/docs/DASHBOARD.md)
+
+## License
+
+MIT — see [LICENSE](https://github.com/ChanduBobbili/rag-debugger/blob/main/LICENSE) for details.

rag_debugger-1.0.0/README.md

@@ -0,0 +1,139 @@
+# RAG Debugger SDK 🔍
+
+[![PyPI version](https://img.shields.io/pypi/v/rag-debugger.svg)](https://pypi.org/project/rag-debugger/)
+[![Python](https://img.shields.io/pypi/pyversions/rag-debugger.svg)](https://pypi.org/project/rag-debugger/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**One-line decorator to debug your RAG pipelines in real time.**
+
+Instrument any Python RAG pipeline with `@rag_trace` — captures inputs, outputs, timing, and errors for every stage (embed → retrieve → rerank → generate) and streams them to the [RAG Debugger Dashboard](https://github.com/ChanduBobbili/rag-debugger).
+
+## Features
+
+- 🔗 **One decorator** — `@rag_trace("retrieve")` on your existing functions
+- ⚡ **Non-blocking** — async background worker, never slows your pipeline
+- 🧵 **Auto-correlation** — `trace_id` / `query_id` via `ContextVar` (no manual threading)
+- 🔒 **PII scrubbing** — emails, phone numbers, SSNs, API keys automatically redacted
+- 🔌 **Framework adapters** — LangChain, LlamaIndex, and OpenAI out of the box
+- 🛡️ **Safe** — errors in the SDK never crash your application
+
+## Installation
+
+```bash
+pip install rag-debugger
+```
+
+With framework adapters:
+
+```bash
+pip install rag-debugger[langchain]    # LangChain
+pip install rag-debugger[llamaindex]   # LlamaIndex
+pip install rag-debugger[openai]       # OpenAI
+pip install rag-debugger[all]          # All adapters
+```
+
+## Quick Start
+
+```python
+from rag_debugger import init, rag_trace
+
+# 1. Point to your RAG Debugger server
+init(dashboard_url="http://localhost:7777")
+
+# 2. Decorate your pipeline functions
+@rag_trace("embed")
+async def embed_query(query: str) -> list[float]:
+    return await my_embedder.embed(query)
+
+@rag_trace("retrieve")
+async def retrieve_chunks(vector: list[float], k: int = 10):
+    return await vector_store.query(vector, k)
+
+@rag_trace("rerank")
+async def rerank(query: str, chunks: list) -> list:
+    return await reranker.rerank(query, chunks)
+
+@rag_trace("generate")
+async def generate(query: str, context: str) -> str:
+    return await llm.complete(query, context)
+
+# 3. Call your pipeline — traces appear in the dashboard
+answer = await generate(query, context)
+```
+
+The decorator automatically:
+
+- Generates `trace_id` and `query_id` per request
+- Captures function inputs and outputs
+- Measures `duration_ms` for each stage
+- Emits a `session_complete` summary after the generate stage
+- Scrubs PII before sending
+
+## Framework Adapters
+
+### LangChain
+
+```python
+from rag_debugger.adapters.langchain import RAGDebuggerCallback
+
+handler = RAGDebuggerCallback()
+chain.invoke({"query": "..."}, config={"callbacks": [handler]})
+```
+
+### LlamaIndex
+
+```python
+from rag_debugger.adapters.llamaindex import RAGDebuggerLlamaIndex
+from llama_index.core.callbacks import CallbackManager
+
+handler = RAGDebuggerLlamaIndex()
+callback_manager = CallbackManager([handler])
+index = VectorStoreIndex.from_documents(docs, callback_manager=callback_manager)
+```
+
+### OpenAI
+
+```python
+from rag_debugger.adapters.openai import RAGDebuggerOpenAI
+
+client = RAGDebuggerOpenAI(openai.AsyncOpenAI())
+embedding = await client.embed("What is RAG?")
+response = await client.complete("Explain RAG")
+```
+
+## Advanced Usage
+
+### Explicit Trace Control
+
+```python
+from rag_debugger import new_trace, reset_context
+
+# Group events under a custom trace
+new_trace(trace_id="my-trace-123", query_id="q-001")
+await embed_query("What is RAG?")
+await retrieve_chunks(vector)
+
+# Reset for the next request
+reset_context()
+```
+
+### Async Context Manager
+
+```python
+import rag_debugger
+
+async with rag_debugger.trace(trace_id="req-123") as t:
+    print(t.trace_id)
+    result = await my_rag_pipeline(query)
+# Context is automatically restored after the block
+```
+
+## Documentation
+
+- [Full SDK Documentation](https://github.com/ChanduBobbili/rag-debugger/blob/main/docs/SDK.md)
+- [Server Documentation](https://github.com/ChanduBobbili/rag-debugger/blob/main/docs/SERVER.md)
+- [Dashboard Documentation](https://github.com/ChanduBobbili/rag-debugger/blob/main/docs/DASHBOARD.md)
+
+## License
+
+MIT — see [LICENSE](https://github.com/ChanduBobbili/rag-debugger/blob/main/LICENSE) for details.

rag_debugger-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "rag-debugger"
+version = "1.0.0"
+description = "Real-time debugging SDK for RAG pipelines"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Chandu Bobbili"},
+]
+keywords = ["rag", "debugging", "llm", "observability", "tracing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.1.0"]
+llamaindex = ["llama-index-core>=0.10.0"]
+openai = ["openai>=1.0.0"]
+all = ["langchain-core>=0.1.0", "llama-index-core>=0.10.0", "openai>=1.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/ChanduBobbili/rag-debugger"
+Repository = "https://github.com/ChanduBobbili/rag-debugger"
+Issues = "https://github.com/ChanduBobbili/rag-debugger/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["rag_debugger"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

rag_debugger-1.0.0/rag_debugger/__init__.py

@@ -0,0 +1,77 @@
+import uuid
+from contextlib import asynccontextmanager
+from .emitter import configure, stop_worker
+from .decorators import rag_trace
+from .context import set_trace_id, set_query_id, reset_context
+from .context import _trace_id, _query_id
+
+__version__ = "1.0.0"
+
+_initialized = False
+
+
+def init(dashboard_url: str = "http://localhost:7777") -> None:
+    """Call once at application startup.
+
+    Configures the dashboard URL. The background worker starts lazily
+    on the first ``emit()`` call, so this is safe to call at import time
+    or before the async event loop is running.
+    """
+    global _initialized
+    configure(dashboard_url)
+    _initialized = True
+
+
+def new_trace(
+    trace_id: str | None = None,
+    query_id: str | None = None,
+) -> None:
+    """Explicitly set trace/query IDs (optional — auto-generated if not called)."""
+    if trace_id:
+        set_trace_id(trace_id)
+    if query_id:
+        set_query_id(query_id)
+
+
+class _TraceHandle:
+    """Lightweight handle returned by the ``trace()`` context manager."""
+    __slots__ = ("trace_id", "query_id")
+
+    def __init__(self, trace_id: str, query_id: str) -> None:
+        self.trace_id = trace_id
+        self.query_id = query_id
+
+
+@asynccontextmanager
+async def trace(
+    trace_id: str | None = None,
+    query_id: str | None = None,
+):
+    """Async context manager for explicit trace scoping.
+
+    Usage::
+
+        async with rag_debugger.trace(trace_id="req-123") as t:
+            print(t.trace_id)
+            result = await my_rag_pipeline(query)
+        # Context is automatically restored after the block
+
+    Nested ``trace()`` contexts work correctly — the outer context
+    is restored when the inner block exits.
+    """
+    tid = trace_id or str(uuid.uuid4())
+    qid = query_id or str(uuid.uuid4())
+
+    # Save previous values using ContextVar tokens
+    trace_token = _trace_id.set(tid)
+    query_token = _query_id.set(qid)
+
+    try:
+        yield _TraceHandle(tid, qid)
+    finally:
+        # Restore previous values
+        _trace_id.reset(trace_token)
+        _query_id.reset(query_token)
+
+
+__all__ = ["init", "rag_trace", "new_trace", "reset_context", "trace", "stop_worker", "__version__"]

rag_debugger-1.0.0/rag_debugger/adapters/langchain.py

@@ -0,0 +1,80 @@
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.outputs import LLMResult
+except ImportError:
+    raise ImportError(
+        "LangChain adapter requires langchain-core. "
+        "Install with: pip install rag-debugger[langchain]"
+    )
+
+import asyncio
+import time
+import uuid
+from ..context import get_or_create_trace_id, get_or_create_query_id
+from ..emitter import emit
+
+
+class RAGDebuggerCallback(BaseCallbackHandler):
+    """
+    LangChain callback handler.
+    Usage:
+        from rag_debugger.adapters.langchain import RAGDebuggerCallback
+        handler = RAGDebuggerCallback()
+        chain.invoke({"query": "..."}, config={"callbacks": [handler]})
+    """
+
+    def __init__(self) -> None:
+        self._retriever_start: float = 0
+        self._llm_start: float = 0
+        self._query_text: str = ""
+
+    def on_retriever_start(self, serialized, query, **kwargs) -> None:
+        self._retriever_start = time.time()
+        self._query_text = query
+
+    def on_retriever_end(self, documents, **kwargs) -> None:
+        duration = (time.time() - self._retriever_start) * 1000
+        chunks = [
+            {
+                "chunk_id": str(i),
+                "text": doc.page_content[:1000],
+                "cosine_score": doc.metadata.get("score", 0.0),
+                "final_rank": i,
+                "metadata": doc.metadata,
+            }
+            for i, doc in enumerate(documents)
+        ]
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(emit({
+                "id": str(uuid.uuid4()),
+                "trace_id": get_or_create_trace_id(),
+                "query_id": get_or_create_query_id(),
+                "stage": "retrieve",
+                "ts_start": self._retriever_start,
+                "duration_ms": duration,
+                "query_text": self._query_text,
+                "chunks": chunks,
+            }))
+        except RuntimeError:
+            pass  # No running loop — skip
+
+    def on_llm_start(self, serialized, prompts, **kwargs) -> None:
+        self._llm_start = time.time()
+
+    def on_llm_end(self, response: LLMResult, **kwargs) -> None:
+        duration = (time.time() - self._llm_start) * 1000
+        answer = response.generations[0][0].text if response.generations else ""
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(emit({
+                "id": str(uuid.uuid4()),
+                "trace_id": get_or_create_trace_id(),
+                "query_id": get_or_create_query_id(),
+                "stage": "generate",
+                "ts_start": self._llm_start,
+                "duration_ms": duration,
+                "generated_answer": answer,
+            }))
+        except RuntimeError:
+            pass

rag_debugger-1.0.0/rag_debugger/adapters/llamaindex.py

@@ -0,0 +1,105 @@
+"""LlamaIndex observer adapter for RAG Debugger SDK."""
+
+try:
+    from llama_index.core.callbacks import CallbackManager, CBEventType, LlamaDebugHandler
+    from llama_index.core.callbacks.base_handler import BaseCallbackHandler
+except ImportError:
+    raise ImportError(
+        "LlamaIndex adapter requires llama-index-core. "
+        "Install with: pip install rag-debugger[llamaindex]"
+    )
+
+import asyncio
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+from ..context import get_or_create_trace_id, get_or_create_query_id
+from ..emitter import emit
+
+
+class RAGDebuggerLlamaIndex(BaseCallbackHandler):
+    """
+    LlamaIndex callback handler for RAG Debugger.
+    Usage:
+        from rag_debugger.adapters.llamaindex import RAGDebuggerLlamaIndex
+        handler = RAGDebuggerLlamaIndex()
+        callback_manager = CallbackManager([handler])
+        index = VectorStoreIndex.from_documents(docs, callback_manager=callback_manager)
+    """
+
+    def __init__(self) -> None:
+        super().__init__([], [])
+        self._event_starts: Dict[str, float] = {}
+
+    def on_event_start(
+        self,
+        event_type: CBEventType,
+        payload: Optional[Dict[str, Any]] = None,
+        event_id: str = "",
+        **kwargs,
+    ) -> str:
+        self._event_starts[event_id] = time.time()
+        return event_id
+
+    def on_event_end(
+        self,
+        event_type: CBEventType,
+        payload: Optional[Dict[str, Any]] = None,
+        event_id: str = "",
+        **kwargs,
+    ) -> None:
+        start_time = self._event_starts.pop(event_id, time.time())
+        duration = (time.time() - start_time) * 1000
+
+        stage = self._map_event_type(event_type)
+        if stage is None:
+            return
+
+        event = {
+            "id": str(uuid.uuid4()),
+            "trace_id": get_or_create_trace_id(),
+            "query_id": get_or_create_query_id(),
+            "stage": stage,
+            "ts_start": start_time,
+            "duration_ms": duration,
+        }
+
+        if payload:
+            if stage == "retrieve" and "nodes" in payload:
+                event["chunks"] = [
+                    {
+                        "chunk_id": str(i),
+                        "text": str(getattr(n, "text", ""))[:1000],
+                        "cosine_score": float(getattr(n, "score", 0.0)),
+                        "final_rank": i,
+                    }
+                    for i, n in enumerate(payload["nodes"])
+                ]
+            elif stage == "generate" and "response" in payload:
+                event["generated_answer"] = str(payload["response"])
+
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(emit(event))
+        except RuntimeError:
+            pass
+
+    def start_trace(self, trace_id: Optional[str] = None) -> None:
+        pass
+
+    def end_trace(
+        self,
+        trace_id: Optional[str] = None,
+        trace_map: Optional[Dict[str, List[str]]] = None,
+    ) -> None:
+        pass
+
+    @staticmethod
+    def _map_event_type(event_type: CBEventType) -> Optional[str]:
+        mapping = {
+            CBEventType.EMBEDDING: "embed",
+            CBEventType.RETRIEVE: "retrieve",
+            CBEventType.RERANKING: "rerank",
+            CBEventType.LLM: "generate",
+        }
+        return mapping.get(event_type)