rag-debugger 1.0.0__py3-none-any.whl

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/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/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)

rag_debugger/adapters/openai.py

@@ -0,0 +1,112 @@
+"""OpenAI wrapper adapter for RAG Debugger SDK."""
+
+try:
+    import openai
+except ImportError:
+    raise ImportError(
+        "OpenAI adapter requires openai. "
+        "Install with: pip install rag-debugger[openai]"
+    )
+
+import asyncio
+import time
+import uuid
+from typing import Any
+from ..context import get_or_create_trace_id, get_or_create_query_id
+from ..emitter import emit
+
+
+class RAGDebuggerOpenAI:
+    """
+    Wrapper around OpenAI client that auto-instruments embedding and completion calls.
+    Usage:
+        from rag_debugger.adapters.openai import RAGDebuggerOpenAI
+        client = RAGDebuggerOpenAI(openai.AsyncOpenAI())
+        embeddings = await client.embed("hello world")
+        response = await client.complete("hello world", system="You are helpful")
+    """
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    async def embed(self, text: str, model: str = "text-embedding-3-small") -> list[float]:
+        ts_start = time.time()
+        try:
+            response = await self._client.embeddings.create(
+                input=text,
+                model=model,
+            )
+            vector = response.data[0].embedding
+            duration = (time.time() - ts_start) * 1000
+
+            await emit({
+                "id": str(uuid.uuid4()),
+                "trace_id": get_or_create_trace_id(),
+                "query_id": get_or_create_query_id(),
+                "stage": "embed",
+                "ts_start": ts_start,
+                "duration_ms": duration,
+                "query_text": text[:500],
+                "query_vector": vector[:1536],
+            })
+
+            return vector
+        except Exception as e:
+            duration = (time.time() - ts_start) * 1000
+            await emit({
+                "id": str(uuid.uuid4()),
+                "trace_id": get_or_create_trace_id(),
+                "query_id": get_or_create_query_id(),
+                "stage": "embed",
+                "ts_start": ts_start,
+                "duration_ms": duration,
+                "query_text": text[:500],
+                "error": str(e),
+            })
+            raise
+
+    async def complete(
+        self,
+        prompt: str,
+        system: str = "You are a helpful assistant.",
+        model: str = "gpt-4o-mini",
+        **kwargs,
+    ) -> str:
+        ts_start = time.time()
+        try:
+            response = await self._client.chat.completions.create(
+                model=model,
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": prompt},
+                ],
+                **kwargs,
+            )
+            answer = response.choices[0].message.content or ""
+            duration = (time.time() - ts_start) * 1000
+
+            await emit({
+                "id": str(uuid.uuid4()),
+                "trace_id": get_or_create_trace_id(),
+                "query_id": get_or_create_query_id(),
+                "stage": "generate",
+                "ts_start": ts_start,
+                "duration_ms": duration,
+                "query_text": prompt[:500],
+                "generated_answer": answer,
+            })
+
+            return answer
+        except Exception as e:
+            duration = (time.time() - ts_start) * 1000
+            await emit({
+                "id": str(uuid.uuid4()),
+                "trace_id": get_or_create_trace_id(),
+                "query_id": get_or_create_query_id(),
+                "stage": "generate",
+                "ts_start": ts_start,
+                "duration_ms": duration,
+                "query_text": prompt[:500],
+                "error": str(e),
+            })
+            raise

rag_debugger/context.py

@@ -0,0 +1,34 @@
+from contextvars import ContextVar
+import uuid
+
+_trace_id: ContextVar[str] = ContextVar("rag_trace_id", default="")
+_query_id: ContextVar[str] = ContextVar("rag_query_id", default="")
+
+
+def get_or_create_trace_id() -> str:
+    tid = _trace_id.get()
+    if not tid:
+        tid = str(uuid.uuid4())
+        _trace_id.set(tid)
+    return tid
+
+
+def get_or_create_query_id() -> str:
+    qid = _query_id.get()
+    if not qid:
+        qid = str(uuid.uuid4())
+        _query_id.set(qid)
+    return qid
+
+
+def set_trace_id(tid: str) -> None:
+    _trace_id.set(tid)
+
+
+def set_query_id(qid: str) -> None:
+    _query_id.set(qid)
+
+
+def reset_context() -> None:
+    _trace_id.set("")
+    _query_id.set("")

