spanweave 0.9.0__py3-none-any.whl

spanweave/__init__.py

@@ -0,0 +1,77 @@
+"""spanweave — agentic-system telemetry into a deterministic, neutral graph.
+
+The public API is exactly what this module exports; everything else is
+internal and may be refactored freely (``CLAUDE.md``).
+
+The library reads trace files and writes a graph. It assigns no roles, no
+judgement, and no domain interpretation of any kind (``SPEC.md`` §1).
+
+The error types are part of that surface. ``SPEC.md`` §3.10 tells callers to
+match on an error's ``code`` and never on its message; until a caller can write
+``except SpanweaveError`` and read ``.code``, that instruction is impossible to
+obey through the public API, and the only alternative is ``except Exception``
+plus ``getattr(error, "code", None)`` -- which puts a missing file, a
+permissions error and a trace the library deliberately refused in the same
+branch. Found by the Phase 2b consumer (`TASKS.md` F4), which had written
+exactly that workaround.
+"""
+
+from spanweave.annotate import Annotation, AnnotationStore
+from spanweave.api import build
+from spanweave.errors import (
+    AdapterSelectionError,
+    DuplicateNodeIdError,
+    SpanweaveError,
+    UnknownAdapterError,
+)
+from spanweave.graph import Graph
+from spanweave.model import (
+    Diagnostic,
+    DiagnosticLevel,
+    Edge,
+    EdgeKind,
+    Meta,
+    Node,
+    NodeKind,
+    Payload,
+    PayloadState,
+    Provenance,
+    RawRecord,
+    Status,
+    Usage,
+    Warrant,
+)
+from spanweave.serialize import dump, dumps, to_document, validate
+from spanweave.version import SCHEMA_FROZEN, SCHEMA_VERSION, __version__
+
+__all__ = [
+    "SCHEMA_FROZEN",
+    "SCHEMA_VERSION",
+    "AdapterSelectionError",
+    "Annotation",
+    "AnnotationStore",
+    "Diagnostic",
+    "DiagnosticLevel",
+    "DuplicateNodeIdError",
+    "Edge",
+    "EdgeKind",
+    "Graph",
+    "Meta",
+    "Node",
+    "NodeKind",
+    "Payload",
+    "PayloadState",
+    "Provenance",
+    "RawRecord",
+    "SpanweaveError",
+    "Status",
+    "UnknownAdapterError",
+    "Usage",
+    "Warrant",
+    "__version__",
+    "build",
+    "dump",
+    "dumps",
+    "to_document",
+    "validate",
+]

spanweave/adapters/__init__.py

