forgesight-otel 0.1.0__tar.gz

forgesight_otel-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.so
+
+# venv / tooling
+.venv/
+venv/
+.uv/
+uv.lock
+
+# test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# secrets / local env (never commit)
+.env
+.env.*
+
+# editor / OS
+.DS_Store
+.idea/
+.vscode/
+
+# local-only session working state (per the workspace pipeline)
+.claude/state/
+
+# local-only launch planning (not part of the published repo)
+/launch/

forgesight_otel-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: forgesight-otel
+Version: 0.1.0
+Summary: ForgeSight OpenTelemetry exporter — maps records to OTLP spans via the GenAI semantic conventions.
+Project-URL: Homepage, https://github.com/Scaffoldic/forgesight
+Project-URL: Repository, https://github.com/Scaffoldic/forgesight
+Project-URL: Issues, https://github.com/Scaffoldic/forgesight/issues
+Project-URL: Changelog, https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md
+Author: kjoshi
+License-Expression: Apache-2.0
+Keywords: ai-agents,forgesight,genai,observability,opentelemetry,otlp
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: forgesight-core
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
+Requires-Dist: opentelemetry-sdk>=1.27
+Provides-Extra: grpc
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.27; extra == 'grpc'
+Description-Content-Type: text/markdown
+
+# forgesight-otel
+
+The OpenTelemetry exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Maps ForgeSight `Record`s onto OTLP spans using the OpenTelemetry **GenAI semantic
+conventions** — so anything that ingests OTLP (Datadog, Honeycomb, Jaeger, Grafana
+Tempo, SigNoz, New Relic, Arize Phoenix) works with no additional package.
+
+```bash
+pip install forgesight-otel
+```
+
+```python
+import forgesight
+from forgesight_otel import OTelExporter
+
+forgesight.configure(exporters=[OTelExporter(endpoint="http://otel-collector:4318")])
+```
+
+Or enable by name via config (`exporters: [{name: otel, config: {...}}]`) — it
+registers under the `forgesight.exporters` entry point.
+
+- Provider discriminator: `gen_ai.provider.name` (legacy `gen_ai.system` opt-in).
+- Cost: emitted as the extension attribute `forgesight.usage.cost_usd` (OTel defines
+  no cost attribute).
+- Prompt/response content is **off by default** (`capture_content=True` to opt in).
+- gRPC transport: `pip install forgesight-otel[grpc]` + `protocol="grpc"`.
+
+## License
+
+Apache-2.0

forgesight_otel-0.1.0/README.md

@@ -0,0 +1,30 @@
+# forgesight-otel
+
+The OpenTelemetry exporter for [ForgeSight](https://github.com/Scaffoldic/forgesight).
+Maps ForgeSight `Record`s onto OTLP spans using the OpenTelemetry **GenAI semantic
+conventions** — so anything that ingests OTLP (Datadog, Honeycomb, Jaeger, Grafana
+Tempo, SigNoz, New Relic, Arize Phoenix) works with no additional package.
+
+```bash
+pip install forgesight-otel
+```
+
+```python
+import forgesight
+from forgesight_otel import OTelExporter
+
+forgesight.configure(exporters=[OTelExporter(endpoint="http://otel-collector:4318")])
+```
+
+Or enable by name via config (`exporters: [{name: otel, config: {...}}]`) — it
+registers under the `forgesight.exporters` entry point.
+
+- Provider discriminator: `gen_ai.provider.name` (legacy `gen_ai.system` opt-in).
+- Cost: emitted as the extension attribute `forgesight.usage.cost_usd` (OTel defines
+  no cost attribute).
+- Prompt/response content is **off by default** (`capture_content=True` to opt in).
+- gRPC transport: `pip install forgesight-otel[grpc]` + `protocol="grpc"`.
+
+## License
+
+Apache-2.0

forgesight_otel-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "forgesight-otel"
+version = "0.1.0"
+description = "ForgeSight OpenTelemetry exporter — maps records to OTLP spans via the GenAI semantic conventions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+authors = [{ name = "kjoshi" }]
+keywords = ["observability", "opentelemetry", "otlp", "ai-agents", "genai", "forgesight"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Topic :: System :: Monitoring",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+# Integration package: api/core + the OTel SDK + OTLP/http exporter. grpc is an extra.
+dependencies = [
+    "forgesight-core",
+    "opentelemetry-sdk>=1.27",
+    "opentelemetry-exporter-otlp-proto-http>=1.27",
+]
+
+[project.optional-dependencies]
+grpc = ["opentelemetry-exporter-otlp-proto-grpc>=1.27"]
+
+[project.entry-points."forgesight.exporters"]
+otel = "forgesight_otel.exporter:OTelExporter"
+
+[project.urls]
+Homepage = "https://github.com/Scaffoldic/forgesight"
+Repository = "https://github.com/Scaffoldic/forgesight"
+Issues = "https://github.com/Scaffoldic/forgesight/issues"
+Changelog = "https://github.com/Scaffoldic/forgesight/blob/main/docs/releases/v0.1.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/forgesight_otel"]
+
+[tool.uv.sources]
+forgesight-core = { workspace = true }

forgesight_otel-0.1.0/src/forgesight_otel/__init__.py

@@ -0,0 +1,19 @@
+"""ForgeSight OpenTelemetry exporter — OTLP spans via the GenAI semantic conventions."""
+
+from __future__ import annotations
+
+from .exporter import OTelExporter
+from .propagation import extract, inject
+from .semconv import SEMCONV_COMMIT, SEMCONV_VERSION, SemConvMapper
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "SEMCONV_COMMIT",
+    "SEMCONV_VERSION",
+    "OTelExporter",
+    "SemConvMapper",
+    "__version__",
+    "extract",
+    "inject",
+]

