SledTrace Python SDK

SledTrace is a local-first observability and debugging SDK for RAG pipelines.

This package documents 0.7.1 — Trustworthy Local Tracing, including one explicit, non-streaming OpenAI Responses usage-recording path. It does not automatically intercept model calls or reconcile a provider bill.

Project and visual overview: github.com/Schromeo/SledTrace

Distribution status

For this version, install from PyPI when available:

python -m pip install sledtrace==0.7.1

Before publication, or when testing source changes, use the editable install or locally built wheel below. The preceding production version is 0.7.0.

The immutable 0.7.0rc1 publication candidate remains available on TestPyPI for release-history purposes.

Install from source for development

cd sdk/python
python -m pip install -e .

Build a local wheel or sdist

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

python -m pip install dist/*.whl

CLI

Editable and wheel installations provide:

sledtrace --help
sledtrace serve --help
sledtrace version

sledtrace version reports 0.7.1 for this source tree and its built wheel.

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.

Copyable independent-app example

The source repository includes a single-file example that depends only on the installed sledtrace package and Python's standard library:

cd sdk/python
python -m examples.independent_app success
python -m examples.independent_app application-error
python -m examples.independent_app collector-offline --collector-url http://127.0.0.1:1

application-error intentionally returns 2 after the error trace is delivered. collector-offline intentionally returns 1 and prints both the completed business result and the observable SledTrace delivery failure. Copy examples/independent_app.py into another project or temporary directory to verify that it runs against an installed wheel without relying on the SledTrace checkout. When the checkout version is newer than production PyPI, install this checkout's editable package or built wheel before running its examples.

Basic usage

One Python tool path

E2 added a synchronous, caller-instrumented tool span and explicit task result in 0.7.1. These APIs are absent from production PyPI 0.7.0. From this checkout, run the deterministic example without a paid model:

cd sdk/python
python -m examples.agent_tool_demo success
python -m examples.agent_tool_demo business-failure
python -m examples.agent_tool_demo tool-recovery

Add --flush when a local Collector is running. The example uses one tool layer and simulated LLM outputs solely to check integration; it is not proof of value in a real external agent. For your own synchronous workflow, record safe input and output summaries, and keep the final task result separate from intermediate LLM responses:

with trace("policy-review", metadata={
    "task_id": "case-1", "run_id": "run-1",
    "variant": "baseline", "app_version": "my-app-1",
}) as t:
    with t.measure() as timing:
        found = lookup_policy("refund")
    t.tool("policy_lookup", input_summary="refund key",
           output_summary="one match" if found else "no match", timing=timing)
    t.llm(model="my-model", response="draft", input_tokens=10)
    t.log_task_result("review accepted", accepted=True)

t.tool(...) records only what the application supplies and returns a span ID. Use status="error", error="safe summary" for a failed tool or LLM attempt; the error is per step and does not automatically fail a recovered task. log_task_result(result, accepted=...) sets trace-level task_result, accepted, and the compatibility answer field; accepted=False marks the task trace as an error. No agent/LLM is run by the SDK, no provider usage is captured automatically, and sensitive arguments or secrets should not be put in summaries.

Explicit OpenAI Responses usage

Version 0.7.1 adds sledtrace.openai.record_response for one completed, non-streaming OpenAI Python SDK Responses result. Your application makes the provider call; the helper reads response.model and response.usage after the call and records an LLM span without storing prompts, output text, IDs, or credentials:

from sledtrace import trace
from sledtrace.openai import record_response

# response = your_openai_client.responses.create(...)
with trace("my-task") as t:
    record_response(t, response)
    # t.flush() when your local Collector is running

The OpenAI SDK is optional and not imported by SledTrace. Missing usage remains unknown; cached input and reasoning output are included in their parent counts, not added again. The Dashboard currently estimates Standard text-token-only USD cost for gpt-4.1-mini and gpt-4o-mini (including their documented snapshot IDs) using an official rate snapshot checked 2026-09-24. It leaves other models, missing cache counts, nonzero cache writes, and conflicted usage unpriced. This estimate is not a provider bill and excludes tools, alternate tiers, regional uplifts and other charges. Later model/rate overrides can be provided by a rate-card input in the Dashboard calculation; there is no user settings UI yet.

Existing RAG usage

This example uses 0.7.1's t.measure() and t.try_flush(). Against the published sledtrace==0.7.0 package, omit t.measure() and pass explicit duration_ms/latency_ms (or leave timing unset).

from sledtrace import trace

with trace("example") as t:
    with t.measure() as retrieval_timing:
        chunks = [
            {
                "id": "chunk-1",
                "text": "Refunds are accepted within 30 days with proof of purchase.",
                "score": 0.92,
                "score_type": "similarity",
                "score_direction": "higher_is_better",
                "metadata": {"source": "refund_policy.md"},
            }
        ]

    t.retrieval(
        query="What is the refund policy?",
        chunks=chunks,
        top_k=1,
        timing=retrieval_timing,
    )

    with t.measure() as llm_timing:
        answer = "Refunds are accepted within 30 days with proof of purchase."

    t.llm(
        model="demo-model",
        prompt="Question: What is the refund policy?",
        response=answer,
        provider="local-demo",
        timing=llm_timing,
    )

t.flush()

t.flush() is the existing strict delivery path and still raises on serialization, timeout, HTTP, or connection failures. Applications that must keep telemetry failure separate from business behavior can opt into the observable best-effort path:

delivery = t.try_flush()
if not delivery.ok:
    print(f"SledTrace delivery failed: {delivery.error!r}")

try_flush() returns TraceFlushResult(ok, response, error). It performs one synchronous attempt with the same URL/timeout options as flush(); it does not retry, queue, log automatically, or catch KeyboardInterrupt/SystemExit.

t.measure() captures actual operation timing. Calls recorded only after the work, without timing, duration_ms for retrieval, or latency_ms for LLM, remain compatible and are shown as not measured.

For retriever-native results, use normalize_chunk(...) or normalize_chunks(...). The normalizer preserves score_type and score_direction: named distances are lower-is-better, named similarity/relevance scores are higher-is-better, and ambiguous tuple scores are unknown. SledTrace never assumes a universal 1 - distance conversion. Explicit custom mappings can set score_type and score_direction; existing explicit score= mappings remain higher-is-better by default for compatibility.

Collector URL configuration

The default collector URL is http://localhost:4319.

Use the SledTrace environment variable:

export SLEDTRACE_COLLECTOR_URL=http://localhost:4319

PowerShell:

$env:SLEDTRACE_COLLECTOR_URL="http://localhost:4319"

Legacy compatibility remains temporarily supported for migration:

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:

from sledtrace import trace

More docs

• Full project README and screenshots
• User onboarding guide
• Python SDK integration guide
• v0.7.1 release notes
• v0.7.0 release

Repository examples are source-only aids and are not bundled as a separate public SDK surface. examples.independent_app is deliberately copyable and uses only the installed public API; the other examples remain local developer demos.