opexia-trace 0.1.0a1__tar.gz

opexia_trace-0.1.0a1/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: opexia-trace
+Version: 0.1.0a1
+Summary: Pluggable reasoning-trace observability for LLM applications
+Author: OpexIA
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/star-56/deep_reasoning/tree/main/opexia_trace
+Project-URL: Repository, https://github.com/star-56/deep_reasoning
+Project-URL: Issues, https://github.com/star-56/deep_reasoning/issues
+Keywords: observability,opentelemetry,llm,reasoning,tracing,otel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.24
+Requires-Dist: opentelemetry-sdk>=1.24
+Requires-Dist: opentelemetry-exporter-otlp>=1.24
+Requires-Dist: pydantic>=2.6
+Requires-Dist: tiktoken>=0.6
+Requires-Dist: httpx>=0.27
+Provides-Extra: openllmetry
+Requires-Dist: traceloop-sdk>=0.18; extra == "openllmetry"
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == "litellm"
+Provides-Extra: adapters-microsoft
+Provides-Extra: adapters-langchain
+Requires-Dist: langchain-core>=0.2; extra == "adapters-langchain"
+
+# opexia-trace
+
+Pluggable reasoning-trace observability for LLM applications.
+
+`opexia-trace` is the client SDK for the **OpexIA Observability Layer**. It
+captures *reasoning-altitude* spans — the decisions an agent made, the sources
+it used, what each step cost, and the inputs to a reliability score — and ships
+them to an OpexIA backend over OTLP. Unlike raw LLM logging, the unit of
+observation is the *reasoning step*, not the HTTP call.
+
+## Install
+
+```bash
+pip install opexia-trace
+```
+
+## Quickstart
+
+Call `init()` once at process startup:
+
+```python
+from opexia.trace import init
+
+init(
+    org_id="pwc",
+    workspace_id="chatpwc",
+    project_id="due-diligence",
+    backend_url="https://opexia.internal.example.com",
+    api_key="opx_live_...",          # your workspace API key
+)
+```
+
+With `auto_instrument=True` (the default), every LLM call made through
+litellm / anthropic / openai is now traced. No other code changes required.
+
+## The three integration patterns
+
+### Pattern A — Auto-instrument (zero code changes)
+
+`init(auto_instrument=True)` monkey-patches the litellm / anthropic / openai
+client methods at startup. Every completion call emits a `gen_ai.*` span
+carrying the model, token usage, and computed USD cost. This is the default;
+you get it just by calling `init()`.
+
+### Pattern B — the `@observe` decorator
+
+Wrap any function — sync or async — to emit a reasoning span for it:
+
+```python
+from opexia.trace import observe
+
+@observe(reasoning_role="decomposer", node_type="decomposer", name="plan.decompose")
+async def decompose(query: str) -> list[str]:
+    ...
+```
+
+Nested `@observe` calls auto-parent via OpenTelemetry context — a decorated
+function called inside another decorated function becomes its child span, so
+the reasoning tree falls out of normal call structure.
+
+### Pattern C — the `ReasoningTrace` context manager
+
+For explicit, structured traces — when you want to record decisions, sources,
+and costs by hand:
+
+```python
+from opexia.trace import ReasoningTrace
+
+with ReasoningTrace(name="answer.query", reasoning_role="synthesis") as trace:
+    trace.record_cost(model="claude-opus-4-6", input_tokens=1200, output_tokens=400)
+    trace.record_sources(used=[...], consulted=[...], dropped=[...])
+    trace.record_decision(selected="opt_a", rules_fired=[...], scores={...})
+    with trace.subnode(name="retrieve", node_type="retriever") as node:
+        node.record_sources(...)
+```
+
+### Framework adapters
+
+For agent frameworks, one line instruments a whole crew:
+
+```python
+from opexia.trace.adapters.microsoft import instrument_microsoft_agents
+instrument_microsoft_agents(crew)        # Microsoft Agent Framework
+
+from opexia.trace.adapters.reasonix import instrument_reasonix
+instrument_reasonix(orchestrator)        # Reasonix orchestrator
+```
+
+Adapters are duck-typed — they import nothing from the framework, so they
+never pin you to a version.
+
+## Configuration — `init()` parameters
+
+| Parameter | Default | Meaning |
+|-----------|---------|---------|
+| `org_id` / `workspace_id` / `project_id` | required | Tenancy identity stamped on every span. |
+| `backend_url` | required | The OpexIA backend base URL. |
+| `api_key` | required | Workspace API key (`opx_live_…` / `opx_test_…`). |
+| `collector_endpoint` | `http://localhost:4317` | OTLP collector endpoint. |
+| `wal_path` | `.opexia-wal/spans.jsonl` | Write-ahead-log path (see Durability). |
+| `auto_instrument` | `True` | Patch litellm/anthropic/openai at startup. |
+| `fail_open` | `False` | See "fail_open scope" in the FAQ. |
+| `sampler_rate` | `1.0` | Fraction of traces sampled. |
+
+## Durability — the write-ahead log
+
+Spans are written to a local WAL (`wal_path`) before they are exported, so a
+process crash or an unreachable collector does not lose spans — the next
+`init()` replays any WAL left by a previous run. The WAL is why a dropped span
+is treated as a *bug*, not an expected failure mode.
+
+## Troubleshooting
+
+- **No spans appear in the backend.** Check `backend_url` / `collector_endpoint`
+  reachability and that `api_key` is a live (not revoked) workspace key.
+- **`init() has not been called`.** A `@observe` / `ReasoningTrace` ran before
+  `init()`. Call `init()` once at process startup, before any traced code.
+- **Auto-instrument patched 0 clients.** None of litellm/anthropic/openai are
+  importable in the process — Pattern A has nothing to patch. Use Pattern B/C.
+
+## FAQ
+
+**Does `opexia-trace` import my agent framework?** No. The adapters are
+duck-typed and import nothing from the framework or from the OpexIA backend.
+
+**What does `fail_open` actually cover?** `fail_open=True` only suppresses a
+failure of *auto-instrument registration* during `init()` — it does NOT wrap
+the whole `init()` body. A bad `collector_endpoint` or a WAL-path I/O error
+still raises. Treat `fail_open` as "don't let auto-instrument break my
+startup," not "make `init()` never raise." (Tracked as deferred note B2-N5;
+a future release may widen the scope.)
+
+**Can I emit spans during process shutdown?** No. Do not start new spans after
+your shutdown hook runs — a span started concurrently with the exporter
+shutting down can be dropped (this race exists in upstream OpenTelemetry's
+`BatchSpanProcessor` too). Finish traced work before tearing the process down.
+(Tracked as deferred note B2-N7.)
+
+**Is the SDK safe in production?** Yes — span export is buffered and
+WAL-backed, and a traced function never fails because tracing failed:
+attribute-extraction errors are caught and recorded on the span, and the
+original return value passes through untouched.

