debrix 0.1.0a1__py3-none-any.whl

debrix/__init__.py

@@ -0,0 +1,23 @@
+"""Debrix — open-source instrumentation SDK for AI agents."""
+
+from debrix.config import configure, force_flush
+from debrix.semconv import SPAN_KINDS, Attr, Event, SpanKind
+from debrix.span import DebrixSpan
+from debrix.tracing import get_tracer, trace_agent, trace_span, trace_tool
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    "__version__",
+    "SpanKind",
+    "Attr",
+    "Event",
+    "SPAN_KINDS",
+    "configure",
+    "force_flush",
+    "DebrixSpan",
+    "get_tracer",
+    "trace_agent",
+    "trace_tool",
+    "trace_span",
+]

debrix/config.py

@@ -0,0 +1,115 @@
+"""OTLP/HTTP exporter configuration for Debrix.
+
+Default endpoint: ``http://127.0.0.1:4318`` (OTLP/HTTP protobuf).
+Standard OpenTelemetry environment variables still apply and override defaults
+when set (e.g. ``OTEL_EXPORTER_OTLP_ENDPOINT``).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import warnings
+from typing import Final
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor
+
+from debrix.payloads import ensure_worker, flush_payloads, get_capture_mode
+
+DEFAULT_OTLP_ENDPOINT: Final = "http://127.0.0.1:4318"
+
+logger = logging.getLogger("debrix.config")
+
+_configured = False
+_endpoint: str = DEFAULT_OTLP_ENDPOINT
+
+
+def _resolved_endpoint(endpoint: str | None = None) -> str:
+    if endpoint:
+        return endpoint.rstrip("/")
+    return os.environ.get(
+        "OTEL_EXPORTER_OTLP_ENDPOINT", DEFAULT_OTLP_ENDPOINT
+    ).rstrip("/")
+
+
+def force_flush(timeout_millis: int = 10_000) -> bool:
+    """Flush OTLP spans and pending conversation payload uploads.
+
+    Short-lived scripts must call this (or rely on atexit) before exit;
+    otherwise ``blob_ref`` may land in Debrix without the payload body.
+    """
+    ok = True
+    provider = trace.get_tracer_provider()
+    if isinstance(provider, TracerProvider):
+        ok = bool(provider.force_flush(timeout_millis=timeout_millis)) and ok
+    ok = flush_payloads(timeout_millis=timeout_millis) and ok
+    return ok
+
+
+def configure(
+    *,
+    endpoint: str | None = None,
+    service_name: str = "debrix",
+    batch: bool = True,
+) -> TracerProvider:
+    """Configure a global TracerProvider that exports OTLP/HTTP to Debrix.
+
+    Idempotent: subsequent calls return the existing provider without
+    re-installing exporters.
+
+    Args:
+        endpoint: OTLP base URL (paths like ``/v1/traces`` are appended by the
+            exporter). Defaults to ``http://127.0.0.1:4318``, or
+            ``OTEL_EXPORTER_OTLP_ENDPOINT`` when set.
+        service_name: Value for ``service.name`` resource attribute.
+        batch: Use ``BatchSpanProcessor`` when True (default); otherwise
+            ``SimpleSpanProcessor`` (useful for short-lived scripts).
+    """
+    global _configured, _endpoint
+
+    current = trace.get_tracer_provider()
+    # OpenTelemetry forbids replacing an installed TracerProvider; reuse it.
+    if isinstance(current, TracerProvider):
+        _configured = True
+        ensure_worker(_endpoint)
+        return current
+
+    resolved = _resolved_endpoint(endpoint)
+    _endpoint = resolved
+    # Ensure env protocol matches our contract when unset.
+    os.environ.setdefault("OTEL_EXPORTER_OTLP_PROTOCOL", "http/protobuf")
+
+    if not batch and get_capture_mode() == "full":
+        warnings.warn(
+            "debrix.configure(batch=False) with full message capture may block "
+            "the agent on span end while large exports flush; prefer batch=True "
+            "for long-running agents.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    resource = Resource.create({"service.name": service_name})
+    provider = TracerProvider(resource=resource)
+    exporter = OTLPSpanExporter(endpoint=f"{resolved}/v1/traces")
+    processor = (
+        BatchSpanProcessor(exporter) if batch else SimpleSpanProcessor(exporter)
+    )
+    provider.add_span_processor(processor)
+    trace.set_tracer_provider(provider)
+    _configured = True
+    ensure_worker(resolved)
+    return provider
+
+
+def reset_for_tests() -> None:
+    """Reset configuration flag (tests only)."""
+    global _configured, _endpoint
+    _configured = False
+    _endpoint = DEFAULT_OTLP_ENDPOINT
+    from debrix.payloads import reset_worker_for_tests
+
+    reset_worker_for_tests()

debrix/payloads.py

@@ -0,0 +1,279 @@
+"""Background payload worker: full conversation bodies → Debrix /v1/payloads."""
+
+from __future__ import annotations
+
+import atexit
+import gzip
+import hashlib
+import json
+import logging
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from opentelemetry.trace import SpanContext
+
+logger = logging.getLogger("debrix.payloads")
+
+CaptureMode = Literal["full", "preview", "off"]
+
+DEFAULT_MAX_PAYLOAD_BYTES = 209_715_200  # ~200 MiB
+DEFAULT_PREVIEW_CHARS = 4096
+DEFAULT_QUEUE_SIZE = 64
+
+
+@dataclass
+class PayloadJob:
+    kind: Literal["messages", "response"]
+    body: bytes
+    sha256_hex: str
+    span_context: SpanContext
+    service_name: str
+    trace_id_hex: str
+    agent_name: str | None = None
+
+
+_worker: PayloadWorker | None = None
+_worker_lock = threading.Lock()
+_atexit_registered = False
+
+
+def get_capture_mode() -> CaptureMode:
+    env = os.environ.get("DEBRIX_CAPTURE_MESSAGES", "").strip().lower()
+    if env in ("full", "preview", "off"):
+        return env  # type: ignore[return-value]
+    # Desktop Memory tab writes settings.json next to the app DB.
+    for candidate in _settings_candidates():
+        try:
+            with open(candidate, encoding="utf-8") as f:
+                data = json.load(f)
+            mode = str(data.get("captureMessages", "")).lower()
+            if mode in ("full", "preview", "off"):
+                return mode  # type: ignore[return-value]
+        except (OSError, json.JSONDecodeError, TypeError):
+            continue
+    return "full"
+
+
+def get_max_payload_bytes() -> int:
+    raw = os.environ.get("DEBRIX_MAX_PAYLOAD_BYTES")
+    if raw:
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+    return DEFAULT_MAX_PAYLOAD_BYTES
+
+
+def get_preview_chars() -> int:
+    raw = os.environ.get("DEBRIX_PREVIEW_CHARS")
+    if raw:
+        try:
+            return max(64, int(raw))
+        except ValueError:
+            pass
+    return DEFAULT_PREVIEW_CHARS
+
+
+def _settings_candidates() -> list[str]:
+    home = os.path.expanduser("~")
+    return [
+        os.environ.get("DEBRIX_SETTINGS_PATH", ""),
+        os.path.join(
+            home,
+            "Library",
+            "Application Support",
+            "com.debrix.app",
+            "settings.json",
+        ),
+        os.path.join(home, ".debrix", "settings.json"),
+    ]
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def truncate_text(text: str, budget: int) -> tuple[str, bool]:
+    if len(text) <= budget:
+        return text, False
+    head = budget // 2
+    tail = budget - head
+    return text[:head] + "…[preview]…" + text[-tail:], True
+
+
+def build_messages_preview(
+    messages: list[dict[str, str]], preview_chars: int
+) -> tuple[list[dict[str, str]], bool]:
+    truncated = False
+    out: list[dict[str, str]] = []
+    for msg in messages:
+        entry = dict(msg)
+        content, was = truncate_text(entry.get("content", ""), preview_chars)
+        entry["content"] = content
+        truncated = truncated or was
+        out.append(entry)
+    return out, truncated
+
+
+def build_response_preview(
+    response: dict[str, Any], preview_chars: int
+) -> tuple[dict[str, Any], bool]:
+    out = dict(response)
+    truncated = False
+    content = out.get("content")
+    if isinstance(content, str):
+        shortened, was = truncate_text(content, preview_chars)
+        out["content"] = shortened
+        truncated = was
+    return out, truncated
+
+
+class PayloadWorker:
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        max_bytes: int = DEFAULT_MAX_PAYLOAD_BYTES,
+        queue_size: int = DEFAULT_QUEUE_SIZE,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._max_bytes = max_bytes
+        self._queue: queue.Queue[PayloadJob | None] = queue.Queue(maxsize=queue_size)
+        self._thread = threading.Thread(
+            target=self._run, name="debrix-payload-worker", daemon=True
+        )
+        self._started = False
+        self._pending = 0
+        self._pending_lock = threading.Lock()
+        self._idle = threading.Condition(self._pending_lock)
+
+    def start(self) -> None:
+        if not self._started:
+            self._thread.start()
+            self._started = True
+
+    def stop(self) -> None:
+        try:
+            self._queue.put_nowait(None)
+        except queue.Full:
+            pass
+
+    def try_enqueue(self, job: PayloadJob) -> str | None:
+        """Enqueue job. Returns error string on failure (overflow / over-cap)."""
+        if len(job.body) > self._max_bytes:
+            return f"payload exceeds max size ({len(job.body)} > {self._max_bytes} bytes)"
+        with self._pending_lock:
+            self._pending += 1
+        try:
+            self._queue.put_nowait(job)
+            return None
+        except queue.Full:
+            with self._pending_lock:
+                self._pending -= 1
+                if self._pending <= 0:
+                    self._idle.notify_all()
+            return "payload queue full"
+
+    def flush(self, timeout_millis: int = 10_000) -> bool:
+        """Block until queued uploads finish (or timeout). Returns True if idle."""
+        deadline = time.monotonic() + (timeout_millis / 1000.0)
+        with self._idle:
+            while self._pending > 0:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    logger.warning(
+                        "payload flush timed out with %s job(s) still pending",
+                        self._pending,
+                    )
+                    return False
+                self._idle.wait(timeout=remaining)
+            return True
+
+    def _job_done(self) -> None:
+        with self._idle:
+            self._pending = max(0, self._pending - 1)
+            if self._pending == 0:
+                self._idle.notify_all()
+
+    def _run(self) -> None:
+        while True:
+            job = self._queue.get()
+            if job is None:
+                return
+            try:
+                self._upload(job)
+            except Exception:  # noqa: BLE001 — never kill worker
+                logger.exception("payload upload failed")
+            finally:
+                self._job_done()
+
+    def _upload(self, job: PayloadJob) -> None:
+        compressed = gzip.compress(job.body)
+        url = f"{self._endpoint}/v1/payloads"
+        req = urllib.request.Request(url, data=compressed, method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Content-Encoding", "gzip")
+        req.add_header("X-Debrix-Sha256", job.sha256_hex)
+        req.add_header("X-Debrix-Kind", job.kind)
+        req.add_header("X-Debrix-Trace-Id", job.trace_id_hex)
+        req.add_header("X-Debrix-Service-Name", job.service_name)
+        if job.agent_name:
+            req.add_header("X-Debrix-Agent-Name", job.agent_name)
+        try:
+            with urllib.request.urlopen(req, timeout=60) as resp:
+                resp.read()
+            logger.debug(
+                "uploaded %s payload sha256:%s (%s bytes)",
+                job.kind,
+                job.sha256_hex,
+                len(job.body),
+            )
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            logger.error("payload upload HTTP %s: %s", exc.code, body)
+            return
+        except urllib.error.URLError as exc:
+            logger.error("payload upload failed: %s", exc)
+            return
+
+
+def ensure_worker(endpoint: str) -> PayloadWorker:
+    global _worker, _atexit_registered
+    with _worker_lock:
+        if _worker is None:
+            _worker = PayloadWorker(
+                endpoint=endpoint, max_bytes=get_max_payload_bytes()
+            )
+            _worker.start()
+            if not _atexit_registered:
+                atexit.register(_atexit_flush)
+                _atexit_registered = True
+        return _worker
+
+
+def flush_payloads(timeout_millis: int = 10_000) -> bool:
+    """Flush the global payload worker if it exists."""
+    with _worker_lock:
+        worker = _worker
+    if worker is None:
+        return True
+    return worker.flush(timeout_millis=timeout_millis)
+
+
+def _atexit_flush() -> None:
+    flush_payloads(timeout_millis=10_000)
+
+
+def reset_worker_for_tests() -> None:
+    global _worker
+    with _worker_lock:
+        if _worker is not None:
+            _worker.stop()
+            _worker.flush(timeout_millis=1_000)
+        _worker = None

debrix/semconv.py

@@ -0,0 +1,83 @@
+"""Debrix semantic conventions — shared span-kind and attribute-key contract.
+
+This module is the Python source of truth for the Debrix semantic model. It
+mirrors ``docs/Semantic_Model.md`` and the Rust ``semconv.rs`` in the desktop
+app. Change the spec doc first, then keep all three in lockstep.
+"""
+
+from __future__ import annotations
+
+__all__ = ["SpanKind", "Attr", "Event", "SPAN_KINDS"]
+
+
+class SpanKind:
+    """Allowed values for the ``debrix.span.kind`` attribute."""
+
+    AGENT = "agent"
+    LLM = "llm"
+    TOOL = "tool"
+    MCP = "mcp"
+    MEMORY = "memory"
+    EVALUATION = "evaluation"
+    HUMAN = "human"
+    CUSTOM = "custom"
+
+
+class Attr:
+    """Debrix-owned attribute keys. All use the ``debrix.`` prefix."""
+
+    # Identity
+    SPAN_KIND = "debrix.span.kind"
+    AGENT_NAME = "debrix.agent.name"
+    TOOL_NAME = "debrix.tool.name"
+    MCP_SERVER = "debrix.mcp.server"
+    MCP_TOOL = "debrix.mcp.tool"
+
+    # Messages / response (legacy inline + blob model)
+    MESSAGES = "debrix.messages"
+    MESSAGES_PREVIEW = "debrix.messages.preview"
+    MESSAGES_BLOB_REF = "debrix.messages.blob_ref"
+    MESSAGES_BYTES = "debrix.messages.bytes"
+    MESSAGES_CHARS = "debrix.messages.chars"
+    MESSAGES_COUNT = "debrix.messages.count"
+    MESSAGES_TRUNCATED = "debrix.messages.truncated"
+    MESSAGES_CAPTURE_ERROR = "debrix.messages.capture_error"
+
+    RESPONSE = "debrix.response"
+    RESPONSE_PREVIEW = "debrix.response.preview"
+    RESPONSE_BLOB_REF = "debrix.response.blob_ref"
+    RESPONSE_BYTES = "debrix.response.bytes"
+    RESPONSE_CHARS = "debrix.response.chars"
+    RESPONSE_TRUNCATED = "debrix.response.truncated"
+    RESPONSE_CAPTURE_ERROR = "debrix.response.capture_error"
+
+    # Status / errors
+    ERROR_SUMMARY = "debrix.error.summary"
+
+    # Mock / replay / eval (reserved for later phases)
+    MOCKED = "debrix.mocked"
+    REPLAY_INPUT = "debrix.replay.input"
+    REPLAY_OUTPUT = "debrix.replay.output"
+    REPLAY_SEQUENCE_INDEX = "debrix.replay.sequence_index"
+    EVAL_SOURCE_TRACE_ID = "debrix.eval.source_trace_id"
+
+    PAYLOAD_KIND = "debrix.payload.kind"
+    PAYLOAD_BLOB_REF = "debrix.payload.blob_ref"
+
+
+class Event:
+    """Debrix span event names."""
+
+    PAYLOAD_READY = "debrix.payload.ready"
+
+
+SPAN_KINDS: tuple[str, ...] = (
+    SpanKind.AGENT,
+    SpanKind.LLM,
+    SpanKind.TOOL,
+    SpanKind.MCP,
+    SpanKind.MEMORY,
+    SpanKind.EVALUATION,
+    SpanKind.HUMAN,
+    SpanKind.CUSTOM,
+)

debrix/span.py

@@ -0,0 +1,243 @@
+"""Debrix span wrapper with opt-in message / response recording."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from opentelemetry.trace import Span, Status, StatusCode
+
+from debrix.payloads import (
+    PayloadJob,
+    build_messages_preview,
+    build_response_preview,
+    ensure_worker,
+    get_capture_mode,
+    get_preview_chars,
+    sha256_hex,
+)
+from debrix.semconv import Attr, Event
+
+__all__ = ["DebrixSpan", "ALLOWED_MESSAGE_ROLES"]
+
+ALLOWED_MESSAGE_ROLES: frozenset[str] = frozenset(
+    {"system", "user", "assistant", "tool"}
+)
+
+
+def _normalize_messages(
+    messages: Sequence[Mapping[str, Any]],
+) -> list[dict[str, str]]:
+    normalized: list[dict[str, str]] = []
+    for i, msg in enumerate(messages):
+        if not isinstance(msg, Mapping):
+            raise TypeError(
+                f"messages[{i}] must be a mapping, got {type(msg).__name__}"
+            )
+        role = msg.get("role")
+        content = msg.get("content")
+        if not isinstance(role, str) or role not in ALLOWED_MESSAGE_ROLES:
+            raise ValueError(
+                f"messages[{i}].role must be one of "
+                f"{sorted(ALLOWED_MESSAGE_ROLES)}, got {role!r}"
+            )
+        if not isinstance(content, str):
+            raise TypeError(
+                f"messages[{i}].content must be a str, "
+                f"got {type(content).__name__}"
+            )
+        entry: dict[str, str] = {"role": role, "content": content}
+        name = msg.get("name")
+        if name is not None:
+            if not isinstance(name, str):
+                raise TypeError(
+                    f"messages[{i}].name must be a str when provided, "
+                    f"got {type(name).__name__}"
+                )
+            entry["name"] = name
+        normalized.append(entry)
+    return normalized
+
+
+def _service_name_from_span(span: Span) -> str:
+    # Resource is on the tracer provider; fall back for tests.
+    try:
+        resource = span.resource  # type: ignore[attr-defined]
+        if resource is not None:
+            val = resource.attributes.get("service.name")
+            if isinstance(val, str) and val:
+                return val
+    except Exception:  # noqa: BLE001
+        pass
+    return "debrix"
+
+
+def _trace_id_hex(span: Span) -> str:
+    ctx = span.get_span_context()
+    return format(ctx.trace_id, "032x")
+
+
+def _current_agent_name() -> str | None:
+    # Lazy import: tracing → span → tracing would cycle at module load.
+    from debrix.tracing import current_agent_name
+
+    return current_agent_name()
+
+
+class DebrixSpan:
+    """Thin wrapper around an OpenTelemetry span with Debrix helpers."""
+
+    def __init__(self, span: Span) -> None:
+        self._span = span
+
+    @property
+    def otel_span(self) -> Span:
+        """Underlying OpenTelemetry span."""
+        return self._span
+
+    def record_messages(
+        self,
+        messages: Sequence[Mapping[str, Any]],
+    ) -> None:
+        """Record opt-in conversation messages on this span.
+
+        Full bodies are uploaded asynchronously to Debrix ``/v1/payloads``.
+        The span receives preview + stats + ``blob_ref`` immediately so the
+        agent thread never waits on disk/network for large prompts.
+        """
+        mode = get_capture_mode()
+        if mode == "off":
+            return
+
+        normalized = _normalize_messages(messages)
+        preview_chars = get_preview_chars()
+        preview, truncated = build_messages_preview(normalized, preview_chars)
+        body = json.dumps(normalized, separators=(",", ":")).encode("utf-8")
+        digest = sha256_hex(body)
+
+        self._span.set_attribute(
+            Attr.MESSAGES_PREVIEW, json.dumps(preview, separators=(",", ":"))
+        )
+        self._span.set_attribute(Attr.MESSAGES_BYTES, len(body))
+        self._span.set_attribute(Attr.MESSAGES_CHARS, len(body.decode("utf-8")))
+        self._span.set_attribute(Attr.MESSAGES_COUNT, len(normalized))
+        self._span.set_attribute(Attr.MESSAGES_TRUNCATED, truncated)
+
+        if mode == "preview":
+            # Compat: also set legacy inline attribute to the preview.
+            self._span.set_attribute(
+                Attr.MESSAGES, json.dumps(preview, separators=(",", ":"))
+            )
+            return
+
+        # full capture
+        blob_ref = f"sha256:{digest}"
+        self._span.set_attribute(Attr.MESSAGES_BLOB_REF, blob_ref)
+        # Small payloads: also keep legacy inline for older UIs / offline Debrix.
+        if len(body) <= 64_000:
+            self._span.set_attribute(Attr.MESSAGES, body.decode("utf-8"))
+
+        from debrix.config import DEFAULT_OTLP_ENDPOINT, _resolved_endpoint
+
+        worker = ensure_worker(_resolved_endpoint() or DEFAULT_OTLP_ENDPOINT)
+        err = worker.try_enqueue(
+            PayloadJob(
+                kind="messages",
+                body=body,
+                sha256_hex=digest,
+                span_context=self._span.get_span_context(),
+                service_name=_service_name_from_span(self._span),
+                trace_id_hex=_trace_id_hex(self._span),
+                agent_name=_current_agent_name(),
+            )
+        )
+        if err:
+            self._span.set_attribute(Attr.MESSAGES_CAPTURE_ERROR, err)
+        else:
+            self._emit_payload_ready("messages", blob_ref)
+
+    def record_response(self, response: Mapping[str, Any]) -> None:
+        """Record opt-in model output / usage on this span.
+
+        Expected loose shape (extra keys allowed)::
+
+            {
+              "content": "...",
+              "model": "...",
+              "usage": {"input_tokens": 0, "output_tokens": 0}
+            }
+        """
+        if not isinstance(response, Mapping):
+            raise TypeError(
+                f"response must be a mapping, got {type(response).__name__}"
+            )
+        mode = get_capture_mode()
+        if mode == "off":
+            return
+
+        payload = dict(response)
+        preview_chars = get_preview_chars()
+        preview, truncated = build_response_preview(payload, preview_chars)
+        body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        digest = sha256_hex(body)
+
+        self._span.set_attribute(
+            Attr.RESPONSE_PREVIEW, json.dumps(preview, separators=(",", ":"))
+        )
+        self._span.set_attribute(Attr.RESPONSE_BYTES, len(body))
+        self._span.set_attribute(Attr.RESPONSE_CHARS, len(body.decode("utf-8")))
+        self._span.set_attribute(Attr.RESPONSE_TRUNCATED, truncated)
+
+        if mode == "preview":
+            self._span.set_attribute(
+                Attr.RESPONSE, json.dumps(preview, separators=(",", ":"))
+            )
+            return
+
+        blob_ref = f"sha256:{digest}"
+        self._span.set_attribute(Attr.RESPONSE_BLOB_REF, blob_ref)
+        if len(body) <= 64_000:
+            self._span.set_attribute(Attr.RESPONSE, body.decode("utf-8"))
+
+        from debrix.config import DEFAULT_OTLP_ENDPOINT, _resolved_endpoint
+
+        worker = ensure_worker(_resolved_endpoint() or DEFAULT_OTLP_ENDPOINT)
+        err = worker.try_enqueue(
+            PayloadJob(
+                kind="response",
+                body=body,
+                sha256_hex=digest,
+                span_context=self._span.get_span_context(),
+                service_name=_service_name_from_span(self._span),
+                trace_id_hex=_trace_id_hex(self._span),
+                agent_name=_current_agent_name(),
+            )
+        )
+        if err:
+            self._span.set_attribute(Attr.RESPONSE_CAPTURE_ERROR, err)
+        else:
+            self._emit_payload_ready("response", blob_ref)
+
+    def _emit_payload_ready(self, kind: str, blob_ref: str) -> None:
+        """Mark the content-addressed blob as queued (see Semantic Model)."""
+        self._span.add_event(
+            Event.PAYLOAD_READY,
+            {
+                Attr.PAYLOAD_KIND: kind,
+                Attr.PAYLOAD_BLOB_REF: blob_ref,
+            },
+        )
+
+    def record_exception(self, exc: BaseException) -> None:
+        """Mark the span as errored and attach a short Debrix summary."""
+        self._span.set_status(Status(StatusCode.ERROR, str(exc)))
+        self._span.record_exception(exc)
+        summary = f"{type(exc).__name__}: {exc}"
+        if len(summary) > 200:
+            summary = summary[:197] + "..."
+        self._span.set_attribute(Attr.ERROR_SUMMARY, summary)
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set an attribute on the underlying span."""
+        self._span.set_attribute(key, value)

debrix/tracing.py

@@ -0,0 +1,327 @@
+"""Debrix instrumentation primitives: agents, tools, and generic spans."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Iterator, Mapping, Sequence
+from contextlib import contextmanager
+from typing import Any, ParamSpec, TypeVar, cast, overload
+
+import opentelemetry.context as otel_context
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.trace import Tracer
+
+from debrix.config import configure
+from debrix.semconv import Attr, SpanKind
+from debrix.span import DebrixSpan
+
+__all__ = [
+    "trace_agent",
+    "trace_tool",
+    "trace_span",
+    "get_tracer",
+    "current_agent_name",
+]
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+_TRACER_NAME = "debrix"
+_SKIP_BOUND_PARAMS = frozenset({"self", "cls"})
+_AGENT_NAME_KEY = otel_context.create_key("debrix.agent.name")
+
+
+def current_agent_name() -> str | None:
+    """Return the nearest enclosing ``trace_agent`` name, if any."""
+    value = otel_context.get_value(_AGENT_NAME_KEY)
+    return value if isinstance(value, str) and value else None
+
+
+def get_tracer() -> Tracer:
+    """Return the Debrix tracer, ensuring a provider is configured."""
+    current = trace.get_tracer_provider()
+    if not isinstance(current, TracerProvider):
+        configure()
+    return trace.get_tracer(_TRACER_NAME)
+
+
+def _attach_span(span: Any) -> object:
+    ctx = trace.set_span_in_context(span)
+    return otel_context.attach(ctx)
+
+
+def _detach_token(token: object) -> None:
+    otel_context.detach(token)
+
+
+def _json_safe(value: Any) -> Any:
+    """Convert a value into something ``json.dumps`` can encode."""
+    if value is None or isinstance(value, (bool, int, float, str)):
+        return value
+    if isinstance(value, Mapping):
+        return {str(k): _json_safe(v) for k, v in value.items()}
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [_json_safe(v) for v in value]
+    if isinstance(value, (bytes, bytearray)):
+        return value.decode("utf-8", errors="replace")
+    return repr(value)
+
+
+def _dumps_replay(value: Any) -> str:
+    return json.dumps(_json_safe(value), ensure_ascii=False)
+
+
+def _bind_arguments(
+    fn: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> dict[str, Any]:
+    """Bind call args to parameter names for replay (skip ``self`` / ``cls``)."""
+    try:
+        bound = inspect.signature(fn).bind(*args, **kwargs)
+        bound.apply_defaults()
+    except TypeError:
+        return {
+            "args": list(args),
+            "kwargs": dict(kwargs),
+        }
+    return {
+        name: value
+        for name, value in bound.arguments.items()
+        if name not in _SKIP_BOUND_PARAMS
+    }
+
+
+@contextmanager
+def trace_span(
+    name: str,
+    *,
+    kind: str = SpanKind.CUSTOM,
+    attributes: dict[str, str] | None = None,
+) -> Iterator[DebrixSpan]:
+    """Context manager for a Debrix-instrumented span.
+
+    Args:
+        name: Span name.
+        kind: Value for ``debrix.span.kind`` (default ``custom``).
+        attributes: Extra string attributes to set at start.
+    """
+    attrs: dict[str, str] = {Attr.SPAN_KIND: kind}
+    if attributes:
+        attrs.update(attributes)
+    span = get_tracer().start_span(name, attributes=attrs)
+    token = _attach_span(span)
+    agent_token: object | None = None
+    if kind == SpanKind.AGENT:
+        agent_name = attrs.get(Attr.AGENT_NAME) or name
+        agent_token = otel_context.attach(
+            otel_context.set_value(_AGENT_NAME_KEY, agent_name)
+        )
+    wrapper = DebrixSpan(span)
+    exc: BaseException | None = None
+    try:
+        yield wrapper
+    except BaseException as e:
+        exc = e
+        raise
+    finally:
+        if exc is not None:
+            wrapper.record_exception(exc)
+        span.end()
+        if agent_token is not None:
+            _detach_token(agent_token)
+        _detach_token(token)
+
+
+def _wrap_function(
+    fn: Callable[P, R],
+    *,
+    span_name: str,
+    span_kind: str,
+    attributes: dict[str, str],
+    capture_io: bool = False,
+) -> Callable[P, R]:
+    if inspect.iscoroutinefunction(fn):
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
+            with trace_span(
+                span_name, kind=span_kind, attributes=attributes
+            ) as span:
+                if capture_io:
+                    # Record input before the call so failures still keep args.
+                    span.set_attribute(
+                        Attr.REPLAY_INPUT,
+                        _dumps_replay(
+                            _bind_arguments(fn, args, kwargs)
+                        ),
+                    )
+                result = await cast(Callable[..., Awaitable[Any]], fn)(
+                    *args, **kwargs
+                )
+                if capture_io:
+                    span.set_attribute(
+                        Attr.REPLAY_OUTPUT, _dumps_replay(result)
+                    )
+                return result
+
+        return cast(Callable[P, R], async_wrapper)
+
+    @functools.wraps(fn)
+    def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        with trace_span(span_name, kind=span_kind, attributes=attributes) as span:
+            if capture_io:
+                span.set_attribute(
+                    Attr.REPLAY_INPUT,
+                    _dumps_replay(_bind_arguments(fn, args, kwargs)),
+                )
+            result = fn(*args, **kwargs)
+            if capture_io:
+                span.set_attribute(Attr.REPLAY_OUTPUT, _dumps_replay(result))
+            return result
+
+    return sync_wrapper
+
+
+def _instrument(
+    *,
+    span_kind: str,
+    identity_key: str,
+    func: Callable[..., Any] | None,
+    name: str | None,
+    capture_io: bool = False,
+) -> Any:
+    """Shared implementation for ``trace_agent`` / ``trace_tool``.
+
+    Supports:
+    - ``@trace_agent`` / ``@trace_tool``
+    - ``@trace_agent(name=...)`` / ``@trace_tool(name=...)``
+    - ``with trace_agent("name"):`` / ``with trace_tool("name"):``
+    """
+    # Context-manager form: first positional arg is a string span name.
+    if isinstance(func, str):
+        span_name = func
+
+        @contextmanager
+        def cm() -> Iterator[DebrixSpan]:
+            with trace_span(
+                span_name,
+                kind=span_kind,
+                attributes={identity_key: span_name},
+            ) as span:
+                yield span
+
+        return cm()
+
+    def decorate(fn: Callable[P, R]) -> Callable[P, R]:
+        span_name = name or fn.__name__
+        return _wrap_function(
+            fn,
+            span_name=span_name,
+            span_kind=span_kind,
+            attributes={identity_key: span_name},
+            capture_io=capture_io,
+        )
+
+    if func is not None:
+        return decorate(func)
+    return decorate
+
+
+@overload
+def trace_agent(func: Callable[P, R], /) -> Callable[P, R]: ...
+
+
+@overload
+def trace_agent(name: str, /) -> Any: ...
+
+
+@overload
+def trace_agent(
+    func: None = None,
+    /,
+    *,
+    name: str | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def trace_agent(
+    func: Callable[P, R] | str | None = None,
+    /,
+    *,
+    name: str | None = None,
+) -> Any:
+    """Instrument an agent boundary.
+
+    Usage::
+
+        @trace_agent
+        def run(): ...
+
+        @trace_agent(name="planner")
+        def run(): ...
+
+        with trace_agent("planner") as span:
+            ...
+    """
+    return _instrument(
+        span_kind=SpanKind.AGENT,
+        identity_key=Attr.AGENT_NAME,
+        func=func,
+        name=name,
+        capture_io=False,
+    )
+
+
+@overload
+def trace_tool(func: Callable[P, R], /) -> Callable[P, R]: ...
+
+
+@overload
+def trace_tool(name: str, /) -> Any: ...
+
+
+@overload
+def trace_tool(
+    func: None = None,
+    /,
+    *,
+    name: str | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+
+def trace_tool(
+    func: Callable[P, R] | str | None = None,
+    /,
+    *,
+    name: str | None = None,
+) -> Any:
+    """Instrument a tool call.
+
+    When used as a decorator, records bound call arguments on
+    ``debrix.replay.input`` and the return value on ``debrix.replay.output``
+    (JSON strings) for later deterministic replay. Input is written before the
+    call so failures still retain arguments. Context-manager form does not
+    auto-capture I/O — set those attributes yourself if needed.
+
+    Usage::
+
+        @trace_tool
+        def search(): ...
+
+        @trace_tool(name="web_search")
+        def search(): ...
+
+        with trace_tool("search") as span:
+            ...
+    """
+    return _instrument(
+        span_kind=SpanKind.TOOL,
+        identity_key=Attr.TOOL_NAME,
+        func=func,
+        name=name,
+        capture_io=True,
+    )

debrix-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: debrix
+Version: 0.1.0a1
+Summary: Open-source instrumentation SDK for Debrix — local-first AI Agent DevTools
+Project-URL: Homepage, https://github.com/goyal-prateek/debrix-sdk
+Project-URL: Repository, https://github.com/goyal-prateek/debrix-sdk
+Project-URL: Issues, https://github.com/goyal-prateek/debrix-sdk/issues
+Project-URL: Documentation, https://github.com/goyal-prateek/debrix-sdk#readme
+Author-email: Prateek Goyal <gprateek015@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,debrix,observability,opentelemetry,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0
+Requires-Dist: opentelemetry-sdk>=1.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# debrix
+
+Open-source instrumentation SDK for [Debrix](https://github.com/goyal-prateek/debrix-sdk) — local-first AI Agent DevTools.
+
+**Status:** alpha (`0.1.0a1`). APIs may change.
+
+Requires the Debrix desktop app running locally to receive traces (OTLP/HTTP on `localhost:4318`).
+
+## Install
+
+```bash
+pip install debrix
+```
+
+TestPyPI (pre-release smoke):
+
+```bash
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ debrix==0.1.0a1
+```
+
+## Quick start
+
+```python
+from debrix import configure, force_flush, trace_agent, trace_tool, trace_span, SpanKind
+
+configure(batch=False)  # OTLP/HTTP → http://127.0.0.1:4318
+
+@trace_agent
+def run_agent(query: str) -> str:
+    return research(query)
+
+@trace_tool(name="search")
+def research(query: str) -> str:
+    with trace_span("complete", kind=SpanKind.LLM) as span:
+        span.record_messages([
+            {"role": "system", "content": "You are helpful."},
+            {"role": "user", "content": query},
+        ])
+        answer = "..."
+        span.record_response({
+            "content": answer,
+            "usage": {"input_tokens": 10, "output_tokens": 5},
+        })
+        return answer
+
+run_agent("hello")
+force_flush()  # flush OTLP *and* conversation payload uploads before exit
+```
+
+Decorators also work as context managers:
+
+```python
+with trace_agent("planner") as span:
+    with trace_tool("lookup"):
+        ...
+```
+
+## Public API
+
+| Symbol | Purpose |
+| ------ | ------- |
+| `configure()` | Install OTLP/HTTP exporter to Debrix (`:4318`) |
+| `force_flush()` | Flush OTLP spans + pending `/v1/payloads` uploads (call before short scripts exit) |
+| `trace_agent` | Agent boundary (decorator or `with trace_agent("name")`) |
+| `trace_tool` | Tool call span; decorator records `debrix.replay.input` / `output` |
+| `trace_span` | Generic / LLM / custom span context manager |
+| `DebrixSpan.record_messages(...)` | Opt-in message payloads |
+| `DebrixSpan.record_response(...)` | Opt-in model output / tokens |
+| `SpanKind`, `Attr` | Semantic convention constants |
+
+Nested calls propagate via OpenTelemetry context. On exception, spans are marked `ERROR` with `debrix.error.summary`.
+
+## Develop
+
+```bash
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+MIT

debrix-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,11 @@
+debrix/__init__.py,sha256=eLGElkRE704TGQKS-KTLKkpRUbnHue2LmSnB4lUPFXg,530
+debrix/config.py,sha256=_VlL9uqAnnORdSTrIkzv5-S0nMmjjpidt-KzLY4w_Oc,3904
+debrix/payloads.py,sha256=RLS3XYrWkaT0JNQOFoeQpOtrEElo-f5XSz743pkT9EA,8555
+debrix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+debrix/semconv.py,sha256=xkYC5pNY8VgIy5rXRGca1By6WocfyEX1ttp0x2U_3xk,2431
+debrix/span.py,sha256=-SVtJ_xiIZGf4Bmr7SusFOSFhSBvKwr9WMahdBoMZXs,8591
+debrix/tracing.py,sha256=upbT3M-t2a_oIvqR964hrvmhHV7-zMsmh-1Awn4cVjc,8822
+debrix-0.1.0a1.dist-info/METADATA,sha256=4rQ-CgF_90gGp1CnPZpKKsgDsGZ6ythD_qL4KCgJBF4,3511
+debrix-0.1.0a1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+debrix-0.1.0a1.dist-info/licenses/LICENSE,sha256=ZDmp4oN9DA2Fh_mlOGtV7_eNSg53fjowQr_t52-QU54,1063
+debrix-0.1.0a1.dist-info/RECORD,,

debrix-0.1.0a1.dist-info/WHEEL

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

debrix-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Debrix
+
+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.