agentship-observability 0.0.1__py3-none-any.whl

agentship_observability/__init__.py

@@ -0,0 +1,14 @@
+"""AgentShip observability — the OpenTelemetry pipeline behind the vendor-free ``Observer`` port.
+
+The contract (port, ``SpanKind``/``Usage``, SEMCONV, ``TraceView``) lives in ``agentship-core``;
+this package supplies the concrete OTel ``OTelObserver``, the
+exporter pipeline, the one-per-process LiteLLM cost/token callback, the record/replay capture hook,
+and the studio launcher (design §4.6). Import ``OTelObserver`` here; build a configured one with
+:func:`~agentship_observability.factory.build_otel_observer`.
+"""
+
+from __future__ import annotations
+
+from .otel import OTelObserver
+
+__all__ = ["OTelObserver"]

agentship_observability/config.py

@@ -0,0 +1,57 @@
+"""``ObservabilityConfig`` — the ``observability:`` config surface (C5).
+
+One small Pydantic model parses the ``observability:`` block from an agent's YAML (secrets come from
+the environment, never the file). Defaults are the safe ones: tracing on, the OTel provider, the
+``console`` exporter (which needs no running backend), content capture **off** (the PHI gate), user
+ids hashed, full sampling, and SaaS exporters blocked. Phoenix is the recommended production OSS
+exporter — a one-line ``exporters: [phoenix]`` swap — but is not the zero-config default because it
+needs a collector to point at.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+#: The exporter names the factory knows how to build. Extend here + in ``exporters/factory.py``.
+ExporterName = Literal["console", "phoenix", "langfuse", "langsmith", "opik"]
+
+
+class ObservabilityConfig(BaseModel):
+    """Declarative tracing config for one agent; the factory turns it into an ``Observer``.
+
+    ``provider`` selects the implementation: ``otel`` (the default) builds an ``OTelObserver`` over
+    a process-global ``TracerProvider``; ``none`` yields the no-op observer so a run is untraced but
+    unchanged. ``exporters`` is a list so a span tree can fan out to several backends at once.
+    """
+
+    model_config = {"extra": "forbid"}
+
+    #: Master switch. When false the factory yields the no-op observer regardless of ``provider``.
+    enabled: bool = True
+    #: The observer implementation: ``otel`` (default) or ``none`` (no-op).
+    provider: Literal["otel", "none"] = "otel"
+    #: Backends to export to; every span tree is sent to each. Default console (needs no backend).
+    exporters: list[ExporterName] = Field(default_factory=lambda: ["console"])
+    #: PHI gate — when false, prompt/response content is never put on a span (§4.6). Default off.
+    capture_content: bool = False
+    #: Hash the caller's user id on spans so a raw id never lands in a trace store. Default on.
+    hash_user_id: bool = True
+    #: Parent-based sampling ratio, 0.0–1.0. 1.0 keeps every trace; lower drops a fraction.
+    sample_ratio: float = 1.0
+    #: Allow a SaaS exporter (LangSmith) to receive content-bearing spans. Off in the PHI profile.
+    allow_saas_exporter: bool = False
+
+    @field_validator("sample_ratio")
+    @classmethod
+    def _ratio_in_range(cls, value: float) -> float:
+        """Reject a sampling ratio outside 0.0–1.0 — a typo here silently loses or floods traces."""
+        if not 0.0 <= value <= 1.0:
+            raise ValueError(f"sample_ratio must be between 0.0 and 1.0, got {value}")
+        return value
+
+    @property
+    def uses_saas_exporter(self) -> bool:
+        """Whether any configured exporter ships spans to a SaaS backend (currently LangSmith)."""
+        return "langsmith" in self.exporters

agentship_observability/exporters/__init__.py

@@ -0,0 +1,13 @@
+"""Exporter builders — each turns a configured backend name into an OTel ``SpanProcessor``.
+
+One module per backend (console, phoenix, langfuse, langsmith, opik); :func:`build_processor` in
+``factory`` dispatches a config's ``exporters`` list to them. Every builder returns a ready
+``SpanProcessor`` the tracer provider can register, so adding a backend is a one-file change plus a
+line in the dispatch table.
+"""
+
+from __future__ import annotations
+
+from .factory import build_processor
+
+__all__ = ["build_processor"]

agentship_observability/exporters/console.py

@@ -0,0 +1,24 @@
+"""Console exporter — prints finished spans to stderr. The zero-backend default (§C4).
+
+Needs nothing running, so it is the safe default: a dev can see the span tree immediately and an
+offline CI run never fails on a missing collector. Uses a ``SimpleSpanProcessor`` (synchronous
+export) because console output is cheap and immediate feedback beats batching here.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor, SpanProcessor
+
+from ..config import ObservabilityConfig
+
+
+def build(config: ObservabilityConfig) -> SpanProcessor:
+    """Build a synchronous processor that prints each finished span to stderr.
+
+    Spans go to **stderr**, not stdout: the CLI reserves stdout for the agent's answer so a piped
+    run is never polluted by trace output. ``ConsoleSpanExporter`` defaults to stdout, so the target
+    stream is set explicitly here.
+    """
+    return SimpleSpanProcessor(ConsoleSpanExporter(out=sys.stderr))

agentship_observability/exporters/factory.py

