spanforge 1.0.0__py3-none-any.whl

spanforge/processor.py

@@ -0,0 +1,258 @@
+"""spanforge.processor — Span processor pipeline (RFC-0001 §18).
+
+Span processors let users hook into the span lifecycle **before** and
+**after** a span is exported.  Common uses:
+
+* Attribute enrichment (e.g. add ``k8s.pod_name`` to every span)
+* Redaction of sensitive fields (complementing built-in :class:`~spanforge.redact.RedactionPolicy`)
+* Custom metrics counters / latency histograms
+* Distributed context propagation helpers
+
+Usage::
+
+    from spanforge import configure
+    from spanforge.processor import SpanProcessor, ProcessorChain
+
+    class EnrichProcessor(SpanProcessor):
+        def on_start(self, span) -> None:
+            span.set_attribute("service.region", "us-east-1")
+
+        def on_end(self, span) -> None:
+            # span is already finalised with status / duration
+            if span.status == "error":
+                span.set_attribute("alert.triggered", True)
+
+    configure(span_processors=[EnrichProcessor()])
+
+Processors receive the *live* :class:`~spanforge._span.Span` object.
+Mutations made in ``on_start`` are visible to user code inside the ``with``
+block.  Mutations made in ``on_end`` appear in the exported payload.
+
+Thread-safety
+-------------
+Processors are called from the thread that owns the span context manager, so
+they run in the same thread/task as the user code.  Processors MUST NOT
+block the event loop; long-running work should be dispatched to a background
+thread or asyncio task.
+
+Error handling
+--------------
+Exceptions propagating from a processor are silently caught so that a buggy
+processor never aborts user code.  Errors are logged at ``WARNING`` level.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import threading
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from spanforge._span import Span
+
+__all__ = [
+    "NoopSpanProcessor",
+    "ProcessorChain",
+    "SpanProcessor",
+    "add_processor",
+    "clear_processors",
+]
+
+_proc_logger = logging.getLogger("spanforge.processor")
+
+
+# ---------------------------------------------------------------------------
+# Protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class SpanProcessor(Protocol):
+    """Protocol implemented by all span processors.
+
+    Both methods are optional — a processor that only enriches on start can
+    omit ``on_end``, and vice-versa.  The default no-op implementations
+    defined in this protocol mean partial implementations work correctly.
+    """
+
+    def on_start(self, span: Span) -> None:
+        """Called synchronously immediately after the span is created.
+
+        The span has been pushed onto the context stack and its start time
+        recorded.  Attributes may be freely added or mutated here.
+
+        Args:
+            span: The newly created :class:`~spanforge._span.Span` (mutable).
+        """
+        ...
+
+    def on_end(self, span: Span) -> None:
+        """Called synchronously after the span is finalised but before export.
+
+        ``span.end_ns``, ``span.duration_ms``, and ``span.status`` are all
+        set by the time this method runs.  Attributes may still be mutated
+        and will appear in the exported :class:`~spanforge.namespaces.trace.SpanPayload`.
+
+        Args:
+            span: The finalised :class:`~spanforge._span.Span` (still mutable).
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# No-op implementation (default)
+# ---------------------------------------------------------------------------
+
+
+class NoopSpanProcessor:
+    """Span processor that does nothing.  Used as the default."""
+
+    def on_start(self, span: Span) -> None:
+        """No-op span start hook."""
+        pass
+
+    def on_end(self, span: Span) -> None:
+        """No-op span end hook."""
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Processor chain
+# ---------------------------------------------------------------------------
+
+
+class ProcessorChain:
+    """An ordered chain of :class:`SpanProcessor` implementations.
+
+    Processors are called in insertion order for ``on_start`` and in the
+    **same** order for ``on_end``.  Errors are caught per-processor so a
+    bug in one processor does not prevent subsequent processors from running.
+
+    Args:
+        processors: Initial list of processors.
+
+    Example::
+
+        chain = ProcessorChain([EnrichProcessor(), RedactProcessor()])
+        chain.on_start(span)
+        # ... later ...
+        chain.on_end(span)
+    """
+
+    def __init__(self, processors: list[Any] | None = None) -> None:
+        self._processors: list[Any] = list(processors or [])
+        self._lock = threading.Lock()
+
+    def add(self, processor: Any) -> None:
+        """Append *processor* to the chain."""
+        with self._lock:
+            self._processors.append(processor)
+
+    def remove(self, processor: Any) -> None:
+        """Remove *processor* from the chain (no-op if not present)."""
+        with self._lock, contextlib.suppress(ValueError):
+            self._processors.remove(processor)
+
+    def clear(self) -> None:
+        """Remove all processors from the chain."""
+        with self._lock:
+            self._processors.clear()
+
+    def on_start(self, span: Span) -> None:
+        """Fire ``on_start`` on all processors in order."""
+        with self._lock:
+            procs = list(self._processors)  # snapshot to avoid holding lock during callbacks
+        for proc in procs:
+            try:
+                proc.on_start(span)
+            except Exception as exc:  # NOSONAR
+                _proc_logger.warning(
+                    "SpanProcessor.on_start error in %r: %s", type(proc).__name__, exc
+                )
+
+    def on_end(self, span: Span) -> None:
+        """Fire ``on_end`` on all processors in order."""
+        with self._lock:
+            procs = list(self._processors)  # snapshot to avoid holding lock during callbacks
+        for proc in procs:
+            try:
+                proc.on_end(span)
+            except Exception as exc:  # NOSONAR
+                _proc_logger.warning(
+                    "SpanProcessor.on_end error in %r: %s", type(proc).__name__, exc
+                )
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._processors)
+
+    def __repr__(self) -> str:
+        with self._lock:
+            names = [type(p).__name__ for p in self._processors]
+        return f"ProcessorChain({names!r})"
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers — called from _span.py
+# ---------------------------------------------------------------------------
+
+
+def _run_on_start(span: Span) -> None:
+    """Fire ``on_start`` on all processors registered in the active config."""
+    try:
+        from spanforge.config import get_config
+
+        processors = get_config().span_processors
+    except Exception:  # NOSONAR
+        return
+    for proc in processors:
+        try:
+            proc.on_start(span)
+        except Exception as exc:  # NOSONAR
+            _proc_logger.warning("SpanProcessor.on_start error in %r: %s", type(proc).__name__, exc)
+
+
+def _run_on_end(span: Span) -> None:
+    """Fire ``on_end`` on all processors registered in the active config."""
+    try:
+        from spanforge.config import get_config
+
+        processors = get_config().span_processors
+    except Exception:  # NOSONAR
+        return
+    for proc in processors:
+        try:
+            proc.on_end(span)
+        except Exception as exc:  # NOSONAR
+            _proc_logger.warning("SpanProcessor.on_end error in %r: %s", type(proc).__name__, exc)
+
+
+def add_processor(processor: Any) -> None:
+    """Append *processor* to the global span processor list in the active config.
+
+    Convenience wrapper around ``configure(span_processors=[...])``.
+
+    Args:
+        processor: Any object implementing :class:`SpanProcessor` protocol.
+
+    Example::
+
+        from spanforge.processor import add_processor, SpanProcessor
+
+        class Enricher(SpanProcessor):
+            def on_start(self, span): span.set_attribute("region", "eu-west-1")
+            def on_end(self, span): pass
+
+        add_processor(Enricher())
+    """
+    from spanforge.config import get_config
+
+    get_config().span_processors.append(processor)
+
+
+def clear_processors() -> None:
+    """Remove all span processors from the active config."""
+    from spanforge.config import get_config
+
+    get_config().span_processors.clear()

