ratel-ai-telemetry 0.1.0__tar.gz

ratel_ai_telemetry-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+# Virtualenv + build/test tool caches
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# Wheel/sdist output
+dist/

ratel_ai_telemetry-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `ratel-ai-telemetry` (the Python telemetry helper) are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this package adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-06
+
+### Added
+
+- The telemetry helper (ADR-0015): the full `ratel.*` vocabulary as constants (attribute keys, span/event names, `gen_ai.*` interop keys, and the `Origin`/`SearchTarget`/`AuthOutcome` value enums) pinned to OpenTelemetry semconv `gen_ai` v1.42.0.
+- `init()` sugar over the OpenTelemetry Python SDK: wires an OTLP `http/protobuf` exporter to `RATEL_URL` (or `endpoint=`/`headers=`) with a `service.name` resource and batch processor, and returns the provider as a shutdown handle. `content_capture_mode()` reads the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` gate (default off). OTel deps pinned below 1.42 to keep Python 3.9 support.
+- Shared contract-against-the-pin conformance suite (`../conformance/fixtures.json`): spans built from the constants through the real SDK must emit the exact pinned keys.
+- Usage example in the README (runnable end-to-end in `examples/telemetry-python`).
+- `ratel_span_processor()` / `ratel_span_exporter()` + the default `ratel_signal_filter`: a composable OTLP span-processor for multi-provider coexistence. OpenTelemetry's model is one provider with many span-processors, so a partner already running one (e.g. Langfuse + the Vercel AI SDK) calls `provider.add_span_processor(ratel_span_processor(...))` to dual-export to Ratel — forwarding only the `gen_ai.*` / `ratel.*` signal (overridable via `span_filter`), so the framework's `ai.*` wrapper noise stays out of Ratel. Resolvable top-level via the lazy accessor (a plain `import ratel_ai_telemetry` still pulls no OTel).
+- A regression guard that a plain `import ratel_ai_telemetry` pulls no OpenTelemetry SDK.
+
+### Changed
+
+- The OpenTelemetry SDK is an optional `[otlp]` extra: importing `ratel_ai_telemetry` pulls no OTel SDK (ADR-0015), so the SDK (emit), the server (read), and edge/serverless emitters take the `ratel.*` vocabulary weight-free. `init()` lives in the `ratel_ai_telemetry.otlp` submodule (behind the extra) and raises a clear "install `ratel-ai-telemetry[otlp]`" error when it is absent; a lazy top-level accessor keeps `from ratel_ai_telemetry import init` working.
+- `init()` refactored onto `ratel_span_processor` (still exports every span — it owns the provider) and now raises, pointing at `ratel_span_processor`, when a `TracerProvider` is already registered globally, instead of silently no-op'ing.
+- Released as an independent PyPI unit under the `telemetry-py-v*` tag prefix.

ratel_ai_telemetry-0.1.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Agentified
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ratel_ai_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: ratel-ai-telemetry
+Version: 0.1.0
+Summary: Ratel telemetry conventions — the ratel.* overlay on OpenTelemetry gen_ai spans. init() helper and constants for the Ratel context engineering platform.
+Project-URL: Homepage, https://github.com/ratel-ai/ratel
+Project-URL: Repository, https://github.com/ratel-ai/ratel
+Project-URL: Issues, https://github.com/ratel-ai/ratel/issues
+Author: Agentified
+License: MIT License
+        
+        Copyright (c) 2025 Agentified
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE.md
+Keywords: ai-agents,gen-ai,observability,opentelemetry,ratel,telemetry
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: opentelemetry-api<1.42,>=1.41.0; extra == 'dev'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.42,>=1.41.0; extra == 'dev'
+Requires-Dist: opentelemetry-sdk<1.42,>=1.41.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-api<1.42,>=1.41.0; extra == 'otlp'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<1.42,>=1.41.0; extra == 'otlp'
+Requires-Dist: opentelemetry-sdk<1.42,>=1.41.0; extra == 'otlp'
+Description-Content-Type: text/markdown
+
+# `ratel-ai-telemetry` (Python)
+
+The `ratel.*` telemetry vocabulary for Python: the constants that codify the Tier 2 overlay
+of [`../CONVENTIONS.md`](../CONVENTIONS.md) (attribute keys, span/event names, the
+`Origin`/`SearchTarget`/`AuthOutcome` value enums, the pinned semconv version). **Importing
+the constants pulls no OpenTelemetry SDK** — the vocabulary stays weight-free for the SDK
+(emit side), the cloud (read side), and edge/serverless emitters
+([ADR-0007](../../../docs/adr/0007-telemetry-two-streams.md)). `init()` — turnkey OTLP
+exporter sugar over the standard OTel Python SDK — lives in the `ratel_ai_telemetry.otlp`
+submodule behind the optional `[otlp]` extra.
+
+## Usage
+
+```python
+from opentelemetry import trace
+from ratel_ai_telemetry import EXECUTE_TOOL, GEN_AI_OPERATION_NAME, GEN_AI_TOOL_NAME, RATEL_ORIGIN, Origin
+
+# Emit a standard gen_ai `execute_tool` span enriched with the ratel.* overlay,
+# on your own OTel provider — the constants alone, no extra needed.
+span = trace.get_tracer("my-agent").start_span(
+    EXECUTE_TOOL,
+    attributes={
+        GEN_AI_OPERATION_NAME: EXECUTE_TOOL,
+        GEN_AI_TOOL_NAME: "send_email",
+        RATEL_ORIGIN: Origin.AGENT.value,
+    },
+)
+span.end()
+```
+
+Want turnkey OTLP export to Ratel? Install `ratel-ai-telemetry[otlp]` and call `init()`:
+
+```python
+from ratel_ai_telemetry.otlp import init  # also importable as `from ratel_ai_telemetry import init`
+
+provider = init(api_key="sk-...")  # wires the OTLP exporter to RATEL_URL (or endpoint=/headers=)
+# ... emit spans ...
+provider.shutdown()  # flush the exporter on exit
+```
+
+`init()` owns the global provider, so it is the turnkey path for a greenfield app; it raises —
+pointing at `ratel_span_processor` — rather than silently no-op'ing if a provider is already
+registered. A complete, offline-runnable version (console exporter + a `ratel.search` →
+`execute_tool` trace) is in [`examples/telemetry-python`](../../../examples/telemetry-python/README.md).
+
+### Coexisting with another provider (Langfuse, the Vercel AI SDK, ...)
+
+OpenTelemetry's model is one provider with many span-processors. When a partner already owns the
+provider, add `ratel_span_processor` to it instead of calling `init()` — Ratel ingests only the
+`gen_ai.*` / `ratel.*` signal (the default `ratel_signal_filter`), dropping the framework's `ai.*`
+wrapper noise:
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from ratel_ai_telemetry.otlp import ratel_span_processor
+
+provider = TracerProvider()
+provider.add_span_processor(existing_langfuse_processor)              # keeps every span
+provider.add_span_processor(ratel_span_processor(api_key="sk-..."))  # gen_ai.*/ratel.* only
+```
+
+Pass `span_filter=lambda _s: True` (or your own predicate) to override the default;
+`ratel_span_exporter()` is the bare OTLP exporter if you want to wire your own processor.
+Note that per-span filtering can orphan the AI SDK's `ai.*` wrapper from its `gen_ai.*` child;
+send everything (or tail-sample) when you need full-trace fidelity rather than just the
+gen_ai/ratel metrics.
+
+## Package shape
+
+- Distribution name: `ratel-ai-telemetry`; import name: `ratel_ai_telemetry`
+- Pure Python (hatchling build, no Rust extension); OTel-free constants, `init()` behind the `[otlp]` extra
+- Targets Python >=3.9 (the `[otlp]` OTel deps are pinned below 1.42, the last line supporting 3.9)
+- Released under the `telemetry-py-v*` tag prefix ([ADR-0008](../../../docs/adr/0008-release-engineering.md))
+- MIT ([ADR-0009](../../../docs/adr/0009-licensing.md))
+
+## Build & test
+
+From this directory (needs [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv venv --python 3.11 .venv
+uv pip install --python .venv -e '.[dev]'
+.venv/bin/ruff check . && .venv/bin/mypy ratel_ai_telemetry && .venv/bin/pytest
+```
+
+Unlike the Python SDK there is no `maturin develop` step — the package is pure Python,
+installed editable (`[dev]` pulls the `[otlp]` extra so the tests exercise the real SDK).
+The tests cover the vocabulary (each constant asserted against the pin), `init()`'s
+endpoint/auth resolution, its already-registered guard and the content-capture gate, the
+`ratel_signal_filter` predicate and that `ratel_span_processor` forwards only the spans it
+passes, a purity guard that importing the package pulls no OTel, and the shared
+contract-against-the-pin conformance in
+[`../conformance/`](../conformance/README.md) (spans built from these constants through the
+real SDK must emit the exact pinned keys).

ratel_ai_telemetry-0.1.0/README.md

@@ -0,0 +1,94 @@
+# `ratel-ai-telemetry` (Python)
+
+The `ratel.*` telemetry vocabulary for Python: the constants that codify the Tier 2 overlay
+of [`../CONVENTIONS.md`](../CONVENTIONS.md) (attribute keys, span/event names, the
+`Origin`/`SearchTarget`/`AuthOutcome` value enums, the pinned semconv version). **Importing
+the constants pulls no OpenTelemetry SDK** — the vocabulary stays weight-free for the SDK
+(emit side), the cloud (read side), and edge/serverless emitters
+([ADR-0007](../../../docs/adr/0007-telemetry-two-streams.md)). `init()` — turnkey OTLP
+exporter sugar over the standard OTel Python SDK — lives in the `ratel_ai_telemetry.otlp`
+submodule behind the optional `[otlp]` extra.
+
+## Usage
+
+```python
+from opentelemetry import trace
+from ratel_ai_telemetry import EXECUTE_TOOL, GEN_AI_OPERATION_NAME, GEN_AI_TOOL_NAME, RATEL_ORIGIN, Origin
+
+# Emit a standard gen_ai `execute_tool` span enriched with the ratel.* overlay,
+# on your own OTel provider — the constants alone, no extra needed.
+span = trace.get_tracer("my-agent").start_span(
+    EXECUTE_TOOL,
+    attributes={
+        GEN_AI_OPERATION_NAME: EXECUTE_TOOL,
+        GEN_AI_TOOL_NAME: "send_email",
+        RATEL_ORIGIN: Origin.AGENT.value,
+    },
+)
+span.end()
+```
+
+Want turnkey OTLP export to Ratel? Install `ratel-ai-telemetry[otlp]` and call `init()`:
+
+```python
+from ratel_ai_telemetry.otlp import init  # also importable as `from ratel_ai_telemetry import init`
+
+provider = init(api_key="sk-...")  # wires the OTLP exporter to RATEL_URL (or endpoint=/headers=)
+# ... emit spans ...
+provider.shutdown()  # flush the exporter on exit
+```
+
+`init()` owns the global provider, so it is the turnkey path for a greenfield app; it raises —
+pointing at `ratel_span_processor` — rather than silently no-op'ing if a provider is already
+registered. A complete, offline-runnable version (console exporter + a `ratel.search` →
+`execute_tool` trace) is in [`examples/telemetry-python`](../../../examples/telemetry-python/README.md).
+
+### Coexisting with another provider (Langfuse, the Vercel AI SDK, ...)
+
+OpenTelemetry's model is one provider with many span-processors. When a partner already owns the
+provider, add `ratel_span_processor` to it instead of calling `init()` — Ratel ingests only the
+`gen_ai.*` / `ratel.*` signal (the default `ratel_signal_filter`), dropping the framework's `ai.*`
+wrapper noise:
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from ratel_ai_telemetry.otlp import ratel_span_processor
+
+provider = TracerProvider()
+provider.add_span_processor(existing_langfuse_processor)              # keeps every span
+provider.add_span_processor(ratel_span_processor(api_key="sk-..."))  # gen_ai.*/ratel.* only
+```
+
+Pass `span_filter=lambda _s: True` (or your own predicate) to override the default;
+`ratel_span_exporter()` is the bare OTLP exporter if you want to wire your own processor.
+Note that per-span filtering can orphan the AI SDK's `ai.*` wrapper from its `gen_ai.*` child;
+send everything (or tail-sample) when you need full-trace fidelity rather than just the
+gen_ai/ratel metrics.
+
+## Package shape
+
+- Distribution name: `ratel-ai-telemetry`; import name: `ratel_ai_telemetry`
+- Pure Python (hatchling build, no Rust extension); OTel-free constants, `init()` behind the `[otlp]` extra
+- Targets Python >=3.9 (the `[otlp]` OTel deps are pinned below 1.42, the last line supporting 3.9)
+- Released under the `telemetry-py-v*` tag prefix ([ADR-0008](../../../docs/adr/0008-release-engineering.md))
+- MIT ([ADR-0009](../../../docs/adr/0009-licensing.md))
+
+## Build & test
+
+From this directory (needs [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uv venv --python 3.11 .venv
+uv pip install --python .venv -e '.[dev]'
+.venv/bin/ruff check . && .venv/bin/mypy ratel_ai_telemetry && .venv/bin/pytest
+```
+
+Unlike the Python SDK there is no `maturin develop` step — the package is pure Python,
+installed editable (`[dev]` pulls the `[otlp]` extra so the tests exercise the real SDK).
+The tests cover the vocabulary (each constant asserted against the pin), `init()`'s
+endpoint/auth resolution, its already-registered guard and the content-capture gate, the
+`ratel_signal_filter` predicate and that `ratel_span_processor` forwards only the spans it
+passes, a purity guard that importing the package pulls no OTel, and the shared
+contract-against-the-pin conformance in
+[`../conformance/`](../conformance/README.md) (spans built from these constants through the
+real SDK must emit the exact pinned keys).

ratel_ai_telemetry-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ratel-ai-telemetry"
+version = "0.1.0"
+description = "Ratel telemetry conventions — the ratel.* overlay on OpenTelemetry gen_ai spans. init() helper and constants for the Ratel context engineering platform."
+readme = "README.md"
+license = { file = "LICENSE.md" }
+authors = [{ name = "Agentified" }]
+requires-python = ">=3.9"
+keywords = [
+    "telemetry",
+    "opentelemetry",
+    "observability",
+    "gen-ai",
+    "ai-agents",
+    "ratel",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Monitoring",
+]
+# The ratel.* vocabulary + the OTLP config/gate are pure Python and OTel-free
+# (ADR-0007), so importing the constants pulls no OpenTelemetry SDK. The SDK is an
+# optional [otlp] extra, needed only by init() (in ratel_ai_telemetry.otlp).
+dependencies = []
+
+[project.optional-dependencies]
+# init() is sugar over the standard OTel Python SDK (ADR-0007): no custom transport.
+# Pinned to the 1.41.x line and capped below 1.42, which drops Python 3.9 support
+# (this package targets >=3.9). semantic-conventions is not a direct dep: SERVICE_NAME
+# resolves to the literal "service.name" from opentelemetry-sdk.
+otlp = [
+    "opentelemetry-api>=1.41.0,<1.42",
+    "opentelemetry-sdk>=1.41.0,<1.42",
+    "opentelemetry-exporter-otlp-proto-http>=1.41.0,<1.42",
+]
+# dev pulls the [otlp] extra so the init() + conformance tests exercise the real SDK.
+dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11", "ratel-ai-telemetry[otlp]"]
+
+[project.urls]
+Homepage = "https://github.com/ratel-ai/ratel"
+Repository = "https://github.com/ratel-ai/ratel"
+Issues = "https://github.com/ratel-ai/ratel/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["ratel_ai_telemetry"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+# Runtime floor is 3.9; mypy's minimum supported target is 3.10, so we type-check
+# against that (matches the Python SDK).
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ratel_ai_telemetry-0.1.0/ratel_ai_telemetry/__init__.py

@@ -0,0 +1,229 @@
+"""`ratel-ai-telemetry` — the ratel.* telemetry vocabulary.
+
+See the wire contract in ../CONVENTIONS.md. Emitting the vocabulary is done through
+the standard OpenTelemetry Python SDK; this package adds no transport and no schema
+(ADR-0007). These constants are the ratel.* overlay Ratel owns, plus the small subset
+of gen_ai.* keys the overlay emits directly on the execute_tool span (borrowed verbatim
+from OpenTelemetry, never renamed).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Final
+
+#: The pinned OpenTelemetry semantic-conventions version this vocabulary tracks
+#: (the gen_ai group). The pin is the contract; consumers read against this exact
+#: version, never "latest" (CONVENTIONS.md § The pin).
+SEMCONV_VERSION: Final = "1.42.0"
+
+#: The ecosystem instrumentation env var gating message/tool content capture.
+#: Default off; honored by init() rather than a Ratel-invented flag
+#: (CONVENTIONS.md § Capture gating). Values: legacy boolean, or the enum
+#: NO_CONTENT (default) / SPAN_ONLY / EVENT_ONLY / SPAN_AND_EVENT.
+CAPTURE_CONTENT_ENV: Final = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
+
+# ---------------------------------------------------------------------------
+# Span names (CONVENTIONS.md, Tier 2)
+# ---------------------------------------------------------------------------
+
+#: ratel.search — capability search (unifies tool-search and skill-search).
+RATEL_SEARCH: Final = "ratel.search"
+
+#: execute_tool — the gen_ai.operation.name value for a tool invocation.
+#: Deliberately the standard OTel gen_ai operation, not a bespoke ratel.invoke span,
+#: so a generic OTel backend already understands it (locked 2026-07-05). The invoke
+#: is enriched with ratel.* attributes.
+EXECUTE_TOOL: Final = "execute_tool"
+
+#: ratel.skill.load — skill content load (get_skill_content).
+RATEL_SKILL_LOAD: Final = "ratel.skill.load"
+
+#: ratel.upstream.register — upstream-MCP ingest.
+RATEL_UPSTREAM_REGISTER: Final = "ratel.upstream.register"
+
+#: ratel.auth.flow — MCP auth flow.
+RATEL_AUTH_FLOW: Final = "ratel.auth.flow"
+
+# ---------------------------------------------------------------------------
+# Span event names (CONVENTIONS.md)
+# ---------------------------------------------------------------------------
+
+#: ratel.search.results — Opt-In event carrying hit ids + scores + per-stage BM25
+#: timing; gated like content. The ratel.search span itself carries only counts.
+RATEL_SEARCH_RESULTS: Final = "ratel.search.results"
+
+#: gen_ai.client.inference.operation.details — the event that carries message text
+#: and tool-call content (never span attributes). Borrowed from gen_ai (Tier 1).
+GEN_AI_INFERENCE_DETAILS: Final = "gen_ai.client.inference.operation.details"
+
+# ---------------------------------------------------------------------------
+# ratel.* attribute keys (CONVENTIONS.md, Tier 2)
+# ---------------------------------------------------------------------------
+
+#: ratel.origin — direct library call vs agent-synthesized (shared attribute).
+RATEL_ORIGIN: Final = "ratel.origin"
+
+#: ratel.search.target — "tool" or "skill" (see SearchTarget).
+RATEL_SEARCH_TARGET: Final = "ratel.search.target"
+
+#: ratel.search.top_k — requested result count.
+RATEL_SEARCH_TOP_K: Final = "ratel.search.top_k"
+
+#: ratel.search.hit_count — results returned.
+RATEL_SEARCH_HIT_COUNT: Final = "ratel.search.hit_count"
+
+#: ratel.search.query — the search text (content, gated like message content).
+RATEL_SEARCH_QUERY: Final = "ratel.search.query"
+
+#: ratel.tool.args_size_bytes — argument payload size on the execute_tool span.
+RATEL_TOOL_ARGS_SIZE_BYTES: Final = "ratel.tool.args_size_bytes"
+
+#: ratel.upstream.server — upstream MCP server backing a tool / auth flow.
+RATEL_UPSTREAM_SERVER: Final = "ratel.upstream.server"
+
+#: ratel.upstream.transport — "stdio" / "http" / "sse" / ...
+RATEL_UPSTREAM_TRANSPORT: Final = "ratel.upstream.transport"
+
+#: ratel.upstream.tool_count — tools ingested on register.
+RATEL_UPSTREAM_TOOL_COUNT: Final = "ratel.upstream.tool_count"
+
+#: ratel.skill.id — skill loaded on the ratel.skill.load span.
+RATEL_SKILL_ID: Final = "ratel.skill.id"
+
+#: ratel.auth.outcome — "ok" / "refreshed" / "needs_auth" / "failed" (see AuthOutcome).
+RATEL_AUTH_OUTCOME: Final = "ratel.auth.outcome"
+
+# ---------------------------------------------------------------------------
+# gen_ai.* interop keys (CONVENTIONS.md, Tier 1 — borrowed verbatim)
+#
+# Only the subset the ratel.* overlay directly emits on the execute_tool span.
+# These are OpenTelemetry's, not ours: exposed so callers avoid stringly-typing
+# them, never renamed into ratel.*.
+# ---------------------------------------------------------------------------
+
+#: gen_ai.operation.name — set to EXECUTE_TOOL for a tool invocation.
+GEN_AI_OPERATION_NAME: Final = "gen_ai.operation.name"
+
+#: gen_ai.tool.name — the capability tool id.
+GEN_AI_TOOL_NAME: Final = "gen_ai.tool.name"
+
+#: gen_ai.tool.call.id — tool call id, when available.
+GEN_AI_TOOL_CALL_ID: Final = "gen_ai.tool.call.id"
+
+#: gen_ai.tool.call.arguments — tool arguments (Opt-In content, gated).
+GEN_AI_TOOL_CALL_ARGUMENTS: Final = "gen_ai.tool.call.arguments"
+
+#: gen_ai.tool.call.result — tool result (Opt-In content, gated).
+GEN_AI_TOOL_CALL_RESULT: Final = "gen_ai.tool.call.result"
+
+
+class Origin(str, Enum):
+    """Whether a ratel.* span was a direct library call or synthesized by the agent
+    inside its loop. Carried by ratel.origin; mirrors the local trace Origin (ADR-0007).
+
+    A str-Enum: each member equals its exact wire string, so it is usable directly
+    as an OTel attribute value.
+    """
+
+    DIRECT = "direct"
+    AGENT = "agent"
+
+
+class SearchTarget(str, Enum):
+    """What a ratel.search span was searching. Carried by ratel.search.target; folds
+    capability-tool search and skill search into one span shape."""
+
+    TOOL = "tool"
+    SKILL = "skill"
+
+
+class AuthOutcome(str, Enum):
+    """Outcome of an MCP auth flow. Carried by ratel.auth.outcome; NEEDS_AUTH is the
+    401-driven AuthNeeds case (ADR-0007 auth_needs)."""
+
+    OK = "ok"
+    REFRESHED = "refreshed"
+    NEEDS_AUTH = "needs_auth"
+    FAILED = "failed"
+
+
+# The OTLP exporter surface (init() + config/gate) lives in the opt-in .otlp
+# submodule behind the [otlp] extra, so plain constant imports stay OTel-free
+# (ADR-0007). A module-level __getattr__ lazily resolves it, so the ergonomic
+# `from ratel_ai_telemetry import init` keeps working without eagerly importing it.
+_OTLP_EXPORTS: Final = frozenset(
+    {
+        "init",
+        "resolve_otlp_config",
+        "content_capture_mode",
+        "ContentCapture",
+        "OtlpConfig",
+        "ENDPOINT_ENV",
+        "DEFAULT_SERVICE_NAME",
+        "ratel_signal_filter",
+        "ratel_span_exporter",
+        "ratel_span_processor",
+        "SpanFilter",
+    }
+)
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily resolve the OTLP exporter surface from the opt-in .otlp submodule.
+
+    Keeps `from ratel_ai_telemetry import init` working while a plain
+    `import ratel_ai_telemetry` pulls no OpenTelemetry SDK. init() itself raises a
+    clear error if the [otlp] extra is not installed.
+    """
+    if name in _OTLP_EXPORTS:
+        from . import otlp
+
+        return getattr(otlp, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "CAPTURE_CONTENT_ENV",
+    "EXECUTE_TOOL",
+    "GEN_AI_INFERENCE_DETAILS",
+    "GEN_AI_OPERATION_NAME",
+    "GEN_AI_TOOL_CALL_ARGUMENTS",
+    "GEN_AI_TOOL_CALL_ID",
+    "GEN_AI_TOOL_CALL_RESULT",
+    "GEN_AI_TOOL_NAME",
+    "RATEL_AUTH_FLOW",
+    "RATEL_AUTH_OUTCOME",
+    "RATEL_ORIGIN",
+    "RATEL_SEARCH",
+    "RATEL_SEARCH_HIT_COUNT",
+    "RATEL_SEARCH_QUERY",
+    "RATEL_SEARCH_RESULTS",
+    "RATEL_SEARCH_TARGET",
+    "RATEL_SEARCH_TOP_K",
+    "RATEL_SKILL_ID",
+    "RATEL_SKILL_LOAD",
+    "RATEL_TOOL_ARGS_SIZE_BYTES",
+    "RATEL_UPSTREAM_REGISTER",
+    "RATEL_UPSTREAM_SERVER",
+    "RATEL_UPSTREAM_TOOL_COUNT",
+    "RATEL_UPSTREAM_TRANSPORT",
+    "SEMCONV_VERSION",
+    "AuthOutcome",
+    "Origin",
+    "SearchTarget",
+    # The OTLP exporter surface, lazily resolved from `.otlp` via __getattr__ above
+    # (importing any of these — or `import *` — loads the submodule but still no OTel
+    # SDK; only wiring an exporter needs the [otlp] extra).
+    "init",
+    "resolve_otlp_config",
+    "content_capture_mode",
+    "ContentCapture",
+    "OtlpConfig",
+    "ENDPOINT_ENV",
+    "DEFAULT_SERVICE_NAME",
+    "ratel_signal_filter",
+    "ratel_span_exporter",
+    "ratel_span_processor",
+    "SpanFilter",
+]

ratel_ai_telemetry-0.1.0/ratel_ai_telemetry/otlp.py

@@ -0,0 +1,235 @@
+"""The OTLP exporter surface over the standard OpenTelemetry Python SDK.
+
+Two entry points, no custom transport and no schema (ADR-0007, CONVENTIONS.md § init()
+surface):
+
+- ``init()`` — the turnkey greenfield path: wires an OTLP http/protobuf exporter and
+  registers a provider Ratel owns.
+- ``ratel_span_processor()`` / ``ratel_span_exporter()`` — compose Ratel onto a provider a
+  partner already owns (Langfuse, the Vercel AI SDK, ...), since OpenTelemetry's
+  coexistence model is one provider with many span-processors.
+
+The OpenTelemetry SDK is an optional ``[otlp]`` extra: this module imports it lazily, inside
+the functions that need it, so the config/gate helpers (``resolve_otlp_config``,
+``content_capture_mode``, ``ratel_signal_filter``) and this whole submodule import OTel-free.
+Only wiring an exporter needs the extra.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from . import CAPTURE_CONTENT_ENV
+
+if TYPE_CHECKING:
+    from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor, TracerProvider
+    from opentelemetry.sdk.trace.export import SpanExporter
+
+#: Env var whose value is the default OTLP endpoint when api_key= is used.
+ENDPOINT_ENV = "RATEL_URL"
+
+#: service.name used when the caller does not pass one.
+DEFAULT_SERVICE_NAME = "ratel"
+
+#: Raised when a function needs the OpenTelemetry SDK but the [otlp] extra is absent.
+_EXTRA_HINT = (
+    "ratel telemetry needs the OpenTelemetry SDK. Install the extra: "
+    "pip install 'ratel-ai-telemetry[otlp]'."
+)
+
+
+@dataclass(frozen=True)
+class OtlpConfig:
+    """Resolved exporter configuration; the pure core of init()."""
+
+    url: str
+    headers: dict[str, str]
+    service_name: str
+
+
+def resolve_otlp_config(
+    *,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    service_name: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> OtlpConfig:
+    """Resolve init() options into concrete exporter config.
+
+    Accepts either api_key= (endpoint defaults to RATEL_URL, Authorization: Bearer)
+    or endpoint=/headers= (custom endpoint / collector). The forms compose: an
+    explicit endpoint wins over RATEL_URL, and api_key adds the Bearer header on top
+    of any headers. env is injectable so the precedence is testable without a network.
+    """
+    resolved_env = os.environ if env is None else env
+    url = endpoint if endpoint is not None else resolved_env.get(ENDPOINT_ENV)
+    if not url:
+        raise ValueError(
+            f"ratel telemetry init: no endpoint. Pass endpoint= or set {ENDPOINT_ENV} "
+            "(use api_key= for Bearer auth)."
+        )
+    resolved_headers: dict[str, str] = dict(headers or {})
+    if api_key:
+        resolved_headers["Authorization"] = f"Bearer {api_key}"
+    return OtlpConfig(
+        url=url,
+        headers=resolved_headers,
+        service_name=service_name or DEFAULT_SERVICE_NAME,
+    )
+
+
+#: Predicate deciding whether a finished span is forwarded to Ratel.
+SpanFilter = Callable[["ReadableSpan"], bool]
+
+
+def ratel_signal_filter(span: ReadableSpan) -> bool:
+    """Default span filter: forward only signal-bearing spans — a ratel.* span name, or
+    any attribute key under gen_ai.* / ratel.*.
+
+    This is what lets Ratel share a provider with e.g. Langfuse + the Vercel AI SDK and
+    ingest only the gen_ai/ratel signal (the AI SDK's gen_ai.* spans + Ratel's own
+    ratel.search / execute_tool), dropping the framework's ai.* wrapper noise.
+    """
+    if span.name.startswith("ratel."):
+        return True
+    attributes = span.attributes or {}
+    return any(key.startswith("gen_ai.") or key.startswith("ratel.") for key in attributes)
+
+
+def _accept_all_spans(_span: ReadableSpan) -> bool:
+    """The filter init() uses: it owns the provider, so it exports every span."""
+    return True
+
+
+def ratel_span_exporter(
+    *,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    headers: Mapping[str, str] | None = None,
+) -> SpanExporter:
+    """Build the OTLP http/protobuf span exporter at the resolved Ratel endpoint.
+
+    The standalone exporter for callers wiring their own span-processor; ratel_span_processor
+    batches over it. Carries no resource — the caller's provider owns service.name. Needs the
+    [otlp] extra; raises a clear error otherwise.
+    """
+    try:
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(_EXTRA_HINT) from exc
+    cfg = resolve_otlp_config(api_key=api_key, endpoint=endpoint, headers=headers)
+    return OTLPSpanExporter(endpoint=cfg.url, headers=dict(cfg.headers))
+
+
+def ratel_span_processor(
+    *,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    span_filter: SpanFilter | None = None,
+) -> SpanProcessor:
+    """A BatchSpanProcessor over the Ratel OTLP exporter that forwards only the spans passing
+    span_filter (default ratel_signal_filter; pass ``lambda _s: True`` to forward everything).
+
+    Add it to your own provider (``provider.add_span_processor(ratel_span_processor(...))``) to
+    send Ratel telemetry alongside another provider — no global side effects, no resource.
+    Greenfield apps that want Ratel to own the provider should call init() instead. Needs the
+    [otlp] extra; raises a clear error otherwise.
+    """
+    try:
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(_EXTRA_HINT) from exc
+    active_filter = span_filter or ratel_signal_filter
+    exporter = ratel_span_exporter(api_key=api_key, endpoint=endpoint, headers=headers)
+
+    class _RatelSpanProcessor(BatchSpanProcessor):
+        def on_end(self, span: ReadableSpan) -> None:
+            if active_filter(span):
+                super().on_end(span)
+
+    return _RatelSpanProcessor(exporter)
+
+
+def init(
+    *,
+    api_key: str | None = None,
+    endpoint: str | None = None,
+    headers: Mapping[str, str] | None = None,
+    service_name: str | None = None,
+) -> TracerProvider:
+    """Wire an OTLP http/protobuf exporter + batch processor + service.name resource,
+    register it as the global tracer provider, and return it as the shutdown handle
+    (call provider.shutdown() / provider.force_flush()). Everything else is the
+    untouched OTel SDK.
+
+    init() owns the global provider, so it exports every span (unlike ratel_span_processor,
+    whose default gen_ai.*/ratel.* filter exists for sharing a provider). It raises — pointing
+    at ratel_span_processor — rather than silently no-op'ing, if a provider is already
+    registered globally. Needs the [otlp] extra; raises a clear error otherwise.
+    """
+    try:
+        from opentelemetry import trace
+        from opentelemetry.sdk.resources import SERVICE_NAME, Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.trace import ProxyTracerProvider
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(_EXTRA_HINT) from exc
+    # Resolve first so a missing endpoint raises ValueError before the guard.
+    cfg = resolve_otlp_config(
+        api_key=api_key, endpoint=endpoint, headers=headers, service_name=service_name
+    )
+    # get_tracer_provider() returns the default ProxyTracerProvider until someone installs a
+    # real one; a non-proxy means another provider already owns the global.
+    if not isinstance(trace.get_tracer_provider(), ProxyTracerProvider):
+        raise RuntimeError(
+            "ratel telemetry init(): an OpenTelemetry TracerProvider is already registered "
+            "globally, so init() (the turnkey path that owns the provider) cannot take over. "
+            "To send Ratel telemetry alongside an existing provider (e.g. Langfuse + the Vercel "
+            "AI SDK), add ratel_span_processor(api_key=...) to that provider instead of init()."
+        )
+    provider = TracerProvider(resource=Resource.create({SERVICE_NAME: cfg.service_name}))
+    provider.add_span_processor(
+        ratel_span_processor(
+            api_key=api_key, endpoint=endpoint, headers=headers, span_filter=_accept_all_spans
+        )
+    )
+    trace.set_tracer_provider(provider)
+    return provider
+
+
+class ContentCapture(str, Enum):
+    """Message/tool content capture modes for
+    OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (CONVENTIONS.md § Capture
+    gating). Default off.
+    """
+
+    NO_CONTENT = "NO_CONTENT"
+    SPAN_ONLY = "SPAN_ONLY"
+    EVENT_ONLY = "EVENT_ONLY"
+    SPAN_AND_EVENT = "SPAN_AND_EVENT"
+
+
+def content_capture_mode(env: Mapping[str, str] | None = None) -> ContentCapture:
+    """Parse the ecosystem content-capture gate. Defaults to NO_CONTENT when
+    unset/empty/unrecognized. The legacy boolean form maps true to full capture
+    (SPAN_AND_EVENT) and false to none.
+    """
+    resolved_env = os.environ if env is None else env
+    raw = resolved_env.get(CAPTURE_CONTENT_ENV)
+    if raw is None or raw.strip() == "":
+        return ContentCapture.NO_CONTENT
+    mapping = {
+        "NO_CONTENT": ContentCapture.NO_CONTENT,
+        "SPAN_ONLY": ContentCapture.SPAN_ONLY,
+        "EVENT_ONLY": ContentCapture.EVENT_ONLY,
+        "SPAN_AND_EVENT": ContentCapture.SPAN_AND_EVENT,
+        "TRUE": ContentCapture.SPAN_AND_EVENT,
+        "1": ContentCapture.SPAN_AND_EVENT,
+    }
+    return mapping.get(raw.strip().upper(), ContentCapture.NO_CONTENT)

ratel_ai_telemetry-0.1.0/tests/conftest.py

@@ -0,0 +1,22 @@
+"""Shared test fixtures for the telemetry helper."""
+
+from __future__ import annotations
+
+import pytest
+from opentelemetry import trace as trace_api
+from opentelemetry.util._once import Once
+
+
+def _reset_trace_globals() -> None:
+    # init()'s loud-fail guard throws when a provider is already registered, and OTel's
+    # global tracer provider is process-wide set-once — so reset it around every test to
+    # keep cases (and other test modules) from leaking a provider into each other.
+    trace_api._TRACER_PROVIDER_SET_ONCE = Once()
+    trace_api._TRACER_PROVIDER = None
+
+
+@pytest.fixture(autouse=True)
+def reset_trace_provider() -> object:
+    _reset_trace_globals()
+    yield
+    _reset_trace_globals()

ratel_ai_telemetry-0.1.0/tests/test_conformance.py

@@ -0,0 +1,108 @@
+"""Contract-against-the-pin conformance, driven by the shared ../../conformance/fixtures.json.
+
+Each fixture is built into a span from this helper's own ratel.* constants through the real
+OTel SDK; the emitted span must match the fixture's expected wire name + attributes exactly.
+The same fixtures drive the TS helper, so the two cannot drift.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from ratel_ai_telemetry import (
+    EXECUTE_TOOL,
+    GEN_AI_INFERENCE_DETAILS,
+    GEN_AI_OPERATION_NAME,
+    GEN_AI_TOOL_CALL_ARGUMENTS,
+    GEN_AI_TOOL_CALL_ID,
+    GEN_AI_TOOL_CALL_RESULT,
+    GEN_AI_TOOL_NAME,
+    RATEL_AUTH_FLOW,
+    RATEL_AUTH_OUTCOME,
+    RATEL_ORIGIN,
+    RATEL_SEARCH,
+    RATEL_SEARCH_HIT_COUNT,
+    RATEL_SEARCH_QUERY,
+    RATEL_SEARCH_RESULTS,
+    RATEL_SEARCH_TARGET,
+    RATEL_SEARCH_TOP_K,
+    RATEL_SKILL_ID,
+    RATEL_SKILL_LOAD,
+    RATEL_TOOL_ARGS_SIZE_BYTES,
+    RATEL_UPSTREAM_REGISTER,
+    RATEL_UPSTREAM_SERVER,
+    RATEL_UPSTREAM_TOOL_COUNT,
+    RATEL_UPSTREAM_TRANSPORT,
+    SEMCONV_VERSION,
+)
+
+_FIXTURES = json.loads(
+    (Path(__file__).resolve().parents[2] / "conformance" / "fixtures.json").read_text()
+)
+
+# Logical span id -> the span-name constant under test.
+SPAN_NAME = {
+    "execute_tool": EXECUTE_TOOL,
+    "ratel_search": RATEL_SEARCH,
+    "ratel_skill_load": RATEL_SKILL_LOAD,
+    "ratel_upstream_register": RATEL_UPSTREAM_REGISTER,
+    "ratel_auth_flow": RATEL_AUTH_FLOW,
+}
+
+# Logical attribute id -> the attribute-key constant under test.
+ATTR_KEY = {
+    "gen_ai_operation_name": GEN_AI_OPERATION_NAME,
+    "gen_ai_tool_name": GEN_AI_TOOL_NAME,
+    "gen_ai_tool_call_id": GEN_AI_TOOL_CALL_ID,
+    "gen_ai_tool_call_arguments": GEN_AI_TOOL_CALL_ARGUMENTS,
+    "gen_ai_tool_call_result": GEN_AI_TOOL_CALL_RESULT,
+    "ratel_origin": RATEL_ORIGIN,
+    "ratel_tool_args_size_bytes": RATEL_TOOL_ARGS_SIZE_BYTES,
+    "ratel_upstream_server": RATEL_UPSTREAM_SERVER,
+    "ratel_search_target": RATEL_SEARCH_TARGET,
+    "ratel_search_top_k": RATEL_SEARCH_TOP_K,
+    "ratel_search_hit_count": RATEL_SEARCH_HIT_COUNT,
+    "ratel_search_query": RATEL_SEARCH_QUERY,
+    "ratel_skill_id": RATEL_SKILL_ID,
+    "ratel_upstream_transport": RATEL_UPSTREAM_TRANSPORT,
+    "ratel_upstream_tool_count": RATEL_UPSTREAM_TOOL_COUNT,
+    "ratel_auth_outcome": RATEL_AUTH_OUTCOME,
+}
+
+# Logical event id -> the event-name constant under test.
+EVENT_NAME = {
+    "ratel_search_results": RATEL_SEARCH_RESULTS,
+    "gen_ai_inference_details": GEN_AI_INFERENCE_DETAILS,
+}
+
+
+def test_fixtures_share_the_pinned_semconv_version() -> None:
+    assert _FIXTURES["semconv_version"] == SEMCONV_VERSION
+
+
+@pytest.mark.parametrize("fixture", _FIXTURES["fixtures"], ids=lambda f: f["name"])
+def test_fixture_emits_pinned_keys(fixture: dict[str, Any]) -> None:
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    tracer = provider.get_tracer("conformance")
+
+    span = tracer.start_span(SPAN_NAME[fixture["span"]])
+    for field, value in fixture["set"].items():
+        span.set_attribute(ATTR_KEY[field], value)
+    for event in fixture.get("add_events", []):
+        span.add_event(EVENT_NAME[event])
+    span.end()
+
+    emitted = exporter.get_finished_spans()
+    assert len(emitted) == 1
+    assert emitted[0].name == fixture["expect_name"]
+    assert dict(emitted[0].attributes or {}) == fixture["expect_attributes"]
+    assert [e.name for e in emitted[0].events] == fixture.get("expect_events", [])

ratel_ai_telemetry-0.1.0/tests/test_constants.py

@@ -0,0 +1,147 @@
+"""Contract-against-the-pin tests for the ratel.* telemetry vocabulary.
+
+Each constant is asserted against the vocabulary pinned in ../CONVENTIONS.md.
+"""
+
+from ratel_ai_telemetry import (
+    CAPTURE_CONTENT_ENV,
+    EXECUTE_TOOL,
+    GEN_AI_INFERENCE_DETAILS,
+    GEN_AI_OPERATION_NAME,
+    GEN_AI_TOOL_CALL_ARGUMENTS,
+    GEN_AI_TOOL_CALL_ID,
+    GEN_AI_TOOL_CALL_RESULT,
+    GEN_AI_TOOL_NAME,
+    RATEL_AUTH_FLOW,
+    RATEL_AUTH_OUTCOME,
+    RATEL_ORIGIN,
+    RATEL_SEARCH,
+    RATEL_SEARCH_HIT_COUNT,
+    RATEL_SEARCH_QUERY,
+    RATEL_SEARCH_RESULTS,
+    RATEL_SEARCH_TARGET,
+    RATEL_SEARCH_TOP_K,
+    RATEL_SKILL_ID,
+    RATEL_SKILL_LOAD,
+    RATEL_TOOL_ARGS_SIZE_BYTES,
+    RATEL_UPSTREAM_REGISTER,
+    RATEL_UPSTREAM_SERVER,
+    RATEL_UPSTREAM_TOOL_COUNT,
+    RATEL_UPSTREAM_TRANSPORT,
+    SEMCONV_VERSION,
+    AuthOutcome,
+    Origin,
+    SearchTarget,
+)
+
+
+def test_pins_the_otel_gen_ai_semconv_version() -> None:
+    assert SEMCONV_VERSION == "1.42.0"
+
+
+def test_gates_content_capture_on_the_ecosystem_env_var() -> None:
+    assert CAPTURE_CONTENT_ENV == "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
+
+
+def test_names_the_ratel_spans_per_the_pin() -> None:
+    assert RATEL_SEARCH == "ratel.search"
+    assert RATEL_SKILL_LOAD == "ratel.skill.load"
+    assert RATEL_UPSTREAM_REGISTER == "ratel.upstream.register"
+    assert RATEL_AUTH_FLOW == "ratel.auth.flow"
+
+
+def test_names_the_span_events_per_the_pin() -> None:
+    assert RATEL_SEARCH_RESULTS == "ratel.search.results"
+    assert GEN_AI_INFERENCE_DETAILS == "gen_ai.client.inference.operation.details"
+
+
+def test_tool_invocation_is_gen_ai_execute_tool_not_ratel_invoke() -> None:
+    assert EXECUTE_TOOL == "execute_tool"
+    assert EXECUTE_TOOL != "ratel.invoke"
+
+
+def test_ratel_attribute_keys_match_the_pin() -> None:
+    assert RATEL_ORIGIN == "ratel.origin"
+    assert RATEL_SEARCH_TARGET == "ratel.search.target"
+    assert RATEL_SEARCH_TOP_K == "ratel.search.top_k"
+    assert RATEL_SEARCH_HIT_COUNT == "ratel.search.hit_count"
+    assert RATEL_SEARCH_QUERY == "ratel.search.query"
+    assert RATEL_TOOL_ARGS_SIZE_BYTES == "ratel.tool.args_size_bytes"
+    assert RATEL_UPSTREAM_SERVER == "ratel.upstream.server"
+    assert RATEL_UPSTREAM_TRANSPORT == "ratel.upstream.transport"
+    assert RATEL_UPSTREAM_TOOL_COUNT == "ratel.upstream.tool_count"
+    assert RATEL_SKILL_ID == "ratel.skill.id"
+    assert RATEL_AUTH_OUTCOME == "ratel.auth.outcome"
+
+
+def test_gen_ai_interop_keys_stay_under_gen_ai_never_renamed_into_ratel() -> None:
+    assert GEN_AI_OPERATION_NAME == "gen_ai.operation.name"
+    assert GEN_AI_TOOL_NAME == "gen_ai.tool.name"
+    assert GEN_AI_TOOL_CALL_ID == "gen_ai.tool.call.id"
+    assert GEN_AI_TOOL_CALL_ARGUMENTS == "gen_ai.tool.call.arguments"
+    assert GEN_AI_TOOL_CALL_RESULT == "gen_ai.tool.call.result"
+    for key in (
+        GEN_AI_OPERATION_NAME,
+        GEN_AI_TOOL_NAME,
+        GEN_AI_TOOL_CALL_ID,
+        GEN_AI_TOOL_CALL_ARGUMENTS,
+        GEN_AI_TOOL_CALL_RESULT,
+    ):
+        assert key.startswith("gen_ai.")
+        assert not key.startswith("ratel.")
+
+
+def test_every_ratel_attribute_key_is_namespaced() -> None:
+    for key in (
+        RATEL_ORIGIN,
+        RATEL_SEARCH_TARGET,
+        RATEL_SEARCH_TOP_K,
+        RATEL_SEARCH_HIT_COUNT,
+        RATEL_SEARCH_QUERY,
+        RATEL_TOOL_ARGS_SIZE_BYTES,
+        RATEL_UPSTREAM_SERVER,
+        RATEL_UPSTREAM_TRANSPORT,
+        RATEL_UPSTREAM_TOOL_COUNT,
+        RATEL_SKILL_ID,
+        RATEL_AUTH_OUTCOME,
+    ):
+        assert key.startswith("ratel.")
+
+
+def test_attribute_keys_are_unique() -> None:
+    keys = [
+        RATEL_ORIGIN,
+        RATEL_SEARCH_TARGET,
+        RATEL_SEARCH_TOP_K,
+        RATEL_SEARCH_HIT_COUNT,
+        RATEL_SEARCH_QUERY,
+        RATEL_TOOL_ARGS_SIZE_BYTES,
+        RATEL_UPSTREAM_SERVER,
+        RATEL_UPSTREAM_TRANSPORT,
+        RATEL_UPSTREAM_TOOL_COUNT,
+        RATEL_SKILL_ID,
+        RATEL_AUTH_OUTCOME,
+        GEN_AI_OPERATION_NAME,
+        GEN_AI_TOOL_NAME,
+        GEN_AI_TOOL_CALL_ID,
+        GEN_AI_TOOL_CALL_ARGUMENTS,
+        GEN_AI_TOOL_CALL_RESULT,
+    ]
+    assert len(set(keys)) == len(keys)
+
+
+def test_origin_maps_to_wire_strings() -> None:
+    assert Origin.DIRECT == "direct"
+    assert Origin.AGENT == "agent"
+
+
+def test_search_target_maps_to_wire_strings() -> None:
+    assert SearchTarget.TOOL == "tool"
+    assert SearchTarget.SKILL == "skill"
+
+
+def test_auth_outcome_maps_to_wire_strings() -> None:
+    assert AuthOutcome.OK == "ok"
+    assert AuthOutcome.REFRESHED == "refreshed"
+    assert AuthOutcome.NEEDS_AUTH == "needs_auth"
+    assert AuthOutcome.FAILED == "failed"

ratel_ai_telemetry-0.1.0/tests/test_import_purity.py

@@ -0,0 +1,24 @@
+"""Regression guard for the tree-shakeable split (ADR-0007).
+
+Importing the constants must not pull the OpenTelemetry SDK, so the SDK (emit
+side), the server (read side), and edge/serverless emitters take the `ratel.*`
+vocabulary weight-free. `init()` lives in the opt-in `ratel_ai_telemetry.otlp`
+submodule behind the `[otlp]` extra; plain `import ratel_ai_telemetry` stays clean.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+
+
+def test_importing_the_package_pulls_no_opentelemetry() -> None:
+    # A fresh interpreter, so OTel imported by other test modules can't leak in.
+    code = (
+        "import sys, ratel_ai_telemetry\n"
+        "otel = sorted(m for m in sys.modules "
+        "if m == 'opentelemetry' or m.startswith('opentelemetry.'))\n"
+        "assert not otel, f'constants import pulled OTel: {otel}'\n"
+    )
+    result = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr

ratel_ai_telemetry-0.1.0/tests/test_init.py

@@ -0,0 +1,104 @@
+"""Tests for the init() OTLP builder and its content-capture gate."""
+
+from __future__ import annotations
+
+import pytest
+
+from ratel_ai_telemetry.otlp import (
+    DEFAULT_SERVICE_NAME,
+    ENDPOINT_ENV,
+    ContentCapture,
+    content_capture_mode,
+    init,
+    resolve_otlp_config,
+)
+
+CONTENT_ENV = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
+
+
+class TestResolveOtlpConfig:
+    def test_api_key_form_uses_ratel_url_and_bearer_and_default_service(self) -> None:
+        cfg = resolve_otlp_config(
+            api_key="secret",
+            env={ENDPOINT_ENV: "https://collector.ratel.sh/v1/traces"},
+        )
+        assert cfg.url == "https://collector.ratel.sh/v1/traces"
+        assert cfg.headers["Authorization"] == "Bearer secret"
+        assert cfg.service_name == DEFAULT_SERVICE_NAME
+
+    def test_endpoint_headers_form_is_verbatim_without_authorization(self) -> None:
+        cfg = resolve_otlp_config(
+            endpoint="http://localhost:4318/v1/traces",
+            headers={"x-custom": "1"},
+            env={},
+        )
+        assert cfg.url == "http://localhost:4318/v1/traces"
+        assert cfg.headers == {"x-custom": "1"}
+        assert "Authorization" not in cfg.headers
+
+    def test_explicit_endpoint_wins_over_ratel_url(self) -> None:
+        cfg = resolve_otlp_config(
+            endpoint="https://explicit/v1/traces",
+            api_key="k",
+            env={ENDPOINT_ENV: "https://env/v1/traces"},
+        )
+        assert cfg.url == "https://explicit/v1/traces"
+        assert cfg.headers["Authorization"] == "Bearer k"
+
+    def test_custom_service_name_is_respected(self) -> None:
+        cfg = resolve_otlp_config(
+            endpoint="https://x/v1/traces", service_name="my-agent", env={}
+        )
+        assert cfg.service_name == "my-agent"
+
+    def test_raises_when_no_endpoint_and_no_ratel_url(self) -> None:
+        with pytest.raises(ValueError, match=ENDPOINT_ENV):
+            resolve_otlp_config(api_key="k", env={})
+
+
+class TestContentCaptureMode:
+    def test_defaults_to_no_content_when_unset_or_empty(self) -> None:
+        assert content_capture_mode(env={}) == ContentCapture.NO_CONTENT
+        assert content_capture_mode(env={CONTENT_ENV: ""}) == ContentCapture.NO_CONTENT
+
+    def test_parses_each_enum_value_case_insensitively(self) -> None:
+        assert content_capture_mode(env={CONTENT_ENV: "NO_CONTENT"}) == ContentCapture.NO_CONTENT
+        assert content_capture_mode(env={CONTENT_ENV: "span_only"}) == ContentCapture.SPAN_ONLY
+        assert content_capture_mode(env={CONTENT_ENV: "Event_Only"}) == ContentCapture.EVENT_ONLY
+        assert (
+            content_capture_mode(env={CONTENT_ENV: "SPAN_AND_EVENT"})
+            == ContentCapture.SPAN_AND_EVENT
+        )
+
+    def test_maps_the_legacy_boolean_form(self) -> None:
+        assert content_capture_mode(env={CONTENT_ENV: "true"}) == ContentCapture.SPAN_AND_EVENT
+        assert content_capture_mode(env={CONTENT_ENV: "false"}) == ContentCapture.NO_CONTENT
+
+
+class TestInit:
+    def test_returns_a_provider_with_shutdown(self) -> None:
+        provider = init(
+            api_key="k",
+            endpoint="http://localhost:4318/v1/traces",
+            service_name="test",
+        )
+        try:
+            assert callable(provider.shutdown)
+        finally:
+            provider.shutdown()
+
+    def test_raises_on_misconfiguration(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv(ENDPOINT_ENV, raising=False)
+        with pytest.raises(ValueError, match=ENDPOINT_ENV):
+            init(api_key="k")
+
+
+def test_top_level_lazy_accessor_resolves_the_otlp_surface() -> None:
+    """`from ratel_ai_telemetry import init` still works via the module __getattr__,
+    resolving to the same object as the .otlp submodule (ADR-0007 back-compat)."""
+    import ratel_ai_telemetry
+    from ratel_ai_telemetry.otlp import init as otlp_init
+    from ratel_ai_telemetry.otlp import resolve_otlp_config as otlp_resolve
+
+    assert ratel_ai_telemetry.init is otlp_init
+    assert ratel_ai_telemetry.resolve_otlp_config is otlp_resolve

ratel_ai_telemetry-0.1.0/tests/test_processor.py

@@ -0,0 +1,94 @@
+"""Tests for the composable OTLP span-processor (coexistence with another provider)."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from ratel_ai_telemetry.otlp import (
+    ENDPOINT_ENV,
+    init,
+    ratel_signal_filter,
+    ratel_span_exporter,
+    ratel_span_processor,
+)
+
+ENDPOINT = "http://localhost:4318/v1/traces"
+
+
+def span(name: str, attributes: dict[str, Any] | None = None) -> Any:
+    # The filter reads only a span's name + attribute keys, so a minimal shape suffices.
+    return SimpleNamespace(name=name, attributes=attributes or {})
+
+
+class TestRatelSignalFilter:
+    def test_forwards_ratel_named_spans(self) -> None:
+        assert ratel_signal_filter(span("ratel.search"))
+        assert ratel_signal_filter(span("ratel.skill.load"))
+
+    def test_forwards_spans_with_gen_ai_or_ratel_attributes(self) -> None:
+        assert ratel_signal_filter(span("execute_tool", {"gen_ai.operation.name": "execute_tool"}))
+        assert ratel_signal_filter(span("execute_tool", {"ratel.origin": "agent"}))
+        assert ratel_signal_filter(span("chat gpt-4o", {"gen_ai.request.model": "gpt-4o"}))
+
+    def test_drops_spans_without_the_signal(self) -> None:
+        assert not ratel_signal_filter(span("ai.generate_text", {"ai.model.id": "gpt-4o"}))
+        assert not ratel_signal_filter(span("GET /health"))
+
+
+class TestRatelSpanExporter:
+    def test_builds_an_otlp_exporter(self) -> None:
+        from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+        assert isinstance(ratel_span_exporter(endpoint=ENDPOINT), OTLPSpanExporter)
+
+    def test_raises_without_endpoint(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv(ENDPOINT_ENV, raising=False)
+        with pytest.raises(ValueError, match=ENDPOINT_ENV):
+            ratel_span_exporter(api_key="k")
+
+
+class TestRatelSpanProcessor:
+    def test_forwards_only_signal_bearing_spans_by_default(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        forwarded: list[str] = []
+        monkeypatch.setattr(BatchSpanProcessor, "on_end", lambda _self, s: forwarded.append(s.name))
+        proc = ratel_span_processor(endpoint=ENDPOINT)
+        proc.on_end(span("ratel.search"))
+        proc.on_end(span("execute_tool", {"gen_ai.operation.name": "execute_tool"}))
+        proc.on_end(span("ai.generate_text", {"ai.model.id": "gpt-4o"}))
+        proc.shutdown()
+        assert forwarded == ["ratel.search", "execute_tool"]
+
+    def test_respects_a_custom_filter(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+        forwarded: list[str] = []
+        monkeypatch.setattr(BatchSpanProcessor, "on_end", lambda _self, s: forwarded.append(s.name))
+        proc = ratel_span_processor(endpoint=ENDPOINT, span_filter=lambda _s: True)
+        proc.on_end(span("ai.generate_text", {"ai.model.id": "gpt-4o"}))
+        proc.shutdown()
+        assert forwarded == ["ai.generate_text"]
+
+
+class TestInitGuard:
+    def test_raises_pointing_at_the_processor_when_a_provider_is_registered(self) -> None:
+        from opentelemetry import trace
+        from opentelemetry.sdk.trace import TracerProvider
+
+        trace.set_tracer_provider(TracerProvider())
+        with pytest.raises(RuntimeError, match="ratel_span_processor"):
+            init(endpoint=ENDPOINT)
+
+
+def test_new_processor_surface_is_importable_top_level() -> None:
+    """The coexistence surface resolves through the lazy top-level accessor (ADR-0007)."""
+    import ratel_ai_telemetry
+    from ratel_ai_telemetry.otlp import ratel_span_processor as otlp_processor
+
+    assert ratel_ai_telemetry.ratel_span_processor is otlp_processor