@@ -0,0 +1,38 @@
+"""Dispatch a config's ``exporters`` list to per-backend processor builders (§C4).
+
+One tiny lookup table maps each exporter name to its module's ``build(config)``. Adding a backend is
+a one-line change here plus its module. An unknown name is a fail-fast :class:`CapabilityError` with
+the known names listed, so a typo in YAML surfaces at build time, not as silent missing traces.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from agentship.errors import CapabilityError
+from opentelemetry.sdk.trace.export import SpanProcessor
+
+from ..config import ObservabilityConfig
+from . import console, langfuse, langsmith, opik, phoenix
+
+#: Exporter name → builder. Keys must match ``config.ExporterName``.
+_BUILDERS: dict[str, Callable[[ObservabilityConfig], SpanProcessor]] = {
+    "console": console.build,
+    "phoenix": phoenix.build,
+    "langfuse": langfuse.build,
+    "langsmith": langsmith.build,
+    "opik": opik.build,
+}
+
+
+def build_processor(name: str, config: ObservabilityConfig) -> SpanProcessor:
+    """Build the ``SpanProcessor`` for one exporter ``name``.
+
+    Raises :class:`CapabilityError` (listing the known names) when ``name`` is not a registered
+    exporter, so a misconfigured ``exporters:`` entry fails loudly at build time.
+    """
+    builder = _BUILDERS.get(name)
+    if builder is None:
+        known = ", ".join(sorted(_BUILDERS))
+        raise CapabilityError(f"unknown exporter {name!r}; known exporters: {known}")
+    return builder(config)

agentship_observability/exporters/langfuse.py

@@ -0,0 +1,41 @@
+"""Langfuse exporter — OTLP/HTTP to a Langfuse project (§C4).
+
+Langfuse (self-hostable or SaaS) accepts OTLP at ``${LANGFUSE_HOST}/api/public/otel/v1/traces`` and
+authenticates with HTTP Basic over the project's public/secret key pair. Keys and host come from the
+environment (never the config file) so a secret never lands in checked-in YAML.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanProcessor
+
+from ..config import ObservabilityConfig
+
+#: Langfuse Cloud host used when ``LANGFUSE_HOST`` is unset; self-hosters override it.
+DEFAULT_HOST = "https://cloud.langfuse.com"
+#: OTLP traces path appended to the host.
+OTEL_PATH = "/api/public/otel/v1/traces"
+
+
+def _basic_auth_header(public_key: str, secret_key: str) -> str:
+    """Return the ``Basic <b64>`` value for Langfuse's public/secret key pair."""
+    token = base64.b64encode(f"{public_key}:{secret_key}".encode()).decode()
+    return f"Basic {token}"
+
+
+def build(config: ObservabilityConfig) -> SpanProcessor:
+    """Build a batched OTLP/HTTP processor pointed at Langfuse with Basic-auth headers.
+
+    Reads ``LANGFUSE_HOST`` (optional), ``LANGFUSE_PUBLIC_KEY`` and ``LANGFUSE_SECRET_KEY`` from the
+    environment. Missing keys still build a processor (fail-open) — the backend simply rejects the
+    unauthenticated export rather than breaking the agent run.
+    """
+    host = os.getenv("LANGFUSE_HOST", DEFAULT_HOST).rstrip("/")
+    public_key = os.getenv("LANGFUSE_PUBLIC_KEY", "")
+    secret_key = os.getenv("LANGFUSE_SECRET_KEY", "")
+    headers = {"Authorization": _basic_auth_header(public_key, secret_key)}
+    return BatchSpanProcessor(OTLPSpanExporter(endpoint=f"{host}{OTEL_PATH}", headers=headers))

agentship_observability/exporters/langsmith.py

@@ -0,0 +1,32 @@
+"""LangSmith exporter — OTLP/HTTP to LangSmith. The one SaaS backend, gated (§C4, §4.6).
+
+LangSmith is a hosted service, so spans leave the boundary. The factory only wires it in when the
+config's ``allow_saas_exporter`` is set — this module just builds the processor. Endpoint and
+``x-api-key`` come from the environment; an optional ``LANGSMITH_PROJECT`` tags the traces.
+"""
+
+from __future__ import annotations
+
+import os
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanProcessor
+
+from ..config import ObservabilityConfig
+
+#: LangSmith's hosted OTLP traces endpoint when ``LANGSMITH_OTEL_ENDPOINT`` is unset.
+DEFAULT_ENDPOINT = "https://api.smith.langchain.com/otel/v1/traces"
+
+
+def build(config: ObservabilityConfig) -> SpanProcessor:
+    """Build a batched OTLP/HTTP processor pointed at LangSmith with its ``x-api-key`` header.
+
+    Reads ``LANGSMITH_OTEL_ENDPOINT`` (optional), ``LANGSMITH_API_KEY`` and ``LANGSMITH_PROJECT``
+    (optional) from the environment. The SaaS gate lives in the factory, not here.
+    """
+    endpoint = os.getenv("LANGSMITH_OTEL_ENDPOINT", DEFAULT_ENDPOINT)
+    headers = {"x-api-key": os.getenv("LANGSMITH_API_KEY", "")}
+    project = os.getenv("LANGSMITH_PROJECT")
+    if project:
+        headers["Langsmith-Project"] = project
+    return BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint, headers=headers))

agentship_observability/exporters/opik.py