spanforge/prompt_registry.py

@@ -0,0 +1,418 @@
+"""spanforge.prompt_registry — Prompt registry with versioning and W3C-event emission.
+
+The prompt registry provides a centralised store for prompt templates so that
+every rendered prompt is linked to the exact version that produced it.  This
+enables:
+
+* **Reproducibility** — re-run any historical span with the same prompt.
+* **A/B testing** — route traffic between prompt versions and compare results.
+* **Audit trail** — the RFC-0001 ``llm.prompt.*`` events capture template
+  load, version change, and render events.
+
+Quick start
+-----------
+::
+
+    from spanforge.prompt_registry import PromptRegistry
+
+    registry = PromptRegistry()
+    registry.register(
+        name="rag_system",
+        template="You are {role}.  Answer only from: {context}",
+        version="1.0.0",
+    )
+
+    rendered = registry.render("rag_system", {"role": "expert", "context": "...docs..."})
+    print(rendered)
+    # You are expert.  Answer only from: ...docs...
+
+    # Later, update the template — version change event is emitted automatically.
+    registry.register(
+        name="rag_system",
+        template="You are {role}.  Use ONLY these documents: {context}",
+        version="1.1.0",
+    )
+
+Module-level singleton
+----------------------
+A module-level ``_DEFAULT_REGISTRY`` is provided.  Helper functions
+:func:`register_prompt`, :func:`get_prompt_version`, and :func:`render_prompt`
+delegate to it for convenience::
+
+    from spanforge.prompt_registry import register_prompt, render_prompt
+
+    register_prompt("greet", "Hello, {name}!", version="1.0.0")
+    text = render_prompt("greet", {"name": "world"})
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "PromptRegistry",
+    "PromptVersion",
+    "get_prompt_version",
+    "register_prompt",
+    "render_prompt",
+]
+
+_log = logging.getLogger("spanforge.prompt_registry")
+
+# Simple {placeholder} pattern (not Jinja — zero runtime dependencies).
+_PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
+
+
+# ---------------------------------------------------------------------------
+# PromptVersion dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PromptVersion:
+    """An immutable snapshot of a versioned prompt template.
+
+    Args:
+        name:       Registry name (e.g. ``"rag_system"``).
+        template:   Raw template string with ``{variable}`` placeholders.
+        version:    Semantic version string (e.g. ``"1.0.0"``).
+        variables:  List of placeholder names extracted from *template*.
+        created_at: Unix timestamp when this version was registered.
+        metadata:   Free-form metadata dict (author, model hint, etc.).
+    """
+
+    name: str
+    template: str
+    version: str
+    variables: list[str] = field(default_factory=list)
+    created_at: float = field(default_factory=time.time)
+    metadata: dict[str, Any] | None = None
+
+    def render(self, variables: dict[str, Any]) -> str:
+        """Render the template by substituting *variables*.
+
+        Args:
+            variables: Dict of ``{placeholder: value}`` pairs.
+
+        Returns:
+            The rendered string.
+
+        Raises:
+            KeyError: If a required placeholder is missing from *variables*.
+
+        Example::
+
+            pv = PromptVersion("greet", "Hello, {name}!", "1.0.0", ["name"])
+            pv.render({"name": "Alice"})
+            # "Hello, Alice!"
+        """
+        missing = [v for v in self.variables if v not in variables]
+        if missing:
+            raise KeyError(
+                f"PromptVersion '{self.name}@{self.version}' requires variables "
+                f"{missing!r} but they were not supplied."
+            )
+        return self.template.format(**variables)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a plain dict."""
+        d: dict[str, Any] = {
+            "name": self.name,
+            "template": self.template,
+            "version": self.version,
+            "variables": self.variables,
+            "created_at": self.created_at,
+        }
+        if self.metadata is not None:
+            d["metadata"] = self.metadata
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PromptVersion:
+        """Deserialise from a plain dict."""
+        return cls(
+            name=data["name"],
+            template=data["template"],
+            version=data["version"],
+            variables=list(data.get("variables", [])),
+            created_at=float(data.get("created_at", time.time())),
+            metadata=data.get("metadata"),
+        )
+
+
+# ---------------------------------------------------------------------------
+# PromptRegistry
+# ---------------------------------------------------------------------------
+
+
+class PromptRegistry:
+    """Thread-safe registry of versioned prompt templates.
+
+    Multiple versions of the same template name are stored independently.
+    The *latest* version (most recently registered) is used by default when
+    calling :meth:`render`.
+
+    Example::
+
+        registry = PromptRegistry()
+        registry.register("system", "You are {role}.", version="1.0.0")
+        registry.register("system", "You are a helpful {role}.", version="2.0.0")
+
+        # Uses version 2.0.0 (latest).
+        registry.render("system", {"role": "assistant"})
+    """
+
+    def __init__(self) -> None:
+        import threading
+
+        self._lock = threading.RLock()
+        # {name: {version: PromptVersion}}
+        self._store: dict[str, dict[str, PromptVersion]] = {}
+        # {name: version_string}  — last registered version = default
+        self._latest: dict[str, str] = {}
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        name: str,
+        template: str,
+        *,
+        version: str = "1.0.0",
+        metadata: dict[str, Any] | None = None,
+    ) -> PromptVersion:
+        """Register (or update) a prompt template.
+
+        Emits:
+        * ``llm.prompt.template.loaded`` on first registration.
+        * ``llm.prompt.version.changed`` when a *name* already exists
+          (even if the version string is the same).
+
+        Args:
+            name:     Unique prompt name within this registry.
+            template: Template string with ``{variable}`` placeholders.
+            version:  Semantic version string.
+            metadata: Optional free-form metadata.
+
+        Returns:
+            The newly created :class:`PromptVersion`.
+        """
+        variables = _PLACEHOLDER_RE.findall(template)
+        pv = PromptVersion(
+            name=name,
+            template=template,
+            version=version,
+            variables=variables,
+            metadata=metadata,
+        )
+        with self._lock:
+            existing = self._store.get(name)
+            is_new = existing is None
+            self._store.setdefault(name, {})[version] = pv
+            previous_version = self._latest.get(name)
+            self._latest[name] = version
+
+        # Emit RFC-0001 events outside the lock.
+        self._emit_register_events(pv, is_new=is_new, previous_version=previous_version)
+        return pv
+
+    # ------------------------------------------------------------------
+    # Retrieval
+    # ------------------------------------------------------------------
+
+    def get(self, name: str, version: str | None = None) -> PromptVersion:
+        """Return the :class:`PromptVersion` for *name*.
+
+        Args:
+            name:    Prompt name.
+            version: Explicit version string, or ``None`` for the latest.
+
+        Raises:
+            KeyError: If *name* or *version* is not found.
+        """
+        with self._lock:
+            versions = self._store.get(name)
+            if versions is None:
+                raise KeyError(f"No prompt registered with name={name!r}")
+            if version is None:
+                version = self._latest[name]
+            pv = versions.get(version)
+            if pv is None:
+                raise KeyError(
+                    f"Prompt {name!r} has no version {version!r}. Available: {sorted(versions)!r}"
+                )
+            return pv
+
+    #: Alias for :meth:`get` (F-26).
+    get_version = get
+
+    def list_versions(self, name: str) -> list[str]:
+        """Return all registered version strings for *name*, sorted ascending."""
+        with self._lock:
+            versions = self._store.get(name)
+            if versions is None:
+                raise KeyError(f"No prompt registered with name={name!r}")
+            return sorted(versions.keys())
+
+    def list_names(self) -> list[str]:
+        """Return all registered prompt names, sorted."""
+        with self._lock:
+            return sorted(self._store.keys())
+
+    # ------------------------------------------------------------------
+    # Rendering
+    # ------------------------------------------------------------------
+
+    def render(
+        self,
+        name: str,
+        variables: dict[str, Any],
+        *,
+        version: str | None = None,
+        span_id: str | None = None,
+        trace_id: str | None = None,
+    ) -> str:
+        """Render a prompt template, emitting a ``llm.prompt.rendered`` event.
+
+        Args:
+            name:      Prompt name.
+            variables: Substitution variables.
+            version:   Optional version string; defaults to latest.
+            span_id:   Optional parent span ID for event correlation.
+            trace_id:  Optional trace ID for event correlation.
+
+        Returns:
+            The rendered template string.
+
+        Raises:
+            KeyError: If the prompt name or version is not found, or if a
+                      required variable is missing.
+        """
+        pv = self.get(name, version)
+        rendered = pv.render(variables)
+        self._emit_rendered_event(pv, rendered, span_id=span_id, trace_id=trace_id)
+        return rendered
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def export_all(self) -> list[dict[str, Any]]:
+        """Return a list of ``to_dict()`` dicts for all registered prompt versions."""
+        with self._lock:
+            return [pv.to_dict() for versions in self._store.values() for pv in versions.values()]
+
+    def import_all(self, records: list[dict[str, Any]]) -> None:
+        """Bulk-import prompt versions from a list of dicts (no events emitted)."""
+        with self._lock:
+            for rec in records:
+                pv = PromptVersion.from_dict(rec)
+                self._store.setdefault(pv.name, {})[pv.version] = pv
+                self._latest[pv.name] = pv.version
+
+    # ------------------------------------------------------------------
+    # Internal event helpers
+    # ------------------------------------------------------------------
+
+    def _emit_register_events(
+        self,
+        pv: PromptVersion,
+        *,
+        is_new: bool,
+        previous_version: str | None,
+    ) -> None:
+        try:
+            from spanforge._stream import emit_rfc_event
+            from spanforge.types import EventType
+
+            if is_new:
+                emit_rfc_event(
+                    EventType.PROMPT_TEMPLATE_LOADED,
+                    payload=pv.to_dict(),
+                )
+            else:
+                emit_rfc_event(
+                    EventType.PROMPT_VERSION_CHANGED,
+                    payload={
+                        **pv.to_dict(),
+                        "previous_version": previous_version,
+                    },
+                )
+        except Exception as exc:  # NOSONAR
+            _log.debug("prompt_registry: failed to emit register event: %s", exc)
+
+    def _emit_rendered_event(
+        self,
+        pv: PromptVersion,
+        rendered: str,
+        *,
+        span_id: str | None,
+        trace_id: str | None,
+    ) -> None:
+        try:
+            from spanforge._stream import emit_rfc_event
+            from spanforge.types import EventType
+
+            emit_rfc_event(
+                EventType.PROMPT_RENDERED,
+                payload={
+                    "name": pv.name,
+                    "version": pv.version,
+                    # Omit the rendered text to avoid leaking PII; include
+                    # only the prompt name/version for correlation.
+                    "rendered_length": len(rendered),
+                },
+                span_id=span_id,
+                trace_id=trace_id,
+            )
+        except Exception as exc:  # NOSONAR
+            _log.debug("prompt_registry: failed to emit rendered event: %s", exc)
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton + helpers
+# ---------------------------------------------------------------------------
+
+_DEFAULT_REGISTRY = PromptRegistry()
+
+
+def register_prompt(
+    name: str,
+    template: str,
+    *,
+    version: str = "1.0.0",
+    metadata: dict[str, Any] | None = None,
+) -> PromptVersion:
+    """Register a prompt in the module-level default registry.
+
+    Convenience wrapper around :meth:`PromptRegistry.register`.
+    """
+    return _DEFAULT_REGISTRY.register(name, template, version=version, metadata=metadata)
+
+
+def get_prompt_version(name: str, version: str | None = None) -> PromptVersion:
+    """Get a :class:`PromptVersion` from the module-level default registry."""
+    return _DEFAULT_REGISTRY.get(name, version)
+
+
+def render_prompt(
+    name: str,
+    variables: dict[str, Any],
+    *,
+    version: str | None = None,
+    span_id: str | None = None,
+    trace_id: str | None = None,
+) -> str:
+    """Render a prompt from the module-level default registry.
+
+    Convenience wrapper around :meth:`PromptRegistry.render`.
+    """
+    return _DEFAULT_REGISTRY.render(
+        name, variables, version=version, span_id=span_id, trace_id=trace_id
+    )