forgesight_otel-0.1.0/src/forgesight_otel/exporter.py

@@ -0,0 +1,150 @@
+"""``OTelExporter`` — a ForgeSight ``TelemetryExporter`` that ships OTLP spans.
+
+It runs on the export worker (feat-003), never the hot path. Each :class:`Record` is
+turned into an OTel :class:`~opentelemetry.sdk.trace.ReadableSpan` (carrying ForgeSight's
+own trace/span ids) and handed to an OTLP span exporter. ``export`` never raises (P6):
+on any failure it returns ``ExportResult.FAILURE``.
+
+For tests, inject a ``span_exporter`` (e.g. OTel's ``InMemorySpanExporter``); in
+production the OTLP exporter is built lazily from ``endpoint``/``protocol``/``headers``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from urllib.parse import urlsplit, urlunsplit
+
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.sdk.util.instrumentation import InstrumentationScope
+from opentelemetry.trace import SpanContext, TraceFlags
+from opentelemetry.trace.status import Status, StatusCode
+
+from forgesight_api import ExportResult, Record, RunStatus
+
+from .semconv import FORGESIGHT_SEMCONV_VERSION, SEMCONV_VERSION, SemConvMapper
+
+__version__ = "0.1.0"
+
+_DEFAULT_SERVICE_NAME = "forgesight-agent"
+_SAMPLED = TraceFlags(TraceFlags.SAMPLED)
+_OK_STATUSES = frozenset({RunStatus.OK, RunStatus.RUNNING})
+
+
+class OTelExporter:
+    """Maps ForgeSight records → OTLP spans via the GenAI semantic conventions."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str | None = None,
+        protocol: str = "http/protobuf",
+        service_name: str = _DEFAULT_SERVICE_NAME,
+        capture_content: bool = False,
+        emit_legacy_system: bool = False,
+        headers: dict[str, str] | None = None,
+        resource_attributes: dict[str, str] | None = None,
+        span_exporter: SpanExporter | None = None,
+    ) -> None:
+        self._mapper = SemConvMapper()
+        self._capture_content = capture_content
+        self._emit_legacy_system = emit_legacy_system
+        res: dict[str, str] = {
+            "service.name": service_name,
+            FORGESIGHT_SEMCONV_VERSION: SEMCONV_VERSION,
+        }
+        if resource_attributes:
+            res.update(resource_attributes)
+        self._resource = Resource.create(res)
+        self._scope = InstrumentationScope("forgesight", __version__)
+        self._span_exporter = span_exporter or self._build_span_exporter(
+            endpoint, protocol, headers
+        )
+
+    # --- TelemetryExporter Protocol --------------------------------------
+    def export(self, records: Sequence[Record]) -> ExportResult:
+        try:
+            spans = [self._to_readable_span(r) for r in records]
+            result = self._span_exporter.export(spans)
+        except Exception:  # defence in depth — export must never raise (P6)
+            return ExportResult.FAILURE
+        return ExportResult.SUCCESS if result is SpanExportResult.SUCCESS else ExportResult.FAILURE
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return self._span_exporter.force_flush(timeout_millis)
+
+    def shutdown(self, timeout_millis: int = 30_000) -> None:
+        self._span_exporter.shutdown()
+
+    # --- internals --------------------------------------------------------
+    def _to_readable_span(self, record: Record) -> ReadableSpan:
+        trace_id = int(record.trace_id, 16)
+        context = SpanContext(
+            trace_id=trace_id,
+            span_id=int(record.span_id, 16),
+            is_remote=False,
+            trace_flags=_SAMPLED,
+        )
+        parent = None
+        if record.parent_span_id is not None:
+            parent = SpanContext(
+                trace_id=trace_id,
+                span_id=int(record.parent_span_id, 16),
+                is_remote=False,
+                trace_flags=_SAMPLED,
+            )
+        attributes = self._mapper.attributes(
+            record,
+            capture_content=self._capture_content,
+            emit_legacy_system=self._emit_legacy_system,
+        )
+        return ReadableSpan(
+            name=self._mapper.span_name(record),
+            context=context,
+            parent=parent,
+            resource=self._resource,
+            attributes=attributes,
+            kind=self._mapper.span_kind(record),
+            status=_status(record.status),
+            start_time=record.start_unix_nanos,
+            end_time=record.end_unix_nanos,
+            instrumentation_scope=self._scope,
+        )
+
+    @staticmethod
+    def _build_span_exporter(
+        endpoint: str | None, protocol: str, headers: dict[str, str] | None
+    ) -> SpanExporter:
+        if protocol in ("http", "http/protobuf"):
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+            return OTLPSpanExporter(endpoint=_http_traces_endpoint(endpoint), headers=headers)
+        if protocol == "grpc":  # pragma: no cover - optional [grpc] extra
+            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (  # type: ignore[import-not-found]
+                OTLPSpanExporter as GrpcExporter,
+            )
+
+            return GrpcExporter(endpoint=endpoint, headers=headers)  # type: ignore[no-any-return]
+        raise ValueError(f"unknown protocol {protocol!r}; expected 'grpc' or 'http/protobuf'")
+
+
+def _http_traces_endpoint(endpoint: str | None) -> str | None:
+    """For OTLP/HTTP, append the ``/v1/traces`` signal path when the caller gave only a base
+    URL. The OTLP/HTTP exporter does NOT append it when ``endpoint`` is set explicitly, so
+    ``http://host:4318`` would 404; a path already present (a custom collector route) is kept.
+    ``None`` is returned unchanged so the OTel env-var defaults still apply."""
+    if endpoint is None:
+        return None
+    parsed = urlsplit(endpoint)
+    if parsed.path in ("", "/"):
+        return urlunsplit(parsed._replace(path="/v1/traces"))
+    return endpoint
+
+
+def _status(status: RunStatus) -> Status:
+    if status is RunStatus.OK:
+        return Status(StatusCode.OK)
+    if status in _OK_STATUSES:  # RUNNING (shouldn't reach export) ⇒ unset
+        return Status(StatusCode.UNSET)
+    return Status(StatusCode.ERROR, description=status.value)