@@ -0,0 +1,43 @@
+"""Opik exporter — OTLP/HTTP to an Opik backend (Comet's open-source LLM tracing tool) (§C4).
+
+Opik is open-source and self-hostable, so the default endpoint is the local Opik server; it also
+reads the GenAI/OpenInference attributes the observer stamps. As with Phoenix we reach it over the
+**standard OTLP/HTTP exporter** rather than Opik's SDK, keeping the pipeline vendor-neutral — Opik
+is just an OTLP endpoint here (integrate, don't reinvent).
+
+The endpoint comes from ``OPIK_OTEL_ENDPOINT`` (default the local server). Auth is optional so the
+local, keyless case just works: when ``OPIK_API_KEY`` is set an ``Authorization`` header is sent,
+and ``OPIK_WORKSPACE`` / ``OPIK_PROJECT_NAME`` add the workspace and project headers Opik Cloud
+expects. Pointing this at Opik Cloud sends spans off-box — the same SaaS consideration the
+factory's ``allow_saas_exporter`` gate covers when the endpoint is a hosted one.
+"""
+
+from __future__ import annotations
+
+import os
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanProcessor
+
+from ..config import ObservabilityConfig
+
+#: Where a local self-hosted Opik server accepts OTLP/HTTP traces when nothing else is configured.
+DEFAULT_ENDPOINT = "http://localhost:5173/api/v1/private/otel/v1/traces"
+
+
+def build(config: ObservabilityConfig) -> SpanProcessor:
+    """Build a batched OTLP/HTTP processor pointed at Opik, with optional auth/workspace headers.
+
+    Reads ``OPIK_OTEL_ENDPOINT`` (optional) and, for Opik Cloud, the optional ``OPIK_API_KEY``,
+    ``OPIK_WORKSPACE`` and ``OPIK_PROJECT_NAME``. With none of them set it targets a local Opik
+    server with no auth, so the offline/self-hosted path needs no configuration.
+    """
+    endpoint = os.getenv("OPIK_OTEL_ENDPOINT", DEFAULT_ENDPOINT)
+    headers: dict[str, str] = {}
+    if api_key := os.getenv("OPIK_API_KEY"):
+        headers["Authorization"] = api_key
+    if workspace := os.getenv("OPIK_WORKSPACE"):
+        headers["Comet-Workspace"] = workspace
+    if project := os.getenv("OPIK_PROJECT_NAME"):
+        headers["projectName"] = project
+    return BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint, headers=headers))

agentship_observability/exporters/phoenix.py

@@ -0,0 +1,32 @@
+"""Phoenix exporter — OTLP/HTTP to an Arize Phoenix collector. The recommended OSS backend (§C4).
+
+Phoenix is self-hosted and open-source, reads the GenAI + OpenInference attributes the observer
+stamps, and needs no API key — just a running collector. The endpoint comes from
+``PHOENIX_COLLECTOR_ENDPOINT`` (default the local dev collector), so pointing at a shared Phoenix is
+an env-var change, not a code change.
+
+We deliberately reach Phoenix over the **standard OTLP/HTTP exporter**, not ``arize-phoenix-otel``'s
+``register()`` convenience. ``register()`` installs a *global* tracer provider; our observer
+composes this processor into its own provider (multiple exporters, one pipeline), so that global
+grab would fight our factory. Using plain OTLP keeps us vendor-neutral with zero Phoenix-SDK
+lock-in — Phoenix
+is just an OTLP endpoint here — which is exactly the integrate-don't-reinvent contract.
+"""
+
+from __future__ import annotations
+
+import os
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanProcessor
+
+from ..config import ObservabilityConfig
+
+#: Where Phoenix listens for OTLP/HTTP traces when nothing else is configured (local dev collector).
+DEFAULT_ENDPOINT = "http://localhost:6006/v1/traces"
+
+
+def build(config: ObservabilityConfig) -> SpanProcessor:
+    """Build a batched OTLP/HTTP processor pointed at the Phoenix collector."""
+    endpoint = os.getenv("PHOENIX_COLLECTOR_ENDPOINT", DEFAULT_ENDPOINT)
+    return BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint))

agentship_observability/factory.py

