failproofai 1.0.10 → 1.0.11-beta.0

package/.next/standalone/sdk/python/README.md

@@ -74,6 +74,47 @@ standard library. See `skill/references/frameworks.md` for the per-framework
 mapping, and `docs/` for a per-framework integration guide with runnable
 examples beside it.
 
+## OpenTelemetry (opt in)
+
+Already emitting OpenTelemetry spans? Install `opentelemetry-sdk` separately,
+then attach FailproofAI's exporter without changing your existing adapters:
+
+```bash
+pip install opentelemetry-sdk
+```
+
+```python
+import failproofai_sdk
+from opentelemetry.sdk.trace import TracerProvider
+
+provider = TracerProvider()
+failproofai_sdk.instrument("otel", provider=provider)
+tracer = provider.get_tracer("my-agent")
+with tracer.start_as_current_span(
+    "agent", attributes={"gen_ai.operation.name": "invoke_agent"}
+):
+    pass
+provider.force_flush()
+```
+
+Without a `provider`, `instrument("otel")` uses the registered provider or creates
+one if none exists. You can also pass `failproofai_sdk.OtelSpanExporter()` to your
+own `SimpleSpanProcessor` or `BatchSpanProcessor`. `uninstrument("otel")` disables
+only our processor and leaves your provider and other exporters unchanged.
+
+The exporter writes durable OTLP/JSON requests to
+`$FAILPROOFAI_HOME/state/spool-otlp`, otherwise `~/.failproofai/state/spool-otlp`.
+It never sends HTTP or reads a Cloud key. Connect the daemon with
+`failproofai config` and ask an admin to enable Settings → OpenTelemetry.
+SDK delivery needs no local TCP listener. `spool_dir` explicitly overrides the
+destination for tests or managed deployments; `configure(base_dir=...)` continues
+to control only the original event adapters.
+
+A bare `instrument()` never enables OTEL. OpenTelemetry is imported only when
+requested, and the SDK still declares zero hard runtime dependencies. Your
+instrumentation controls prompt/content attributes; inspect them before exporting
+sensitive data. Flush your provider before short-lived processes exit.
+
 ## Scopes
 
 The same identity layer, for code the adapters do not cover. `session_id` and

package/.next/standalone/sdk/python/docs/README.md

@@ -28,6 +28,7 @@ That is the whole integration.
 | CrewAI | [crewai/](crewai/) | [crewai/examples/](crewai/examples/) |
 | LlamaIndex | [llama_index/](llama_index/) | [llama_index/examples/](llama_index/examples/) |
 | Pydantic AI | [pydantic_ai/](pydantic_ai/) | [pydantic_ai/examples/](pydantic_ai/examples/) |
+| OpenTelemetry (opt in) | [otel/](otel/) | [otel/examples/](otel/examples/) |
 | **no framework** (your own agent) | [manual/](manual/) | [manual/examples/](manual/examples/) |
 
 Using something else — AutoGen, Haystack, Semantic Kernel, your own loop? Read

package/.next/standalone/sdk/python/docs/otel/README.md