rag_debugger/decorators.py

@@ -0,0 +1,180 @@
+import asyncio
+import time
+import uuid
+from collections import OrderedDict
+from functools import wraps
+from typing import Literal
+from .context import get_or_create_trace_id, get_or_create_query_id
+from .emitter import emit
+
+RAGStage = Literal["embed", "retrieve", "rerank", "generate"]
+
+# Track stages per query for session_complete calculation.
+# OrderedDict for FIFO eviction when cap is exceeded (BUG 1 fix).
+_query_stages: OrderedDict[str, list] = OrderedDict()
+_STAGES_CAP = 500
+_STAGES_EVICT = 100
+
+MAX_VECTOR_DIMS = 4096  # Safety cap — no real model exceeds this
+
+
+def _enforce_stages_cap() -> None:
+    """Evict oldest entries if _query_stages exceeds the safety cap."""
+    if len(_query_stages) > _STAGES_CAP:
+        for _ in range(_STAGES_EVICT):
+            if _query_stages:
+                _query_stages.popitem(last=False)
+
+
+def rag_trace(stage: RAGStage):
+    """
+    Decorator for any RAG pipeline function.
+    Works with both async and sync functions.
+    Auto-generates trace_id and query_id via ContextVar.
+    Emits session_complete after 'generate' stage.
+
+    Sync function support is best-effort. If the decorated sync function
+    is called inside an async framework (FastAPI, Django async views, etc.),
+    use ``async def`` with ``await`` instead.
+    """
+    def decorator(func):
+        @wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            trace_id = get_or_create_trace_id()
+            query_id = get_or_create_query_id()
+            event_id = str(uuid.uuid4())
+            ts_start = time.time()
+
+            event = {
+                "id": event_id,
+                "trace_id": trace_id,
+                "query_id": query_id,
+                "stage": stage,
+                "ts_start": ts_start,
+            }
+
+            # Capture query text from first string argument
+            if args and isinstance(args[0], str):
+                event["query_text"] = args[0][:500]  # truncate
+
+            try:
+                result = await func(*args, **kwargs)
+                event["duration_ms"] = (time.time() - ts_start) * 1000
+                event["output"] = _safe_serialize(result, stage)
+                _enrich_event(event, result, stage)
+                await emit(event)
+                _track_stage(query_id, stage, event)
+
+                # Emit session_complete after generate
+                if stage == "generate":
+                    await _emit_session_complete(query_id, trace_id, event, result)
+
+                return result
+            except Exception as e:
+                event["duration_ms"] = (time.time() - ts_start) * 1000
+                event["error"] = str(e)
+                _query_stages.pop(query_id, None)  # BUG 1: clean up on error
+                await emit(event)
+                raise
+
+        @wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            # BUG 2 fix: simple, honest sync support
+            try:
+                loop = asyncio.get_running_loop()
+                if loop.is_running():
+                    raise RuntimeError(
+                        "rag_trace: cannot use a sync function inside a running "
+                        "async event loop. Use 'async def' with 'await' instead."
+                    )
+            except RuntimeError as e:
+                if "cannot use a sync function" in str(e):
+                    raise
+                # No running loop — safe to use asyncio.run()
+                pass
+            return asyncio.run(async_wrapper(*args, **kwargs))
+
+        return async_wrapper if asyncio.iscoroutinefunction(func) else sync_wrapper
+    return decorator
+
+
+def _enrich_event(event: dict, result, stage: str) -> None:
+    """Add stage-specific output fields."""
+    if stage == "embed" and isinstance(result, list):
+        event["query_vector"] = result[:MAX_VECTOR_DIMS]
+        event.setdefault("metadata", {})["vector_dims"] = len(result)
+    elif stage in ("retrieve", "rerank") and isinstance(result, list):
+        event["chunks"] = [_to_chunk_dict(c, i) for i, c in enumerate(result)]
+    elif stage == "generate" and isinstance(result, str):
+        event["generated_answer"] = result
+
+
+def _to_chunk_dict(chunk, rank: int) -> dict:
+    # BUG 6: Check for LangChain Document (and similar objects with page_content)
+    if hasattr(chunk, "page_content"):
+        metadata = dict(chunk.metadata) if hasattr(chunk, "metadata") and chunk.metadata else {}
+        return {
+            "chunk_id": getattr(chunk, "id", None) or str(rank),
+            "text": str(chunk.page_content)[:1000],
+            "cosine_score": float(metadata.get("score", metadata.get("relevance_score", 0.0))),
+            "rerank_score": metadata.get("rerank_score"),
+            "final_rank": rank,
+            "metadata": metadata,
+        }
+    if isinstance(chunk, dict):
+        return {
+            "chunk_id": chunk.get("id", str(rank)),
+            "text": str(chunk.get("text", chunk.get("page_content", "")))[:1000],
+            "cosine_score": float(chunk.get("score", chunk.get("cosine_score", 0.0))),
+            "rerank_score": chunk.get("rerank_score"),
+            "final_rank": rank,
+            "metadata": chunk.get("metadata", {}),
+        }
+    return {
+        "chunk_id": str(rank),
+        "text": str(chunk)[:500],
+        "cosine_score": 0.0,
+        "final_rank": rank,
+    }
+
+
+def _safe_serialize(value, stage: str):
+    if stage == "embed":
+        return None  # vectors sent separately
+    try:
+        import json
+        json.dumps(value)
+        return value
+    except Exception:
+        return str(value)[:200]
+
+
+def _track_stage(query_id: str, stage: str, event: dict) -> None:
+    if query_id not in _query_stages:
+        _query_stages[query_id] = []
+    _query_stages[query_id].append({
+        "stage": stage,
+        "duration_ms": event.get("duration_ms", 0),
+    })
+    _enforce_stages_cap()
+
+
+async def _emit_session_complete(
+    query_id: str, trace_id: str, gen_event: dict, answer
+) -> None:
+    stages = _query_stages.pop(query_id, [])
+    total_ms = sum(s["duration_ms"] for s in stages)
+    await emit({
+        "id": str(uuid.uuid4()),
+        "trace_id": trace_id,
+        "query_id": query_id,
+        "stage": "session_complete",
+        "ts_start": time.time(),
+        "duration_ms": total_ms,
+        "query_text": gen_event.get("query_text"),
+        "generated_answer": str(answer) if answer else None,
+        "metadata": {
+            "stage_count": len(stages),
+            "has_error": False,
+        },
+    })

