ragdebug 0.1.0__tar.gz

ragdebug-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: ragdebug
+Version: 0.1.0
+Summary: Observability SDK for RAG pipelines — auto-trace every stage of your RAG app.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: click>=8.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.7; extra == "tiktoken"
+
+# RAG Debugger SDK
+
+**Observability & Debugging Platform for RAG Pipelines**
+
+`ragdebug` allows you to auto-trace every stage of your RAG application and start a comprehensive local dashboard for analysis with a single command.
+
+## Quickstart
+
+1. Install the SDK with the CLI power-ups:
+   ```bash
+   pip install "ragdebug[cli]"
+   ```
+
+2. Start the local RAG Debugger platform:
+   ```bash
+   ragdebug up
+   ```
+   *Note: This requires Docker Desktop to be running.*
+
+3. Open the dashboard at [http://localhost:8000](http://localhost:8000)
+
+## Integrating Tracing
+
+Add the `@trace` decorator to your RAG pipeline functions:
+
+```python
+from ragdebug import init, trace, Prompt
+
+init(project="my-project")
+
+test_prompt = Prompt(name="QA Prompt", template="Context: {{context}}\n\nQ: {{query}}")
+
+@trace(name="qa_pipeline")
+def answer_question(query: str):
+    # Your RAG logic here
+    return "Answer"
+
+answer_question("What is RAG?")
+```
+
+## Advanced CLI Usage
+
+| Command | Description |
+|---|---|
+| `ragdebug up` | Start all 4 containers (mongo, postgres, redis, platform) |
+| `ragdebug up --build` | Force rebuild the platform image |
+| `ragdebug down` | Stop all containers |
+| `ragdebug status` | Show container status + API health check |
+| `ragdebug logs` | Stream container logs |
+
+## Documentation
+
+For full documentation on Prompts, Evaluations, and more, check the UI dashboard after running `ragdebug up`.

ragdebug-0.1.0/README.md

@@ -0,0 +1,53 @@
+# RAG Debugger SDK
+
+**Observability & Debugging Platform for RAG Pipelines**
+
+`ragdebug` allows you to auto-trace every stage of your RAG application and start a comprehensive local dashboard for analysis with a single command.
+
+## Quickstart
+
+1. Install the SDK with the CLI power-ups:
+   ```bash
+   pip install "ragdebug[cli]"
+   ```
+
+2. Start the local RAG Debugger platform:
+   ```bash
+   ragdebug up
+   ```
+   *Note: This requires Docker Desktop to be running.*
+
+3. Open the dashboard at [http://localhost:8000](http://localhost:8000)
+
+## Integrating Tracing
+
+Add the `@trace` decorator to your RAG pipeline functions:
+
+```python
+from ragdebug import init, trace, Prompt
+
+init(project="my-project")
+
+test_prompt = Prompt(name="QA Prompt", template="Context: {{context}}\n\nQ: {{query}}")
+
+@trace(name="qa_pipeline")
+def answer_question(query: str):
+    # Your RAG logic here
+    return "Answer"
+
+answer_question("What is RAG?")
+```
+
+## Advanced CLI Usage
+
+| Command | Description |
+|---|---|
+| `ragdebug up` | Start all 4 containers (mongo, postgres, redis, platform) |
+| `ragdebug up --build` | Force rebuild the platform image |
+| `ragdebug down` | Stop all containers |
+| `ragdebug status` | Show container status + API health check |
+| `ragdebug logs` | Stream container logs |
+
+## Documentation
+
+For full documentation on Prompts, Evaluations, and more, check the UI dashboard after running `ragdebug up`.

ragdebug-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ragdebug"
+version = "0.1.0"
+description = "Observability SDK for RAG pipelines — auto-trace every stage of your RAG app."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+    "click>=8.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0", "pytest-asyncio>=0.24"]
+tiktoken = ["tiktoken>=0.7"]
+
+[project.scripts]
+ragdebug = "ragdebug.cli:cli"
+
+[tool.setuptools.packages.find]
+include = ["ragdebug*"]
+
+[tool.setuptools.package-data]
+"ragdebug.platform" = ["*.yml", "*.yaml"]
+

ragdebug-0.1.0/ragdebug/__init__.py

@@ -0,0 +1,89 @@
+"""
+ragdebug — Observability SDK for RAG pipelines.
+
+Usage:
+    from ragdebug import init, trace, span
+
+    init(api_key="rdb_xxx", project="my-rag-app")
+
+    @trace
+    def rag_pipeline(query: str) -> str:
+        with span("embedding"):
+            vector = embed(query)
+        with span("retrieval"):
+            docs = search(vector)
+        with span("llm_call"):
+            response = llm(docs, query)
+        return response
+"""
+
+import logging
+
+from ragdebug.config import set_config
+from ragdebug.tracer import trace
+from ragdebug.spans import span
+from ragdebug.prompt import Prompt
+from ragdebug.evaluator import evaluate
+from ragdebug.debugger import RAGDebugger
+
+logger = logging.getLogger("ragdebug")
+
+
+def _check_backend(endpoint: str) -> None:
+    """Non-blocking health check — warns if the backend is unreachable."""
+    try:
+        import httpx
+        resp = httpx.get(f"{endpoint}/health", timeout=2.0)
+        if resp.status_code == 200:
+            logger.debug(f"Backend reachable at {endpoint}")
+        else:
+            logger.warning(
+                f"⚠ ragdebug backend returned status {resp.status_code}. "
+                f"Dashboard may not be working."
+            )
+    except Exception:
+        print(
+            f"\n⚠  ragdebug backend not reachable at {endpoint}\n"
+            f"   Run 'ragdebug up' to start the platform.\n"
+            f"   Or set enabled=False to silence this warning.\n"
+        )
+
+
+def init(
+    api_key: str = "",
+    project: str = "",
+    endpoint: str = "http://localhost:8000",
+    enabled: bool = True,
+    debug: bool = False,
+    flush_interval: float = 5.0,
+    batch_size: int = 10,
+) -> None:
+    """
+    Initialize the ragdebug SDK.
+
+    Args:
+        api_key: API key for authentication (from the RAG Debugger dashboard).
+        project: Project identifier (e.g. "my-rag-app").
+        endpoint: RAG Debugger platform URL (default: localhost).
+        enabled: Set to False to disable tracing without removing decorators.
+        debug: Enable debug logging.
+        flush_interval: Seconds between flush cycles (default: 5).
+        batch_size: Max traces per flush batch (default: 10).
+    """
+    set_config(
+        api_key=api_key,
+        project=project,
+        endpoint=endpoint,
+        enabled=enabled,
+        debug=debug,
+        flush_interval=flush_interval,
+        batch_size=batch_size,
+    )
+
+    if enabled:
+        _check_backend(endpoint)
+
+
+__all__ = ["init", "trace", "span", "Prompt", "evaluate"]
+__version__ = "0.1.0"
+

ragdebug-0.1.0/ragdebug/cli.py

@@ -0,0 +1,159 @@
+"""
+ragdebug CLI — manage the self-hosted platform via Docker Compose.
+
+Usage:
+    ragdebug up       Start the platform (MongoDB, PostgreSQL, Redis, Backend+Dashboard)
+    ragdebug down     Stop the platform
+    ragdebug status   Show container status and health check
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import shutil
+import subprocess
+import sys
+
+import click
+import httpx
+
+
+def _get_compose_file() -> str:
+    """Resolve the path to the bundled docker-compose.yml."""
+    ref = importlib.resources.files("ragdebug") / "platform" / "docker-compose.yml"
+    with importlib.resources.as_file(ref) as path:
+        return str(path)
+
+
+def _docker_available() -> bool:
+    """Check if Docker and Docker Compose are available."""
+    if shutil.which("docker") is None:
+        click.secho("✗ Docker not found. Please install Docker Desktop:", fg="red")
+        click.echo("  https://docs.docker.com/get-docker/")
+        return False
+    
+    result = subprocess.run(
+        ["docker", "compose", "version"],
+        capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        click.secho("✗ Docker Compose not found. Please install Docker Desktop.", fg="red")
+        return False
+    
+    return True
+
+
+def _run_compose(args: list[str], compose_file: str) -> int:
+    """Run a docker compose command with the bundled compose file."""
+    cmd = ["docker", "compose", "-f", compose_file, "-p", "ragdebug"] + args
+    click.secho(f"  → {' '.join(cmd)}", fg="bright_black")
+    result = subprocess.run(cmd)
+    return result.returncode
+
+
+@click.group()
+@click.version_option(package_name="ragdebug")
+def cli():
+    """ragdebug — Observability & Debugging Platform for RAG Pipelines."""
+    pass
+
+
+@cli.command()
+@click.option("--build", is_flag=True, help="Force rebuild the platform image.")
+@click.option(
+    "--detach/--no-detach", default=True,
+    help="Run containers in the background (default: detach)."
+)
+def up(build: bool, detach: bool):
+    """Start the ragdebug platform (databases + backend + dashboard)."""
+    if not _docker_available():
+        sys.exit(1)
+
+    compose_file = _get_compose_file()
+    click.secho("\n🚀 Starting ragdebug platform...\n", fg="cyan", bold=True)
+
+    args = ["up"]
+    if detach:
+        args.append("-d")
+    if build:
+        args.append("--build")
+
+    rc = _run_compose(args, compose_file)
+
+    if rc == 0 and detach:
+        click.echo()
+        click.secho("✓ Platform is starting up!", fg="green", bold=True)
+        click.echo()
+        click.echo("  Dashboard:  http://localhost:8000")
+        click.echo("  API:        http://localhost:8000/api/v1/")
+        click.echo("  Health:     http://localhost:8000/health")
+        click.echo()
+        click.secho("  Run 'ragdebug status' to check readiness.", fg="bright_black")
+        click.secho("  Run 'ragdebug down' to stop.\n", fg="bright_black")
+    
+    sys.exit(rc)
+
+
+@cli.command()
+@click.option(
+    "--volumes", is_flag=True,
+    help="Also remove persistent data volumes (MongoDB, PostgreSQL)."
+)
+def down(volumes: bool):
+    """Stop the ragdebug platform."""
+    if not _docker_available():
+        sys.exit(1)
+
+    compose_file = _get_compose_file()
+    click.secho("\n⏹  Stopping ragdebug platform...\n", fg="yellow", bold=True)
+
+    args = ["down"]
+    if volumes:
+        args.append("-v")
+
+    rc = _run_compose(args, compose_file)
+
+    if rc == 0:
+        msg = "✓ Platform stopped."
+        if volumes:
+            msg += " All data volumes removed."
+        click.secho(msg, fg="green", bold=True)
+        click.echo()
+
+    sys.exit(rc)
+
+
+@cli.command()
+def status():
+    """Show platform container status and health check."""
+    if not _docker_available():
+        sys.exit(1)
+
+    compose_file = _get_compose_file()
+    click.secho("\n📊 ragdebug platform status\n", fg="cyan", bold=True)
+
+    _run_compose(["ps"], compose_file)
+    click.echo()
+
+    # Health check
+    try:
+        resp = httpx.get("http://localhost:8000/health", timeout=3.0)
+        data = resp.json()
+        click.secho(
+            f"  API Health: ✓ {data.get('status', 'ok')} (v{data.get('version', '?')})",
+            fg="green",
+        )
+    except Exception:
+        click.secho("  API Health: ✗ Backend not reachable", fg="red")
+    
+    click.echo()
+
+
+@cli.command()
+def logs():
+    """Stream logs from the platform containers."""
+    if not _docker_available():
+        sys.exit(1)
+
+    compose_file = _get_compose_file()
+    _run_compose(["logs", "-f", "--tail", "100"], compose_file)

ragdebug-0.1.0/ragdebug/client.py

@@ -0,0 +1,177 @@
+"""
+HTTP client — batches traces and sends them asynchronously.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import queue
+import threading
+from typing import Any
+
+import httpx
+
+from ragdebug.config import get_config
+
+logger = logging.getLogger("ragdebug")
+
+_queue: queue.Queue[dict[str, Any]] = queue.Queue()
+_flush_thread: threading.Thread | None = None
+_shutdown_event = threading.Event()
+
+
+def _flush_loop() -> None:
+    """Background thread that flushes batched traces."""
+    cfg = get_config()
+    while not _shutdown_event.is_set():
+        batch: list[dict] = []
+        try:
+            # Block up to flush_interval for the first item
+            item = _queue.get(timeout=cfg.flush_interval)
+            batch.append(item)
+        except queue.Empty:
+            continue
+
+        # Drain up to batch_size
+        while len(batch) < cfg.batch_size:
+            try:
+                batch.append(_queue.get_nowait())
+            except queue.Empty:
+                break
+
+        _send_batch(batch)
+
+
+def _send_batch(batch: list[dict]) -> None:
+    """Send a batch of traces to the platform API."""
+    cfg = get_config()
+    url = f"{cfg.endpoint}/api/v1/traces"
+    headers = {"Authorization": f"Bearer {cfg.api_key}"}
+
+    for payload in batch:
+        try:
+            resp = httpx.post(url, json=payload, headers=headers, timeout=10.0)
+            if cfg.debug:
+                logger.debug(f"Trace sent: {resp.status_code}")
+        except Exception as exc:
+            if cfg.debug:
+                logger.warning(f"Failed to send trace: {exc}")
+            # Silently swallow — SDK errors must never crash the host app
+
+
+def _sync_prompt(
+    project_id: str,
+    name: str,
+    template: str,
+    template_hash: str,
+    variables: list[str],
+    metadata: dict[str, Any],
+) -> int | None:
+    """Synchronously sync a prompt with the backend and return its ID."""
+    cfg = get_config()
+    if not cfg.enabled:
+        return None
+        
+    url = f"{cfg.endpoint}/api/v1/prompts/sync"
+    headers = {"Authorization": f"Bearer {cfg.api_key}"}
+    payload = {
+        "project_id": project_id,
+        "name": name,
+        "template": template,
+        "template_hash": template_hash,
+        "variables": variables,
+        "metadata": metadata,
+    }
+    
+    try:
+        resp = httpx.post(url, json=payload, headers=headers, timeout=5.0)
+        resp.raise_for_status()
+        return resp.json().get("id")
+    except Exception as exc:
+        if cfg.debug:
+            logger.warning(f"Failed to sync prompt: {exc}")
+        return None
+
+
+def _pull_active_prompt(project_id: str, name: str) -> dict[str, Any] | None:
+    """Synchronously pull the active prompt version from the backend."""
+    cfg = get_config()
+    if not cfg.enabled:
+        return None
+        
+    url = f"{cfg.endpoint}/api/v1/prompts/{name}/active?project_id={project_id}"
+    headers = {"Authorization": f"Bearer {cfg.api_key}"}
+    
+    try:
+        resp = httpx.get(url, headers=headers, timeout=5.0)
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as exc:
+        if cfg.debug:
+            logger.warning(f"Failed to pull active prompt: {exc}")
+        return None
+
+def _trigger_eval(
+    project_id: str,
+    name: str,
+    prompt_version_id: int | None,
+    test_cases: list[dict[str, Any]],
+) -> dict[str, Any] | None:
+    """Synchronously trigger an evaluation run on the backend."""
+    cfg = get_config()
+    if not cfg.enabled:
+        return None
+        
+    url = f"{cfg.endpoint}/api/v1/evaluations"
+    headers = {"Authorization": f"Bearer {cfg.api_key}"}
+    payload = {
+        "project_id": project_id,
+        "name": name,
+        "prompt_version_id": prompt_version_id,
+        "test_cases": test_cases,
+    }
+    
+    try:
+        resp = httpx.post(url, json=payload, headers=headers, timeout=10.0)
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as exc:
+        if cfg.debug:
+            logger.warning(f"Failed to trigger evaluation: {exc}")
+        return None
+
+
+def enqueue_trace(trace_dict: dict[str, Any]) -> None:
+    """Add a trace to the outgoing queue."""
+    cfg = get_config()
+    if not cfg.enabled:
+        return
+
+    _queue.put(trace_dict)
+    _ensure_flush_thread()
+
+
+def _ensure_flush_thread() -> None:
+    """Lazily start the background flush thread."""
+    global _flush_thread
+    if _flush_thread is None or not _flush_thread.is_alive():
+        _flush_thread = threading.Thread(target=_flush_loop, daemon=True, name="ragdebug-flush")
+        _flush_thread.start()
+
+
+def shutdown() -> None:
+    """Flush remaining traces and stop the background thread."""
+    _shutdown_event.set()
+    # Drain remaining items
+    remaining: list[dict] = []
+    while not _queue.empty():
+        try:
+            remaining.append(_queue.get_nowait())
+        except queue.Empty:
+            break
+    if remaining:
+        _send_batch(remaining)
+
+
+atexit.register(shutdown)

ragdebug-0.1.0/ragdebug/config.py

@@ -0,0 +1,33 @@
+"""
+SDK configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class SDKConfig:
+    """Global SDK configuration — set via ragdebug.init()."""
+    api_key: str = ""
+    project: str = ""
+    endpoint: str = "http://localhost:8000"
+    flush_interval: float = 5.0          # seconds
+    batch_size: int = 10
+    enabled: bool = True
+    debug: bool = False
+
+
+# Singleton instance
+_config = SDKConfig()
+
+
+def get_config() -> SDKConfig:
+    return _config
+
+
+def set_config(**kwargs) -> None:
+    for k, v in kwargs.items():
+        if hasattr(_config, k):
+            setattr(_config, k, v)

ragdebug-0.1.0/ragdebug/debugger.py

@@ -0,0 +1,25 @@
+"""
+RAGDebugger wrapper for programmatic trace control.
+"""
+
+from typing import Any, Optional
+from ragdebug.config import set_config
+from ragdebug.tracer import trace
+from ragdebug.spans import span
+
+class RAGDebugger:
+    """
+    Programmatic entry point for the RAG Debugger SDK.
+    """
+    def __init__(self, api_url: str = "http://localhost:8000", project_id: str = "default", api_key: str = "default_key"):
+        set_config(endpoint=api_url, project=project_id, api_key=api_key)
+        self.project_id = project_id
+        self.api_key = api_key
+    
+    def trace(self, query: str):
+        """Context manager/decorator for a trace."""
+        return trace(name=query)
+    
+    def span(self, name: str, span_type: str = "general"):
+        """Context manager for a span."""
+        return span(name=name, span_type=span_type)

ragdebug-0.1.0/ragdebug/evaluator.py

@@ -0,0 +1,61 @@
+"""
+Evaluation trigger from the SDK.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ragdebug.client import _trigger_eval
+from ragdebug.config import get_config
+from ragdebug.prompt import Prompt
+
+
+def evaluate(
+    name: str,
+    test_cases: list[dict[str, Any]],
+    prompt: Prompt | None = None,
+    project_id: str | None = None,
+) -> dict[str, Any] | None:
+    """
+    Trigger an automated evaluation run on the RAG Debugger platform.
+    
+    Args:
+        name: Name for this evaluation run (e.g., "Nightly CI Eval")
+        test_cases: List of dictionaries, each containing at least 'input_query' 
+                    and optionally 'expected_output'.
+        prompt: An optional Prompt instance. If provided, the evaluation will be
+                linked to this prompt's active version.
+        project_id: Override the default project ID.
+        
+    Returns:
+        The evaluation run definition including its ID and status.
+    """
+    cfg = get_config()
+    pid = project_id or cfg.project
+    
+    prompt_version_id = None
+    if prompt:
+        prompt_version_id = getattr(prompt, "version_id", None)
+        
+    # Ensure test cases are formatted correctly
+    formatted_cases = []
+    for tc in test_cases:
+        if "input_query" not in tc:
+            if "query" in tc:
+                tc["input_query"] = tc.pop("query")
+            else:
+                raise ValueError("Each test case must contain an 'input_query' key.")
+        
+        # Ensure we don't send extra junk that the backend doesn't expect
+        formatted_cases.append({
+            "input_query": tc["input_query"],
+            "expected_output": tc.get("expected_output", ""),
+        })
+
+    return _trigger_eval(
+        project_id=pid,
+        name=name,
+        prompt_version_id=prompt_version_id,
+        test_cases=formatted_cases,
+    )

ragdebug-0.1.0/ragdebug/models.py

@@ -0,0 +1,70 @@
+"""
+Lightweight data models for trace payloads (SDK-side).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class SpanData:
+    span_id: str
+    name: str
+    span_type: str = "general"
+    start_time_ms: float = 0
+    duration_ms: float = 0
+    input: dict = field(default_factory=dict)
+    output: dict = field(default_factory=dict)
+    metadata: dict = field(default_factory=dict)
+    status: str = "success"
+    children: list[SpanData] = field(default_factory=list)
+
+    def set_input(self, **kwargs):
+        self.input.update(kwargs)
+
+    def set_output(self, **kwargs):
+        self.output.update(kwargs)
+
+    def to_dict(self) -> dict:
+        return {
+            "span_id": self.span_id,
+            "name": self.name,
+            "span_type": self.span_type,
+            "start_time_ms": self.start_time_ms,
+            "duration_ms": self.duration_ms,
+            "input": self.input,
+            "output": self.output,
+            "metadata": self.metadata,
+            "status": self.status,
+            "children": [c.to_dict() for c in self.children],
+        }
+
+
+@dataclass
+class TraceData:
+    """Full trace payload to be sent to the platform."""
+    project_id: str = ""
+    prompt_version_id: int | None = None
+    input: dict[str, Any] = field(default_factory=dict)
+    output: dict[str, Any] = field(default_factory=dict)
+    spans: list[SpanData] = field(default_factory=list)
+    duration_ms: float = 0
+    status: str = "success"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d = {
+            "project_id": self.project_id,
+            "input": self.input,
+            "output": self.output,
+            "spans": [s.to_dict() for s in self.spans],
+            "duration_ms": self.duration_ms,
+            "status": self.status,
+            "metadata": self.metadata,
+        }
+        if self.prompt_version_id is not None:
+            d["prompt_version_id"] = self.prompt_version_id
+        return d

ragdebug-0.1.0/ragdebug/platform/__init__.py

@@ -0,0 +1 @@
+# Platform data package — contains docker-compose.yml for ragdebug CLI.

ragdebug-0.1.0/ragdebug/platform/docker-compose.yml

@@ -0,0 +1,79 @@
+# ---------------------------------------------------------
+# ragdebug platform — Docker Compose for self-hosted setup
+# Launched via: ragdebug up
+# ---------------------------------------------------------
+#
+# Services:
+#   platform  — FastAPI backend + bundled React dashboard
+#   mongodb   — Trace & span storage
+#   postgres  — Projects, prompts, evaluations, users
+#   redis     — Caching & task queue
+# ---------------------------------------------------------
+
+services:
+  mongodb:
+    image: mongo:7
+    container_name: ragdebug-mongo
+    restart: unless-stopped
+    ports:
+      - "27017:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ragdebug
+      MONGO_INITDB_ROOT_PASSWORD: ragdebug_secret
+    volumes:
+      - ragdebug_mongo_data:/data/db
+
+  postgres:
+    image: postgres:16-alpine
+    container_name: ragdebug-postgres
+    restart: unless-stopped
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: ragdebug
+      POSTGRES_PASSWORD: ragdebug_secret
+      POSTGRES_DB: ragdebug
+    volumes:
+      - ragdebug_pg_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    container_name: ragdebug-redis
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+
+  platform:
+    image: ragdebug/platform:latest
+    container_name: ragdebug-platform
+    restart: unless-stopped
+    ports:
+      - "8000:8000"
+    environment:
+      # Database connections (use Docker service names)
+      MONGO_USER: ragdebug
+      MONGO_PASSWORD: ragdebug_secret
+      MONGO_HOST: mongodb
+      MONGO_PORT: "27017"
+      MONGO_DB: ragdebug
+      PG_USER: ragdebug
+      PG_PASSWORD: ragdebug_secret
+      PG_HOST: postgres
+      PG_PORT: "5432"
+      PG_DB: ragdebug
+      REDIS_HOST: redis
+      REDIS_PORT: "6379"
+      REDIS_URL: redis://redis:6379/0
+      # App
+      APP_ENV: production
+      APP_DEBUG: "false"
+      CORS_ORIGINS: "http://localhost:8000"
+      JWT_SECRET: ragdebug-local-dev-secret
+    depends_on:
+      - mongodb
+      - postgres
+      - redis
+
+volumes:
+  ragdebug_mongo_data:
+  ragdebug_pg_data:

ragdebug-0.1.0/ragdebug/prompt.py

@@ -0,0 +1,95 @@
+"""
+Prompt management via the SDK.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+from typing import Any
+
+from ragdebug.client import _sync_prompt, _pull_active_prompt
+
+# Thread-local storage to associate physical traces with the prompt executed
+_prompt_context = threading.local()
+
+def get_current_prompt_context() -> int | None:
+    """Retrieve the active prompt_version_id for the current thread."""
+    return getattr(_prompt_context, "prompt_version_id", None)
+
+def set_current_prompt_context(version_id: int | None) -> None:
+    """Set the active prompt_version_id for the current thread."""
+    _prompt_context.prompt_version_id = version_id
+
+
+class Prompt:
+    """
+    A Prompt Template that automatically syncs to the RAG Debugger platform.
+    """
+    def __init__(
+        self,
+        name: str,
+        template: str,
+        project_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ):
+        self.name = name
+        self.template = template
+        self.project_id = project_id or "default"
+        self.metadata = metadata or {}
+        
+        # Extract variables simple regex or just string match
+        import re
+        self.variables = list(set(re.findall(r"\{\{(\w+)\}\}", template)))
+        
+        # Compute SHA-256 hash of the template
+        self.template_hash = hashlib.sha256(template.encode("utf-8")).hexdigest()
+        
+        # Sync with backend immediately
+        self.version_id = self._sync()
+        
+    def _sync(self) -> int | None:
+        """Sync this prompt with the platform and return its version ID."""
+        return _sync_prompt(
+            project_id=self.project_id,
+            name=self.name,
+            template=self.template,
+            template_hash=self.template_hash,
+            variables=self.variables,
+            metadata=self.metadata,
+        )
+
+    def format(self, **kwargs: Any) -> str:
+        """
+        Format the prompt with variables.
+        Also temporarily sets the thread-local prompt context so any
+        @trace executed within this block can link to this prompt_version_id.
+        """
+        rendered = self.template
+        for k, v in kwargs.items():
+            rendered = rendered.replace(f"{{{{{k}}}}}", str(v))
+            
+        # Set the prompt context before returning
+        set_current_prompt_context(self.version_id)
+        return rendered
+
+    @classmethod
+    def pull(cls, name: str, project_id: str = "default") -> "Prompt":
+        """
+        Pull the currently active version of a prompt from the platform.
+        """
+        data = _pull_active_prompt(project_id, name)
+        if not data:
+            raise ValueError(f"No active prompt found for '{name}' in project '{project_id}'")
+            
+        # Create an instance that won't re-sync because we already have the ID
+        p = cls.__new__(cls)
+        p.name = data["name"]
+        p.template = data["template"]
+        p.project_id = data["project_id"]
+        p.metadata = data.get("metadata", {})
+        p.variables = data.get("variables", [])
+        p.template_hash = None # Skip hash check
+        p.version_id = data["id"]
+        return p

ragdebug-0.1.0/ragdebug/spans.py

@@ -0,0 +1,63 @@
+"""
+Span context manager — captures timing and I/O for a pipeline stage.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from contextlib import contextmanager
+from typing import Any, Generator
+
+from ragdebug.models import SpanData
+
+# Thread-local span stack (supports nested spans)
+import threading
+
+_span_stack: threading.local = threading.local()
+
+
+def _get_stack() -> list[SpanData]:
+    if not hasattr(_span_stack, "stack"):
+        _span_stack.stack = []
+    return _span_stack.stack
+
+
+@contextmanager
+def span(name: str, span_type: str = "general") -> Generator[SpanData, None, None]:
+    """
+    Context manager that records a named span.
+    """
+    stack = _get_stack()
+    span_data = SpanData(
+        span_id=f"span_{uuid.uuid4().hex[:8]}",
+        name=name,
+        span_type=span_type
+    )
+
+    span_data._abs_start = time.perf_counter()  # type: ignore[attr-defined]
+    stack.append(span_data)
+
+    try:
+        yield span_data
+    except Exception as exc:
+        span_data.status = "error"
+        span_data.metadata["error"] = str(exc)
+        raise
+    finally:
+        elapsed = time.perf_counter() - span_data._abs_start  # type: ignore[attr-defined]
+        span_data.duration_ms = round(elapsed * 1000, 2)
+        stack.pop()
+
+        if stack:
+            # Nest under parent
+            stack[-1].children.append(span_data)
+        else:
+            # Register as top-level span for the current trace
+            from ragdebug.tracer import _register_span
+            _register_span(span_data)
+
+
+def reset_spans() -> None:
+    _span_stack.stack = []
+

ragdebug-0.1.0/ragdebug/tracer.py

@@ -0,0 +1,118 @@
+"""
+@trace decorator — wraps a RAG pipeline function to capture the full trace.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+import time
+import uuid
+from typing import Any, Callable
+
+from ragdebug.client import enqueue_trace
+from ragdebug.config import get_config
+from ragdebug.models import SpanData, TraceData
+from ragdebug.prompt import get_current_prompt_context
+
+# Thread-local to hold the current trace's spans
+import threading
+
+_trace_local = threading.local()
+
+
+def _get_trace_spans() -> list[SpanData]:
+    if not hasattr(_trace_local, "spans"):
+        _trace_local.spans = []
+    return _trace_local.spans
+
+
+def _register_span(span_data: SpanData) -> None:
+    """Called when a top-level span finishes to register it in the current trace."""
+    spans = _get_trace_spans()
+    spans.append(span_data)
+
+
+class TraceContext:
+    def __init__(self, name: str, cfg: SDKConfig):
+        self.name = name
+        self.cfg = cfg
+        self.start_time = 0
+        self.trace_id = str(uuid.uuid4())
+        self.spans = []
+        self.input_data = {}
+        self.output_data = {}
+        self.status = "success"
+
+    def __enter__(self):
+        _trace_local.spans = []
+        self.start_time = time.perf_counter()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        elapsed_ms = round((time.perf_counter() - self.start_time) * 1000, 2)
+        if exc_type:
+            self.status = "error"
+        
+        trace_data = TraceData(
+            project_id=self.cfg.project,
+            prompt_version_id=get_current_prompt_context(),
+            input=self.input_data or {"query": self.name},
+            output=self.output_data,
+            spans=list(_trace_local.spans),
+            duration_ms=elapsed_ms,
+            status=self.status,
+            metadata={"error": str(exc_val)} if exc_val else {},
+        )
+        enqueue_trace(trace_data.to_dict())
+        _trace_local.spans = []
+
+    def span(self, name: str, span_type: str = "general"):
+        from ragdebug.spans import span
+        return span(name=name, span_type=span_type)
+
+    def set_input(self, **kwargs):
+        self.input_data.update(kwargs)
+
+    def set_output(self, **kwargs):
+        self.output_data.update(kwargs)
+
+    def __call__(self, func: Callable):
+        trace_name = self.name or func.__name__
+        if asyncio.iscoroutinefunction(func):
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                if not self.cfg.enabled: return await func(*args, **kwargs)
+                with TraceContext(trace_name, self.cfg) as ctx:
+                    query = str(args[0]) if args else str(kwargs.get("query", ""))
+                    ctx.set_input(query=query)
+                    res = await func(*args, **kwargs)
+                    ctx.set_output(response=str(res))
+                    return res
+            return async_wrapper
+        else:
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                if not self.cfg.enabled: return func(*args, **kwargs)
+                with TraceContext(trace_name, self.cfg) as ctx:
+                    query = str(args[0]) if args else str(kwargs.get("query", ""))
+                    ctx.set_input(query=query)
+                    res = func(*args, **kwargs)
+                    ctx.set_output(response=str(res))
+                    return res
+            return sync_wrapper
+
+def trace(func: Callable | None = None, *, name: str | None = None):
+    """
+    Decorator OR Context Manager to capture a full RAG pipeline trace.
+    """
+    cfg = get_config()
+    if func is None:
+        # If it's not a function, it's a context manager call: with trace(name="..."):
+        # Also supports @trace(name="...") by implementing __call__ on TraceContext
+        return TraceContext(name or "manual_trace", cfg)
+
+    # It's a direct decorator: @trace
+    return TraceContext(name or func.__name__, cfg)(func)
+

ragdebug-0.1.0/ragdebug.egg-info/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: ragdebug
+Version: 0.1.0
+Summary: Observability SDK for RAG pipelines — auto-trace every stage of your RAG app.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: click>=8.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.24; extra == "test"
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.7; extra == "tiktoken"
+
+# RAG Debugger SDK
+
+**Observability & Debugging Platform for RAG Pipelines**
+
+`ragdebug` allows you to auto-trace every stage of your RAG application and start a comprehensive local dashboard for analysis with a single command.
+
+## Quickstart
+
+1. Install the SDK with the CLI power-ups:
+   ```bash
+   pip install "ragdebug[cli]"
+   ```
+
+2. Start the local RAG Debugger platform:
+   ```bash
+   ragdebug up
+   ```
+   *Note: This requires Docker Desktop to be running.*
+
+3. Open the dashboard at [http://localhost:8000](http://localhost:8000)
+
+## Integrating Tracing
+
+Add the `@trace` decorator to your RAG pipeline functions:
+
+```python
+from ragdebug import init, trace, Prompt
+
+init(project="my-project")
+
+test_prompt = Prompt(name="QA Prompt", template="Context: {{context}}\n\nQ: {{query}}")
+
+@trace(name="qa_pipeline")
+def answer_question(query: str):
+    # Your RAG logic here
+    return "Answer"
+
+answer_question("What is RAG?")
+```
+
+## Advanced CLI Usage
+
+| Command | Description |
+|---|---|
+| `ragdebug up` | Start all 4 containers (mongo, postgres, redis, platform) |
+| `ragdebug up --build` | Force rebuild the platform image |
+| `ragdebug down` | Stop all containers |
+| `ragdebug status` | Show container status + API health check |
+| `ragdebug logs` | Stream container logs |
+
+## Documentation
+
+For full documentation on Prompts, Evaluations, and more, check the UI dashboard after running `ragdebug up`.

ragdebug-0.1.0/ragdebug.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+ragdebug/__init__.py
+ragdebug/cli.py
+ragdebug/client.py
+ragdebug/config.py
+ragdebug/debugger.py
+ragdebug/evaluator.py
+ragdebug/models.py
+ragdebug/prompt.py
+ragdebug/spans.py
+ragdebug/tracer.py
+ragdebug.egg-info/PKG-INFO
+ragdebug.egg-info/SOURCES.txt
+ragdebug.egg-info/dependency_links.txt
+ragdebug.egg-info/entry_points.txt
+ragdebug.egg-info/requires.txt
+ragdebug.egg-info/top_level.txt
+ragdebug/platform/__init__.py
+ragdebug/platform/docker-compose.yml

ragdebug-0.1.0/ragdebug.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ragdebug-0.1.0/ragdebug.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ragdebug = ragdebug.cli:cli

ragdebug-0.1.0/ragdebug.egg-info/requires.txt

@@ -0,0 +1,10 @@
+httpx>=0.27
+pydantic>=2.0
+click>=8.0
+
+[test]
+pytest>=8.0
+pytest-asyncio>=0.24
+
+[tiktoken]
+tiktoken>=0.7

ragdebug-0.1.0/ragdebug.egg-info/top_level.txt

@@ -0,0 +1 @@
+ragdebug

ragdebug-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+