raglens-sdk 0.1.0__tar.gz

raglens_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: raglens-sdk
+Version: 0.1.0
+Summary: Lightweight tracing for RAG pipelines
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# RAGLens Python SDK
+
+The full copyable walkthrough is in the repository's
+[quick-start guide](../../docs/QUICKSTART.md). It covers every SDK helper and
+the real Qdrant/OpenRouter example.
+
+Install from this repository: `pip install -e packages/sdk-python` (Python 3.9+).
+
+```python
+from raglens import RAGLens, log_generation
+
+client = RAGLens()  # reads RAGLENS_API_KEY and RAGLENS_BASE_URL
+with client.trace("answer", input={"query": "What is RAG?"}) as trace:
+    with trace.span("llm", "generate") as span:
+        answer = "Retrieval-augmented generation"
+        log_generation(span, answer, {"input_tokens": 12, "output_tokens": 4}, model="mock")
+    trace.set_output({"answer": answer})
+```
+
+Spans nest automatically within a trace using context-local state. Use `span.span()`
+for an explicit parent. Helpers `log_retrieval`, `log_context`, `log_prompt`, and
+`log_generation` accept an existing span; matching `trace.log_*` methods create
+instantaneous spans. Wrap the actual operation in a span for useful latency data.
+Retrieval records require `chunk_id`, `document_id`, `document_name`, `content`, and
+`score`; `rank` and `retrieval_method` are filled automatically. Set `selected` for
+chunks used in context. `log_context` accepts `max_tokens` and a `chunks` list.
+
+Set `RAGLENS_ENABLED=false` to disable delivery. Defaults: API URL
+`http://localhost:8000`, enabled true, HTTP timeout two seconds. Constructor values
+override environment variables. Delivery is synchronous on trace exit, without
+retries (the ingestion API is not idempotent). Network, HTTP and serialization
+failures warn without replacing the application's result or exception. Application
+exceptions are recorded and propagate normally. Supply JSON-compatible dictionaries
+for inputs, outputs, metrics and metadata; datetime and exception values serialize
+into strings and structured errors. Avoid recording secrets or sensitive content.
+
+After delivery `trace.id` contains the server-assigned ID. Set `project_id` and
+optionally `web_url` on the client to populate `trace.url`.
+
+## Tests and release
+
+```sh
+pip install -e 'packages/sdk-python[dev]'
+pytest packages/sdk-python/tests
+python -m build packages/sdk-python
+python -m twine check packages/sdk-python/dist/*
+```
+
+Version is maintained in `pyproject.toml`; `raglens.__version__` reads the installed
+metadata. For a release, bump that version, test, build into a clean `dist/`, then
+upload the reviewed wheel and sdist using `python -m twine upload ...` with your
+registry credentials. No package has been published by this implementation.

raglens_sdk-0.1.0/README.md

@@ -0,0 +1,52 @@
+# RAGLens Python SDK
+
+The full copyable walkthrough is in the repository's
+[quick-start guide](../../docs/QUICKSTART.md). It covers every SDK helper and
+the real Qdrant/OpenRouter example.
+
+Install from this repository: `pip install -e packages/sdk-python` (Python 3.9+).
+
+```python
+from raglens import RAGLens, log_generation
+
+client = RAGLens()  # reads RAGLENS_API_KEY and RAGLENS_BASE_URL
+with client.trace("answer", input={"query": "What is RAG?"}) as trace:
+    with trace.span("llm", "generate") as span:
+        answer = "Retrieval-augmented generation"
+        log_generation(span, answer, {"input_tokens": 12, "output_tokens": 4}, model="mock")
+    trace.set_output({"answer": answer})
+```
+
+Spans nest automatically within a trace using context-local state. Use `span.span()`
+for an explicit parent. Helpers `log_retrieval`, `log_context`, `log_prompt`, and
+`log_generation` accept an existing span; matching `trace.log_*` methods create
+instantaneous spans. Wrap the actual operation in a span for useful latency data.
+Retrieval records require `chunk_id`, `document_id`, `document_name`, `content`, and
+`score`; `rank` and `retrieval_method` are filled automatically. Set `selected` for
+chunks used in context. `log_context` accepts `max_tokens` and a `chunks` list.
+
+Set `RAGLENS_ENABLED=false` to disable delivery. Defaults: API URL
+`http://localhost:8000`, enabled true, HTTP timeout two seconds. Constructor values
+override environment variables. Delivery is synchronous on trace exit, without
+retries (the ingestion API is not idempotent). Network, HTTP and serialization
+failures warn without replacing the application's result or exception. Application
+exceptions are recorded and propagate normally. Supply JSON-compatible dictionaries
+for inputs, outputs, metrics and metadata; datetime and exception values serialize
+into strings and structured errors. Avoid recording secrets or sensitive content.
+
+After delivery `trace.id` contains the server-assigned ID. Set `project_id` and
+optionally `web_url` on the client to populate `trace.url`.
+
+## Tests and release
+
+```sh
+pip install -e 'packages/sdk-python[dev]'
+pytest packages/sdk-python/tests
+python -m build packages/sdk-python
+python -m twine check packages/sdk-python/dist/*
+```
+
+Version is maintained in `pyproject.toml`; `raglens.__version__` reads the installed
+metadata. For a release, bump that version, test, build into a clean `dist/`, then
+upload the reviewed wheel and sdist using `python -m twine upload ...` with your
+registry credentials. No package has been published by this implementation.

