sledtrace 0.7.0__py3-none-any.whl

raglens/__init__.py

@@ -0,0 +1,23 @@
+import warnings
+
+from .trace import trace, RAGLensTrace, SledTraceTrace
+from .chunks import ChunkNormalizationError, normalize_chunk, normalize_chunks
+
+__version__ = "0.7.0"
+
+warnings.warn(
+    "The 'raglens' package is deprecated and kept only for temporary compatibility. "
+    "Please import from 'sledtrace' instead.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+__all__ = [
+    "__version__",
+    "trace",
+    "SledTraceTrace",
+    "RAGLensTrace",
+    "ChunkNormalizationError",
+    "normalize_chunk",
+    "normalize_chunks",
+]

raglens/chunks.py

@@ -0,0 +1,499 @@
+"""
+Chunk normalization helpers for SledTrace.
+
+RAG frameworks return retrieved chunks in many shapes:
+
+- Standard dict:
+    {"text": "...", "source": "...", "score": 0.9}
+
+- LangChain-like:
+    {"page_content": "...", "metadata": {"source": "..."}}
+
+- Haystack-like:
+    {"content": "...", "meta": {"source": "..."}}
+
+- LlamaIndex-like:
+    {"node": {"text": "...", "metadata": {"file_name": "..."}}, "score": 0.8}
+
+- Tuple result:
+    (document, score)
+
+- Bare string:
+    "chunk text..."
+
+SledTrace only needs a normalized chunk payload:
+
+{
+    "id": "...",
+    "text": "...",
+    "source": "...",
+    "score": 0.9,
+    "rank": 1,
+    "metadata": {...}
+}
+
+Minimum diagnostic contract:
+- text is required
+- source is recommended, falls back to "unknown"
+- score is optional
+- rank is optional but auto-filled by normalize_chunks
+- metadata is optional
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from typing import Any, Callable, Dict, Iterable, List, Optional, Union
+
+
+TextExtractor = Union[str, Callable[[Any], Optional[str]]]
+ValueExtractor = Union[str, Callable[[Any], Any]]
+
+
+class ChunkNormalizationError(ValueError):
+    """Raised when a retrieved item cannot be normalized into a SledTrace chunk."""
+
+
+def normalize_chunk(
+    raw: Any,
+    rank: Optional[int] = None,
+    *,
+    text: Optional[TextExtractor] = None,
+    source: Optional[ValueExtractor] = None,
+    score: Optional[ValueExtractor] = None,
+    chunk_id: Optional[ValueExtractor] = None,
+    metadata: Optional[ValueExtractor] = None,
+    default_source: str = "unknown",
+) -> Dict[str, Any]:
+    """
+    Normalize one raw retrieved item into the SledTrace chunk contract.
+
+    Parameters:
+        raw:
+            A raw retrieved item. Can be a dict, object, tuple, string, etc.
+
+        rank:
+            Optional 1-based rank. If omitted, rank is left as None.
+
+        text/source/score/chunk_id/metadata:
+            Optional explicit extractors. Each can be:
+            - a dotted path string, such as "metadata.source" or "node.text"
+            - a callable, such as lambda d: d.page_content
+
+        default_source:
+            Used when no source-like field can be found.
+
+    Returns:
+        A dict with:
+        - id
+        - text
+        - source
+        - score
+        - rank
+        - metadata
+    """
+    item, tuple_score = _unwrap_tuple_result(raw)
+
+    extracted_text = _extract_text(item, explicit=text)
+    if not extracted_text:
+        raise ChunkNormalizationError(
+            "Could not normalize retrieved chunk because no text/content field was found. "
+            "Provide text='...' or pass an object with text/page_content/content/node.text."
+        )
+
+    extracted_metadata = _extract_metadata(item, explicit=metadata)
+    extracted_source = _extract_source(item, extracted_metadata, explicit=source)
+    extracted_score = _extract_score(item, tuple_score=tuple_score, explicit=score)
+    extracted_id = _extract_id(item, explicit=chunk_id)
+
+    if not extracted_id:
+        extracted_id = _stable_chunk_id(extracted_text, extracted_source or default_source)
+
+    normalized_metadata = dict(extracted_metadata)
+    normalized_metadata.setdefault("normalized_by", "sledtrace.normalize_chunk")
+
+    return {
+        "id": extracted_id,
+        "text": extracted_text,
+        "source": extracted_source or default_source,
+        "score": extracted_score,
+        "rank": rank,
+        "metadata": normalized_metadata,
+    }
+
+
+def normalize_chunks(
+    raw_chunks: Iterable[Any],
+    *,
+    text: Optional[TextExtractor] = None,
+    source: Optional[ValueExtractor] = None,
+    score: Optional[ValueExtractor] = None,
+    chunk_id: Optional[ValueExtractor] = None,
+    metadata: Optional[ValueExtractor] = None,
+    default_source: str = "unknown",
+    start_rank: int = 1,
+    skip_invalid: bool = False,
+) -> List[Dict[str, Any]]:
+    """
+    Normalize many raw retrieved items into SledTrace chunks.
+
+    By default, invalid items raise ChunkNormalizationError.
+    Set skip_invalid=True to drop invalid items.
+    """
+    normalized: List[Dict[str, Any]] = []
+
+    for index, raw in enumerate(raw_chunks):
+        rank = start_rank + index
+
+        try:
+            normalized.append(
+                normalize_chunk(
+                    raw,
+                    rank=rank,
+                    text=text,
+                    source=source,
+                    score=score,
+                    chunk_id=chunk_id,
+                    metadata=metadata,
+                    default_source=default_source,
+                )
+            )
+        except ChunkNormalizationError:
+            if not skip_invalid:
+                raise
+
+    return normalized
+
+
+def _unwrap_tuple_result(raw: Any) -> tuple[Any, Any]:
+    """
+    Common vector-store pattern:
+        (document, score)
+
+    Also supports:
+        [document, score]
+    """
+    if isinstance(raw, tuple) and len(raw) == 2:
+        return raw[0], raw[1]
+
+    if isinstance(raw, list) and len(raw) == 2 and not _looks_like_chunk_list(raw):
+        return raw[0], raw[1]
+
+    return raw, None
+
+
+def _looks_like_chunk_list(value: list[Any]) -> bool:
+    if not value:
+        return False
+
+    return all(isinstance(item, (str, Mapping)) for item in value)
+
+
+def _extract_text(item: Any, explicit: Optional[TextExtractor]) -> str:
+    if isinstance(item, str):
+        return item.strip()
+
+    if explicit is not None:
+        value = _extract_with_spec(item, explicit)
+        return _to_clean_string(value)
+
+    candidates = [
+        "text",
+        "page_content",
+        "content",
+        "body",
+        "chunk",
+        "node.text",
+        "node.content",
+        "node.page_content",
+        "node.text_resource.text",
+        "document.text",
+        "document.page_content",
+        "document.content",
+    ]
+
+    for path in candidates:
+        value = _get_path(item, path)
+        cleaned = _to_clean_string(value)
+
+        if cleaned:
+            return cleaned
+
+    # Object fallback for LangChain-style Document.
+    for attr in ("page_content", "text", "content"):
+        value = getattr(item, attr, None)
+        cleaned = _to_clean_string(value)
+
+        if cleaned:
+            return cleaned
+
+    # LlamaIndex-style node sometimes exposes get_content().
+    get_content = getattr(item, "get_content", None)
+    if callable(get_content):
+        cleaned = _to_clean_string(get_content())
+        if cleaned:
+            return cleaned
+
+    node = getattr(item, "node", None)
+    if node is not None:
+        get_content = getattr(node, "get_content", None)
+        if callable(get_content):
+            cleaned = _to_clean_string(get_content())
+            if cleaned:
+                return cleaned
+
+    return ""
+
+
+def _extract_metadata(
+    item: Any,
+    explicit: Optional[ValueExtractor],
+) -> Dict[str, Any]:
+    if explicit is not None:
+        value = _extract_with_spec(item, explicit)
+        return _to_metadata_dict(value)
+
+    candidates = [
+        "metadata",
+        "meta",
+        "extra_info",
+        "node.metadata",
+        "node.meta",
+        "document.metadata",
+        "document.meta",
+    ]
+
+    merged: Dict[str, Any] = {}
+
+    for path in candidates:
+        value = _get_path(item, path)
+        if isinstance(value, Mapping):
+            merged.update(dict(value))
+
+    # Object fallback.
+    for attr in ("metadata", "meta", "extra_info"):
+        value = getattr(item, attr, None)
+        if isinstance(value, Mapping):
+            merged.update(dict(value))
+
+    node = getattr(item, "node", None)
+    if node is not None:
+        for attr in ("metadata", "meta", "extra_info"):
+            value = getattr(node, attr, None)
+            if isinstance(value, Mapping):
+                merged.update(dict(value))
+
+    return merged
+
+
+def _extract_source(
+    item: Any,
+    metadata: Mapping[str, Any],
+    explicit: Optional[ValueExtractor],
+) -> str:
+    if explicit is not None:
+        return _to_clean_string(_extract_with_spec(item, explicit))
+
+    direct_candidates = [
+        "source",
+        "file_name",
+        "filename",
+        "doc_id",
+        "document_id",
+        "uri",
+        "url",
+        "path",
+        "title",
+        "name",
+        "node.source",
+        "node.file_name",
+        "node.id_",
+        "document.source",
+        "document.file_name",
+        "document.id",
+    ]
+
+    metadata_candidates = [
+        "source",
+        "file_name",
+        "filename",
+        "doc_id",
+        "document_id",
+        "file_id",
+        "uri",
+        "url",
+        "path",
+        "title",
+        "name",
+    ]
+
+    for path in direct_candidates:
+        value = _to_clean_string(_get_path(item, path))
+        if value:
+            return value
+
+    for key in metadata_candidates:
+        value = _to_clean_string(metadata.get(key))
+        if value:
+            return value
+
+    return ""
+
+
+def _extract_score(
+    item: Any,
+    *,
+    tuple_score: Any,
+    explicit: Optional[ValueExtractor],
+) -> Optional[float]:
+    if explicit is not None:
+        return _to_float_or_none(_extract_with_spec(item, explicit))
+
+    tuple_score_float = _to_float_or_none(tuple_score)
+    if tuple_score_float is not None:
+        return tuple_score_float
+
+    candidates = [
+        "score",
+        "similarity",
+        "similarity_score",
+        "rerank_score",
+        "relevance_score",
+        "distance",
+        "metadata.score",
+        "metadata.similarity",
+        "metadata.similarity_score",
+        "metadata.rerank_score",
+        "meta.score",
+        "meta.similarity",
+        "node.score",
+    ]
+
+    for path in candidates:
+        value = _to_float_or_none(_get_path(item, path))
+        if value is not None:
+            return value
+
+    for attr in (
+        "score",
+        "similarity",
+        "similarity_score",
+        "rerank_score",
+        "relevance_score",
+        "distance",
+    ):
+        value = _to_float_or_none(getattr(item, attr, None))
+        if value is not None:
+            return value
+
+    return None
+
+
+def _extract_id(
+    item: Any,
+    explicit: Optional[ValueExtractor],
+) -> str:
+    if explicit is not None:
+        return _to_clean_string(_extract_with_spec(item, explicit))
+
+    candidates = [
+        "id",
+        "chunk_id",
+        "doc_id",
+        "document_id",
+        "node_id",
+        "id_",
+        "node.id",
+        "node.id_",
+        "node.node_id",
+        "document.id",
+        "metadata.id",
+        "metadata.chunk_id",
+        "metadata.doc_id",
+        "metadata.document_id",
+        "meta.id",
+        "meta.chunk_id",
+    ]
+
+    for path in candidates:
+        value = _to_clean_string(_get_path(item, path))
+        if value:
+            return value
+
+    for attr in ("id", "id_", "chunk_id", "doc_id", "document_id", "node_id"):
+        value = _to_clean_string(getattr(item, attr, None))
+        if value:
+            return value
+
+    return ""
+
+
+def _extract_with_spec(item: Any, spec: Union[str, Callable[[Any], Any]]) -> Any:
+    if callable(spec):
+        return spec(item)
+
+    return _get_path(item, spec)
+
+
+def _get_path(item: Any, path: str) -> Any:
+    current = item
+
+    for part in path.split("."):
+        if current is None:
+            return None
+
+        if isinstance(current, Mapping):
+            current = current.get(part)
+            continue
+
+        current = getattr(current, part, None)
+
+    return current
+
+
+def _to_clean_string(value: Any) -> str:
+    if value is None:
+        return ""
+
+    if isinstance(value, str):
+        return value.strip()
+
+    if isinstance(value, (int, float)):
+        return str(value)
+
+    return ""
+
+
+def _to_float_or_none(value: Any) -> Optional[float]:
+    if value is None:
+        return None
+
+    if isinstance(value, bool):
+        return None
+
+    if isinstance(value, (int, float)):
+        return float(value)
+
+    if isinstance(value, str) and value.strip():
+        try:
+            return float(value.strip())
+        except ValueError:
+            return None
+
+    return None
+
+
+def _to_metadata_dict(value: Any) -> Dict[str, Any]:
+    if value is None:
+        return {}
+
+    if isinstance(value, Mapping):
+        return dict(value)
+
+    return {"raw_metadata": value}
+
+
+def _stable_chunk_id(text: str, source: str) -> str:
+    digest = hashlib.sha1(f"{source}\n{text}".encode("utf-8")).hexdigest()[:12]
+    return f"chunk_{digest}"

raglens/models.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+from datetime import datetime, timezone
+import time
+import uuid
+
+
+JsonDict = Dict[str, Any]
+
+
+def utc_now_iso() -> str:
+    """Return current UTC time in ISO-8601 format."""
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def now_ms() -> float:
+    """Return monotonic time in milliseconds."""
+    return time.perf_counter() * 1000
+
+
+def new_id(prefix: str) -> str:
+    """Generate a simple prefixed UUID ID."""
+    return f"{prefix}_{uuid.uuid4().hex}"
+
+
+@dataclass
+class Span:
+    span_id: str
+    trace_id: str
+    parent_span_id: Optional[str]
+    type: str
+    name: str
+    status: str
+    input: JsonDict = field(default_factory=dict)
+    output: JsonDict = field(default_factory=dict)
+    metadata: JsonDict = field(default_factory=dict)
+    started_at: str = field(default_factory=utc_now_iso)
+    ended_at: Optional[str] = None
+    duration_ms: Optional[int] = None
+    error: Optional[JsonDict] = None
+
+    def to_dict(self) -> JsonDict:
+        return asdict(self)
+
+
+@dataclass
+class TraceRecord:
+    trace_id: str
+    name: str
+    status: str
+    input: JsonDict = field(default_factory=dict)
+    output: JsonDict = field(default_factory=dict)
+    metadata: JsonDict = field(default_factory=dict)
+    started_at: str = field(default_factory=utc_now_iso)
+    ended_at: Optional[str] = None
+    duration_ms: Optional[int] = None
+
+    def to_dict(self) -> JsonDict:
+        return asdict(self)
+
+
+@dataclass
+class TracePayload:
+    trace: TraceRecord
+    spans: List[Span] = field(default_factory=list)
+
+    def to_dict(self) -> JsonDict:
+        return {
+            "trace": self.trace.to_dict(),
+            "spans": [span.to_dict() for span in self.spans],
+        }

raglens/trace.py

@@ -0,0 +1,367 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+import json
+import os
+import sys
+import traceback
+import urllib.request
+import urllib.error
+
+from .models import (
+    JsonDict,
+    Span,
+    TraceRecord,
+    TracePayload,
+    new_id,
+    now_ms,
+    utc_now_iso,
+)
+
+
+class RAGLensTrace:
+    """
+    A lightweight trace context manager for recording one RAG request.
+
+    Public API example:
+
+        from sledtrace import trace
+
+        with trace("refund-policy-qa") as t:
+            t.retrieval(query="...", chunks=[...])
+            t.llm(model="...", prompt="...", response="...")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        query: Optional[str] = None,
+        metadata: Optional[JsonDict] = None,
+        collector_url: Optional[str] = None,
+    ) -> None:
+        self.trace_id = new_id("trace")
+        self.name = name
+        self.query = query
+        self.metadata = metadata or {}
+        self.collector_url = resolve_collector_url(collector_url)
+
+        self._started_at: Optional[str] = None
+        self._ended_at: Optional[str] = None
+        self._start_ms: Optional[float] = None
+        self._duration_ms: Optional[int] = None
+
+        self._status = "ok"
+        self._output: JsonDict = {}
+        self._spans: List[Span] = []
+        self._error: Optional[JsonDict] = None
+
+    def __enter__(self) -> "RAGLensTrace":
+        self._started_at = utc_now_iso()
+        self._start_ms = now_ms()
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        self._ended_at = utc_now_iso()
+
+        if self._start_ms is not None:
+            self._duration_ms = int(now_ms() - self._start_ms)
+
+        if exc is not None:
+            self._status = "error"
+            self._error = {
+                "type": exc_type.__name__ if exc_type else "Error",
+                "message": str(exc),
+                "stack": "".join(traceback.format_exception(exc_type, exc, tb)),
+            }
+
+        # Do not suppress exceptions.
+        return False
+
+    def retrieval(
+        self,
+        query: str,
+        chunks: List[JsonDict],
+        name: str = "retrieval",
+        top_k: Optional[int] = None,
+        metadata: Optional[JsonDict] = None,
+    ) -> None:
+        """
+        Record a retrieval span.
+
+        Args:
+            query: Query sent to retriever.
+            chunks: Retrieved chunks.
+            name: Human-readable span name.
+            top_k: Number of requested chunks.
+            metadata: Retriever metadata.
+        """
+        start = now_ms()
+        started_at = utc_now_iso()
+
+        normalized_chunks = self._normalize_chunks(chunks)
+
+        span_input: JsonDict = {
+            "query": query,
+        }
+
+        if top_k is not None:
+            span_input["top_k"] = top_k
+
+        span = Span(
+            span_id=new_id("span"),
+            trace_id=self.trace_id,
+            parent_span_id=None,
+            type="retrieval",
+            name=name,
+            status="ok",
+            input=span_input,
+            output={
+                "chunks": normalized_chunks,
+            },
+            metadata=metadata or {},
+            started_at=started_at,
+            ended_at=utc_now_iso(),
+            duration_ms=int(now_ms() - start),
+            error=None,
+        )
+
+        self._spans.append(span)
+
+        if self.query is None:
+            self.query = query
+
+    def llm(
+        self,
+        model: str,
+        prompt: Optional[str] = None,
+        response: Optional[str] = None,
+        messages: Optional[List[JsonDict]] = None,
+        name: str = "llm",
+        provider: Optional[str] = None,
+        input_tokens: Optional[int] = None,
+        output_tokens: Optional[int] = None,
+        latency_ms: Optional[int] = None,
+        metadata: Optional[JsonDict] = None,
+    ) -> None:
+        """
+        Record an LLM span.
+
+        Args:
+            model: Model name.
+            prompt: Prompt text.
+            response: Model response text.
+            messages: Optional chat messages.
+            name: Human-readable span name.
+            provider: LLM provider.
+            input_tokens: Input token count.
+            output_tokens: Output token count.
+            latency_ms: LLM call latency.
+            metadata: Additional metadata.
+        """
+        start = now_ms()
+        started_at = utc_now_iso()
+
+        span_input: JsonDict = {
+            "model": model,
+        }
+
+        if prompt is not None:
+            span_input["prompt"] = prompt
+
+        if messages is not None:
+            span_input["messages"] = messages
+
+        span_output: JsonDict = {}
+
+        if response is not None:
+            span_output["response"] = response
+            self._output["answer"] = response
+
+        span_metadata: JsonDict = metadata.copy() if metadata else {}
+
+        if provider is not None:
+            span_metadata["provider"] = provider
+
+        if input_tokens is not None:
+            span_metadata["input_tokens"] = input_tokens
+
+        if output_tokens is not None:
+            span_metadata["output_tokens"] = output_tokens
+
+        if input_tokens is not None and output_tokens is not None:
+            span_metadata["total_tokens"] = input_tokens + output_tokens
+
+        if latency_ms is not None:
+            span_metadata["latency_ms"] = latency_ms
+
+        span = Span(
+            span_id=new_id("span"),
+            trace_id=self.trace_id,
+            parent_span_id=None,
+            type="llm",
+            name=name,
+            status="ok",
+            input=span_input,
+            output=span_output,
+            metadata=span_metadata,
+            started_at=started_at,
+            ended_at=utc_now_iso(),
+            duration_ms=latency_ms if latency_ms is not None else int(now_ms() - start),
+            error=None,
+        )
+
+        self._spans.append(span)
+
+    def log_answer(self, answer: str) -> None:
+        """Record the final answer at trace level."""
+        self._output["answer"] = answer
+
+    def to_payload(self) -> TracePayload:
+        trace_input: JsonDict = {}
+
+        if self.query is not None:
+            trace_input["query"] = self.query
+
+        trace_metadata = {
+            "sdk_language": "python",
+            "sdk_version": "0.7.0",
+            **self.metadata,
+        }
+
+        if self._error is not None:
+            trace_metadata["error"] = self._error
+
+        record = TraceRecord(
+            trace_id=self.trace_id,
+            name=self.name,
+            status=self._status,
+            input=trace_input,
+            output=self._output,
+            metadata=trace_metadata,
+            started_at=self._started_at or utc_now_iso(),
+            ended_at=self._ended_at,
+            duration_ms=self._duration_ms,
+        )
+
+        return TracePayload(trace=record, spans=self._spans)
+
+    def to_dict(self) -> JsonDict:
+        return self.to_payload().to_dict()
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, ensure_ascii=False)
+
+    def print_json(self) -> None:
+        print(self.to_json())
+
+    def flush(self, collector_url: Optional[str] = None, timeout: float = 5.0) -> JsonDict:
+        """
+        Send the trace payload to the local SledTrace collector.
+
+        Args:
+            collector_url: Optional collector base URL. Defaults to self.collector_url.
+            timeout: HTTP timeout in seconds.
+
+        Returns:
+            Collector JSON response.
+
+        Raises:
+            RuntimeError: If the collector request fails.
+        """
+        base_url = (collector_url or self.collector_url).rstrip("/")
+        url = f"{base_url}/api/traces"
+
+        data = json.dumps(self.to_dict()).encode("utf-8")
+
+        request = urllib.request.Request(
+            url=url,
+            data=data,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": "sledtrace-python-sdk/0.7.0",
+            },
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                response_body = response.read().decode("utf-8")
+                if not response_body:
+                    return {}
+
+                return json.loads(response_body)
+
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeError(
+                f"SledTrace collector returned HTTP {exc.code}: {body}"
+            ) from exc
+
+        except urllib.error.URLError as exc:
+            raise RuntimeError(
+                f"Failed to connect to SledTrace collector at {url}: {exc.reason}"
+            ) from exc
+
+    def _normalize_chunks(self, chunks: List[JsonDict]) -> List[JsonDict]:
+        normalized: List[JsonDict] = []
+
+        for index, chunk in enumerate(chunks):
+            normalized_chunk = dict(chunk)
+
+            if "rank" not in normalized_chunk:
+                normalized_chunk["rank"] = index + 1
+
+            if "metadata" not in normalized_chunk or normalized_chunk["metadata"] is None:
+                normalized_chunk["metadata"] = {}
+
+            normalized.append(normalized_chunk)
+
+        return normalized
+
+
+def trace(
+    name: str,
+    query: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    collector_url: Optional[str] = None,
+) -> RAGLensTrace:
+    """
+    Create a SledTrace trace context manager.
+    """
+    return RAGLensTrace(name=name, query=query, metadata=metadata, collector_url=collector_url,)
+
+
+SledTraceTrace = RAGLensTrace
+
+_DEFAULT_COLLECTOR_URL = "http://localhost:4319"
+_LEGACY_COLLECTOR_ENV = "RAGLENS_COLLECTOR_URL"
+_NEW_COLLECTOR_ENV = "SLEDTRACE_COLLECTOR_URL"
+_legacy_env_notice_emitted = False
+
+
+def resolve_collector_url(explicit_url: Optional[str]) -> str:
+    if explicit_url:
+        return explicit_url
+
+    new_value = os.getenv(_NEW_COLLECTOR_ENV)
+    if new_value:
+        return new_value
+
+    legacy_value = os.getenv(_LEGACY_COLLECTOR_ENV)
+    if legacy_value:
+        emit_legacy_env_warning_once()
+        return legacy_value
+
+    return _DEFAULT_COLLECTOR_URL
+
+
+def emit_legacy_env_warning_once() -> None:
+    global _legacy_env_notice_emitted
+    if _legacy_env_notice_emitted:
+        return
+
+    _legacy_env_notice_emitted = True
+    print(
+        "DEPRECATED: RAGLENS_COLLECTOR_URL is deprecated; use SLEDTRACE_COLLECTOR_URL instead.",
+        file=sys.stderr,
+    )