opexia_trace-0.1.0a1/README.md

@@ -0,0 +1,142 @@
+# opexia-trace
+
+Pluggable reasoning-trace observability for LLM applications.
+
+`opexia-trace` is the client SDK for the **OpexIA Observability Layer**. It
+captures *reasoning-altitude* spans — the decisions an agent made, the sources
+it used, what each step cost, and the inputs to a reliability score — and ships
+them to an OpexIA backend over OTLP. Unlike raw LLM logging, the unit of
+observation is the *reasoning step*, not the HTTP call.
+
+## Install
+
+```bash
+pip install opexia-trace
+```
+
+## Quickstart
+
+Call `init()` once at process startup:
+
+```python
+from opexia.trace import init
+
+init(
+    org_id="pwc",
+    workspace_id="chatpwc",
+    project_id="due-diligence",
+    backend_url="https://opexia.internal.example.com",
+    api_key="opx_live_...",          # your workspace API key
+)
+```
+
+With `auto_instrument=True` (the default), every LLM call made through
+litellm / anthropic / openai is now traced. No other code changes required.
+
+## The three integration patterns
+
+### Pattern A — Auto-instrument (zero code changes)
+
+`init(auto_instrument=True)` monkey-patches the litellm / anthropic / openai
+client methods at startup. Every completion call emits a `gen_ai.*` span
+carrying the model, token usage, and computed USD cost. This is the default;
+you get it just by calling `init()`.
+
+### Pattern B — the `@observe` decorator
+
+Wrap any function — sync or async — to emit a reasoning span for it:
+
+```python
+from opexia.trace import observe
+
+@observe(reasoning_role="decomposer", node_type="decomposer", name="plan.decompose")
+async def decompose(query: str) -> list[str]:
+    ...
+```
+
+Nested `@observe` calls auto-parent via OpenTelemetry context — a decorated
+function called inside another decorated function becomes its child span, so
+the reasoning tree falls out of normal call structure.
+
+### Pattern C — the `ReasoningTrace` context manager
+
+For explicit, structured traces — when you want to record decisions, sources,
+and costs by hand:
+
+```python
+from opexia.trace import ReasoningTrace
+
+with ReasoningTrace(name="answer.query", reasoning_role="synthesis") as trace:
+    trace.record_cost(model="claude-opus-4-6", input_tokens=1200, output_tokens=400)
+    trace.record_sources(used=[...], consulted=[...], dropped=[...])
+    trace.record_decision(selected="opt_a", rules_fired=[...], scores={...})
+    with trace.subnode(name="retrieve", node_type="retriever") as node:
+        node.record_sources(...)
+```
+
+### Framework adapters
+
+For agent frameworks, one line instruments a whole crew:
+
+```python
+from opexia.trace.adapters.microsoft import instrument_microsoft_agents
+instrument_microsoft_agents(crew)        # Microsoft Agent Framework
+
+from opexia.trace.adapters.reasonix import instrument_reasonix
+instrument_reasonix(orchestrator)        # Reasonix orchestrator
+```
+
+Adapters are duck-typed — they import nothing from the framework, so they
+never pin you to a version.
+
+## Configuration — `init()` parameters
+
+| Parameter | Default | Meaning |
+|-----------|---------|---------|
+| `org_id` / `workspace_id` / `project_id` | required | Tenancy identity stamped on every span. |
+| `backend_url` | required | The OpexIA backend base URL. |
+| `api_key` | required | Workspace API key (`opx_live_…` / `opx_test_…`). |
+| `collector_endpoint` | `http://localhost:4317` | OTLP collector endpoint. |
+| `wal_path` | `.opexia-wal/spans.jsonl` | Write-ahead-log path (see Durability). |
+| `auto_instrument` | `True` | Patch litellm/anthropic/openai at startup. |
+| `fail_open` | `False` | See "fail_open scope" in the FAQ. |
+| `sampler_rate` | `1.0` | Fraction of traces sampled. |
+
+## Durability — the write-ahead log
+
+Spans are written to a local WAL (`wal_path`) before they are exported, so a
+process crash or an unreachable collector does not lose spans — the next
+`init()` replays any WAL left by a previous run. The WAL is why a dropped span
+is treated as a *bug*, not an expected failure mode.
+
+## Troubleshooting
+
+- **No spans appear in the backend.** Check `backend_url` / `collector_endpoint`
+  reachability and that `api_key` is a live (not revoked) workspace key.
+- **`init() has not been called`.** A `@observe` / `ReasoningTrace` ran before
+  `init()`. Call `init()` once at process startup, before any traced code.
+- **Auto-instrument patched 0 clients.** None of litellm/anthropic/openai are
+  importable in the process — Pattern A has nothing to patch. Use Pattern B/C.
+
+## FAQ
+
+**Does `opexia-trace` import my agent framework?** No. The adapters are
+duck-typed and import nothing from the framework or from the OpexIA backend.
+
+**What does `fail_open` actually cover?** `fail_open=True` only suppresses a
+failure of *auto-instrument registration* during `init()` — it does NOT wrap
+the whole `init()` body. A bad `collector_endpoint` or a WAL-path I/O error
+still raises. Treat `fail_open` as "don't let auto-instrument break my
+startup," not "make `init()` never raise." (Tracked as deferred note B2-N5;
+a future release may widen the scope.)
+
+**Can I emit spans during process shutdown?** No. Do not start new spans after
+your shutdown hook runs — a span started concurrently with the exporter
+shutting down can be dropped (this race exists in upstream OpenTelemetry's
+`BatchSpanProcessor` too). Finish traced work before tearing the process down.
+(Tracked as deferred note B2-N7.)
+
+**Is the SDK safe in production?** Yes — span export is buffered and
+WAL-backed, and a traced function never fails because tracing failed:
+attribute-extraction errors are caught and recorded on the span, and the
+original return value passes through untouched.