raglens_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name ="raglens-sdk"
+version = "0.1.0"
+description = "Lightweight tracing for RAG pipelines"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build", "twine"]
+
+[tool.setuptools.packages.find]
+include = ["raglens*"]

raglens_sdk-0.1.0/raglens/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import version
+
+from .client import RAGLens
+from .helpers import log_context, log_generation, log_prompt, log_retrieval
+from .span import Span
+from .trace import Trace
+
+__version__ = version("raglens")
+__all__ = ["RAGLens", "Trace", "Span", "log_retrieval", "log_context", "log_prompt", "log_generation"]

raglens_sdk-0.1.0/raglens/client.py

@@ -0,0 +1,44 @@
+import logging
+import os
+
+import httpx
+
+logger = logging.getLogger("raglens")
+
+
+class RAGLens:
+    """Synchronous, best-effort trace delivery with a bounded HTTP timeout."""
+
+    def __init__(self, api_key=None, base_url=None, enabled=None, timeout=2.0,
+                 project_id=None, web_url="http://localhost:3000", transport=None):
+        self.api_key = api_key if api_key is not None else os.getenv("RAGLENS_API_KEY", "")
+        self.base_url = (base_url or os.getenv("RAGLENS_BASE_URL", "http://localhost:8000")).rstrip("/")
+        self.enabled = (os.getenv("RAGLENS_ENABLED", "true").lower() not in
+                        {"0", "false", "no", "off"}) if enabled is None else enabled
+        self.project_id = project_id
+        self.web_url = web_url.rstrip("/")
+        self.timeout = timeout
+        self.transport = transport
+
+    def trace(self, name, **kwargs):
+        from .trace import Trace
+        return Trace(self, name, **kwargs)
+
+    def send_trace(self, trace):
+        if not self.enabled:
+            return None
+        try:
+            if not self.api_key:
+                logger.warning("Trace delivery skipped: RAGLENS_API_KEY is not configured")
+                return None
+            from .serializers import serialize_trace
+            payload = serialize_trace(trace)
+            with httpx.Client(timeout=self.timeout, transport=self.transport) as client:
+                response = client.post(self.base_url + "/v1/traces", json=payload,
+                                       headers={"Authorization": "Bearer " + self.api_key})
+                response.raise_for_status()
+                return response.json()["trace_id"]
+        except Exception as exc:
+            # Avoid logging payloads, credentials or exception URLs.
+            logger.warning("Trace delivery failed (%s)", type(exc).__name__)
+            return None

raglens_sdk-0.1.0/raglens/helpers.py

