catalyst-tracing 0.0.1__py3-none-any.whl

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/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/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/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"]

catalyst_tracing/constants.py

@@ -0,0 +1,122 @@
+"""Package-level constants shared across setup, installers, and patchers."""
+
+from __future__ import annotations
+
+PACKAGE_VERSION = "0.0.1"
+
+
+class DefaultConfig:
+    OTLP_ENDPOINT = "http://localhost:8799"
+    SERVICE_NAME_PREFIX = "catalyst-app"
+    SERVICE_VERSION = PACKAGE_VERSION
+
+
+class EnvVar:
+    CATALYST_OTLP_ENDPOINT = "CATALYST_OTLP_ENDPOINT"
+    LEGACY_OTLP_ENDPOINT = "OTLP_ENDPOINT"
+    CATALYST_OTLP_TOKEN = "CATALYST_OTLP_TOKEN"
+    LEGACY_OTLP_INGEST_TOKEN = "OTLP_INGEST_TOKEN"
+    CATALYST_SERVICE_NAME = "CATALYST_SERVICE_NAME"
+    LEGACY_SERVICE_NAME = "SERVICE_NAME"
+    CATALYST_SERVICE_VERSION = "CATALYST_SERVICE_VERSION"
+    CATALYST_DEBUG = "CATALYST_DEBUG"
+
+
+class MimeType:
+    JSON = "application/json"
+
+
+class HttpHeader:
+    AUTHORIZATION = "Authorization"
+    CONTENT_TYPE = "Content-Type"
+
+
+class OtlpPath:
+    TRACES = "/v1/traces"
+
+
+class BatchingMode:
+    BATCH = "batch"
+    SIMPLE = "simple"
+
+
+class SpanProcessorDefaults:
+    MAX_EXPORT_BATCH_SIZE = 64
+    SCHEDULE_DELAY_MILLIS = 1000
+
+
+class ResourceAttribute:
+    SERVICE_NAME = "service.name"
+    SERVICE_VERSION = "service.version"
+
+
+class OpenTelemetryRuntime:
+    PROXY_TRACER_PROVIDER = "ProxyTracerProvider"
+
+
+class IntegrationId:
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    LANGCHAIN = "langchain"
+    LANGGRAPH = "langgraph"
+    LANGSMITH = "langsmith"
+    OPENAI_AGENTS = "openai-agents"
+    CLAUDE_AGENT_SDK = "claude-agent-sdk"
+    PYDANTIC_AI = "pydantic-ai"
+
+
+class InstallerId:
+    """Function-name-compatible integration identifiers for errors."""
+
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    LANGCHAIN = "langchain"
+    LANGGRAPH = "langgraph"
+    LANGSMITH = "langsmith"
+    OPENAI_AGENTS = "openai_agents"
+    CLAUDE_AGENT_SDK = "claude_agent_sdk"
+    PYDANTIC_AI = "pydantic_ai"
+
+
+class ImportName:
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    LANGCHAIN_CORE = "langchain_core"
+    LANGGRAPH = "langgraph"
+    LANGSMITH = "langsmith"
+    LANGSMITH_CLIENT = "langsmith.client"
+    OPENAI_AGENTS = "agents"
+    CLAUDE_AGENT_SDK = "claude_agent_sdk"
+    CLAUDE_AGENT_SDK_QUERY = "claude_agent_sdk.query"
+    PYDANTIC_AI = "pydantic_ai"
+
+
+class GenAISystem:
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+
+
+class TracerName:
+    ROOT = "catalyst_tracing"
+    OPENAI = "catalyst_tracing.openai"
+    ANTHROPIC = "catalyst_tracing.anthropic"
+    LANGCHAIN = "catalyst_tracing.langchain"
+    CLAUDE_AGENT_SDK = "catalyst_tracing.claude_agent_sdk"
+
+
+class SpanName:
+    OPENAI_CHAT_COMPLETIONS = "OpenAI Chat Completions"
+    OPENAI_RESPONSES = "OpenAI Responses"
+    ANTHROPIC_MESSAGES = "Anthropic Messages"
+    CLAUDE_AGENT_QUERY = "ClaudeAgentSDK.query"
+
+
+class AgentName:
+    CLAUDE_AGENT_SDK = "ClaudeAgentSDK"
+
+
+class PatchedMethod:
+    CREATE = "create"
+
+
+PATCH_MARKER_ATTR = "_catalyst_wrapped"

catalyst_tracing/env.py

@@ -0,0 +1,67 @@
+"""Resolve catalyst-tracing config from kwargs + env vars."""
+
+from __future__ import annotations
+
+import os
+import uuid
+from dataclasses import dataclass
+
+from .constants import DefaultConfig, EnvVar
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    endpoint: str
+    token: str | None
+    service_name: str
+    service_version: str
+    debug: bool
+
+
+def _truthy(value: str | None) -> bool:
+    if value is None or value == "":
+        return False
+    return value.lower() not in {"0", "false", "no"}
+
+
+def resolve_config(
+    *,
+    endpoint: str | None = None,
+    token: str | None = None,
+    service_name: str | None = None,
+    service_version: str | None = None,
+    debug: bool | None = None,
+) -> ResolvedConfig:
+    env = os.environ
+    resolved_endpoint = (
+        endpoint
+        or env.get(EnvVar.CATALYST_OTLP_ENDPOINT)
+        or env.get(EnvVar.LEGACY_OTLP_ENDPOINT)
+        or DefaultConfig.OTLP_ENDPOINT
+    )
+    resolved_token = (
+        token
+        or env.get(EnvVar.CATALYST_OTLP_TOKEN)
+        or env.get(EnvVar.LEGACY_OTLP_INGEST_TOKEN)
+    )
+    resolved_service_name = (
+        service_name
+        or env.get(EnvVar.CATALYST_SERVICE_NAME)
+        or env.get(EnvVar.LEGACY_SERVICE_NAME)
+        or f"{DefaultConfig.SERVICE_NAME_PREFIX}-{uuid.uuid4().hex[:8]}"
+    )
+    resolved_service_version = (
+        service_version
+        or env.get(EnvVar.CATALYST_SERVICE_VERSION)
+        or DefaultConfig.SERVICE_VERSION
+    )
+    resolved_debug = (
+        debug if debug is not None else _truthy(env.get(EnvVar.CATALYST_DEBUG))
+    )
+    return ResolvedConfig(
+        endpoint=resolved_endpoint,
+        token=resolved_token,
+        service_name=resolved_service_name,
+        service_version=resolved_service_version,
+        debug=resolved_debug,
+    )

