morphsdk 0.2.5__py3-none-any.whl

morphsdk/tracing/interaction.py

@@ -0,0 +1,284 @@
+"""Morph Tracing -- interactions, tools, and manual spans.
+
+An :class:`Interaction` is one user turn / agent run. It threads association
+properties (``user_id`` / ``convo_id`` / ``event_id``) onto every span created
+inside it -- including the auto-instrumented LLM spans -- so a whole conversation
+stitches together in the Morph UI. Built on Traceloop's association properties
+and the OpenTelemetry tracer for manual workflow/tool spans.
+
+Attribute keys and ``traceloop.span.kind`` values are kept byte-for-byte
+identical to the TypeScript SDK so both emit the same wire payload.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid as _uuid
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any, Callable, TypeVar
+
+from . import _otel
+from .otel import metadata as build_metadata
+from .reflex import REFLEX_RUN_ATTRIBUTE, serialize_evals
+from .types import (
+    FinishOptions,
+    MetadataOptions,
+    SpanParams,
+    ToolParams,
+    TraceContext,
+    TrackToolParams,
+)
+
+T = TypeVar("T")
+
+# Traceloop semantic-convention attribute keys.
+_ASSOC = "traceloop.association.properties."
+_ENTITY_INPUT = "traceloop.entity.input"
+_ENTITY_OUTPUT = "traceloop.entity.output"
+_ENTITY_NAME = "traceloop.entity.name"
+_SPAN_KIND = "traceloop.span.kind"
+
+_TRACER_NAME = "morphsdk.tracing"
+
+
+def _uuid4() -> str:
+    return str(_uuid.uuid4())
+
+
+def _as_string(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, separators=(",", ":"), default=str)
+
+
+def _association_props(ctx: TraceContext, extra: dict[str, str]) -> dict[str, str]:
+    """Build the association-property bag propagated onto child spans."""
+    props: dict[str, str] = dict(extra)
+    if ctx.user_id:
+        props["user_id"] = ctx.user_id
+    if ctx.convo_id:
+        props["convo_id"] = ctx.convo_id
+    if ctx.event_id:
+        props["event_id"] = ctx.event_id
+    if ctx.event:
+        props["event_name"] = ctx.event
+    return props
+
+
+class ToolSpan:
+    """A manual tool span the caller drives explicitly."""
+
+    def __init__(self, span: Any, trace_content: bool) -> None:
+        self._span = span
+        self._trace_content = trace_content
+
+    def set_input(self, value: Any) -> None:
+        if self._trace_content:
+            self._span.set_attribute(_ENTITY_INPUT, _as_string(value))
+
+    def set_output(self, value: Any) -> None:
+        if self._trace_content:
+            self._span.set_attribute(_ENTITY_OUTPUT, _as_string(value))
+
+    def set_error(self, error: str | BaseException) -> None:
+        exc = error if isinstance(error, BaseException) else Exception(error)
+        status = _otel.status_codes()
+        self._span.record_exception(exc)
+        self._span.set_status(status.Status(status.StatusCode.ERROR, str(exc)))
+
+    def end(self) -> None:
+        self._span.end()
+
+
+class Interaction:
+    """A single traced AI interaction (one user turn / agent run)."""
+
+    def __init__(self, initial: TraceContext, trace_content: bool) -> None:
+        self._ctx = initial.model_copy(deep=True)
+        if self._ctx.event_id is None:
+            self._ctx.event_id = _uuid4()
+        self._properties: dict[str, str] = dict(initial.properties or {})
+        self._input = initial.input
+        self._trace_content = trace_content
+        self._workflow_span: Any = None
+        # Serialized once. Set as a raw attribute on the workflow span only -- NOT
+        # an association property, so it is not copied onto child LLM spans. Ingest
+        # reads `morph.reflex.run` off the workflow-span to enqueue the evals.
+        self._reflex_run = serialize_evals(self._ctx.evals)
+
+    # -- accessors ---------------------------------------------------------
+
+    def get_event_id(self) -> str | None:
+        return self._ctx.event_id
+
+    def set_input(self, value: str) -> None:
+        self._input = value
+
+    def set_property(self, key: str, value: str) -> None:
+        self._properties[key] = value
+
+    def set_properties(self, props: dict[str, str]) -> None:
+        self._properties.update(props)
+
+    def vercel_ai_sdk_metadata(self) -> dict[str, str]:
+        """Attribution metadata for OTel-emitting SDKs (e.g. Vercel AI SDK)."""
+        return build_metadata(
+            MetadataOptions(
+                user_id=self._ctx.user_id or "unknown",
+                convo_id=self._ctx.convo_id,
+                event_name=self._ctx.event,
+                event_id=self._ctx.event_id,
+                properties=self._properties,
+            )
+        )
+
+    # -- internals ---------------------------------------------------------
+
+    def _workflow_name(self) -> str:
+        return self._ctx.event or "interaction"
+
+    @contextmanager
+    def _assoc(self) -> Iterator[None]:
+        """Activate this interaction's association properties for the block.
+
+        Traceloop copies the current association properties onto every span
+        created while they are set, so auto-instrumented LLM spans inherit
+        attribution. Restored afterwards to avoid leaking across interactions.
+        """
+        traceloop = _otel.traceloop()
+        props = _association_props(self._ctx, self._properties)
+        traceloop.set_association_properties(props)
+        try:
+            yield
+        finally:
+            traceloop.set_association_properties({})
+
+    def _ensure_workflow_span(self) -> Any:
+        """Open the interaction workflow span once; stays active until finish()."""
+        if self._workflow_span is not None:
+            return self._workflow_span
+        trace = _otel.trace_api()
+        tracer = trace.get_tracer(_TRACER_NAME)
+        span = tracer.start_span(self._workflow_name())
+        span.set_attribute(_SPAN_KIND, "workflow")
+        for key, value in _association_props(self._ctx, self._properties).items():
+            span.set_attribute(_ASSOC + key, value)
+        if self._trace_content and self._input:
+            span.set_attribute(_ENTITY_INPUT, self._input)
+        if self._reflex_run:
+            span.set_attribute(REFLEX_RUN_ATTRIBUTE, self._reflex_run)
+        self._workflow_span = span
+        return span
+
+    @contextmanager
+    def _workflow_context(self) -> Iterator[None]:
+        """Run a block with association props + the workflow span as parent."""
+        trace = _otel.trace_api()
+        with self._assoc():
+            span = self._ensure_workflow_span()
+            with trace.use_span(span, end_on_exit=False):
+                yield
+
+    @staticmethod
+    def _as_tool_params(params: ToolParams | str | dict[str, Any]) -> ToolParams:
+        if isinstance(params, ToolParams):
+            return params
+        if isinstance(params, str):
+            return ToolParams(name=params)
+        return ToolParams.model_validate(params)
+
+    @staticmethod
+    def _as_span_params(params: SpanParams | str | dict[str, Any]) -> SpanParams:
+        if isinstance(params, SpanParams):
+            return params
+        if isinstance(params, str):
+            return SpanParams(name=params)
+        return SpanParams.model_validate(params)
+
+    # -- spans -------------------------------------------------------------
+
+    def start_tool_span(self, params: ToolParams | str | dict[str, Any]) -> ToolSpan:
+        """Start a tool span you end manually via :meth:`ToolSpan.end`."""
+        trace = _otel.trace_api()
+        tool = self._as_tool_params(params)
+        tracer = trace.get_tracer(_TRACER_NAME)
+        span = tracer.start_span(tool.name)
+        span.set_attribute(_SPAN_KIND, "tool")
+        span.set_attribute(_ENTITY_NAME, tool.name)
+        for key, value in _association_props(self._ctx, self._properties).items():
+            span.set_attribute(_ASSOC + key, value)
+        if tool.properties:
+            for key, value in tool.properties.items():
+                span.set_attribute(key, value)
+        return ToolSpan(span, self._trace_content)
+
+    def run(self, fn: Callable[[], T]) -> T:
+        """Run *fn* with this interaction's association properties active.
+
+        Required so auto-instrumented OpenAI/Anthropic spans inherit
+        ``user_id`` / ``convo_id`` / tags.
+        """
+        with self._workflow_context():
+            return fn()
+
+    def with_span(self, params: SpanParams | str | dict[str, Any], fn: Callable[[], T]) -> T:
+        """Run *fn* inside a traced task span; LLM calls within inherit attribution."""
+        trace = _otel.trace_api()
+        task = self._as_span_params(params)
+        with self._workflow_context():
+            tracer = trace.get_tracer(_TRACER_NAME)
+            with tracer.start_as_current_span(task.name) as span:
+                span.set_attribute(_SPAN_KIND, "task")
+                span.set_attribute(_ENTITY_NAME, task.name)
+                if task.properties:
+                    for key, value in task.properties.items():
+                        span.set_attribute(key, value)
+                return fn()
+
+    def with_tool(self, params: ToolParams | str | dict[str, Any], fn: Callable[[], T]) -> T:
+        """Run *fn* inside a traced tool span."""
+        trace = _otel.trace_api()
+        tool = self._as_tool_params(params)
+        with self._workflow_context():
+            tracer = trace.get_tracer(_TRACER_NAME)
+            with tracer.start_as_current_span(tool.name) as span:
+                span.set_attribute(_SPAN_KIND, "tool")
+                span.set_attribute(_ENTITY_NAME, tool.name)
+                if tool.properties:
+                    for key, value in tool.properties.items():
+                        span.set_attribute(key, value)
+                return fn()
+
+    def track_tool(self, params: TrackToolParams | dict[str, Any]) -> None:
+        """Record an already-completed tool invocation as a single span."""
+        if isinstance(params, TrackToolParams):
+            track = params
+        else:
+            track = TrackToolParams.model_validate(params)
+        span = self.start_tool_span(ToolParams(name=track.name, properties=track.properties))
+        if track.input is not None:
+            span.set_input(track.input)
+        if track.output is not None:
+            span.set_output(track.output)
+        if track.error:
+            span.set_error(track.error)
+        span.end()
+
+    def finish(self, opts: FinishOptions | str | dict[str, Any]) -> None:
+        """End the interaction with its final output."""
+        if isinstance(opts, str):
+            output = opts
+        else:
+            finish = opts if isinstance(opts, FinishOptions) else FinishOptions.model_validate(opts)
+            output = finish.output
+            if finish.properties:
+                self._properties.update(finish.properties)
+        with self._assoc():
+            span = self._ensure_workflow_span()
+            if self._trace_content:
+                span.set_attribute(_ENTITY_OUTPUT, output)
+            span.end()
+            self._workflow_span = None

morphsdk/tracing/otel.py

@@ -0,0 +1,75 @@
+"""Morph Tracing -- OpenTelemetry attribution helper.
+
+LLM SDKs that emit their own OpenTelemetry spans (e.g. the Vercel AI SDK) only
+need each call tagged with attribution metadata so Morph can stitch the spans to
+a user / conversation / event. :func:`metadata` builds that tag bag.
+
+This module has **no** OpenTelemetry dependency -- it returns a plain ``dict`` of
+snake_case keys, byte-for-byte identical to the TypeScript ``otel.ts`` helper::
+
+    from morphsdk.tracing import metadata
+
+    tags = metadata(user_id="user-123", convo_id="convo-456")
+"""
+
+from __future__ import annotations
+
+import uuid as _uuid
+
+from .types import MetadataOptions
+
+# Reserved keys Morph owns. Custom ``properties`` cannot overwrite these so
+# attribution (user_id / convo_id / event_id / event_name) stays intact.
+_RESERVED_KEYS = frozenset({"user_id", "convo_id", "event_id", "event_name"})
+
+
+def _uuid4() -> str:
+    return str(_uuid.uuid4())
+
+
+def metadata(
+    opts: MetadataOptions | dict[str, object] | None = None,
+    *,
+    user_id: str | None = None,
+    convo_id: str | None = None,
+    event_name: str | None = None,
+    event_id: str | None = None,
+    properties: dict[str, str] | None = None,
+) -> dict[str, str]:
+    """Build the attribution metadata bag for OTel-emitting LLM SDKs.
+
+    Accepts either a :class:`MetadataOptions` (or plain dict) positionally, or
+    keyword arguments. A fresh ``event_id`` is generated per call when omitted,
+    matching the TypeScript helper.
+
+    The returned keys are snake_case (``user_id``, ``convo_id``, ...) -- exactly
+    what Morph's ClickHouse views read.
+    """
+    if opts is not None:
+        resolved = (
+            opts if isinstance(opts, MetadataOptions) else MetadataOptions.model_validate(opts)
+        )
+    else:
+        if user_id is None:
+            raise TypeError("metadata() requires user_id")
+        resolved = MetadataOptions(
+            user_id=user_id,
+            convo_id=convo_id,
+            event_name=event_name,
+            event_id=event_id,
+            properties=properties,
+        )
+
+    result: dict[str, str] = {
+        "user_id": resolved.user_id,
+        "event_id": resolved.event_id or _uuid4(),
+    }
+    if resolved.convo_id:
+        result["convo_id"] = resolved.convo_id
+    if resolved.event_name:
+        result["event_name"] = resolved.event_name
+    if resolved.properties:
+        for key, value in resolved.properties.items():
+            if key not in _RESERVED_KEYS:
+                result[key] = value
+    return result

morphsdk/tracing/reflex.py

@@ -0,0 +1,58 @@
+"""Morph Tracing -- eval selection (which Reflexes to run on a trace).
+
+Mirror of the TypeScript ``morphsdk/tracing/reflex.ts``. The public API is ``evals`` (see
+:data:`EvalSelection`): ``{"user": [...], "assistant": [...]}`` choosing which role each model
+classifies. The selection is serialized onto a single ``morph.reflex.run`` attribute on the
+interaction's workflow span (NOT an association property, so it is not copied onto child LLM
+spans); Morph's ingest reads it and runs the classifications async. Plain nouns in, wire detail
+hidden.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .types import EvalSelection
+
+#: Raw span attribute key carrying the serialized selection (internal wire detail).
+REFLEX_RUN_ATTRIBUTE = "morph.reflex.run"
+
+# Public role -> backend transform id. user = the user's message, assistant = the agent's output.
+_USER_TRANSFORM = "user_message"
+_ASSISTANT_TRANSFORM = "assistant_message"
+
+
+def normalize_evals(evals: EvalSelection | None) -> list[dict[str, str]]:
+    """Normalize a public ``evals`` selection into deduped ``{"model","transform"}`` wire entries.
+    ``user`` models run on the user turn, ``assistant`` models on the agent turn. Drops blank
+    models; first-seen order."""
+    if not evals:
+        return []
+    out: list[dict[str, str]] = []
+    seen: set[str] = set()
+
+    def add(models: list[str] | None, transform: str) -> None:
+        for raw in models or []:
+            model = raw.strip() if isinstance(raw, str) else ""
+            if not model:
+                continue
+            key = f"{model} {transform}"
+            if key in seen:
+                continue
+            seen.add(key)
+            out.append({"model": model, "transform": transform})
+
+    add(evals.get("user"), _USER_TRANSFORM)
+    add(evals.get("assistant"), _ASSISTANT_TRANSFORM)
+    return out
+
+
+def serialize_evals(evals: EvalSelection | None) -> str | None:
+    """Serialize an ``evals`` selection to the ``morph.reflex.run`` string, or ``None`` when there
+    is nothing to run (so the attribute is omitted)."""
+    entries = normalize_evals(evals)
+    if not entries:
+        return None
+    # ensure_ascii=False to match TS JSON.stringify (raw UTF-8) byte-for-byte for non-ASCII model
+    # names; without it Python emits \uXXXX escapes and the wire string diverges from the TS SDK.
+    return json.dumps(entries, separators=(",", ":"), ensure_ascii=False)