forgesight_otel-0.1.0/src/forgesight_otel/propagation.py

@@ -0,0 +1,45 @@
+"""W3C TraceContext propagation helpers for cross-process / cross-agent hops.
+
+Used by A2A (feat-014) and MCP (feat-016) integrations to stitch one end-to-end trace
+across processes: the caller injects ``traceparent``/``tracestate`` from a ForgeSight
+trace/span id, the callee extracts them and opens its span as a child.
+"""
+
+from __future__ import annotations
+
+from opentelemetry.trace import (
+    NonRecordingSpan,
+    SpanContext,
+    TraceFlags,
+    get_current_span,
+    set_span_in_context,
+)
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+_PROP = TraceContextTextMapPropagator()
+_SAMPLED = TraceFlags(TraceFlags.SAMPLED)
+
+
+def inject(trace_id: str, span_id: str, carrier: dict[str, str] | None = None) -> dict[str, str]:
+    """Inject ``traceparent``/``tracestate`` for the given ids into a carrier dict."""
+    out: dict[str, str] = {} if carrier is None else carrier
+    context = set_span_in_context(
+        NonRecordingSpan(
+            SpanContext(
+                trace_id=int(trace_id, 16),
+                span_id=int(span_id, 16),
+                is_remote=False,
+                trace_flags=_SAMPLED,
+            )
+        )
+    )
+    _PROP.inject(out, context=context)
+    return out
+
+
+def extract(carrier: dict[str, str]) -> tuple[str, str] | None:
+    """Extract ``(trace_id_hex, span_id_hex)`` from a carrier, or ``None`` if absent."""
+    span_context = get_current_span(_PROP.extract(carrier)).get_span_context()
+    if not span_context.is_valid:
+        return None
+    return format(span_context.trace_id, "032x"), format(span_context.span_id, "016x")

forgesight_otel-0.1.0/src/forgesight_otel/semconv.py