@@ -0,0 +1,122 @@
+"""Build an :class:`Observer` from an :class:`ObservabilityConfig` (§C5).
+
+The public seam the rest of AgentShip calls. :func:`build_observer` maps a config to a concrete
+observer: ``provider: none`` (or ``enabled: false``) yields the no-op observer so a run is untraced
+but unchanged; ``provider: otel`` builds an :class:`OTelObserver` over a **process-global**
+``TracerProvider``.
+
+The provider is memoized (§DoD "one process-global"): every agent in a process shares one provider,
+so exporters and their batching threads are created once, not per agent. The memo key is the config
+signature that affects the pipeline (service name, exporters, sampling), so two agents with the same
+observability block reuse the same provider and two with different blocks each get their own.
+"""
+
+from __future__ import annotations
+
+import os
+
+from agentship.errors import CapabilityError
+from agentship.observability import NoOpObserver, Observer
+from agentship.spec import ObservabilitySpec
+from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
+
+from .config import ObservabilityConfig
+from .exporters import build_processor
+from .otel import OTelObserver
+
+#: The OTel ``service.name`` for every AgentShip span, overridable via env for multi-service setups.
+DEFAULT_SERVICE_NAME = "agentship"
+
+#: Process-global cache of built providers, keyed by :func:`_provider_key`.
+_PROVIDERS: dict[tuple, TracerProvider] = {}
+
+
+def _service_name() -> str:
+    """Resolve the ``service.name`` resource attribute (env override, then default)."""
+    return os.getenv("AGENTSHIP_SERVICE_NAME", DEFAULT_SERVICE_NAME)
+
+
+def _resolved_exporters(config: ObservabilityConfig) -> list[str]:
+    """Return the exporter names to wire, enforcing the SaaS gate (§4.6).
+
+    A SaaS exporter (LangSmith) ships spans off-box, so it is only allowed when the config opts in
+    with ``allow_saas_exporter``. Otherwise it is a fail-fast :class:`CapabilityError` rather than a
+    silent data-egress the operator did not ask for.
+    """
+    if config.uses_saas_exporter and not config.allow_saas_exporter:
+        raise CapabilityError(
+            "exporter 'langsmith' ships spans to a SaaS backend; set allow_saas_exporter: true "
+            "to enable it"
+        )
+    return list(config.exporters)
+
+
+def _provider_key(config: ObservabilityConfig) -> tuple:
+    """Build the memo key: the config fields that change the provider's pipeline."""
+    return (_service_name(), tuple(config.exporters), config.sample_ratio)
+
+
+def build_tracer_provider(config: ObservabilityConfig) -> TracerProvider:
+    """Return the process-global ``TracerProvider`` for ``config``, building it once.
+
+    The provider carries the ``service.name`` resource and a ``ParentBased(TraceIdRatioBased)``
+    sampler (so a child inherits its root's keep/drop decision) and registers one span processor per
+    configured exporter.
+    """
+    key = _provider_key(config)
+    provider = _PROVIDERS.get(key)
+    if provider is not None:
+        return provider
+
+    resource = Resource.create({SERVICE_NAME: _service_name()})
+    sampler = ParentBased(TraceIdRatioBased(config.sample_ratio))
+    provider = TracerProvider(resource=resource, sampler=sampler)
+    for name in _resolved_exporters(config):
+        provider.add_span_processor(build_processor(name, config))
+
+    _PROVIDERS[key] = provider
+    return provider
+
+
+def _as_config(config: ObservabilityConfig | ObservabilitySpec | None) -> ObservabilityConfig:
+    """Coerce the declarative :class:`ObservabilitySpec` (or ``None``) into an adapter config.
+
+    The kernel's ``observability:`` block is an :class:`~agentship.spec.ObservabilitySpec` — a
+    vendor-neutral authoring surface. This maps its fields onto the adapter's
+    :class:`ObservabilityConfig`, which is where exporter names are actually validated (against the
+    backends this package can build) and env-driven endpoints/keys are resolved. A pass-through
+    ``ObservabilityConfig`` is returned as-is, and ``None`` yields the console-only default.
+    """
+    if isinstance(config, ObservabilitySpec):
+        return ObservabilityConfig(**config.model_dump())
+    return config or ObservabilityConfig()
+
+
+def build_otel_observer(
+    config: ObservabilityConfig | ObservabilitySpec | None = None,
+) -> OTelObserver:
+    """Build an :class:`OTelObserver` over the process-global provider for ``config``.
+
+    Called by the ``agentship.observers`` entry point (``otel``) with an agent's
+    :class:`~agentship.spec.ObservabilitySpec`, and by tests with an :class:`ObservabilityConfig`
+    directly. Either is coerced by :func:`_as_config`; a bare call still yields a working
+    console-exporting observer.
+    """
+    config = _as_config(config)
+    provider = build_tracer_provider(config)
+    return OTelObserver(provider, capture_content=config.capture_content)
+
+
+def build_observer(config: ObservabilityConfig | None = None) -> Observer:
+    """Map a config to a concrete observer: no-op when disabled/``none``, else the OTel observer."""
+    config = config or ObservabilityConfig()
+    if not config.enabled or config.provider == "none":
+        return NoOpObserver()
+    return build_otel_observer(config)
+
+
+def _reset_providers_for_tests() -> None:
+    """Clear the process-global provider cache. For tests that assert build-once behaviour."""
+    _PROVIDERS.clear()

agentship_observability/litellm_logger.py