morphsdk/tracing/types.py

@@ -0,0 +1,163 @@
+"""Morph Tracing -- public types.
+
+Morph Tracing instruments the top AI SDKs (OpenAI, Anthropic, LangChain,
+Bedrock, Vertex, Cohere, Together, LlamaIndex, ...) and ships OpenTelemetry
+spans to Morph. It is a thin, Morph-branded layer over OpenLLMetry / Traceloop,
+mirroring the TypeScript ``morphsdk/tracing`` module byte-for-byte on the wire.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+# ---------------------------------------------------------------------------
+# Eval selection
+# ---------------------------------------------------------------------------
+
+# Always explicit per role — no implicit default, since a model run on the wrong role gives a
+# meaningless label. Keys: "user" (the user's message), "assistant" (the agent's output).
+EvalSelection = dict[str, list[str]]
+"""Reflexes (evals) to run automatically on a trace, keyed by which role each model classifies::
+
+    evals={"user": ["jailbreak", "guardrail"]}
+    evals={"user": ["jailbreak"], "assistant": ["leaked-thinking"]}
+"""
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+
+class MorphTracingConfig(BaseModel):
+    """Configuration for :func:`morphsdk.tracing.morph_tracing`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    api_key: str | None = None
+    """Morph API key. Defaults to ``MORPH_API_KEY``. Sent as
+    ``Authorization: Bearer <api_key>`` to the trace ingest endpoint."""
+
+    base_url: str | None = None
+    """Base URL for the Morph ingest API. Traces are POSTed to
+    ``{base_url}/v1/traces``. Defaults to ``MORPH_TRACES_URL`` then
+    ``https://api.morphllm.com``."""
+
+    app_name: str | None = None
+    """Service/app name attached to every span. Defaults to ``"morph-app"``."""
+
+    disabled: bool = False
+    """When true, the SDK initializes nothing and ships nothing."""
+
+    disable_batching: bool | None = None
+    """Send spans immediately instead of batching. Defaults to true outside
+    production (``MORPH_ENVIRONMENT``/``NODE_ENV`` != ``production``)."""
+
+    trace_content: bool = True
+    """Capture prompt/response content on spans. Set false for
+    zero-data-retention."""
+
+    instrument_modules: set[str] | None = None
+    """Explicit set of instrument names to enable. Omit to auto-instrument all
+    supported libraries."""
+
+    use_external_otel: bool = False
+    """Set true when you run your own OpenTelemetry pipeline. Morph will not
+    start its own; use :meth:`MorphTracing.span_processor` instead."""
+
+    headers: dict[str, str] | None = None
+    """Extra headers merged onto the OTLP exporter request."""
+
+    debug: bool | None = None
+    """Verbose ``[morph-tracing]`` logging. Defaults to
+    ``MORPH_TRACING_DEBUG=1``."""
+
+    evals: EvalSelection | None = None
+    """Default evals to run on every interaction's trace. Overridable per-interaction via
+    ``begin({"evals": ...})``. Requires ``begin()`` so the trace carries an event id.
+    Omit for none."""
+
+
+class TraceContext(BaseModel):
+    """Identity + content for a single traced AI interaction."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    event_id: str | None = None
+    """Stable identifier for the interaction; auto-generated if omitted."""
+
+    user_id: str | None = None
+    """End-user identifier."""
+
+    convo_id: str | None = None
+    """Conversation/session identifier grouping related interactions."""
+
+    event: str | None = None
+    """Event name (defaults to ``"ai_generation"`` on the backend)."""
+
+    input: str | None = None
+    """User input for this interaction."""
+
+    properties: dict[str, str] | None = None
+    """Arbitrary string metadata propagated onto spans."""
+
+    evals: EvalSelection | None = None
+    """Evals to run automatically on this interaction's trace. Overrides any default set in
+    ``morph_tracing({"evals": ...})``. Omit to inherit the default (or run none)."""
+
+
+class SpanParams(BaseModel):
+    """Parameters for a manual task span."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    properties: dict[str, str] | None = None
+
+
+class ToolParams(BaseModel):
+    """Parameters for a tool span."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    version: int | None = None
+    properties: dict[str, str] | None = None
+
+
+class TrackToolParams(BaseModel):
+    """Record a tool invocation that has already completed."""
+
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    name: str
+    input: Any | None = None
+    output: Any | None = None
+    duration_ms: int | None = None
+    error: str | BaseException | None = None
+    properties: dict[str, str] | None = None
+
+
+class FinishOptions(BaseModel):
+    """Options for ending an interaction."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    output: str
+    properties: dict[str, str] | None = None
+
+
+class MetadataOptions(BaseModel):
+    """Metadata payload for the Vercel AI SDK / OTel attribution."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    user_id: str
+    convo_id: str | None = None
+    event_name: str | None = None
+    event_id: str | None = None
+    properties: dict[str, str] | None = None
+    """Custom tags, e.g. ``{"source": "support-bot"}`` ->
+    ``association.properties.source``."""