@@ -0,0 +1,36 @@
+# OpenTelemetry spans
+
+Use `failproofai_sdk.instrument("otel", provider=provider)` to attach the optional
+OTLP/JSON exporter to your OpenTelemetry `TracerProvider`. Install
+`opentelemetry-sdk` in the application, not as a FailproofAI runtime dependency.
+`pip install 'failproofai-sdk[otel]'` is the optional convenience extra.
+
+```python
+import failproofai_sdk
+from opentelemetry.sdk.trace import TracerProvider
+
+provider = TracerProvider()
+failproofai_sdk.instrument("otel", provider=provider)
+with provider.get_tracer("my-agent").start_as_current_span(
+    "agent", attributes={"gen_ai.operation.name": "invoke_agent"}
+):
+    pass
+provider.force_flush()
+provider.shutdown()
+```
+
+The exporter publishes requests into the relay's spool. Run a connected
+`failproofaid` on the same machine; no auth header or exporter network setup is
+needed. An org admin must enable OpenTelemetry ingest in Cloud. Export related
+spans together and include the root agent span.
+
+You can also pass `failproofai_sdk.OtelSpanExporter()` to your existing span
+processor. Existing processors continue unchanged. `uninstrument("otel")` stops
+new exports from the processor installed by FailproofAI and leaves the provider
+registered. Prompt and response attributes are sent as supplied by your app.
+
+See the [SDK README](../../README.md#opentelemetry-opt-in) for spool overrides and
+the zero-dependency contract.
+
+Run [examples/quickstart.py](examples/quickstart.py) for one span, or
+[examples/agent_trace.py](examples/agent_trace.py) for an agent/model/tool trace.

package/.next/standalone/sdk/python/docs/otel/examples/agent_trace.py

@@ -0,0 +1,30 @@
+"""Export one related agent/model/tool trace through the local spool.
+
+pip install 'failproofai-sdk[otel]'
+python docs/otel/examples/agent_trace.py
+"""
+import failproofai_sdk
+from opentelemetry.sdk.trace import TracerProvider
+
+
+def main():
+    provider = TracerProvider()
+    failproofai_sdk.instrument("otel", provider=provider)
+    tracer = provider.get_tracer("planner")
+    with tracer.start_as_current_span(
+        "planner", attributes={"gen_ai.operation.name": "invoke_agent"}
+    ):
+        with tracer.start_as_current_span(
+            "model", attributes={"gen_ai.operation.name": "chat"}
+        ):
+            pass
+        with tracer.start_as_current_span(
+            "search", attributes={"gen_ai.operation.name": "execute_tool"}
+        ):
+            pass
+    provider.force_flush()
+    provider.shutdown()
+
+
+if __name__ == "__main__":
+    main()

package/.next/standalone/sdk/python/docs/otel/examples/quickstart.py

@@ -0,0 +1,22 @@
+"""An optional OTEL span, durably exported with no HTTP setup.
+
+pip install 'failproofai-sdk[otel]'
+python docs/otel/examples/quickstart.py
+"""
+import failproofai_sdk
+from opentelemetry.sdk.trace import TracerProvider
+
+
+def main():
+    provider = TracerProvider()
+    failproofai_sdk.instrument("otel", provider=provider)
+    with provider.get_tracer("my-agent").start_as_current_span(
+        "agent", attributes={"gen_ai.operation.name": "invoke_agent"}
+    ):
+        pass
+    provider.force_flush()
+    provider.shutdown()
+
+
+if __name__ == "__main__":
+    main()

package/.next/standalone/sdk/python/failproofai_sdk/__init__.py

@@ -38,6 +38,7 @@ __all__ = [
     "propagate",
     "instrument",
     "uninstrument",
+    "OtelSpanExporter",
     "_writer",
 ]
 
@@ -123,6 +124,13 @@ def uninstrument(framework: str | None = None):
     return _impl(framework)
 
 
+def __getattr__(name):
+    if name == "OtelSpanExporter":
+        from failproofai_sdk.integrations.otel import OtelSpanExporter
+        return OtelSpanExporter
+    raise AttributeError(name)
+
+
 # MUST be last: any `import failproofai_sdk.<sub>` binds the *module* onto this
 # package as `failproofai_sdk._writer`. Rebinding it here to the instance is what
 # keeps the published `failproofai_sdk._writer.flush_now()` recipe working — and

package/.next/standalone/sdk/python/failproofai_sdk/integrations/__init__.py

@@ -58,6 +58,7 @@ _REGISTRY: dict[str, str] = {
     "crewai": "failproofai_sdk.integrations.crewai",
     "llama_index": "failproofai_sdk.integrations.llama_index",
     "pydantic_ai": "failproofai_sdk.integrations.pydantic_ai",
+    "otel": "failproofai_sdk.integrations.otel",
 }
 
 # Spellings people actually type. LangGraph is served by the LangChain adapter
@@ -79,6 +80,8 @@ _DETECT: dict[str, tuple[str, ...]] = {
     "crewai": ("crewai",),
     "llama_index": ("llama_index", "llama_index.core"),
     "pydantic_ai": ("pydantic_ai",),
+    # OTEL is explicit-only: installing it must not duplicate existing adapters.
+    "otel": (),
 }
 
 # Guards _ACTIVE and every install/uninstall. `instrument()` is called from

package/.next/standalone/sdk/python/failproofai_sdk/integrations/otel.py

@@ -0,0 +1,189 @@
+"""Explicit OTLP/JSON exporter; disk only. OpenTelemetry is an optional runtime import."""
+import base64
+import json
+import logging
+import math
+import os
+import threading
+import uuid
+from pathlib import Path
+
+_MAX_BYTES = 8 * 1024 * 1024
+_METADATA = b'{"path":"/v1/traces","content_type":"application/json","encoding":null}\n'
+
+
+def _value(value):
+    if isinstance(value, bool):
+        return {"boolValue": value}
+    if isinstance(value, str):
+        return {"stringValue": value}
+    if isinstance(value, int):
+        return {"intValue": str(value)}
+    if isinstance(value, float):
+        return {"doubleValue": value if math.isfinite(value) else str(value)}
+    if isinstance(value, bytes):
+        return {"bytesValue": base64.b64encode(value).decode("ascii")}
+    if isinstance(value, (list, tuple)):
+        return {"arrayValue": {"values": [_value(v) for v in value]}}
+    if hasattr(value, "items"):
+        return {"kvlistValue": {"values": _attributes(value)}}
+    return {}
+
+
+def _attributes(attributes=None):
+    return [{"key": str(k), "value": _value(v)} for k, v in (attributes or {}).items() if v is not None]
+
+
+def _context(context):
+    result = {"traceId": f"{context.trace_id:032x}", "spanId": f"{context.span_id:016x}",
+              "flags": int(context.trace_flags)}
+    if context.trace_state:
+        result["traceState"] = context.trace_state.to_header()
+    return result
+
+
+def _resource_span(span):
+    data = _context(span.context)
+    if span.parent:
+        data["parentSpanId"] = f"{span.parent.span_id:016x}"
+    data.update({
+        "name": span.name, "kind": span.kind.value + 1,
+        "startTimeUnixNano": str(span.start_time), "endTimeUnixNano": str(span.end_time),
+        "attributes": _attributes(span.attributes),
+        "status": {"code": span.status.status_code.value, **({"message": span.status.description} if span.status.description else {})},
+        "droppedAttributesCount": span.dropped_attributes,
+        "droppedEventsCount": span.dropped_events, "droppedLinksCount": span.dropped_links,
+        "events": [{"name": event.name, "timeUnixNano": str(event.timestamp),
+                    "attributes": _attributes(event.attributes),
+                    "droppedAttributesCount": event.dropped_attributes} for event in span.events],
+        "links": [{**_context(link.context), "attributes": _attributes(link.attributes),
+                   "droppedAttributesCount": link.dropped_attributes} for link in span.links],
+    })
+    scope = span.instrumentation_scope
+    return {
+        "resource": {"attributes": _attributes(span.resource.attributes)},
+        **({"schemaUrl": span.resource.schema_url} if span.resource.schema_url else {}),
+        "scopeSpans": [{
+            "scope": {"name": scope.name if scope else "", **({"version": scope.version} if scope and scope.version else {})},
+            **({"schemaUrl": scope.schema_url} if scope and scope.schema_url else {}),
+            "spans": [data],
+        }],
+    }
+
+
+class OtelSpanExporter:
+    """Exports standard spans durably to the daemon's raw OTLP spool, never HTTP."""
+
+    def __init__(self, *, spool_dir=None):
+        self._directory = Path(spool_dir) if spool_dir is not None else None
+        self._stopped = False
+        self._lock = threading.Lock()
+
+    def export(self, spans):
+        from opentelemetry.sdk.trace.export import SpanExportResult
+        with self._lock:
+            if self._stopped:
+                return SpanExportResult.FAILURE
+            try:
+                directory = self._directory or Path(os.environ.get("FAILPROOFAI_HOME", Path.home() / ".failproofai")) / "state" / "spool-otlp"
+                items, chunks, size = [], [], 20
+                for span in spans:
+                    encoded = json.dumps(_resource_span(span), ensure_ascii=True, separators=(",", ":")).encode("utf8")
+                    if len(encoded) + 20 > _MAX_BYTES:
+                        raise ValueError("OTEL span exceeds the 8 MiB relay limit")
+                    if size + len(encoded) + 1 > _MAX_BYTES:
+                        chunks.append(b'{"resourceSpans":[' + b",".join(items) + b"]}")
+                        items, size = [], 20
+                    items.append(encoded)
+                    size += len(encoded) + 1
+                if items:
+                    chunks.append(b'{"resourceSpans":[' + b",".join(items) + b"]}")
+                for chunk in chunks:
+                    self._publish(directory, chunk)
+                return SpanExportResult.SUCCESS
+            except Exception:
+                logging.getLogger(__name__).warning("OTEL export failed; request was not published", exc_info=True)
+                return SpanExportResult.FAILURE
+
+    def _publish(self, directory, body):
+        directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        name = f"otlp-sdk-{uuid.uuid4()}"
+        temporary = directory / f".{name}.tmp"
+        try:
+            descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            with os.fdopen(descriptor, "wb") as stream:
+                stream.write(_METADATA + body)
+                stream.flush()
+                os.fsync(stream.fileno())
+            os.replace(temporary, directory / f"{name}.jsonl")
+            if os.name != "nt":
+                descriptor = os.open(directory, os.O_RDONLY)
+                try:
+                    os.fsync(descriptor)
+                finally:
+                    os.close(descriptor)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def shutdown(self):
+        with self._lock:
+            self._stopped = True
+
+    def force_flush(self, timeout_millis=30000):
+        return True
+
+
+class _Gate:
+    def __init__(self, processor):
+        self.processor = processor
+        self.enabled = True
+
+    def on_start(self, span, parent_context=None):
+        if self.enabled:
+            self.processor.on_start(span, parent_context=parent_context)
+
+    def on_end(self, span):
+        if self.enabled:
+            self.processor.on_end(span)
+
+    def _on_ending(self, span):
+        if self.enabled:
+            callback = getattr(self.processor, "_on_ending", None)
+            if callback:
+                callback(span)
+
+    def shutdown(self):
+        self.processor.shutdown()
+
+    def force_flush(self, timeout_millis=30000):
+        return self.processor.force_flush(timeout_millis) if self.enabled else True
+
+
+class _Adapter:
+    name = "otel"
+    module = "opentelemetry"
+
+    def __init__(self):
+        self.gate = None
+
+    def install(self, **options):
+        from opentelemetry import trace
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        provider = options.get("provider") or trace.get_tracer_provider()
+        if not hasattr(provider, "add_span_processor"):
+            if options.get("provider") is not None:
+                raise ValueError("OTEL provider must support add_span_processor()")
+            provider = TracerProvider()
+            trace.set_tracer_provider(provider)
+        self.gate = _Gate(BatchSpanProcessor(OtelSpanExporter(spool_dir=options.get("spool_dir"))))
+        provider.add_span_processor(self.gate)
+
+    def uninstall(self):
+        if self.gate:
+            self.gate.enabled = False
+            self.gate.shutdown()
+            self.gate = None
+
+
+adapter = _Adapter()

package/.next/standalone/sdk/python/pyproject.toml

@@ -50,7 +50,7 @@ Changelog = "https://github.com/FailproofAI/failproofai/blob/main/sdk/python/CHA
 # `tomli` is `tomllib`'s backport: 3.10 has no stdlib TOML parser, and that test
 # reads this file to prove the promise, so on 3.10 it needs one rather than
 # skipping the check on the oldest interpreter we advertise.
-dev = ["pytest>=7", "tomli>=2; python_version<'3.11'", "pytest-asyncio>=1.3,<2"]
+dev = ["pytest>=7", "tomli>=2; python_version<'3.11'", "pytest-asyncio>=1.3,<2", "opentelemetry-sdk>=1.39,<2"]
 
 # Convenience aliases that pull the FRAMEWORK in. The adapter code always ships
 # in the base wheel and lazy-imports, so these gate nothing on our side — most
@@ -72,6 +72,7 @@ crewai = [
 ]
 llamaindex = ["llama-index-core>=0.14.23,<0.15"]
 pydantic-ai = ["pydantic-ai-slim>=2.0,<3"]      # 2.0 removed Agent(instrument=...)
+otel = ["opentelemetry-sdk>=1.39,<2"]          # optional SpanExporter / processor APIs
 
 [tool.setuptools.dynamic]
 version = { attr = "failproofai_sdk._version.__version__" }

package/.next/standalone/sdk/python/tests/test_docs.py

@@ -40,6 +40,7 @@ ADAPTER_DIRS = {
     "crewai": "crewai",
     "llama_index": "llama_index",
     "pydantic_ai": "pydantic_ai",
+    "otel": "otel",
 }
 
 #: directory -> the failproofai-sdk extra its guide must name.
@@ -48,6 +49,7 @@ DIR_EXTRA = {
     "crewai": "crewai",
     "llama_index": "llamaindex",
     "pydantic_ai": "pydantic-ai",
+    "otel": "otel",
 }
 
 #: directory -> third-party modules its examples may import. `manual/` maps to
@@ -59,6 +61,7 @@ DIR_IMPORTS = {
     "llama_index": {"llama_index"},
     "pydantic_ai": {"pydantic_ai", "pydantic"},
     "manual": {"openai"},
+    "otel": {"opentelemetry"},
 }
 
 #: stdlib and local helpers every example may import. `_shared` is the trace
@@ -191,7 +194,12 @@ def test_a_framework_guide_names_its_own_extra(directory, extra):
 def test_a_framework_guide_shows_instrument_and_a_session(directory):
     text = (DOCS / directory / "README.md").read_text(encoding="utf-8")
     assert "failproofai_sdk.instrument(" in text, f"{directory} never shows instrument()"
-    assert "failproofai_sdk.session()" in text, f"{directory} never shows a session"
+    if directory == "otel":
+        # OTEL supplies trace identity itself, not the SDK event scopes.
+        assert 'instrument("otel"' in text
+        assert "start_as_current_span(" in text
+    else:
+        assert "failproofai_sdk.session()" in text, f"{directory} never shows a session"
 
 
 @pytest.mark.parametrize("guide", _guides(), ids=lambda p: p.parent.name)
@@ -285,7 +293,11 @@ def test_an_example_does_not_thread_identity_by_hand(path):
 @pytest.mark.parametrize("path", EXAMPLES, ids=EXAMPLE_IDS)
 def test_an_example_opens_a_session(path):
     source = path.read_text(encoding="utf-8")
-    assert "failproofai_sdk.session()" in source, f"{path.name} never opens a session"
+    if path.parents[1].name == "otel":
+        assert "start_as_current_span(" in source
+        assert '"gen_ai.operation.name": "invoke_agent"' in source
+    else:
+        assert "failproofai_sdk.session()" in source, f"{path.name} never opens a session"
 
 
 @pytest.mark.parametrize(
@@ -295,7 +307,8 @@ def test_an_example_opens_a_session(path):
 )
 def test_a_framework_example_instruments(path):
     source = path.read_text(encoding="utf-8")
-    assert "failproofai_sdk.instrument()" in source, f"{path.name} never instruments"
+    call = 'failproofai_sdk.instrument("otel",' if path.parents[1].name == "otel" else "failproofai_sdk.instrument()"
+    assert call in source, f"{path.name} never instruments"
 
 
 @pytest.mark.parametrize(

package/.next/standalone/sdk/python/tests/test_integrations.py

@@ -106,7 +106,7 @@ def fake(monkeypatch):
 def test_the_four_adapters_are_pre_registered():
     # Registered before their modules exist so that adding an adapter is one new
     # file, never an edit to the registry (which four agents would conflict on).
-    assert integrations.available() == ("crewai", "langchain", "llama_index", "pydantic_ai")
+    assert integrations.available() == ("crewai", "langchain", "llama_index", "otel", "pydantic_ai")
 
 
 @pytest.mark.parametrize(

package/.next/standalone/sdk/python/tests/test_otel.py

@@ -0,0 +1,147 @@
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor, SpanExportResult
+from opentelemetry.trace import Link, SpanKind, Status, StatusCode
+
+import failproofai_sdk
+from failproofai_sdk.integrations import _core
+
+
+def test_module_and_exporter_import_without_opentelemetry():
+    package_root = Path(failproofai_sdk.__file__).resolve().parent.parent
+    result = subprocess.run(
+        [sys.executable, "-I", "-S", "-c", f"""
+import importlib.abc
+import sys
+sys.path.insert(0, {str(package_root)!r})
+class AbsentOpenTelemetry(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path=None, target=None):
+        if fullname == "opentelemetry" or fullname.startswith("opentelemetry."):
+            raise ModuleNotFoundError("OpenTelemetry is not installed")
+sys.meta_path.insert(0, AbsentOpenTelemetry())
+from failproofai_sdk.integrations.otel import OtelSpanExporter
+import failproofai_sdk
+assert failproofai_sdk.OtelSpanExporter is OtelSpanExporter
+exporter = OtelSpanExporter()
+assert exporter.force_flush()
+exporter.shutdown()
+assert not any(name.startswith("opentelemetry") for name in sys.modules)
+print("Imported OTEL module and exporter without OpenTelemetry")
+"""],
+        capture_output=True, text=True, timeout=15,
+    )
+    assert result.returncode == 0, result.stderr
+    assert "without OpenTelemetry" in result.stdout
+
+
+@pytest.fixture(autouse=True)
+def enabled_otel(monkeypatch):
+    # The CrewAI test module disables its own vendor telemetry at collection.
+    # These tests explicitly exercise OTEL, without changing that other suite.
+    monkeypatch.delenv("OTEL_SDK_DISABLED", raising=False)
+
+
+def batches(home):
+    result = []
+    for file in (home / "state/spool-otlp").glob("*.jsonl"):
+        header, body = file.read_bytes().split(b"\n", 1)
+        assert json.loads(header) == {"path": "/v1/traces", "content_type": "application/json", "encoding": None}
+        assert file.stat().st_mode & 0o777 == 0o600
+        result.extend(json.loads(body)["resourceSpans"])
+    return result
+
+
+def test_real_spans_preserve_context_attributes_events_and_precise_time(tmp_path, monkeypatch):
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path))
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(failproofai_sdk.OtelSpanExporter()))
+    tracer = provider.get_tracer("scope", "1.0")
+    parent = tracer.start_span("agent", start_time=1780000000000000123)
+    child = tracer.start_span("chat", kind=SpanKind.CLIENT,
+                              context=trace.set_span_in_context(parent),
+                              start_time=1780000000000000456,
+                              attributes={"gen_ai.operation.name": "chat", "count": 42, "enabled": True, "values": ("a", "b")},
+                              links=[Link(parent.get_span_context(), attributes={"linked": True})])
+    child.add_event("prompt", {"text": "hi"}, timestamp=1780000000000000789)
+    child.set_status(Status(StatusCode.ERROR, "failed"))
+    child.end(end_time=1780000001000000012)
+    parent.end(end_time=1780000001000000013)
+    assert provider.force_flush()
+    output = next(span for resource in batches(tmp_path) for scope in resource["scopeSpans"]
+                  for span in scope["spans"] if span["name"] == "chat")
+    assert output["traceId"] == f"{child.get_span_context().trace_id:032x}"
+    assert output["parentSpanId"] == f"{parent.get_span_context().span_id:016x}"
+    assert output["kind"] == 3
+    assert output["startTimeUnixNano"] == "1780000000000000456"
+    assert output["endTimeUnixNano"] == "1780000001000000012"
+    assert output["status"] == {"code": 2, "message": "failed"}
+    assert {"key": "count", "value": {"intValue": "42"}} in output["attributes"]
+    assert output["events"][0]["timeUnixNano"] == "1780000000000000789"
+    assert output["links"][0]["spanId"] == f"{parent.get_span_context().span_id:016x}"
+    assert not list((tmp_path / "state/spool-otlp").glob("*.tmp"))
+    provider.shutdown()
+
+
+def test_exporter_reports_failures_and_shutdown(tmp_path):
+    file = tmp_path / "not-a-directory"
+    file.write_text("x")
+    exporter = failproofai_sdk.OtelSpanExporter(spool_dir=file)
+    provider = TracerProvider()
+    span = provider.get_tracer("app").start_span("test")
+    span.end()
+    assert exporter.export([span]) == SpanExportResult.FAILURE
+    exporter.shutdown()
+    assert exporter.export([]) == SpanExportResult.FAILURE
+    assert exporter.force_flush()
+    provider.shutdown()
+
+
+def test_batches_split_at_relay_limit(tmp_path, monkeypatch):
+    from opentelemetry.sdk.trace import SpanLimits
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path))
+    provider = TracerProvider(span_limits=SpanLimits(max_attribute_length=10_000_000))
+    span = provider.get_tracer("app").start_span("large", attributes={"content": "x" * (4 * 1024 * 1024)})
+    span.end()
+    assert failproofai_sdk.OtelSpanExporter().export([span, span]) == SpanExportResult.SUCCESS
+    assert len(list((tmp_path / "state/spool-otlp").glob("*.jsonl"))) == 2
+    assert len(batches(tmp_path)) == 2
+    provider.shutdown()
+
+
+def test_instrument_is_explicit_gated_and_keeps_other_processors(tmp_path, monkeypatch):
+    monkeypatch.setenv("FAILPROOFAI_HOME", str(tmp_path))
+    _core.set_strict(True)
+    provider = TracerProvider()
+    other = []
+
+    class Existing:
+        def on_start(self, *_args, **_kwargs): pass
+        def on_end(self, span): other.append(span.name)
+        def shutdown(self): pass
+        def force_flush(self, *_args): return True
+        def _on_ending(self, span): pass
+
+    provider.add_span_processor(Existing())
+    try:
+        assert "otel" not in failproofai_sdk.integrations._detected()
+        assert failproofai_sdk.instrument("otel", provider=provider) == ("otel",)
+        assert failproofai_sdk.instrument("otel", provider=provider) == ()
+        tracer = provider.get_tracer("app")
+        tracer.start_span("before").end()
+        assert provider.force_flush()
+        assert len(batches(tmp_path)) == 1
+        assert failproofai_sdk.uninstrument("otel") == ("otel",)
+        tracer.start_span("after").end()
+        assert provider.force_flush()
+        assert len(batches(tmp_path)) == 1
+        assert other == ["before", "after"]
+    finally:
+        failproofai_sdk.uninstrument("otel")
+        _core.set_strict(None)
+        provider.shutdown()