@@ -0,0 +1,152 @@
+"""The one LiteLLM callback that turns a completed model call into span usage (P07 · C3).
+
+Every model call in AgentShip goes through LiteLLM. LiteLLM fires success callbacks with the token
+counts, resolved model, finish reasons, and computed cost — exactly the roll-up the ``model`` span
+wants. This module registers **one** process-global :class:`CustomLogger` that, on each success,
+builds a :class:`Usage` and hands it to the observer's :meth:`on_model`, which stamps it onto the
+currently-active model span (§4.3).
+
+The callback carries no per-run state: ``on_model`` targets whatever model span is current on the
+OTel context, so a single registered logger serves every concurrent agent. Registration is
+idempotent — calling :func:`register_litellm_logger` twice adds the callback once (§DoD "one
+process-global LiteLLM callback").
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from typing import Any
+
+import litellm
+from agentship.observability import Observer, Usage, replay_attributes
+from litellm.integrations.custom_logger import CustomLogger
+
+_log = logging.getLogger("agentship.observability")
+
+
+def _latency_ms(start_time: Any, end_time: Any) -> float:
+    """Milliseconds between LiteLLM's start/end markers; 0.0 if they aren't usable datetimes."""
+    if isinstance(start_time, datetime) and isinstance(end_time, datetime):
+        return (end_time - start_time).total_seconds() * 1000.0
+    return 0.0
+
+
+def _provider_of(kwargs: dict[str, Any], model: str) -> str:
+    """Best-effort LLM provider (``openai``, ``anthropic``, …) from kwargs, else the model prefix.
+
+    LiteLLM usually sets ``custom_llm_provider``; when it doesn't, fall back to the
+    ``provider/model`` prefix, and finally to ``unknown`` rather than raising inside a callback.
+    """
+    provider = kwargs.get("custom_llm_provider")
+    if provider:
+        return str(provider)
+    if "/" in model:
+        return model.split("/", 1)[0]
+    return "unknown"
+
+
+def _finish_reasons(response_obj: Any) -> list[str]:
+    """Collect non-empty ``finish_reason`` values from a response's choices."""
+    reasons: list[str] = []
+    for choice in getattr(response_obj, "choices", None) or []:
+        reason = getattr(choice, "finish_reason", None)
+        if reason:
+            reasons.append(str(reason))
+    return reasons
+
+
+def usage_from_litellm(
+    kwargs: dict[str, Any], response_obj: Any, start_time: Any, end_time: Any
+) -> Usage | None:
+    """Build a :class:`Usage` from a LiteLLM success callback's arguments, or ``None`` if unusable.
+
+    Reads token counts from ``response_obj.usage``, the resolved model from the response, the cost
+    from ``kwargs['response_cost']`` (LiteLLM computes it), and latency from the start/end markers.
+    Returns ``None`` when there is no usage block to report, so the caller can skip stamping.
+    """
+    usage = getattr(response_obj, "usage", None)
+    if usage is None:
+        return None
+    requested_model = str(kwargs.get("model") or getattr(response_obj, "model", "") or "")
+    response_model = getattr(response_obj, "model", None)
+    cost = kwargs.get("response_cost")
+    return Usage(
+        model=requested_model,
+        provider=_provider_of(kwargs, requested_model),
+        input_tokens=int(getattr(usage, "prompt_tokens", 0) or 0),
+        output_tokens=int(getattr(usage, "completion_tokens", 0) or 0),
+        cost_usd=float(cost) if cost is not None else None,
+        latency_ms=_latency_ms(start_time, end_time),
+        finish_reasons=_finish_reasons(response_obj),
+        response_model=str(response_model) if response_model else None,
+    )
+
+
+class AgentShipLiteLLMLogger(CustomLogger):
+    """A LiteLLM callback that stamps each completed model call onto the active model span.
+
+    Holds a reference to an :class:`Observer` only to reach :meth:`Observer.on_model`; the span it
+    writes to is the one current on the trace context, not anything this logger tracks. Both the
+    sync and async success hooks funnel through :meth:`_emit`, which is fail-open — a bad callback
+    payload is logged and dropped, never raised into LiteLLM's request path.
+    """
+
+    def __init__(self, observer: Observer) -> None:
+        """Bind the observer whose ``on_model`` receives each call's usage."""
+        self._observer = observer
+
+    def _emit(self, kwargs: Any, response_obj: Any, start_time: Any, end_time: Any) -> None:
+        """Stamp usage and the replay-capture attributes onto the model span; swallow any failure.
+
+        Usage (tokens/cost/latency) always lands; the record/replay attributes (request hash, and
+        the request/response payload only when the observer's ``capture_content`` is set) let P12
+        rebuild a deterministic cassette (§4.10). Both go on the same active model span.
+        """
+        try:
+            kwargs = kwargs or {}
+            usage = usage_from_litellm(kwargs, response_obj, start_time, end_time)
+            if usage is not None:
+                self._observer.on_model(usage)
+            capture_content = bool(getattr(self._observer, "capture_content", False))
+            self._observer.annotate_model(
+                replay_attributes(kwargs, response_obj, capture_content=capture_content)
+            )
+        except Exception:  # noqa: BLE001 - a callback must never break the model call
+            _log.warning("observability.litellm_logger.failed (usage dropped)", exc_info=True)
+
+    def log_success_event(self, kwargs, response_obj, start_time, end_time) -> None:
+        """LiteLLM sync success hook — stamp usage onto the current model span."""
+        self._emit(kwargs, response_obj, start_time, end_time)
+
+    async def async_log_success_event(self, kwargs, response_obj, start_time, end_time) -> None:
+        """LiteLLM async success hook — stamp usage onto the current model span."""
+        self._emit(kwargs, response_obj, start_time, end_time)
+
+
+#: The one registered logger for this process; ``None`` until the first registration.
+_registered: AgentShipLiteLLMLogger | None = None
+
+
+def register_litellm_logger(observer: Observer) -> AgentShipLiteLLMLogger:
+    """Register the process-global LiteLLM callback once, returning it (idempotent).
+
+    On the first call, an :class:`AgentShipLiteLLMLogger` is appended to ``litellm.callbacks``.
+    Later calls return the same logger without re-registering, so only one usage stamp fires per
+    model call regardless of how many agents are built.
+    """
+    global _registered
+    if _registered is not None:
+        return _registered
+    logger = AgentShipLiteLLMLogger(observer)
+    litellm.callbacks.append(logger)
+    _registered = logger
+    return logger
+
+
+def _reset_litellm_logger_for_tests() -> None:
+    """Remove the registered callback and clear the guard. For registration tests only."""
+    global _registered
+    if _registered is not None and _registered in litellm.callbacks:
+        litellm.callbacks.remove(_registered)
+    _registered = None

agentship_observability/otel/__init__.py

@@ -0,0 +1,8 @@
+"""The OpenTelemetry implementation of the ``Observer`` port: kinds mapping + ``OTelObserver``."""
+
+from __future__ import annotations
+
+from .kinds import to_otel_kind
+from .observer import OTelObserver
+
+__all__ = ["OTelObserver", "to_otel_kind"]

agentship_observability/otel/kinds.py