rag_debugger/emitter.py

@@ -0,0 +1,72 @@
+import asyncio
+import sys
+import httpx
+from .scrubber import scrub_event
+
+_queue: asyncio.Queue | None = None
+_dashboard_url: str = "http://localhost:7777"
+_worker_task: asyncio.Task | None = None
+_init_lock: asyncio.Lock | None = None
+
+# BUG 3: Track dropped events and warn periodically
+_drop_count: int = 0
+
+
+def configure(dashboard_url: str) -> None:
+    global _dashboard_url
+    _dashboard_url = dashboard_url.rstrip("/")
+
+
+async def _emit_worker() -> None:
+    """Background worker that drains the queue and POSTs events."""
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        while True:
+            try:
+                event = await asyncio.wait_for(_queue.get(), timeout=1.0)
+                for attempt in range(3):
+                    try:
+                        await client.post(f"{_dashboard_url}/events", json=event)
+                        break
+                    except Exception:
+                        await asyncio.sleep(0.5 * (2 ** attempt))
+                _queue.task_done()
+            except asyncio.TimeoutError:
+                continue
+            except asyncio.CancelledError:
+                break
+
+
+async def _ensure_worker_started() -> None:
+    """Lazily initialize queue and worker on first emit (BUG 4 fix)."""
+    global _queue, _worker_task, _init_lock
+    if _queue is not None:
+        return  # already started
+    if _init_lock is None:
+        _init_lock = asyncio.Lock()
+    async with _init_lock:
+        if _queue is None:  # double-check after acquiring lock
+            _queue = asyncio.Queue(maxsize=1000)
+            _worker_task = asyncio.create_task(_emit_worker())
+
+
+async def stop_worker() -> None:
+    if _worker_task:
+        await _queue.join()
+        _worker_task.cancel()
+
+
+async def emit(event: dict) -> None:
+    """Non-blocking enqueue. Warns on drops instead of silently losing events."""
+    global _drop_count
+    await _ensure_worker_started()
+    scrubbed = scrub_event(event)
+    try:
+        _queue.put_nowait(scrubbed)
+    except asyncio.QueueFull:
+        _drop_count += 1
+        if _drop_count == 1 or _drop_count % 50 == 0:
+            print(
+                f"[rag-debugger] WARNING: event dropped (total dropped: {_drop_count})"
+                f" — is the server running at {_dashboard_url}?",
+                file=sys.stderr,
+            )

