catalyst-tracing 0.0.1__tar.gz

catalyst_tracing-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.uv/
+dist/
+build/
+*.egg-info/

catalyst_tracing-0.0.1/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: catalyst-tracing
+Version: 0.0.1
+Summary: Catalyst tracing SDK for Python. OpenInference-shaped instrumentation for openai, anthropic, langchain, langgraph, langsmith, openai-agents, claude-agent-sdk, and pydantic-ai.
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-api>=1.28.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-common>=1.28.0
+Requires-Dist: opentelemetry-sdk>=1.28.0
+Requires-Dist: protobuf>=5.0.0
+Requires-Dist: requests>=2.32.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.0.1; extra == 'claude-agent-sdk'
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.3.0; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.6.0; extra == 'langgraph'
+Provides-Extra: langsmith
+Requires-Dist: langsmith>=0.3.15; extra == 'langsmith'
+Provides-Extra: openai
+Requires-Dist: openai>=1.54.0; extra == 'openai'
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.0.5; extra == 'openai-agents'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai>=0.0.50; extra == 'pydantic-ai'

catalyst_tracing-0.0.1/README.md

@@ -0,0 +1,201 @@
+# `catalyst-tracing` (Python)
+
+First-party tracing for LLM apps on CPython 3.11+.
+OpenInference-shaped spans, OTLP/JSON export to a catalyst ingest, no
+`openinference-instrumentation-*` runtime dependencies.
+
+## Quick start
+
+```python
+from catalyst_tracing import setup
+from openai import OpenAI
+
+tracing = setup()
+
+client = OpenAI(api_key=...)
+client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "hello"}],
+)
+
+tracing.shutdown()
+```
+
+A single `OpenAI Chat Completions` span lands at your catalyst ingest
+with the full OpenInference attribute set.
+
+## Install with extras
+
+```bash
+pip install 'catalyst-tracing[openai]'
+pip install 'catalyst-tracing[openai,anthropic]'
+pip install 'catalyst-tracing[langchain]'
+pip install 'catalyst-tracing[langgraph]'
+pip install 'catalyst-tracing[langsmith]'
+pip install 'catalyst-tracing[claude-agent-sdk]'
+pip install 'catalyst-tracing[pydantic-ai]'
+```
+
+The extras pull in the upstream LLM SDKs themselves. The
+instrumentation runtime ships with the base package — no additional
+deps required for tracing.
+
+## Supported SDKs
+
+| SDK | Patches |
+|---|---|
+| `openai` | `Completions.create` / `AsyncCompletions.create` and `Responses.create` / `AsyncResponses.create` |
+| `anthropic` | `Messages.create` / `AsyncMessages.create` |
+| `langchain` | Hooks `BaseCallbackManager.__init__` so every callback manager picks up our handler |
+| `langgraph` | Uses the LangChain callback manager and preserves graph/node parent-child spans |
+| `langsmith` | Bridges LangSmith OTel tracing into the Catalyst provider for `traceable` and LangSmith framework integrations |
+| `openai-agents` | The agents SDK calls `openai` under the hood — install both extras and you're covered |
+| `claude-agent-sdk` | Patches `claude_agent_sdk.query.query` AND the package-level `claude_agent_sdk.query` snapshot, so top-level `from claude_agent_sdk import query` works |
+| `pydantic-ai` | Native first-party OTel — we just call `Agent.instrument_all()` for you |
+
+## Per-SDK entry-point imports
+
+If you only need one or two SDKs, import per-SDK to keep the import
+graph small and skip the multi-module orchestration in `setup()`:
+
+```python
+from catalyst_tracing import setup
+from catalyst_tracing.openai import install_openai
+
+tracing = setup()
+install_openai(tracing.provider)
+```
+
+Available entry points:
+
+| Import | Exports | Use when |
+|---|---|---|
+| `catalyst_tracing` | `setup`, `agent_span`, `Attr`, `SpanKindValues`, error types | You want everything from one import. |
+| `catalyst_tracing.openai` | `install_openai` | Only OpenAI. |
+| `catalyst_tracing.anthropic` | `install_anthropic` | Only Anthropic. |
+| `catalyst_tracing.langchain` | `install_langchain` | Only LangChain. |
+| `catalyst_tracing.langgraph` | `install_langgraph` | Only LangGraph. |
+| `catalyst_tracing.langsmith` | `install_langsmith` | Bridge existing LangSmith OTel tracing into Catalyst. |
+| `catalyst_tracing.openai_agents` | `install_openai_agents` | Only `agents` (OpenAI's). |
+| `catalyst_tracing.claude_agent_sdk` | `install_claude_agent_sdk` | Only the Claude Agent SDK. |
+| `catalyst_tracing.pydantic_ai` | `install_pydantic_ai` | Only Pydantic-AI. |
+
+Every `install_*` helper takes a `TracerProvider` (the standard OTel
+type, what `tracing.provider` is). It returns an `InstrumentResult`
+on success, raises `InvalidTracerProviderError` on misuse.
+
+## Internal source layout
+
+The package separates public entry points from installation glue and
+low-level patchers:
+
+| Path | Purpose |
+|---|---|
+| `src/catalyst_tracing/*.py` | Public package and per-SDK entry-point modules. Keep these thin and stable. |
+| `src/catalyst_tracing/installers/` | `setup()` integration adapters. These validate optional SDK modules, call the patchers, and report install results. |
+| `src/catalyst_tracing/instrumentation/` | Low-level SDK patchers and shared extraction helpers. This is where OpenInference attribute extraction belongs. |
+
+## Errors
+
+The package raises typed errors for misuse so you can catch and
+branch programmatically:
+
+```python
+from catalyst_tracing import (
+    CatalystTracingError, InvalidTracerProviderError,
+)
+from catalyst_tracing.openai import install_openai
+
+try:
+    install_openai(provider)
+except InvalidTracerProviderError as err:
+    # err.code == "ERR_INVALID_TRACER_PROVIDER"
+    # err.integration == "openai"
+    # str(err) carries a "Hint:" line
+    raise
+except CatalystTracingError:
+    raise  # base class — catch this for "did the package raise?"
+```
+
+Each `install_*` returns a frozen `InstrumentResult` dataclass:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `name` | `str` | Integration name. |
+| `installed` | `bool` | Whether the patch took. |
+| `code` | `Literal["INSTALLED", "SDK_NOT_INSTALLED", "SDK_VERSION_INCOMPATIBLE"]` | Stable code for branching. |
+| `reason` | `str | None` | Human-readable reason; `None` on success. |
+
+## Manual spans
+
+For CLI subprocess wrappers and custom logic, `agent_span` is a
+context manager:
+
+```python
+from catalyst_tracing import agent_span, setup
+
+tracing = setup()
+
+with agent_span(tracing.tracer, name="ClaudeCode", system="anthropic") as span:
+    span.set_input(prompt)
+    answer = run_cli(prompt)
+    span.set_output(answer)
+    span.record_tokens(prompt=120, completion=40)
+
+tracing.shutdown()
+```
+
+The body runs inside the span's active OTel context, so any child
+spans created by instrumented LLM SDKs auto-parent under it.
+
+## Configuration
+
+| Option (programmatic) | Env var | Default |
+|---|---|---|
+| `endpoint` | `CATALYST_OTLP_ENDPOINT` (legacy `OTLP_ENDPOINT`) | `http://localhost:8799` |
+| `token` | `CATALYST_OTLP_TOKEN` (legacy `OTLP_INGEST_TOKEN`) | — |
+| `service_name` | `CATALYST_SERVICE_NAME` (legacy `SERVICE_NAME`) | `catalyst-app-${random8}` |
+| `service_version` | `CATALYST_SERVICE_VERSION` | `0.0.1` |
+| `debug` | `CATALYST_DEBUG` (`1`/`true`/`yes`) | `false` |
+| `batching` | — | `"batch"` |
+
+## Wire format
+
+Every span carries the OpenInference attribute set —
+`openinference.span.kind`, `input.value`, `output.value`,
+`llm.input_messages.{i}.message.{role,content}`,
+`llm.output_messages.{i}.message.{role,content}`,
+`llm.invocation_parameters`, `llm.model_name`, `llm.token_count.*`,
+`llm.finish_reason`, `gen_ai.system`. OI-aware viewers can render our
+spans without configuration.
+
+The constants live in `Attr` and `SpanKindValues`:
+
+```python
+from catalyst_tracing import Attr, SpanKindValues
+
+span.set_attribute(Attr.SPAN_KIND, SpanKindValues.LLM.value)
+span.set_attribute(Attr.MODEL_NAME, "gpt-4o-mini")
+```
+
+## Testing
+
+```bash
+# From the repository root, run the full cross-language gate.
+task check
+
+# From this package, run the Python package tests directly.
+uv run pytest
+```
+
+Integration tests exercise the real openai/anthropic/langchain/langgraph/langsmith SDKs
+against `respx`-mocked httpx (no API keys required). The
+`claude-agent-sdk` integration test imports the real message types
+and asserts our wrapper handles them correctly.
+
+## See also
+
+- `docs/internal/architecture/catalyst-tracing-package-plan.md` — design doc
+- `docs/internal/architecture/claude-agent-sdk-frozen-namespace.md` — TS-specific note
+  on why we ship `wrapClaudeAgentSdkQuery` instead of mutating the
+  ESM namespace

catalyst_tracing-0.0.1/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "catalyst-tracing"
+version = "0.0.1"
+description = "Catalyst tracing SDK for Python. OpenInference-shaped instrumentation for openai, anthropic, langchain, langgraph, langsmith, openai-agents, claude-agent-sdk, and pydantic-ai."
+requires-python = ">=3.11"
+dependencies = [
+    "opentelemetry-api>=1.28.0",
+    "opentelemetry-sdk>=1.28.0",
+    "opentelemetry-exporter-otlp-proto-common>=1.28.0",
+    "protobuf>=5.0.0",
+    "requests>=2.32.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.54.0"]
+anthropic = ["anthropic>=0.30.0"]
+langchain = ["langchain>=0.3.0"]
+langgraph = ["langgraph>=0.6.0"]
+langsmith = ["langsmith>=0.3.15"]
+openai-agents = ["openai-agents>=0.0.5"]
+claude-agent-sdk = ["claude-agent-sdk>=0.0.1"]
+pydantic-ai = ["pydantic-ai>=0.0.50"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "respx>=0.21.0",
+    # Real SDKs imported by the integration tests. Optional in
+    # production (declared via [project.optional-dependencies]); we
+    # add them here so the test suite can exercise the real APIs
+    # against mocked HTTP backends.
+    "openai>=1.54.0",
+    "anthropic>=0.30.0",
+    "langchain>=0.3.0",
+    "langchain-core>=0.3.0",
+    "langgraph>=0.6.0",
+    "langsmith>=0.3.15",
+    "claude-agent-sdk>=0.1.0",
+    "pydantic-ai>=0.0.50",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/catalyst_tracing"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "/.venv",
+    "/tests",
+    "/uv.lock",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

catalyst_tracing-0.0.1/src/catalyst_tracing/__init__.py

@@ -0,0 +1,94 @@
+"""``catalyst_tracing`` — first-party tracing for LLM apps.
+
+Drop-in OpenInference-shaped instrumentation for the SDKs your app
+uses (openai, anthropic, langchain, langgraph, langsmith,
+openai-agents, claude-agent-sdk, pydantic-ai), plus a small ergonomic helper layer for cases where
+you need to author spans by hand.
+
+Quick start::
+
+    from catalyst_tracing import setup
+    from openai import OpenAI
+
+    tracing = setup()
+    client = OpenAI(api_key=...)
+    client.chat.completions.create(model=..., messages=...)
+    tracing.shutdown()
+
+What this package owns
+----------------------
+
+- **OTLP plumbing** — endpoint, token, service-name resource, batch
+  vs. simple processor selection, env-var resolution with sensible
+  defaults including legacy ``OTLP_*`` fallback.
+- **First-party OpenInference instrumentation** for openai, anthropic,
+  langchain, langgraph, openai-agents, claude-agent-sdk, plus bridges
+  for langsmith and pydantic-ai's native OTel. No
+  ``openinference-instrumentation-*`` runtime dependency.
+- **Helpers**: :func:`agent_span` for manual AGENT spans;
+  :class:`Attr` and :class:`SpanKindValues` for the OI semantic-
+  convention constants you'd want when authoring custom spans.
+
+What this package doesn't own
+-----------------------------
+
+- The SDKs themselves. They're optional extras — pull in only the
+  ones you use::
+
+      pip install 'catalyst-tracing[openai,anthropic]'
+
+- Shipping spans somewhere other than OTLP/HTTP/JSON. If you need a
+  different transport, build your own exporter and add it to
+  ``tracing.provider``.
+
+Public API
+----------
+
+* :func:`setup` — bootstrap tracing, returns a
+  :class:`CatalystTracing` handle.
+* :func:`agent_span` — context manager that wraps work in an
+  OI-shaped AGENT span.
+* :class:`Attr`, :class:`SpanKindValues` — wire-format constants
+  shared across instrumentation and consumer-authored spans.
+"""
+
+from .agent_span import AgentSpanHandle, agent_span
+from .errors import (
+    CatalystTracingError,
+    CatalystTracingErrorCode,
+    CatalystTracingErrorCodes,
+    InvalidSdkInputError,
+    InvalidTracerProviderError,
+)
+from .semconv import Attr, MessageRole, OpenInferenceAttribute, SpanKindValues
+from .setup import CatalystTracing, InstrumentResult, setup
+
+__version__ = "0.0.1"
+PACKAGE_NAME = "catalyst-tracing"
+IMPORT_NAME = "catalyst_tracing"
+COMPANY_NAME = "Inference"
+PLATFORM_NAME = "Catalyst"
+PRODUCT_NAME = "Catalyst by Inference.net"
+
+__all__ = [
+    "AgentSpanHandle",
+    "Attr",
+    "CatalystTracing",
+    "CatalystTracingError",
+    "CatalystTracingErrorCode",
+    "CatalystTracingErrorCodes",
+    "COMPANY_NAME",
+    "IMPORT_NAME",
+    "InstrumentResult",
+    "InvalidSdkInputError",
+    "InvalidTracerProviderError",
+    "MessageRole",
+    "OpenInferenceAttribute",
+    "PACKAGE_NAME",
+    "PLATFORM_NAME",
+    "PRODUCT_NAME",
+    "SpanKindValues",
+    "__version__",
+    "agent_span",
+    "setup",
+]

catalyst_tracing-0.0.1/src/catalyst_tracing/agent_span.py

@@ -0,0 +1,199 @@
+""":func:`agent_span` — context manager that wraps work in an
+OpenInference-flavored AGENT span.
+
+Use this when you have a chunk of "agent work" — a CLI subprocess
+call, a multi-step Pydantic AI run, the outer wrapper around an
+``agents-sdk`` ``Runner.run()`` — and you want it to show up in
+the trace viewer as a single AGENT-kind row with input/output and
+optional token counts.
+
+The context manager:
+
+* Sets ``openinference.span.kind=AGENT``, ``agent.name``,
+  ``gen_ai.system`` automatically.
+* Runs the body inside the span's active OTel context, so child
+  spans created by instrumented LLM SDKs auto-parent to this
+  AGENT span. (That's how a full trace tree forms.)
+* Ends with ``OK`` on success, records the exception and ends with
+  ``ERROR`` on failure (re-raising so the caller's error handling
+  is unaffected).
+
+Example
+-------
+Wrapping a CLI subprocess::
+
+    from catalyst_tracing import agent_span, setup
+
+    tracing = setup()
+    with agent_span(tracing.tracer, name="ClaudeCode", system="anthropic") as span:
+        span.set_input(prompt)
+        answer = run_cli(prompt)
+        span.set_output(answer)
+        span.record_tokens(prompt=120, completion=40)
+
+Wrapping an `openai-agents` runner so its LLM-call spans nest
+under the AGENT span::
+
+    from catalyst_tracing import agent_span, setup
+    from agents import Agent, Runner
+
+    tracing = setup()
+    agent = Agent(name="SupportAgent", instructions=..., tools=[...])
+
+    with agent_span(tracing.tracer, name="SupportAgent", system="openai") as span:
+        span.set_input(user_message)
+        result = await Runner.run(agent, input=user_message)
+        span.set_output(str(result.final_output))
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode, Tracer
+
+from .semconv import Attr, SpanKindValues
+
+
+@dataclass
+class AgentSpanHandle:
+    """The handle yielded by :func:`agent_span`.
+
+    Provides type-safe helpers for the OI attribute set the agent
+    span should carry, plus a ``span`` escape hatch for callers
+    that need the underlying OTel span (e.g. to add custom
+    attributes outside the OI vocabulary).
+    """
+
+    #: The underlying OTel span — escape hatch for advanced use.
+    span: Span
+
+    def set_input(self, value: Any) -> None:
+        """Record the agent's input.
+
+        Strings are stored as-is on ``input.value``. Non-strings
+        are JSON-stringified.
+        """
+        self.span.set_attribute(
+            Attr.INPUT_VALUE,
+            value if isinstance(value, str) else json.dumps(value),
+        )
+
+    def set_output(self, value: Any) -> None:
+        """Record the agent's final output.
+
+        Same string-vs-JSON rule as :meth:`set_input`.
+        """
+        self.span.set_attribute(
+            Attr.OUTPUT_VALUE,
+            value if isinstance(value, str) else json.dumps(value),
+        )
+
+    def record_tokens(
+        self,
+        *,
+        prompt: int | None = None,
+        completion: int | None = None,
+        total: int | None = None,
+    ) -> None:
+        """Record token usage on the agent span.
+
+        Any of ``prompt``, ``completion``, ``total`` may be omitted;
+        only the provided fields are written. Use this when you have
+        aggregated counts across multiple LLM calls inside the agent
+        loop — per-call counts get captured by the LLM-level
+        instrumentation separately.
+        """
+        if prompt is not None:
+            self.span.set_attribute(Attr.TOKEN_COUNT_PROMPT, prompt)
+        if completion is not None:
+            self.span.set_attribute(Attr.TOKEN_COUNT_COMPLETION, completion)
+        if total is not None:
+            self.span.set_attribute(Attr.TOKEN_COUNT_TOTAL, total)
+
+    def set_model(self, model: str) -> None:
+        """Record the model name (becomes ``llm.model_name``)."""
+        self.span.set_attribute(Attr.MODEL_NAME, model)
+
+
+@contextmanager
+def agent_span(
+    tracer: Tracer,
+    *,
+    name: str,
+    system: str | None = None,
+    span_kind: SpanKindValues | str = SpanKindValues.AGENT,
+    otel_kind: SpanKind = SpanKind.INTERNAL,
+    span_name: str | None = None,
+) -> Iterator[AgentSpanHandle]:
+    """Wrap a chunk of agent work in an OI-shaped AGENT span.
+
+    Parameters
+    ----------
+    tracer : Tracer
+        OpenTelemetry tracer to author the span from. Use the one
+        on :class:`CatalystTracing.tracer`.
+    name : str
+        Logical agent name — e.g. ``"ClaudeCode"``,
+        ``"WeatherAgent"``. Becomes the ``agent.name`` attribute
+        and the prefix of the default span name.
+    system : str, optional
+        Identifier of the LLM provider this agent runs on, e.g.
+        ``"openai"`` or ``"anthropic"``. Becomes the
+        ``gen_ai.system`` attribute. Optional — omit if the agent
+        is provider-agnostic.
+    span_kind : SpanKindValues or str, default AGENT
+        OpenInference span kind. Pass another
+        :class:`SpanKindValues` (e.g. ``CHAIN``) when this helper
+        is used outside a strictly agent context.
+    otel_kind : SpanKind, default INTERNAL
+        OTel-level span kind. ``INTERNAL`` because the work itself
+        is internal to this process; the LLM-call children get
+        their own ``CLIENT`` kind from the per-SDK patchers.
+    span_name : str, optional
+        Override the auto-generated span name (``f"{name}.run"``).
+        Useful when "run" doesn't fit — e.g. our examples use
+        ``"claude-code.invocation"`` for one-shot CLI calls.
+
+    Yields
+    ------
+    AgentSpanHandle
+        Helpers to set input/output/tokens/model on the span.
+
+    Notes
+    -----
+    The span is closed automatically when the ``with`` block
+    exits. On unhandled exceptions the span ends with ``ERROR``
+    status and an ``exception`` event recording the traceback,
+    then the exception re-raises so caller error handling is
+    unaffected.
+    """
+    resolved_span_name = span_name or f"{name}.run"
+    resolved_kind_value = (
+        span_kind.value if isinstance(span_kind, SpanKindValues) else span_kind
+    )
+
+    attributes: dict[str, str] = {
+        Attr.SPAN_KIND: resolved_kind_value,
+        Attr.AGENT_NAME: name,
+    }
+    if system is not None:
+        attributes[Attr.SYSTEM] = system
+
+    with tracer.start_as_current_span(
+        resolved_span_name,
+        kind=otel_kind,
+        attributes=attributes,
+    ) as span:
+        handle = AgentSpanHandle(span=span)
+        try:
+            yield handle
+            span.set_status(Status(StatusCode.OK))
+        except Exception as err:
+            span.record_exception(err)
+            span.set_status(Status(StatusCode.ERROR, str(err)))
+            raise

catalyst_tracing-0.0.1/src/catalyst_tracing/anthropic.py

@@ -0,0 +1,17 @@
+"""``catalyst_tracing.anthropic`` — granular entry-point import for the
+Anthropic integration.
+
+Example::
+
+    from catalyst_tracing import setup
+    from catalyst_tracing.anthropic import install_anthropic
+
+    tracing = setup()
+    install_anthropic(tracing.provider)
+"""
+
+from __future__ import annotations
+
+from .installers.anthropic import install_anthropic
+
+__all__ = ["install_anthropic"]

catalyst_tracing-0.0.1/src/catalyst_tracing/claude_agent_sdk.py

@@ -0,0 +1,21 @@
+"""``catalyst_tracing.claude_agent_sdk`` — granular entry-point import
+for the Claude Agent SDK integration.
+
+Example::
+
+    from catalyst_tracing import setup
+    from catalyst_tracing.claude_agent_sdk import install_claude_agent_sdk
+
+    tracing = setup()
+    install_claude_agent_sdk(tracing.provider)
+
+    # `from claude_agent_sdk import query` continues to read the
+    # wrapped function. The patch covers both the package-level and
+    # submodule bindings.
+"""
+
+from __future__ import annotations
+
+from .installers.claude_agent_sdk import install_claude_agent_sdk
+
+__all__ = ["install_claude_agent_sdk"]