@@ -0,0 +1,26 @@
+"""Map AgentShip's semantic :class:`SpanKind` onto OpenTelemetry's ``trace.SpanKind`` (§4.1).
+
+OTel has no ``AGENT`` or ``TOOL`` kind, so the semantic role travels on the
+``gen_ai.operation.name`` attribute (where Phoenix/Langfuse's OpenInference expects it) and the OTel
+kind is only a coarse client/internal hint. The mapping: ``LLM`` → ``CLIENT`` (an outbound call to a
+provider), everything else (``AGENT``/``TOOL``/``INTERNAL``) → ``INTERNAL``. Kept in one tiny table
+so the choice is inspectable in one place.
+"""
+
+from __future__ import annotations
+
+from agentship.observability import SpanKind
+from opentelemetry.trace import SpanKind as OTelSpanKind
+
+#: The single source of truth for AgentShip-kind → OTel-kind. ``LLM`` is the only outbound call.
+_KIND_TO_OTEL: dict[SpanKind, OTelSpanKind] = {
+    SpanKind.AGENT: OTelSpanKind.INTERNAL,
+    SpanKind.LLM: OTelSpanKind.CLIENT,
+    SpanKind.TOOL: OTelSpanKind.INTERNAL,
+    SpanKind.INTERNAL: OTelSpanKind.INTERNAL,
+}
+
+
+def to_otel_kind(kind: SpanKind) -> OTelSpanKind:
+    """Return the OTel ``SpanKind`` for an AgentShip ``SpanKind`` (defaults to ``INTERNAL``)."""
+    return _KIND_TO_OTEL.get(kind, OTelSpanKind.INTERNAL)

agentship_observability/otel/observer.py