@@ -0,0 +1,32 @@
+"""Log structured data into existing spans so timing includes the actual work."""
+
+
+def log_retrieval(span, results, method="cosine", query=None):
+    span.retrieval_results = [dict(result, rank=result.get("rank", i),
+                                   retrieval_method=result.get("retrieval_method", method))
+                              for i, result in enumerate(results, 1)]
+    span.set_attributes({"retrieval_method": method, "top_k": len(results)})
+    if query is not None:
+        span.input = {"query": query}
+    span.set_output({"results": span.retrieval_results})
+
+
+def log_context(span, context, tokens, max_tokens=None, chunks=None):
+    span.set_output({"context": context, "chunks": chunks or []})
+    span.set_attributes({"token_count": tokens, "max_tokens": max_tokens})
+    span.trace.metrics["context_tokens"] = span.trace.metrics.get("context_tokens", 0) + tokens
+
+
+def log_prompt(span, prompt, tokens=None, template_variables=None):
+    span.set_output({"messages" if isinstance(prompt, list) else "prompt": prompt})
+    span.set_attributes({"token_count": tokens, "template_variables": template_variables or {}})
+
+
+def log_generation(span, response, tokens, model, provider="mock", **attributes):
+    usage = {"input_tokens": tokens, "output_tokens": 0} if isinstance(tokens, int) else dict(tokens)
+    span.set_output({"content": response})
+    span.set_attributes({"model": model, "provider": provider, **usage, **attributes})
+    for key in ("input_tokens", "output_tokens"):
+        span.trace.metrics[key] = span.trace.metrics.get(key, 0) + usage.get(key, 0)
+    span.trace.metrics["total_tokens"] = (span.trace.metrics.get("input_tokens", 0) +
+                                           span.trace.metrics.get("output_tokens", 0))

raglens_sdk-0.1.0/raglens/serializers.py

@@ -0,0 +1,20 @@
+import json
+from datetime import date, datetime
+
+
+def _default(value):
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, BaseException):
+        return {"type": type(value).__name__, "message": str(value)}
+    raise TypeError(f"Unsupported trace value: {type(value).__name__}")
+
+
+def serialize_trace(trace):
+    fields = ("name", "session_id", "user_id", "started_at", "ended_at", "duration_ms",
+              "status", "input", "output", "metrics", "metadata")
+    payload = {key: getattr(trace, key) for key in fields}
+    span_fields = ("id", "parent_span_id", "type", "name", "started_at", "ended_at",
+                   "duration_ms", "status", "input", "output", "attributes", "retrieval_results")
+    payload["spans"] = [{key: getattr(span, key) for key in span_fields} for span in trace.spans]
+    return json.loads(json.dumps(payload, default=_default, allow_nan=False))

raglens_sdk-0.1.0/raglens/span.py

@@ -0,0 +1,45 @@
+from datetime import datetime, timezone
+from time import perf_counter
+from uuid import uuid4
+
+
+class Span:
+    def __init__(self, trace, type, name, input=None, attributes=None, parent_span_id=None):
+        self.trace = trace
+        self.id = "span_" + uuid4().hex
+        self.type, self.name = type, name
+        self.parent_span_id = parent_span_id
+        self.input, self.output = input, None
+        self.attributes = dict(attributes or {})
+        self.retrieval_results = []
+        self.status = "success"
+        self.started_at = self.ended_at = None
+        self.duration_ms = 0
+
+    def __enter__(self):
+        self.started_at = datetime.now(timezone.utc)
+        self._start = perf_counter()
+        parent = self.trace._active_span.get()
+        if self.parent_span_id is None and parent is not None:
+            self.parent_span_id = parent.id
+        self._token = self.trace._active_span.set(self)
+        self.trace.spans.append(self)
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.ended_at = datetime.now(timezone.utc)
+        self.duration_ms = max(0, int((perf_counter() - self._start) * 1000))
+        if exc is not None:
+            self.status = "error"
+            self.attributes["error"] = {"type": exc_type.__name__, "message": str(exc)}
+        self.trace._active_span.reset(self._token)
+        return False
+
+    def set_output(self, output):
+        self.output = output
+
+    def set_attributes(self, attributes):
+        self.attributes.update(attributes)
+
+    def span(self, type, name, **kwargs):
+        return self.trace.span(type=type, name=name, parent_span_id=self.id, **kwargs)

raglens_sdk-0.1.0/raglens/trace.py