sledtrace/__init__.py

@@ -0,0 +1,24 @@
+import warnings
+
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore", category=DeprecationWarning, module=r"raglens.*")
+    from raglens import (
+        ChunkNormalizationError,
+        RAGLensTrace,
+        SledTraceTrace,
+        normalize_chunk,
+        normalize_chunks,
+        trace,
+    )
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "__version__",
+    "trace",
+    "SledTraceTrace",
+    "RAGLensTrace",
+    "ChunkNormalizationError",
+    "normalize_chunk",
+    "normalize_chunks",
+]

sledtrace/cli.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+from typing import Iterable, Optional
+
+from . import __version__
+
+
+REPO_MARKERS = (
+    Path("AGENTS.md"),
+    Path("docker-compose.yml"),
+    Path("scripts") / "start-sledtrace.py",
+)
+
+SERVE_CHECKOUT_ERROR = (
+    "sledtrace serve currently requires a SledTrace source checkout. "
+    "Run it from the repository, or use Docker Compose from the repository root. "
+    "Standalone wheel-installed serving is not supported by this package."
+)
+
+
+def _candidate_directories(start: Path) -> Iterable[Path]:
+    current = start.resolve()
+    if current.is_file():
+        current = current.parent
+
+    yield current
+    yield from current.parents
+
+
+def find_repo_root(start: Optional[Path] = None) -> Optional[Path]:
+    """Find a SledTrace source checkout at or above the starting directory."""
+    for candidate in _candidate_directories(start or Path.cwd()):
+        if all((candidate / marker).exists() for marker in REPO_MARKERS):
+            return candidate
+
+    return None
+
+
+def serve() -> int:
+    repo_root = find_repo_root()
+    if repo_root is None:
+        print(SERVE_CHECKOUT_ERROR, file=sys.stderr)
+        return 1
+
+    startup_script = repo_root / "scripts" / "start-sledtrace.py"
+
+    print("Starting SledTrace local stack...")
+    return subprocess.call([sys.executable, str(startup_script)])
+
+
+def show_version() -> int:
+    print(__version__)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sledtrace",
+        description="Inspect and run SledTrace local developer tooling.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    serve_parser = subparsers.add_parser(
+        "serve",
+        help="Start the collector and dashboard from a SledTrace source checkout",
+        description=(
+            "Start the local collector and dashboard. This command must be run "
+            "from inside a SledTrace source checkout; standalone wheel-installed "
+            "serving is not supported by this package."
+        ),
+    )
+    serve_parser.set_defaults(func=lambda _args: serve())
+
+    version_parser = subparsers.add_parser(
+        "version",
+        help="Print the installed SledTrace package version",
+        description="Print the installed SledTrace package version.",
+    )
+    version_parser.set_defaults(func=lambda _args: show_version())
+
+    return parser
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sledtrace-0.7.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: sledtrace
+Version: 0.7.0
+Summary: Local-first tracing and debugging SDK for RAG pipelines
+Author: SledTrace Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Schromeo/SledTrace
+Project-URL: Documentation, https://github.com/Schromeo/SledTrace#readme
+Project-URL: Repository, https://github.com/Schromeo/SledTrace
+Project-URL: Issues, https://github.com/Schromeo/SledTrace/issues
+Keywords: rag,observability,tracing,llm,ai,debugging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# SledTrace Python SDK
+
+SledTrace is a local-first observability and debugging SDK for RAG pipelines.
+
+Current release: **0.7.0 — External Developer Readiness**
+
+Project and visual overview: [github.com/Schromeo/SledTrace](https://github.com/Schromeo/SledTrace)
+
+## Distribution status
+
+Install the released SDK and CLI from production PyPI:
+
+```bash
+python -m pip install sledtrace==0.7.0
+```
+
+The immutable `0.7.0rc1` publication candidate remains available on [TestPyPI](https://test.pypi.org/project/sledtrace/0.7.0rc1/) for release-history purposes.
+
+## Install from source for development
+
+```bash
+cd sdk/python
+python -m pip install -e .
+```
+
+## Build a local wheel or sdist
+
+```bash
+cd sdk/python
+python -m pip install --upgrade pip
+python -m pip install build
+python -m build
+```
+
+This produces wheel and source-distribution artifacts in `dist/`.
+
+## Install the built wheel
+
+```bash
+python -m pip install dist/*.whl
+```
+
+## CLI
+
+Editable and wheel installations provide:
+
+```bash
+sledtrace --help
+sledtrace serve --help
+sledtrace version
+```
+
+`sledtrace version` reports `0.7.0` for this release.
+
+`sledtrace serve` must be run from inside a SledTrace source checkout. It locates the repository from the current working directory and delegates to `scripts/start-sledtrace.py`. The wheel does not bundle the Collector, Dashboard, Docker assets, or a standalone serving runtime; outside a checkout, `serve` exits with actionable guidance.
+
+## Basic usage
+
+```python
+from sledtrace import trace
+
+with trace("example") as t:
+    t.retrieval(
+        query="What is the refund policy?",
+        chunks=[
+            {
+                "id": "chunk-1",
+                "text": "Refunds are accepted within 30 days with proof of purchase.",
+                "score": 0.92,
+                "metadata": {"source": "refund_policy.md"},
+            }
+        ],
+        top_k=1,
+    )
+
+    t.llm(
+        model="demo-model",
+        prompt="Question: What is the refund policy?",
+        response="Refunds are accepted within 30 days with proof of purchase.",
+        provider="local-demo",
+    )
+
+t.flush()
+```
+
+## Collector URL configuration
+
+The default collector URL is `http://localhost:4319`.
+
+Use the SledTrace environment variable:
+
+```bash
+export SLEDTRACE_COLLECTOR_URL=http://localhost:4319
+```
+
+PowerShell:
+
+```powershell
+$env:SLEDTRACE_COLLECTOR_URL="http://localhost:4319"
+```
+
+Legacy compatibility remains temporarily supported for migration:
+
+```bash
+export RAGLENS_COLLECTOR_URL=http://localhost:4319
+```
+
+The precedence is:
+
+1. `SLEDTRACE_COLLECTOR_URL`
+2. `RAGLENS_COLLECTOR_URL`
+3. `http://localhost:4319`
+
+## Legacy compatibility note
+
+Legacy `raglens` imports remain temporarily supported during migration, but new code should use the SledTrace package path:
+
+```python
+from sledtrace import trace
+```
+
+## More docs
+
+- [Full project README and screenshots](https://github.com/Schromeo/SledTrace#readme)
+- [User onboarding guide](https://github.com/Schromeo/SledTrace/blob/main/docs/product/USER_ONBOARDING.md)
+- [Python SDK integration guide](https://github.com/Schromeo/SledTrace/blob/main/docs/integrations/PYTHON_SDK_GUIDE.md)
+- [v0.7.0 release](https://github.com/Schromeo/SledTrace/releases/tag/v0.7.0)
+
+Repository examples such as `examples.custom_pipeline_demo` are local developer examples and not a separate public SDK surface.
+
+

sledtrace-0.7.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+raglens/__init__.py,sha256=Z1XUqDRZZGWmQekzsrvyv2V-Ht5PdRVdGHxTq3vUHBY,534
+raglens/chunks.py,sha256=aya7qsXMHfyZB1sCP5q1byhleYahnESqm2JHurwKlPg,12400
+raglens/client.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+raglens/models.py,sha256=3dFtLmj2eI29kWihFsoYaHsv7jnuBJlzcZI8V83Yk8E,1837
+raglens/trace.py,sha256=soxr-Sxcs_USGgdrnkQj34y7uvDio1ZhNAmIp1HuNOQ,10479
+sledtrace/__init__.py,sha256=go1T0aqaDKtfxsWML7_m720eqNyJJpfFq1mxtEegZ14,504
+sledtrace/cli.py,sha256=VDOJ5d3cqLweyNar0F2vrckJQCVoLfYvBDlyyIx8kNA,2758
+sledtrace-0.7.0.dist-info/licenses/LICENSE,sha256=BNRnIjkX59ltbQ3sxGUnO6nXWVZYJRCe83qZcnnnNvU,1079
+sledtrace-0.7.0.dist-info/METADATA,sha256=wmB0aAG2eaqXaD7-kFcoSYG0ICEze6yGSnU_Ba2ijQc,4529
+sledtrace-0.7.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sledtrace-0.7.0.dist-info/entry_points.txt,sha256=sYh3wzoWaFLUWUnclK-5eUjygRblXvypCG6PR9tN2CQ,49
+sledtrace-0.7.0.dist-info/top_level.txt,sha256=lGkXnSSWTdqDYLx4vNPEtle-wL5YBjmR_7ZMraOdrhY,18
+sledtrace-0.7.0.dist-info/RECORD,,

sledtrace-0.7.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sledtrace-0.7.0.dist-info/entry_points.txt

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

sledtrace-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SledTrace contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sledtrace-0.7.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+raglens
+sledtrace