@@ -0,0 +1,207 @@
+"""The single source of truth for ForgeSight's OTLP wire format.
+
+Maps a :class:`~forgesight_api.Record` onto a span name, an OTel ``SpanKind``, and the
+GenAI semantic-convention attribute set, per ``docs/design/otel-semantic-conventions.md``.
+Re-pinning the spec changes only this module (P5, ADR-0004).
+
+The conventions live in ``open-telemetry/semantic-conventions-genai`` and are all at
+``Development`` stability with no tagged release, so we pin to a commit and stamp the
+version on every span's Resource.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+
+from opentelemetry.trace import SpanKind
+from opentelemetry.util.types import AttributeValue
+
+from forgesight_api import Kind, Record, RunStatus
+
+# --- pinning ---------------------------------------------------------------
+SEMCONV_COMMIT = "open-telemetry/semantic-conventions-genai@main"
+SEMCONV_VERSION = "genai-dev-2026-06"
+
+# --- attribute keys (locked to the design doc) -----------------------------
+GEN_AI_OPERATION_NAME = "gen_ai.operation.name"
+GEN_AI_PROVIDER_NAME = "gen_ai.provider.name"
+GEN_AI_SYSTEM = "gen_ai.system"  # legacy; opt-in only
+GEN_AI_AGENT_NAME = "gen_ai.agent.name"
+GEN_AI_AGENT_VERSION = "gen_ai.agent.version"
+GEN_AI_CONVERSATION_ID = "gen_ai.conversation.id"
+GEN_AI_REQUEST_MODEL = "gen_ai.request.model"
+GEN_AI_REQUEST_PREFIX = "gen_ai.request."
+GEN_AI_RESPONSE_MODEL = "gen_ai.response.model"
+GEN_AI_RESPONSE_ID = "gen_ai.response.id"
+GEN_AI_RESPONSE_FINISH_REASONS = "gen_ai.response.finish_reasons"
+GEN_AI_RESPONSE_TTFC = "gen_ai.response.time_to_first_chunk"
+GEN_AI_USAGE_INPUT = "gen_ai.usage.input_tokens"
+GEN_AI_USAGE_OUTPUT = "gen_ai.usage.output_tokens"
+GEN_AI_USAGE_CACHE_READ = "gen_ai.usage.cache_read.input_tokens"
+GEN_AI_USAGE_CACHE_CREATION = "gen_ai.usage.cache_creation.input_tokens"
+GEN_AI_USAGE_REASONING = "gen_ai.usage.reasoning.output_tokens"
+GEN_AI_TOOL_NAME = "gen_ai.tool.name"
+GEN_AI_TOOL_TYPE = "gen_ai.tool.type"
+GEN_AI_TOOL_CALL_ID = "gen_ai.tool.call.id"
+GEN_AI_TOOL_DESCRIPTION = "gen_ai.tool.description"
+GEN_AI_INPUT_MESSAGES = "gen_ai.input.messages"
+GEN_AI_OUTPUT_MESSAGES = "gen_ai.output.messages"
+GEN_AI_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
+MCP_METHOD_NAME = "mcp.method.name"
+MCP_SESSION_ID = "mcp.session.id"
+MCP_PROTOCOL_VERSION = "mcp.protocol.version"
+ERROR_TYPE = "error.type"
+
+# extensions (namespaced — OTel defines none of these)
+FORGESIGHT_RUN_ID = "forgesight.run.id"
+FORGESIGHT_PARENT_RUN_ID = "forgesight.parent.run_id"
+FORGESIGHT_COST_USD = "forgesight.usage.cost_usd"
+FORGESIGHT_SEMCONV_VERSION = "forgesight.semconv_version"
+
+# operation.name values
+OP_INVOKE_AGENT = "invoke_agent"
+OP_INVOKE_WORKFLOW = "invoke_workflow"
+OP_CHAT = "chat"
+OP_EXECUTE_TOOL = "execute_tool"
+
+_MCP_TOOLS_CALL = "tools/call"
+# structured run fields that feat-002 stashes in Record.attributes → mapped to gen_ai.*
+_STRUCTURED = {
+    "agent.version": GEN_AI_AGENT_VERSION,
+    "context.id": GEN_AI_CONVERSATION_ID,
+    "parent.run_id": FORGESIGHT_PARENT_RUN_ID,
+}
+_OK_STATUSES = frozenset({RunStatus.OK, RunStatus.RUNNING})
+
+
+def _coerce(value: object) -> AttributeValue:
+    """Coerce an arbitrary value to a valid OTel attribute value."""
+    if isinstance(value, str | bool | int | float):
+        return value
+    if isinstance(value, list | tuple):
+        return [str(item) for item in value]
+    return str(value)
+
+
+class SemConvMapper:
+    """Pure Record → (span name, kind, attributes) mapping. No I/O, no OTel SDK state."""
+
+    def span_name(self, record: Record) -> str:
+        if record.kind is Kind.WORKFLOW:
+            return f"{OP_INVOKE_WORKFLOW} {record.name}"
+        if record.kind is Kind.AGENT:
+            return f"{OP_INVOKE_AGENT} {record.name}"
+        if record.kind is Kind.LLM:
+            return f"{OP_CHAT} {record.name}"
+        if record.kind is Kind.TOOL:
+            return f"{OP_EXECUTE_TOOL} {record.name}"
+        if record.kind is Kind.MCP and record.mcp is not None:
+            if record.mcp.method == _MCP_TOOLS_CALL and record.mcp.tool:
+                return f"{_MCP_TOOLS_CALL} {record.mcp.tool}"
+            return record.mcp.method
+        return record.name  # STEP (custom name)
+
+    def span_kind(self, record: Record) -> SpanKind:
+        if record.kind in (Kind.LLM, Kind.MCP):
+            return SpanKind.CLIENT
+        return SpanKind.INTERNAL
+
+    def attributes(
+        self, record: Record, *, capture_content: bool = False, emit_legacy_system: bool = False
+    ) -> dict[str, AttributeValue]:
+        attrs: dict[str, AttributeValue] = {FORGESIGHT_RUN_ID: record.run_id}
+        self._map_metadata(record.attributes, attrs)
+        if record.kind is Kind.AGENT:
+            attrs[GEN_AI_OPERATION_NAME] = OP_INVOKE_AGENT
+            attrs[GEN_AI_AGENT_NAME] = record.name
+        elif record.kind is Kind.WORKFLOW:
+            attrs[GEN_AI_OPERATION_NAME] = OP_INVOKE_WORKFLOW
+        elif record.kind is Kind.LLM and record.llm is not None:
+            self._map_llm(record, attrs, capture_content, emit_legacy_system)
+        elif record.kind is Kind.TOOL and record.tool is not None:
+            attrs[GEN_AI_OPERATION_NAME] = OP_EXECUTE_TOOL
+            attrs[GEN_AI_TOOL_NAME] = record.tool.name
+            attrs[GEN_AI_TOOL_TYPE] = record.tool.tool_type
+            if record.tool.call_id is not None:
+                attrs[GEN_AI_TOOL_CALL_ID] = record.tool.call_id
+            if record.tool.description is not None:
+                attrs[GEN_AI_TOOL_DESCRIPTION] = record.tool.description
+        elif record.kind is Kind.MCP and record.mcp is not None:
+            self._map_mcp(record, attrs)
+        if record.error is not None:
+            attrs[ERROR_TYPE] = record.error.error_type
+            if record.error.code is not None:
+                attrs["error.code"] = record.error.code
+        elif record.status not in _OK_STATUSES:
+            attrs[ERROR_TYPE] = record.status.value
+        return attrs
+
+    # --- helpers ----------------------------------------------------------
+    def _map_metadata(self, source: Mapping[str, object], attrs: dict[str, AttributeValue]) -> None:
+        for key, value in source.items():
+            mapped = _STRUCTURED.get(key)
+            attrs[mapped if mapped is not None else key] = _coerce(value)
+
+    def _map_llm(
+        self,
+        record: Record,
+        attrs: dict[str, AttributeValue],
+        capture_content: bool,
+        emit_legacy_system: bool,
+    ) -> None:
+        llm = record.llm
+        assert llm is not None
+        attrs[GEN_AI_OPERATION_NAME] = OP_CHAT
+        attrs[GEN_AI_PROVIDER_NAME] = llm.provider
+        if emit_legacy_system:
+            attrs[GEN_AI_SYSTEM] = llm.provider
+        attrs[GEN_AI_REQUEST_MODEL] = llm.request_model
+        if llm.response_model is not None:
+            attrs[GEN_AI_RESPONSE_MODEL] = llm.response_model
+        if llm.response_id is not None:
+            attrs[GEN_AI_RESPONSE_ID] = llm.response_id
+        usage = llm.usage
+        attrs[GEN_AI_USAGE_INPUT] = usage.input
+        attrs[GEN_AI_USAGE_OUTPUT] = usage.output
+        if usage.cache_read:
+            attrs[GEN_AI_USAGE_CACHE_READ] = usage.cache_read
+        if usage.cache_creation:
+            attrs[GEN_AI_USAGE_CACHE_CREATION] = usage.cache_creation
+        if usage.reasoning:
+            attrs[GEN_AI_USAGE_REASONING] = usage.reasoning
+        if llm.finish_reasons:
+            attrs[GEN_AI_RESPONSE_FINISH_REASONS] = list(llm.finish_reasons)
+        if llm.time_to_first_chunk_ms is not None:
+            attrs[GEN_AI_RESPONSE_TTFC] = llm.time_to_first_chunk_ms / 1000.0
+        if llm.cost_usd is not None:
+            attrs[FORGESIGHT_COST_USD] = llm.cost_usd
+        for key, value in llm.params.items():
+            attrs[f"{GEN_AI_REQUEST_PREFIX}{key}"] = _coerce(value)
+        if capture_content and llm.content is not None:
+            self._map_content(llm.content, attrs)
+
+    @staticmethod
+    def _map_content(content: object, attrs: dict[str, AttributeValue]) -> None:
+        # content is the experimental forgesight_api.Content container (P7-gated).
+        for field, key in (
+            ("input_messages", GEN_AI_INPUT_MESSAGES),
+            ("output_messages", GEN_AI_OUTPUT_MESSAGES),
+            ("system_instructions", GEN_AI_SYSTEM_INSTRUCTIONS),
+        ):
+            value = getattr(content, field, None)
+            if value is not None:
+                attrs[key] = json.dumps(value, default=str)
+
+    def _map_mcp(self, record: Record, attrs: dict[str, AttributeValue]) -> None:
+        mcp = record.mcp
+        assert mcp is not None
+        attrs[MCP_METHOD_NAME] = mcp.method
+        if mcp.session_id is not None:
+            attrs[MCP_SESSION_ID] = mcp.session_id
+        if mcp.protocol_version is not None:
+            attrs[MCP_PROTOCOL_VERSION] = mcp.protocol_version
+        if mcp.method == _MCP_TOOLS_CALL:
+            attrs[GEN_AI_OPERATION_NAME] = OP_EXECUTE_TOOL
+            if mcp.tool is not None:
+                attrs[GEN_AI_TOOL_NAME] = mcp.tool

forgesight_otel-0.1.0/tests/test_exporter.py

@@ -0,0 +1,147 @@
+"""Tests for OTelExporter: ReadableSpan construction, fault isolation, e2e."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import pytest
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.sdk.trace.export import SpanExportResult
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind
+from opentelemetry.trace.status import StatusCode
+
+from forgesight_api import ExportResult, Kind, LLMCall, Record, RunStatus, TokenUsage
+from forgesight_core import configure, reset_runtime, telemetry
+from forgesight_otel import OTelExporter
+from forgesight_otel.exporter import _http_traces_endpoint, _status
+
+TRACE = "4bf92f3577b34da6a3ce929d0e0e4736"
+
+
+def _llm_record(span: str, parent: str | None) -> Record:
+    return Record(
+        kind=Kind.LLM,
+        run_id="01J9Z3K7P8QF2R5V6W7X8Y9Z0A",
+        trace_id=TRACE,
+        span_id=span,
+        parent_span_id=parent,
+        name="claude-sonnet-4-5",
+        status=RunStatus.OK,
+        start_unix_nanos=1_000_000,
+        end_unix_nanos=3_000_000,
+        llm=LLMCall(
+            provider="anthropic",
+            request_model="claude-sonnet-4-5",
+            usage=TokenUsage(input=100, output=50),
+            cost_usd=0.01,
+        ),
+    )
+
+
+def test_export_builds_readable_spans_with_our_ids() -> None:
+    sink = InMemorySpanExporter()
+    exporter = OTelExporter(span_exporter=sink, service_name="t")
+    result = exporter.export([_llm_record("00f067aa0ba902b7", "0011223344556677")])
+    assert result is ExportResult.SUCCESS
+    spans = sink.get_finished_spans()
+    assert len(spans) == 1
+    span = spans[0]
+    assert span.name == "chat claude-sonnet-4-5"
+    assert span.kind is SpanKind.CLIENT
+    assert span.context is not None
+    assert format(span.context.trace_id, "032x") == TRACE
+    assert format(span.context.span_id, "016x") == "00f067aa0ba902b7"
+    assert span.parent is not None
+    assert format(span.parent.span_id, "016x") == "0011223344556677"
+    assert span.attributes is not None
+    assert span.attributes["gen_ai.provider.name"] == "anthropic"
+    assert span.attributes["forgesight.usage.cost_usd"] == 0.01
+    assert span.resource.attributes["forgesight.semconv_version"]
+
+
+def test_export_returns_failure_when_sink_returns_failure() -> None:
+    class FailSink(InMemorySpanExporter):
+        def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:  # type: ignore[override]
+            return SpanExportResult.FAILURE
+
+    exporter = OTelExporter(span_exporter=FailSink())
+    assert exporter.export([_llm_record("00f067aa0ba902b7", None)]) is ExportResult.FAILURE
+
+
+def test_export_never_raises() -> None:
+    class BoomSink(InMemorySpanExporter):
+        def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:  # type: ignore[override]
+            raise RuntimeError("otlp down")
+
+    exporter = OTelExporter(span_exporter=BoomSink())
+    assert exporter.export([_llm_record("00f067aa0ba902b7", None)]) is ExportResult.FAILURE
+
+
+def test_error_record_sets_error_span_status() -> None:
+    sink = InMemorySpanExporter()
+    exporter = OTelExporter(span_exporter=sink)
+    rec = Record(
+        kind=Kind.AGENT,
+        run_id="01J9Z3K7P8QF2R5V6W7X8Y9Z0A",
+        trace_id=TRACE,
+        span_id="00f067aa0ba902b7",
+        parent_span_id=None,
+        name="classifier",
+        status=RunStatus.ERROR,
+        start_unix_nanos=1,
+        end_unix_nanos=2,
+    )
+    exporter.export([rec])
+    span = sink.get_finished_spans()[0]
+    assert span.status.status_code is StatusCode.ERROR
+
+
+def test_status_mapping() -> None:
+    assert _status(RunStatus.OK).status_code is StatusCode.OK
+    assert _status(RunStatus.RUNNING).status_code is StatusCode.UNSET
+    assert _status(RunStatus.GUARDRAIL).status_code is StatusCode.ERROR
+
+
+def test_builds_http_exporter_and_shuts_down() -> None:
+    exporter = OTelExporter(protocol="http/protobuf", endpoint="http://localhost:4318")
+    assert exporter.force_flush() is True
+    exporter.shutdown()
+
+
+def test_unknown_protocol_raises() -> None:
+    with pytest.raises(ValueError, match="unknown protocol"):
+        OTelExporter(protocol="carrier-pigeon")
+
+
+def test_end_to_end_through_runtime() -> None:
+    sink = InMemorySpanExporter()
+    configure(exporters=[OTelExporter(span_exporter=sink)], sync_export=True)
+    try:
+        with telemetry.agent_run("issue-classifier", version="1.2.0") as run:
+            run.set_metadata(team="platform")
+            with run.step("react-1"), run.llm_call("anthropic", "claude-sonnet-4-5") as call:
+                call.record_usage(input=10, output=5)
+        names = sorted(s.name for s in sink.get_finished_spans())
+        assert names == ["chat claude-sonnet-4-5", "invoke_agent issue-classifier", "react-1"]
+        agent_span = next(s for s in sink.get_finished_spans() if s.name.startswith("invoke_agent"))
+        assert agent_span.attributes is not None
+        assert agent_span.attributes["team"] == "platform"
+        assert agent_span.attributes["gen_ai.agent.version"] == "1.2.0"
+    finally:
+        reset_runtime()
+
+
+def test_http_traces_endpoint_appends_signal_path() -> None:
+    # a base URL gets /v1/traces appended (OTLP/HTTP does not append it when endpoint is set)
+    assert _http_traces_endpoint("http://localhost:4318") == "http://localhost:4318/v1/traces"
+    assert _http_traces_endpoint("http://localhost:4318/") == "http://localhost:4318/v1/traces"
+    assert _http_traces_endpoint("https://otlp.example.com") == "https://otlp.example.com/v1/traces"
+    # an explicit path (a custom collector route) is left untouched
+    assert (
+        _http_traces_endpoint("http://localhost:4318/v1/traces")
+        == "http://localhost:4318/v1/traces"
+    )
+    assert _http_traces_endpoint("http://collector/custom/path") == "http://collector/custom/path"
+    # None defers to the OTel env-var defaults
+    assert _http_traces_endpoint(None) is None

