debrix 0.1.0a1__tar.gz

debrix-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package + test deps
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -q
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

debrix-0.1.0a1/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+uv.lock

debrix-0.1.0a1/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.

debrix-0.1.0a1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,82 @@
+# 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/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "debrix"
+version = "0.1.0a1"
+description = "Open-source instrumentation SDK for Debrix — local-first AI Agent DevTools"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Prateek Goyal", email = "gprateek015@gmail.com" }]
+keywords = ["observability", "opentelemetry", "agents", "tracing", "debrix"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+  "opentelemetry-api>=1.27.0",
+  "opentelemetry-sdk>=1.27.0",
+  "opentelemetry-exporter-otlp-proto-http>=1.27.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/goyal-prateek/debrix-sdk"
+Repository = "https://github.com/goyal-prateek/debrix-sdk"
+Issues = "https://github.com/goyal-prateek/debrix-sdk/issues"
+Documentation = "https://github.com/goyal-prateek/debrix-sdk#readme"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/debrix"]
+
+[dependency-groups]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

debrix-0.1.0a1/src/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-0.1.0a1/src/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()