opexia_trace-0.1.0a1/opexia/trace/__init__.py

@@ -0,0 +1,112 @@
+"""opexia-trace — pluggable reasoning-trace observability."""
+from __future__ import annotations
+from opentelemetry import trace as ot_trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opexia.trace.exporter import OpexiaSpanExporter
+from opexia.trace._internal.queue import (
+    DurableBatchSpanProcessor,
+    replay_wal_if_exists,
+)
+from opexia.trace._internal.config import OpexiaConfig, set_config, get_config
+from opexia.trace.schemas import (
+    OpexiaSpanAttributes, DecisionBasis, ReliabilitySignal,
+    SourceAssessment, CostBreakdown,
+)
+from opexia.trace.decorator import observe
+from opexia.trace.context_manager import ReasoningTrace
+from opexia.trace.cost import estimate_cost_usd, pricing_version
+
+
+def init(
+    *, org_id: str, workspace_id: str, project_id: str,
+    backend_url: str, api_key: str,
+    collector_endpoint: str = "http://localhost:4317",
+    wal_path: str = ".opexia-wal/spans.jsonl",
+    auto_instrument: bool = True, fail_open: bool = False,
+    sampler_rate: float = 1.0,
+) -> None:
+    cfg = OpexiaConfig(
+        org_id=org_id, workspace_id=workspace_id, project_id=project_id,
+        backend_url=backend_url, api_key=api_key,
+        collector_endpoint=collector_endpoint, wal_path=wal_path,
+        auto_instrument=auto_instrument, fail_open=fail_open,
+        sampler_rate=sampler_rate,
+    )
+    set_config(cfg)
+
+    # Fetch the workspace capture_text opt-in from the backend (fail-closed).
+    try:
+        import httpx
+        _r = httpx.get(
+            f"{cfg.backend_url.rstrip('/')}/v1/workspaces/{cfg.workspace_id}/sdk-config",
+            headers={"x-opexia-api-key": cfg.api_key}, timeout=5.0)
+        if _r.status_code == 200:
+            cfg.capture_text = bool(_r.json().get("capture_text", False))
+    except Exception:
+        cfg.capture_text = False
+
+    # B2-N5: fail_open wraps the WHOLE init body below — exporter construction,
+    # provider setup, WAL replay, and auto-instrument — not just auto-instrument
+    # registration. With fail_open=True a bad collector endpoint, a WAL I/O
+    # error, or an exporter-constructor failure degrades gracefully instead of
+    # taking down customer startup. set_config() above runs FIRST and outside
+    # this guard, so get_config() still works in the degraded state.
+    try:
+        resource = Resource.create({
+            "service.name": f"opexia.{org_id}.{workspace_id}.{project_id}",
+            "opexia.org_id": org_id,
+            "opexia.workspace_id": workspace_id,
+            "opexia.project_id": project_id,
+        })
+        provider = TracerProvider(resource=resource)
+        exporter = OpexiaSpanExporter(
+            endpoint=collector_endpoint,
+            headers={"x-opexia-api-key": api_key},
+            insecure=collector_endpoint.startswith("http://"),
+        )
+        processor = DurableBatchSpanProcessor(exporter=exporter, wal_path=wal_path)
+        provider.add_span_processor(processor)
+        ot_trace.set_tracer_provider(provider)
+
+        # Replay any WAL from a previous crashed process
+        replayed = replay_wal_if_exists(wal_path, exporter)
+        if replayed:
+            import logging
+            logging.getLogger(__name__).warning(
+                "opexia.trace: replayed %d WAL entries from previous run", replayed
+            )
+
+        if auto_instrument:
+            # ImportError on the auto_instrument MODULE is benign (the feature
+            # is simply unavailable) — log debug and continue. A runtime error
+            # from register_auto_instrument() itself propagates to the
+            # fail_open guard below (the B5-N5 distinction).
+            try:
+                from opexia.trace.auto_instrument import register_auto_instrument
+            except ImportError:
+                import logging
+                logging.getLogger(__name__).debug(
+                    "opexia.trace.auto_instrument module not available"
+                )
+            else:
+                count = register_auto_instrument()
+                import logging
+                logging.getLogger(__name__).info(
+                    "opexia.trace: auto-instrumented %d LLM client methods", count
+                )
+    except Exception:
+        import logging
+        logging.getLogger(__name__).exception("opexia.trace: init failed")
+        if not fail_open:
+            raise
+
+
+__all__ = [
+    "init", "get_config",
+    "OpexiaSpanExporter",
+    "OpexiaSpanAttributes", "DecisionBasis", "ReliabilitySignal",
+    "SourceAssessment", "CostBreakdown",
+    "observe", "ReasoningTrace",
+    "estimate_cost_usd", "pricing_version",
+]