rag_debugger/models.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel, Field
+from typing import Literal
+import uuid
+
+
+class ChunkScore(BaseModel):
+    chunk_id: str
+    text: str
+    cosine_score: float
+    rerank_score: float | None = None
+    final_rank: int
+    metadata: dict = Field(default_factory=dict)
+
+
+class RAGEvent(BaseModel):
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    trace_id: str
+    query_id: str
+    stage: Literal["embed", "retrieve", "rerank", "generate", "session_complete"]
+    ts_start: float
+    duration_ms: float | None = None
+    query_text: str | None = None
+    query_vector: list[float] | None = None
+    chunks: list[ChunkScore] | None = None
+    generated_answer: str | None = None
+    error: str | None = None
+    metadata: dict = Field(default_factory=dict)

rag_debugger/scrubber.py

@@ -0,0 +1,29 @@
+"""PII scrubber — redacts emails, phone numbers, SSNs from event payloads."""
+import re
+
+_PATTERNS = [
+    (re.compile(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'), "[EMAIL]"),
+    (re.compile(r'\b\d{3}[-.]?\d{3}[-.]?\d{4}\b'), "[PHONE]"),
+    (re.compile(r'\b\d{3}-\d{2}-\d{4}\b'), "[SSN]"),
+    (re.compile(r'\bsk-[a-zA-Z0-9]{20,}\b'), "[API_KEY]"),
+]
+
+
+def scrub(value):
+    """Recursively scrub PII from strings, dicts, and lists."""
+    if isinstance(value, str):
+        if not value:
+            return value
+        for pattern, replacement in _PATTERNS:
+            value = pattern.sub(replacement, value)
+        return value
+    elif isinstance(value, dict):
+        return {k: scrub(v) for k, v in value.items()}
+    elif isinstance(value, list):
+        return [scrub(item) for item in value]
+    return value
+
+
+def scrub_event(event: dict) -> dict:
+    """Scrub PII from all string fields recursively in an event dict."""
+    return scrub(event)

rag_debugger-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+rag_debugger/__init__.py,sha256=F0s6eeTEECWRfCETcGqAiyi8gjgfsuPcg4HmIEiWShs,2191
+rag_debugger/context.py,sha256=n3GN4WZsq69GQAkrbr8OvpSX-y2strLr8wDBr6isTJ8,691
+rag_debugger/decorators.py,sha256=0O3Ub7Sh1o5Gg0tS2CJHfipfO7RKhVSnY2HCT0Wn0L4,6510
+rag_debugger/emitter.py,sha256=zAXo_PyVJRHx5aY9giIL8oXIssPUOykZgSlFmQs77_s,2341
+rag_debugger/models.py,sha256=lI6cy9QfwaA69kXa8__fz-ZtDJpzfRqcSVlc3fTmOxI,777
+rag_debugger/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rag_debugger/scrubber.py,sha256=e32i_k5X6KbRluiHxZhKvE3ei-38yF8JLChcWUMAZ0k,973
+rag_debugger/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rag_debugger/adapters/langchain.py,sha256=TKLpfvST1tcACjA9ZF4_r098xWPIn7A9n3lbxEkk1Wc,2783
+rag_debugger/adapters/llamaindex.py,sha256=Afs4COAZ_JoN0j9TpYlrmHS7Gic6oOrb65mwpKqbSCg,3319
+rag_debugger/adapters/openai.py,sha256=fzCSi-qbeqLhjC5zfb63BzfXjlYMA5fL9KZGhQs-Dmg,3682
+rag_debugger-1.0.0.dist-info/METADATA,sha256=8udIDBvuyYk-3-D7b0Dkd59Zejt82PB037OCn_N1tp8,5725
+rag_debugger-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+rag_debugger-1.0.0.dist-info/RECORD,,

rag_debugger-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any