@@ -0,0 +1,224 @@
+"""``OTelObserver`` — the concrete :class:`Observer` over an OpenTelemetry ``TracerProvider`` (C1).
+
+This is the default observer. It owns the span-tree shape (§4.1): every ``span()`` opens an OTel
+span set as the current one, so a span opened inside another nests automatically (OTel's own
+contextvars), and the tree is identical whichever engine runs. It stamps GenAI attributes (§4.2)
+and, via :meth:`on_model`, rolls up cost/tokens/latency onto the active ``model`` span.
+
+Fail-open is a hard rule (§4.7): a tracing/SDK fault is logged and swallowed so it can never break
+an agent run. Only the *caller's* exception propagates — and when it does, the span records it and
+is marked errored before it re-raises, so the run's error flow is untouched.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator, Mapping
+from contextlib import contextmanager
+from typing import Any
+
+from agentship.observability import Observer, Span, SpanKind, Usage, semconv, usage_attributes
+from opentelemetry import trace
+from opentelemetry.trace import Span as OTelSpanType
+from opentelemetry.trace import SpanKind as OTelSpanKind
+from opentelemetry.trace import Status, StatusCode
+
+from .kinds import to_otel_kind
+
+_log = logging.getLogger("agentship.observability")
+
+#: OTel accepts only str/bool/int/float (and sequences of those) as attribute values.
+_SCALAR = (str, bool, int, float)
+
+
+def _clean_attrs(attrs: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Coerce an attribute mapping into OTel-safe values, dropping ``None``.
+
+    Anything not a scalar (or a list of scalars) is stringified rather than dropped, so a caller's
+    attribute is never silently lost — it just arrives as text. ``None`` values are omitted because
+    OTel rejects them.
+    """
+    cleaned: dict[str, Any] = {}
+    for key, value in (attrs or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, _SCALAR):
+            cleaned[key] = value
+        elif isinstance(value, (list, tuple)) and all(isinstance(v, _SCALAR) for v in value):
+            cleaned[key] = list(value)
+        else:
+            cleaned[key] = str(value)
+    return cleaned
+
+
+class _OTelSpan:
+    """The :class:`Span` handed to callers — a thin writer over a live OTel span."""
+
+    def __init__(self, span: OTelSpanType) -> None:
+        """Bind the OTel span this handle writes through."""
+        self._span = span
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set one attribute, coercing it to an OTel-safe value first."""
+        cleaned = _clean_attrs({key: value})
+        if cleaned:
+            self._span.set_attribute(key, cleaned[key])
+
+    def set_attributes(self, attrs: Mapping[str, Any]) -> None:
+        """Set several attributes at once (each coerced, ``None`` dropped)."""
+        self._span.set_attributes(_clean_attrs(attrs))
+
+    def record_exception(self, exc: BaseException) -> None:
+        """Attach the exception to the span (does not itself set error status)."""
+        self._span.record_exception(exc)
+
+    def set_error(self, exc: BaseException | None = None) -> None:
+        """Mark the span's status ERROR, recording ``exc`` when given."""
+        if exc is not None:
+            self._span.record_exception(exc)
+        self._span.set_status(Status(StatusCode.ERROR))
+
+    def end(self) -> None:
+        """End the underlying OTel span, fixing its end time (for :meth:`Observer.start_span`)."""
+        self._span.end()
+
+
+class _NoOpSpan:
+    """Handed out only when opening a real span itself failed — keeps the caller's block running."""
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Ignore."""
+
+    def set_attributes(self, attrs: Mapping[str, Any]) -> None:
+        """Ignore."""
+
+    def record_exception(self, exc: BaseException) -> None:
+        """Ignore."""
+
+    def set_error(self, exc: BaseException | None = None) -> None:
+        """Ignore."""
+
+    def end(self) -> None:
+        """Ignore — a no-op span has nothing to close."""
+
+
+class OTelObserver(Observer):
+    """The OpenTelemetry :class:`Observer`: a span factory + per-model-call usage sink.
+
+    Construct with a configured ``TracerProvider`` (the factory builds one process-global provider).
+    ``capture_content`` mirrors the PHI gate — when false, content-bearing attributes are never set,
+    so prompt/response text cannot leave the process even if a caller passes it.
+    """
+
+    def __init__(
+        self, tracer_provider: trace.TracerProvider, *, capture_content: bool = False
+    ) -> None:
+        """Bind a tracer from ``tracer_provider`` and record the PHI content-capture flag."""
+        self._tracer = tracer_provider.get_tracer("agentship")
+        self.capture_content = capture_content
+
+    @contextmanager
+    def span(
+        self, name: str, kind: SpanKind, attrs: Mapping[str, Any] | None = None
+    ) -> Iterator[Span]:
+        """Open an OTel span ``name`` of ``kind`` (nested under the current one) and yield a handle.
+
+        On a raise inside the block, OTel records the exception and sets ERROR status before it
+        re-raises. If opening the span itself fails, a no-op handle is yielded so the caller's work
+        still runs (fail-open, §4.7).
+        """
+        try:
+            cm = self._tracer.start_as_current_span(
+                name,
+                kind=to_otel_kind(kind),
+                attributes=_clean_attrs(attrs),
+                record_exception=True,
+                set_status_on_exception=True,
+            )
+        except Exception:  # noqa: BLE001 - tracing must never break the run
+            _log.warning("observability.span.failed name=%s (tracing skipped)", name, exc_info=True)
+            yield _NoOpSpan()
+            return
+        with cm as otel_span:
+            yield _OTelSpan(otel_span)
+
+    def start_span(
+        self,
+        name: str,
+        kind: SpanKind,
+        attrs: Mapping[str, Any] | None = None,
+        *,
+        parent: Span | None = None,
+    ) -> Span:
+        """Open an OTel span without entering it as current; the caller must :meth:`Span.end` it.
+
+        The manual counterpart to :meth:`span`, for the callback-driven tracer. ``parent`` nests the
+        span explicitly: a :class:`_OTelSpan` from an earlier ``start_span`` becomes the parent via
+        its OTel context, so the model→tool tree is rebuilt from ``run_id``/``parent_run_id`` even
+        though the events fire as separate calls. With ``parent=None`` the ambient context is used,
+        so the first callback span lands under the open root ``agent`` span. Fail-open: if opening
+        fails, a no-op handle is returned so the run continues untraced (§4.7).
+        """
+        try:
+            context = None
+            if isinstance(parent, _OTelSpan):
+                context = trace.set_span_in_context(parent._span)
+            otel_span = self._tracer.start_span(
+                name,
+                context=context,
+                kind=to_otel_kind(kind),
+                attributes=_clean_attrs(attrs),
+            )
+            return _OTelSpan(otel_span)
+        except Exception:  # noqa: BLE001 - tracing must never break the run
+            _log.warning(
+                "observability.start_span.failed name=%s (tracing skipped)", name, exc_info=True
+            )
+            return _NoOpSpan()
+
+    def _is_model_span(self, span: OTelSpanType) -> bool:
+        """Return whether ``span`` is the ``model`` span usage should land on.
+
+        Prefers the span name (``model``); falls back to the OTel kind (``CLIENT``, which only the
+        model span uses) for spans whose name is not exposed.
+        """
+        if getattr(span, "name", None) == semconv.SPAN_MODEL:
+            return True
+        return getattr(span, "kind", None) == OTelSpanKind.CLIENT
+
+    def on_model(self, usage: Usage) -> None:
+        """Stamp GenAI + OpenInference cost/token/latency attributes onto the active model span.
+
+        A no-op (with a warning) when the current span is not a model span, so a stray callback
+        never corrupts an unrelated span (§4.3). Fail-open — any error here is swallowed.
+        """
+        try:
+            span = trace.get_current_span()
+            if not span.is_recording() or not self._is_model_span(span):
+                _log.warning("on_model called off a model span; usage dropped")
+                return
+            span.set_attributes(_clean_attrs(usage_attributes(usage)))
+        except Exception:  # noqa: BLE001 - tracing must never break the run
+            _log.warning("observability.on_model.failed (usage dropped)", exc_info=True)
+
+    def annotate_model(self, attrs: Mapping[str, Any]) -> None:
+        """Stamp extra attributes (replay hash + gated payload) onto the active model span.
+
+        A no-op (with a warning) off a model span, mirroring :meth:`on_model`. Fail-open — any
+        error is swallowed so the capture hook can never break the model call (§4.7).
+        """
+        try:
+            span = trace.get_current_span()
+            if not span.is_recording() or not self._is_model_span(span):
+                _log.warning("annotate_model called off a model span; attributes dropped")
+                return
+            span.set_attributes(_clean_attrs(attrs))
+        except Exception:  # noqa: BLE001 - tracing must never break the run
+            _log.warning("observability.annotate_model.failed (attributes dropped)", exc_info=True)
+
+    def current_trace_id(self) -> str | None:
+        """Return the active trace id as 32-hex, or ``None`` when no valid span is active."""
+        ctx = trace.get_current_span().get_span_context()
+        if ctx is None or not ctx.is_valid:
+            return None
+        return format(ctx.trace_id, "032x")

agentship_observability-0.0.1.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: agentship-observability
+Version: 0.0.1
+Summary: AgentShip observability — the OpenTelemetry implementation of the Observer port: span-tree exporter pipeline (Phoenix/Langfuse/LangSmith), the one-per-process LiteLLM cost/token callback, and the studio launcher. The vendor-free contract lives in agentship-core.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: agentship-core==0.0.1
+Requires-Dist: litellm>=1.74
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
+Requires-Dist: opentelemetry-sdk>=1.27
+Provides-Extra: phoenix
+Requires-Dist: arize-phoenix-otel>=0.6; extra == 'phoenix'
+Requires-Dist: openinference-semantic-conventions>=0.1; extra == 'phoenix'
+Description-Content-Type: text/markdown
+
+# agentship-observability
+
+The OpenTelemetry implementation of AgentShip's `Observer` port (Phase 07).
+
+The **contract** — the `Observer`/`Span` port, `SpanKind`/`Usage`, the frozen SEMCONV span-name and
+attribute-key constants, and the `TraceView` read-port — lives in **`agentship-core`** with no OTel
+dependency, so an engine or eval hook can read a trace with only the kernel installed (design §4.6).
+
+This package holds only the **pipeline**:
+
+- `otel/observer.py` — `OTelObserver`, the concrete port over a `TracerProvider`: it builds the
+  canonical span tree (§4.1), sets GenAI attributes (§4.2), and rolls up cost/tokens/latency.
+- `exporters/` — one `SpanProcessor` per backend (`console`, `phoenix`, `langfuse`, `langsmith`),
+  all reached over OTLP/HTTP (no per-vendor SDK lock-in).
+- `litellm_callback.py` — one process-global `CustomLogger` that stamps cost/tokens/latency onto the
+  current `model` span, so every LiteLLM caller is covered without per-call wiring.
+- `config.py` + `factory.py` — the `observability:` config surface and the process-global
+  `TracerProvider` the factory memoises; `provider: otel` (default) → `OTelObserver`, `none` → NoOp.
+- `capture.py` — the record/replay hook that stamps `agentship.replay.request_hash` (+ gated
+  request/response) so P12 can build deterministic cassettes.
+- `studio.py` — `generate_langgraph_json` + the loopback-only, dev-token studio launcher.
+
+Everything a price table, trace store, or UI would provide is **consumed** (Phoenix/Langfuse/
+LangSmith + LangGraph Studio); we build only the composition.
+
+## Conformance guards (we keep thin, but prove it conforms)
+
+Two pieces are deliberately vendor-free — the semantic-convention key constants and the
+`RecordingObserver` — because the kernel cannot import OpenTelemetry (design §4.6) and the base
+install ships without a collector. To keep them from silently drifting from the real thing, each is
+continuously proven against upstream:
+
+- `tests/test_semconv_upstream.py` asserts every `gen_ai.*` / `llm.*` key equals the OTel-GenAI /
+  OpenInference string it claims to speak.
+- `tests/test_observer_parity.py` runs one interaction through both the in-memory `RecordingObserver`
+  and the real `OTelObserver`, and asserts the two produce the same span tree and model-span
+  attributes.
+
+See [`docs/decisions/0001-integrate-not-invent.md`](../../docs/decisions/0001-integrate-not-invent.md)
+for the full rationale.

agentship_observability-0.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+agentship_observability/__init__.py,sha256=CK6SEAOPawrbE01Bmt8gAEgPjq6kZ9B5lfetHNYPi30,620
+agentship_observability/config.py,sha256=HG1yRkKWFUYY740o-ndAxuPrJuOzU5PLuk0bP9ZNZXc,2889
+agentship_observability/factory.py,sha256=GwhqmqOl4f8rphCyl_k5uZ3GOJF1nyB8YnuAC5jVLlA,5479
+agentship_observability/litellm_logger.py,sha256=4HM7DOQ3_4-DarNWPRhBQQWenpDcef9uoUj8n5Xshu4,7002
+agentship_observability/exporters/__init__.py,sha256=KVAr8uOUmHkZSo82aQgz6eVZppss2Wll5XNbH1Dl-1M,521
+agentship_observability/exporters/console.py,sha256=oKetjrodGNKz0wBT1RmwYEVY6asYyYK_-0S2S41VB5A,1010
+agentship_observability/exporters/factory.py,sha256=S65eWOKP0TC9D-Y6VyJGlaF1aANos_o6Ylh_qGMxGkQ,1506
+agentship_observability/exporters/langfuse.py,sha256=lIE0YvZY5piG2JhhhzWikCZNkUqwz2MK3EumTsMCu3c,1849
+agentship_observability/exporters/langsmith.py,sha256=MG1lh4gUFxDl24oTjnWZOrsIOqtoZwoKooDpxfeBNoI,1459
+agentship_observability/exporters/opik.py,sha256=tG7Oe6qJxR0Wsw-gmzwCkJjjAz3jYbX-rq08tN1f-0c,2245
+agentship_observability/exporters/phoenix.py,sha256=nOR_QLYsluPsj7d_W8jTYHxPzkiD1MSorjzX-Cc2NVU,1603
+agentship_observability/otel/__init__.py,sha256=zDJRxp5gfIm5Qi7YAFF6Q17ToHsHMPkG7UZFTSdgVfg,247
+agentship_observability/otel/kinds.py,sha256=Qoo6x74wzxEOHBNJdYPSMpJKbsBLyocjgy-xMk2hLzs,1191
+agentship_observability/otel/observer.py,sha256=OPyIhUAuIAj3cQ0ViK1nC3_r-U-PA7gQYQ_i8m8ZQCA,9803
+agentship_observability-0.0.1.dist-info/METADATA,sha256=9Lf002sgks4Jy5FCD8-BPzAR4Y54rHZ-NOcPO0RPfVM,3263
+agentship_observability-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agentship_observability-0.0.1.dist-info/entry_points.txt,sha256=O-csEoe8xy_SK_y02zUKdjC4EzKnHYfqnken1__fAeE,81
+agentship_observability-0.0.1.dist-info/RECORD,,

agentship_observability-0.0.1.dist-info/WHEEL

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

agentship_observability-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[agentship.observers]
+otel = agentship_observability.factory:build_otel_observer