@@ -0,0 +1,72 @@
+from contextvars import ContextVar
+from datetime import datetime, timezone
+from time import perf_counter
+
+from .span import Span
+
+
+class Trace:
+    def __init__(self, client, name, input=None, metadata=None, session_id=None, user_id=None):
+        self.client, self.name = client, name
+        self.input, self.output = input, None
+        self.metadata = dict(metadata or {})
+        self.session_id, self.user_id = session_id, user_id
+        self.metrics, self.spans = {}, []
+        self.status = "success"
+        self.started_at = self.ended_at = None
+        self.duration_ms = 0
+        self.id = None
+        self._active_span = ContextVar("raglens_span", default=None)
+
+    @property
+    def url(self):
+        if self.id and self.client.project_id:
+            return f"{self.client.web_url}/projects/{self.client.project_id}/traces/{self.id}"
+        return None
+
+    def __enter__(self):
+        self.started_at = datetime.now(timezone.utc)
+        self._start = perf_counter()
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.ended_at = datetime.now(timezone.utc)
+        self.duration_ms = max(0, int((perf_counter() - self._start) * 1000))
+        if exc is not None:
+            self.status = "error"
+            self.metadata["error"] = {"type": exc_type.__name__, "message": str(exc)}
+        self.id = self.client.send_trace(self)
+        return False
+
+    def span(self, type, name, **kwargs):
+        return Span(self, type, name, **kwargs)
+
+    def set_output(self, output):
+        self.output = output
+
+    def set_metrics(self, metrics):
+        self.metrics.update(metrics)
+
+    def log_retrieval(self, **kwargs):
+        from .helpers import log_retrieval
+        with self.span("retrieval", "retrieval") as span:
+            log_retrieval(span, **kwargs)
+        return span
+
+    def log_context(self, **kwargs):
+        from .helpers import log_context
+        with self.span("context", "context") as span:
+            log_context(span, **kwargs)
+        return span
+
+    def log_prompt(self, **kwargs):
+        from .helpers import log_prompt
+        with self.span("prompt", "prompt") as span:
+            log_prompt(span, **kwargs)
+        return span
+
+    def log_generation(self, **kwargs):
+        from .helpers import log_generation
+        with self.span("llm", "generation") as span:
+            log_generation(span, **kwargs)
+        return span

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

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: raglens-sdk
+Version: 0.1.0
+Summary: Lightweight tracing for RAG pipelines
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# RAGLens Python SDK
+
+The full copyable walkthrough is in the repository's
+[quick-start guide](../../docs/QUICKSTART.md). It covers every SDK helper and
+the real Qdrant/OpenRouter example.
+
+Install from this repository: `pip install -e packages/sdk-python` (Python 3.9+).
+
+```python
+from raglens import RAGLens, log_generation
+
+client = RAGLens()  # reads RAGLENS_API_KEY and RAGLENS_BASE_URL
+with client.trace("answer", input={"query": "What is RAG?"}) as trace:
+    with trace.span("llm", "generate") as span:
+        answer = "Retrieval-augmented generation"
+        log_generation(span, answer, {"input_tokens": 12, "output_tokens": 4}, model="mock")
+    trace.set_output({"answer": answer})
+```
+
+Spans nest automatically within a trace using context-local state. Use `span.span()`
+for an explicit parent. Helpers `log_retrieval`, `log_context`, `log_prompt`, and
+`log_generation` accept an existing span; matching `trace.log_*` methods create
+instantaneous spans. Wrap the actual operation in a span for useful latency data.
+Retrieval records require `chunk_id`, `document_id`, `document_name`, `content`, and
+`score`; `rank` and `retrieval_method` are filled automatically. Set `selected` for
+chunks used in context. `log_context` accepts `max_tokens` and a `chunks` list.
+
+Set `RAGLENS_ENABLED=false` to disable delivery. Defaults: API URL
+`http://localhost:8000`, enabled true, HTTP timeout two seconds. Constructor values
+override environment variables. Delivery is synchronous on trace exit, without
+retries (the ingestion API is not idempotent). Network, HTTP and serialization
+failures warn without replacing the application's result or exception. Application
+exceptions are recorded and propagate normally. Supply JSON-compatible dictionaries
+for inputs, outputs, metrics and metadata; datetime and exception values serialize
+into strings and structured errors. Avoid recording secrets or sensitive content.
+
+After delivery `trace.id` contains the server-assigned ID. Set `project_id` and
+optionally `web_url` on the client to populate `trace.url`.
+
+## Tests and release
+
+```sh
+pip install -e 'packages/sdk-python[dev]'
+pytest packages/sdk-python/tests
+python -m build packages/sdk-python
+python -m twine check packages/sdk-python/dist/*
+```
+
+Version is maintained in `pyproject.toml`; `raglens.__version__` reads the installed
+metadata. For a release, bump that version, test, build into a clean `dist/`, then
+upload the reviewed wheel and sdist using `python -m twine upload ...` with your
+registry credentials. No package has been published by this implementation.

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

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+raglens/__init__.py
+raglens/client.py
+raglens/helpers.py
+raglens/serializers.py
+raglens/span.py
+raglens/trace.py
+raglens_sdk.egg-info/PKG-INFO
+raglens_sdk.egg-info/SOURCES.txt
+raglens_sdk.egg-info/dependency_links.txt
+raglens_sdk.egg-info/requires.txt
+raglens_sdk.egg-info/top_level.txt
+tests/test_sdk.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,6 @@
+httpx<1,>=0.27
+
+[dev]
+pytest>=8
+build
+twine

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