forgesight_otel-0.1.0/tests/test_propagation.py

@@ -0,0 +1,28 @@
+"""Tests for W3C TraceContext inject/extract roundtrip."""
+
+from __future__ import annotations
+
+from forgesight_otel import extract, inject
+
+TRACE = "4bf92f3577b34da6a3ce929d0e0e4736"
+SPAN = "00f067aa0ba902b7"
+
+
+def test_inject_then_extract_roundtrips() -> None:
+    carrier = inject(TRACE, SPAN)
+    assert "traceparent" in carrier
+    assert TRACE in carrier["traceparent"]
+    result = extract(carrier)
+    assert result == (TRACE, SPAN)
+
+
+def test_extract_empty_carrier_is_none() -> None:
+    assert extract({}) is None
+
+
+def test_inject_into_existing_carrier() -> None:
+    carrier = {"x-custom": "keep"}
+    out = inject(TRACE, SPAN, carrier)
+    assert out is carrier
+    assert out["x-custom"] == "keep"
+    assert "traceparent" in out

forgesight_otel-0.1.0/tests/test_semconv.py

@@ -0,0 +1,226 @@
+"""Table-driven tests for the Record → GenAI semconv mapping."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+
+import pytest
+from opentelemetry.trace import SpanKind
+
+from forgesight_api import (
+    Content,
+    Kind,
+    LLMCall,
+    MCPCall,
+    Record,
+    RunStatus,
+    TokenUsage,
+    ToolCall,
+)
+from forgesight_otel.semconv import (
+    ERROR_TYPE,
+    FORGESIGHT_COST_USD,
+    FORGESIGHT_RUN_ID,
+    GEN_AI_AGENT_NAME,
+    GEN_AI_AGENT_VERSION,
+    GEN_AI_CONVERSATION_ID,
+    GEN_AI_INPUT_MESSAGES,
+    GEN_AI_OPERATION_NAME,
+    GEN_AI_PROVIDER_NAME,
+    GEN_AI_REQUEST_MODEL,
+    GEN_AI_RESPONSE_FINISH_REASONS,
+    GEN_AI_SYSTEM,
+    GEN_AI_TOOL_NAME,
+    GEN_AI_USAGE_CACHE_READ,
+    GEN_AI_USAGE_INPUT,
+    MCP_METHOD_NAME,
+    SemConvMapper,
+)
+
+MAPPER = SemConvMapper()
+TRACE = "4bf92f3577b34da6a3ce929d0e0e4736"
+SPAN = "00f067aa0ba902b7"
+
+
+def _record(kind: Kind, name: str, **kw: object) -> Record:
+    return Record(
+        kind=kind,
+        run_id="01J9Z3K7P8QF2R5V6W7X8Y9Z0A",
+        trace_id=TRACE,
+        span_id=SPAN,
+        parent_span_id=kw.pop("parent_span_id", None),  # type: ignore[arg-type]
+        name=name,
+        status=kw.pop("status", RunStatus.OK),  # type: ignore[arg-type]
+        start_unix_nanos=1_000_000,
+        end_unix_nanos=3_000_000,
+        attributes=MappingProxyType(kw.pop("attributes", {})),  # type: ignore[arg-type]
+        llm=kw.pop("llm", None),  # type: ignore[arg-type]
+        tool=kw.pop("tool", None),  # type: ignore[arg-type]
+        mcp=kw.pop("mcp", None),  # type: ignore[arg-type]
+        error=kw.pop("error", None),  # type: ignore[arg-type]
+    )
+
+
+def test_span_names_and_kinds() -> None:
+    cases = [
+        (_record(Kind.WORKFLOW, "nightly"), "invoke_workflow nightly", SpanKind.INTERNAL),
+        (_record(Kind.AGENT, "classifier"), "invoke_agent classifier", SpanKind.INTERNAL),
+        (_record(Kind.STEP, "react-1"), "react-1", SpanKind.INTERNAL),
+        (
+            _record(Kind.LLM, "claude", llm=LLMCall(provider="anthropic", request_model="claude")),
+            "chat claude",
+            SpanKind.CLIENT,
+        ),
+        (
+            _record(Kind.TOOL, "search", tool=ToolCall(name="search")),
+            "execute_tool search",
+            SpanKind.INTERNAL,
+        ),
+        (
+            _record(
+                Kind.MCP, "tools/call", mcp=MCPCall(server="f", method="tools/call", tool="rd")
+            ),
+            "tools/call rd",
+            SpanKind.CLIENT,
+        ),
+        (
+            _record(Kind.MCP, "tools/list", mcp=MCPCall(server="f", method="tools/list")),
+            "tools/list",
+            SpanKind.CLIENT,
+        ),
+    ]
+    for record, name, kind in cases:
+        assert MAPPER.span_name(record) == name
+        assert MAPPER.span_kind(record) == kind
+
+
+def test_agent_attributes_and_structured_metadata() -> None:
+    rec = _record(
+        Kind.AGENT,
+        "classifier",
+        attributes={"agent.version": "1.2.0", "context.id": "sess-9", "team": "platform"},
+    )
+    attrs = MAPPER.attributes(rec)
+    assert attrs[GEN_AI_OPERATION_NAME] == "invoke_agent"
+    assert attrs[GEN_AI_AGENT_NAME] == "classifier"
+    assert attrs[GEN_AI_AGENT_VERSION] == "1.2.0"
+    assert attrs[GEN_AI_CONVERSATION_ID] == "sess-9"
+    assert attrs["team"] == "platform"  # business metadata passes through
+    assert attrs[FORGESIGHT_RUN_ID] == rec.run_id
+
+
+def test_llm_attributes_cost_is_extension_not_gen_ai() -> None:
+    llm = LLMCall(
+        provider="anthropic",
+        request_model="claude-sonnet-4-5",
+        usage=TokenUsage(input=100, output=50, cache_read=10),
+        cost_usd=0.0123,
+        finish_reasons=("stop",),
+    )
+    attrs = MAPPER.attributes(_record(Kind.LLM, "claude-sonnet-4-5", llm=llm))
+    assert attrs[GEN_AI_PROVIDER_NAME] == "anthropic"
+    assert attrs[GEN_AI_REQUEST_MODEL] == "claude-sonnet-4-5"
+    assert attrs[GEN_AI_USAGE_INPUT] == 100
+    assert attrs[GEN_AI_USAGE_CACHE_READ] == 10
+    assert attrs[GEN_AI_RESPONSE_FINISH_REASONS] == ["stop"]
+    assert attrs[FORGESIGHT_COST_USD] == 0.0123
+    assert "gen_ai.usage.cost" not in attrs
+    assert "gen_ai.usage.cost_usd" not in attrs
+    assert GEN_AI_SYSTEM not in attrs  # legacy off by default
+
+
+def test_legacy_system_opt_in() -> None:
+    llm = LLMCall(provider="openai", request_model="gpt")
+    attrs = MAPPER.attributes(_record(Kind.LLM, "gpt", llm=llm), emit_legacy_system=True)
+    assert attrs[GEN_AI_SYSTEM] == "openai"
+
+
+def test_content_gating() -> None:
+    llm = LLMCall(
+        provider="anthropic",
+        request_model="m",
+        content=Content(input_messages=[{"role": "user", "text": "hi"}]),
+    )
+    off = MAPPER.attributes(_record(Kind.LLM, "m", llm=llm), capture_content=False)
+    assert GEN_AI_INPUT_MESSAGES not in off
+    on = MAPPER.attributes(_record(Kind.LLM, "m", llm=llm), capture_content=True)
+    assert "user" in str(on[GEN_AI_INPUT_MESSAGES])
+
+
+def test_mcp_tools_call_maps_to_execute_tool() -> None:
+    mcp = MCPCall(server="files", method="tools/call", tool="read_file", session_id="s1")
+    attrs = MAPPER.attributes(_record(Kind.MCP, "tools/call", mcp=mcp))
+    assert attrs[MCP_METHOD_NAME] == "tools/call"
+    assert attrs[GEN_AI_OPERATION_NAME] == "execute_tool"
+    assert attrs[GEN_AI_TOOL_NAME] == "read_file"
+
+
+def test_tool_attributes() -> None:
+    tool = ToolCall(name="search", tool_type="function", call_id="c1", description="web search")
+    attrs = MAPPER.attributes(_record(Kind.TOOL, "search", tool=tool))
+    assert attrs[GEN_AI_TOOL_NAME] == "search"
+    assert attrs[GEN_AI_OPERATION_NAME] == "execute_tool"
+
+
+def test_error_status_sets_error_type() -> None:
+    attrs = MAPPER.attributes(_record(Kind.AGENT, "a", status=RunStatus.ERROR))
+    assert attrs[ERROR_TYPE] == "error"
+    budget = MAPPER.attributes(_record(Kind.AGENT, "a", status=RunStatus.BUDGET_EXCEEDED))
+    assert budget[ERROR_TYPE] == "budget_exceeded"
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        (1, 1),
+        (1.5, 1.5),
+        (True, True),
+        ("s", "s"),
+        (("a", "b"), ["a", "b"]),
+        ({"x": 1}, "{'x': 1}"),
+    ],
+)
+def test_coerce_via_metadata(value: object, expected: object) -> None:
+    attrs = MAPPER.attributes(_record(Kind.STEP, "s", attributes={"k": value}))
+    assert attrs["k"] == expected
+
+
+def test_llm_full_optional_fields() -> None:
+    llm = LLMCall(
+        provider="anthropic",
+        request_model="m",
+        response_model="m-2",
+        response_id="r1",
+        usage=TokenUsage(input=1, output=2, cache_creation=3, reasoning=4),
+        time_to_first_chunk_ms=120.0,
+        params={"temperature": 0.2},
+    )
+    attrs = MAPPER.attributes(_record(Kind.LLM, "m", llm=llm))
+    assert attrs["gen_ai.response.model"] == "m-2"
+    assert attrs["gen_ai.response.id"] == "r1"
+    assert attrs["gen_ai.usage.cache_creation.input_tokens"] == 3
+    assert attrs["gen_ai.usage.reasoning.output_tokens"] == 4
+    assert attrs["gen_ai.response.time_to_first_chunk"] == 0.12
+    assert attrs["gen_ai.request.temperature"] == 0.2
+
+
+def test_mcp_session_and_protocol_attributes() -> None:
+    mcp = MCPCall(server="f", method="tools/list", session_id="s1", protocol_version="2025-06-18")
+    attrs = MAPPER.attributes(_record(Kind.MCP, "tools/list", mcp=mcp))
+    assert attrs["mcp.session.id"] == "s1"
+    assert attrs["mcp.protocol.version"] == "2025-06-18"
+
+
+def test_error_info_maps_to_error_type_and_code() -> None:
+    from forgesight_api import ErrorInfo
+
+    rec = _record(
+        Kind.LLM,
+        "m",
+        status=RunStatus.ERROR,
+        llm=LLMCall(provider="anthropic", request_model="m"),
+        error=ErrorInfo(error_type="RateLimitError", message="429", code="rate_limited"),
+    )
+    attrs = MAPPER.attributes(rec)
+    assert attrs[ERROR_TYPE] == "RateLimitError"  # exception class, not the status value
+    assert attrs["error.code"] == "rate_limited"