catalyst_tracing/errors.py

@@ -0,0 +1,134 @@
+"""Catalyst-tracing error types.
+
+Errors raised by this package always extend :class:`CatalystTracingError`
+and carry a stable :attr:`~CatalystTracingError.code` string for
+programmatic handling. Messages are written for humans — they say what
+went wrong AND how to fix it.
+
+Use ``isinstance(err, CatalystTracingError)`` for catch-and-log
+policies and the ``code`` field for fine-grained branching.
+
+Example::
+
+    from catalyst_tracing import CatalystTracingError, install_openai
+
+    try:
+        install_openai(provider)
+    except CatalystTracingError as err:
+        if err.code == "ERR_INVALID_TRACER_PROVIDER":
+            ...  # actionable handling
+        raise
+"""
+
+from __future__ import annotations
+
+from typing import Any, Final, Literal
+
+from .constants import InstallerId
+
+CatalystTracingErrorCode = Literal[
+    "ERR_INVALID_TRACER_PROVIDER",
+    "ERR_INVALID_SDK_INPUT",
+]
+
+
+class CatalystTracingErrorCodes:
+    INVALID_TRACER_PROVIDER: CatalystTracingErrorCode = "ERR_INVALID_TRACER_PROVIDER"
+    INVALID_SDK_INPUT: CatalystTracingErrorCode = "ERR_INVALID_SDK_INPUT"
+
+
+class CatalystTracingError(Exception):
+    """Base class for every error raised by ``catalyst_tracing``.
+
+    Catch this when you only need "did the package raise?". Subclasses
+    exist for the specific failure modes.
+    """
+
+    #: Stable, machine-readable code for ``except``-and-branch logic.
+    code: CatalystTracingErrorCode
+
+    def __init__(self, code: CatalystTracingErrorCode, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class InvalidTracerProviderError(CatalystTracingError):
+    """Raised when an ``install_*`` helper is given something that
+    isn't a TracerProvider.
+
+    The Python install helpers consistently take a TracerProvider
+    (matching the OTel SDK's idiom). If you pass a Tracer, a string,
+    or ``None``, you get this error pointing at the call site rather
+    than a confusing AttributeError deep in the patcher.
+    """
+
+    INTEGRATION_HINTS: Final[dict[str, str]] = {
+        InstallerId.OPENAI: "install_openai(provider)",
+        InstallerId.ANTHROPIC: "install_anthropic(provider)",
+        InstallerId.LANGCHAIN: "install_langchain(provider)",
+        InstallerId.LANGGRAPH: "install_langgraph(provider)",
+        InstallerId.LANGSMITH: "install_langsmith(provider)",
+        InstallerId.OPENAI_AGENTS: "install_openai_agents(provider)",
+        InstallerId.CLAUDE_AGENT_SDK: "install_claude_agent_sdk(provider)",
+        InstallerId.PYDANTIC_AI: "install_pydantic_ai(provider)",
+    }
+
+    def __init__(self, integration: str, received: Any) -> None:
+        hint = self.INTEGRATION_HINTS.get(
+            integration,
+            f"install_{integration}(provider)",
+        )
+        super().__init__(
+            CatalystTracingErrorCodes.INVALID_TRACER_PROVIDER,
+            f"install_{integration}: expected a TracerProvider "
+            f"(from `opentelemetry.sdk.trace`), got {_describe(received)}.\n"
+            f"Hint: pass `tracing.provider` from `setup()`, or your own "
+            f"`TracerProvider`: `{hint}`.",
+        )
+        self.integration = integration
+
+
+class InvalidSdkInputError(CatalystTracingError):
+    """Raised when an ``install_*`` helper that takes an SDK module
+    is given a non-module / wrong-shape argument."""
+
+    def __init__(
+        self,
+        *,
+        integration: str,
+        expectation: str,
+        received: Any,
+        fix_hint: str,
+    ) -> None:
+        super().__init__(
+            CatalystTracingErrorCodes.INVALID_SDK_INPUT,
+            f"install_{integration}: {expectation}, got {_describe(received)}.\n"
+            f"Hint: {fix_hint}",
+        )
+        self.integration = integration
+
+
+def _describe(value: Any) -> str:
+    """Short, human-friendly description of a value for error text.
+
+    We avoid logging the full value (potentially huge / contains
+    secrets); just enough context for the user to recognize what they
+    passed.
+    """
+    if value is None:
+        return "None"
+    if isinstance(value, type):
+        return f"class {value.__name__}"
+    if callable(value):
+        name = getattr(value, "__name__", None) or "anonymous"
+        return f"callable `{name}`"
+    if isinstance(value, dict):
+        keys = list(value)[:4]
+        if not keys:
+            return "an empty dict"
+        suffix = ", ..." if len(value) > 4 else ""
+        return f"dict with keys {keys}{suffix}"
+    type_name = type(value).__name__
+    if isinstance(value, (str, int, float, bool)):
+        return f"{type_name} {value!r}"
+    return type_name