@@ -0,0 +1,161 @@
+"""The adapter registry and dialect selection.
+
+Selection is the one place this library can fail in the way it least wants
+to: quietly. A mis-detected input produces a **plausible but wrong graph**,
+and nothing downstream can tell. So ambiguity is a hard error here, never a
+first-wins race and never a fallback to a default (`SPEC.md` §6.1).
+
+That hard error is also what makes the weaker half of the mechanism
+survivable. Adapters self-report their confidence and could inflate it
+(`OPEN_QUESTIONS.md` §3); failing loudly on a tie means an inflated claim
+collides visibly instead of winning silently.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+from spanweave.adapters.base import Adapter
+from spanweave.errors import (
+    ADAPTER_DETECT_FAILED,
+    ADAPTER_UNCONFIDENT,
+    DUPLICATE_ADAPTER_ID,
+    NO_ADAPTERS_REGISTERED,
+    AdapterSelectionError,
+    UnknownAdapterError,
+)
+from spanweave.model import JsonValue
+
+__all__ = [
+    "DETECTION_SAMPLE_SIZE",
+    "MINIMUM_CONFIDENCE",
+    "AdapterRegistry",
+    "detect",
+    "get",
+    "register",
+    "registered",
+]
+
+#: `detect()` sees a bounded sample, so selection costs the same on a
+#: 10-record trace and a 10-million-record one.
+DETECTION_SAMPLE_SIZE = 50
+
+#: Below this, nobody is confident enough and the caller is told so.
+MINIMUM_CONFIDENCE = 0.5
+
+
+@dataclass(slots=True)
+class AdapterRegistry:
+    """The registered adapters. Registration order never affects selection."""
+
+    _adapters: dict[str, Adapter] = field(default_factory=dict)
+
+    def register(self, adapter: Adapter) -> None:
+        existing = self._adapters.get(adapter.id)
+        if existing is not None and existing is not adapter:
+            raise AdapterSelectionError(
+                f"two different adapters both claim the id {adapter.id!r}; "
+                f"ids must be unique",
+                code=DUPLICATE_ADAPTER_ID,
+            )
+        self._adapters[adapter.id] = adapter
+
+    def registered(self) -> tuple[Adapter, ...]:
+        """Every adapter, ordered by id -- never by registration order."""
+        return tuple(self._adapters[key] for key in sorted(self._adapters))
+
+    def get(self, adapter_id: str) -> Adapter:
+        try:
+            return self._adapters[adapter_id]
+        except KeyError:
+            known = ", ".join(sorted(self._adapters)) or "none registered"
+            raise UnknownAdapterError(
+                f"no adapter with id {adapter_id!r}; registered: {known}"
+            ) from None
+
+    def confidences(self, sample: Sequence[JsonValue]) -> tuple[tuple[str, float], ...]:
+        """Every adapter's confidence in this input, ordered by adapter id."""
+        results = []
+        for adapter in self.registered():
+            try:
+                confidence = float(adapter.detect(sample))
+            except Exception as failure:
+                # `detect()` must not raise (ADAPTERS.md §2). One that does is
+                # a broken adapter, not malformed input, and swallowing it
+                # would let a different adapter win by default -- which is
+                # exactly the silent-wrong-graph outcome this module exists to
+                # prevent. So it is reported, loudly, naming the adapter.
+                raise AdapterSelectionError(
+                    f"adapter {adapter.id!r} raised during detection "
+                    f"({failure!r}); detect() must be pure and must not raise",
+                    code=ADAPTER_DETECT_FAILED,
+                ) from failure
+            results.append((adapter.id, confidence))
+        return tuple(results)
+
+    def detect(self, records: Sequence[JsonValue]) -> tuple[Adapter, float]:
+        """Choose the adapter for this input, or refuse to (`SPEC.md` §6.1)."""
+        if not self._adapters:
+            raise AdapterSelectionError(
+                "no adapters are registered, so nothing can read this input",
+                code=NO_ADAPTERS_REGISTERED,
+            )
+        sample = list(records[:DETECTION_SAMPLE_SIZE])
+        measured = self.confidences(sample)
+        best = max(confidence for _, confidence in measured)
+        winners = [name for name, confidence in measured if confidence == best]
+
+        if best < MINIMUM_CONFIDENCE:
+            raise AdapterSelectionError(
+                f"no adapter is confident enough about this input "
+                f"(highest {best:.2f}, minimum {MINIMUM_CONFIDENCE:.2f}). "
+                f"{_report(measured)} "
+                f"Name one explicitly with --adapter if you know the dialect.",
+                code=ADAPTER_UNCONFIDENT,
+            )
+        if len(winners) > 1:
+            tied = ", ".join(winners)
+            raise AdapterSelectionError(
+                f"this input is ambiguous: {tied} are equally confident "
+                f"({best:.2f}). {_report(measured)} "
+                f"Name one explicitly with --adapter; guessing between them "
+                f"would produce a plausible graph from possibly the wrong "
+                f"dialect."
+            )
+        return self.get(winners[0]), best
+
+
+def _report(measured: Sequence[tuple[str, float]]) -> str:
+    listed = ", ".join(f"{name} {confidence:.2f}" for name, confidence in measured)
+    return f"Confidence declared by each adapter: {listed}."
+
+
+#: The registry the CLI and the public API use.
+REGISTRY = AdapterRegistry()
+
+
+def register(adapter: Adapter) -> None:
+    REGISTRY.register(adapter)
+
+
+def registered() -> tuple[Adapter, ...]:
+    return REGISTRY.registered()
+
+
+def get(adapter_id: str) -> Adapter:
+    return REGISTRY.get(adapter_id)
+
+
+def detect(records: Sequence[JsonValue]) -> tuple[Adapter, float]:
+    return REGISTRY.detect(records)
+
+
+# Registered here, at the end of the module, so that importing the registry
+# also makes the shipped dialects available -- and so that an adapter file
+# never has to import the registry back (ADAPTERS.md §4).
+from spanweave.adapters.openinference import OpenInferenceAdapter  # noqa: E402
+from spanweave.adapters.otel_genai import OtelGenAiAdapter  # noqa: E402
+
+REGISTRY.register(OpenInferenceAdapter())
+REGISTRY.register(OtelGenAiAdapter())

spanweave/adapters/base.py

@@ -0,0 +1,58 @@
+"""What an adapter is.
+
+An adapter teaches `spanweave` exactly one telemetry dialect, and it is the
+only place dialect knowledge may live. Full authoring guide: ``ADAPTERS.md``.
+
+The seam types are defined in ``spanweave.seam`` and re-exported here, because
+an adapter author should need one import and because the builder must be able
+to name ``NormalizedSpan`` without importing anything from this package
+(``DESIGN.md`` §2).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from typing import Protocol, runtime_checkable
+
+from spanweave.model import JsonValue
+from spanweave.seam import CallRole, DeclaredDataEdge, NormalizedSpan, SpanLink
+
+__all__ = [
+    "Adapter",
+    "CallRole",
+    "DeclaredDataEdge",
+    "NormalizedSpan",
+    "SpanLink",
+]
+
+
+@runtime_checkable
+class Adapter(Protocol):
+    """One dialect, translated. Nothing more (`SPEC.md` §6)."""
+
+    #: Stable, lowercase, no spaces.
+    id: str
+    #: The adapter's own version, independent of the library's.
+    version: str
+
+    def detect(self, sample: Sequence[JsonValue]) -> float:
+        """Confidence in ``[0.0, 1.0]`` that this adapter handles the input.
+
+        Pure, and it must not raise. Key on distinctive marker keys, not on
+        generic ones. Be honest about partial matches, and **do not return
+        1.0 defensively**: inflated confidence turns detection into a race,
+        and a wrong adapter silently producing a plausible graph is far worse
+        than an honest "ambiguous input" error.
+        """
+        ...
+
+    def parse(self, records: Iterable[JsonValue]) -> Iterator[NormalizedSpan]:
+        """Translate records into spans.
+
+        Pure, lazy, order-independent, and it never raises on malformed
+        input: what cannot be mapped becomes a diagnostic on the span, or an
+        ``unknown`` span carrying the record verbatim. Transcribe, don't
+        interpret -- every temptation to infer something the dialect did not
+        say is answered with a ``Diagnostic`` or a ``None``.
+        """
+        ...