agentship-observability 0.0.1__tar.gz

agentship_observability-0.0.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Env / secrets — never commit
+.env
+.env.*
+!.env.example
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Docs build
+site/

agentship_observability-0.0.1/PKG-INFO

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

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

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentship-observability"
+version = "0.0.1"
+description = "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."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "Apache-2.0"
+# The tracing SDK + OTLP/HTTP export are the only hard deps: every backend
+# (Phoenix, Langfuse, LangSmith) is reached over OTLP/HTTP, so there is no
+# per-vendor SDK lock-in here (design §5 — we consume, we do not reinvent).
+dependencies = [
+    "agentship-core==0.0.1",
+    "opentelemetry-api>=1.27",
+    "opentelemetry-sdk>=1.27",
+    "opentelemetry-exporter-otlp-proto-http>=1.27",
+    # The one success callback that turns each model call into span usage runs off
+    # LiteLLM's CustomLogger; every model call in AgentShip already routes through it.
+    "litellm>=1.74",
+]
+
+[project.optional-dependencies]
+# The OpenInference semantic-convention keys + Phoenix's one-command OTel wiring.
+# The exporter works over plain OTLP without these; they add the attribute mirrors
+# Phoenix's cost panel reads. Optional so a Langfuse/LangSmith user need not pull them.
+phoenix = ["arize-phoenix-otel>=0.6", "openinference-semantic-conventions>=0.1"]
+
+# The default OTel observer registers here so the factory discovers it by name with
+# no core edit — mirroring how engines and auth providers are found (entry points).
+[project.entry-points."agentship.observers"]
+otel = "agentship_observability.factory:build_otel_observer"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agentship_observability"]

agentship_observability-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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()