softprobe 0.1.0__py3-none-any.whl

softprobe/__init__.py

@@ -0,0 +1,54 @@
+"""Softprobe Python instrumentation SDK."""
+
+from typing import Any
+
+from softprobe.client import SoftprobeClient
+from softprobe.observation import Generation, Observation
+from softprobe.redaction import default_redact_keys, redact_value
+from softprobe.scores import build_score_request
+from softprobe.tools import (
+    accumulate_tool_call_deltas,
+    finalize_tool_call_deltas,
+    normalize_tool_calls,
+    normalize_tool_definitions,
+    record_tool_calls,
+    record_tool_definitions,
+    tool_result_event_payload,
+)
+from softprobe.types import OBSERVATION_TYPES
+
+__all__ = [
+    "OBSERVATION_TYPES",
+    "Generation",
+    "Observation",
+    "SoftprobeClient",
+    "accumulate_tool_call_deltas",
+    "build_score_request",
+    "default_redact_keys",
+    "finalize_tool_call_deltas",
+    "normalize_tool_calls",
+    "normalize_tool_definitions",
+    "propagate_attributes",
+    "record_tool_calls",
+    "record_tool_definitions",
+    "redact_value",
+    "tool_result_event_payload",
+    "observe_openai",
+    "CallbackHandler",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "observe_openai":
+        from softprobe.openai import observe_openai
+
+        return observe_openai
+    if name == "propagate_attributes":
+        from softprobe.propagation import propagate_attributes
+
+        return propagate_attributes
+    if name == "CallbackHandler":
+        from softprobe.langchain import CallbackHandler
+
+        return CallbackHandler
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

softprobe/attributes.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from softprobe.redaction import serialize_captured
+from softprobe.types import Attributes
+
+
+def apply_metadata(attrs: Attributes, metadata: Mapping[str, Any] | None) -> None:
+    if not metadata:
+        return
+    for key, value in metadata.items():
+        if value is None:
+            continue
+        if isinstance(value, (str, int, float, bool)):
+            attrs[f"sp.metadata.{key}"] = value
+        else:
+            serialized = serialize_captured(value, [])
+            if serialized is not None:
+                attrs[f"sp.metadata.{key}"] = serialized
+
+
+def build_observation_attributes(
+    *,
+    observation_type: str,
+    attributes: Mapping[str, Any] | None = None,
+    input: Any | None = None,
+    output: Any | None = None,
+    session_id: str | None = None,
+    user_id: str | None = None,
+    release: str | None = None,
+    tags: list[str] | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    version: str | None = None,
+    trace_name: str | None = None,
+    redact_keys: list[str],
+) -> Attributes:
+    attrs: Attributes = dict(attributes or {})
+    attrs["sp.observation.type"] = observation_type
+    if session_id:
+        attrs["sp.session.id"] = session_id
+        attrs["gen_ai.conversation.id"] = session_id
+    if user_id:
+        attrs["sp.user.id"] = user_id
+    if release:
+        attrs["sp.release"] = release
+    if tags is not None:
+        attrs["sp.tags"] = list(tags)
+    if version:
+        attrs["sp.version"] = version
+    if trace_name:
+        attrs["sp.trace.name"] = trace_name
+    apply_metadata(attrs, metadata)
+    serialized_input = serialize_captured(input, redact_keys)
+    serialized_output = serialize_captured(output, redact_keys)
+    if serialized_input is not None:
+        attrs["sp.input"] = serialized_input
+    if serialized_output is not None:
+        attrs["sp.output"] = serialized_output
+    return attrs
+
+
+def build_generation_attributes(
+    *,
+    attributes: Mapping[str, Any] | None = None,
+    input: Any | None = None,
+    output: Any | None = None,
+    session_id: str | None = None,
+    user_id: str | None = None,
+    release: str | None = None,
+    tags: list[str] | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    version: str | None = None,
+    trace_name: str | None = None,
+    redact_keys: list[str],
+    model: str | None = None,
+    response_model: str | None = None,
+    provider: str | None = None,
+    operation_name: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    usage: Mapping[str, int] | None = None,
+    cost: Mapping[str, float] | None = None,
+    completion_start_time: str | None = None,
+    response_id: str | None = None,
+    finish_reasons: list[str] | None = None,
+    prompt: Mapping[str, Any] | None = None,
+) -> Attributes:
+    attrs = build_observation_attributes(
+        observation_type="generation",
+        attributes=attributes,
+        input=input,
+        output=output,
+        session_id=session_id,
+        user_id=user_id,
+        release=release,
+        tags=tags,
+        metadata=metadata,
+        version=version,
+        trace_name=trace_name,
+        redact_keys=redact_keys,
+    )
+    if operation_name:
+        attrs["gen_ai.operation.name"] = operation_name
+    if provider:
+        attrs["gen_ai.provider.name"] = provider
+    if model:
+        attrs["gen_ai.request.model"] = model
+    if response_model:
+        attrs["gen_ai.response.model"] = response_model
+    if temperature is not None:
+        attrs["gen_ai.request.temperature"] = temperature
+    if max_tokens is not None:
+        attrs["gen_ai.request.max_tokens"] = max_tokens
+    if usage:
+        if "input_tokens" in usage:
+            attrs["gen_ai.usage.input_tokens"] = usage["input_tokens"]
+        if "output_tokens" in usage:
+            attrs["gen_ai.usage.output_tokens"] = usage["output_tokens"]
+        if "total_tokens" in usage:
+            attrs["gen_ai.usage.total_tokens"] = usage["total_tokens"]
+        elif "input_tokens" in usage or "output_tokens" in usage:
+            attrs["gen_ai.usage.total_tokens"] = int(usage.get("input_tokens", 0)) + int(
+                usage.get("output_tokens", 0)
+            )
+    if cost:
+        if "input" in cost:
+            attrs["sp.cost.input"] = cost["input"]
+        if "output" in cost:
+            attrs["sp.cost.output"] = cost["output"]
+        if "total" in cost:
+            attrs["sp.cost.total"] = cost["total"]
+    if completion_start_time:
+        attrs["sp.generation.completion_start_time"] = completion_start_time
+    if response_id:
+        attrs["gen_ai.response.id"] = response_id
+    if finish_reasons is not None:
+        attrs["gen_ai.response.finish_reasons"] = list(finish_reasons)
+    if prompt:
+        if prompt.get("id"):
+            attrs["sp.prompt.id"] = str(prompt["id"])
+        if prompt.get("name"):
+            attrs["sp.prompt.name"] = str(prompt["name"])
+        if prompt.get("version") is not None:
+            attrs["sp.prompt.version"] = int(prompt["version"])
+    return attrs

softprobe/client.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager, contextmanager
+from datetime import datetime
+from typing import Any, AsyncIterator, Iterator, Mapping
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    SimpleSpanProcessor,
+    SpanExporter,
+)
+from opentelemetry.semconv.resource import ResourceAttributes
+
+from softprobe.config import (
+    MissingSoftprobeCredentialsError,
+    derive_otlp_endpoint,
+    resolve_softprobe_config_from_env,
+)
+from softprobe.observation import (
+    Generation,
+    Observation,
+    ObservationRuntime,
+    observation_scope,
+    start_generation,
+    start_observation,
+)
+from softprobe.propagation import propagate_attributes
+from softprobe.redaction import default_redact_keys
+from softprobe.scores import HttpScoreTransport, build_score_request
+from softprobe.tools import tool_span_attributes
+from softprobe.types import ObservationType, ScoreDataType, ScoreSource, ScoreTransport
+
+
+class SoftprobeClient:
+    def __init__(
+        self,
+        *,
+        public_key: str,
+        base_url: str,
+        otlp_endpoint: str | None = None,
+        service_name: str = "softprobe-app",
+        service_version: str | None = None,
+        environment: str | None = None,
+        release: str | None = None,
+        session_id: str | None = None,
+        user_id: str | None = None,
+        tags: list[str] | None = None,
+        redact_keys: list[str] | None = None,
+        timeout_ms: int = 10_000,
+        headers: Mapping[str, str] | None = None,
+        span_exporter: SpanExporter | None = None,
+        score_transport: ScoreTransport | None = None,
+        use_simple_processor: bool = False,
+    ) -> None:
+        if not public_key or not public_key.strip():
+            raise ValueError("public_key is required")
+        if not base_url or not base_url.strip():
+            raise ValueError("base_url is required")
+        base_url = base_url.strip()
+        resolved_otlp = (
+            otlp_endpoint.strip()
+            if otlp_endpoint and otlp_endpoint.strip()
+            else derive_otlp_endpoint(base_url)
+        )
+        if span_exporter is None and not resolved_otlp:
+            raise ValueError("otlp_endpoint is required")
+
+        resource_attrs: dict[str, str] = {
+            ResourceAttributes.SERVICE_NAME: service_name,
+            "telemetry.sdk.name": "softprobe",
+        }
+        if service_version:
+            resource_attrs[ResourceAttributes.SERVICE_VERSION] = service_version
+        if environment:
+            resource_attrs["deployment.environment.name"] = environment
+
+        exporter = span_exporter or OTLPSpanExporter(
+            endpoint=resolved_otlp,
+            headers={
+                "Authorization": f"Bearer {public_key}",
+                **dict(headers or {}),
+            },
+            timeout=timeout_ms / 1000.0,
+        )
+        processor = (
+            SimpleSpanProcessor(exporter)
+            if use_simple_processor
+            else BatchSpanProcessor(exporter)
+        )
+        self._provider = TracerProvider(resource=Resource.create(resource_attrs))
+        self._provider.add_span_processor(processor)
+        # Avoid set_tracer_provider so multiple clients/tests can coexist.
+        # Parent/child linking uses explicit context attach on observations.
+
+        self._runtime = ObservationRuntime(
+            tracer=self._provider.get_tracer("softprobe", "0.1.0"),
+            redact_keys=redact_keys or default_redact_keys(),
+            session_id=session_id,
+            user_id=user_id,
+            release=release,
+            tags=tags,
+        )
+        self._score_transport = score_transport or HttpScoreTransport(
+            base_url,
+            public_key.strip(),
+            headers or {},
+            timeout_ms,
+        )
+        self._shut_down = False
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> SoftprobeClient:
+        """Build a client from ``SOFTPROBE_*`` environment variables.
+
+        Requires ``SOFTPROBE_PUBLIC_KEY`` and ``SOFTPROBE_BASE_URL``.
+        Keyword overrides are merged on top of the resolved env config.
+        """
+        cfg = resolve_softprobe_config_from_env()
+        if cfg is None:
+            raise MissingSoftprobeCredentialsError(
+                "Set SOFTPROBE_PUBLIC_KEY and SOFTPROBE_BASE_URL"
+            )
+        kwargs: dict[str, Any] = {
+            "public_key": cfg["public_key"],
+            "base_url": cfg["base_url"],
+            "otlp_endpoint": cfg.get("otlp_endpoint"),
+        }
+        if cfg.get("environment"):
+            kwargs["environment"] = cfg["environment"]
+        if cfg.get("session_id"):
+            kwargs["session_id"] = cfg["session_id"]
+        if cfg.get("user_id"):
+            kwargs["user_id"] = cfg["user_id"]
+        if cfg.get("service_name"):
+            kwargs["service_name"] = cfg["service_name"]
+        kwargs.update(overrides)
+        return cls(**kwargs)
+
+    def start_observation(
+        self,
+        *,
+        name: str,
+        as_type: ObservationType = "span",
+        attributes: Mapping[str, Any] | None = None,
+        input: Any | None = None,
+        output: Any | None = None,
+        session_id: str | None = None,
+        user_id: str | None = None,
+        release: str | None = None,
+        tags: list[str] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        version: str | None = None,
+        trace_name: str | None = None,
+        parent: Observation | None = None,
+        trace_context: Mapping[str, str] | None = None,
+        start_time: datetime | float | int | None = None,
+    ) -> Observation:
+        self._assert_active()
+        return start_observation(
+            self._runtime,
+            name=name,
+            as_type=as_type,
+            attributes=attributes,
+            input=input,
+            output=output,
+            session_id=session_id,
+            user_id=user_id,
+            release=release,
+            tags=tags,
+            metadata=metadata,
+            version=version,
+            trace_name=trace_name,
+            parent=parent,
+            trace_context=trace_context,
+            start_time=start_time,
+        )
+
+    def start_generation(self, *, name: str, **kwargs: Any) -> Generation:
+        self._assert_active()
+        return start_generation(self._runtime, name=name, **kwargs)
+
+    def propagate_attributes(self, **kwargs: Any) -> Any:
+        """Context manager that scopes session/user/tags/metadata for nested work."""
+        return propagate_attributes(**kwargs)
+
+    @property
+    def tracer(self) -> Any:
+        return self._runtime.tracer
+
+    def start_agent(self, *, name: str, **kwargs: Any) -> Observation:
+        return self.start_observation(name=name, as_type="agent", **kwargs)
+
+    def start_tool(
+        self,
+        *,
+        name: str,
+        tool_name: str | None = None,
+        tool_call_id: str | None = None,
+        kind: str | None = None,
+        status: str | None = None,
+        index: int | None = None,
+        mcp_server: str | None = None,
+        mcp_tool: str | None = None,
+        attributes: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Observation:
+        merged = dict(attributes or {})
+        merged.update(
+            tool_span_attributes(
+                tool_name=tool_name or name,
+                tool_call_id=tool_call_id,
+                kind=kind or "function",
+                status=status or "ok",
+                index=index,
+                mcp_server=mcp_server,
+                mcp_tool=mcp_tool,
+            )
+        )
+        return self.start_observation(
+            name=name, as_type="tool", attributes=merged, **kwargs
+        )
+
+    def start_chain(self, *, name: str, **kwargs: Any) -> Observation:
+        return self.start_observation(name=name, as_type="chain", **kwargs)
+
+    def start_retriever(self, *, name: str, **kwargs: Any) -> Observation:
+        return self.start_observation(name=name, as_type="retriever", **kwargs)
+
+    def start_evaluator(self, *, name: str, **kwargs: Any) -> Observation:
+        return self.start_observation(name=name, as_type="evaluator", **kwargs)
+
+    def start_embedding(self, *, name: str, **kwargs: Any) -> Observation:
+        return self.start_observation(name=name, as_type="embedding", **kwargs)
+
+    def start_guardrail(self, *, name: str, **kwargs: Any) -> Observation:
+        return self.start_observation(name=name, as_type="guardrail", **kwargs)
+
+    def start_event(self, *, name: str, **kwargs: Any) -> Observation:
+        return self.start_observation(name=name, as_type="event", **kwargs)
+
+    @contextmanager
+    def observation(self, *, name: str, **kwargs: Any) -> Iterator[Observation]:
+        obs = self.start_observation(name=name, **kwargs)
+        with observation_scope(obs) as scoped:
+            yield scoped
+
+    @contextmanager
+    def generation(self, *, name: str, **kwargs: Any) -> Iterator[Generation]:
+        gen = self.start_generation(name=name, **kwargs)
+        with observation_scope(gen) as scoped:
+            yield scoped  # type: ignore[misc]
+
+    @asynccontextmanager
+    async def async_observation(
+        self, *, name: str, **kwargs: Any
+    ) -> AsyncIterator[Observation]:
+        with self.observation(name=name, **kwargs) as obs:
+            yield obs
+
+    @asynccontextmanager
+    async def async_generation(
+        self, *, name: str, **kwargs: Any
+    ) -> AsyncIterator[Generation]:
+        with self.generation(name=name, **kwargs) as gen:
+            yield gen
+
+    def create_score(
+        self,
+        *,
+        score_id: str,
+        name: str,
+        data_type: ScoreDataType,
+        source: ScoreSource,
+        timestamp: str | datetime | None = None,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+        session_id: str | None = None,
+        numeric_value: float | None = None,
+        string_value: str | None = None,
+        boolean_value: bool | None = None,
+        comment: str | None = None,
+        config_id: str | None = None,
+        author_id: str | None = None,
+        metadata: Mapping[str, str] | None = None,
+    ) -> None:
+        self._assert_active()
+        request = build_score_request(
+            score_id=score_id,
+            name=name,
+            data_type=data_type,
+            source=source,
+            timestamp=timestamp,
+            trace_id=trace_id,
+            span_id=span_id,
+            session_id=session_id,
+            numeric_value=numeric_value,
+            string_value=string_value,
+            boolean_value=boolean_value,
+            comment=comment,
+            config_id=config_id,
+            author_id=author_id,
+            metadata=metadata,
+        )
+        self._score_transport.create_score(request)
+
+    def force_flush(self, timeout_millis: int = 30_000) -> bool:
+        return bool(self._provider.force_flush(timeout_millis))
+
+    def flush(self, timeout_millis: int = 30_000) -> bool:
+        """Alias for :meth:`force_flush`."""
+        return self.force_flush(timeout_millis)
+
+    def shutdown(self) -> None:
+        if self._shut_down:
+            return
+        self._shut_down = True
+        self._provider.shutdown()
+
+    def _assert_active(self) -> None:
+        if self._shut_down:
+            raise RuntimeError("SoftprobeClient has been shut down")

softprobe/config.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping, TypedDict
+
+
+class ResolvedSoftprobeConfig(TypedDict, total=False):
+    public_key: str
+    base_url: str
+    otlp_endpoint: str
+    environment: str
+    session_id: str
+    user_id: str
+    service_name: str
+
+
+class MissingSoftprobeCredentialsError(ValueError):
+    """Raised when Softprobe credentials cannot be resolved."""
+
+
+def as_non_empty_string(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    trimmed = value.strip()
+    return trimmed if trimmed else None
+
+
+def derive_otlp_endpoint(base_url: str, explicit: str | None = None) -> str:
+    if explicit and explicit.strip():
+        return explicit.strip()
+    return f"{base_url.rstrip('/')}/v1/traces"
+
+
+def resolve_softprobe_config_from_env(
+    env: Mapping[str, str | None] | None = None,
+) -> ResolvedSoftprobeConfig | None:
+    source = env if env is not None else os.environ
+    public_key = as_non_empty_string(source.get("SOFTPROBE_PUBLIC_KEY"))
+    base_url = as_non_empty_string(source.get("SOFTPROBE_BASE_URL"))
+    if not public_key or not base_url:
+        return None
+    return ResolvedSoftprobeConfig(
+        public_key=public_key,
+        base_url=base_url,
+        otlp_endpoint=derive_otlp_endpoint(
+            base_url,
+            as_non_empty_string(source.get("SOFTPROBE_OTLP_ENDPOINT")),
+        ),
+        environment=as_non_empty_string(source.get("SOFTPROBE_ENVIRONMENT")),
+        session_id=as_non_empty_string(source.get("SOFTPROBE_SESSION_ID")),
+        user_id=as_non_empty_string(source.get("SOFTPROBE_USER_ID")),
+        service_name=as_non_empty_string(source.get("SOFTPROBE_SERVICE_NAME")),
+    )
+
+
+def resolve_softprobe_config_from_mapping(raw: Mapping[str, Any]) -> ResolvedSoftprobeConfig:
+    public_key = as_non_empty_string(raw.get("public_key") or raw.get("publicKey"))
+    base_url = as_non_empty_string(raw.get("base_url") or raw.get("baseUrl"))
+    if not public_key or not base_url:
+        raise MissingSoftprobeCredentialsError("public_key and base_url are required")
+    explicit = as_non_empty_string(raw.get("otlp_endpoint") or raw.get("otlpEndpoint"))
+    return ResolvedSoftprobeConfig(
+        public_key=public_key,
+        base_url=base_url,
+        otlp_endpoint=derive_otlp_endpoint(base_url, explicit),
+        environment=as_non_empty_string(raw.get("environment")),
+        session_id=as_non_empty_string(raw.get("session_id") or raw.get("sessionId")),
+        user_id=as_non_empty_string(raw.get("user_id") or raw.get("userId")),
+        service_name=as_non_empty_string(raw.get("service_name") or raw.get("serviceName")),
+    )

softprobe/identity.py

@@ -0,0 +1,75 @@
+"""Resolve product conversation / user identity from the builder's world.
+
+Priority: LangChain/LangGraph run metadata (incl. configurable) →
+explicit Softprobe fallbacks → SOFTPROBE_* env.
+Softprobe never invents a session id.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+SESSION_KEYS = (
+    "thread_id",
+    "threadId",
+    "session_id",
+    "sessionId",
+    "conversation_id",
+    "conversationId",
+    "chat_id",
+    "chatId",
+)
+
+USER_KEYS = ("user_id", "userId", "user")
+
+
+def _as_non_empty(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    trimmed = value.strip()
+    return trimmed or None
+
+
+def _first_key(sources: list[Mapping[str, Any] | None], keys: tuple[str, ...]) -> str | None:
+    for source in sources:
+        if not source:
+            continue
+        for key in keys:
+            found = _as_non_empty(source.get(key))
+            if found:
+                return found
+    return None
+
+
+def identity_sources_from_metadata(
+    metadata: Mapping[str, Any] | None,
+) -> list[Mapping[str, Any] | None]:
+    if not metadata:
+        return []
+    configurable = metadata.get("configurable")
+    if isinstance(configurable, Mapping):
+        return [configurable, metadata]
+    return [metadata]
+
+
+def resolve_run_identity(
+    *,
+    metadata: Mapping[str, Any] | None = None,
+    fallback_session_id: str | None = None,
+    fallback_user_id: str | None = None,
+    env: Mapping[str, str | None] | None = None,
+) -> tuple[str | None, str | None]:
+    source_env = env if env is not None else os.environ
+    from_meta = identity_sources_from_metadata(metadata)
+    session_id = (
+        _first_key(from_meta, SESSION_KEYS)
+        or _as_non_empty(fallback_session_id)
+        or _as_non_empty(source_env.get("SOFTPROBE_SESSION_ID"))
+    )
+    user_id = (
+        _first_key(from_meta, USER_KEYS)
+        or _as_non_empty(fallback_user_id)
+        or _as_non_empty(source_env.get("SOFTPROBE_USER_ID"))
+    )
+    return session_id, user_id