@@ -0,0 +1 @@
+raglens

raglens_sdk-0.1.0/setup.cfg

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

raglens_sdk-0.1.0/tests/test_sdk.py

@@ -0,0 +1,80 @@
+import asyncio
+import json
+from datetime import datetime, timezone
+
+import httpx
+import pytest
+
+from raglens import RAGLens, log_retrieval
+from raglens.serializers import serialize_trace
+
+
+def client(handler):
+    return RAGLens(api_key="test-key", project_id="project", transport=httpx.MockTransport(handler))
+
+
+def test_complete_payload_and_nesting():
+    captured = []
+    def handle(request):
+        assert request.url.path == "/v1/traces"
+        assert request.headers["authorization"] == "Bearer test-key"
+        captured.append(json.loads(request.content))
+        return httpx.Response(201, json={"trace_id": "trace_test"})
+    with client(handle).trace("test", input={"date": datetime.now(timezone.utc)}) as trace:
+        with trace.span("query", "root") as root:
+            with trace.span("retrieval", "search") as span:
+                log_retrieval(span, [{"chunk_id": "c", "document_id": "d", "document_name": "Doc",
+                                     "content": "text", "score": .9, "selected": True}])
+            trace.log_context(context="text", tokens=1, max_tokens=10)
+            trace.log_prompt(prompt="question", tokens=1)
+            trace.log_generation(response="answer", tokens={"input_tokens": 2, "output_tokens": 1}, model="mock")
+        trace.set_output({"answer": "answer"})
+    payload = captured[0]
+    assert len(payload["spans"]) == 5
+    assert all(s["parent_span_id"] == root.id for s in payload["spans"][1:])
+    assert payload["spans"][1]["retrieval_results"][0]["rank"] == 1
+    assert payload["metrics"]["total_tokens"] == 3
+    assert payload["ended_at"] >= payload["started_at"]
+    assert trace.url == "http://localhost:3000/projects/project/traces/trace_test"
+
+
+@pytest.mark.parametrize("failure", ["network", "http", "json", "serialize"])
+def test_delivery_failures_do_not_replace_application_exception(failure):
+    def handle(request):
+        if failure == "network":
+            raise httpx.ConnectError("offline")
+        return httpx.Response(500 if failure == "http" else 201, text="invalid json")
+    error = ValueError("application failure")
+    with pytest.raises(ValueError) as caught:
+        with client(handle).trace("failure") as trace:
+            if failure == "serialize":
+                trace.set_output({"unsupported": object()})
+            with trace.span("custom", "fails"):
+                raise error
+    assert caught.value is error
+    assert trace.status == trace.spans[0].status == "error"
+    assert trace.id is None
+
+
+def test_disabled_env_and_serialization(monkeypatch):
+    monkeypatch.setenv("RAGLENS_ENABLED", "false")
+    monkeypatch.setenv("RAGLENS_BASE_URL", "http://example.test")
+    c = RAGLens(transport=httpx.MockTransport(lambda r: pytest.fail("HTTP called")))
+    with c.trace("disabled", metadata={"error": ValueError("example")}) as trace:
+        pass
+    assert trace.id is None
+    assert c.base_url == "http://example.test"
+    assert serialize_trace(trace)["metadata"]["error"]["type"] == "ValueError"
+
+
+def test_concurrent_span_parents_are_isolated():
+    async def run():
+        with RAGLens(enabled=False).trace("parallel") as trace:
+            async def child(name):
+                with trace.span("custom", name) as parent:
+                    await asyncio.sleep(0)
+                    with trace.span("custom", name + "-child") as nested:
+                        assert nested.parent_span_id == parent.id
+            await asyncio.gather(child("one"), child("two"))
+        assert sum(s.parent_span_id is None for s in trace.spans) == 2
+    asyncio.run(run())