opexia_trace-0.1.0a1/opexia/trace/_internal/config.py

@@ -0,0 +1,33 @@
+# opexia_trace/opexia/trace/_internal/config.py
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class OpexiaConfig:
+    org_id: str
+    workspace_id: str
+    project_id: str
+    backend_url: str
+    api_key: str
+    collector_endpoint: str = "http://localhost:4317"
+    wal_path: str = ".opexia-wal/spans.jsonl"
+    auto_instrument: bool = True
+    fail_open: bool = False
+    sampler_rate: float = 1.0
+    capture_text: bool = False   # set from the backend sdk-config fetch (Task 6)
+
+
+_GLOBAL: Optional[OpexiaConfig] = None
+
+
+def set_config(cfg: OpexiaConfig) -> None:
+    global _GLOBAL
+    _GLOBAL = cfg
+
+
+def get_config() -> OpexiaConfig:
+    if _GLOBAL is None:
+        raise RuntimeError("opexia.trace.init() has not been called")
+    return _GLOBAL

opexia_trace-0.1.0a1/opexia/trace/_internal/queue.py

@@ -0,0 +1,110 @@
+# opexia_trace/opexia/trace/_internal/queue.py
+"""Disk-backed durability wrapper for span export.
+
+Writes a JSON line per span to a WAL file BEFORE handing the span to the
+BatchSpanProcessor. On clean shutdown, truncates entries that exported
+successfully. On crash/restart, init() replays unfinished WAL entries
+through the exporter.
+
+Invariant (spec §5.1): the SDK never loses a span on process restart.
+"""
+from __future__ import annotations
+import os, threading, time
+from pathlib import Path
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
+
+
+class DurableBatchSpanProcessor(BatchSpanProcessor):
+    def __init__(self, exporter: SpanExporter, wal_path: str,
+                 max_queue_size: int = 2048, max_export_batch_size: int = 512,
+                 max_wal_bytes: int = 10_000_000):
+        super().__init__(
+            span_exporter=exporter,
+            max_queue_size=max_queue_size,
+            max_export_batch_size=max_export_batch_size,
+        )
+        self._wal_path = Path(wal_path)
+        self._wal_path.parent.mkdir(parents=True, exist_ok=True)
+        self._wal_lock = threading.Lock()
+        self._wal_fp = open(self._wal_path, "a", encoding="utf-8")
+        # B2-N6: disk-backed WAL size cap (~10MB default). Past the cap the WAL
+        # write is REFUSED — the span still goes to the in-memory BSP queue for
+        # export, only its crash-durability is lost — and a drop counter
+        # advances. Refuse-new beats rewrite-to-drop-oldest: the latter would
+        # rewrite the whole file under the lock on the hot path.
+        self._max_wal_bytes = max_wal_bytes
+        self._wal_bytes = self._wal_fp.tell()  # current on-disk size
+        self._wal_dropped = 0
+        self._wal_full_warned = False
+        # B2-N7: set True once shutdown() begins; on_end() gates on it under
+        # the same lock so no span is written/enqueued after shutdown started.
+        self._is_shutdown = False
+
+    def on_end(self, span: ReadableSpan) -> None:
+        # B2-N7: the WAL write AND super().on_end() (the in-memory enqueue)
+        # both run under _wal_lock. A concurrent shutdown() blocks on the lock
+        # until this completes; a span arriving once shutdown has begun sees
+        # _is_shutdown and is dropped cleanly here — never enqueued into an
+        # already-shut-down processor, and never left on a WAL line that the
+        # shutdown unlink() then deletes.
+        with self._wal_lock:
+            if self._is_shutdown:
+                return
+            line = span.to_json(indent=None) + "\n"
+            encoded_len = len(line.encode("utf-8"))
+            # B2-N6: refuse the WAL write past the size cap. The span is still
+            # exported (super().on_end below) — only crash-durability is lost.
+            if self._wal_bytes + encoded_len > self._max_wal_bytes:
+                self._wal_dropped += 1
+                if not self._wal_full_warned:
+                    import logging
+                    logging.getLogger(__name__).warning(
+                        "opexia.trace: WAL size cap (%d bytes) reached — new "
+                        "spans are still exported but no longer crash-durable "
+                        "until the WAL drains.", self._max_wal_bytes,
+                    )
+                    self._wal_full_warned = True
+            else:
+                try:
+                    self._wal_fp.write(line)
+                    self._wal_fp.flush()
+                    os.fsync(self._wal_fp.fileno())
+                    self._wal_bytes += encoded_len
+                except Exception:
+                    # WAL failure must not crash the customer process.
+                    pass
+            super().on_end(span)
+
+    def shutdown(self) -> None:
+        # B2-N7: the whole shutdown sequence runs under _wal_lock, and
+        # _is_shutdown is set FIRST. A racing on_end() either already finished
+        # (its span is in the WAL + the BSP queue) or blocks on the lock and
+        # then drops cleanly — closing the write-after-shutdown race.
+        with self._wal_lock:
+            self._is_shutdown = True
+            super().shutdown()
+            try:
+                self._wal_fp.close()
+                # On clean shutdown, drop the WAL — all spans exported.
+                self._wal_path.unlink(missing_ok=True)
+            except Exception:
+                pass
+
+
+def replay_wal_if_exists(wal_path: str, _exporter: SpanExporter) -> int:
+    """Called on init(): re-export WAL entries from a prior crash.
+    Returns the number of spans replayed.
+    """
+    p = Path(wal_path)
+    if not p.exists():
+        return 0
+    count = 0
+    # MVP: log-only replay; full OTLP serialization round-trip is a Batch 22 hardening item.
+    # For v1 we record the line count and rename the file to <wal>.replayed-<ts> so
+    # operators can manually re-emit if needed.
+    with open(p, "r", encoding="utf-8") as f:
+        for _ in f:
+            count += 1
+    p.rename(str(p) + f".replayed-{int(time.time())}")
+    return count

opexia_trace-0.1.0a1/opexia/trace/adapters/__init__.py

@@ -0,0 +1,12 @@
+"""Framework adapters for opexia-trace.
+
+Each adapter instruments one agent framework's crew/orchestrator to emit
+opexia reasoning spans, importing nothing from the framework itself (duck-typed).
+
+B16-N3: the adapters are re-exported here so callers can use the short form
+``from opexia.trace.adapters import instrument_microsoft_agents``.
+"""
+from opexia.trace.adapters.microsoft import instrument_microsoft_agents
+from opexia.trace.adapters.reasonix import instrument_reasonix
+
+__all__ = ["instrument_microsoft_agents", "instrument_reasonix"]