package/.next/standalone/sdk/python/tests/test_zero_dependencies.py

@@ -61,13 +61,14 @@ ADAPTER_IMPORTS = {
     "crewai.py": {"crewai"},
     "llama_index.py": {"llama_index", "llama_index_instrumentation", "pydantic"},
     "pydantic_ai.py": {"pydantic_ai"},
+    "otel.py": {"opentelemetry"},
 }
 
 #: Framework top-level names that must never appear in `sys.modules` after a bare
 #: `import failproofai_sdk`.
 FRAMEWORK_ROOTS = {
     "langchain", "langchain_core", "langgraph", "crewai",
-    "llama_index", "llama_index_instrumentation", "pydantic", "pydantic_ai",
+    "llama_index", "llama_index_instrumentation", "pydantic", "pydantic_ai", "opentelemetry",
 }
 
 
@@ -142,6 +143,7 @@ def test_no_runtime_dependencies_are_declared():
 #: convenience library drifting in — anything here is one `--extra dev` away from a
 #: user's environment, and none of it is covered by the zero-dependency promise.
 ALLOWED_DEV_DEPENDENCIES = {
+    "opentelemetry-sdk": "real optional OTEL SpanExporter and processor contract tests; never a base dependency",
     "pytest": "the test runner",
     "pytest-asyncio": "the adapters are half-async; their scopes are exercised "
                       "under `async with`, which needs an async test runner",
@@ -159,6 +161,7 @@ FRAMEWORK_EXTRAS = {
     "crewai": {"crewai", "onnxruntime"},
     "llamaindex": {"llama-index-core"},
     "pydantic-ai": {"pydantic-ai-slim"},
+    "otel": {"opentelemetry-sdk"},
 }