langfuse

Langfuse Python SDK — observability, evaluation, and prompt management for LLM applications.

Capabilities:

Quickstart:

# env: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
from langfuse import get_client

langfuse = get_client()

# Create a span using a context manager
with langfuse.start_as_current_observation(as_type="span", name="process-request") as span:
    # Your processing logic here
    span.update(output="Processing complete")

    # Create a nested generation for an LLM call
    with langfuse.start_as_current_observation(as_type="generation", name="llm-response", model="gpt-3.5-turbo") as generation:
        # Your LLM call logic here
        generation.update(output="Generated response")

# All spans are automatically closed when exiting their context blocks

# Flush events in short-lived applications
langfuse.flush()

Configuration is via constructor args or environment variables: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL (defaults to https://cloud.langfuse.com). See langfuse._client.environment_variables for the full list.

Docs: https://langfuse.com/docs — machine-readable index: https://langfuse.com/llms.txt

  1"""Langfuse Python SDK — observability, evaluation, and prompt management for LLM applications.
  2
  3Capabilities:
  4
  5- **Tracing / observability**: `@observe` decorator, `Langfuse.start_observation` /
  6  `start_as_current_observation` context managers, OpenTelemetry-based; integrations
  7  for OpenAI (`langfuse.openai`) and LangChain (`langfuse.langchain.CallbackHandler`).
  8- **Trace attributes**: `propagate_attributes` (top-level function) sets user_id,
  9  session_id, tags, and metadata on all spans in a context.
 10- **Datasets & experiments**: `Langfuse.get_dataset`, `Langfuse.run_experiment` for
 11  offline evaluation and regression testing of prompt/model changes (CI support via
 12  https://github.com/langfuse/experiment-action and `RegressionError`).
 13- **Evaluation / LLM-as-a-judge**: `Evaluation` results from custom or model-based
 14  evaluators; scores via `Langfuse.create_score` / `span.score`.
 15- **Prompt management**: `Langfuse.get_prompt`, `Langfuse.create_prompt` with
 16  client-side caching and version/label control.
 17- **Full REST API**: `Langfuse.api` (sync) / `Langfuse.async_api` (async) clients.
 18
 19Quickstart:
 20
 21```python
 22# env: LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_BASE_URL
 23from langfuse import get_client
 24
 25langfuse = get_client()
 26
 27# Create a span using a context manager
 28with langfuse.start_as_current_observation(as_type="span", name="process-request") as span:
 29    # Your processing logic here
 30    span.update(output="Processing complete")
 31
 32    # Create a nested generation for an LLM call
 33    with langfuse.start_as_current_observation(as_type="generation", name="llm-response", model="gpt-3.5-turbo") as generation:
 34        # Your LLM call logic here
 35        generation.update(output="Generated response")
 36
 37# All spans are automatically closed when exiting their context blocks
 38
 39# Flush events in short-lived applications
 40langfuse.flush()
 41```
 42
 43Configuration is via constructor args or environment variables: `LANGFUSE_PUBLIC_KEY`,
 44`LANGFUSE_SECRET_KEY`, `LANGFUSE_BASE_URL` (defaults to https://cloud.langfuse.com). See `langfuse._client.environment_variables`
 45for the full list.
 46
 47Docs: https://langfuse.com/docs — machine-readable index: https://langfuse.com/llms.txt
 48
 49.. include:: ../README.md
 50"""
 51
 52from langfuse.batch_evaluation import (
 53    BatchEvaluationResult,
 54    BatchEvaluationResumeToken,
 55    CompositeEvaluatorFunction,
 56    EvaluatorInputs,
 57    EvaluatorStats,
 58    MapperFunction,
 59)
 60from langfuse.experiment import Evaluation, RegressionError, RunnerContext
 61
 62from ._client import client as _client_module
 63from ._client.attributes import LangfuseOtelSpanAttributes
 64from ._client.constants import ObservationTypeLiteral
 65from ._client.get_client import get_client
 66from ._client.observe import observe
 67from ._client.propagation import propagate_attributes
 68from ._client.span import (
 69    LangfuseAgent,
 70    LangfuseChain,
 71    LangfuseEmbedding,
 72    LangfuseEvaluator,
 73    LangfuseEvent,
 74    LangfuseGeneration,
 75    LangfuseGuardrail,
 76    LangfuseRetriever,
 77    LangfuseSpan,
 78    LangfuseTool,
 79)
 80from ._version import __version__
 81from .media import LangfuseMedia, LangfuseMediaReference
 82from .span_filter import (
 83    KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES,
 84    is_default_export_span,
 85    is_genai_span,
 86    is_known_llm_instrumentor,
 87    is_langfuse_span,
 88)
 89from .types import (
 90    MaskOtelSpansFunction,
 91    MaskOtelSpansParams,
 92    MaskOtelSpansResult,
 93    OtelSpanData,
 94    OtelSpanIdentifier,
 95    OtelSpanPatch,
 96)
 97
 98Langfuse = _client_module.Langfuse
 99
100__all__ = [
101    "Langfuse",
102    "LangfuseMedia",
103    "LangfuseMediaReference",
104    "get_client",
105    "observe",
106    "propagate_attributes",
107    "ObservationTypeLiteral",
108    "LangfuseSpan",
109    "LangfuseGeneration",
110    "LangfuseEvent",
111    "LangfuseOtelSpanAttributes",
112    "LangfuseAgent",
113    "LangfuseTool",
114    "LangfuseChain",
115    "LangfuseEmbedding",
116    "LangfuseEvaluator",
117    "LangfuseRetriever",
118    "LangfuseGuardrail",
119    "Evaluation",
120    "EvaluatorInputs",
121    "MapperFunction",
122    "CompositeEvaluatorFunction",
123    "EvaluatorStats",
124    "BatchEvaluationResumeToken",
125    "BatchEvaluationResult",
126    "RunnerContext",
127    "RegressionError",
128    "__version__",
129    "is_default_export_span",
130    "is_langfuse_span",
131    "is_genai_span",
132    "is_known_llm_instrumentor",
133    "KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES",
134    "MaskOtelSpansFunction",
135    "MaskOtelSpansParams",
136    "MaskOtelSpansResult",
137    "OtelSpanData",
138    "OtelSpanIdentifier",
139    "OtelSpanPatch",
140    "experiment",
141    "api",
142]
class Langfuse: 
 156class Langfuse:
 157    """Main client for Langfuse tracing and platform features.
 158
 159    This class provides an interface for creating and managing traces, spans,
 160    and generations in Langfuse as well as interacting with the Langfuse API.
 161
 162    The client features a thread-safe singleton pattern for each unique public API key,
 163    ensuring consistent trace context propagation across your application. It implements
 164    efficient batching of spans with configurable flush settings and includes background
 165    thread management for media uploads and score ingestion.
 166
 167    Configuration is flexible through either direct parameters or environment variables,
 168    with graceful fallbacks and runtime configuration updates.
 169
 170    Attributes:
 171        api: Synchronous API client for Langfuse backend communication
 172        async_api: Asynchronous API client for Langfuse backend communication
 173        _otel_tracer: Internal LangfuseTracer instance managing OpenTelemetry components
 174
 175    Parameters:
 176        public_key (Optional[str]): Your Langfuse public API key. Can also be set via LANGFUSE_PUBLIC_KEY environment variable.
 177        secret_key (Optional[str]): Your Langfuse secret API key. Can also be set via LANGFUSE_SECRET_KEY environment variable.
 178        base_url (Optional[str]): The Langfuse API base URL. Defaults to "https://cloud.langfuse.com". Can also be set via LANGFUSE_BASE_URL environment variable.
 179        host (Optional[str]): Deprecated. Use base_url instead. The Langfuse API host URL. Defaults to "https://cloud.langfuse.com".
 180        timeout (Optional[int]): Timeout in seconds for API requests. Defaults to 5 seconds.
 181        httpx_client (Optional[httpx.Client]): Custom httpx client for making non-tracing HTTP requests. If not provided, a default client will be created.
 182            **Fork safety**: ``httpx.Client`` is thread-safe but not process-safe. When using
 183            ``fork()``-based servers (e.g. Gunicorn with ``--preload``), the SDK automatically
 184            recreates its internally-managed HTTP client in child processes after fork. A custom
 185            ``httpx_client`` is intentionally left as-is (the fork-inherited copy is reused), so
 186            you retain the opportunity to handle process-safety yourself — for example by
 187            registering your own ``os.register_at_fork(after_in_child=...)`` handler to close and
 188            reopen connections on the custom client.
 189        debug (bool): Enable debug logging. Defaults to False. Can also be set via LANGFUSE_DEBUG environment variable.
 190        tracing_enabled (Optional[bool]): Enable or disable tracing. Defaults to True. Can also be set via LANGFUSE_TRACING_ENABLED environment variable.
 191        flush_at (Optional[int]): Number of spans to batch before sending to the API. Defaults to 512. Can also be set via LANGFUSE_FLUSH_AT environment variable.
 192        flush_interval (Optional[float]): Time in seconds between batch flushes. Defaults to 5 seconds. Can also be set via LANGFUSE_FLUSH_INTERVAL environment variable.
 193        environment (Optional[str]): Environment name for tracing. Default is 'default'. Can also be set via LANGFUSE_TRACING_ENVIRONMENT environment variable. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
 194        release (Optional[str]): Release version/hash of your application. Used for grouping analytics by release.
 195        media_upload_thread_count (Optional[int]): Number of background threads for handling media uploads. Defaults to 1. Can also be set via LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT environment variable.
 196        sample_rate (Optional[float]): Sampling rate for traces (0.0 to 1.0). Defaults to 1.0 (100% of traces are sampled). Can also be set via LANGFUSE_SAMPLE_RATE environment variable.
 197        mask (Optional[MaskFunction]): Function to mask sensitive data synchronously when Langfuse SDK attributes are created. This applies only to data set through Langfuse SDK APIs such as `start_observation()`, `update()`, and `set_trace_io()`.
 198        mask_otel_spans (Optional[MaskOtelSpansFunction]): Synchronous export-stage hook for masking raw OpenTelemetry span attributes before this Langfuse client sends them to Langfuse. Use this for spans created by third-party OpenTelemetry instrumentations, or when you need to inspect final span attributes after export filtering and Langfuse media handling. It does not modify spans already exported through other OpenTelemetry exporters.
 199
 200            The hook receives one OpenTelemetry export batch. A batch is not guaranteed to contain a complete trace, request, or Langfuse observation tree. The hook usually runs on the OpenTelemetry batch span processor worker thread; during `flush()` and shutdown it may run on the caller thread. Keep it synchronous, deterministic, and fast.
 201
 202            Return `None` to leave the batch unchanged. Return `MaskOtelSpansResult` with `OtelSpanPatch` values to delete or replace attributes on selected spans. If the hook raises or returns an invalid batch result, Langfuse drops the whole export batch. If one returned span patch is invalid, Langfuse drops only that span from the Langfuse export.
 203
 204            Example:
 205                ```python
 206                from typing import Optional
 207
 208                from langfuse import Langfuse
 209                from langfuse.types import (
 210                    MaskOtelSpansParams,
 211                    MaskOtelSpansResult,
 212                    OtelSpanPatch,
 213                )
 214
 215                def mask_otel_spans(
 216                    *, params: MaskOtelSpansParams
 217                ) -> Optional[MaskOtelSpansResult]:
 218                    patches = {}
 219
 220                    for identifier, span in params.spans.items():
 221                        if "gen_ai.prompt.0.content" in span.attributes:
 222                            patches[identifier] = OtelSpanPatch(
 223                                delete_attributes=("gen_ai.prompt.0.content",),
 224                                set_attributes={"masking.applied": True},
 225                            )
 226
 227                    return MaskOtelSpansResult(span_patches=patches)
 228
 229                langfuse = Langfuse(mask_otel_spans=mask_otel_spans)
 230                ```
 231        blocked_instrumentation_scopes (Optional[List[str]]): Deprecated. Use `should_export_span` instead. Equivalent behavior:
 232            ```python
 233            from langfuse.span_filter import is_default_export_span
 234            blocked = {"sqlite", "requests"}
 235
 236            should_export_span = lambda span: (
 237                is_default_export_span(span)
 238                and (
 239                    span.instrumentation_scope is None
 240                    or span.instrumentation_scope.name not in blocked
 241                )
 242            )
 243            ```
 244        should_export_span (Optional[Callable[[ReadableSpan], bool]]): Callback to decide whether to export a span. If omitted, Langfuse uses the default filter (Langfuse SDK spans, spans with `gen_ai.*` attributes, and known LLM instrumentation scopes).
 245        additional_headers (Optional[Dict[str, str]]): Additional headers to include in all API requests and in the default OTLPSpanExporter requests. These headers will be merged with default headers. Note: If httpx_client is provided, additional_headers must be set directly on your custom httpx_client as well. If `span_exporter` is provided, these headers are not wired into that exporter and must be configured on the exporter instance directly.
 246        tracer_provider(Optional[TracerProvider]): OpenTelemetry TracerProvider to use for Langfuse. This can be useful to set to have disconnected tracing between Langfuse and other OpenTelemetry-span emitting libraries. Note: To track active spans, the context is still shared between TracerProviders. This may lead to broken trace trees.
 247        id_generator (Optional[IdGenerator]): OpenTelemetry ID generator to use when Langfuse creates its own TracerProvider. If omitted, the OpenTelemetry SDK default is used. If `tracer_provider` is provided, or an OpenTelemetry TracerProvider is already registered globally, configure the ID generator on that provider instead.
 248        span_exporter (Optional[SpanExporter]): Custom OpenTelemetry span exporter for the Langfuse span processor. If omitted, Langfuse creates an OTLPSpanExporter pointed at the Langfuse OTLP endpoint. If provided, Langfuse does not wire `base_url`, exporter headers, exporter auth, or exporter timeout into it. Configure endpoint, headers, and timeout on the exporter instance directly. If you are sending spans to Langfuse v4 or using Langfuse Cloud Fast Preview, include `x-langfuse-ingestion-version=4` on the exporter to enable real time processing of exported spans.
 249
 250    Example:
 251        ```python
 252        from langfuse import Langfuse
 253
 254        # Initialize the client (reads from env vars if not provided)
 255        langfuse = Langfuse(
 256            public_key="your-public-key",
 257            secret_key="your-secret-key",
 258            base_url="https://cloud.langfuse.com",  # Optional, default shown
 259        )
 260
 261        # Create a trace span
 262        with langfuse.start_as_current_observation(name="process-query") as span:
 263            # Your application code here
 264
 265            # Create a nested generation span for an LLM call
 266            with span.start_as_current_generation(
 267                name="generate-response",
 268                model="gpt-4",
 269                input={"query": "Tell me about AI"},
 270                model_parameters={"temperature": 0.7, "max_tokens": 500}
 271            ) as generation:
 272                # Generate response here
 273                response = "AI is a field of computer science..."
 274
 275                generation.update(
 276                    output=response,
 277                    usage_details={"prompt_tokens": 10, "completion_tokens": 50},
 278                    cost_details={"total_cost": 0.0023}
 279                )
 280
 281                # Score the generation (supports NUMERIC, BOOLEAN, CATEGORICAL)
 282                generation.score(name="relevance", value=0.95, data_type="NUMERIC")
 283        ```
 284    """
 285
 286    _resources: Optional[LangfuseResourceManager] = None
 287    _mask: Optional[MaskFunction] = None
 288    _otel_tracer: otel_trace_api.Tracer
 289
 290    def __init__(
 291        self,
 292        *,
 293        public_key: Optional[str] = None,
 294        secret_key: Optional[str] = None,
 295        base_url: Optional[str] = None,
 296        host: Optional[str] = None,
 297        timeout: Optional[int] = None,
 298        httpx_client: Optional[httpx.Client] = None,
 299        debug: bool = False,
 300        tracing_enabled: Optional[bool] = True,
 301        flush_at: Optional[int] = None,
 302        flush_interval: Optional[float] = None,
 303        environment: Optional[str] = None,
 304        release: Optional[str] = None,
 305        media_upload_thread_count: Optional[int] = None,
 306        sample_rate: Optional[float] = None,
 307        mask: Optional[MaskFunction] = None,
 308        mask_otel_spans: Optional[MaskOtelSpansFunction] = None,
 309        blocked_instrumentation_scopes: Optional[List[str]] = None,
 310        should_export_span: Optional[Callable[[ReadableSpan], bool]] = None,
 311        additional_headers: Optional[Dict[str, str]] = None,
 312        tracer_provider: Optional[TracerProvider] = None,
 313        id_generator: Optional[IdGenerator] = None,
 314        span_exporter: Optional[SpanExporter] = None,
 315    ):
 316        self._base_url = (
 317            base_url
 318            or os.environ.get(LANGFUSE_BASE_URL)
 319            or host
 320            or os.environ.get(LANGFUSE_HOST, "https://cloud.langfuse.com")
 321        )
 322        self._environment = environment or cast(
 323            str, os.environ.get(LANGFUSE_TRACING_ENVIRONMENT)
 324        )
 325        self._release = (
 326            release
 327            or os.environ.get(LANGFUSE_RELEASE, None)
 328            or get_common_release_envs()
 329        )
 330        self._project_id: Optional[str] = None
 331        sample_rate = sample_rate or float(os.environ.get(LANGFUSE_SAMPLE_RATE, 1.0))
 332        if not 0.0 <= sample_rate <= 1.0:
 333            raise ValueError(
 334                f"Sample rate must be between 0.0 and 1.0, got {sample_rate}"
 335            )
 336
 337        timeout = timeout or int(os.environ.get(LANGFUSE_TIMEOUT, 5))
 338
 339        self._tracing_enabled = (
 340            tracing_enabled
 341            and os.environ.get(LANGFUSE_TRACING_ENABLED, "true").lower() != "false"
 342        )
 343        if not self._tracing_enabled:
 344            langfuse_logger.info(
 345                "Configuration: Langfuse tracing is explicitly disabled. No data will be sent to the Langfuse API."
 346            )
 347
 348        debug = (
 349            debug if debug else (os.getenv(LANGFUSE_DEBUG, "false").lower() == "true")
 350        )
 351        if debug:
 352            logging.basicConfig(
 353                format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 354            )
 355            langfuse_logger.setLevel(logging.DEBUG)
 356
 357        public_key = public_key or os.environ.get(LANGFUSE_PUBLIC_KEY)
 358        if public_key is None:
 359            langfuse_logger.warning(
 360                "Authentication error: Langfuse client initialized without public_key. Client will be disabled. "
 361                "Provide a public_key parameter or set LANGFUSE_PUBLIC_KEY environment variable. "
 362            )
 363            self._otel_tracer = otel_trace_api.NoOpTracer()
 364            return
 365
 366        secret_key = secret_key or os.environ.get(LANGFUSE_SECRET_KEY)
 367        if secret_key is None:
 368            langfuse_logger.warning(
 369                "Authentication error: Langfuse client initialized without secret_key. Client will be disabled. "
 370                "Provide a secret_key parameter or set LANGFUSE_SECRET_KEY environment variable. "
 371            )
 372            self._otel_tracer = otel_trace_api.NoOpTracer()
 373            return
 374
 375        if os.environ.get("OTEL_SDK_DISABLED", "false").lower() == "true":
 376            langfuse_logger.warning(
 377                "OTEL_SDK_DISABLED is set. Langfuse tracing will be disabled and no traces will appear in the UI."
 378            )
 379
 380        if blocked_instrumentation_scopes is not None:
 381            warnings.warn(
 382                "`blocked_instrumentation_scopes` is deprecated and will be removed in a future release. "
 383                "Use `should_export_span` instead. Example: "
 384                "from langfuse.span_filter import is_default_export_span; "
 385                'blocked={"scope"}; should_export_span=lambda span: '
 386                "is_default_export_span(span) and (span.instrumentation_scope is None or "
 387                "span.instrumentation_scope.name not in blocked).",
 388                DeprecationWarning,
 389                stacklevel=2,
 390            )
 391
 392        # Initialize api and tracer if requirements are met
 393        self._resources = LangfuseResourceManager(
 394            public_key=public_key,
 395            secret_key=secret_key,
 396            base_url=self._base_url,
 397            timeout=timeout,
 398            environment=self._environment,
 399            release=release,
 400            flush_at=flush_at,
 401            flush_interval=flush_interval,
 402            httpx_client=httpx_client,
 403            media_upload_thread_count=media_upload_thread_count,
 404            sample_rate=sample_rate,
 405            mask=mask,
 406            mask_otel_spans=mask_otel_spans,
 407            tracing_enabled=self._tracing_enabled,
 408            blocked_instrumentation_scopes=blocked_instrumentation_scopes,
 409            should_export_span=should_export_span,
 410            additional_headers=additional_headers,
 411            tracer_provider=tracer_provider,
 412            id_generator=id_generator,
 413            span_exporter=span_exporter,
 414        )
 415        self._mask = self._resources.mask
 416
 417        self._otel_tracer = (
 418            self._resources.tracer
 419            if self._tracing_enabled and self._resources.tracer is not None
 420            else otel_trace_api.NoOpTracer()
 421        )
 422
 423    @property
 424    def api(self) -> LangfuseAPI:
 425        """Synchronous client for the full Langfuse REST API (traces, observations, scores, datasets, prompts, ...).
 426
 427        Use this to read or manage data on the Langfuse server; use the tracing methods
 428        (`start_observation`, `@observe`) to create traces. Use `async_api` for the
 429        asyncio variant.
 430
 431        Semantics that are easy to miss:
 432
 433        - **Ingestion is asynchronous.** `langfuse.flush()` only guarantees delivery to
 434          the API, not read visibility: reads such as `api.trace.get(trace_id)` may
 435          raise `langfuse.api.NotFoundError` until processing completes (typically
 436          within 15-30 seconds; longer under load). The same applies to scores and
 437          dataset run reads. Instead of a fixed sleep, retry with a deadline:
 438
 439        - **List endpoints return lightweight views.** `api.trace.list(...)` returns
 440          `TraceWithDetails`, where `observations` and `scores` are lists of ID strings.
 441          Fetch the full objects with `api.trace.get(trace_id)` (`TraceWithFullDetails`),
 442          or prefer `api.observations.get_many(trace_id=...)` for row-level observation
 443          queries. The same list-view vs. get-detail pattern applies to other resources.
 444
 445        - **Prefer the v2 data APIs — they are the defaults since SDK v4.**
 446          `api.observations` and `api.metrics` map to the high-performance
 447          `/api/public/v2/...` endpoints and are the recommended read path. Their v1
 448          equivalents remain available under `api.legacy.observations_v1` /
 449          `api.legacy.metrics_v1` but are less performant at scale, not recommended
 450          for new workflows, and will be deprecated.
 451
 452        - For large-scale aggregation (usage/cost by model, user, etc.), prefer the
 453        v2 Metrics API (`api.metrics.metrics(...)`) over paginating row-level data.
 454
 455
 456        See also: `async_api`,
 457        https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk
 458        (ingestion lag: #ingestion-lag, list vs. get: #traces-list-vs-get),
 459        https://langfuse.com/docs/api-and-data-platform/features/observations-api,
 460        https://langfuse.com/docs/metrics/features/metrics-api
 461        """
 462        if self._resources is None:
 463            raise AttributeError("Langfuse client is not initialized")
 464
 465        return self._resources.api
 466
 467    @api.setter
 468    def api(self, value: LangfuseAPI) -> None:
 469        if self._resources is None:
 470            raise AttributeError("Langfuse client is not initialized")
 471
 472        self._resources.api = value
 473
 474    @property
 475    def async_api(self) -> AsyncLangfuseAPI:
 476        if self._resources is None:
 477            raise AttributeError("Langfuse client is not initialized")
 478
 479        return self._resources.async_api
 480
 481    @async_api.setter
 482    def async_api(self, value: AsyncLangfuseAPI) -> None:
 483        if self._resources is None:
 484            raise AttributeError("Langfuse client is not initialized")
 485
 486        self._resources.async_api = value
 487
 488    @overload
 489    def start_observation(
 490        self,
 491        *,
 492        trace_context: Optional[TraceContext] = None,
 493        name: str,
 494        as_type: Literal["generation"],
 495        input: Optional[Any] = None,
 496        output: Optional[Any] = None,
 497        metadata: Optional[Any] = None,
 498        version: Optional[str] = None,
 499        level: Optional[SpanLevel] = None,
 500        status_message: Optional[str] = None,
 501        completion_start_time: Optional[datetime] = None,
 502        model: Optional[str] = None,
 503        model_parameters: Optional[Dict[str, MapValue]] = None,
 504        usage_details: Optional[Dict[str, int]] = None,
 505        cost_details: Optional[Dict[str, float]] = None,
 506        prompt: Optional[PromptClient] = None,
 507    ) -> LangfuseGeneration: ...
 508
 509    @overload
 510    def start_observation(
 511        self,
 512        *,
 513        trace_context: Optional[TraceContext] = None,
 514        name: str,
 515        as_type: Literal["span"] = "span",
 516        input: Optional[Any] = None,
 517        output: Optional[Any] = None,
 518        metadata: Optional[Any] = None,
 519        version: Optional[str] = None,
 520        level: Optional[SpanLevel] = None,
 521        status_message: Optional[str] = None,
 522    ) -> LangfuseSpan: ...
 523
 524    @overload
 525    def start_observation(
 526        self,
 527        *,
 528        trace_context: Optional[TraceContext] = None,
 529        name: str,
 530        as_type: Literal["agent"],
 531        input: Optional[Any] = None,
 532        output: Optional[Any] = None,
 533        metadata: Optional[Any] = None,
 534        version: Optional[str] = None,
 535        level: Optional[SpanLevel] = None,
 536        status_message: Optional[str] = None,
 537    ) -> LangfuseAgent: ...
 538
 539    @overload
 540    def start_observation(
 541        self,
 542        *,
 543        trace_context: Optional[TraceContext] = None,
 544        name: str,
 545        as_type: Literal["tool"],
 546        input: Optional[Any] = None,
 547        output: Optional[Any] = None,
 548        metadata: Optional[Any] = None,
 549        version: Optional[str] = None,
 550        level: Optional[SpanLevel] = None,
 551        status_message: Optional[str] = None,
 552    ) -> LangfuseTool: ...
 553
 554    @overload
 555    def start_observation(
 556        self,
 557        *,
 558        trace_context: Optional[TraceContext] = None,
 559        name: str,
 560        as_type: Literal["chain"],
 561        input: Optional[Any] = None,
 562        output: Optional[Any] = None,
 563        metadata: Optional[Any] = None,
 564        version: Optional[str] = None,
 565        level: Optional[SpanLevel] = None,
 566        status_message: Optional[str] = None,
 567    ) -> LangfuseChain: ...
 568
 569    @overload
 570    def start_observation(
 571        self,
 572        *,
 573        trace_context: Optional[TraceContext] = None,
 574        name: str,
 575        as_type: Literal["retriever"],
 576        input: Optional[Any] = None,
 577        output: Optional[Any] = None,
 578        metadata: Optional[Any] = None,
 579        version: Optional[str] = None,
 580        level: Optional[SpanLevel] = None,
 581        status_message: Optional[str] = None,
 582    ) -> LangfuseRetriever: ...
 583
 584    @overload
 585    def start_observation(
 586        self,
 587        *,
 588        trace_context: Optional[TraceContext] = None,
 589        name: str,
 590        as_type: Literal["evaluator"],
 591        input: Optional[Any] = None,
 592        output: Optional[Any] = None,
 593        metadata: Optional[Any] = None,
 594        version: Optional[str] = None,
 595        level: Optional[SpanLevel] = None,
 596        status_message: Optional[str] = None,
 597    ) -> LangfuseEvaluator: ...
 598
 599    @overload
 600    def start_observation(
 601        self,
 602        *,
 603        trace_context: Optional[TraceContext] = None,
 604        name: str,
 605        as_type: Literal["embedding"],
 606        input: Optional[Any] = None,
 607        output: Optional[Any] = None,
 608        metadata: Optional[Any] = None,
 609        version: Optional[str] = None,
 610        level: Optional[SpanLevel] = None,
 611        status_message: Optional[str] = None,
 612        completion_start_time: Optional[datetime] = None,
 613        model: Optional[str] = None,
 614        model_parameters: Optional[Dict[str, MapValue]] = None,
 615        usage_details: Optional[Dict[str, int]] = None,
 616        cost_details: Optional[Dict[str, float]] = None,
 617        prompt: Optional[PromptClient] = None,
 618    ) -> LangfuseEmbedding: ...
 619
 620    @overload
 621    def start_observation(
 622        self,
 623        *,
 624        trace_context: Optional[TraceContext] = None,
 625        name: str,
 626        as_type: Literal["guardrail"],
 627        input: Optional[Any] = None,
 628        output: Optional[Any] = None,
 629        metadata: Optional[Any] = None,
 630        version: Optional[str] = None,
 631        level: Optional[SpanLevel] = None,
 632        status_message: Optional[str] = None,
 633    ) -> LangfuseGuardrail: ...
 634
 635    def start_observation(
 636        self,
 637        *,
 638        trace_context: Optional[TraceContext] = None,
 639        name: str,
 640        as_type: ObservationTypeLiteralNoEvent = "span",
 641        input: Optional[Any] = None,
 642        output: Optional[Any] = None,
 643        metadata: Optional[Any] = None,
 644        version: Optional[str] = None,
 645        level: Optional[SpanLevel] = None,
 646        status_message: Optional[str] = None,
 647        completion_start_time: Optional[datetime] = None,
 648        model: Optional[str] = None,
 649        model_parameters: Optional[Dict[str, MapValue]] = None,
 650        usage_details: Optional[Dict[str, int]] = None,
 651        cost_details: Optional[Dict[str, float]] = None,
 652        prompt: Optional[PromptClient] = None,
 653    ) -> Union[
 654        LangfuseSpan,
 655        LangfuseGeneration,
 656        LangfuseAgent,
 657        LangfuseTool,
 658        LangfuseChain,
 659        LangfuseRetriever,
 660        LangfuseEvaluator,
 661        LangfuseEmbedding,
 662        LangfuseGuardrail,
 663    ]:
 664        """Create a new observation of the specified type.
 665
 666        This method creates a new observation but does not set it as the current span in the
 667        context. To create and use an observation within a context, use start_as_current_observation().
 668
 669        Args:
 670            trace_context: Optional context for connecting to an existing trace
 671            name: Name of the observation
 672            as_type: Type of observation to create (defaults to "span")
 673            input: Input data for the operation
 674            output: Output data from the operation
 675            metadata: Additional metadata to associate with the observation
 676            version: Version identifier for the code or component
 677            level: Importance level of the observation
 678            status_message: Optional status message for the observation
 679            completion_start_time: When the model started generating (for generation types)
 680            model: Name/identifier of the AI model used (for generation types)
 681            model_parameters: Parameters used for the model (for generation types)
 682            usage_details: Token usage information (for generation types)
 683            cost_details: Cost information (for generation types)
 684            prompt: Associated prompt template (for generation types)
 685
 686        Returns:
 687            An observation object of the appropriate type that must be ended with .end()
 688        """
 689        if trace_context:
 690            trace_id = trace_context.get("trace_id", None)
 691            parent_span_id = trace_context.get("parent_span_id", None)
 692
 693            if trace_id:
 694                remote_parent_span = self._create_remote_parent_span(
 695                    trace_id=trace_id, parent_span_id=parent_span_id
 696                )
 697
 698                with otel_trace_api.use_span(
 699                    cast(otel_trace_api.Span, remote_parent_span)
 700                ):
 701                    otel_span = self._otel_tracer.start_span(name=name)
 702                    otel_span.set_attribute(LangfuseOtelSpanAttributes.AS_ROOT, True)
 703
 704                    return self._create_observation_from_otel_span(
 705                        otel_span=otel_span,
 706                        as_type=as_type,
 707                        input=input,
 708                        output=output,
 709                        metadata=metadata,
 710                        version=version,
 711                        level=level,
 712                        status_message=status_message,
 713                        completion_start_time=completion_start_time,
 714                        model=model,
 715                        model_parameters=model_parameters,
 716                        usage_details=usage_details,
 717                        cost_details=cost_details,
 718                        prompt=prompt,
 719                    )
 720
 721        otel_span = self._otel_tracer.start_span(name=name)
 722
 723        return self._create_observation_from_otel_span(
 724            otel_span=otel_span,
 725            as_type=as_type,
 726            input=input,
 727            output=output,
 728            metadata=metadata,
 729            version=version,
 730            level=level,
 731            status_message=status_message,
 732            completion_start_time=completion_start_time,
 733            model=model,
 734            model_parameters=model_parameters,
 735            usage_details=usage_details,
 736            cost_details=cost_details,
 737            prompt=prompt,
 738        )
 739
 740    def _create_observation_from_otel_span(
 741        self,
 742        *,
 743        otel_span: otel_trace_api.Span,
 744        as_type: ObservationTypeLiteralNoEvent,
 745        input: Optional[Any] = None,
 746        output: Optional[Any] = None,
 747        metadata: Optional[Any] = None,
 748        version: Optional[str] = None,
 749        level: Optional[SpanLevel] = None,
 750        status_message: Optional[str] = None,
 751        completion_start_time: Optional[datetime] = None,
 752        model: Optional[str] = None,
 753        model_parameters: Optional[Dict[str, MapValue]] = None,
 754        usage_details: Optional[Dict[str, int]] = None,
 755        cost_details: Optional[Dict[str, float]] = None,
 756        prompt: Optional[PromptClient] = None,
 757    ) -> Union[
 758        LangfuseSpan,
 759        LangfuseGeneration,
 760        LangfuseAgent,
 761        LangfuseTool,
 762        LangfuseChain,
 763        LangfuseRetriever,
 764        LangfuseEvaluator,
 765        LangfuseEmbedding,
 766        LangfuseGuardrail,
 767    ]:
 768        """Create the appropriate observation type from an OTEL span."""
 769        if as_type in get_observation_types_list(ObservationTypeGenerationLike):
 770            observation_class = self._get_span_class(as_type)
 771            # Type ignore to prevent overloads of internal _get_span_class function,
 772            # issue is that LangfuseEvent could be returned and that classes have diff. args
 773            return observation_class(  # type: ignore[return-value,call-arg]
 774                otel_span=otel_span,
 775                langfuse_client=self,
 776                environment=self._environment,
 777                release=self._release,
 778                input=input,
 779                output=output,
 780                metadata=metadata,
 781                version=version,
 782                level=level,
 783                status_message=status_message,
 784                completion_start_time=completion_start_time,
 785                model=model,
 786                model_parameters=model_parameters,
 787                usage_details=usage_details,
 788                cost_details=cost_details,
 789                prompt=prompt,
 790            )
 791        else:
 792            # For other types (e.g. span, guardrail), create appropriate class without generation properties
 793            observation_class = self._get_span_class(as_type)
 794            # Type ignore to prevent overloads of internal _get_span_class function,
 795            # issue is that LangfuseEvent could be returned and that classes have diff. args
 796            return observation_class(  # type: ignore[return-value,call-arg]
 797                otel_span=otel_span,
 798                langfuse_client=self,
 799                environment=self._environment,
 800                release=self._release,
 801                input=input,
 802                output=output,
 803                metadata=metadata,
 804                version=version,
 805                level=level,
 806                status_message=status_message,
 807            )
 808            # span._observation_type = as_type
 809            # span._otel_span.set_attribute("langfuse.observation.type", as_type)
 810            # return span
 811
 812    @overload
 813    def start_as_current_observation(
 814        self,
 815        *,
 816        trace_context: Optional[TraceContext] = None,
 817        name: str,
 818        as_type: Literal["generation"],
 819        input: Optional[Any] = None,
 820        output: Optional[Any] = None,
 821        metadata: Optional[Any] = None,
 822        version: Optional[str] = None,
 823        level: Optional[SpanLevel] = None,
 824        status_message: Optional[str] = None,
 825        completion_start_time: Optional[datetime] = None,
 826        model: Optional[str] = None,
 827        model_parameters: Optional[Dict[str, MapValue]] = None,
 828        usage_details: Optional[Dict[str, int]] = None,
 829        cost_details: Optional[Dict[str, float]] = None,
 830        prompt: Optional[PromptClient] = None,
 831        end_on_exit: Optional[bool] = None,
 832    ) -> _AgnosticContextManager[LangfuseGeneration]: ...
 833
 834    @overload
 835    def start_as_current_observation(
 836        self,
 837        *,
 838        trace_context: Optional[TraceContext] = None,
 839        name: str,
 840        as_type: Literal["span"] = "span",
 841        input: Optional[Any] = None,
 842        output: Optional[Any] = None,
 843        metadata: Optional[Any] = None,
 844        version: Optional[str] = None,
 845        level: Optional[SpanLevel] = None,
 846        status_message: Optional[str] = None,
 847        end_on_exit: Optional[bool] = None,
 848    ) -> _AgnosticContextManager[LangfuseSpan]: ...
 849
 850    @overload
 851    def start_as_current_observation(
 852        self,
 853        *,
 854        trace_context: Optional[TraceContext] = None,
 855        name: str,
 856        as_type: Literal["agent"],
 857        input: Optional[Any] = None,
 858        output: Optional[Any] = None,
 859        metadata: Optional[Any] = None,
 860        version: Optional[str] = None,
 861        level: Optional[SpanLevel] = None,
 862        status_message: Optional[str] = None,
 863        end_on_exit: Optional[bool] = None,
 864    ) -> _AgnosticContextManager[LangfuseAgent]: ...
 865
 866    @overload
 867    def start_as_current_observation(
 868        self,
 869        *,
 870        trace_context: Optional[TraceContext] = None,
 871        name: str,
 872        as_type: Literal["tool"],
 873        input: Optional[Any] = None,
 874        output: Optional[Any] = None,
 875        metadata: Optional[Any] = None,
 876        version: Optional[str] = None,
 877        level: Optional[SpanLevel] = None,
 878        status_message: Optional[str] = None,
 879        end_on_exit: Optional[bool] = None,
 880    ) -> _AgnosticContextManager[LangfuseTool]: ...
 881
 882    @overload
 883    def start_as_current_observation(
 884        self,
 885        *,
 886        trace_context: Optional[TraceContext] = None,
 887        name: str,
 888        as_type: Literal["chain"],
 889        input: Optional[Any] = None,
 890        output: Optional[Any] = None,
 891        metadata: Optional[Any] = None,
 892        version: Optional[str] = None,
 893        level: Optional[SpanLevel] = None,
 894        status_message: Optional[str] = None,
 895        end_on_exit: Optional[bool] = None,
 896    ) -> _AgnosticContextManager[LangfuseChain]: ...
 897
 898    @overload
 899    def start_as_current_observation(
 900        self,
 901        *,
 902        trace_context: Optional[TraceContext] = None,
 903        name: str,
 904        as_type: Literal["retriever"],
 905        input: Optional[Any] = None,
 906        output: Optional[Any] = None,
 907        metadata: Optional[Any] = None,
 908        version: Optional[str] = None,
 909        level: Optional[SpanLevel] = None,
 910        status_message: Optional[str] = None,
 911        end_on_exit: Optional[bool] = None,
 912    ) -> _AgnosticContextManager[LangfuseRetriever]: ...
 913
 914    @overload
 915    def start_as_current_observation(
 916        self,
 917        *,
 918        trace_context: Optional[TraceContext] = None,
 919        name: str,
 920        as_type: Literal["evaluator"],
 921        input: Optional[Any] = None,
 922        output: Optional[Any] = None,
 923        metadata: Optional[Any] = None,
 924        version: Optional[str] = None,
 925        level: Optional[SpanLevel] = None,
 926        status_message: Optional[str] = None,
 927        end_on_exit: Optional[bool] = None,
 928    ) -> _AgnosticContextManager[LangfuseEvaluator]: ...
 929
 930    @overload
 931    def start_as_current_observation(
 932        self,
 933        *,
 934        trace_context: Optional[TraceContext] = None,
 935        name: str,
 936        as_type: Literal["embedding"],
 937        input: Optional[Any] = None,
 938        output: Optional[Any] = None,
 939        metadata: Optional[Any] = None,
 940        version: Optional[str] = None,
 941        level: Optional[SpanLevel] = None,
 942        status_message: Optional[str] = None,
 943        completion_start_time: Optional[datetime] = None,
 944        model: Optional[str] = None,
 945        model_parameters: Optional[Dict[str, MapValue]] = None,
 946        usage_details: Optional[Dict[str, int]] = None,
 947        cost_details: Optional[Dict[str, float]] = None,
 948        prompt: Optional[PromptClient] = None,
 949        end_on_exit: Optional[bool] = None,
 950    ) -> _AgnosticContextManager[LangfuseEmbedding]: ...
 951
 952    @overload
 953    def start_as_current_observation(
 954        self,
 955        *,
 956        trace_context: Optional[TraceContext] = None,
 957        name: str,
 958        as_type: Literal["guardrail"],
 959        input: Optional[Any] = None,
 960        output: Optional[Any] = None,
 961        metadata: Optional[Any] = None,
 962        version: Optional[str] = None,
 963        level: Optional[SpanLevel] = None,
 964        status_message: Optional[str] = None,
 965        end_on_exit: Optional[bool] = None,
 966    ) -> _AgnosticContextManager[LangfuseGuardrail]: ...
 967
 968    def start_as_current_observation(
 969        self,
 970        *,
 971        trace_context: Optional[TraceContext] = None,
 972        name: str,
 973        as_type: ObservationTypeLiteralNoEvent = "span",
 974        input: Optional[Any] = None,
 975        output: Optional[Any] = None,
 976        metadata: Optional[Any] = None,
 977        version: Optional[str] = None,
 978        level: Optional[SpanLevel] = None,
 979        status_message: Optional[str] = None,
 980        completion_start_time: Optional[datetime] = None,
 981        model: Optional[str] = None,
 982        model_parameters: Optional[Dict[str, MapValue]] = None,
 983        usage_details: Optional[Dict[str, int]] = None,
 984        cost_details: Optional[Dict[str, float]] = None,
 985        prompt: Optional[PromptClient] = None,
 986        end_on_exit: Optional[bool] = None,
 987    ) -> Union[
 988        _AgnosticContextManager[LangfuseGeneration],
 989        _AgnosticContextManager[LangfuseSpan],
 990        _AgnosticContextManager[LangfuseAgent],
 991        _AgnosticContextManager[LangfuseTool],
 992        _AgnosticContextManager[LangfuseChain],
 993        _AgnosticContextManager[LangfuseRetriever],
 994        _AgnosticContextManager[LangfuseEvaluator],
 995        _AgnosticContextManager[LangfuseEmbedding],
 996        _AgnosticContextManager[LangfuseGuardrail],
 997    ]:
 998        """Create a new observation and set it as the current span in a context manager.
 999
1000        This method creates a new observation of the specified type and sets it as the
1001        current span within a context manager. Use this method with a 'with' statement to
1002        automatically handle the observation lifecycle within a code block.
1003
1004        The created observation will be the child of the current span in the context.
1005
1006        Args:
1007            trace_context: Optional context for connecting to an existing trace
1008            name: Name of the observation (e.g., function or operation name)
1009            as_type: Type of observation to create (defaults to "span")
1010            input: Input data for the operation (can be any JSON-serializable object)
1011            output: Output data from the operation (can be any JSON-serializable object)
1012            metadata: Additional metadata to associate with the observation
1013            version: Version identifier for the code or component
1014            level: Importance level of the observation (info, warning, error)
1015            status_message: Optional status message for the observation
1016            end_on_exit (default: True): Whether to end the span automatically when leaving the context manager. If False, the span must be manually ended to avoid memory leaks.
1017
1018            The following parameters are available when as_type is: "generation" or "embedding".
1019            completion_start_time: When the model started generating the response
1020            model: Name/identifier of the AI model used (e.g., "gpt-4")
1021            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1022            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1023            cost_details: Cost information for the model call
1024            prompt: Associated prompt template from Langfuse prompt management
1025
1026        Returns:
1027            A context manager that yields the appropriate observation type based on as_type
1028
1029        Example:
1030            ```python
1031            # Create a span
1032            with langfuse.start_as_current_observation(name="process-query", as_type="span") as span:
1033                # Do work
1034                result = process_data()
1035                span.update(output=result)
1036
1037                # Create a child span automatically
1038                with span.start_as_current_observation(name="sub-operation") as child_span:
1039                    # Do sub-operation work
1040                    child_span.update(output="sub-result")
1041
1042            # Create a tool observation
1043            with langfuse.start_as_current_observation(name="web-search", as_type="tool") as tool:
1044                # Do tool work
1045                results = search_web(query)
1046                tool.update(output=results)
1047
1048            # Create a generation observation
1049            with langfuse.start_as_current_observation(
1050                name="answer-generation",
1051                as_type="generation",
1052                model="gpt-4"
1053            ) as generation:
1054                # Generate answer
1055                response = llm.generate(...)
1056                generation.update(output=response)
1057            ```
1058        """
1059        if as_type in get_observation_types_list(ObservationTypeGenerationLike):
1060            if trace_context:
1061                trace_id = trace_context.get("trace_id", None)
1062                parent_span_id = trace_context.get("parent_span_id", None)
1063
1064                if trace_id:
1065                    remote_parent_span = self._create_remote_parent_span(
1066                        trace_id=trace_id, parent_span_id=parent_span_id
1067                    )
1068
1069                    return cast(
1070                        Union[
1071                            _AgnosticContextManager[LangfuseGeneration],
1072                            _AgnosticContextManager[LangfuseEmbedding],
1073                        ],
1074                        self._create_span_with_parent_context(
1075                            as_type=as_type,
1076                            name=name,
1077                            remote_parent_span=remote_parent_span,
1078                            parent=None,
1079                            end_on_exit=end_on_exit,
1080                            input=input,
1081                            output=output,
1082                            metadata=metadata,
1083                            version=version,
1084                            level=level,
1085                            status_message=status_message,
1086                            completion_start_time=completion_start_time,
1087                            model=model,
1088                            model_parameters=model_parameters,
1089                            usage_details=usage_details,
1090                            cost_details=cost_details,
1091                            prompt=prompt,
1092                        ),
1093                    )
1094
1095            return cast(
1096                Union[
1097                    _AgnosticContextManager[LangfuseGeneration],
1098                    _AgnosticContextManager[LangfuseEmbedding],
1099                ],
1100                self._start_as_current_otel_span_with_processed_media(
1101                    as_type=as_type,
1102                    name=name,
1103                    end_on_exit=end_on_exit,
1104                    input=input,
1105                    output=output,
1106                    metadata=metadata,
1107                    version=version,
1108                    level=level,
1109                    status_message=status_message,
1110                    completion_start_time=completion_start_time,
1111                    model=model,
1112                    model_parameters=model_parameters,
1113                    usage_details=usage_details,
1114                    cost_details=cost_details,
1115                    prompt=prompt,
1116                ),
1117            )
1118
1119        if as_type in get_observation_types_list(ObservationTypeSpanLike):
1120            if trace_context:
1121                trace_id = trace_context.get("trace_id", None)
1122                parent_span_id = trace_context.get("parent_span_id", None)
1123
1124                if trace_id:
1125                    remote_parent_span = self._create_remote_parent_span(
1126                        trace_id=trace_id, parent_span_id=parent_span_id
1127                    )
1128
1129                    return cast(
1130                        Union[
1131                            _AgnosticContextManager[LangfuseSpan],
1132                            _AgnosticContextManager[LangfuseAgent],
1133                            _AgnosticContextManager[LangfuseTool],
1134                            _AgnosticContextManager[LangfuseChain],
1135                            _AgnosticContextManager[LangfuseRetriever],
1136                            _AgnosticContextManager[LangfuseEvaluator],
1137                            _AgnosticContextManager[LangfuseGuardrail],
1138                        ],
1139                        self._create_span_with_parent_context(
1140                            as_type=as_type,
1141                            name=name,
1142                            remote_parent_span=remote_parent_span,
1143                            parent=None,
1144                            end_on_exit=end_on_exit,
1145                            input=input,
1146                            output=output,
1147                            metadata=metadata,
1148                            version=version,
1149                            level=level,
1150                            status_message=status_message,
1151                        ),
1152                    )
1153
1154            return cast(
1155                Union[
1156                    _AgnosticContextManager[LangfuseSpan],
1157                    _AgnosticContextManager[LangfuseAgent],
1158                    _AgnosticContextManager[LangfuseTool],
1159                    _AgnosticContextManager[LangfuseChain],
1160                    _AgnosticContextManager[LangfuseRetriever],
1161                    _AgnosticContextManager[LangfuseEvaluator],
1162                    _AgnosticContextManager[LangfuseGuardrail],
1163                ],
1164                self._start_as_current_otel_span_with_processed_media(
1165                    as_type=as_type,
1166                    name=name,
1167                    end_on_exit=end_on_exit,
1168                    input=input,
1169                    output=output,
1170                    metadata=metadata,
1171                    version=version,
1172                    level=level,
1173                    status_message=status_message,
1174                ),
1175            )
1176
1177        # This should never be reached since all valid types are handled above
1178        langfuse_logger.warning(
1179            f"Unknown observation type: {as_type}, falling back to span"
1180        )
1181        return self._start_as_current_otel_span_with_processed_media(
1182            as_type="span",
1183            name=name,
1184            end_on_exit=end_on_exit,
1185            input=input,
1186            output=output,
1187            metadata=metadata,
1188            version=version,
1189            level=level,
1190            status_message=status_message,
1191        )
1192
1193    def _get_span_class(
1194        self,
1195        as_type: str,
1196    ) -> Union[
1197        Type[LangfuseAgent],
1198        Type[LangfuseTool],
1199        Type[LangfuseChain],
1200        Type[LangfuseRetriever],
1201        Type[LangfuseEvaluator],
1202        Type[LangfuseEmbedding],
1203        Type[LangfuseGuardrail],
1204        Type[LangfuseGeneration],
1205        Type[LangfuseEvent],
1206        Type[LangfuseSpan],
1207    ]:
1208        """Get the appropriate span class based on as_type."""
1209        normalized_type = as_type.lower()
1210
1211        if normalized_type == "agent":
1212            return LangfuseAgent
1213        elif normalized_type == "tool":
1214            return LangfuseTool
1215        elif normalized_type == "chain":
1216            return LangfuseChain
1217        elif normalized_type == "retriever":
1218            return LangfuseRetriever
1219        elif normalized_type == "evaluator":
1220            return LangfuseEvaluator
1221        elif normalized_type == "embedding":
1222            return LangfuseEmbedding
1223        elif normalized_type == "guardrail":
1224            return LangfuseGuardrail
1225        elif normalized_type == "generation":
1226            return LangfuseGeneration
1227        elif normalized_type == "event":
1228            return LangfuseEvent
1229        elif normalized_type == "span":
1230            return LangfuseSpan
1231        else:
1232            return LangfuseSpan
1233
1234    @staticmethod
1235    def _get_observation_type_from_otel_span(otel_span: otel_trace_api.Span) -> str:
1236        if not otel_span.is_recording():
1237            return "span"
1238
1239        attributes = getattr(otel_span, "attributes", None)
1240        if attributes is None or not hasattr(attributes, "get"):
1241            return "span"
1242
1243        observation_type = attributes.get(
1244            LangfuseOtelSpanAttributes.OBSERVATION_TYPE, "span"
1245        )
1246
1247        return observation_type if isinstance(observation_type, str) else "span"
1248
1249    @_agnosticcontextmanager
1250    def _create_span_with_parent_context(
1251        self,
1252        *,
1253        name: str,
1254        parent: Optional[otel_trace_api.Span] = None,
1255        remote_parent_span: Optional[otel_trace_api.Span] = None,
1256        as_type: ObservationTypeLiteralNoEvent,
1257        end_on_exit: Optional[bool] = None,
1258        input: Optional[Any] = None,
1259        output: Optional[Any] = None,
1260        metadata: Optional[Any] = None,
1261        version: Optional[str] = None,
1262        level: Optional[SpanLevel] = None,
1263        status_message: Optional[str] = None,
1264        completion_start_time: Optional[datetime] = None,
1265        model: Optional[str] = None,
1266        model_parameters: Optional[Dict[str, MapValue]] = None,
1267        usage_details: Optional[Dict[str, int]] = None,
1268        cost_details: Optional[Dict[str, float]] = None,
1269        prompt: Optional[PromptClient] = None,
1270    ) -> Any:
1271        parent_span = parent or cast(otel_trace_api.Span, remote_parent_span)
1272
1273        with otel_trace_api.use_span(parent_span):
1274            with self._start_as_current_otel_span_with_processed_media(
1275                name=name,
1276                as_type=as_type,
1277                end_on_exit=end_on_exit,
1278                input=input,
1279                output=output,
1280                metadata=metadata,
1281                version=version,
1282                level=level,
1283                status_message=status_message,
1284                completion_start_time=completion_start_time,
1285                model=model,
1286                model_parameters=model_parameters,
1287                usage_details=usage_details,
1288                cost_details=cost_details,
1289                prompt=prompt,
1290            ) as langfuse_span:
1291                if remote_parent_span is not None:
1292                    langfuse_span._otel_span.set_attribute(
1293                        LangfuseOtelSpanAttributes.AS_ROOT, True
1294                    )
1295
1296                yield langfuse_span
1297
1298    @_agnosticcontextmanager
1299    def _start_as_current_otel_span_with_processed_media(
1300        self,
1301        *,
1302        name: str,
1303        as_type: Optional[ObservationTypeLiteralNoEvent] = None,
1304        end_on_exit: Optional[bool] = None,
1305        input: Optional[Any] = None,
1306        output: Optional[Any] = None,
1307        metadata: Optional[Any] = None,
1308        version: Optional[str] = None,
1309        level: Optional[SpanLevel] = None,
1310        status_message: Optional[str] = None,
1311        completion_start_time: Optional[datetime] = None,
1312        model: Optional[str] = None,
1313        model_parameters: Optional[Dict[str, MapValue]] = None,
1314        usage_details: Optional[Dict[str, int]] = None,
1315        cost_details: Optional[Dict[str, float]] = None,
1316        prompt: Optional[PromptClient] = None,
1317    ) -> Any:
1318        with self._otel_tracer.start_as_current_span(
1319            name=name,
1320            end_on_exit=end_on_exit if end_on_exit is not None else True,
1321        ) as otel_span:
1322            baggage_token = None
1323
1324            if otel_span.is_recording():
1325                context_with_app_root_claim = _set_langfuse_trace_id_in_baggage(
1326                    trace_id=self._get_otel_trace_id(otel_span),
1327                    context=otel_context_api.get_current(),
1328                )
1329                baggage_token = otel_context_api.attach(context_with_app_root_claim)
1330
1331            span_class = self._get_span_class(
1332                as_type or "generation"
1333            )  # default was "generation"
1334
1335            try:
1336                common_args = {
1337                    "otel_span": otel_span,
1338                    "langfuse_client": self,
1339                    "environment": self._environment,
1340                    "release": self._release,
1341                    "input": input,
1342                    "output": output,
1343                    "metadata": metadata,
1344                    "version": version,
1345                    "level": level,
1346                    "status_message": status_message,
1347                }
1348
1349                if span_class in [
1350                    LangfuseGeneration,
1351                    LangfuseEmbedding,
1352                ]:
1353                    common_args.update(
1354                        {
1355                            "completion_start_time": completion_start_time,
1356                            "model": model,
1357                            "model_parameters": model_parameters,
1358                            "usage_details": usage_details,
1359                            "cost_details": cost_details,
1360                            "prompt": prompt,
1361                        }
1362                    )
1363                # For span-like types (span, agent, tool, chain, retriever, evaluator, guardrail), no generation properties needed
1364
1365                yield span_class(**common_args)  # type: ignore[arg-type]
1366
1367            finally:
1368                if baggage_token is not None:
1369                    _detach_context_token_safely(baggage_token)
1370
1371    def _get_current_otel_span(self) -> Optional[otel_trace_api.Span]:
1372        current_span = otel_trace_api.get_current_span()
1373
1374        if current_span is otel_trace_api.INVALID_SPAN:
1375            langfuse_logger.warning(
1376                "Context error: No active span in current context. Operations that depend on an active span will be skipped. "
1377                "Ensure spans are created with start_as_current_observation() or that you're operating within an active span context."
1378            )
1379            return None
1380
1381        return current_span
1382
1383    def update_current_generation(
1384        self,
1385        *,
1386        name: Optional[str] = None,
1387        input: Optional[Any] = None,
1388        output: Optional[Any] = None,
1389        metadata: Optional[Any] = None,
1390        version: Optional[str] = None,
1391        level: Optional[SpanLevel] = None,
1392        status_message: Optional[str] = None,
1393        completion_start_time: Optional[datetime] = None,
1394        model: Optional[str] = None,
1395        model_parameters: Optional[Dict[str, MapValue]] = None,
1396        usage_details: Optional[Dict[str, int]] = None,
1397        cost_details: Optional[Dict[str, float]] = None,
1398        prompt: Optional[PromptClient] = None,
1399    ) -> None:
1400        """Update the current active generation span with new information.
1401
1402        This method updates the current generation span in the active context with
1403        additional information. It's useful for adding output, usage stats, or other
1404        details that become available during or after model generation.
1405
1406        Args:
1407            name: The generation name
1408            input: Updated input data for the model
1409            output: Output from the model (e.g., completions)
1410            metadata: Additional metadata to associate with the generation
1411            version: Version identifier for the model or component
1412            level: Importance level of the generation (info, warning, error)
1413            status_message: Optional status message for the generation
1414            completion_start_time: When the model started generating the response
1415            model: Name/identifier of the AI model used (e.g., "gpt-4")
1416            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1417            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1418            cost_details: Cost information for the model call
1419            prompt: Associated prompt template from Langfuse prompt management
1420
1421        Example:
1422            ```python
1423            with langfuse.start_as_current_generation(name="answer-query") as generation:
1424                # Initial setup and API call
1425                response = llm.generate(...)
1426
1427                # Update with results that weren't available at creation time
1428                langfuse.update_current_generation(
1429                    output=response.text,
1430                    usage_details={
1431                        "prompt_tokens": response.usage.prompt_tokens,
1432                        "completion_tokens": response.usage.completion_tokens
1433                    }
1434                )
1435            ```
1436        """
1437        if not self._tracing_enabled:
1438            langfuse_logger.debug(
1439                "Operation skipped: update_current_generation - Tracing is disabled or client is in no-op mode."
1440            )
1441            return
1442
1443        current_otel_span = self._get_current_otel_span()
1444
1445        if current_otel_span is not None:
1446            generation = LangfuseGeneration(
1447                otel_span=current_otel_span, langfuse_client=self
1448            )
1449
1450            if name:
1451                current_otel_span.update_name(name)
1452
1453            generation.update(
1454                input=input,
1455                output=output,
1456                metadata=metadata,
1457                version=version,
1458                level=level,
1459                status_message=status_message,
1460                completion_start_time=completion_start_time,
1461                model=model,
1462                model_parameters=model_parameters,
1463                usage_details=usage_details,
1464                cost_details=cost_details,
1465                prompt=prompt,
1466            )
1467
1468    def update_current_span(
1469        self,
1470        *,
1471        name: Optional[str] = None,
1472        input: Optional[Any] = None,
1473        output: Optional[Any] = None,
1474        metadata: Optional[Any] = None,
1475        version: Optional[str] = None,
1476        level: Optional[SpanLevel] = None,
1477        status_message: Optional[str] = None,
1478    ) -> None:
1479        """Update the current active span with new information.
1480
1481        This method updates the current span in the active context with
1482        additional information. It's useful for adding outputs or metadata
1483        that become available during execution.
1484
1485        Args:
1486            name: The span name
1487            input: Updated input data for the operation
1488            output: Output data from the operation
1489            metadata: Additional metadata to associate with the span
1490            version: Version identifier for the code or component
1491            level: Importance level of the span (info, warning, error)
1492            status_message: Optional status message for the span
1493
1494        Example:
1495            ```python
1496            with langfuse.start_as_current_observation(name="process-data") as span:
1497                # Initial processing
1498                result = process_first_part()
1499
1500                # Update with intermediate results
1501                langfuse.update_current_span(metadata={"intermediate_result": result})
1502
1503                # Continue processing
1504                final_result = process_second_part(result)
1505
1506                # Final update
1507                langfuse.update_current_span(output=final_result)
1508            ```
1509        """
1510        if not self._tracing_enabled:
1511            langfuse_logger.debug(
1512                "Operation skipped: update_current_span - Tracing is disabled or client is in no-op mode."
1513            )
1514            return
1515
1516        current_otel_span = self._get_current_otel_span()
1517
1518        if current_otel_span is not None:
1519            span_class = self._get_span_class(
1520                self._get_observation_type_from_otel_span(current_otel_span)
1521            )
1522            span = span_class(
1523                otel_span=current_otel_span,
1524                langfuse_client=self,
1525                environment=self._environment,
1526                release=self._release,
1527            )
1528
1529            if name:
1530                current_otel_span.update_name(name)
1531
1532            span.update(
1533                input=input,
1534                output=output,
1535                metadata=metadata,
1536                version=version,
1537                level=level,
1538                status_message=status_message,
1539            )
1540
1541    @deprecated(
1542        "Trace-level input/output is deprecated. "
1543        "For trace attributes (user_id, session_id, tags, etc.), use propagate_attributes() instead. "
1544        "This method will be removed in a future major version."
1545    )
1546    def set_current_trace_io(
1547        self,
1548        *,
1549        input: Optional[Any] = None,
1550        output: Optional[Any] = None,
1551    ) -> None:
1552        """Set trace-level input and output for the current span's trace.
1553
1554        .. deprecated::
1555            This is a legacy method for backward compatibility with Langfuse platform
1556            features that still rely on trace-level input/output (e.g., legacy LLM-as-a-judge
1557            evaluators). It will be removed in a future major version.
1558
1559            For setting other trace attributes (user_id, session_id, metadata, tags, version),
1560            use :func:`langfuse.propagate_attributes` (top-level import) instead.
1561
1562        Args:
1563            input: Input data to associate with the trace.
1564            output: Output data to associate with the trace.
1565        """
1566        if not self._tracing_enabled:
1567            langfuse_logger.debug(
1568                "Operation skipped: set_current_trace_io - Tracing is disabled or client is in no-op mode."
1569            )
1570            return
1571
1572        current_otel_span = self._get_current_otel_span()
1573
1574        if current_otel_span is not None and current_otel_span.is_recording():
1575            span_class = self._get_span_class(
1576                self._get_observation_type_from_otel_span(current_otel_span)
1577            )
1578            span = span_class(
1579                otel_span=current_otel_span,
1580                langfuse_client=self,
1581                environment=self._environment,
1582                release=self._release,
1583            )
1584
1585            span.set_trace_io(
1586                input=input,
1587                output=output,
1588            )
1589
1590    def set_current_trace_as_public(self) -> None:
1591        """Make the current trace publicly accessible via its URL.
1592
1593        When a trace is published, anyone with the trace link can view the full trace
1594        without needing to be logged in to Langfuse. This action cannot be undone
1595        programmatically - once published, the entire trace becomes public.
1596
1597        This is a convenience method that publishes the trace from the currently
1598        active span context. Use this when you want to make a trace public from
1599        within a traced function without needing direct access to the span object.
1600        """
1601        if not self._tracing_enabled:
1602            langfuse_logger.debug(
1603                "Operation skipped: set_current_trace_as_public - Tracing is disabled or client is in no-op mode."
1604            )
1605            return
1606
1607        current_otel_span = self._get_current_otel_span()
1608
1609        if current_otel_span is not None and current_otel_span.is_recording():
1610            span_class = self._get_span_class(
1611                self._get_observation_type_from_otel_span(current_otel_span)
1612            )
1613            span = span_class(
1614                otel_span=current_otel_span,
1615                langfuse_client=self,
1616                environment=self._environment,
1617            )
1618
1619            span.set_trace_as_public()
1620
1621    def create_event(
1622        self,
1623        *,
1624        trace_context: Optional[TraceContext] = None,
1625        name: str,
1626        input: Optional[Any] = None,
1627        output: Optional[Any] = None,
1628        metadata: Optional[Any] = None,
1629        version: Optional[str] = None,
1630        level: Optional[SpanLevel] = None,
1631        status_message: Optional[str] = None,
1632    ) -> LangfuseEvent:
1633        """Create a new Langfuse observation of type 'EVENT'.
1634
1635        The created Langfuse Event observation will be the child of the current span in the context.
1636
1637        Args:
1638            trace_context: Optional context for connecting to an existing trace
1639            name: Name of the span (e.g., function or operation name)
1640            input: Input data for the operation (can be any JSON-serializable object)
1641            output: Output data from the operation (can be any JSON-serializable object)
1642            metadata: Additional metadata to associate with the span
1643            version: Version identifier for the code or component
1644            level: Importance level of the span (info, warning, error)
1645            status_message: Optional status message for the span
1646
1647        Returns:
1648            The Langfuse Event object
1649
1650        Example:
1651            ```python
1652            event = langfuse.create_event(name="process-event")
1653            ```
1654        """
1655        timestamp = time_ns()
1656
1657        if trace_context:
1658            trace_id = trace_context.get("trace_id", None)
1659            parent_span_id = trace_context.get("parent_span_id", None)
1660
1661            if trace_id:
1662                remote_parent_span = self._create_remote_parent_span(
1663                    trace_id=trace_id, parent_span_id=parent_span_id
1664                )
1665
1666                with otel_trace_api.use_span(
1667                    cast(otel_trace_api.Span, remote_parent_span)
1668                ):
1669                    otel_span = self._otel_tracer.start_span(
1670                        name=name, start_time=timestamp
1671                    )
1672                    otel_span.set_attribute(LangfuseOtelSpanAttributes.AS_ROOT, True)
1673
1674                    return cast(
1675                        LangfuseEvent,
1676                        LangfuseEvent(
1677                            otel_span=otel_span,
1678                            langfuse_client=self,
1679                            environment=self._environment,
1680                            release=self._release,
1681                            input=input,
1682                            output=output,
1683                            metadata=metadata,
1684                            version=version,
1685                            level=level,
1686                            status_message=status_message,
1687                        ).end(end_time=timestamp),
1688                    )
1689
1690        otel_span = self._otel_tracer.start_span(name=name, start_time=timestamp)
1691
1692        return cast(
1693            LangfuseEvent,
1694            LangfuseEvent(
1695                otel_span=otel_span,
1696                langfuse_client=self,
1697                environment=self._environment,
1698                release=self._release,
1699                input=input,
1700                output=output,
1701                metadata=metadata,
1702                version=version,
1703                level=level,
1704                status_message=status_message,
1705            ).end(end_time=timestamp),
1706        )
1707
1708    def _create_remote_parent_span(
1709        self, *, trace_id: str, parent_span_id: Optional[str]
1710    ) -> Any:
1711        if not self._is_valid_trace_id(trace_id):
1712            langfuse_logger.warning(
1713                f"Passed trace ID '{trace_id}' is not a valid 32 lowercase hex char Langfuse trace id. Ignoring trace ID."
1714            )
1715
1716        if parent_span_id and not self._is_valid_span_id(parent_span_id):
1717            langfuse_logger.warning(
1718                f"Passed span ID '{parent_span_id}' is not a valid 16 lowercase hex char Langfuse span id. Ignoring parent span ID."
1719            )
1720
1721        int_trace_id = int(trace_id, 16)
1722        int_parent_span_id = (
1723            int(parent_span_id, 16)
1724            if parent_span_id
1725            else RandomIdGenerator().generate_span_id()
1726        )
1727
1728        span_context = otel_trace_api.SpanContext(
1729            trace_id=int_trace_id,
1730            span_id=int_parent_span_id,
1731            trace_flags=otel_trace_api.TraceFlags(0x01),  # mark span as sampled
1732            is_remote=False,
1733        )
1734
1735        return otel_trace_api.NonRecordingSpan(span_context)
1736
1737    def _is_valid_trace_id(self, trace_id: str) -> bool:
1738        pattern = r"^[0-9a-f]{32}$"
1739
1740        return bool(re.match(pattern, trace_id))
1741
1742    def _is_valid_span_id(self, span_id: str) -> bool:
1743        pattern = r"^[0-9a-f]{16}$"
1744
1745        return bool(re.match(pattern, span_id))
1746
1747    def _create_observation_id(self, *, seed: Optional[str] = None) -> str:
1748        """Create a unique observation ID for use with Langfuse.
1749
1750        This method generates a unique observation ID (span ID in OpenTelemetry terms)
1751        for use with various Langfuse APIs. It can either generate a random ID or
1752        create a deterministic ID based on a seed string.
1753
1754        Observation IDs must be 16 lowercase hexadecimal characters, representing 8 bytes.
1755        This method ensures the generated ID meets this requirement. If you need to
1756        correlate an external ID with a Langfuse observation ID, use the external ID as
1757        the seed to get a valid, deterministic observation ID.
1758
1759        Args:
1760            seed: Optional string to use as a seed for deterministic ID generation.
1761                 If provided, the same seed will always produce the same ID.
1762                 If not provided, a random ID will be generated.
1763
1764        Returns:
1765            A 16-character lowercase hexadecimal string representing the observation ID.
1766
1767        Example:
1768            ```python
1769            # Generate a random observation ID
1770            obs_id = langfuse.create_observation_id()
1771
1772            # Generate a deterministic ID based on a seed
1773            user_obs_id = langfuse.create_observation_id(seed="user-123-feedback")
1774
1775            # Correlate an external item ID with a Langfuse observation ID
1776            item_id = "item-789012"
1777            correlated_obs_id = langfuse.create_observation_id(seed=item_id)
1778
1779            # Use the ID with Langfuse APIs
1780            langfuse.create_score(
1781                name="relevance",
1782                value=0.95,
1783                trace_id=trace_id,
1784                observation_id=obs_id
1785            )
1786            ```
1787        """
1788        if not seed:
1789            span_id_int = RandomIdGenerator().generate_span_id()
1790
1791            return self._format_otel_span_id(span_id_int)
1792
1793        return sha256(seed.encode("utf-8")).digest()[:8].hex()
1794
1795    @staticmethod
1796    def create_trace_id(*, seed: Optional[str] = None) -> str:
1797        """Create a unique trace ID for use with Langfuse.
1798
1799        This method generates a unique trace ID for use with various Langfuse APIs.
1800        It can either generate a random ID or create a deterministic ID based on
1801        a seed string.
1802
1803        Trace IDs must be 32 lowercase hexadecimal characters, representing 16 bytes.
1804        This method ensures the generated ID meets this requirement. If you need to
1805        correlate an external ID with a Langfuse trace ID, use the external ID as the
1806        seed to get a valid, deterministic Langfuse trace ID.
1807
1808        Args:
1809            seed: Optional string to use as a seed for deterministic ID generation.
1810                 If provided, the same seed will always produce the same ID.
1811                 If not provided, a random ID will be generated.
1812
1813        Returns:
1814            A 32-character lowercase hexadecimal string representing the Langfuse trace ID.
1815
1816        Example:
1817            ```python
1818            # Generate a random trace ID
1819            trace_id = langfuse.create_trace_id()
1820
1821            # Generate a deterministic ID based on a seed
1822            session_trace_id = langfuse.create_trace_id(seed="session-456")
1823
1824            # Correlate an external ID with a Langfuse trace ID
1825            external_id = "external-system-123456"
1826            correlated_trace_id = langfuse.create_trace_id(seed=external_id)
1827
1828            # Use the ID with trace context
1829            with langfuse.start_as_current_observation(
1830                name="process-request",
1831                trace_context={"trace_id": trace_id}
1832            ) as span:
1833                # Operation will be part of the specific trace
1834                pass
1835            ```
1836        """
1837        if not seed:
1838            trace_id_int = RandomIdGenerator().generate_trace_id()
1839
1840            return Langfuse._format_otel_trace_id(trace_id_int)
1841
1842        return sha256(seed.encode("utf-8")).digest()[:16].hex()
1843
1844    def _get_otel_trace_id(self, otel_span: otel_trace_api.Span) -> str:
1845        span_context = otel_span.get_span_context()
1846
1847        return self._format_otel_trace_id(span_context.trace_id)
1848
1849    def _get_otel_span_id(self, otel_span: otel_trace_api.Span) -> str:
1850        span_context = otel_span.get_span_context()
1851
1852        return self._format_otel_span_id(span_context.span_id)
1853
1854    @staticmethod
1855    def _format_otel_span_id(span_id_int: int) -> str:
1856        """Format an integer span ID to a 16-character lowercase hex string.
1857
1858        Internal method to convert an OpenTelemetry integer span ID to the standard
1859        W3C Trace Context format (16-character lowercase hex string).
1860
1861        Args:
1862            span_id_int: 64-bit integer representing a span ID
1863
1864        Returns:
1865            A 16-character lowercase hexadecimal string
1866        """
1867        return format(span_id_int, "016x")
1868
1869    @staticmethod
1870    def _format_otel_trace_id(trace_id_int: int) -> str:
1871        """Format an integer trace ID to a 32-character lowercase hex string.
1872
1873        Internal method to convert an OpenTelemetry integer trace ID to the standard
1874        W3C Trace Context format (32-character lowercase hex string).
1875
1876        Args:
1877            trace_id_int: 128-bit integer representing a trace ID
1878
1879        Returns:
1880            A 32-character lowercase hexadecimal string
1881        """
1882        return format(trace_id_int, "032x")
1883
1884    @overload
1885    def create_score(
1886        self,
1887        *,
1888        name: str,
1889        value: float,
1890        session_id: Optional[str] = None,
1891        dataset_run_id: Optional[str] = None,
1892        trace_id: Optional[str] = None,
1893        observation_id: Optional[str] = None,
1894        score_id: Optional[str] = None,
1895        data_type: Optional[Literal["NUMERIC", "BOOLEAN"]] = None,
1896        comment: Optional[str] = None,
1897        config_id: Optional[str] = None,
1898        metadata: Optional[Any] = None,
1899        timestamp: Optional[datetime] = None,
1900        environment: Optional[str] = None,
1901    ) -> None: ...
1902
1903    @overload
1904    def create_score(
1905        self,
1906        *,
1907        name: str,
1908        value: str,
1909        session_id: Optional[str] = None,
1910        dataset_run_id: Optional[str] = None,
1911        trace_id: Optional[str] = None,
1912        score_id: Optional[str] = None,
1913        observation_id: Optional[str] = None,
1914        data_type: Optional[
1915            Literal["CATEGORICAL", "TEXT", "CORRECTION"]
1916        ] = "CATEGORICAL",
1917        comment: Optional[str] = None,
1918        config_id: Optional[str] = None,
1919        metadata: Optional[Any] = None,
1920        timestamp: Optional[datetime] = None,
1921        environment: Optional[str] = None,
1922    ) -> None: ...
1923
1924    def create_score(
1925        self,
1926        *,
1927        name: str,
1928        value: Union[float, str],
1929        session_id: Optional[str] = None,
1930        dataset_run_id: Optional[str] = None,
1931        trace_id: Optional[str] = None,
1932        observation_id: Optional[str] = None,
1933        score_id: Optional[str] = None,
1934        data_type: Optional[ScoreDataType] = None,
1935        comment: Optional[str] = None,
1936        config_id: Optional[str] = None,
1937        metadata: Optional[Any] = None,
1938        timestamp: Optional[datetime] = None,
1939        environment: Optional[str] = None,
1940    ) -> None:
1941        """Create a score for a specific trace or observation.
1942
1943        This method creates a score for evaluating a Langfuse trace or observation. Scores can be
1944        used to track quality metrics, user feedback, or automated evaluations.
1945
1946        Args:
1947            name: Name of the score (e.g., "relevance", "accuracy")
1948            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
1949            session_id: ID of the Langfuse session to associate the score with
1950            dataset_run_id: ID of the Langfuse dataset run to associate the score with
1951            trace_id: ID of the Langfuse trace to associate the score with
1952            observation_id: Optional ID of the specific observation to score. Trace ID must be provided too.
1953            score_id: Optional custom ID for the score (auto-generated if not provided)
1954            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
1955            comment: Optional comment or explanation for the score
1956            config_id: Optional ID of a score config defined in Langfuse
1957            metadata: Optional metadata to be attached to the score
1958            timestamp: Optional timestamp for the score (defaults to current UTC time)
1959            environment: Optional environment override for this score. If omitted,
1960                the score uses the client-level environment from
1961                `Langfuse(environment=...)` or `LANGFUSE_TRACING_ENVIRONMENT`.
1962                Langfuse observation wrapper methods pass their resolved span
1963                environment here so scores created via `span.score()` or
1964                `span.score_trace()` stay grouped with the scored observation or
1965                trace, including request-scoped environments propagated with
1966                `propagate_attributes(environment=...)`.
1967
1968        Example:
1969            ```python
1970            # Create a numeric score for accuracy
1971            langfuse.create_score(
1972                name="accuracy",
1973                value=0.92,
1974                trace_id="abcdef1234567890abcdef1234567890",
1975                data_type="NUMERIC",
1976                comment="High accuracy with minor irrelevant details"
1977            )
1978
1979            # Create a categorical score for sentiment
1980            langfuse.create_score(
1981                name="sentiment",
1982                value="positive",
1983                trace_id="abcdef1234567890abcdef1234567890",
1984                observation_id="abcdef1234567890",
1985                data_type="CATEGORICAL"
1986            )
1987            ```
1988        """
1989        if not self._tracing_enabled:
1990            return
1991
1992        score_id = score_id or self._create_observation_id()
1993
1994        try:
1995            new_body = ScoreBody(
1996                id=score_id,
1997                sessionId=session_id,
1998                datasetRunId=dataset_run_id,
1999                traceId=trace_id,
2000                observationId=observation_id,
2001                name=name,
2002                value=value,
2003                dataType=data_type,  # type: ignore
2004                comment=comment,
2005                configId=config_id,
2006                environment=environment or self._environment,
2007                metadata=metadata,
2008            )
2009
2010            event = {
2011                "id": self.create_trace_id(),
2012                "type": "score-create",
2013                "timestamp": timestamp or _get_timestamp(),
2014                "body": new_body,
2015            }
2016
2017            if self._resources is not None:
2018                # Force the score to be in sample if it was for a legacy trace ID, i.e. non-32 hexchar
2019                force_sample = (
2020                    not self._is_valid_trace_id(trace_id) if trace_id else True
2021                )
2022
2023                self._resources.add_score_task(
2024                    event,
2025                    force_sample=force_sample,
2026                )
2027
2028        except Exception as e:
2029            langfuse_logger.exception(
2030                f"Error creating score: Failed to process score event for trace_id={trace_id}, name={name}. Error: {e}"
2031            )
2032
2033    def _create_trace_tags_via_ingestion(
2034        self,
2035        *,
2036        trace_id: str,
2037        tags: List[str],
2038    ) -> None:
2039        """Private helper to enqueue trace tag updates via ingestion API events."""
2040        if not self._tracing_enabled:
2041            return
2042
2043        if len(tags) == 0:
2044            return
2045
2046        try:
2047            new_body = TraceBody(
2048                id=trace_id,
2049                tags=tags,
2050            )
2051
2052            event = {
2053                "id": self.create_trace_id(),
2054                "type": "trace-create",
2055                "timestamp": _get_timestamp(),
2056                "body": new_body,
2057            }
2058
2059            if self._resources is not None:
2060                self._resources.add_trace_task(event)
2061        except Exception as e:
2062            langfuse_logger.exception(
2063                f"Error updating trace tags: Failed to process trace update event for trace_id={trace_id}. Error: {e}"
2064            )
2065
2066    @overload
2067    def score_current_span(
2068        self,
2069        *,
2070        name: str,
2071        value: float,
2072        score_id: Optional[str] = None,
2073        data_type: Optional[Literal["NUMERIC", "BOOLEAN"]] = None,
2074        comment: Optional[str] = None,
2075        config_id: Optional[str] = None,
2076        metadata: Optional[Any] = None,
2077    ) -> None: ...
2078
2079    @overload
2080    def score_current_span(
2081        self,
2082        *,
2083        name: str,
2084        value: str,
2085        score_id: Optional[str] = None,
2086        data_type: Optional[
2087            Literal["CATEGORICAL", "TEXT", "CORRECTION"]
2088        ] = "CATEGORICAL",
2089        comment: Optional[str] = None,
2090        config_id: Optional[str] = None,
2091        metadata: Optional[Any] = None,
2092    ) -> None: ...
2093
2094    def score_current_span(
2095        self,
2096        *,
2097        name: str,
2098        value: Union[float, str],
2099        score_id: Optional[str] = None,
2100        data_type: Optional[ScoreDataType] = None,
2101        comment: Optional[str] = None,
2102        config_id: Optional[str] = None,
2103        metadata: Optional[Any] = None,
2104    ) -> None:
2105        """Create a score for the current active span.
2106
2107        This method scores the currently active span in the context. It's a convenient
2108        way to score the current operation without needing to know its trace and span IDs.
2109        If the active span has a `langfuse.environment` attribute, including one
2110        set by `propagate_attributes(environment=...)`, the score uses that
2111        environment. Otherwise it uses the client-level environment.
2112
2113        Args:
2114            name: Name of the score (e.g., "relevance", "accuracy")
2115            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
2116            score_id: Optional custom ID for the score (auto-generated if not provided)
2117            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
2118            comment: Optional comment or explanation for the score
2119            config_id: Optional ID of a score config defined in Langfuse
2120            metadata: Optional metadata to be attached to the score
2121
2122        Example:
2123            ```python
2124            with langfuse.start_as_current_generation(name="answer-query") as generation:
2125                # Generate answer
2126                response = generate_answer(...)
2127                generation.update(output=response)
2128
2129                # Score the generation
2130                langfuse.score_current_span(
2131                    name="relevance",
2132                    value=0.85,
2133                    data_type="NUMERIC",
2134                    comment="Mostly relevant but contains some tangential information",
2135                    metadata={"model": "gpt-4", "prompt_version": "v2"}
2136                )
2137            ```
2138        """
2139        current_span = self._get_current_otel_span()
2140
2141        if current_span is not None:
2142            trace_id = self._get_otel_trace_id(current_span)
2143            observation_id = self._get_otel_span_id(current_span)
2144
2145            langfuse_logger.info(
2146                f"Score: Creating score name='{name}' value={value} for current span ({observation_id}) in trace {trace_id}"
2147            )
2148
2149            self.create_score(
2150                trace_id=trace_id,
2151                observation_id=observation_id,
2152                name=name,
2153                value=cast(str, value),
2154                score_id=score_id,
2155                data_type=cast(Literal["CATEGORICAL", "TEXT", "CORRECTION"], data_type),
2156                comment=comment,
2157                config_id=config_id,
2158                metadata=metadata,
2159                environment=get_string_span_attribute(
2160                    current_span, LangfuseOtelSpanAttributes.ENVIRONMENT
2161                ),
2162            )
2163
2164    @overload
2165    def score_current_trace(
2166        self,
2167        *,
2168        name: str,
2169        value: float,
2170        score_id: Optional[str] = None,
2171        data_type: Optional[Literal["NUMERIC", "BOOLEAN"]] = None,
2172        comment: Optional[str] = None,
2173        config_id: Optional[str] = None,
2174        metadata: Optional[Any] = None,
2175    ) -> None: ...
2176
2177    @overload
2178    def score_current_trace(
2179        self,
2180        *,
2181        name: str,
2182        value: str,
2183        score_id: Optional[str] = None,
2184        data_type: Optional[
2185            Literal["CATEGORICAL", "TEXT", "CORRECTION"]
2186        ] = "CATEGORICAL",
2187        comment: Optional[str] = None,
2188        config_id: Optional[str] = None,
2189        metadata: Optional[Any] = None,
2190    ) -> None: ...
2191
2192    def score_current_trace(
2193        self,
2194        *,
2195        name: str,
2196        value: Union[float, str],
2197        score_id: Optional[str] = None,
2198        data_type: Optional[ScoreDataType] = None,
2199        comment: Optional[str] = None,
2200        config_id: Optional[str] = None,
2201        metadata: Optional[Any] = None,
2202    ) -> None:
2203        """Create a score for the current trace.
2204
2205        This method scores the trace of the currently active span. Unlike score_current_span,
2206        this method associates the score with the entire trace rather than a specific span.
2207        It's useful for scoring overall performance or quality of the entire operation.
2208        If the active span has a `langfuse.environment` attribute, including one
2209        set by `propagate_attributes(environment=...)`, the score uses that
2210        environment. Otherwise it uses the client-level environment.
2211
2212        Args:
2213            name: Name of the score (e.g., "user_satisfaction", "overall_quality")
2214            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
2215            score_id: Optional custom ID for the score (auto-generated if not provided)
2216            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
2217            comment: Optional comment or explanation for the score
2218            config_id: Optional ID of a score config defined in Langfuse
2219            metadata: Optional metadata to be attached to the score
2220
2221        Example:
2222            ```python
2223            with langfuse.start_as_current_observation(name="process-user-request") as span:
2224                # Process request
2225                result = process_complete_request()
2226                span.update(output=result)
2227
2228                # Score the overall trace
2229                langfuse.score_current_trace(
2230                    name="overall_quality",
2231                    value=0.95,
2232                    data_type="NUMERIC",
2233                    comment="High quality end-to-end response",
2234                    metadata={"evaluator": "gpt-4", "criteria": "comprehensive"}
2235                )
2236            ```
2237        """
2238        current_span = self._get_current_otel_span()
2239
2240        if current_span is not None:
2241            trace_id = self._get_otel_trace_id(current_span)
2242
2243            langfuse_logger.info(
2244                f"Score: Creating score name='{name}' value={value} for entire trace {trace_id}"
2245            )
2246
2247            self.create_score(
2248                trace_id=trace_id,
2249                name=name,
2250                value=cast(str, value),
2251                score_id=score_id,
2252                data_type=cast(Literal["CATEGORICAL", "TEXT", "CORRECTION"], data_type),
2253                comment=comment,
2254                config_id=config_id,
2255                metadata=metadata,
2256                environment=get_string_span_attribute(
2257                    current_span, LangfuseOtelSpanAttributes.ENVIRONMENT
2258                ),
2259            )
2260
2261    def flush(self) -> None:
2262        """Force flush all pending spans and events to the Langfuse API.
2263
2264        This method manually flushes any pending spans, scores, and other events to the
2265        Langfuse API. It's useful in scenarios where you want to ensure all data is sent
2266        before proceeding, without waiting for the automatic flush interval.
2267
2268        Example:
2269            ```python
2270            # Record some spans and scores
2271            with langfuse.start_as_current_observation(name="operation") as span:
2272                # Do work...
2273                pass
2274
2275            # Ensure all data is sent to Langfuse before proceeding
2276            langfuse.flush()
2277
2278            # Continue with other work
2279            ```
2280
2281        Note:
2282            `flush()` guarantees data was *delivered* to the API, not that it is
2283            *readable* yet: server-side ingestion is asynchronous, so flushed data
2284            may not be queryable for 15-30 seconds —
2285            `api.observations.get_many(trace_id=...)` may return empty results and
2286            `api.trace.get()` may raise `langfuse.api.NotFoundError` right after a
2287            successful flush. See the `api` property docs for a bounded retry
2288            pattern, or
2289            https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk#ingestion-lag
2290        """
2291        if self._resources is not None:
2292            self._resources.flush()
2293
2294    def shutdown(self) -> None:
2295        """Shut down the Langfuse client and flush all pending data.
2296
2297        This method cleanly shuts down the Langfuse client, ensuring all pending data
2298        is flushed to the API and all background threads are properly terminated.
2299
2300        It's important to call this method when your application is shutting down to
2301        prevent data loss and resource leaks. For most applications, using the client
2302        as a context manager or relying on the automatic shutdown via atexit is sufficient.
2303
2304        Example:
2305            ```python
2306            # Initialize Langfuse
2307            langfuse = Langfuse(public_key="...", secret_key="...")
2308
2309            # Use Langfuse throughout your application
2310            # ...
2311
2312            # When application is shutting down
2313            langfuse.shutdown()
2314            ```
2315        """
2316        if self._resources is not None:
2317            self._resources.shutdown()
2318
2319    def get_current_trace_id(self) -> Optional[str]:
2320        """Get the trace ID of the current active span.
2321
2322        This method retrieves the trace ID from the currently active span in the context.
2323        It can be used to get the trace ID for referencing in logs, external systems,
2324        or for creating related operations.
2325
2326        Returns:
2327            The current trace ID as a 32-character lowercase hexadecimal string,
2328            or None if there is no active span.
2329
2330        Example:
2331            ```python
2332            with langfuse.start_as_current_observation(name="process-request") as span:
2333                # Get the current trace ID for reference
2334                trace_id = langfuse.get_current_trace_id()
2335
2336                # Use it for external correlation
2337                log.info(f"Processing request with trace_id: {trace_id}")
2338
2339                # Or pass to another system
2340                external_system.process(data, trace_id=trace_id)
2341            ```
2342        """
2343        if not self._tracing_enabled:
2344            langfuse_logger.debug(
2345                "Operation skipped: get_current_trace_id - Tracing is disabled or client is in no-op mode."
2346            )
2347            return None
2348
2349        current_otel_span = self._get_current_otel_span()
2350
2351        return self._get_otel_trace_id(current_otel_span) if current_otel_span else None
2352
2353    def get_current_observation_id(self) -> Optional[str]:
2354        """Get the observation ID (span ID) of the current active span.
2355
2356        This method retrieves the observation ID from the currently active span in the context.
2357        It can be used to get the observation ID for referencing in logs, external systems,
2358        or for creating scores or other related operations.
2359
2360        Returns:
2361            The current observation ID as a 16-character lowercase hexadecimal string,
2362            or None if there is no active span.
2363
2364        Example:
2365            ```python
2366            with langfuse.start_as_current_observation(name="process-user-query") as span:
2367                # Get the current observation ID
2368                observation_id = langfuse.get_current_observation_id()
2369
2370                # Store it for later reference
2371                cache.set(f"query_{query_id}_observation", observation_id)
2372
2373                # Process the query...
2374            ```
2375        """
2376        if not self._tracing_enabled:
2377            langfuse_logger.debug(
2378                "Operation skipped: get_current_observation_id - Tracing is disabled or client is in no-op mode."
2379            )
2380            return None
2381
2382        current_otel_span = self._get_current_otel_span()
2383
2384        return self._get_otel_span_id(current_otel_span) if current_otel_span else None
2385
2386    def _get_project_id(self) -> Optional[str]:
2387        """Fetch and return the current project id. Persisted across requests. Returns None if no project id is found for api keys."""
2388        if not self._project_id:
2389            proj = self.api.projects.get()
2390            if not proj.data or not proj.data[0].id:
2391                return None
2392
2393            self._project_id = proj.data[0].id
2394
2395        return self._project_id
2396
2397    def get_trace_url(self, *, trace_id: Optional[str] = None) -> Optional[str]:
2398        """Get the URL to view a trace in the Langfuse UI.
2399
2400        This method generates a URL that links directly to a trace in the Langfuse UI.
2401        It's useful for providing links in logs, notifications, or debugging tools.
2402
2403        Args:
2404            trace_id: Optional trace ID to generate a URL for. If not provided,
2405                     the trace ID of the current active span will be used.
2406
2407        Returns:
2408            A URL string pointing to the trace in the Langfuse UI,
2409            or None if the project ID couldn't be retrieved or no trace ID is available.
2410
2411        Example:
2412            ```python
2413            # Get URL for the current trace
2414            with langfuse.start_as_current_observation(name="process-request") as span:
2415                trace_url = langfuse.get_trace_url()
2416                log.info(f"Processing trace: {trace_url}")
2417
2418            # Get URL for a specific trace
2419            specific_trace_url = langfuse.get_trace_url(trace_id="1234567890abcdef1234567890abcdef")
2420            send_notification(f"Review needed for trace: {specific_trace_url}")
2421            ```
2422        """
2423        final_trace_id = trace_id or self.get_current_trace_id()
2424        if not final_trace_id:
2425            return None
2426
2427        project_id = self._get_project_id()
2428
2429        return (
2430            f"{self._base_url}/project/{project_id}/traces/{final_trace_id}"
2431            if project_id and final_trace_id
2432            else None
2433        )
2434
2435    def get_dataset(
2436        self,
2437        name: str,
2438        *,
2439        fetch_items_page_size: Optional[int] = 50,
2440        version: Optional[datetime] = None,
2441    ) -> "DatasetClient":
2442        """Fetch a dataset by its name.
2443
2444        Args:
2445            name: The name of the dataset to fetch.
2446            fetch_items_page_size: All items of the dataset will be fetched in chunks of this size. Defaults to 50.
2447            version: Retrieve dataset items as they existed at this specific point in time (UTC).
2448                If provided, returns the state of items at the specified UTC timestamp.
2449                If not provided, returns the latest version. Must be a timezone-aware datetime object in UTC.
2450
2451        Returns:
2452            DatasetClient: The dataset with the given name.
2453        """
2454        try:
2455            langfuse_logger.debug(f"Getting datasets {name}")
2456            dataset = self.api.datasets.get(dataset_name=self._url_encode(name))
2457
2458            dataset_items: List[DatasetItem] = []
2459            page = 1
2460
2461            while True:
2462                new_items = self.api.dataset_items.list(
2463                    dataset_name=self._url_encode(name, is_url_param=True),
2464                    page=page,
2465                    limit=fetch_items_page_size,
2466                    version=version,
2467                )
2468                dataset_items.extend(
2469                    self._hydrate_dataset_item_media_references(item)
2470                    for item in new_items.data
2471                )
2472
2473                if new_items.meta.total_pages <= page:
2474                    break
2475
2476                page += 1
2477
2478            return DatasetClient(
2479                dataset=dataset,
2480                items=dataset_items,
2481                version=version,
2482                langfuse_client=self,
2483            )
2484
2485        except Error as e:
2486            handle_fern_exception(e)
2487            raise e
2488
2489    def get_dataset_run(
2490        self, *, dataset_name: str, run_name: str
2491    ) -> DatasetRunWithItems:
2492        """Fetch a dataset run by dataset name and run name.
2493
2494        Args:
2495            dataset_name (str): The name of the dataset.
2496            run_name (str): The name of the run.
2497
2498        Returns:
2499            DatasetRunWithItems: The dataset run with its items.
2500        """
2501        try:
2502            return cast(
2503                DatasetRunWithItems,
2504                self.api.datasets.get_run(
2505                    dataset_name=self._url_encode(dataset_name),
2506                    run_name=self._url_encode(run_name),
2507                    request_options=None,
2508                ),
2509            )
2510        except Error as e:
2511            handle_fern_exception(e)
2512            raise e
2513
2514    def get_dataset_runs(
2515        self,
2516        *,
2517        dataset_name: str,
2518        page: Optional[int] = None,
2519        limit: Optional[int] = None,
2520    ) -> PaginatedDatasetRuns:
2521        """Fetch all runs for a dataset.
2522
2523        Args:
2524            dataset_name (str): The name of the dataset.
2525            page (Optional[int]): Page number, starts at 1.
2526            limit (Optional[int]): Limit of items per page.
2527
2528        Returns:
2529            PaginatedDatasetRuns: Paginated list of dataset runs.
2530        """
2531        try:
2532            return cast(
2533                PaginatedDatasetRuns,
2534                self.api.datasets.get_runs(
2535                    dataset_name=self._url_encode(dataset_name),
2536                    page=page,
2537                    limit=limit,
2538                    request_options=None,
2539                ),
2540            )
2541        except Error as e:
2542            handle_fern_exception(e)
2543            raise e
2544
2545    def delete_dataset_run(
2546        self, *, dataset_name: str, run_name: str
2547    ) -> DeleteDatasetRunResponse:
2548        """Delete a dataset run and all its run items. This action is irreversible.
2549
2550        Args:
2551            dataset_name (str): The name of the dataset.
2552            run_name (str): The name of the run.
2553
2554        Returns:
2555            DeleteDatasetRunResponse: Confirmation of deletion.
2556        """
2557        try:
2558            return cast(
2559                DeleteDatasetRunResponse,
2560                self.api.datasets.delete_run(
2561                    dataset_name=self._url_encode(dataset_name),
2562                    run_name=self._url_encode(run_name),
2563                    request_options=None,
2564                ),
2565            )
2566        except Error as e:
2567            handle_fern_exception(e)
2568            raise e
2569
2570    def run_experiment(
2571        self,
2572        *,
2573        name: str,
2574        run_name: Optional[str] = None,
2575        description: Optional[str] = None,
2576        data: ExperimentData,
2577        task: TaskFunction,
2578        evaluators: List[EvaluatorFunction] = [],
2579        composite_evaluator: Optional[CompositeEvaluatorFunction] = None,
2580        run_evaluators: List[RunEvaluatorFunction] = [],
2581        max_concurrency: int = 50,
2582        metadata: Optional[Dict[str, str]] = None,
2583        _dataset_version: Optional[datetime] = None,
2584    ) -> ExperimentResult:
2585        """Run an experiment on a dataset with automatic tracing and evaluation.
2586
2587        This method executes a task function on each item in the provided dataset,
2588        automatically traces all executions with Langfuse for observability, runs
2589        item-level and run-level evaluators on the outputs, and returns comprehensive
2590        results with evaluation metrics.
2591
2592        The experiment system provides:
2593        - Automatic tracing of all task executions
2594        - Concurrent processing with configurable limits
2595        - Comprehensive error handling that isolates failures
2596        - Integration with Langfuse datasets for experiment tracking
2597        - Flexible evaluation framework supporting both sync and async evaluators
2598
2599        Args:
2600            name: Human-readable name for the experiment. Used for identification
2601                in the Langfuse UI.
2602            run_name: Optional exact name for the experiment run. If provided, this will be
2603                used as the exact dataset run name if the `data` contains Langfuse dataset items.
2604                If not provided, this will default to the experiment name appended with an ISO timestamp.
2605            description: Optional description explaining the experiment's purpose,
2606                methodology, or expected outcomes.
2607            data: Array of data items to process. Can be either:
2608                - List of dict-like items with 'input', 'expected_output', 'metadata' keys
2609                - List of Langfuse DatasetItem objects from dataset.items
2610            task: Function that processes each data item and returns output.
2611                Must accept 'item' as keyword argument and can return sync or async results.
2612                The task function signature should be: task(*, item, **kwargs) -> Any
2613            evaluators: List of functions to evaluate each item's output individually.
2614                Each evaluator receives input, output, expected_output, and metadata.
2615                Can return single Evaluation dict or list of Evaluation dicts.
2616            composite_evaluator: Optional function that creates composite scores from item-level evaluations.
2617                Receives the same inputs as item-level evaluators (input, output, expected_output, metadata)
2618                plus the list of evaluations from item-level evaluators. Useful for weighted averages,
2619                pass/fail decisions based on multiple criteria, or custom scoring logic combining multiple metrics.
2620            run_evaluators: List of functions to evaluate the entire experiment run.
2621                Each run evaluator receives all item_results and can compute aggregate metrics.
2622                Useful for calculating averages, distributions, or cross-item comparisons.
2623            max_concurrency: Maximum number of concurrent task executions (default: 50).
2624                Controls the number of items processed simultaneously. Adjust based on
2625                API rate limits and system resources.
2626            metadata: Optional metadata dictionary to attach to all experiment traces.
2627                This metadata will be included in every trace created during the experiment.
2628                If `data` are Langfuse dataset items, the metadata will be attached to the dataset run, too.
2629
2630        Returns:
2631            ExperimentResult containing:
2632            - run_name: The experiment run name. This is equal to the dataset run name if experiment was on Langfuse dataset.
2633            - item_results: List of results for each processed item with outputs and evaluations
2634            - run_evaluations: List of aggregate evaluation results for the entire run
2635            - experiment_id: Stable identifier for the experiment run across all items
2636            - dataset_run_id: ID of the dataset run (if using Langfuse datasets)
2637            - dataset_run_url: Direct URL to view results in Langfuse UI (if applicable)
2638
2639        Raises:
2640            ValueError: If required parameters are missing or invalid
2641            Exception: If experiment setup fails (individual item failures are handled gracefully)
2642
2643        Examples:
2644            Basic experiment with local data:
2645            ```python
2646            def summarize_text(*, item, **kwargs):
2647                return f"Summary: {item['input'][:50]}..."
2648
2649            def length_evaluator(*, input, output, expected_output=None, **kwargs):
2650                return {
2651                    "name": "output_length",
2652                    "value": len(output),
2653                    "comment": f"Output contains {len(output)} characters"
2654                }
2655
2656            result = langfuse.run_experiment(
2657                name="Text Summarization Test",
2658                description="Evaluate summarization quality and length",
2659                data=[
2660                    {"input": "Long article text...", "expected_output": "Expected summary"},
2661                    {"input": "Another article...", "expected_output": "Another summary"}
2662                ],
2663                task=summarize_text,
2664                evaluators=[length_evaluator]
2665            )
2666
2667            print(f"Processed {len(result.item_results)} items")
2668            for item_result in result.item_results:
2669                print(f"Input: {item_result.item['input']}")
2670                print(f"Output: {item_result.output}")
2671                print(f"Evaluations: {item_result.evaluations}")
2672            ```
2673
2674            Advanced experiment with async task and multiple evaluators:
2675            ```python
2676            async def llm_task(*, item, **kwargs):
2677                # Simulate async LLM call
2678                response = await openai_client.chat.completions.create(
2679                    model="gpt-4",
2680                    messages=[{"role": "user", "content": item["input"]}]
2681                )
2682                return response.choices[0].message.content
2683
2684            def accuracy_evaluator(*, input, output, expected_output=None, **kwargs):
2685                if expected_output and expected_output.lower() in output.lower():
2686                    return {"name": "accuracy", "value": 1.0, "comment": "Correct answer"}
2687                return {"name": "accuracy", "value": 0.0, "comment": "Incorrect answer"}
2688
2689            def toxicity_evaluator(*, input, output, expected_output=None, **kwargs):
2690                # Simulate toxicity check
2691                toxicity_score = check_toxicity(output)  # Your toxicity checker
2692                return {
2693                    "name": "toxicity",
2694                    "value": toxicity_score,
2695                    "comment": f"Toxicity level: {'high' if toxicity_score > 0.7 else 'low'}"
2696                }
2697
2698            def average_accuracy(*, item_results, **kwargs):
2699                accuracies = [
2700                    eval.value for result in item_results
2701                    for eval in result.evaluations
2702                    if eval.name == "accuracy"
2703                ]
2704                return {
2705                    "name": "average_accuracy",
2706                    "value": sum(accuracies) / len(accuracies) if accuracies else 0,
2707                    "comment": f"Average accuracy across {len(accuracies)} items"
2708                }
2709
2710            result = langfuse.run_experiment(
2711                name="LLM Safety and Accuracy Test",
2712                description="Evaluate model accuracy and safety across diverse prompts",
2713                data=test_dataset,  # Your dataset items
2714                task=llm_task,
2715                evaluators=[accuracy_evaluator, toxicity_evaluator],
2716                run_evaluators=[average_accuracy],
2717                max_concurrency=5,  # Limit concurrent API calls
2718                metadata={"model": "gpt-4", "temperature": 0.7}
2719            )
2720            ```
2721
2722            Using with Langfuse datasets:
2723            ```python
2724            # Get dataset from Langfuse
2725            dataset = langfuse.get_dataset("my-eval-dataset")
2726
2727            result = dataset.run_experiment(
2728                name="Production Model Evaluation",
2729                description="Monthly evaluation of production model performance",
2730                task=my_production_task,
2731                evaluators=[accuracy_evaluator, latency_evaluator]
2732            )
2733
2734            # Results automatically linked to dataset in Langfuse UI
2735            print(f"View results: {result['dataset_run_url']}")
2736            ```
2737
2738        Note:
2739            - Task and evaluator functions can be either synchronous or asynchronous
2740            - Individual item failures are logged but don't stop the experiment
2741            - All executions are automatically traced and visible in Langfuse UI
2742            - When using Langfuse datasets, results are automatically linked for easy comparison
2743            - This method works in both sync and async contexts (Jupyter notebooks, web apps, etc.)
2744            - Async execution is handled automatically with smart event loop detection
2745        """
2746        return cast(
2747            ExperimentResult,
2748            run_async_safely(
2749                self._run_experiment_async(
2750                    name=name,
2751                    run_name=self._create_experiment_run_name(
2752                        name=name, run_name=run_name
2753                    ),
2754                    description=description,
2755                    data=data,
2756                    task=task,
2757                    evaluators=evaluators or [],
2758                    composite_evaluator=composite_evaluator,
2759                    run_evaluators=run_evaluators or [],
2760                    max_concurrency=max_concurrency,
2761                    metadata=metadata,
2762                    dataset_version=_dataset_version,
2763                ),
2764            ),
2765        )
2766
2767    async def _run_experiment_async(
2768        self,
2769        *,
2770        name: str,
2771        run_name: str,
2772        description: Optional[str],
2773        data: ExperimentData,
2774        task: TaskFunction,
2775        evaluators: List[EvaluatorFunction],
2776        composite_evaluator: Optional[CompositeEvaluatorFunction],
2777        run_evaluators: List[RunEvaluatorFunction],
2778        max_concurrency: int,
2779        metadata: Optional[Dict[str, Any]] = None,
2780        dataset_version: Optional[datetime] = None,
2781    ) -> ExperimentResult:
2782        langfuse_logger.debug(
2783            f"Starting experiment '{name}' run '{run_name}' with {len(data)} items"
2784        )
2785
2786        shared_fallback_experiment_id = self._create_observation_id()
2787
2788        # Set up concurrency control
2789        semaphore = asyncio.Semaphore(max_concurrency)
2790
2791        # Process all items
2792        async def process_item(item: ExperimentItem) -> ExperimentItemResult:
2793            async with semaphore:
2794                return await self._process_experiment_item(
2795                    item,
2796                    task,
2797                    evaluators,
2798                    composite_evaluator,
2799                    shared_fallback_experiment_id,
2800                    name,
2801                    run_name,
2802                    description,
2803                    metadata,
2804                    dataset_version,
2805                )
2806
2807        # Run all items concurrently
2808        tasks = [process_item(item) for item in data]
2809        item_results = await asyncio.gather(*tasks, return_exceptions=True)
2810
2811        # Filter out any exceptions and log errors
2812        valid_results: List[ExperimentItemResult] = []
2813        for i, result in enumerate(item_results):
2814            if isinstance(result, Exception):
2815                langfuse_logger.error(f"Item {i} failed: {result}")
2816            elif isinstance(result, ExperimentItemResult):
2817                valid_results.append(result)  # type: ignore
2818
2819        # Run experiment-level evaluators
2820        run_evaluations: List[Evaluation] = []
2821        for run_evaluator in run_evaluators:
2822            try:
2823                evaluations = await _run_evaluator(
2824                    run_evaluator, item_results=valid_results
2825                )
2826                run_evaluations.extend(evaluations)
2827            except Exception as e:
2828                langfuse_logger.error(f"Run evaluator failed: {e}")
2829
2830        # Generate dataset run URL if applicable
2831        dataset_run_id = next(
2832            (
2833                result.dataset_run_id
2834                for result in valid_results
2835                if result.dataset_run_id
2836            ),
2837            None,
2838        )
2839        dataset_run_url = None
2840        if dataset_run_id and data:
2841            try:
2842                # Check if the first item has dataset_id (for DatasetItem objects)
2843                first_item = data[0]
2844                dataset_id = None
2845
2846                if hasattr(first_item, "dataset_id"):
2847                    dataset_id = getattr(first_item, "dataset_id", None)
2848
2849                if dataset_id:
2850                    project_id = self._get_project_id()
2851
2852                    if project_id:
2853                        dataset_run_url = f"{self._base_url}/project/{project_id}/datasets/{dataset_id}/runs/{dataset_run_id}"
2854
2855            except Exception:
2856                pass  # URL generation is optional
2857
2858        # Store run-level evaluations as scores
2859        for evaluation in run_evaluations:
2860            try:
2861                if dataset_run_id:
2862                    self.create_score(
2863                        dataset_run_id=dataset_run_id,
2864                        name=evaluation.name or "<unknown>",
2865                        value=evaluation.value,  # type: ignore
2866                        comment=evaluation.comment,
2867                        metadata=evaluation.metadata,
2868                        data_type=evaluation.data_type,  # type: ignore
2869                        config_id=evaluation.config_id,
2870                    )
2871
2872            except Exception as e:
2873                langfuse_logger.error(f"Failed to store run evaluation: {e}")
2874
2875        # Flush scores and traces
2876        self.flush()
2877
2878        return ExperimentResult(
2879            name=name,
2880            run_name=run_name,
2881            description=description,
2882            item_results=valid_results,
2883            run_evaluations=run_evaluations,
2884            experiment_id=dataset_run_id or shared_fallback_experiment_id,
2885            dataset_run_id=dataset_run_id,
2886            dataset_run_url=dataset_run_url,
2887        )
2888
2889    async def _process_experiment_item(
2890        self,
2891        item: ExperimentItem,
2892        task: Callable,
2893        evaluators: List[Callable],
2894        composite_evaluator: Optional[CompositeEvaluatorFunction],
2895        fallback_experiment_id: str,
2896        experiment_name: str,
2897        experiment_run_name: str,
2898        experiment_description: Optional[str],
2899        experiment_metadata: Optional[Dict[str, Any]] = None,
2900        dataset_version: Optional[datetime] = None,
2901    ) -> ExperimentItemResult:
2902        span_name = "experiment-item-run"
2903
2904        with self.start_as_current_observation(name=span_name) as span:
2905            try:
2906                input_data = (
2907                    item.get("input")
2908                    if isinstance(item, dict)
2909                    else getattr(item, "input", None)
2910                )
2911
2912                if input_data is None:
2913                    raise ValueError("Experiment Item is missing input. Skipping item.")
2914
2915                expected_output = (
2916                    item.get("expected_output")
2917                    if isinstance(item, dict)
2918                    else getattr(item, "expected_output", None)
2919                )
2920
2921                item_metadata = (
2922                    item.get("metadata")
2923                    if isinstance(item, dict)
2924                    else getattr(item, "metadata", None)
2925                )
2926
2927                final_observation_metadata = {
2928                    "experiment_name": experiment_name,
2929                    "experiment_run_name": experiment_run_name,
2930                    **(experiment_metadata or {}),
2931                }
2932
2933                trace_id = span.trace_id
2934                dataset_id = None
2935                dataset_item_id = None
2936                dataset_run_id = None
2937
2938                # Link to dataset run if this is a dataset item
2939                if hasattr(item, "id") and hasattr(item, "dataset_id"):
2940                    try:
2941                        # Use sync API to avoid event loop issues when run_async_safely
2942                        # creates multiple event loops across different threads
2943                        dataset_run_item = await asyncio.to_thread(
2944                            self.api.dataset_run_items.create,
2945                            run_name=experiment_run_name,
2946                            run_description=experiment_description,
2947                            metadata=experiment_metadata,
2948                            dataset_item_id=item.id,  # type: ignore
2949                            trace_id=trace_id,
2950                            observation_id=span.id,
2951                            dataset_version=dataset_version,
2952                        )
2953
2954                        dataset_run_id = dataset_run_item.dataset_run_id
2955
2956                    except Exception as e:
2957                        langfuse_logger.error(f"Failed to create dataset run item: {e}")
2958
2959                if (
2960                    not isinstance(item, dict)
2961                    and hasattr(item, "dataset_id")
2962                    and hasattr(item, "id")
2963                ):
2964                    dataset_id = item.dataset_id
2965                    dataset_item_id = item.id
2966
2967                    final_observation_metadata.update(
2968                        {"dataset_id": dataset_id, "dataset_item_id": dataset_item_id}
2969                    )
2970
2971                if isinstance(item_metadata, dict):
2972                    final_observation_metadata.update(item_metadata)
2973
2974                experiment_id = dataset_run_id or fallback_experiment_id
2975                experiment_item_id = (
2976                    dataset_item_id or get_sha256_hash_hex(_serialize(input_data))[:16]
2977                )
2978                span._otel_span.set_attributes(
2979                    {
2980                        k: v
2981                        for k, v in {
2982                            LangfuseOtelSpanAttributes.ENVIRONMENT: LANGFUSE_SDK_EXPERIMENT_ENVIRONMENT,
2983                            LangfuseOtelSpanAttributes.EXPERIMENT_DESCRIPTION: experiment_description,
2984                            LangfuseOtelSpanAttributes.EXPERIMENT_ITEM_EXPECTED_OUTPUT: _serialize(
2985                                expected_output
2986                            ),
2987                        }.items()
2988                        if v is not None
2989                    }
2990                )
2991
2992                propagated_experiment_attributes = PropagatedExperimentAttributes(
2993                    experiment_id=experiment_id,
2994                    experiment_name=experiment_run_name,
2995                    experiment_metadata=_flatten_and_serialize_metadata_values(
2996                        experiment_metadata
2997                    ),
2998                    experiment_dataset_id=dataset_id,
2999                    experiment_item_id=experiment_item_id,
3000                    experiment_item_metadata=_flatten_and_serialize_metadata_values(
3001                        item_metadata if isinstance(item_metadata, dict) else None
3002                    ),
3003                    experiment_item_root_observation_id=span.id,
3004                )
3005
3006                with _propagate_attributes(experiment=propagated_experiment_attributes):
3007                    output = await _run_task(task, item)
3008
3009                span.update(
3010                    input=input_data,
3011                    output=output,
3012                    metadata=final_observation_metadata,
3013                )
3014
3015            except Exception as e:
3016                span.update(
3017                    output=f"Error: {str(e)}", level="ERROR", status_message=str(e)
3018                )
3019                raise e
3020
3021            # Run evaluators
3022            evaluations = []
3023
3024            for evaluator in evaluators:
3025                try:
3026                    eval_metadata: Optional[Dict[str, Any]] = None
3027
3028                    if isinstance(item, dict):
3029                        eval_metadata = item.get("metadata")
3030                    elif hasattr(item, "metadata"):
3031                        eval_metadata = item.metadata
3032
3033                    with _propagate_attributes(
3034                        experiment=propagated_experiment_attributes
3035                    ):
3036                        eval_results = await _run_evaluator(
3037                            evaluator,
3038                            input=input_data,
3039                            output=output,
3040                            expected_output=expected_output,
3041                            metadata=eval_metadata,
3042                        )
3043                        evaluations.extend(eval_results)
3044
3045                        # Store evaluations as scores
3046                        for evaluation in eval_results:
3047                            self.create_score(
3048                                trace_id=trace_id,
3049                                observation_id=span.id,
3050                                name=evaluation.name,
3051                                value=evaluation.value,  # type: ignore
3052                                comment=evaluation.comment,
3053                                metadata=evaluation.metadata,
3054                                config_id=evaluation.config_id,
3055                                data_type=evaluation.data_type,  # type: ignore
3056                            )
3057
3058                except Exception as e:
3059                    langfuse_logger.error(f"Evaluator failed: {e}")
3060
3061            # Run composite evaluator if provided and we have evaluations
3062            if composite_evaluator and evaluations:
3063                try:
3064                    composite_eval_metadata: Optional[Dict[str, Any]] = None
3065                    if isinstance(item, dict):
3066                        composite_eval_metadata = item.get("metadata")
3067                    elif hasattr(item, "metadata"):
3068                        composite_eval_metadata = item.metadata
3069
3070                    with _propagate_attributes(
3071                        experiment=propagated_experiment_attributes
3072                    ):
3073                        result = composite_evaluator(
3074                            input=input_data,
3075                            output=output,
3076                            expected_output=expected_output,
3077                            metadata=composite_eval_metadata,
3078                            evaluations=evaluations,
3079                        )
3080
3081                        # Handle async composite evaluators
3082                        if asyncio.iscoroutine(result):
3083                            result = await result
3084
3085                        # Normalize to list
3086                        composite_evals: List[Evaluation] = []
3087                        if isinstance(result, (dict, Evaluation)):
3088                            composite_evals = [result]  # type: ignore
3089                        elif isinstance(result, list):
3090                            composite_evals = result  # type: ignore
3091
3092                        # Store composite evaluations as scores and add to evaluations list
3093                        for composite_evaluation in composite_evals:
3094                            self.create_score(
3095                                trace_id=trace_id,
3096                                observation_id=span.id,
3097                                name=composite_evaluation.name,
3098                                value=composite_evaluation.value,  # type: ignore
3099                                comment=composite_evaluation.comment,
3100                                metadata=composite_evaluation.metadata,
3101                                config_id=composite_evaluation.config_id,
3102                                data_type=composite_evaluation.data_type,  # type: ignore
3103                            )
3104                            evaluations.append(composite_evaluation)
3105
3106                except Exception as e:
3107                    langfuse_logger.error(f"Composite evaluator failed: {e}")
3108
3109            return ExperimentItemResult(
3110                item=item,
3111                output=output,
3112                evaluations=evaluations,
3113                trace_id=trace_id,
3114                dataset_run_id=dataset_run_id,
3115            )
3116
3117    def _create_experiment_run_name(
3118        self, *, name: Optional[str] = None, run_name: Optional[str] = None
3119    ) -> str:
3120        if run_name:
3121            return run_name
3122
3123        iso_timestamp = _get_timestamp().isoformat().replace("+00:00", "Z")
3124
3125        return f"{name} - {iso_timestamp}"
3126
3127    def run_batched_evaluation(
3128        self,
3129        *,
3130        scope: Literal["traces", "observations"],
3131        mapper: MapperFunction,
3132        filter: Optional[str] = None,
3133        fetch_batch_size: int = 50,
3134        fetch_trace_fields: Optional[str] = None,
3135        max_items: Optional[int] = None,
3136        max_retries: int = 3,
3137        evaluators: List[EvaluatorFunction],
3138        composite_evaluator: Optional[CompositeEvaluatorFunction] = None,
3139        max_concurrency: int = 5,
3140        metadata: Optional[Dict[str, Any]] = None,
3141        _add_observation_scores_to_trace: bool = False,
3142        _additional_trace_tags: Optional[List[str]] = None,
3143        resume_from: Optional[BatchEvaluationResumeToken] = None,
3144        verbose: bool = False,
3145    ) -> BatchEvaluationResult:
3146        """Fetch traces or observations and run evaluations on each item.
3147
3148        This method provides a powerful way to evaluate existing data in Langfuse at scale.
3149        It fetches items based on filters, transforms them using a mapper function, runs
3150        evaluators on each item, and creates scores that are linked back to the original
3151        entities. This is ideal for:
3152
3153        - Running evaluations on production traces after deployment
3154        - Backtesting new evaluation metrics on historical data
3155        - Batch scoring of observations for quality monitoring
3156        - Periodic evaluation runs on recent data
3157
3158        The method uses a streaming/pipeline approach to process items in batches, making
3159        it memory-efficient for large datasets. It includes comprehensive error handling,
3160        retry logic, and resume capability for long-running evaluations.
3161
3162        Args:
3163            scope: The type of items to evaluate. Must be one of:
3164                - "traces": Evaluate complete traces with all their observations
3165                - "observations": Evaluate individual observations (spans, generations, events)
3166            mapper: Function that transforms API response objects into evaluator inputs.
3167                Receives a trace/observation object and returns an EvaluatorInputs
3168                instance with input, output, expected_output, and metadata fields.
3169                Can be sync or async.
3170            evaluators: List of evaluation functions to run on each item. Each evaluator
3171                receives the mapped inputs and returns Evaluation object(s). Evaluator
3172                failures are logged but don't stop the batch evaluation.
3173            filter: Optional JSON filter string for querying items (same format as Langfuse API). Examples:
3174                - '{"tags": ["production"]}'
3175                - '{"user_id": "user123", "timestamp": {"operator": ">", "value": "2024-01-01"}}'
3176                Default: None (fetches all items).
3177            fetch_batch_size: Number of items to fetch per API call and hold in memory.
3178                Larger values may be faster but use more memory. Default: 50.
3179            fetch_trace_fields: Comma-separated list of fields to include when fetching traces. Available field groups: 'core' (always included), 'io' (input, output, metadata), 'scores', 'observations', 'metrics'. If not specified, all fields are returned. Example: 'core,scores,metrics'. Note: Excluded 'observations' or 'scores' fields return empty arrays; excluded 'metrics' returns -1 for 'totalCost' and 'latency'. Only relevant if scope is 'traces'.
3180            max_items: Maximum total number of items to process. If None, processes all
3181                items matching the filter. Useful for testing or limiting evaluation runs.
3182                Default: None (process all).
3183            max_concurrency: Maximum number of items to evaluate concurrently. Controls
3184                parallelism and resource usage. Default: 5.
3185            composite_evaluator: Optional function that creates a composite score from
3186                item-level evaluations. Receives the original item and its evaluations,
3187                returns a single Evaluation. Useful for weighted averages or combined metrics.
3188                Default: None.
3189            metadata: Optional metadata dict to add to all created scores. Useful for
3190                tracking evaluation runs, versions, or other context. Default: None.
3191            max_retries: Maximum number of retry attempts for failed batch fetches.
3192                Uses exponential backoff (1s, 2s, 4s). Default: 3.
3193            verbose: If True, logs progress information to console. Useful for monitoring
3194                long-running evaluations. Default: False.
3195            resume_from: Optional resume token from a previous incomplete run. Allows
3196                continuing evaluation after interruption or failure. Default: None.
3197
3198
3199        Returns:
3200            BatchEvaluationResult containing:
3201                - total_items_fetched: Number of items fetched from API
3202                - total_items_processed: Number of items successfully evaluated
3203                - total_items_failed: Number of items that failed evaluation
3204                - total_scores_created: Scores created by item-level evaluators
3205                - total_composite_scores_created: Scores created by composite evaluator
3206                - total_evaluations_failed: Individual evaluator failures
3207                - evaluator_stats: Per-evaluator statistics (success rate, scores created)
3208                - resume_token: Token for resuming if incomplete (None if completed)
3209                - completed: True if all items processed
3210                - duration_seconds: Total execution time
3211                - failed_item_ids: IDs of items that failed
3212                - error_summary: Error types and counts
3213                - has_more_items: True if max_items reached but more exist
3214
3215        Raises:
3216            ValueError: If invalid scope is provided.
3217
3218        Examples:
3219            Basic trace evaluation:
3220            ```python
3221            from langfuse import Langfuse, EvaluatorInputs, Evaluation
3222
3223            client = Langfuse()
3224
3225            # Define mapper to extract fields from traces
3226            def trace_mapper(trace):
3227                return EvaluatorInputs(
3228                    input=trace.input,
3229                    output=trace.output,
3230                    expected_output=None,
3231                    metadata={"trace_id": trace.id}
3232                )
3233
3234            # Define evaluator
3235            def length_evaluator(*, input, output, expected_output, metadata):
3236                return Evaluation(
3237                    name="output_length",
3238                    value=len(output) if output else 0
3239                )
3240
3241            # Run batch evaluation
3242            result = client.run_batched_evaluation(
3243                scope="traces",
3244                mapper=trace_mapper,
3245                evaluators=[length_evaluator],
3246                filter='{"tags": ["production"]}',
3247                max_items=1000,
3248                verbose=True
3249            )
3250
3251            print(f"Processed {result.total_items_processed} traces")
3252            print(f"Created {result.total_scores_created} scores")
3253            ```
3254
3255            Evaluation with composite scorer:
3256            ```python
3257            def accuracy_evaluator(*, input, output, expected_output, metadata):
3258                # ... evaluation logic
3259                return Evaluation(name="accuracy", value=0.85)
3260
3261            def relevance_evaluator(*, input, output, expected_output, metadata):
3262                # ... evaluation logic
3263                return Evaluation(name="relevance", value=0.92)
3264
3265            def composite_evaluator(*, item, evaluations):
3266                # Weighted average of evaluations
3267                weights = {"accuracy": 0.6, "relevance": 0.4}
3268                total = sum(
3269                    e.value * weights.get(e.name, 0)
3270                    for e in evaluations
3271                    if isinstance(e.value, (int, float))
3272                )
3273                return Evaluation(
3274                    name="composite_score",
3275                    value=total,
3276                    comment=f"Weighted average of {len(evaluations)} metrics"
3277                )
3278
3279            result = client.run_batched_evaluation(
3280                scope="traces",
3281                mapper=trace_mapper,
3282                evaluators=[accuracy_evaluator, relevance_evaluator],
3283                composite_evaluator=composite_evaluator,
3284                filter='{"user_id": "important_user"}',
3285                verbose=True
3286            )
3287            ```
3288
3289            Handling incomplete runs with resume:
3290            ```python
3291            # Initial run that may fail or timeout
3292            result = client.run_batched_evaluation(
3293                scope="observations",
3294                mapper=obs_mapper,
3295                evaluators=[my_evaluator],
3296                max_items=10000,
3297                verbose=True
3298            )
3299
3300            # Check if incomplete
3301            if not result.completed and result.resume_token:
3302                print(f"Processed {result.resume_token.items_processed} items before interruption")
3303
3304                # Resume from where it left off
3305                result = client.run_batched_evaluation(
3306                    scope="observations",
3307                    mapper=obs_mapper,
3308                    evaluators=[my_evaluator],
3309                    resume_from=result.resume_token,
3310                    verbose=True
3311                )
3312
3313            print(f"Total items processed: {result.total_items_processed}")
3314            ```
3315
3316            Monitoring evaluator performance:
3317            ```python
3318            result = client.run_batched_evaluation(...)
3319
3320            for stats in result.evaluator_stats:
3321                success_rate = stats.successful_runs / stats.total_runs
3322                print(f"{stats.name}:")
3323                print(f"  Success rate: {success_rate:.1%}")
3324                print(f"  Scores created: {stats.total_scores_created}")
3325
3326                if stats.failed_runs > 0:
3327                    print(f"  ⚠️  Failed {stats.failed_runs} times")
3328            ```
3329
3330        Note:
3331            - Evaluator failures are logged but don't stop the batch evaluation
3332            - Individual item failures are tracked but don't stop processing
3333            - Fetch failures are retried with exponential backoff
3334            - All scores are automatically flushed to Langfuse at the end
3335            - The resume mechanism uses timestamp-based filtering to avoid duplicates
3336        """
3337        runner = BatchEvaluationRunner(self)
3338
3339        return cast(
3340            BatchEvaluationResult,
3341            run_async_safely(
3342                runner.run_async(
3343                    scope=scope,
3344                    mapper=mapper,
3345                    evaluators=evaluators,
3346                    filter=filter,
3347                    fetch_batch_size=fetch_batch_size,
3348                    fetch_trace_fields=fetch_trace_fields,
3349                    max_items=max_items,
3350                    max_concurrency=max_concurrency,
3351                    composite_evaluator=composite_evaluator,
3352                    metadata=metadata,
3353                    _add_observation_scores_to_trace=_add_observation_scores_to_trace,
3354                    _additional_trace_tags=_additional_trace_tags,
3355                    max_retries=max_retries,
3356                    verbose=verbose,
3357                    resume_from=resume_from,
3358                )
3359            ),
3360        )
3361
3362    def auth_check(self) -> bool:
3363        """Check if the provided credentials (public and secret key) are valid.
3364
3365        Raises:
3366            Exception: If no projects were found for the provided credentials.
3367
3368        Note:
3369            This method is blocking. It is discouraged to use it in production code.
3370        """
3371        try:
3372            projects = self.api.projects.get()
3373            langfuse_logger.debug(
3374                f"Auth check successful, found {len(projects.data)} projects"
3375            )
3376            if len(projects.data) == 0:
3377                raise Exception(
3378                    "Auth check failed, no project found for the keys provided."
3379                )
3380            return True
3381
3382        except AttributeError as e:
3383            langfuse_logger.warning(
3384                f"Auth check failed: Client not properly initialized. Error: {e}"
3385            )
3386            return False
3387
3388        except Error as e:
3389            handle_fern_exception(e)
3390            raise e
3391
3392    def create_dataset(
3393        self,
3394        *,
3395        name: str,
3396        description: Optional[str] = None,
3397        metadata: Optional[Any] = None,
3398        input_schema: Optional[Any] = None,
3399        expected_output_schema: Optional[Any] = None,
3400    ) -> Dataset:
3401        """Create a dataset with the given name on Langfuse.
3402
3403        Args:
3404            name: Name of the dataset to create.
3405            description: Description of the dataset. Defaults to None.
3406            metadata: Additional metadata. Defaults to None.
3407            input_schema: JSON Schema for validating dataset item inputs. When set, all new items will be validated against this schema.
3408            expected_output_schema: JSON Schema for validating dataset item expected outputs. When set, all new items will be validated against this schema.
3409
3410        Returns:
3411            Dataset: The created dataset as returned by the Langfuse API.
3412        """
3413        try:
3414            langfuse_logger.debug(f"Creating datasets {name}")
3415
3416            result = self.api.datasets.create(
3417                name=name,
3418                description=description,
3419                metadata=metadata,
3420                input_schema=input_schema,
3421                expected_output_schema=expected_output_schema,
3422            )
3423
3424            return cast(Dataset, result)
3425
3426        except Error as e:
3427            handle_fern_exception(e)
3428            raise e
3429
3430    def create_dataset_item(
3431        self,
3432        *,
3433        dataset_name: str,
3434        input: Optional[Any] = None,
3435        expected_output: Optional[Any] = None,
3436        metadata: Optional[Any] = None,
3437        source_trace_id: Optional[str] = None,
3438        source_observation_id: Optional[str] = None,
3439        status: Optional[DatasetStatus] = None,
3440        id: Optional[str] = None,
3441    ) -> DatasetItem:
3442        """Create a dataset item.
3443
3444        Upserts if an item with id already exists.
3445
3446        Args:
3447            dataset_name: Name of the dataset in which the dataset item should be created.
3448            input: Input data. Defaults to None. Can contain any dict, list or scalar.
3449            expected_output: Expected output data. Defaults to None. Can contain any dict, list or scalar.
3450            metadata: Additional metadata. Defaults to None. Can contain any dict, list or scalar.
3451            source_trace_id: Id of the source trace. Defaults to None.
3452            source_observation_id: Id of the source observation. Defaults to None.
3453            status: Status of the dataset item. Defaults to ACTIVE for newly created items.
3454            id: Id of the dataset item. Defaults to None. Provide your own id if you want to dedupe dataset items. Id needs to be globally unique and cannot be reused across datasets.
3455
3456        Returns:
3457            DatasetItem: The created dataset item as returned by the Langfuse API.
3458
3459        Example:
3460            ```python
3461            from langfuse import Langfuse
3462
3463            langfuse = Langfuse()
3464
3465            # Uploading items to the Langfuse dataset named "capital_cities"
3466            langfuse.create_dataset_item(
3467                dataset_name="capital_cities",
3468                input={"input": {"country": "Italy"}},
3469                expected_output={"expected_output": "Rome"},
3470                metadata={"foo": "bar"}
3471            )
3472            ```
3473        """
3474        try:
3475            langfuse_logger.debug(f"Creating dataset item for dataset {dataset_name}")
3476
3477            # Media uploads must reference the (dataset, item) they belong to, and
3478            # the item need not exist yet — so settle on the item id up front and
3479            # reuse it for the create call below.
3480            item_id = id if id is not None else str(uuid.uuid4())
3481
3482            # Single pass per field: swap each LangfuseMedia for its reference
3483            # string (derived from content, not the upload) and collect the media
3484            # still to upload, deduped by media id and tagged with its field.
3485            pending_media: Dict[str, Tuple[LangfuseMedia, str]] = {}
3486            input = self._process_dataset_item_media(
3487                data=input,
3488                pending_media=pending_media,
3489                field=DatasetItemMediaReferenceField.INPUT.value,
3490            )
3491            expected_output = self._process_dataset_item_media(
3492                data=expected_output,
3493                pending_media=pending_media,
3494                field=DatasetItemMediaReferenceField.EXPECTED_OUTPUT.value,
3495            )
3496            metadata = self._process_dataset_item_media(
3497                data=metadata,
3498                pending_media=pending_media,
3499                field=DatasetItemMediaReferenceField.METADATA.value,
3500            )
3501
3502            # The upload needs the dataset id, but the create API only takes the
3503            # name. Resolve it once, and only when there is actually media to
3504            # upload — a plain item pays no extra datasets.get round-trip.
3505            if pending_media:
3506                assert self._resources is not None
3507                dataset_id = self.api.datasets.get(self._url_encode(dataset_name)).id
3508                for media, field in pending_media.values():
3509                    self._resources._media_manager._upload_media_sync(
3510                        media=media,
3511                        dataset_id=dataset_id,
3512                        dataset_item_id=item_id,
3513                        field=field,
3514                    )
3515
3516            result = self.api.dataset_items.create(
3517                dataset_name=dataset_name,
3518                input=input,
3519                expected_output=expected_output,
3520                metadata=metadata,
3521                source_trace_id=source_trace_id,
3522                source_observation_id=source_observation_id,
3523                status=status,
3524                id=item_id,
3525            )
3526
3527            return cast(DatasetItem, result)
3528        except Error as e:
3529            handle_fern_exception(e)
3530            raise e
3531
3532    def _process_dataset_item_media(
3533        self,
3534        *,
3535        data: Any,
3536        pending_media: Dict[str, Tuple[LangfuseMedia, str]],
3537        field: str,
3538    ) -> Any:
3539        """Swap each ``LangfuseMedia`` for its reference string in ``data``.
3540
3541        Each replaced media is recorded in ``pending_media`` (keyed by media id,
3542        so the same media across fields uploads once) for the caller to upload
3543        after the dataset id has been resolved.
3544        """
3545        if self._resources is None:
3546            return data
3547
3548        max_levels = 10
3549
3550        def _process_data_recursively(
3551            data: Any, level: int, ancestor_container_ids: set[int]
3552        ) -> Any:
3553            if isinstance(data, LangfuseMedia):
3554                reference_string = data._reference_string
3555                media_id = data._media_id
3556                if reference_string is None or media_id is None:
3557                    raise ValueError(
3558                        "Cannot create dataset item with invalid LangfuseMedia."
3559                    )
3560                # First field a media appears in wins; later duplicates dedupe.
3561                pending_media.setdefault(media_id, (data, field))
3562                return reference_string
3563
3564            if isinstance(data, LangfuseMediaReference):
3565                return data.reference_string if data.reference_string else data
3566
3567            # Tuples are intentionally excluded: namedtuple subclasses can't be
3568            # rebuilt from an iterable, so media inside them is left untouched.
3569            if not isinstance(data, (list, set, frozenset, dict)):
3570                return data
3571
3572            # Container ids only protect against recursive cycles.
3573            data_id = id(data)
3574            if data_id in ancestor_container_ids or level > max_levels:
3575                return data
3576
3577            next_ancestor_container_ids = ancestor_container_ids | {data_id}
3578
3579            if isinstance(data, (list, set, frozenset)):
3580                processed = (
3581                    _process_data_recursively(
3582                        item, level + 1, next_ancestor_container_ids
3583                    )
3584                    for item in data
3585                )
3586                return type(data)(processed)
3587
3588            return {
3589                key: _process_data_recursively(
3590                    value, level + 1, next_ancestor_container_ids
3591                )
3592                for key, value in data.items()
3593            }
3594
3595        return _process_data_recursively(data, 1, set())
3596
3597    def _hydrate_dataset_item_media_references(self, item: DatasetItem) -> DatasetItem:
3598        media_references = item.media_references or []
3599        if not media_references:
3600            return item
3601
3602        # Map the API enum member to the snake_case model attribute so this keeps
3603        # working regardless of the enum's wire value (e.g. "expectedOutput").
3604        attr_by_field = {
3605            DatasetItemMediaReferenceField.INPUT: "input",
3606            DatasetItemMediaReferenceField.EXPECTED_OUTPUT: "expected_output",
3607            DatasetItemMediaReferenceField.METADATA: "metadata",
3608        }
3609        hydrated_fields = {
3610            "input": item.input,
3611            "expected_output": item.expected_output,
3612            "metadata": item.metadata,
3613        }
3614
3615        for media_reference in media_references:
3616            media = media_reference.media
3617            field = attr_by_field.get(media_reference.field)
3618            if field is None:
3619                continue
3620
3621            replacement = LangfuseMediaReference(
3622                media_id=media.media_id,
3623                content_type=media.content_type,
3624                url=media.url,
3625                url_expiry=media.url_expiry,
3626                content_length=media.content_length,
3627                reference_string=media_reference.reference_string,
3628            )
3629            hydrated_fields[field] = self._replace_json_path_value(
3630                value=hydrated_fields[field],
3631                path=media_reference.json_path,
3632                replacement=replacement,
3633            )
3634
3635        return item.model_copy(
3636            update={
3637                "input": hydrated_fields["input"],
3638                "expected_output": hydrated_fields["expected_output"],
3639                "metadata": hydrated_fields["metadata"],
3640            }
3641        )
3642
3643    def _replace_json_path_value(
3644        self, *, value: Any, path: str, replacement: LangfuseMediaReference
3645    ) -> Any:
3646        try:
3647            return json_path.set_value_at_path(value, path, replacement)
3648        except Exception as e:
3649            langfuse_logger.warning(
3650                f"Failed to hydrate dataset media reference at JSONPath {path}",
3651                exc_info=e,
3652            )
3653
3654            return value
3655
3656    def resolve_media_references(
3657        self,
3658        *,
3659        obj: Any,
3660        resolve_with: Literal["base64_data_uri"],
3661        max_depth: int = 10,
3662        content_fetch_timeout_seconds: int = 5,
3663    ) -> Any:
3664        """Replace media reference strings in an object with base64 data URIs.
3665
3666        This method recursively traverses an object (up to max_depth) looking for media reference strings
3667        in the format "@@@langfuseMedia:...@@@". When found, it (synchronously) fetches the actual media content using
3668        the provided Langfuse client and replaces the reference string with a base64 data URI.
3669
3670        If fetching media content fails for a reference string, a warning is logged and the reference
3671        string is left unchanged.
3672
3673        Args:
3674            obj: The object to process. Can be a primitive value, array, or nested object.
3675                If the object has a __dict__ attribute, a dict will be returned instead of the original object type.
3676            resolve_with: The representation of the media content to replace the media reference string with.
3677                Currently only "base64_data_uri" is supported.
3678            max_depth: int: The maximum depth to traverse the object. Default is 10.
3679            content_fetch_timeout_seconds: int: The timeout in seconds for fetching media content. Default is 5.
3680
3681        Returns:
3682            A deep copy of the input object with all media references replaced with base64 data URIs where possible.
3683            If the input object has a __dict__ attribute, a dict will be returned instead of the original object type.
3684
3685        Example:
3686            obj = {
3687                "image": "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@",
3688                "nested": {
3689                    "pdf": "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@"
3690                }
3691            }
3692
3693            result = await LangfuseMedia.resolve_media_references(obj, langfuse_client)
3694
3695            # Result:
3696            # {
3697            #     "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
3698            #     "nested": {
3699            #         "pdf": "data:application/pdf;base64,JVBERi0xLjcK..."
3700            #     }
3701            # }
3702        """
3703        return LangfuseMedia.resolve_media_references(
3704            langfuse_client=self,
3705            obj=obj,
3706            resolve_with=resolve_with,
3707            max_depth=max_depth,
3708            content_fetch_timeout_seconds=content_fetch_timeout_seconds,
3709        )
3710
3711    @overload
3712    def get_prompt(
3713        self,
3714        name: str,
3715        *,
3716        version: Optional[int] = None,
3717        label: Optional[str] = None,
3718        type: Literal["chat"],
3719        cache_ttl_seconds: Optional[int] = None,
3720        fallback: Optional[List[ChatMessageDict]] = None,
3721        max_retries: Optional[int] = None,
3722        fetch_timeout_seconds: Optional[int] = None,
3723    ) -> ChatPromptClient: ...
3724
3725    @overload
3726    def get_prompt(
3727        self,
3728        name: str,
3729        *,
3730        version: Optional[int] = None,
3731        label: Optional[str] = None,
3732        type: Literal["text"] = "text",
3733        cache_ttl_seconds: Optional[int] = None,
3734        fallback: Optional[str] = None,
3735        max_retries: Optional[int] = None,
3736        fetch_timeout_seconds: Optional[int] = None,
3737    ) -> TextPromptClient: ...
3738
3739    def get_prompt(
3740        self,
3741        name: str,
3742        *,
3743        version: Optional[int] = None,
3744        label: Optional[str] = None,
3745        type: Literal["chat", "text"] = "text",
3746        cache_ttl_seconds: Optional[int] = None,
3747        fallback: Union[Optional[List[ChatMessageDict]], Optional[str]] = None,
3748        max_retries: Optional[int] = None,
3749        fetch_timeout_seconds: Optional[int] = None,
3750    ) -> PromptClient:
3751        """Get a prompt.
3752
3753        This method attempts to fetch the requested prompt from the local cache. If the prompt is not found
3754        in the cache or if the cached prompt has expired, it will try to fetch the prompt from the server again
3755        and update the cache. If fetching the new prompt fails, and there is an expired prompt in the cache, it will
3756        return the expired prompt as a fallback.
3757
3758        Args:
3759            name (str): The name of the prompt to retrieve.
3760
3761        Keyword Args:
3762            version (Optional[int]): The version of the prompt to retrieve. If no label and version is specified, the `production` label is returned. Specify either version or label, not both.
3763            label: Optional[str]: The label of the prompt to retrieve. If no label and version is specified, the `production` label is returned. Specify either version or label, not both.
3764            cache_ttl_seconds: Optional[int]: Time-to-live in seconds for caching the prompt. Must be specified as a
3765            keyword argument. If not set, defaults to 60 seconds. Disables caching if set to 0.
3766            type: Literal["chat", "text"]: The type of the prompt to retrieve. Defaults to "text".
3767            fallback: Union[Optional[List[ChatMessageDict]], Optional[str]]: The prompt string to return if fetching the prompt fails. Important on the first call where no cached prompt is available. Follows Langfuse prompt formatting with double curly braces for variables. Defaults to None.
3768            max_retries: Optional[int]: The maximum number of retries in case of API/network errors. Defaults to 2. The maximum value is 4. Retries have an exponential backoff with a maximum delay of 10 seconds.
3769            fetch_timeout_seconds: Optional[int]: The timeout in milliseconds for fetching the prompt. Defaults to the default timeout set on the SDK, which is 5 seconds per default.
3770
3771        Returns:
3772            The prompt object retrieved from the cache or directly fetched if not cached or expired of type
3773            - TextPromptClient, if type argument is 'text'.
3774            - ChatPromptClient, if type argument is 'chat'.
3775
3776        Raises:
3777            Exception: Propagates any exceptions raised during the fetching of a new prompt, unless there is an
3778            expired prompt in the cache, in which case it logs a warning and returns the expired prompt.
3779        """
3780        if self._resources is None:
3781            raise Error(
3782                "SDK is not correctly initialized. Check the init logs for more details."
3783            )
3784        if version is not None and label is not None:
3785            raise ValueError("Cannot specify both version and label at the same time.")
3786
3787        if not name:
3788            raise ValueError("Prompt name cannot be empty.")
3789
3790        cache_key = PromptCache.generate_cache_key(name, version=version, label=label)
3791        bounded_max_retries = self._get_bounded_max_retries(
3792            max_retries, default_max_retries=2, max_retries_upper_bound=4
3793        )
3794
3795        langfuse_logger.debug(f"Getting prompt '{cache_key}'")
3796        cached_prompt = self._resources.prompt_cache.get(cache_key)
3797
3798        if cached_prompt is None or cache_ttl_seconds == 0:
3799            langfuse_logger.debug(
3800                f"Prompt '{cache_key}' not found in cache or caching disabled."
3801            )
3802            try:
3803                return self._fetch_prompt_and_update_cache(
3804                    name,
3805                    version=version,
3806                    label=label,
3807                    ttl_seconds=cache_ttl_seconds,
3808                    max_retries=bounded_max_retries,
3809                    fetch_timeout_seconds=fetch_timeout_seconds,
3810                )
3811            except Exception as e:
3812                if fallback:
3813                    langfuse_logger.warning(
3814                        f"Returning fallback prompt for '{cache_key}' due to fetch error: {e}"
3815                    )
3816
3817                    fallback_client_args: Dict[str, Any] = {
3818                        "name": name,
3819                        "prompt": fallback,
3820                        "type": type,
3821                        "version": version or 0,
3822                        "config": {},
3823                        "labels": [label] if label else [],
3824                        "tags": [],
3825                    }
3826
3827                    if type == "text":
3828                        return TextPromptClient(
3829                            prompt=Prompt_Text(**fallback_client_args),
3830                            is_fallback=True,
3831                        )
3832
3833                    if type == "chat":
3834                        return ChatPromptClient(
3835                            prompt=Prompt_Chat(**fallback_client_args),
3836                            is_fallback=True,
3837                        )
3838
3839                raise e
3840
3841        if cached_prompt.is_expired():
3842            langfuse_logger.debug(f"Stale prompt '{cache_key}' found in cache.")
3843            try:
3844                # refresh prompt in background thread, refresh_prompt deduplicates tasks
3845                langfuse_logger.debug(f"Refreshing prompt '{cache_key}' in background.")
3846
3847                def refresh_task() -> None:
3848                    self._fetch_prompt_and_update_cache(
3849                        name,
3850                        version=version,
3851                        label=label,
3852                        ttl_seconds=cache_ttl_seconds,
3853                        max_retries=bounded_max_retries,
3854                        fetch_timeout_seconds=fetch_timeout_seconds,
3855                    )
3856
3857                self._resources.prompt_cache.add_refresh_prompt_task_if_current(
3858                    cache_key,
3859                    cached_prompt,
3860                    refresh_task,
3861                )
3862                langfuse_logger.debug(
3863                    f"Returning stale prompt '{cache_key}' from cache."
3864                )
3865                # return stale prompt
3866                return cached_prompt.value
3867
3868            except Exception as e:
3869                langfuse_logger.warning(
3870                    f"Error when refreshing cached prompt '{cache_key}', returning cached version. Error: {e}"
3871                )
3872                # creation of refresh prompt task failed, return stale prompt
3873                return cached_prompt.value
3874
3875        return cached_prompt.value
3876
3877    def _fetch_prompt_and_update_cache(
3878        self,
3879        name: str,
3880        *,
3881        version: Optional[int] = None,
3882        label: Optional[str] = None,
3883        ttl_seconds: Optional[int] = None,
3884        max_retries: int,
3885        fetch_timeout_seconds: Optional[int],
3886    ) -> PromptClient:
3887        cache_key = PromptCache.generate_cache_key(name, version=version, label=label)
3888        langfuse_logger.debug(f"Fetching prompt '{cache_key}' from server...")
3889
3890        try:
3891
3892            @backoff.on_exception(
3893                backoff.constant, Exception, max_tries=max_retries + 1, logger=None
3894            )
3895            def fetch_prompts() -> Any:
3896                return self.api.prompts.get(
3897                    self._url_encode(name),
3898                    version=version,
3899                    label=label,
3900                    request_options={
3901                        "timeout_in_seconds": fetch_timeout_seconds,
3902                    }
3903                    if fetch_timeout_seconds is not None
3904                    else None,
3905                )
3906
3907            prompt_response = fetch_prompts()
3908
3909            prompt: PromptClient
3910            if prompt_response.type == "chat":
3911                prompt = ChatPromptClient(prompt_response)
3912            else:
3913                prompt = TextPromptClient(prompt_response)
3914
3915            if self._resources is not None:
3916                self._resources.prompt_cache.set(cache_key, prompt, ttl_seconds)
3917
3918            return prompt
3919
3920        except NotFoundError as not_found_error:
3921            langfuse_logger.warning(
3922                f"Prompt '{cache_key}' not found during refresh, evicting from cache."
3923            )
3924            if self._resources is not None:
3925                self._resources.prompt_cache.delete(cache_key)
3926            raise not_found_error
3927
3928        except Exception as e:
3929            langfuse_logger.error(
3930                f"Error while fetching prompt '{cache_key}': {str(e)}"
3931            )
3932            raise e
3933
3934    def _get_bounded_max_retries(
3935        self,
3936        max_retries: Optional[int],
3937        *,
3938        default_max_retries: int = 2,
3939        max_retries_upper_bound: int = 4,
3940    ) -> int:
3941        if max_retries is None:
3942            return default_max_retries
3943
3944        bounded_max_retries = min(
3945            max(max_retries, 0),
3946            max_retries_upper_bound,
3947        )
3948
3949        return bounded_max_retries
3950
3951    @overload
3952    def create_prompt(
3953        self,
3954        *,
3955        name: str,
3956        prompt: List[Union[ChatMessageDict, ChatMessageWithPlaceholdersDict]],
3957        labels: List[str] = [],
3958        tags: Optional[List[str]] = None,
3959        type: Optional[Literal["chat"]],
3960        config: Optional[Any] = None,
3961        commit_message: Optional[str] = None,
3962    ) -> ChatPromptClient: ...
3963
3964    @overload
3965    def create_prompt(
3966        self,
3967        *,
3968        name: str,
3969        prompt: str,
3970        labels: List[str] = [],
3971        tags: Optional[List[str]] = None,
3972        type: Optional[Literal["text"]] = "text",
3973        config: Optional[Any] = None,
3974        commit_message: Optional[str] = None,
3975    ) -> TextPromptClient: ...
3976
3977    def create_prompt(
3978        self,
3979        *,
3980        name: str,
3981        prompt: Union[
3982            str, List[Union[ChatMessageDict, ChatMessageWithPlaceholdersDict]]
3983        ],
3984        labels: List[str] = [],
3985        tags: Optional[List[str]] = None,
3986        type: Optional[Literal["chat", "text"]] = "text",
3987        config: Optional[Any] = None,
3988        commit_message: Optional[str] = None,
3989    ) -> PromptClient:
3990        """Create a new prompt in Langfuse.
3991
3992        Keyword Args:
3993            name : The name of the prompt to be created.
3994            prompt : The content of the prompt to be created.
3995            is_active [DEPRECATED] : A flag indicating whether the prompt is active or not. This is deprecated and will be removed in a future release. Please use the 'production' label instead.
3996            labels: The labels of the prompt. Defaults to None. To create a default-served prompt, add the 'production' label.
3997            tags: The tags of the prompt. Defaults to None. Will be applied to all versions of the prompt.
3998            config: Additional structured data to be saved with the prompt. Defaults to None.
3999            type: The type of the prompt to be created. "chat" vs. "text". Defaults to "text".
4000            commit_message: Optional string describing the change.
4001
4002        Returns:
4003            TextPromptClient: The prompt if type argument is 'text'.
4004            ChatPromptClient: The prompt if type argument is 'chat'.
4005        """
4006        try:
4007            langfuse_logger.debug(f"Creating prompt {name=}, {labels=}")
4008
4009            if type == "chat":
4010                if not isinstance(prompt, list):
4011                    raise ValueError(
4012                        "For 'chat' type, 'prompt' must be a list of chat messages with role and content attributes."
4013                    )
4014                request: Union[CreateChatPromptRequest, CreateTextPromptRequest] = (
4015                    CreateChatPromptRequest(
4016                        name=name,
4017                        prompt=cast(Any, prompt),
4018                        labels=labels,
4019                        tags=tags,
4020                        config=config or {},
4021                        commit_message=commit_message,
4022                        type=CreateChatPromptType.CHAT,
4023                    )
4024                )
4025                server_prompt = self.api.prompts.create(request=request)
4026
4027                if self._resources is not None:
4028                    self._resources.prompt_cache.invalidate(name)
4029
4030                return ChatPromptClient(prompt=cast(Prompt_Chat, server_prompt))
4031
4032            if not isinstance(prompt, str):
4033                raise ValueError("For 'text' type, 'prompt' must be a string.")
4034
4035            request = CreateTextPromptRequest(
4036                name=name,
4037                prompt=prompt,
4038                labels=labels,
4039                tags=tags,
4040                config=config or {},
4041                commit_message=commit_message,
4042            )
4043
4044            server_prompt = self.api.prompts.create(request=request)
4045
4046            if self._resources is not None:
4047                self._resources.prompt_cache.invalidate(name)
4048
4049            return TextPromptClient(prompt=cast(Prompt_Text, server_prompt))
4050
4051        except Error as e:
4052            handle_fern_exception(e)
4053            raise e
4054
4055    def update_prompt(
4056        self,
4057        *,
4058        name: str,
4059        version: int,
4060        new_labels: List[str] = [],
4061    ) -> Any:
4062        """Update an existing prompt version in Langfuse. The Langfuse SDK prompt cache is invalidated for all prompts witht he specified name.
4063
4064        Args:
4065            name (str): The name of the prompt to update.
4066            version (int): The version number of the prompt to update.
4067            new_labels (List[str], optional): New labels to assign to the prompt version. Labels are unique across versions. The "latest" label is reserved and managed by Langfuse. Defaults to [].
4068
4069        Returns:
4070            Prompt: The updated prompt from the Langfuse API.
4071
4072        """
4073        updated_prompt = self.api.prompt_version.update(
4074            name=self._url_encode(name),
4075            version=version,
4076            new_labels=new_labels,
4077        )
4078
4079        if self._resources is not None:
4080            self._resources.prompt_cache.invalidate(name)
4081
4082        return updated_prompt
4083
4084    def _url_encode(self, url: str, *, is_url_param: Optional[bool] = False) -> str:
4085        # httpx ≥ 0.28 does its own WHATWG-compliant quoting (eg. encodes bare
4086        # “%”, “?”, “#”, “|”, … in query/path parts).  Re-quoting here would
4087        # double-encode, so we skip when the value is about to be sent straight
4088        # to httpx (`is_url_param=True`) and the installed version is ≥ 0.28.
4089        if is_url_param and Version(httpx.__version__) >= Version("0.28.0"):
4090            return url
4091
4092        # urllib.parse.quote does not escape slashes "/" by default; we need to add safe="" to force escaping
4093        # we need add safe="" to force escaping of slashes
4094        # This is necessary for prompts in prompt folders
4095        return urllib.parse.quote(url, safe="")
4096
4097    def clear_prompt_cache(self) -> None:
4098        """Clear the entire prompt cache, removing all cached prompts.
4099
4100        This method is useful when you want to force a complete refresh of all
4101        cached prompts, for example after major updates or when you need to
4102        ensure the latest versions are fetched from the server.
4103        """
4104        if self._resources is not None:
4105            self._resources.prompt_cache.clear()

Main client for Langfuse tracing and platform features.

This class provides an interface for creating and managing traces, spans, and generations in Langfuse as well as interacting with the Langfuse API.

The client features a thread-safe singleton pattern for each unique public API key, ensuring consistent trace context propagation across your application. It implements efficient batching of spans with configurable flush settings and includes background thread management for media uploads and score ingestion.

Configuration is flexible through either direct parameters or environment variables, with graceful fallbacks and runtime configuration updates.

Attributes:
  • api: Synchronous API client for Langfuse backend communication
  • async_api: Asynchronous API client for Langfuse backend communication
  • _otel_tracer: Internal LangfuseTracer instance managing OpenTelemetry components
Arguments:
  • public_key (Optional[str]): Your Langfuse public API key. Can also be set via LANGFUSE_PUBLIC_KEY environment variable.
  • secret_key (Optional[str]): Your Langfuse secret API key. Can also be set via LANGFUSE_SECRET_KEY environment variable.
  • base_url (Optional[str]): The Langfuse API base URL. Defaults to "https://cloud.langfuse.com". Can also be set via LANGFUSE_BASE_URL environment variable.
  • host (Optional[str]): Deprecated. Use base_url instead. The Langfuse API host URL. Defaults to "https://cloud.langfuse.com".
  • timeout (Optional[int]): Timeout in seconds for API requests. Defaults to 5 seconds.
  • httpx_client (Optional[httpx.Client]): Custom httpx client for making non-tracing HTTP requests. If not provided, a default client will be created. Fork safety: httpx.Client is thread-safe but not process-safe. When using fork()-based servers (e.g. Gunicorn with --preload), the SDK automatically recreates its internally-managed HTTP client in child processes after fork. A custom httpx_client is intentionally left as-is (the fork-inherited copy is reused), so you retain the opportunity to handle process-safety yourself — for example by registering your own os.register_at_fork(after_in_child=...) handler to close and reopen connections on the custom client.
  • debug (bool): Enable debug logging. Defaults to False. Can also be set via LANGFUSE_DEBUG environment variable.
  • tracing_enabled (Optional[bool]): Enable or disable tracing. Defaults to True. Can also be set via LANGFUSE_TRACING_ENABLED environment variable.
  • flush_at (Optional[int]): Number of spans to batch before sending to the API. Defaults to 512. Can also be set via LANGFUSE_FLUSH_AT environment variable.
  • flush_interval (Optional[float]): Time in seconds between batch flushes. Defaults to 5 seconds. Can also be set via LANGFUSE_FLUSH_INTERVAL environment variable.
  • environment (Optional[str]): Environment name for tracing. Default is 'default'. Can also be set via LANGFUSE_TRACING_ENVIRONMENT environment variable. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.
  • release (Optional[str]): Release version/hash of your application. Used for grouping analytics by release.
  • media_upload_thread_count (Optional[int]): Number of background threads for handling media uploads. Defaults to 1. Can also be set via LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT environment variable.
  • sample_rate (Optional[float]): Sampling rate for traces (0.0 to 1.0). Defaults to 1.0 (100% of traces are sampled). Can also be set via LANGFUSE_SAMPLE_RATE environment variable.
  • mask (Optional[MaskFunction]): Function to mask sensitive data synchronously when Langfuse SDK attributes are created. This applies only to data set through Langfuse SDK APIs such as start_observation(), update(), and set_trace_io().

  • mask_otel_spans (Optional[MaskOtelSpansFunction]): Synchronous export-stage hook for masking raw OpenTelemetry span attributes before this Langfuse client sends them to Langfuse. Use this for spans created by third-party OpenTelemetry instrumentations, or when you need to inspect final span attributes after export filtering and Langfuse media handling. It does not modify spans already exported through other OpenTelemetry exporters.

    The hook receives one OpenTelemetry export batch. A batch is not guaranteed to contain a complete trace, request, or Langfuse observation tree. The hook usually runs on the OpenTelemetry batch span processor worker thread; during flush() and shutdown it may run on the caller thread. Keep it synchronous, deterministic, and fast.

    Return None to leave the batch unchanged. Return MaskOtelSpansResult with OtelSpanPatch values to delete or replace attributes on selected spans. If the hook raises or returns an invalid batch result, Langfuse drops the whole export batch. If one returned span patch is invalid, Langfuse drops only that span from the Langfuse export.

    Example:

    

    from typing import Optional

from langfuse import Langfuse
from langfuse.types import (
    MaskOtelSpansParams,
    MaskOtelSpansResult,
    OtelSpanPatch,
)

def mask_otel_spans(
    *, params: MaskOtelSpansParams
) -> Optional[MaskOtelSpansResult]:
    patches = {}

    for identifier, span in params.spans.items():
        if "gen_ai.prompt.0.content" in span.attributes:
            patches[identifier] = OtelSpanPatch(
                delete_attributes=("gen_ai.prompt.0.content",),
                set_attributes={"masking.applied": True},
            )

    return MaskOtelSpansResult(span_patches=patches)

langfuse = Langfuse(mask_otel_spans=mask_otel_spans)

  • blocked_instrumentation_scopes (Optional[List[str]]): Deprecated. Use should_export_span instead. Equivalent behavior:

    from langfuse.span_filter import is_default_export_span
blocked = {"sqlite", "requests"}

should_export_span = lambda span: (
    is_default_export_span(span)
    and (
        span.instrumentation_scope is None
        or span.instrumentation_scope.name not in blocked
    )
)

  • should_export_span (Optional[Callable[[ReadableSpan], bool]]): Callback to decide whether to export a span. If omitted, Langfuse uses the default filter (Langfuse SDK spans, spans with gen_ai.* attributes, and known LLM instrumentation scopes).

  • additional_headers (Optional[Dict[str, str]]): Additional headers to include in all API requests and in the default OTLPSpanExporter requests. These headers will be merged with default headers. Note: If httpx_client is provided, additional_headers must be set directly on your custom httpx_client as well. If span_exporter is provided, these headers are not wired into that exporter and must be configured on the exporter instance directly.
  • tracer_provider(Optional[TracerProvider]): OpenTelemetry TracerProvider to use for Langfuse. This can be useful to set to have disconnected tracing between Langfuse and other OpenTelemetry-span emitting libraries. Note: To track active spans, the context is still shared between TracerProviders. This may lead to broken trace trees.
  • id_generator (Optional[IdGenerator]): OpenTelemetry ID generator to use when Langfuse creates its own TracerProvider. If omitted, the OpenTelemetry SDK default is used. If tracer_provider is provided, or an OpenTelemetry TracerProvider is already registered globally, configure the ID generator on that provider instead.
  • span_exporter (Optional[SpanExporter]): Custom OpenTelemetry span exporter for the Langfuse span processor. If omitted, Langfuse creates an OTLPSpanExporter pointed at the Langfuse OTLP endpoint. If provided, Langfuse does not wire base_url, exporter headers, exporter auth, or exporter timeout into it. Configure endpoint, headers, and timeout on the exporter instance directly. If you are sending spans to Langfuse v4 or using Langfuse Cloud Fast Preview, include x-langfuse-ingestion-version=4 on the exporter to enable real time processing of exported spans.
Example:
from langfuse import Langfuse

# Initialize the client (reads from env vars if not provided)
langfuse = Langfuse(
    public_key="your-public-key",
    secret_key="your-secret-key",
    base_url="https://cloud.langfuse.com",  # Optional, default shown
)

# Create a trace span
with langfuse.start_as_current_observation(name="process-query") as span:
    # Your application code here

    # Create a nested generation span for an LLM call
    with span.start_as_current_generation(
        name="generate-response",
        model="gpt-4",
        input={"query": "Tell me about AI"},
        model_parameters={"temperature": 0.7, "max_tokens": 500}
    ) as generation:
        # Generate response here
        response = "AI is a field of computer science..."

        generation.update(
            output=response,
            usage_details={"prompt_tokens": 10, "completion_tokens": 50},
            cost_details={"total_cost": 0.0023}
        )

        # Score the generation (supports NUMERIC, BOOLEAN, CATEGORICAL)
        generation.score(name="relevance", value=0.95, data_type="NUMERIC")
Langfuse( *, public_key: Optional[str] = None, secret_key: Optional[str] = None, base_url: Optional[str] = None, host: Optional[str] = None, timeout: Optional[int] = None, httpx_client: Optional[httpx.Client] = None, debug: bool = False, tracing_enabled: Optional[bool] = True, flush_at: Optional[int] = None, flush_interval: Optional[float] = None, environment: Optional[str] = None, release: Optional[str] = None, media_upload_thread_count: Optional[int] = None, sample_rate: Optional[float] = None, mask: Optional[langfuse.types.MaskFunction] = None, mask_otel_spans: Optional[MaskOtelSpansFunction] = None, blocked_instrumentation_scopes: Optional[List[str]] = None, should_export_span: Optional[Callable[[opentelemetry.sdk.trace.ReadableSpan], bool]] = None, additional_headers: Optional[Dict[str, str]] = None, tracer_provider: Optional[opentelemetry.sdk.trace.TracerProvider] = None, id_generator: Optional[opentelemetry.sdk.trace.id_generator.IdGenerator] = None, span_exporter: Optional[opentelemetry.sdk.trace.export.SpanExporter] = None) 
290    def __init__(
291        self,
292        *,
293        public_key: Optional[str] = None,
294        secret_key: Optional[str] = None,
295        base_url: Optional[str] = None,
296        host: Optional[str] = None,
297        timeout: Optional[int] = None,
298        httpx_client: Optional[httpx.Client] = None,
299        debug: bool = False,
300        tracing_enabled: Optional[bool] = True,
301        flush_at: Optional[int] = None,
302        flush_interval: Optional[float] = None,
303        environment: Optional[str] = None,
304        release: Optional[str] = None,
305        media_upload_thread_count: Optional[int] = None,
306        sample_rate: Optional[float] = None,
307        mask: Optional[MaskFunction] = None,
308        mask_otel_spans: Optional[MaskOtelSpansFunction] = None,
309        blocked_instrumentation_scopes: Optional[List[str]] = None,
310        should_export_span: Optional[Callable[[ReadableSpan], bool]] = None,
311        additional_headers: Optional[Dict[str, str]] = None,
312        tracer_provider: Optional[TracerProvider] = None,
313        id_generator: Optional[IdGenerator] = None,
314        span_exporter: Optional[SpanExporter] = None,
315    ):
316        self._base_url = (
317            base_url
318            or os.environ.get(LANGFUSE_BASE_URL)
319            or host
320            or os.environ.get(LANGFUSE_HOST, "https://cloud.langfuse.com")
321        )
322        self._environment = environment or cast(
323            str, os.environ.get(LANGFUSE_TRACING_ENVIRONMENT)
324        )
325        self._release = (
326            release
327            or os.environ.get(LANGFUSE_RELEASE, None)
328            or get_common_release_envs()
329        )
330        self._project_id: Optional[str] = None
331        sample_rate = sample_rate or float(os.environ.get(LANGFUSE_SAMPLE_RATE, 1.0))
332        if not 0.0 <= sample_rate <= 1.0:
333            raise ValueError(
334                f"Sample rate must be between 0.0 and 1.0, got {sample_rate}"
335            )
336
337        timeout = timeout or int(os.environ.get(LANGFUSE_TIMEOUT, 5))
338
339        self._tracing_enabled = (
340            tracing_enabled
341            and os.environ.get(LANGFUSE_TRACING_ENABLED, "true").lower() != "false"
342        )
343        if not self._tracing_enabled:
344            langfuse_logger.info(
345                "Configuration: Langfuse tracing is explicitly disabled. No data will be sent to the Langfuse API."
346            )
347
348        debug = (
349            debug if debug else (os.getenv(LANGFUSE_DEBUG, "false").lower() == "true")
350        )
351        if debug:
352            logging.basicConfig(
353                format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
354            )
355            langfuse_logger.setLevel(logging.DEBUG)
356
357        public_key = public_key or os.environ.get(LANGFUSE_PUBLIC_KEY)
358        if public_key is None:
359            langfuse_logger.warning(
360                "Authentication error: Langfuse client initialized without public_key. Client will be disabled. "
361                "Provide a public_key parameter or set LANGFUSE_PUBLIC_KEY environment variable. "
362            )
363            self._otel_tracer = otel_trace_api.NoOpTracer()
364            return
365
366        secret_key = secret_key or os.environ.get(LANGFUSE_SECRET_KEY)
367        if secret_key is None:
368            langfuse_logger.warning(
369                "Authentication error: Langfuse client initialized without secret_key. Client will be disabled. "
370                "Provide a secret_key parameter or set LANGFUSE_SECRET_KEY environment variable. "
371            )
372            self._otel_tracer = otel_trace_api.NoOpTracer()
373            return
374
375        if os.environ.get("OTEL_SDK_DISABLED", "false").lower() == "true":
376            langfuse_logger.warning(
377                "OTEL_SDK_DISABLED is set. Langfuse tracing will be disabled and no traces will appear in the UI."
378            )
379
380        if blocked_instrumentation_scopes is not None:
381            warnings.warn(
382                "`blocked_instrumentation_scopes` is deprecated and will be removed in a future release. "
383                "Use `should_export_span` instead. Example: "
384                "from langfuse.span_filter import is_default_export_span; "
385                'blocked={"scope"}; should_export_span=lambda span: '
386                "is_default_export_span(span) and (span.instrumentation_scope is None or "
387                "span.instrumentation_scope.name not in blocked).",
388                DeprecationWarning,
389                stacklevel=2,
390            )
391
392        # Initialize api and tracer if requirements are met
393        self._resources = LangfuseResourceManager(
394            public_key=public_key,
395            secret_key=secret_key,
396            base_url=self._base_url,
397            timeout=timeout,
398            environment=self._environment,
399            release=release,
400            flush_at=flush_at,
401            flush_interval=flush_interval,
402            httpx_client=httpx_client,
403            media_upload_thread_count=media_upload_thread_count,
404            sample_rate=sample_rate,
405            mask=mask,
406            mask_otel_spans=mask_otel_spans,
407            tracing_enabled=self._tracing_enabled,
408            blocked_instrumentation_scopes=blocked_instrumentation_scopes,
409            should_export_span=should_export_span,
410            additional_headers=additional_headers,
411            tracer_provider=tracer_provider,
412            id_generator=id_generator,
413            span_exporter=span_exporter,
414        )
415        self._mask = self._resources.mask
416
417        self._otel_tracer = (
418            self._resources.tracer
419            if self._tracing_enabled and self._resources.tracer is not None
420            else otel_trace_api.NoOpTracer()
421        )
api: langfuse.api.LangfuseAPI 
423    @property
424    def api(self) -> LangfuseAPI:
425        """Synchronous client for the full Langfuse REST API (traces, observations, scores, datasets, prompts, ...).
426
427        Use this to read or manage data on the Langfuse server; use the tracing methods
428        (`start_observation`, `@observe`) to create traces. Use `async_api` for the
429        asyncio variant.
430
431        Semantics that are easy to miss:
432
433        - **Ingestion is asynchronous.** `langfuse.flush()` only guarantees delivery to
434          the API, not read visibility: reads such as `api.trace.get(trace_id)` may
435          raise `langfuse.api.NotFoundError` until processing completes (typically
436          within 15-30 seconds; longer under load). The same applies to scores and
437          dataset run reads. Instead of a fixed sleep, retry with a deadline:
438
439        - **List endpoints return lightweight views.** `api.trace.list(...)` returns
440          `TraceWithDetails`, where `observations` and `scores` are lists of ID strings.
441          Fetch the full objects with `api.trace.get(trace_id)` (`TraceWithFullDetails`),
442          or prefer `api.observations.get_many(trace_id=...)` for row-level observation
443          queries. The same list-view vs. get-detail pattern applies to other resources.
444
445        - **Prefer the v2 data APIs — they are the defaults since SDK v4.**
446          `api.observations` and `api.metrics` map to the high-performance
447          `/api/public/v2/...` endpoints and are the recommended read path. Their v1
448          equivalents remain available under `api.legacy.observations_v1` /
449          `api.legacy.metrics_v1` but are less performant at scale, not recommended
450          for new workflows, and will be deprecated.
451
452        - For large-scale aggregation (usage/cost by model, user, etc.), prefer the
453        v2 Metrics API (`api.metrics.metrics(...)`) over paginating row-level data.
454
455
456        See also: `async_api`,
457        https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk
458        (ingestion lag: #ingestion-lag, list vs. get: #traces-list-vs-get),
459        https://langfuse.com/docs/api-and-data-platform/features/observations-api,
460        https://langfuse.com/docs/metrics/features/metrics-api
461        """
462        if self._resources is None:
463            raise AttributeError("Langfuse client is not initialized")
464
465        return self._resources.api

Synchronous client for the full Langfuse REST API (traces, observations, scores, datasets, prompts, ...).

Use this to read or manage data on the Langfuse server; use the tracing methods (start_observation, @observe) to create traces. Use async_api for the asyncio variant.

Semantics that are easy to miss:

  • Ingestion is asynchronous. langfuse.flush() only guarantees delivery to the API, not read visibility: reads such as api.trace.get(trace_id) may raise langfuse.api.NotFoundError until processing completes (typically within 15-30 seconds; longer under load). The same applies to scores and dataset run reads. Instead of a fixed sleep, retry with a deadline:

  • List endpoints return lightweight views. api.trace.list(...) returns TraceWithDetails, where observations and scores are lists of ID strings. Fetch the full objects with api.trace.get(trace_id) (TraceWithFullDetails), or prefer api.observations.get_many(trace_id=...) for row-level observation queries. The same list-view vs. get-detail pattern applies to other resources.

  • Prefer the v2 data APIs — they are the defaults since SDK v4. api.observations and api.metrics map to the high-performance /api/public/v2/... endpoints and are the recommended read path. Their v1 equivalents remain available under api.legacy.observations_v1 / api.legacy.metrics_v1 but are less performant at scale, not recommended for new workflows, and will be deprecated.

  • For large-scale aggregation (usage/cost by model, user, etc.), prefer the v2 Metrics API (api.metrics.metrics(...)) over paginating row-level data.

See also: async_api, https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk (ingestion lag: #ingestion-lag, list vs. get: #traces-list-vs-get), https://langfuse.com/docs/api-and-data-platform/features/observations-api, https://langfuse.com/docs/metrics/features/metrics-api

async_api: langfuse.api.AsyncLangfuseAPI 
474    @property
475    def async_api(self) -> AsyncLangfuseAPI:
476        if self._resources is None:
477            raise AttributeError("Langfuse client is not initialized")
478
479        return self._resources.async_api
def start_observation( self, *, trace_context: Optional[langfuse.types.TraceContext] = None, name: str, as_type: Union[Literal['generation', 'embedding'], Literal['span', 'agent', 'tool', 'chain', 'retriever', 'evaluator', 'guardrail']] = 'span', input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None, completion_start_time: Optional[datetime.datetime] = None, model: Optional[str] = None, model_parameters: Optional[Dict[str, Union[str, NoneType, int, float, bool, List[str]]]] = None, usage_details: Optional[Dict[str, int]] = None, cost_details: Optional[Dict[str, float]] = None, prompt: Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient, NoneType] = None) -> Union[LangfuseSpan, LangfuseGeneration, LangfuseAgent, LangfuseTool, LangfuseChain, LangfuseRetriever, LangfuseEvaluator, LangfuseEmbedding, LangfuseGuardrail]: 
635    def start_observation(
636        self,
637        *,
638        trace_context: Optional[TraceContext] = None,
639        name: str,
640        as_type: ObservationTypeLiteralNoEvent = "span",
641        input: Optional[Any] = None,
642        output: Optional[Any] = None,
643        metadata: Optional[Any] = None,
644        version: Optional[str] = None,
645        level: Optional[SpanLevel] = None,
646        status_message: Optional[str] = None,
647        completion_start_time: Optional[datetime] = None,
648        model: Optional[str] = None,
649        model_parameters: Optional[Dict[str, MapValue]] = None,
650        usage_details: Optional[Dict[str, int]] = None,
651        cost_details: Optional[Dict[str, float]] = None,
652        prompt: Optional[PromptClient] = None,
653    ) -> Union[
654        LangfuseSpan,
655        LangfuseGeneration,
656        LangfuseAgent,
657        LangfuseTool,
658        LangfuseChain,
659        LangfuseRetriever,
660        LangfuseEvaluator,
661        LangfuseEmbedding,
662        LangfuseGuardrail,
663    ]:
664        """Create a new observation of the specified type.
665
666        This method creates a new observation but does not set it as the current span in the
667        context. To create and use an observation within a context, use start_as_current_observation().
668
669        Args:
670            trace_context: Optional context for connecting to an existing trace
671            name: Name of the observation
672            as_type: Type of observation to create (defaults to "span")
673            input: Input data for the operation
674            output: Output data from the operation
675            metadata: Additional metadata to associate with the observation
676            version: Version identifier for the code or component
677            level: Importance level of the observation
678            status_message: Optional status message for the observation
679            completion_start_time: When the model started generating (for generation types)
680            model: Name/identifier of the AI model used (for generation types)
681            model_parameters: Parameters used for the model (for generation types)
682            usage_details: Token usage information (for generation types)
683            cost_details: Cost information (for generation types)
684            prompt: Associated prompt template (for generation types)
685
686        Returns:
687            An observation object of the appropriate type that must be ended with .end()
688        """
689        if trace_context:
690            trace_id = trace_context.get("trace_id", None)
691            parent_span_id = trace_context.get("parent_span_id", None)
692
693            if trace_id:
694                remote_parent_span = self._create_remote_parent_span(
695                    trace_id=trace_id, parent_span_id=parent_span_id
696                )
697
698                with otel_trace_api.use_span(
699                    cast(otel_trace_api.Span, remote_parent_span)
700                ):
701                    otel_span = self._otel_tracer.start_span(name=name)
702                    otel_span.set_attribute(LangfuseOtelSpanAttributes.AS_ROOT, True)
703
704                    return self._create_observation_from_otel_span(
705                        otel_span=otel_span,
706                        as_type=as_type,
707                        input=input,
708                        output=output,
709                        metadata=metadata,
710                        version=version,
711                        level=level,
712                        status_message=status_message,
713                        completion_start_time=completion_start_time,
714                        model=model,
715                        model_parameters=model_parameters,
716                        usage_details=usage_details,
717                        cost_details=cost_details,
718                        prompt=prompt,
719                    )
720
721        otel_span = self._otel_tracer.start_span(name=name)
722
723        return self._create_observation_from_otel_span(
724            otel_span=otel_span,
725            as_type=as_type,
726            input=input,
727            output=output,
728            metadata=metadata,
729            version=version,
730            level=level,
731            status_message=status_message,
732            completion_start_time=completion_start_time,
733            model=model,
734            model_parameters=model_parameters,
735            usage_details=usage_details,
736            cost_details=cost_details,
737            prompt=prompt,
738        )

Create a new observation of the specified type.

This method creates a new observation but does not set it as the current span in the context. To create and use an observation within a context, use start_as_current_observation().

Arguments:
  • trace_context: Optional context for connecting to an existing trace
  • name: Name of the observation
  • as_type: Type of observation to create (defaults to "span")
  • input: Input data for the operation
  • output: Output data from the operation
  • metadata: Additional metadata to associate with the observation
  • version: Version identifier for the code or component
  • level: Importance level of the observation
  • status_message: Optional status message for the observation
  • completion_start_time: When the model started generating (for generation types)
  • model: Name/identifier of the AI model used (for generation types)
  • model_parameters: Parameters used for the model (for generation types)
  • usage_details: Token usage information (for generation types)
  • cost_details: Cost information (for generation types)
  • prompt: Associated prompt template (for generation types)
Returns:

An observation object of the appropriate type that must be ended with .end()

def start_as_current_observation( self, *, trace_context: Optional[langfuse.types.TraceContext] = None, name: str, as_type: Union[Literal['generation', 'embedding'], Literal['span', 'agent', 'tool', 'chain', 'retriever', 'evaluator', 'guardrail']] = 'span', input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None, completion_start_time: Optional[datetime.datetime] = None, model: Optional[str] = None, model_parameters: Optional[Dict[str, Union[str, NoneType, int, float, bool, List[str]]]] = None, usage_details: Optional[Dict[str, int]] = None, cost_details: Optional[Dict[str, float]] = None, prompt: Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient, NoneType] = None, end_on_exit: Optional[bool] = None) -> Union[opentelemetry.util._decorator._AgnosticContextManager[LangfuseGeneration], opentelemetry.util._decorator._AgnosticContextManager[LangfuseSpan], opentelemetry.util._decorator._AgnosticContextManager[LangfuseAgent], opentelemetry.util._decorator._AgnosticContextManager[LangfuseTool], opentelemetry.util._decorator._AgnosticContextManager[LangfuseChain], opentelemetry.util._decorator._AgnosticContextManager[LangfuseRetriever], opentelemetry.util._decorator._AgnosticContextManager[LangfuseEvaluator], opentelemetry.util._decorator._AgnosticContextManager[LangfuseEmbedding], opentelemetry.util._decorator._AgnosticContextManager[LangfuseGuardrail]]: 
 968    def start_as_current_observation(
 969        self,
 970        *,
 971        trace_context: Optional[TraceContext] = None,
 972        name: str,
 973        as_type: ObservationTypeLiteralNoEvent = "span",
 974        input: Optional[Any] = None,
 975        output: Optional[Any] = None,
 976        metadata: Optional[Any] = None,
 977        version: Optional[str] = None,
 978        level: Optional[SpanLevel] = None,
 979        status_message: Optional[str] = None,
 980        completion_start_time: Optional[datetime] = None,
 981        model: Optional[str] = None,
 982        model_parameters: Optional[Dict[str, MapValue]] = None,
 983        usage_details: Optional[Dict[str, int]] = None,
 984        cost_details: Optional[Dict[str, float]] = None,
 985        prompt: Optional[PromptClient] = None,
 986        end_on_exit: Optional[bool] = None,
 987    ) -> Union[
 988        _AgnosticContextManager[LangfuseGeneration],
 989        _AgnosticContextManager[LangfuseSpan],
 990        _AgnosticContextManager[LangfuseAgent],
 991        _AgnosticContextManager[LangfuseTool],
 992        _AgnosticContextManager[LangfuseChain],
 993        _AgnosticContextManager[LangfuseRetriever],
 994        _AgnosticContextManager[LangfuseEvaluator],
 995        _AgnosticContextManager[LangfuseEmbedding],
 996        _AgnosticContextManager[LangfuseGuardrail],
 997    ]:
 998        """Create a new observation and set it as the current span in a context manager.
 999
1000        This method creates a new observation of the specified type and sets it as the
1001        current span within a context manager. Use this method with a 'with' statement to
1002        automatically handle the observation lifecycle within a code block.
1003
1004        The created observation will be the child of the current span in the context.
1005
1006        Args:
1007            trace_context: Optional context for connecting to an existing trace
1008            name: Name of the observation (e.g., function or operation name)
1009            as_type: Type of observation to create (defaults to "span")
1010            input: Input data for the operation (can be any JSON-serializable object)
1011            output: Output data from the operation (can be any JSON-serializable object)
1012            metadata: Additional metadata to associate with the observation
1013            version: Version identifier for the code or component
1014            level: Importance level of the observation (info, warning, error)
1015            status_message: Optional status message for the observation
1016            end_on_exit (default: True): Whether to end the span automatically when leaving the context manager. If False, the span must be manually ended to avoid memory leaks.
1017
1018            The following parameters are available when as_type is: "generation" or "embedding".
1019            completion_start_time: When the model started generating the response
1020            model: Name/identifier of the AI model used (e.g., "gpt-4")
1021            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1022            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1023            cost_details: Cost information for the model call
1024            prompt: Associated prompt template from Langfuse prompt management
1025
1026        Returns:
1027            A context manager that yields the appropriate observation type based on as_type
1028
1029        Example:
1030            ```python
1031            # Create a span
1032            with langfuse.start_as_current_observation(name="process-query", as_type="span") as span:
1033                # Do work
1034                result = process_data()
1035                span.update(output=result)
1036
1037                # Create a child span automatically
1038                with span.start_as_current_observation(name="sub-operation") as child_span:
1039                    # Do sub-operation work
1040                    child_span.update(output="sub-result")
1041
1042            # Create a tool observation
1043            with langfuse.start_as_current_observation(name="web-search", as_type="tool") as tool:
1044                # Do tool work
1045                results = search_web(query)
1046                tool.update(output=results)
1047
1048            # Create a generation observation
1049            with langfuse.start_as_current_observation(
1050                name="answer-generation",
1051                as_type="generation",
1052                model="gpt-4"
1053            ) as generation:
1054                # Generate answer
1055                response = llm.generate(...)
1056                generation.update(output=response)
1057            ```
1058        """
1059        if as_type in get_observation_types_list(ObservationTypeGenerationLike):
1060            if trace_context:
1061                trace_id = trace_context.get("trace_id", None)
1062                parent_span_id = trace_context.get("parent_span_id", None)
1063
1064                if trace_id:
1065                    remote_parent_span = self._create_remote_parent_span(
1066                        trace_id=trace_id, parent_span_id=parent_span_id
1067                    )
1068
1069                    return cast(
1070                        Union[
1071                            _AgnosticContextManager[LangfuseGeneration],
1072                            _AgnosticContextManager[LangfuseEmbedding],
1073                        ],
1074                        self._create_span_with_parent_context(
1075                            as_type=as_type,
1076                            name=name,
1077                            remote_parent_span=remote_parent_span,
1078                            parent=None,
1079                            end_on_exit=end_on_exit,
1080                            input=input,
1081                            output=output,
1082                            metadata=metadata,
1083                            version=version,
1084                            level=level,
1085                            status_message=status_message,
1086                            completion_start_time=completion_start_time,
1087                            model=model,
1088                            model_parameters=model_parameters,
1089                            usage_details=usage_details,
1090                            cost_details=cost_details,
1091                            prompt=prompt,
1092                        ),
1093                    )
1094
1095            return cast(
1096                Union[
1097                    _AgnosticContextManager[LangfuseGeneration],
1098                    _AgnosticContextManager[LangfuseEmbedding],
1099                ],
1100                self._start_as_current_otel_span_with_processed_media(
1101                    as_type=as_type,
1102                    name=name,
1103                    end_on_exit=end_on_exit,
1104                    input=input,
1105                    output=output,
1106                    metadata=metadata,
1107                    version=version,
1108                    level=level,
1109                    status_message=status_message,
1110                    completion_start_time=completion_start_time,
1111                    model=model,
1112                    model_parameters=model_parameters,
1113                    usage_details=usage_details,
1114                    cost_details=cost_details,
1115                    prompt=prompt,
1116                ),
1117            )
1118
1119        if as_type in get_observation_types_list(ObservationTypeSpanLike):
1120            if trace_context:
1121                trace_id = trace_context.get("trace_id", None)
1122                parent_span_id = trace_context.get("parent_span_id", None)
1123
1124                if trace_id:
1125                    remote_parent_span = self._create_remote_parent_span(
1126                        trace_id=trace_id, parent_span_id=parent_span_id
1127                    )
1128
1129                    return cast(
1130                        Union[
1131                            _AgnosticContextManager[LangfuseSpan],
1132                            _AgnosticContextManager[LangfuseAgent],
1133                            _AgnosticContextManager[LangfuseTool],
1134                            _AgnosticContextManager[LangfuseChain],
1135                            _AgnosticContextManager[LangfuseRetriever],
1136                            _AgnosticContextManager[LangfuseEvaluator],
1137                            _AgnosticContextManager[LangfuseGuardrail],
1138                        ],
1139                        self._create_span_with_parent_context(
1140                            as_type=as_type,
1141                            name=name,
1142                            remote_parent_span=remote_parent_span,
1143                            parent=None,
1144                            end_on_exit=end_on_exit,
1145                            input=input,
1146                            output=output,
1147                            metadata=metadata,
1148                            version=version,
1149                            level=level,
1150                            status_message=status_message,
1151                        ),
1152                    )
1153
1154            return cast(
1155                Union[
1156                    _AgnosticContextManager[LangfuseSpan],
1157                    _AgnosticContextManager[LangfuseAgent],
1158                    _AgnosticContextManager[LangfuseTool],
1159                    _AgnosticContextManager[LangfuseChain],
1160                    _AgnosticContextManager[LangfuseRetriever],
1161                    _AgnosticContextManager[LangfuseEvaluator],
1162                    _AgnosticContextManager[LangfuseGuardrail],
1163                ],
1164                self._start_as_current_otel_span_with_processed_media(
1165                    as_type=as_type,
1166                    name=name,
1167                    end_on_exit=end_on_exit,
1168                    input=input,
1169                    output=output,
1170                    metadata=metadata,
1171                    version=version,
1172                    level=level,
1173                    status_message=status_message,
1174                ),
1175            )
1176
1177        # This should never be reached since all valid types are handled above
1178        langfuse_logger.warning(
1179            f"Unknown observation type: {as_type}, falling back to span"
1180        )
1181        return self._start_as_current_otel_span_with_processed_media(
1182            as_type="span",
1183            name=name,
1184            end_on_exit=end_on_exit,
1185            input=input,
1186            output=output,
1187            metadata=metadata,
1188            version=version,
1189            level=level,
1190            status_message=status_message,
1191        )

Create a new observation and set it as the current span in a context manager.

This method creates a new observation of the specified type and sets it as the current span within a context manager. Use this method with a 'with' statement to automatically handle the observation lifecycle within a code block.

The created observation will be the child of the current span in the context.

Arguments:
  • trace_context: Optional context for connecting to an existing trace
  • name: Name of the observation (e.g., function or operation name)
  • as_type: Type of observation to create (defaults to "span")
  • input: Input data for the operation (can be any JSON-serializable object)
  • output: Output data from the operation (can be any JSON-serializable object)
  • metadata: Additional metadata to associate with the observation
  • version: Version identifier for the code or component
  • level: Importance level of the observation (info, warning, error)
  • status_message: Optional status message for the observation
  • end_on_exit (default: True): Whether to end the span automatically when leaving the context manager. If False, the span must be manually ended to avoid memory leaks.
  • The following parameters are available when as_type is: "generation" or "embedding".
  • completion_start_time: When the model started generating the response
  • model: Name/identifier of the AI model used (e.g., "gpt-4")
  • model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
  • usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
  • cost_details: Cost information for the model call
  • prompt: Associated prompt template from Langfuse prompt management
Returns:

A context manager that yields the appropriate observation type based on as_type

Example:
# Create a span
with langfuse.start_as_current_observation(name="process-query", as_type="span") as span:
    # Do work
    result = process_data()
    span.update(output=result)

    # Create a child span automatically
    with span.start_as_current_observation(name="sub-operation") as child_span:
        # Do sub-operation work
        child_span.update(output="sub-result")

# Create a tool observation
with langfuse.start_as_current_observation(name="web-search", as_type="tool") as tool:
    # Do tool work
    results = search_web(query)
    tool.update(output=results)

# Create a generation observation
with langfuse.start_as_current_observation(
    name="answer-generation",
    as_type="generation",
    model="gpt-4"
) as generation:
    # Generate answer
    response = llm.generate(...)
    generation.update(output=response)
def update_current_generation( self, *, name: Optional[str] = None, input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None, completion_start_time: Optional[datetime.datetime] = None, model: Optional[str] = None, model_parameters: Optional[Dict[str, Union[str, NoneType, int, float, bool, List[str]]]] = None, usage_details: Optional[Dict[str, int]] = None, cost_details: Optional[Dict[str, float]] = None, prompt: Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient, NoneType] = None) -> None: 
1383    def update_current_generation(
1384        self,
1385        *,
1386        name: Optional[str] = None,
1387        input: Optional[Any] = None,
1388        output: Optional[Any] = None,
1389        metadata: Optional[Any] = None,
1390        version: Optional[str] = None,
1391        level: Optional[SpanLevel] = None,
1392        status_message: Optional[str] = None,
1393        completion_start_time: Optional[datetime] = None,
1394        model: Optional[str] = None,
1395        model_parameters: Optional[Dict[str, MapValue]] = None,
1396        usage_details: Optional[Dict[str, int]] = None,
1397        cost_details: Optional[Dict[str, float]] = None,
1398        prompt: Optional[PromptClient] = None,
1399    ) -> None:
1400        """Update the current active generation span with new information.
1401
1402        This method updates the current generation span in the active context with
1403        additional information. It's useful for adding output, usage stats, or other
1404        details that become available during or after model generation.
1405
1406        Args:
1407            name: The generation name
1408            input: Updated input data for the model
1409            output: Output from the model (e.g., completions)
1410            metadata: Additional metadata to associate with the generation
1411            version: Version identifier for the model or component
1412            level: Importance level of the generation (info, warning, error)
1413            status_message: Optional status message for the generation
1414            completion_start_time: When the model started generating the response
1415            model: Name/identifier of the AI model used (e.g., "gpt-4")
1416            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1417            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1418            cost_details: Cost information for the model call
1419            prompt: Associated prompt template from Langfuse prompt management
1420
1421        Example:
1422            ```python
1423            with langfuse.start_as_current_generation(name="answer-query") as generation:
1424                # Initial setup and API call
1425                response = llm.generate(...)
1426
1427                # Update with results that weren't available at creation time
1428                langfuse.update_current_generation(
1429                    output=response.text,
1430                    usage_details={
1431                        "prompt_tokens": response.usage.prompt_tokens,
1432                        "completion_tokens": response.usage.completion_tokens
1433                    }
1434                )
1435            ```
1436        """
1437        if not self._tracing_enabled:
1438            langfuse_logger.debug(
1439                "Operation skipped: update_current_generation - Tracing is disabled or client is in no-op mode."
1440            )
1441            return
1442
1443        current_otel_span = self._get_current_otel_span()
1444
1445        if current_otel_span is not None:
1446            generation = LangfuseGeneration(
1447                otel_span=current_otel_span, langfuse_client=self
1448            )
1449
1450            if name:
1451                current_otel_span.update_name(name)
1452
1453            generation.update(
1454                input=input,
1455                output=output,
1456                metadata=metadata,
1457                version=version,
1458                level=level,
1459                status_message=status_message,
1460                completion_start_time=completion_start_time,
1461                model=model,
1462                model_parameters=model_parameters,
1463                usage_details=usage_details,
1464                cost_details=cost_details,
1465                prompt=prompt,
1466            )

Update the current active generation span with new information.

This method updates the current generation span in the active context with additional information. It's useful for adding output, usage stats, or other details that become available during or after model generation.

Arguments:
  • name: The generation name
  • input: Updated input data for the model
  • output: Output from the model (e.g., completions)
  • metadata: Additional metadata to associate with the generation
  • version: Version identifier for the model or component
  • level: Importance level of the generation (info, warning, error)
  • status_message: Optional status message for the generation
  • completion_start_time: When the model started generating the response
  • model: Name/identifier of the AI model used (e.g., "gpt-4")
  • model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
  • usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
  • cost_details: Cost information for the model call
  • prompt: Associated prompt template from Langfuse prompt management
Example:
with langfuse.start_as_current_generation(name="answer-query") as generation:
    # Initial setup and API call
    response = llm.generate(...)

    # Update with results that weren't available at creation time
    langfuse.update_current_generation(
        output=response.text,
        usage_details={
            "prompt_tokens": response.usage.prompt_tokens,
            "completion_tokens": response.usage.completion_tokens
        }
    )
def update_current_span( self, *, name: Optional[str] = None, input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None) -> None: 
1468    def update_current_span(
1469        self,
1470        *,
1471        name: Optional[str] = None,
1472        input: Optional[Any] = None,
1473        output: Optional[Any] = None,
1474        metadata: Optional[Any] = None,
1475        version: Optional[str] = None,
1476        level: Optional[SpanLevel] = None,
1477        status_message: Optional[str] = None,
1478    ) -> None:
1479        """Update the current active span with new information.
1480
1481        This method updates the current span in the active context with
1482        additional information. It's useful for adding outputs or metadata
1483        that become available during execution.
1484
1485        Args:
1486            name: The span name
1487            input: Updated input data for the operation
1488            output: Output data from the operation
1489            metadata: Additional metadata to associate with the span
1490            version: Version identifier for the code or component
1491            level: Importance level of the span (info, warning, error)
1492            status_message: Optional status message for the span
1493
1494        Example:
1495            ```python
1496            with langfuse.start_as_current_observation(name="process-data") as span:
1497                # Initial processing
1498                result = process_first_part()
1499
1500                # Update with intermediate results
1501                langfuse.update_current_span(metadata={"intermediate_result": result})
1502
1503                # Continue processing
1504                final_result = process_second_part(result)
1505
1506                # Final update
1507                langfuse.update_current_span(output=final_result)
1508            ```
1509        """
1510        if not self._tracing_enabled:
1511            langfuse_logger.debug(
1512                "Operation skipped: update_current_span - Tracing is disabled or client is in no-op mode."
1513            )
1514            return
1515
1516        current_otel_span = self._get_current_otel_span()
1517
1518        if current_otel_span is not None:
1519            span_class = self._get_span_class(
1520                self._get_observation_type_from_otel_span(current_otel_span)
1521            )
1522            span = span_class(
1523                otel_span=current_otel_span,
1524                langfuse_client=self,
1525                environment=self._environment,
1526                release=self._release,
1527            )
1528
1529            if name:
1530                current_otel_span.update_name(name)
1531
1532            span.update(
1533                input=input,
1534                output=output,
1535                metadata=metadata,
1536                version=version,
1537                level=level,
1538                status_message=status_message,
1539            )

Update the current active span with new information.

This method updates the current span in the active context with additional information. It's useful for adding outputs or metadata that become available during execution.

Arguments:
  • name: The span name
  • input: Updated input data for the operation
  • output: Output data from the operation
  • metadata: Additional metadata to associate with the span
  • version: Version identifier for the code or component
  • level: Importance level of the span (info, warning, error)
  • status_message: Optional status message for the span
Example:
with langfuse.start_as_current_observation(name="process-data") as span:
    # Initial processing
    result = process_first_part()

    # Update with intermediate results
    langfuse.update_current_span(metadata={"intermediate_result": result})

    # Continue processing
    final_result = process_second_part(result)

    # Final update
    langfuse.update_current_span(output=final_result)
@deprecated('Trace-level input/output is deprecated. For trace attributes (user_id, session_id, tags, etc.), use propagate_attributes() instead. This method will be removed in a future major version.')
def set_current_trace_io( self, *, input: Optional[Any] = None, output: Optional[Any] = None) -> None: 
1541    @deprecated(
1542        "Trace-level input/output is deprecated. "
1543        "For trace attributes (user_id, session_id, tags, etc.), use propagate_attributes() instead. "
1544        "This method will be removed in a future major version."
1545    )
1546    def set_current_trace_io(
1547        self,
1548        *,
1549        input: Optional[Any] = None,
1550        output: Optional[Any] = None,
1551    ) -> None:
1552        """Set trace-level input and output for the current span's trace.
1553
1554        .. deprecated::
1555            This is a legacy method for backward compatibility with Langfuse platform
1556            features that still rely on trace-level input/output (e.g., legacy LLM-as-a-judge
1557            evaluators). It will be removed in a future major version.
1558
1559            For setting other trace attributes (user_id, session_id, metadata, tags, version),
1560            use :func:`langfuse.propagate_attributes` (top-level import) instead.
1561
1562        Args:
1563            input: Input data to associate with the trace.
1564            output: Output data to associate with the trace.
1565        """
1566        if not self._tracing_enabled:
1567            langfuse_logger.debug(
1568                "Operation skipped: set_current_trace_io - Tracing is disabled or client is in no-op mode."
1569            )
1570            return
1571
1572        current_otel_span = self._get_current_otel_span()
1573
1574        if current_otel_span is not None and current_otel_span.is_recording():
1575            span_class = self._get_span_class(
1576                self._get_observation_type_from_otel_span(current_otel_span)
1577            )
1578            span = span_class(
1579                otel_span=current_otel_span,
1580                langfuse_client=self,
1581                environment=self._environment,
1582                release=self._release,
1583            )
1584
1585            span.set_trace_io(
1586                input=input,
1587                output=output,
1588            )

Set trace-level input and output for the current span's trace.

Deprecated since version : This is a legacy method for backward compatibility with Langfuse platform features that still rely on trace-level input/output (e.g., legacy LLM-as-a-judge evaluators). It will be removed in a future major version.

For setting other trace attributes (user_id, session_id, metadata, tags, version), use langfuse.propagate_attributes() (top-level import) instead.

Arguments:
  • input: Input data to associate with the trace.
  • output: Output data to associate with the trace.
def set_current_trace_as_public(self) -> None: 
1590    def set_current_trace_as_public(self) -> None:
1591        """Make the current trace publicly accessible via its URL.
1592
1593        When a trace is published, anyone with the trace link can view the full trace
1594        without needing to be logged in to Langfuse. This action cannot be undone
1595        programmatically - once published, the entire trace becomes public.
1596
1597        This is a convenience method that publishes the trace from the currently
1598        active span context. Use this when you want to make a trace public from
1599        within a traced function without needing direct access to the span object.
1600        """
1601        if not self._tracing_enabled:
1602            langfuse_logger.debug(
1603                "Operation skipped: set_current_trace_as_public - Tracing is disabled or client is in no-op mode."
1604            )
1605            return
1606
1607        current_otel_span = self._get_current_otel_span()
1608
1609        if current_otel_span is not None and current_otel_span.is_recording():
1610            span_class = self._get_span_class(
1611                self._get_observation_type_from_otel_span(current_otel_span)
1612            )
1613            span = span_class(
1614                otel_span=current_otel_span,
1615                langfuse_client=self,
1616                environment=self._environment,
1617            )
1618
1619            span.set_trace_as_public()

Make the current trace publicly accessible via its URL.

When a trace is published, anyone with the trace link can view the full trace without needing to be logged in to Langfuse. This action cannot be undone programmatically - once published, the entire trace becomes public.

This is a convenience method that publishes the trace from the currently active span context. Use this when you want to make a trace public from within a traced function without needing direct access to the span object.

def create_event( self, *, trace_context: Optional[langfuse.types.TraceContext] = None, name: str, input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None) -> LangfuseEvent: 
1621    def create_event(
1622        self,
1623        *,
1624        trace_context: Optional[TraceContext] = None,
1625        name: str,
1626        input: Optional[Any] = None,
1627        output: Optional[Any] = None,
1628        metadata: Optional[Any] = None,
1629        version: Optional[str] = None,
1630        level: Optional[SpanLevel] = None,
1631        status_message: Optional[str] = None,
1632    ) -> LangfuseEvent:
1633        """Create a new Langfuse observation of type 'EVENT'.
1634
1635        The created Langfuse Event observation will be the child of the current span in the context.
1636
1637        Args:
1638            trace_context: Optional context for connecting to an existing trace
1639            name: Name of the span (e.g., function or operation name)
1640            input: Input data for the operation (can be any JSON-serializable object)
1641            output: Output data from the operation (can be any JSON-serializable object)
1642            metadata: Additional metadata to associate with the span
1643            version: Version identifier for the code or component
1644            level: Importance level of the span (info, warning, error)
1645            status_message: Optional status message for the span
1646
1647        Returns:
1648            The Langfuse Event object
1649
1650        Example:
1651            ```python
1652            event = langfuse.create_event(name="process-event")
1653            ```
1654        """
1655        timestamp = time_ns()
1656
1657        if trace_context:
1658            trace_id = trace_context.get("trace_id", None)
1659            parent_span_id = trace_context.get("parent_span_id", None)
1660
1661            if trace_id:
1662                remote_parent_span = self._create_remote_parent_span(
1663                    trace_id=trace_id, parent_span_id=parent_span_id
1664                )
1665
1666                with otel_trace_api.use_span(
1667                    cast(otel_trace_api.Span, remote_parent_span)
1668                ):
1669                    otel_span = self._otel_tracer.start_span(
1670                        name=name, start_time=timestamp
1671                    )
1672                    otel_span.set_attribute(LangfuseOtelSpanAttributes.AS_ROOT, True)
1673
1674                    return cast(
1675                        LangfuseEvent,
1676                        LangfuseEvent(
1677                            otel_span=otel_span,
1678                            langfuse_client=self,
1679                            environment=self._environment,
1680                            release=self._release,
1681                            input=input,
1682                            output=output,
1683                            metadata=metadata,
1684                            version=version,
1685                            level=level,
1686                            status_message=status_message,
1687                        ).end(end_time=timestamp),
1688                    )
1689
1690        otel_span = self._otel_tracer.start_span(name=name, start_time=timestamp)
1691
1692        return cast(
1693            LangfuseEvent,
1694            LangfuseEvent(
1695                otel_span=otel_span,
1696                langfuse_client=self,
1697                environment=self._environment,
1698                release=self._release,
1699                input=input,
1700                output=output,
1701                metadata=metadata,
1702                version=version,
1703                level=level,
1704                status_message=status_message,
1705            ).end(end_time=timestamp),
1706        )

Create a new Langfuse observation of type 'EVENT'.

The created Langfuse Event observation will be the child of the current span in the context.

Arguments:
  • trace_context: Optional context for connecting to an existing trace
  • name: Name of the span (e.g., function or operation name)
  • input: Input data for the operation (can be any JSON-serializable object)
  • output: Output data from the operation (can be any JSON-serializable object)
  • metadata: Additional metadata to associate with the span
  • version: Version identifier for the code or component
  • level: Importance level of the span (info, warning, error)
  • status_message: Optional status message for the span
Returns:

The Langfuse Event object

Example:
event = langfuse.create_event(name="process-event")
@staticmethod
def create_trace_id(*, seed: Optional[str] = None) -> str: 
1795    @staticmethod
1796    def create_trace_id(*, seed: Optional[str] = None) -> str:
1797        """Create a unique trace ID for use with Langfuse.
1798
1799        This method generates a unique trace ID for use with various Langfuse APIs.
1800        It can either generate a random ID or create a deterministic ID based on
1801        a seed string.
1802
1803        Trace IDs must be 32 lowercase hexadecimal characters, representing 16 bytes.
1804        This method ensures the generated ID meets this requirement. If you need to
1805        correlate an external ID with a Langfuse trace ID, use the external ID as the
1806        seed to get a valid, deterministic Langfuse trace ID.
1807
1808        Args:
1809            seed: Optional string to use as a seed for deterministic ID generation.
1810                 If provided, the same seed will always produce the same ID.
1811                 If not provided, a random ID will be generated.
1812
1813        Returns:
1814            A 32-character lowercase hexadecimal string representing the Langfuse trace ID.
1815
1816        Example:
1817            ```python
1818            # Generate a random trace ID
1819            trace_id = langfuse.create_trace_id()
1820
1821            # Generate a deterministic ID based on a seed
1822            session_trace_id = langfuse.create_trace_id(seed="session-456")
1823
1824            # Correlate an external ID with a Langfuse trace ID
1825            external_id = "external-system-123456"
1826            correlated_trace_id = langfuse.create_trace_id(seed=external_id)
1827
1828            # Use the ID with trace context
1829            with langfuse.start_as_current_observation(
1830                name="process-request",
1831                trace_context={"trace_id": trace_id}
1832            ) as span:
1833                # Operation will be part of the specific trace
1834                pass
1835            ```
1836        """
1837        if not seed:
1838            trace_id_int = RandomIdGenerator().generate_trace_id()
1839
1840            return Langfuse._format_otel_trace_id(trace_id_int)
1841
1842        return sha256(seed.encode("utf-8")).digest()[:16].hex()

Create a unique trace ID for use with Langfuse.

This method generates a unique trace ID for use with various Langfuse APIs. It can either generate a random ID or create a deterministic ID based on a seed string.

Trace IDs must be 32 lowercase hexadecimal characters, representing 16 bytes. This method ensures the generated ID meets this requirement. If you need to correlate an external ID with a Langfuse trace ID, use the external ID as the seed to get a valid, deterministic Langfuse trace ID.

Arguments:
  • seed: Optional string to use as a seed for deterministic ID generation. If provided, the same seed will always produce the same ID. If not provided, a random ID will be generated.
Returns:

A 32-character lowercase hexadecimal string representing the Langfuse trace ID.

Example:
# Generate a random trace ID
trace_id = langfuse.create_trace_id()

# Generate a deterministic ID based on a seed
session_trace_id = langfuse.create_trace_id(seed="session-456")

# Correlate an external ID with a Langfuse trace ID
external_id = "external-system-123456"
correlated_trace_id = langfuse.create_trace_id(seed=external_id)

# Use the ID with trace context
with langfuse.start_as_current_observation(
    name="process-request",
    trace_context={"trace_id": trace_id}
) as span:
    # Operation will be part of the specific trace
    pass
def create_score( self, *, name: str, value: Union[float, str], session_id: Optional[str] = None, dataset_run_id: Optional[str] = None, trace_id: Optional[str] = None, observation_id: Optional[str] = None, score_id: Optional[str] = None, data_type: Optional[Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN', 'TEXT', 'CORRECTION']] = None, comment: Optional[str] = None, config_id: Optional[str] = None, metadata: Optional[Any] = None, timestamp: Optional[datetime.datetime] = None, environment: Optional[str] = None) -> None: 
1924    def create_score(
1925        self,
1926        *,
1927        name: str,
1928        value: Union[float, str],
1929        session_id: Optional[str] = None,
1930        dataset_run_id: Optional[str] = None,
1931        trace_id: Optional[str] = None,
1932        observation_id: Optional[str] = None,
1933        score_id: Optional[str] = None,
1934        data_type: Optional[ScoreDataType] = None,
1935        comment: Optional[str] = None,
1936        config_id: Optional[str] = None,
1937        metadata: Optional[Any] = None,
1938        timestamp: Optional[datetime] = None,
1939        environment: Optional[str] = None,
1940    ) -> None:
1941        """Create a score for a specific trace or observation.
1942
1943        This method creates a score for evaluating a Langfuse trace or observation. Scores can be
1944        used to track quality metrics, user feedback, or automated evaluations.
1945
1946        Args:
1947            name: Name of the score (e.g., "relevance", "accuracy")
1948            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
1949            session_id: ID of the Langfuse session to associate the score with
1950            dataset_run_id: ID of the Langfuse dataset run to associate the score with
1951            trace_id: ID of the Langfuse trace to associate the score with
1952            observation_id: Optional ID of the specific observation to score. Trace ID must be provided too.
1953            score_id: Optional custom ID for the score (auto-generated if not provided)
1954            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
1955            comment: Optional comment or explanation for the score
1956            config_id: Optional ID of a score config defined in Langfuse
1957            metadata: Optional metadata to be attached to the score
1958            timestamp: Optional timestamp for the score (defaults to current UTC time)
1959            environment: Optional environment override for this score. If omitted,
1960                the score uses the client-level environment from
1961                `Langfuse(environment=...)` or `LANGFUSE_TRACING_ENVIRONMENT`.
1962                Langfuse observation wrapper methods pass their resolved span
1963                environment here so scores created via `span.score()` or
1964                `span.score_trace()` stay grouped with the scored observation or
1965                trace, including request-scoped environments propagated with
1966                `propagate_attributes(environment=...)`.
1967
1968        Example:
1969            ```python
1970            # Create a numeric score for accuracy
1971            langfuse.create_score(
1972                name="accuracy",
1973                value=0.92,
1974                trace_id="abcdef1234567890abcdef1234567890",
1975                data_type="NUMERIC",
1976                comment="High accuracy with minor irrelevant details"
1977            )
1978
1979            # Create a categorical score for sentiment
1980            langfuse.create_score(
1981                name="sentiment",
1982                value="positive",
1983                trace_id="abcdef1234567890abcdef1234567890",
1984                observation_id="abcdef1234567890",
1985                data_type="CATEGORICAL"
1986            )
1987            ```
1988        """
1989        if not self._tracing_enabled:
1990            return
1991
1992        score_id = score_id or self._create_observation_id()
1993
1994        try:
1995            new_body = ScoreBody(
1996                id=score_id,
1997                sessionId=session_id,
1998                datasetRunId=dataset_run_id,
1999                traceId=trace_id,
2000                observationId=observation_id,
2001                name=name,
2002                value=value,
2003                dataType=data_type,  # type: ignore
2004                comment=comment,
2005                configId=config_id,
2006                environment=environment or self._environment,
2007                metadata=metadata,
2008            )
2009
2010            event = {
2011                "id": self.create_trace_id(),
2012                "type": "score-create",
2013                "timestamp": timestamp or _get_timestamp(),
2014                "body": new_body,
2015            }
2016
2017            if self._resources is not None:
2018                # Force the score to be in sample if it was for a legacy trace ID, i.e. non-32 hexchar
2019                force_sample = (
2020                    not self._is_valid_trace_id(trace_id) if trace_id else True
2021                )
2022
2023                self._resources.add_score_task(
2024                    event,
2025                    force_sample=force_sample,
2026                )
2027
2028        except Exception as e:
2029            langfuse_logger.exception(
2030                f"Error creating score: Failed to process score event for trace_id={trace_id}, name={name}. Error: {e}"
2031            )

Create a score for a specific trace or observation.

This method creates a score for evaluating a Langfuse trace or observation. Scores can be used to track quality metrics, user feedback, or automated evaluations.

Arguments:
  • name: Name of the score (e.g., "relevance", "accuracy")
  • value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
  • session_id: ID of the Langfuse session to associate the score with
  • dataset_run_id: ID of the Langfuse dataset run to associate the score with
  • trace_id: ID of the Langfuse trace to associate the score with
  • observation_id: Optional ID of the specific observation to score. Trace ID must be provided too.
  • score_id: Optional custom ID for the score (auto-generated if not provided)
  • data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
  • comment: Optional comment or explanation for the score
  • config_id: Optional ID of a score config defined in Langfuse
  • metadata: Optional metadata to be attached to the score
  • timestamp: Optional timestamp for the score (defaults to current UTC time)
  • environment: Optional environment override for this score. If omitted, the score uses the client-level environment from Langfuse(environment=...) or LANGFUSE_TRACING_ENVIRONMENT. Langfuse observation wrapper methods pass their resolved span environment here so scores created via span.score() or span.score_trace() stay grouped with the scored observation or trace, including request-scoped environments propagated with propagate_attributes(environment=...).
Example:
# Create a numeric score for accuracy
langfuse.create_score(
    name="accuracy",
    value=0.92,
    trace_id="abcdef1234567890abcdef1234567890",
    data_type="NUMERIC",
    comment="High accuracy with minor irrelevant details"
)

# Create a categorical score for sentiment
langfuse.create_score(
    name="sentiment",
    value="positive",
    trace_id="abcdef1234567890abcdef1234567890",
    observation_id="abcdef1234567890",
    data_type="CATEGORICAL"
)
def score_current_span( self, *, name: str, value: Union[float, str], score_id: Optional[str] = None, data_type: Optional[Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN', 'TEXT', 'CORRECTION']] = None, comment: Optional[str] = None, config_id: Optional[str] = None, metadata: Optional[Any] = None) -> None: 
2094    def score_current_span(
2095        self,
2096        *,
2097        name: str,
2098        value: Union[float, str],
2099        score_id: Optional[str] = None,
2100        data_type: Optional[ScoreDataType] = None,
2101        comment: Optional[str] = None,
2102        config_id: Optional[str] = None,
2103        metadata: Optional[Any] = None,
2104    ) -> None:
2105        """Create a score for the current active span.
2106
2107        This method scores the currently active span in the context. It's a convenient
2108        way to score the current operation without needing to know its trace and span IDs.
2109        If the active span has a `langfuse.environment` attribute, including one
2110        set by `propagate_attributes(environment=...)`, the score uses that
2111        environment. Otherwise it uses the client-level environment.
2112
2113        Args:
2114            name: Name of the score (e.g., "relevance", "accuracy")
2115            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
2116            score_id: Optional custom ID for the score (auto-generated if not provided)
2117            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
2118            comment: Optional comment or explanation for the score
2119            config_id: Optional ID of a score config defined in Langfuse
2120            metadata: Optional metadata to be attached to the score
2121
2122        Example:
2123            ```python
2124            with langfuse.start_as_current_generation(name="answer-query") as generation:
2125                # Generate answer
2126                response = generate_answer(...)
2127                generation.update(output=response)
2128
2129                # Score the generation
2130                langfuse.score_current_span(
2131                    name="relevance",
2132                    value=0.85,
2133                    data_type="NUMERIC",
2134                    comment="Mostly relevant but contains some tangential information",
2135                    metadata={"model": "gpt-4", "prompt_version": "v2"}
2136                )
2137            ```
2138        """
2139        current_span = self._get_current_otel_span()
2140
2141        if current_span is not None:
2142            trace_id = self._get_otel_trace_id(current_span)
2143            observation_id = self._get_otel_span_id(current_span)
2144
2145            langfuse_logger.info(
2146                f"Score: Creating score name='{name}' value={value} for current span ({observation_id}) in trace {trace_id}"
2147            )
2148
2149            self.create_score(
2150                trace_id=trace_id,
2151                observation_id=observation_id,
2152                name=name,
2153                value=cast(str, value),
2154                score_id=score_id,
2155                data_type=cast(Literal["CATEGORICAL", "TEXT", "CORRECTION"], data_type),
2156                comment=comment,
2157                config_id=config_id,
2158                metadata=metadata,
2159                environment=get_string_span_attribute(
2160                    current_span, LangfuseOtelSpanAttributes.ENVIRONMENT
2161                ),
2162            )

Create a score for the current active span.

This method scores the currently active span in the context. It's a convenient way to score the current operation without needing to know its trace and span IDs. If the active span has a langfuse.environment attribute, including one set by propagate_attributes(environment=...), the score uses that environment. Otherwise it uses the client-level environment.

Arguments:
  • name: Name of the score (e.g., "relevance", "accuracy")
  • value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
  • score_id: Optional custom ID for the score (auto-generated if not provided)
  • data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
  • comment: Optional comment or explanation for the score
  • config_id: Optional ID of a score config defined in Langfuse
  • metadata: Optional metadata to be attached to the score
Example:
with langfuse.start_as_current_generation(name="answer-query") as generation:
    # Generate answer
    response = generate_answer(...)
    generation.update(output=response)

    # Score the generation
    langfuse.score_current_span(
        name="relevance",
        value=0.85,
        data_type="NUMERIC",
        comment="Mostly relevant but contains some tangential information",
        metadata={"model": "gpt-4", "prompt_version": "v2"}
    )
def score_current_trace( self, *, name: str, value: Union[float, str], score_id: Optional[str] = None, data_type: Optional[Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN', 'TEXT', 'CORRECTION']] = None, comment: Optional[str] = None, config_id: Optional[str] = None, metadata: Optional[Any] = None) -> None: 
2192    def score_current_trace(
2193        self,
2194        *,
2195        name: str,
2196        value: Union[float, str],
2197        score_id: Optional[str] = None,
2198        data_type: Optional[ScoreDataType] = None,
2199        comment: Optional[str] = None,
2200        config_id: Optional[str] = None,
2201        metadata: Optional[Any] = None,
2202    ) -> None:
2203        """Create a score for the current trace.
2204
2205        This method scores the trace of the currently active span. Unlike score_current_span,
2206        this method associates the score with the entire trace rather than a specific span.
2207        It's useful for scoring overall performance or quality of the entire operation.
2208        If the active span has a `langfuse.environment` attribute, including one
2209        set by `propagate_attributes(environment=...)`, the score uses that
2210        environment. Otherwise it uses the client-level environment.
2211
2212        Args:
2213            name: Name of the score (e.g., "user_satisfaction", "overall_quality")
2214            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
2215            score_id: Optional custom ID for the score (auto-generated if not provided)
2216            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
2217            comment: Optional comment or explanation for the score
2218            config_id: Optional ID of a score config defined in Langfuse
2219            metadata: Optional metadata to be attached to the score
2220
2221        Example:
2222            ```python
2223            with langfuse.start_as_current_observation(name="process-user-request") as span:
2224                # Process request
2225                result = process_complete_request()
2226                span.update(output=result)
2227
2228                # Score the overall trace
2229                langfuse.score_current_trace(
2230                    name="overall_quality",
2231                    value=0.95,
2232                    data_type="NUMERIC",
2233                    comment="High quality end-to-end response",
2234                    metadata={"evaluator": "gpt-4", "criteria": "comprehensive"}
2235                )
2236            ```
2237        """
2238        current_span = self._get_current_otel_span()
2239
2240        if current_span is not None:
2241            trace_id = self._get_otel_trace_id(current_span)
2242
2243            langfuse_logger.info(
2244                f"Score: Creating score name='{name}' value={value} for entire trace {trace_id}"
2245            )
2246
2247            self.create_score(
2248                trace_id=trace_id,
2249                name=name,
2250                value=cast(str, value),
2251                score_id=score_id,
2252                data_type=cast(Literal["CATEGORICAL", "TEXT", "CORRECTION"], data_type),
2253                comment=comment,
2254                config_id=config_id,
2255                metadata=metadata,
2256                environment=get_string_span_attribute(
2257                    current_span, LangfuseOtelSpanAttributes.ENVIRONMENT
2258                ),
2259            )

Create a score for the current trace.

This method scores the trace of the currently active span. Unlike score_current_span, this method associates the score with the entire trace rather than a specific span. It's useful for scoring overall performance or quality of the entire operation. If the active span has a langfuse.environment attribute, including one set by propagate_attributes(environment=...), the score uses that environment. Otherwise it uses the client-level environment.

Arguments:
  • name: Name of the score (e.g., "user_satisfaction", "overall_quality")
  • value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
  • score_id: Optional custom ID for the score (auto-generated if not provided)
  • data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
  • comment: Optional comment or explanation for the score
  • config_id: Optional ID of a score config defined in Langfuse
  • metadata: Optional metadata to be attached to the score
Example:
with langfuse.start_as_current_observation(name="process-user-request") as span:
    # Process request
    result = process_complete_request()
    span.update(output=result)

    # Score the overall trace
    langfuse.score_current_trace(
        name="overall_quality",
        value=0.95,
        data_type="NUMERIC",
        comment="High quality end-to-end response",
        metadata={"evaluator": "gpt-4", "criteria": "comprehensive"}
    )
def flush(self) -> None: 
2261    def flush(self) -> None:
2262        """Force flush all pending spans and events to the Langfuse API.
2263
2264        This method manually flushes any pending spans, scores, and other events to the
2265        Langfuse API. It's useful in scenarios where you want to ensure all data is sent
2266        before proceeding, without waiting for the automatic flush interval.
2267
2268        Example:
2269            ```python
2270            # Record some spans and scores
2271            with langfuse.start_as_current_observation(name="operation") as span:
2272                # Do work...
2273                pass
2274
2275            # Ensure all data is sent to Langfuse before proceeding
2276            langfuse.flush()
2277
2278            # Continue with other work
2279            ```
2280
2281        Note:
2282            `flush()` guarantees data was *delivered* to the API, not that it is
2283            *readable* yet: server-side ingestion is asynchronous, so flushed data
2284            may not be queryable for 15-30 seconds —
2285            `api.observations.get_many(trace_id=...)` may return empty results and
2286            `api.trace.get()` may raise `langfuse.api.NotFoundError` right after a
2287            successful flush. See the `api` property docs for a bounded retry
2288            pattern, or
2289            https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk#ingestion-lag
2290        """
2291        if self._resources is not None:
2292            self._resources.flush()

Force flush all pending spans and events to the Langfuse API.

This method manually flushes any pending spans, scores, and other events to the Langfuse API. It's useful in scenarios where you want to ensure all data is sent before proceeding, without waiting for the automatic flush interval.

Example:
# Record some spans and scores
with langfuse.start_as_current_observation(name="operation") as span:
    # Do work...
    pass

# Ensure all data is sent to Langfuse before proceeding
langfuse.flush()

# Continue with other work
Note:

flush() guarantees data was delivered to the API, not that it is readable yet: server-side ingestion is asynchronous, so flushed data may not be queryable for 15-30 seconds — api.observations.get_many(trace_id=...) may return empty results and api.trace.get() may raise langfuse.api.NotFoundError right after a successful flush. See the api property docs for a bounded retry pattern, or https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk#ingestion-lag

def shutdown(self) -> None: 
2294    def shutdown(self) -> None:
2295        """Shut down the Langfuse client and flush all pending data.
2296
2297        This method cleanly shuts down the Langfuse client, ensuring all pending data
2298        is flushed to the API and all background threads are properly terminated.
2299
2300        It's important to call this method when your application is shutting down to
2301        prevent data loss and resource leaks. For most applications, using the client
2302        as a context manager or relying on the automatic shutdown via atexit is sufficient.
2303
2304        Example:
2305            ```python
2306            # Initialize Langfuse
2307            langfuse = Langfuse(public_key="...", secret_key="...")
2308
2309            # Use Langfuse throughout your application
2310            # ...
2311
2312            # When application is shutting down
2313            langfuse.shutdown()
2314            ```
2315        """
2316        if self._resources is not None:
2317            self._resources.shutdown()

Shut down the Langfuse client and flush all pending data.

This method cleanly shuts down the Langfuse client, ensuring all pending data is flushed to the API and all background threads are properly terminated.

It's important to call this method when your application is shutting down to prevent data loss and resource leaks. For most applications, using the client as a context manager or relying on the automatic shutdown via atexit is sufficient.

Example:
# Initialize Langfuse
langfuse = Langfuse(public_key="...", secret_key="...")

# Use Langfuse throughout your application
# ...

# When application is shutting down
langfuse.shutdown()
def get_current_trace_id(self) -> Optional[str]: 
2319    def get_current_trace_id(self) -> Optional[str]:
2320        """Get the trace ID of the current active span.
2321
2322        This method retrieves the trace ID from the currently active span in the context.
2323        It can be used to get the trace ID for referencing in logs, external systems,
2324        or for creating related operations.
2325
2326        Returns:
2327            The current trace ID as a 32-character lowercase hexadecimal string,
2328            or None if there is no active span.
2329
2330        Example:
2331            ```python
2332            with langfuse.start_as_current_observation(name="process-request") as span:
2333                # Get the current trace ID for reference
2334                trace_id = langfuse.get_current_trace_id()
2335
2336                # Use it for external correlation
2337                log.info(f"Processing request with trace_id: {trace_id}")
2338
2339                # Or pass to another system
2340                external_system.process(data, trace_id=trace_id)
2341            ```
2342        """
2343        if not self._tracing_enabled:
2344            langfuse_logger.debug(
2345                "Operation skipped: get_current_trace_id - Tracing is disabled or client is in no-op mode."
2346            )
2347            return None
2348
2349        current_otel_span = self._get_current_otel_span()
2350
2351        return self._get_otel_trace_id(current_otel_span) if current_otel_span else None

Get the trace ID of the current active span.

This method retrieves the trace ID from the currently active span in the context. It can be used to get the trace ID for referencing in logs, external systems, or for creating related operations.

Returns:

The current trace ID as a 32-character lowercase hexadecimal string, or None if there is no active span.

Example:
with langfuse.start_as_current_observation(name="process-request") as span:
    # Get the current trace ID for reference
    trace_id = langfuse.get_current_trace_id()

    # Use it for external correlation
    log.info(f"Processing request with trace_id: {trace_id}")

    # Or pass to another system
    external_system.process(data, trace_id=trace_id)
def get_current_observation_id(self) -> Optional[str]: 
2353    def get_current_observation_id(self) -> Optional[str]:
2354        """Get the observation ID (span ID) of the current active span.
2355
2356        This method retrieves the observation ID from the currently active span in the context.
2357        It can be used to get the observation ID for referencing in logs, external systems,
2358        or for creating scores or other related operations.
2359
2360        Returns:
2361            The current observation ID as a 16-character lowercase hexadecimal string,
2362            or None if there is no active span.
2363
2364        Example:
2365            ```python
2366            with langfuse.start_as_current_observation(name="process-user-query") as span:
2367                # Get the current observation ID
2368                observation_id = langfuse.get_current_observation_id()
2369
2370                # Store it for later reference
2371                cache.set(f"query_{query_id}_observation", observation_id)
2372
2373                # Process the query...
2374            ```
2375        """
2376        if not self._tracing_enabled:
2377            langfuse_logger.debug(
2378                "Operation skipped: get_current_observation_id - Tracing is disabled or client is in no-op mode."
2379            )
2380            return None
2381
2382        current_otel_span = self._get_current_otel_span()
2383
2384        return self._get_otel_span_id(current_otel_span) if current_otel_span else None

Get the observation ID (span ID) of the current active span.

This method retrieves the observation ID from the currently active span in the context. It can be used to get the observation ID for referencing in logs, external systems, or for creating scores or other related operations.

Returns:

The current observation ID as a 16-character lowercase hexadecimal string, or None if there is no active span.

Example:
with langfuse.start_as_current_observation(name="process-user-query") as span:
    # Get the current observation ID
    observation_id = langfuse.get_current_observation_id()

    # Store it for later reference
    cache.set(f"query_{query_id}_observation", observation_id)

    # Process the query...
def get_trace_url(self, *, trace_id: Optional[str] = None) -> Optional[str]: 
2397    def get_trace_url(self, *, trace_id: Optional[str] = None) -> Optional[str]:
2398        """Get the URL to view a trace in the Langfuse UI.
2399
2400        This method generates a URL that links directly to a trace in the Langfuse UI.
2401        It's useful for providing links in logs, notifications, or debugging tools.
2402
2403        Args:
2404            trace_id: Optional trace ID to generate a URL for. If not provided,
2405                     the trace ID of the current active span will be used.
2406
2407        Returns:
2408            A URL string pointing to the trace in the Langfuse UI,
2409            or None if the project ID couldn't be retrieved or no trace ID is available.
2410
2411        Example:
2412            ```python
2413            # Get URL for the current trace
2414            with langfuse.start_as_current_observation(name="process-request") as span:
2415                trace_url = langfuse.get_trace_url()
2416                log.info(f"Processing trace: {trace_url}")
2417
2418            # Get URL for a specific trace
2419            specific_trace_url = langfuse.get_trace_url(trace_id="1234567890abcdef1234567890abcdef")
2420            send_notification(f"Review needed for trace: {specific_trace_url}")
2421            ```
2422        """
2423        final_trace_id = trace_id or self.get_current_trace_id()
2424        if not final_trace_id:
2425            return None
2426
2427        project_id = self._get_project_id()
2428
2429        return (
2430            f"{self._base_url}/project/{project_id}/traces/{final_trace_id}"
2431            if project_id and final_trace_id
2432            else None
2433        )

Get the URL to view a trace in the Langfuse UI.

This method generates a URL that links directly to a trace in the Langfuse UI. It's useful for providing links in logs, notifications, or debugging tools.

Arguments:
  • trace_id: Optional trace ID to generate a URL for. If not provided, the trace ID of the current active span will be used.
Returns:

A URL string pointing to the trace in the Langfuse UI, or None if the project ID couldn't be retrieved or no trace ID is available.

Example:
# Get URL for the current trace
with langfuse.start_as_current_observation(name="process-request") as span:
    trace_url = langfuse.get_trace_url()
    log.info(f"Processing trace: {trace_url}")

# Get URL for a specific trace
specific_trace_url = langfuse.get_trace_url(trace_id="1234567890abcdef1234567890abcdef")
send_notification(f"Review needed for trace: {specific_trace_url}")
def get_dataset( self, name: str, *, fetch_items_page_size: Optional[int] = 50, version: Optional[datetime.datetime] = None) -> langfuse._client.datasets.DatasetClient: 
2435    def get_dataset(
2436        self,
2437        name: str,
2438        *,
2439        fetch_items_page_size: Optional[int] = 50,
2440        version: Optional[datetime] = None,
2441    ) -> "DatasetClient":
2442        """Fetch a dataset by its name.
2443
2444        Args:
2445            name: The name of the dataset to fetch.
2446            fetch_items_page_size: All items of the dataset will be fetched in chunks of this size. Defaults to 50.
2447            version: Retrieve dataset items as they existed at this specific point in time (UTC).
2448                If provided, returns the state of items at the specified UTC timestamp.
2449                If not provided, returns the latest version. Must be a timezone-aware datetime object in UTC.
2450
2451        Returns:
2452            DatasetClient: The dataset with the given name.
2453        """
2454        try:
2455            langfuse_logger.debug(f"Getting datasets {name}")
2456            dataset = self.api.datasets.get(dataset_name=self._url_encode(name))
2457
2458            dataset_items: List[DatasetItem] = []
2459            page = 1
2460
2461            while True:
2462                new_items = self.api.dataset_items.list(
2463                    dataset_name=self._url_encode(name, is_url_param=True),
2464                    page=page,
2465                    limit=fetch_items_page_size,
2466                    version=version,
2467                )
2468                dataset_items.extend(
2469                    self._hydrate_dataset_item_media_references(item)
2470                    for item in new_items.data
2471                )
2472
2473                if new_items.meta.total_pages <= page:
2474                    break
2475
2476                page += 1
2477
2478            return DatasetClient(
2479                dataset=dataset,
2480                items=dataset_items,
2481                version=version,
2482                langfuse_client=self,
2483            )
2484
2485        except Error as e:
2486            handle_fern_exception(e)
2487            raise e

Fetch a dataset by its name.

Arguments:
  • name: The name of the dataset to fetch.
  • fetch_items_page_size: All items of the dataset will be fetched in chunks of this size. Defaults to 50.
  • version: Retrieve dataset items as they existed at this specific point in time (UTC). If provided, returns the state of items at the specified UTC timestamp. If not provided, returns the latest version. Must be a timezone-aware datetime object in UTC.
Returns:

DatasetClient: The dataset with the given name.

def get_dataset_run( self, *, dataset_name: str, run_name: str) -> langfuse.api.DatasetRunWithItems: 
2489    def get_dataset_run(
2490        self, *, dataset_name: str, run_name: str
2491    ) -> DatasetRunWithItems:
2492        """Fetch a dataset run by dataset name and run name.
2493
2494        Args:
2495            dataset_name (str): The name of the dataset.
2496            run_name (str): The name of the run.
2497
2498        Returns:
2499            DatasetRunWithItems: The dataset run with its items.
2500        """
2501        try:
2502            return cast(
2503                DatasetRunWithItems,
2504                self.api.datasets.get_run(
2505                    dataset_name=self._url_encode(dataset_name),
2506                    run_name=self._url_encode(run_name),
2507                    request_options=None,
2508                ),
2509            )
2510        except Error as e:
2511            handle_fern_exception(e)
2512            raise e

Fetch a dataset run by dataset name and run name.

Arguments:
  • dataset_name (str): The name of the dataset.
  • run_name (str): The name of the run.
Returns:

DatasetRunWithItems: The dataset run with its items.

def get_dataset_runs( self, *, dataset_name: str, page: Optional[int] = None, limit: Optional[int] = None) -> langfuse.api.PaginatedDatasetRuns: 
2514    def get_dataset_runs(
2515        self,
2516        *,
2517        dataset_name: str,
2518        page: Optional[int] = None,
2519        limit: Optional[int] = None,
2520    ) -> PaginatedDatasetRuns:
2521        """Fetch all runs for a dataset.
2522
2523        Args:
2524            dataset_name (str): The name of the dataset.
2525            page (Optional[int]): Page number, starts at 1.
2526            limit (Optional[int]): Limit of items per page.
2527
2528        Returns:
2529            PaginatedDatasetRuns: Paginated list of dataset runs.
2530        """
2531        try:
2532            return cast(
2533                PaginatedDatasetRuns,
2534                self.api.datasets.get_runs(
2535                    dataset_name=self._url_encode(dataset_name),
2536                    page=page,
2537                    limit=limit,
2538                    request_options=None,
2539                ),
2540            )
2541        except Error as e:
2542            handle_fern_exception(e)
2543            raise e

Fetch all runs for a dataset.

Arguments:
  • dataset_name (str): The name of the dataset.
  • page (Optional[int]): Page number, starts at 1.
  • limit (Optional[int]): Limit of items per page.
Returns:

PaginatedDatasetRuns: Paginated list of dataset runs.

def delete_dataset_run( self, *, dataset_name: str, run_name: str) -> langfuse.api.DeleteDatasetRunResponse: 
2545    def delete_dataset_run(
2546        self, *, dataset_name: str, run_name: str
2547    ) -> DeleteDatasetRunResponse:
2548        """Delete a dataset run and all its run items. This action is irreversible.
2549
2550        Args:
2551            dataset_name (str): The name of the dataset.
2552            run_name (str): The name of the run.
2553
2554        Returns:
2555            DeleteDatasetRunResponse: Confirmation of deletion.
2556        """
2557        try:
2558            return cast(
2559                DeleteDatasetRunResponse,
2560                self.api.datasets.delete_run(
2561                    dataset_name=self._url_encode(dataset_name),
2562                    run_name=self._url_encode(run_name),
2563                    request_options=None,
2564                ),
2565            )
2566        except Error as e:
2567            handle_fern_exception(e)
2568            raise e

Delete a dataset run and all its run items. This action is irreversible.

Arguments:
  • dataset_name (str): The name of the dataset.
  • run_name (str): The name of the run.
Returns:

DeleteDatasetRunResponse: Confirmation of deletion.

def run_experiment( self, *, name: str, run_name: Optional[str] = None, description: Optional[str] = None, data: Union[List[langfuse.experiment.LocalExperimentItem], List[langfuse.api.DatasetItem]], task: langfuse.experiment.TaskFunction, evaluators: List[langfuse.experiment.EvaluatorFunction] = [], composite_evaluator: Optional[CompositeEvaluatorFunction] = None, run_evaluators: List[langfuse.experiment.RunEvaluatorFunction] = [], max_concurrency: int = 50, metadata: Optional[Dict[str, str]] = None, _dataset_version: Optional[datetime.datetime] = None) -> langfuse.experiment.ExperimentResult: 
2570    def run_experiment(
2571        self,
2572        *,
2573        name: str,
2574        run_name: Optional[str] = None,
2575        description: Optional[str] = None,
2576        data: ExperimentData,
2577        task: TaskFunction,
2578        evaluators: List[EvaluatorFunction] = [],
2579        composite_evaluator: Optional[CompositeEvaluatorFunction] = None,
2580        run_evaluators: List[RunEvaluatorFunction] = [],
2581        max_concurrency: int = 50,
2582        metadata: Optional[Dict[str, str]] = None,
2583        _dataset_version: Optional[datetime] = None,
2584    ) -> ExperimentResult:
2585        """Run an experiment on a dataset with automatic tracing and evaluation.
2586
2587        This method executes a task function on each item in the provided dataset,
2588        automatically traces all executions with Langfuse for observability, runs
2589        item-level and run-level evaluators on the outputs, and returns comprehensive
2590        results with evaluation metrics.
2591
2592        The experiment system provides:
2593        - Automatic tracing of all task executions
2594        - Concurrent processing with configurable limits
2595        - Comprehensive error handling that isolates failures
2596        - Integration with Langfuse datasets for experiment tracking
2597        - Flexible evaluation framework supporting both sync and async evaluators
2598
2599        Args:
2600            name: Human-readable name for the experiment. Used for identification
2601                in the Langfuse UI.
2602            run_name: Optional exact name for the experiment run. If provided, this will be
2603                used as the exact dataset run name if the `data` contains Langfuse dataset items.
2604                If not provided, this will default to the experiment name appended with an ISO timestamp.
2605            description: Optional description explaining the experiment's purpose,
2606                methodology, or expected outcomes.
2607            data: Array of data items to process. Can be either:
2608                - List of dict-like items with 'input', 'expected_output', 'metadata' keys
2609                - List of Langfuse DatasetItem objects from dataset.items
2610            task: Function that processes each data item and returns output.
2611                Must accept 'item' as keyword argument and can return sync or async results.
2612                The task function signature should be: task(*, item, **kwargs) -> Any
2613            evaluators: List of functions to evaluate each item's output individually.
2614                Each evaluator receives input, output, expected_output, and metadata.
2615                Can return single Evaluation dict or list of Evaluation dicts.
2616            composite_evaluator: Optional function that creates composite scores from item-level evaluations.
2617                Receives the same inputs as item-level evaluators (input, output, expected_output, metadata)
2618                plus the list of evaluations from item-level evaluators. Useful for weighted averages,
2619                pass/fail decisions based on multiple criteria, or custom scoring logic combining multiple metrics.
2620            run_evaluators: List of functions to evaluate the entire experiment run.
2621                Each run evaluator receives all item_results and can compute aggregate metrics.
2622                Useful for calculating averages, distributions, or cross-item comparisons.
2623            max_concurrency: Maximum number of concurrent task executions (default: 50).
2624                Controls the number of items processed simultaneously. Adjust based on
2625                API rate limits and system resources.
2626            metadata: Optional metadata dictionary to attach to all experiment traces.
2627                This metadata will be included in every trace created during the experiment.
2628                If `data` are Langfuse dataset items, the metadata will be attached to the dataset run, too.
2629
2630        Returns:
2631            ExperimentResult containing:
2632            - run_name: The experiment run name. This is equal to the dataset run name if experiment was on Langfuse dataset.
2633            - item_results: List of results for each processed item with outputs and evaluations
2634            - run_evaluations: List of aggregate evaluation results for the entire run
2635            - experiment_id: Stable identifier for the experiment run across all items
2636            - dataset_run_id: ID of the dataset run (if using Langfuse datasets)
2637            - dataset_run_url: Direct URL to view results in Langfuse UI (if applicable)
2638
2639        Raises:
2640            ValueError: If required parameters are missing or invalid
2641            Exception: If experiment setup fails (individual item failures are handled gracefully)
2642
2643        Examples:
2644            Basic experiment with local data:
2645            ```python
2646            def summarize_text(*, item, **kwargs):
2647                return f"Summary: {item['input'][:50]}..."
2648
2649            def length_evaluator(*, input, output, expected_output=None, **kwargs):
2650                return {
2651                    "name": "output_length",
2652                    "value": len(output),
2653                    "comment": f"Output contains {len(output)} characters"
2654                }
2655
2656            result = langfuse.run_experiment(
2657                name="Text Summarization Test",
2658                description="Evaluate summarization quality and length",
2659                data=[
2660                    {"input": "Long article text...", "expected_output": "Expected summary"},
2661                    {"input": "Another article...", "expected_output": "Another summary"}
2662                ],
2663                task=summarize_text,
2664                evaluators=[length_evaluator]
2665            )
2666
2667            print(f"Processed {len(result.item_results)} items")
2668            for item_result in result.item_results:
2669                print(f"Input: {item_result.item['input']}")
2670                print(f"Output: {item_result.output}")
2671                print(f"Evaluations: {item_result.evaluations}")
2672            ```
2673
2674            Advanced experiment with async task and multiple evaluators:
2675            ```python
2676            async def llm_task(*, item, **kwargs):
2677                # Simulate async LLM call
2678                response = await openai_client.chat.completions.create(
2679                    model="gpt-4",
2680                    messages=[{"role": "user", "content": item["input"]}]
2681                )
2682                return response.choices[0].message.content
2683
2684            def accuracy_evaluator(*, input, output, expected_output=None, **kwargs):
2685                if expected_output and expected_output.lower() in output.lower():
2686                    return {"name": "accuracy", "value": 1.0, "comment": "Correct answer"}
2687                return {"name": "accuracy", "value": 0.0, "comment": "Incorrect answer"}
2688
2689            def toxicity_evaluator(*, input, output, expected_output=None, **kwargs):
2690                # Simulate toxicity check
2691                toxicity_score = check_toxicity(output)  # Your toxicity checker
2692                return {
2693                    "name": "toxicity",
2694                    "value": toxicity_score,
2695                    "comment": f"Toxicity level: {'high' if toxicity_score > 0.7 else 'low'}"
2696                }
2697
2698            def average_accuracy(*, item_results, **kwargs):
2699                accuracies = [
2700                    eval.value for result in item_results
2701                    for eval in result.evaluations
2702                    if eval.name == "accuracy"
2703                ]
2704                return {
2705                    "name": "average_accuracy",
2706                    "value": sum(accuracies) / len(accuracies) if accuracies else 0,
2707                    "comment": f"Average accuracy across {len(accuracies)} items"
2708                }
2709
2710            result = langfuse.run_experiment(
2711                name="LLM Safety and Accuracy Test",
2712                description="Evaluate model accuracy and safety across diverse prompts",
2713                data=test_dataset,  # Your dataset items
2714                task=llm_task,
2715                evaluators=[accuracy_evaluator, toxicity_evaluator],
2716                run_evaluators=[average_accuracy],
2717                max_concurrency=5,  # Limit concurrent API calls
2718                metadata={"model": "gpt-4", "temperature": 0.7}
2719            )
2720            ```
2721
2722            Using with Langfuse datasets:
2723            ```python
2724            # Get dataset from Langfuse
2725            dataset = langfuse.get_dataset("my-eval-dataset")
2726
2727            result = dataset.run_experiment(
2728                name="Production Model Evaluation",
2729                description="Monthly evaluation of production model performance",
2730                task=my_production_task,
2731                evaluators=[accuracy_evaluator, latency_evaluator]
2732            )
2733
2734            # Results automatically linked to dataset in Langfuse UI
2735            print(f"View results: {result['dataset_run_url']}")
2736            ```
2737
2738        Note:
2739            - Task and evaluator functions can be either synchronous or asynchronous
2740            - Individual item failures are logged but don't stop the experiment
2741            - All executions are automatically traced and visible in Langfuse UI
2742            - When using Langfuse datasets, results are automatically linked for easy comparison
2743            - This method works in both sync and async contexts (Jupyter notebooks, web apps, etc.)
2744            - Async execution is handled automatically with smart event loop detection
2745        """
2746        return cast(
2747            ExperimentResult,
2748            run_async_safely(
2749                self._run_experiment_async(
2750                    name=name,
2751                    run_name=self._create_experiment_run_name(
2752                        name=name, run_name=run_name
2753                    ),
2754                    description=description,
2755                    data=data,
2756                    task=task,
2757                    evaluators=evaluators or [],
2758                    composite_evaluator=composite_evaluator,
2759                    run_evaluators=run_evaluators or [],
2760                    max_concurrency=max_concurrency,
2761                    metadata=metadata,
2762                    dataset_version=_dataset_version,
2763                ),
2764            ),
2765        )

Run an experiment on a dataset with automatic tracing and evaluation.

This method executes a task function on each item in the provided dataset, automatically traces all executions with Langfuse for observability, runs item-level and run-level evaluators on the outputs, and returns comprehensive results with evaluation metrics.

The experiment system provides:

  • Automatic tracing of all task executions
  • Concurrent processing with configurable limits
  • Comprehensive error handling that isolates failures
  • Integration with Langfuse datasets for experiment tracking
  • Flexible evaluation framework supporting both sync and async evaluators
Arguments:
  • name: Human-readable name for the experiment. Used for identification in the Langfuse UI.
  • run_name: Optional exact name for the experiment run. If provided, this will be used as the exact dataset run name if the data contains Langfuse dataset items. If not provided, this will default to the experiment name appended with an ISO timestamp.
  • description: Optional description explaining the experiment's purpose, methodology, or expected outcomes.
  • data: Array of data items to process. Can be either:
    • List of dict-like items with 'input', 'expected_output', 'metadata' keys
    • List of Langfuse DatasetItem objects from dataset.items
  • task: Function that processes each data item and returns output. Must accept 'item' as keyword argument and can return sync or async results. The task function signature should be: task(*, item, **kwargs) -> Any
  • evaluators: List of functions to evaluate each item's output individually. Each evaluator receives input, output, expected_output, and metadata. Can return single Evaluation dict or list of Evaluation dicts.
  • composite_evaluator: Optional function that creates composite scores from item-level evaluations. Receives the same inputs as item-level evaluators (input, output, expected_output, metadata) plus the list of evaluations from item-level evaluators. Useful for weighted averages, pass/fail decisions based on multiple criteria, or custom scoring logic combining multiple metrics.
  • run_evaluators: List of functions to evaluate the entire experiment run. Each run evaluator receives all item_results and can compute aggregate metrics. Useful for calculating averages, distributions, or cross-item comparisons.
  • max_concurrency: Maximum number of concurrent task executions (default: 50). Controls the number of items processed simultaneously. Adjust based on API rate limits and system resources.
  • metadata: Optional metadata dictionary to attach to all experiment traces. This metadata will be included in every trace created during the experiment. If data are Langfuse dataset items, the metadata will be attached to the dataset run, too.
Returns:

ExperimentResult containing:

  • run_name: The experiment run name. This is equal to the dataset run name if experiment was on Langfuse dataset.
  • item_results: List of results for each processed item with outputs and evaluations
  • run_evaluations: List of aggregate evaluation results for the entire run
  • experiment_id: Stable identifier for the experiment run across all items
  • dataset_run_id: ID of the dataset run (if using Langfuse datasets)
  • dataset_run_url: Direct URL to view results in Langfuse UI (if applicable)
Raises:
  • ValueError: If required parameters are missing or invalid
  • Exception: If experiment setup fails (individual item failures are handled gracefully)
Examples:

Basic experiment with local data:

def summarize_text(*, item, **kwargs):
    return f"Summary: {item['input'][:50]}..."

def length_evaluator(*, input, output, expected_output=None, **kwargs):
    return {
        "name": "output_length",
        "value": len(output),
        "comment": f"Output contains {len(output)} characters"
    }

result = langfuse.run_experiment(
    name="Text Summarization Test",
    description="Evaluate summarization quality and length",
    data=[
        {"input": "Long article text...", "expected_output": "Expected summary"},
        {"input": "Another article...", "expected_output": "Another summary"}
    ],
    task=summarize_text,
    evaluators=[length_evaluator]
)

print(f"Processed {len(result.item_results)} items")
for item_result in result.item_results:
    print(f"Input: {item_result.item['input']}")
    print(f"Output: {item_result.output}")
    print(f"Evaluations: {item_result.evaluations}")

Advanced experiment with async task and multiple evaluators:

async def llm_task(*, item, **kwargs):
    # Simulate async LLM call
    response = await openai_client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": item["input"]}]
    )
    return response.choices[0].message.content

def accuracy_evaluator(*, input, output, expected_output=None, **kwargs):
    if expected_output and expected_output.lower() in output.lower():
        return {"name": "accuracy", "value": 1.0, "comment": "Correct answer"}
    return {"name": "accuracy", "value": 0.0, "comment": "Incorrect answer"}

def toxicity_evaluator(*, input, output, expected_output=None, **kwargs):
    # Simulate toxicity check
    toxicity_score = check_toxicity(output)  # Your toxicity checker
    return {
        "name": "toxicity",
        "value": toxicity_score,
        "comment": f"Toxicity level: {'high' if toxicity_score > 0.7 else 'low'}"
    }

def average_accuracy(*, item_results, **kwargs):
    accuracies = [
        eval.value for result in item_results
        for eval in result.evaluations
        if eval.name == "accuracy"
    ]
    return {
        "name": "average_accuracy",
        "value": sum(accuracies) / len(accuracies) if accuracies else 0,
        "comment": f"Average accuracy across {len(accuracies)} items"
    }

result = langfuse.run_experiment(
    name="LLM Safety and Accuracy Test",
    description="Evaluate model accuracy and safety across diverse prompts",
    data=test_dataset,  # Your dataset items
    task=llm_task,
    evaluators=[accuracy_evaluator, toxicity_evaluator],
    run_evaluators=[average_accuracy],
    max_concurrency=5,  # Limit concurrent API calls
    metadata={"model": "gpt-4", "temperature": 0.7}
)

Using with Langfuse datasets:

# Get dataset from Langfuse
dataset = langfuse.get_dataset("my-eval-dataset")

result = dataset.run_experiment(
    name="Production Model Evaluation",
    description="Monthly evaluation of production model performance",
    task=my_production_task,
    evaluators=[accuracy_evaluator, latency_evaluator]
)

# Results automatically linked to dataset in Langfuse UI
print(f"View results: {result['dataset_run_url']}")
Note:
  • Task and evaluator functions can be either synchronous or asynchronous
  • Individual item failures are logged but don't stop the experiment
  • All executions are automatically traced and visible in Langfuse UI
  • When using Langfuse datasets, results are automatically linked for easy comparison
  • This method works in both sync and async contexts (Jupyter notebooks, web apps, etc.)
  • Async execution is handled automatically with smart event loop detection
def run_batched_evaluation( self, *, scope: Literal['traces', 'observations'], mapper: MapperFunction, filter: Optional[str] = None, fetch_batch_size: int = 50, fetch_trace_fields: Optional[str] = None, max_items: Optional[int] = None, max_retries: int = 3, evaluators: List[langfuse.experiment.EvaluatorFunction], composite_evaluator: Optional[CompositeEvaluatorFunction] = None, max_concurrency: int = 5, metadata: Optional[Dict[str, Any]] = None, _add_observation_scores_to_trace: bool = False, _additional_trace_tags: Optional[List[str]] = None, resume_from: Optional[BatchEvaluationResumeToken] = None, verbose: bool = False) -> BatchEvaluationResult: 
3127    def run_batched_evaluation(
3128        self,
3129        *,
3130        scope: Literal["traces", "observations"],
3131        mapper: MapperFunction,
3132        filter: Optional[str] = None,
3133        fetch_batch_size: int = 50,
3134        fetch_trace_fields: Optional[str] = None,
3135        max_items: Optional[int] = None,
3136        max_retries: int = 3,
3137        evaluators: List[EvaluatorFunction],
3138        composite_evaluator: Optional[CompositeEvaluatorFunction] = None,
3139        max_concurrency: int = 5,
3140        metadata: Optional[Dict[str, Any]] = None,
3141        _add_observation_scores_to_trace: bool = False,
3142        _additional_trace_tags: Optional[List[str]] = None,
3143        resume_from: Optional[BatchEvaluationResumeToken] = None,
3144        verbose: bool = False,
3145    ) -> BatchEvaluationResult:
3146        """Fetch traces or observations and run evaluations on each item.
3147
3148        This method provides a powerful way to evaluate existing data in Langfuse at scale.
3149        It fetches items based on filters, transforms them using a mapper function, runs
3150        evaluators on each item, and creates scores that are linked back to the original
3151        entities. This is ideal for:
3152
3153        - Running evaluations on production traces after deployment
3154        - Backtesting new evaluation metrics on historical data
3155        - Batch scoring of observations for quality monitoring
3156        - Periodic evaluation runs on recent data
3157
3158        The method uses a streaming/pipeline approach to process items in batches, making
3159        it memory-efficient for large datasets. It includes comprehensive error handling,
3160        retry logic, and resume capability for long-running evaluations.
3161
3162        Args:
3163            scope: The type of items to evaluate. Must be one of:
3164                - "traces": Evaluate complete traces with all their observations
3165                - "observations": Evaluate individual observations (spans, generations, events)
3166            mapper: Function that transforms API response objects into evaluator inputs.
3167                Receives a trace/observation object and returns an EvaluatorInputs
3168                instance with input, output, expected_output, and metadata fields.
3169                Can be sync or async.
3170            evaluators: List of evaluation functions to run on each item. Each evaluator
3171                receives the mapped inputs and returns Evaluation object(s). Evaluator
3172                failures are logged but don't stop the batch evaluation.
3173            filter: Optional JSON filter string for querying items (same format as Langfuse API). Examples:
3174                - '{"tags": ["production"]}'
3175                - '{"user_id": "user123", "timestamp": {"operator": ">", "value": "2024-01-01"}}'
3176                Default: None (fetches all items).
3177            fetch_batch_size: Number of items to fetch per API call and hold in memory.
3178                Larger values may be faster but use more memory. Default: 50.
3179            fetch_trace_fields: Comma-separated list of fields to include when fetching traces. Available field groups: 'core' (always included), 'io' (input, output, metadata), 'scores', 'observations', 'metrics'. If not specified, all fields are returned. Example: 'core,scores,metrics'. Note: Excluded 'observations' or 'scores' fields return empty arrays; excluded 'metrics' returns -1 for 'totalCost' and 'latency'. Only relevant if scope is 'traces'.
3180            max_items: Maximum total number of items to process. If None, processes all
3181                items matching the filter. Useful for testing or limiting evaluation runs.
3182                Default: None (process all).
3183            max_concurrency: Maximum number of items to evaluate concurrently. Controls
3184                parallelism and resource usage. Default: 5.
3185            composite_evaluator: Optional function that creates a composite score from
3186                item-level evaluations. Receives the original item and its evaluations,
3187                returns a single Evaluation. Useful for weighted averages or combined metrics.
3188                Default: None.
3189            metadata: Optional metadata dict to add to all created scores. Useful for
3190                tracking evaluation runs, versions, or other context. Default: None.
3191            max_retries: Maximum number of retry attempts for failed batch fetches.
3192                Uses exponential backoff (1s, 2s, 4s). Default: 3.
3193            verbose: If True, logs progress information to console. Useful for monitoring
3194                long-running evaluations. Default: False.
3195            resume_from: Optional resume token from a previous incomplete run. Allows
3196                continuing evaluation after interruption or failure. Default: None.
3197
3198
3199        Returns:
3200            BatchEvaluationResult containing:
3201                - total_items_fetched: Number of items fetched from API
3202                - total_items_processed: Number of items successfully evaluated
3203                - total_items_failed: Number of items that failed evaluation
3204                - total_scores_created: Scores created by item-level evaluators
3205                - total_composite_scores_created: Scores created by composite evaluator
3206                - total_evaluations_failed: Individual evaluator failures
3207                - evaluator_stats: Per-evaluator statistics (success rate, scores created)
3208                - resume_token: Token for resuming if incomplete (None if completed)
3209                - completed: True if all items processed
3210                - duration_seconds: Total execution time
3211                - failed_item_ids: IDs of items that failed
3212                - error_summary: Error types and counts
3213                - has_more_items: True if max_items reached but more exist
3214
3215        Raises:
3216            ValueError: If invalid scope is provided.
3217
3218        Examples:
3219            Basic trace evaluation:
3220            ```python
3221            from langfuse import Langfuse, EvaluatorInputs, Evaluation
3222
3223            client = Langfuse()
3224
3225            # Define mapper to extract fields from traces
3226            def trace_mapper(trace):
3227                return EvaluatorInputs(
3228                    input=trace.input,
3229                    output=trace.output,
3230                    expected_output=None,
3231                    metadata={"trace_id": trace.id}
3232                )
3233
3234            # Define evaluator
3235            def length_evaluator(*, input, output, expected_output, metadata):
3236                return Evaluation(
3237                    name="output_length",
3238                    value=len(output) if output else 0
3239                )
3240
3241            # Run batch evaluation
3242            result = client.run_batched_evaluation(
3243                scope="traces",
3244                mapper=trace_mapper,
3245                evaluators=[length_evaluator],
3246                filter='{"tags": ["production"]}',
3247                max_items=1000,
3248                verbose=True
3249            )
3250
3251            print(f"Processed {result.total_items_processed} traces")
3252            print(f"Created {result.total_scores_created} scores")
3253            ```
3254
3255            Evaluation with composite scorer:
3256            ```python
3257            def accuracy_evaluator(*, input, output, expected_output, metadata):
3258                # ... evaluation logic
3259                return Evaluation(name="accuracy", value=0.85)
3260
3261            def relevance_evaluator(*, input, output, expected_output, metadata):
3262                # ... evaluation logic
3263                return Evaluation(name="relevance", value=0.92)
3264
3265            def composite_evaluator(*, item, evaluations):
3266                # Weighted average of evaluations
3267                weights = {"accuracy": 0.6, "relevance": 0.4}
3268                total = sum(
3269                    e.value * weights.get(e.name, 0)
3270                    for e in evaluations
3271                    if isinstance(e.value, (int, float))
3272                )
3273                return Evaluation(
3274                    name="composite_score",
3275                    value=total,
3276                    comment=f"Weighted average of {len(evaluations)} metrics"
3277                )
3278
3279            result = client.run_batched_evaluation(
3280                scope="traces",
3281                mapper=trace_mapper,
3282                evaluators=[accuracy_evaluator, relevance_evaluator],
3283                composite_evaluator=composite_evaluator,
3284                filter='{"user_id": "important_user"}',
3285                verbose=True
3286            )
3287            ```
3288
3289            Handling incomplete runs with resume:
3290            ```python
3291            # Initial run that may fail or timeout
3292            result = client.run_batched_evaluation(
3293                scope="observations",
3294                mapper=obs_mapper,
3295                evaluators=[my_evaluator],
3296                max_items=10000,
3297                verbose=True
3298            )
3299
3300            # Check if incomplete
3301            if not result.completed and result.resume_token:
3302                print(f"Processed {result.resume_token.items_processed} items before interruption")
3303
3304                # Resume from where it left off
3305                result = client.run_batched_evaluation(
3306                    scope="observations",
3307                    mapper=obs_mapper,
3308                    evaluators=[my_evaluator],
3309                    resume_from=result.resume_token,
3310                    verbose=True
3311                )
3312
3313            print(f"Total items processed: {result.total_items_processed}")
3314            ```
3315
3316            Monitoring evaluator performance:
3317            ```python
3318            result = client.run_batched_evaluation(...)
3319
3320            for stats in result.evaluator_stats:
3321                success_rate = stats.successful_runs / stats.total_runs
3322                print(f"{stats.name}:")
3323                print(f"  Success rate: {success_rate:.1%}")
3324                print(f"  Scores created: {stats.total_scores_created}")
3325
3326                if stats.failed_runs > 0:
3327                    print(f"  ⚠️  Failed {stats.failed_runs} times")
3328            ```
3329
3330        Note:
3331            - Evaluator failures are logged but don't stop the batch evaluation
3332            - Individual item failures are tracked but don't stop processing
3333            - Fetch failures are retried with exponential backoff
3334            - All scores are automatically flushed to Langfuse at the end
3335            - The resume mechanism uses timestamp-based filtering to avoid duplicates
3336        """
3337        runner = BatchEvaluationRunner(self)
3338
3339        return cast(
3340            BatchEvaluationResult,
3341            run_async_safely(
3342                runner.run_async(
3343                    scope=scope,
3344                    mapper=mapper,
3345                    evaluators=evaluators,
3346                    filter=filter,
3347                    fetch_batch_size=fetch_batch_size,
3348                    fetch_trace_fields=fetch_trace_fields,
3349                    max_items=max_items,
3350                    max_concurrency=max_concurrency,
3351                    composite_evaluator=composite_evaluator,
3352                    metadata=metadata,
3353                    _add_observation_scores_to_trace=_add_observation_scores_to_trace,
3354                    _additional_trace_tags=_additional_trace_tags,
3355                    max_retries=max_retries,
3356                    verbose=verbose,
3357                    resume_from=resume_from,
3358                )
3359            ),
3360        )

Fetch traces or observations and run evaluations on each item.

This method provides a powerful way to evaluate existing data in Langfuse at scale. It fetches items based on filters, transforms them using a mapper function, runs evaluators on each item, and creates scores that are linked back to the original entities. This is ideal for:

  • Running evaluations on production traces after deployment
  • Backtesting new evaluation metrics on historical data
  • Batch scoring of observations for quality monitoring
  • Periodic evaluation runs on recent data

The method uses a streaming/pipeline approach to process items in batches, making it memory-efficient for large datasets. It includes comprehensive error handling, retry logic, and resume capability for long-running evaluations.

Arguments:
  • scope: The type of items to evaluate. Must be one of:
    • "traces": Evaluate complete traces with all their observations
    • "observations": Evaluate individual observations (spans, generations, events)
  • mapper: Function that transforms API response objects into evaluator inputs. Receives a trace/observation object and returns an EvaluatorInputs instance with input, output, expected_output, and metadata fields. Can be sync or async.
  • evaluators: List of evaluation functions to run on each item. Each evaluator receives the mapped inputs and returns Evaluation object(s). Evaluator failures are logged but don't stop the batch evaluation.
  • filter: Optional JSON filter string for querying items (same format as Langfuse API). Examples:
    • '{"tags": ["production"]}'
    • '{"user_id": "user123", "timestamp": {"operator": ">", "value": "2024-01-01"}}' Default: None (fetches all items).
  • fetch_batch_size: Number of items to fetch per API call and hold in memory. Larger values may be faster but use more memory. Default: 50.
  • fetch_trace_fields: Comma-separated list of fields to include when fetching traces. Available field groups: 'core' (always included), 'io' (input, output, metadata), 'scores', 'observations', 'metrics'. If not specified, all fields are returned. Example: 'core,scores,metrics'. Note: Excluded 'observations' or 'scores' fields return empty arrays; excluded 'metrics' returns -1 for 'totalCost' and 'latency'. Only relevant if scope is 'traces'.
  • max_items: Maximum total number of items to process. If None, processes all items matching the filter. Useful for testing or limiting evaluation runs. Default: None (process all).
  • max_concurrency: Maximum number of items to evaluate concurrently. Controls parallelism and resource usage. Default: 5.
  • composite_evaluator: Optional function that creates a composite score from item-level evaluations. Receives the original item and its evaluations, returns a single Evaluation. Useful for weighted averages or combined metrics. Default: None.
  • metadata: Optional metadata dict to add to all created scores. Useful for tracking evaluation runs, versions, or other context. Default: None.
  • max_retries: Maximum number of retry attempts for failed batch fetches. Uses exponential backoff (1s, 2s, 4s). Default: 3.
  • verbose: If True, logs progress information to console. Useful for monitoring long-running evaluations. Default: False.
  • resume_from: Optional resume token from a previous incomplete run. Allows continuing evaluation after interruption or failure. Default: None.
Returns:

BatchEvaluationResult containing: - total_items_fetched: Number of items fetched from API - total_items_processed: Number of items successfully evaluated - total_items_failed: Number of items that failed evaluation - total_scores_created: Scores created by item-level evaluators - total_composite_scores_created: Scores created by composite evaluator - total_evaluations_failed: Individual evaluator failures - evaluator_stats: Per-evaluator statistics (success rate, scores created) - resume_token: Token for resuming if incomplete (None if completed) - completed: True if all items processed - duration_seconds: Total execution time - failed_item_ids: IDs of items that failed - error_summary: Error types and counts - has_more_items: True if max_items reached but more exist

Raises:
  • ValueError: If invalid scope is provided.
Examples:

Basic trace evaluation:

from langfuse import Langfuse, EvaluatorInputs, Evaluation

client = Langfuse()

# Define mapper to extract fields from traces
def trace_mapper(trace):
    return EvaluatorInputs(
        input=trace.input,
        output=trace.output,
        expected_output=None,
        metadata={"trace_id": trace.id}
    )

# Define evaluator
def length_evaluator(*, input, output, expected_output, metadata):
    return Evaluation(
        name="output_length",
        value=len(output) if output else 0
    )

# Run batch evaluation
result = client.run_batched_evaluation(
    scope="traces",
    mapper=trace_mapper,
    evaluators=[length_evaluator],
    filter='{"tags": ["production"]}',
    max_items=1000,
    verbose=True
)

print(f"Processed {result.total_items_processed} traces")
print(f"Created {result.total_scores_created} scores")

Evaluation with composite scorer:

def accuracy_evaluator(*, input, output, expected_output, metadata):
    # ... evaluation logic
    return Evaluation(name="accuracy", value=0.85)

def relevance_evaluator(*, input, output, expected_output, metadata):
    # ... evaluation logic
    return Evaluation(name="relevance", value=0.92)

def composite_evaluator(*, item, evaluations):
    # Weighted average of evaluations
    weights = {"accuracy": 0.6, "relevance": 0.4}
    total = sum(
        e.value * weights.get(e.name, 0)
        for e in evaluations
        if isinstance(e.value, (int, float))
    )
    return Evaluation(
        name="composite_score",
        value=total,
        comment=f"Weighted average of {len(evaluations)} metrics"
    )

result = client.run_batched_evaluation(
    scope="traces",
    mapper=trace_mapper,
    evaluators=[accuracy_evaluator, relevance_evaluator],
    composite_evaluator=composite_evaluator,
    filter='{"user_id": "important_user"}',
    verbose=True
)

Handling incomplete runs with resume:

# Initial run that may fail or timeout
result = client.run_batched_evaluation(
    scope="observations",
    mapper=obs_mapper,
    evaluators=[my_evaluator],
    max_items=10000,
    verbose=True
)

# Check if incomplete
if not result.completed and result.resume_token:
    print(f"Processed {result.resume_token.items_processed} items before interruption")

    # Resume from where it left off
    result = client.run_batched_evaluation(
        scope="observations",
        mapper=obs_mapper,
        evaluators=[my_evaluator],
        resume_from=result.resume_token,
        verbose=True
    )

print(f"Total items processed: {result.total_items_processed}")

Monitoring evaluator performance:

result = client.run_batched_evaluation(...)

for stats in result.evaluator_stats:
    success_rate = stats.successful_runs / stats.total_runs
    print(f"{stats.name}:")
    print(f"  Success rate: {success_rate:.1%}")
    print(f"  Scores created: {stats.total_scores_created}")

    if stats.failed_runs > 0:
        print(f"  ⚠️  Failed {stats.failed_runs} times")
Note:
  • Evaluator failures are logged but don't stop the batch evaluation
  • Individual item failures are tracked but don't stop processing
  • Fetch failures are retried with exponential backoff
  • All scores are automatically flushed to Langfuse at the end
  • The resume mechanism uses timestamp-based filtering to avoid duplicates
def auth_check(self) -> bool: 
3362    def auth_check(self) -> bool:
3363        """Check if the provided credentials (public and secret key) are valid.
3364
3365        Raises:
3366            Exception: If no projects were found for the provided credentials.
3367
3368        Note:
3369            This method is blocking. It is discouraged to use it in production code.
3370        """
3371        try:
3372            projects = self.api.projects.get()
3373            langfuse_logger.debug(
3374                f"Auth check successful, found {len(projects.data)} projects"
3375            )
3376            if len(projects.data) == 0:
3377                raise Exception(
3378                    "Auth check failed, no project found for the keys provided."
3379                )
3380            return True
3381
3382        except AttributeError as e:
3383            langfuse_logger.warning(
3384                f"Auth check failed: Client not properly initialized. Error: {e}"
3385            )
3386            return False
3387
3388        except Error as e:
3389            handle_fern_exception(e)
3390            raise e

Check if the provided credentials (public and secret key) are valid.

Raises:
  • Exception: If no projects were found for the provided credentials.
Note:

This method is blocking. It is discouraged to use it in production code.

def create_dataset( self, *, name: str, description: Optional[str] = None, metadata: Optional[Any] = None, input_schema: Optional[Any] = None, expected_output_schema: Optional[Any] = None) -> langfuse.api.Dataset: 
3392    def create_dataset(
3393        self,
3394        *,
3395        name: str,
3396        description: Optional[str] = None,
3397        metadata: Optional[Any] = None,
3398        input_schema: Optional[Any] = None,
3399        expected_output_schema: Optional[Any] = None,
3400    ) -> Dataset:
3401        """Create a dataset with the given name on Langfuse.
3402
3403        Args:
3404            name: Name of the dataset to create.
3405            description: Description of the dataset. Defaults to None.
3406            metadata: Additional metadata. Defaults to None.
3407            input_schema: JSON Schema for validating dataset item inputs. When set, all new items will be validated against this schema.
3408            expected_output_schema: JSON Schema for validating dataset item expected outputs. When set, all new items will be validated against this schema.
3409
3410        Returns:
3411            Dataset: The created dataset as returned by the Langfuse API.
3412        """
3413        try:
3414            langfuse_logger.debug(f"Creating datasets {name}")
3415
3416            result = self.api.datasets.create(
3417                name=name,
3418                description=description,
3419                metadata=metadata,
3420                input_schema=input_schema,
3421                expected_output_schema=expected_output_schema,
3422            )
3423
3424            return cast(Dataset, result)
3425
3426        except Error as e:
3427            handle_fern_exception(e)
3428            raise e

Create a dataset with the given name on Langfuse.

Arguments:
  • name: Name of the dataset to create.
  • description: Description of the dataset. Defaults to None.
  • metadata: Additional metadata. Defaults to None.
  • input_schema: JSON Schema for validating dataset item inputs. When set, all new items will be validated against this schema.
  • expected_output_schema: JSON Schema for validating dataset item expected outputs. When set, all new items will be validated against this schema.
Returns:

Dataset: The created dataset as returned by the Langfuse API.

def create_dataset_item( self, *, dataset_name: str, input: Optional[Any] = None, expected_output: Optional[Any] = None, metadata: Optional[Any] = None, source_trace_id: Optional[str] = None, source_observation_id: Optional[str] = None, status: Optional[langfuse.api.DatasetStatus] = None, id: Optional[str] = None) -> langfuse.api.DatasetItem: 
3430    def create_dataset_item(
3431        self,
3432        *,
3433        dataset_name: str,
3434        input: Optional[Any] = None,
3435        expected_output: Optional[Any] = None,
3436        metadata: Optional[Any] = None,
3437        source_trace_id: Optional[str] = None,
3438        source_observation_id: Optional[str] = None,
3439        status: Optional[DatasetStatus] = None,
3440        id: Optional[str] = None,
3441    ) -> DatasetItem:
3442        """Create a dataset item.
3443
3444        Upserts if an item with id already exists.
3445
3446        Args:
3447            dataset_name: Name of the dataset in which the dataset item should be created.
3448            input: Input data. Defaults to None. Can contain any dict, list or scalar.
3449            expected_output: Expected output data. Defaults to None. Can contain any dict, list or scalar.
3450            metadata: Additional metadata. Defaults to None. Can contain any dict, list or scalar.
3451            source_trace_id: Id of the source trace. Defaults to None.
3452            source_observation_id: Id of the source observation. Defaults to None.
3453            status: Status of the dataset item. Defaults to ACTIVE for newly created items.
3454            id: Id of the dataset item. Defaults to None. Provide your own id if you want to dedupe dataset items. Id needs to be globally unique and cannot be reused across datasets.
3455
3456        Returns:
3457            DatasetItem: The created dataset item as returned by the Langfuse API.
3458
3459        Example:
3460            ```python
3461            from langfuse import Langfuse
3462
3463            langfuse = Langfuse()
3464
3465            # Uploading items to the Langfuse dataset named "capital_cities"
3466            langfuse.create_dataset_item(
3467                dataset_name="capital_cities",
3468                input={"input": {"country": "Italy"}},
3469                expected_output={"expected_output": "Rome"},
3470                metadata={"foo": "bar"}
3471            )
3472            ```
3473        """
3474        try:
3475            langfuse_logger.debug(f"Creating dataset item for dataset {dataset_name}")
3476
3477            # Media uploads must reference the (dataset, item) they belong to, and
3478            # the item need not exist yet — so settle on the item id up front and
3479            # reuse it for the create call below.
3480            item_id = id if id is not None else str(uuid.uuid4())
3481
3482            # Single pass per field: swap each LangfuseMedia for its reference
3483            # string (derived from content, not the upload) and collect the media
3484            # still to upload, deduped by media id and tagged with its field.
3485            pending_media: Dict[str, Tuple[LangfuseMedia, str]] = {}
3486            input = self._process_dataset_item_media(
3487                data=input,
3488                pending_media=pending_media,
3489                field=DatasetItemMediaReferenceField.INPUT.value,
3490            )
3491            expected_output = self._process_dataset_item_media(
3492                data=expected_output,
3493                pending_media=pending_media,
3494                field=DatasetItemMediaReferenceField.EXPECTED_OUTPUT.value,
3495            )
3496            metadata = self._process_dataset_item_media(
3497                data=metadata,
3498                pending_media=pending_media,
3499                field=DatasetItemMediaReferenceField.METADATA.value,
3500            )
3501
3502            # The upload needs the dataset id, but the create API only takes the
3503            # name. Resolve it once, and only when there is actually media to
3504            # upload — a plain item pays no extra datasets.get round-trip.
3505            if pending_media:
3506                assert self._resources is not None
3507                dataset_id = self.api.datasets.get(self._url_encode(dataset_name)).id
3508                for media, field in pending_media.values():
3509                    self._resources._media_manager._upload_media_sync(
3510                        media=media,
3511                        dataset_id=dataset_id,
3512                        dataset_item_id=item_id,
3513                        field=field,
3514                    )
3515
3516            result = self.api.dataset_items.create(
3517                dataset_name=dataset_name,
3518                input=input,
3519                expected_output=expected_output,
3520                metadata=metadata,
3521                source_trace_id=source_trace_id,
3522                source_observation_id=source_observation_id,
3523                status=status,
3524                id=item_id,
3525            )
3526
3527            return cast(DatasetItem, result)
3528        except Error as e:
3529            handle_fern_exception(e)
3530            raise e

Create a dataset item.

Upserts if an item with id already exists.

Arguments:
  • dataset_name: Name of the dataset in which the dataset item should be created.
  • input: Input data. Defaults to None. Can contain any dict, list or scalar.
  • expected_output: Expected output data. Defaults to None. Can contain any dict, list or scalar.
  • metadata: Additional metadata. Defaults to None. Can contain any dict, list or scalar.
  • source_trace_id: Id of the source trace. Defaults to None.
  • source_observation_id: Id of the source observation. Defaults to None.
  • status: Status of the dataset item. Defaults to ACTIVE for newly created items.
  • id: Id of the dataset item. Defaults to None. Provide your own id if you want to dedupe dataset items. Id needs to be globally unique and cannot be reused across datasets.
Returns:

DatasetItem: The created dataset item as returned by the Langfuse API.

Example:
from langfuse import Langfuse

langfuse = Langfuse()

# Uploading items to the Langfuse dataset named "capital_cities"
langfuse.create_dataset_item(
    dataset_name="capital_cities",
    input={"input": {"country": "Italy"}},
    expected_output={"expected_output": "Rome"},
    metadata={"foo": "bar"}
)
def resolve_media_references( self, *, obj: Any, resolve_with: Literal['base64_data_uri'], max_depth: int = 10, content_fetch_timeout_seconds: int = 5) -> Any: 
3656    def resolve_media_references(
3657        self,
3658        *,
3659        obj: Any,
3660        resolve_with: Literal["base64_data_uri"],
3661        max_depth: int = 10,
3662        content_fetch_timeout_seconds: int = 5,
3663    ) -> Any:
3664        """Replace media reference strings in an object with base64 data URIs.
3665
3666        This method recursively traverses an object (up to max_depth) looking for media reference strings
3667        in the format "@@@langfuseMedia:...@@@". When found, it (synchronously) fetches the actual media content using
3668        the provided Langfuse client and replaces the reference string with a base64 data URI.
3669
3670        If fetching media content fails for a reference string, a warning is logged and the reference
3671        string is left unchanged.
3672
3673        Args:
3674            obj: The object to process. Can be a primitive value, array, or nested object.
3675                If the object has a __dict__ attribute, a dict will be returned instead of the original object type.
3676            resolve_with: The representation of the media content to replace the media reference string with.
3677                Currently only "base64_data_uri" is supported.
3678            max_depth: int: The maximum depth to traverse the object. Default is 10.
3679            content_fetch_timeout_seconds: int: The timeout in seconds for fetching media content. Default is 5.
3680
3681        Returns:
3682            A deep copy of the input object with all media references replaced with base64 data URIs where possible.
3683            If the input object has a __dict__ attribute, a dict will be returned instead of the original object type.
3684
3685        Example:
3686            obj = {
3687                "image": "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@",
3688                "nested": {
3689                    "pdf": "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@"
3690                }
3691            }
3692
3693            result = await LangfuseMedia.resolve_media_references(obj, langfuse_client)
3694
3695            # Result:
3696            # {
3697            #     "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
3698            #     "nested": {
3699            #         "pdf": "data:application/pdf;base64,JVBERi0xLjcK..."
3700            #     }
3701            # }
3702        """
3703        return LangfuseMedia.resolve_media_references(
3704            langfuse_client=self,
3705            obj=obj,
3706            resolve_with=resolve_with,
3707            max_depth=max_depth,
3708            content_fetch_timeout_seconds=content_fetch_timeout_seconds,
3709        )

Replace media reference strings in an object with base64 data URIs.

This method recursively traverses an object (up to max_depth) looking for media reference strings in the format "@@@langfuseMedia:...@@@". When found, it (synchronously) fetches the actual media content using the provided Langfuse client and replaces the reference string with a base64 data URI.

If fetching media content fails for a reference string, a warning is logged and the reference string is left unchanged.

Arguments:
  • obj: The object to process. Can be a primitive value, array, or nested object. If the object has a __dict__ attribute, a dict will be returned instead of the original object type.
  • resolve_with: The representation of the media content to replace the media reference string with. Currently only "base64_data_uri" is supported.
  • max_depth: int: The maximum depth to traverse the object. Default is 10.
  • content_fetch_timeout_seconds: int: The timeout in seconds for fetching media content. Default is 5.
Returns:

A deep copy of the input object with all media references replaced with base64 data URIs where possible. If the input object has a __dict__ attribute, a dict will be returned instead of the original object type.

Example:

obj = { "image": "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@", "nested": { "pdf": "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@" } }

result = await LangfuseMedia.resolve_media_references(obj, langfuse_client)

Result:

{

"image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",

"nested": {

"pdf": "data:application/pdf;base64,JVBERi0xLjcK..."

}

}

def get_prompt( self, name: str, *, version: Optional[int] = None, label: Optional[str] = None, type: Literal['chat', 'text'] = 'text', cache_ttl_seconds: Optional[int] = None, fallback: Union[List[langfuse.model.ChatMessageDict], NoneType, str] = None, max_retries: Optional[int] = None, fetch_timeout_seconds: Optional[int] = None) -> Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient]: 
3739    def get_prompt(
3740        self,
3741        name: str,
3742        *,
3743        version: Optional[int] = None,
3744        label: Optional[str] = None,
3745        type: Literal["chat", "text"] = "text",
3746        cache_ttl_seconds: Optional[int] = None,
3747        fallback: Union[Optional[List[ChatMessageDict]], Optional[str]] = None,
3748        max_retries: Optional[int] = None,
3749        fetch_timeout_seconds: Optional[int] = None,
3750    ) -> PromptClient:
3751        """Get a prompt.
3752
3753        This method attempts to fetch the requested prompt from the local cache. If the prompt is not found
3754        in the cache or if the cached prompt has expired, it will try to fetch the prompt from the server again
3755        and update the cache. If fetching the new prompt fails, and there is an expired prompt in the cache, it will
3756        return the expired prompt as a fallback.
3757
3758        Args:
3759            name (str): The name of the prompt to retrieve.
3760
3761        Keyword Args:
3762            version (Optional[int]): The version of the prompt to retrieve. If no label and version is specified, the `production` label is returned. Specify either version or label, not both.
3763            label: Optional[str]: The label of the prompt to retrieve. If no label and version is specified, the `production` label is returned. Specify either version or label, not both.
3764            cache_ttl_seconds: Optional[int]: Time-to-live in seconds for caching the prompt. Must be specified as a
3765            keyword argument. If not set, defaults to 60 seconds. Disables caching if set to 0.
3766            type: Literal["chat", "text"]: The type of the prompt to retrieve. Defaults to "text".
3767            fallback: Union[Optional[List[ChatMessageDict]], Optional[str]]: The prompt string to return if fetching the prompt fails. Important on the first call where no cached prompt is available. Follows Langfuse prompt formatting with double curly braces for variables. Defaults to None.
3768            max_retries: Optional[int]: The maximum number of retries in case of API/network errors. Defaults to 2. The maximum value is 4. Retries have an exponential backoff with a maximum delay of 10 seconds.
3769            fetch_timeout_seconds: Optional[int]: The timeout in milliseconds for fetching the prompt. Defaults to the default timeout set on the SDK, which is 5 seconds per default.
3770
3771        Returns:
3772            The prompt object retrieved from the cache or directly fetched if not cached or expired of type
3773            - TextPromptClient, if type argument is 'text'.
3774            - ChatPromptClient, if type argument is 'chat'.
3775
3776        Raises:
3777            Exception: Propagates any exceptions raised during the fetching of a new prompt, unless there is an
3778            expired prompt in the cache, in which case it logs a warning and returns the expired prompt.
3779        """
3780        if self._resources is None:
3781            raise Error(
3782                "SDK is not correctly initialized. Check the init logs for more details."
3783            )
3784        if version is not None and label is not None:
3785            raise ValueError("Cannot specify both version and label at the same time.")
3786
3787        if not name:
3788            raise ValueError("Prompt name cannot be empty.")
3789
3790        cache_key = PromptCache.generate_cache_key(name, version=version, label=label)
3791        bounded_max_retries = self._get_bounded_max_retries(
3792            max_retries, default_max_retries=2, max_retries_upper_bound=4
3793        )
3794
3795        langfuse_logger.debug(f"Getting prompt '{cache_key}'")
3796        cached_prompt = self._resources.prompt_cache.get(cache_key)
3797
3798        if cached_prompt is None or cache_ttl_seconds == 0:
3799            langfuse_logger.debug(
3800                f"Prompt '{cache_key}' not found in cache or caching disabled."
3801            )
3802            try:
3803                return self._fetch_prompt_and_update_cache(
3804                    name,
3805                    version=version,
3806                    label=label,
3807                    ttl_seconds=cache_ttl_seconds,
3808                    max_retries=bounded_max_retries,
3809                    fetch_timeout_seconds=fetch_timeout_seconds,
3810                )
3811            except Exception as e:
3812                if fallback:
3813                    langfuse_logger.warning(
3814                        f"Returning fallback prompt for '{cache_key}' due to fetch error: {e}"
3815                    )
3816
3817                    fallback_client_args: Dict[str, Any] = {
3818                        "name": name,
3819                        "prompt": fallback,
3820                        "type": type,
3821                        "version": version or 0,
3822                        "config": {},
3823                        "labels": [label] if label else [],
3824                        "tags": [],
3825                    }
3826
3827                    if type == "text":
3828                        return TextPromptClient(
3829                            prompt=Prompt_Text(**fallback_client_args),
3830                            is_fallback=True,
3831                        )
3832
3833                    if type == "chat":
3834                        return ChatPromptClient(
3835                            prompt=Prompt_Chat(**fallback_client_args),
3836                            is_fallback=True,
3837                        )
3838
3839                raise e
3840
3841        if cached_prompt.is_expired():
3842            langfuse_logger.debug(f"Stale prompt '{cache_key}' found in cache.")
3843            try:
3844                # refresh prompt in background thread, refresh_prompt deduplicates tasks
3845                langfuse_logger.debug(f"Refreshing prompt '{cache_key}' in background.")
3846
3847                def refresh_task() -> None:
3848                    self._fetch_prompt_and_update_cache(
3849                        name,
3850                        version=version,
3851                        label=label,
3852                        ttl_seconds=cache_ttl_seconds,
3853                        max_retries=bounded_max_retries,
3854                        fetch_timeout_seconds=fetch_timeout_seconds,
3855                    )
3856
3857                self._resources.prompt_cache.add_refresh_prompt_task_if_current(
3858                    cache_key,
3859                    cached_prompt,
3860                    refresh_task,
3861                )
3862                langfuse_logger.debug(
3863                    f"Returning stale prompt '{cache_key}' from cache."
3864                )
3865                # return stale prompt
3866                return cached_prompt.value
3867
3868            except Exception as e:
3869                langfuse_logger.warning(
3870                    f"Error when refreshing cached prompt '{cache_key}', returning cached version. Error: {e}"
3871                )
3872                # creation of refresh prompt task failed, return stale prompt
3873                return cached_prompt.value
3874
3875        return cached_prompt.value

Get a prompt.

This method attempts to fetch the requested prompt from the local cache. If the prompt is not found in the cache or if the cached prompt has expired, it will try to fetch the prompt from the server again and update the cache. If fetching the new prompt fails, and there is an expired prompt in the cache, it will return the expired prompt as a fallback.

Arguments:
  • name (str): The name of the prompt to retrieve.
Keyword Args:
  • version (Optional[int]): The version of the prompt to retrieve. If no label and version is specified, the production label is returned. Specify either version or label, not both.
  • label: Optional[str]: The label of the prompt to retrieve. If no label and version is specified, the production label is returned. Specify either version or label, not both.
  • cache_ttl_seconds: Optional[int]: Time-to-live in seconds for caching the prompt. Must be specified as a
  • keyword argument. If not set, defaults to 60 seconds. Disables caching if set to 0.
  • type: Literal["chat", "text"]: The type of the prompt to retrieve. Defaults to "text".
  • fallback: Union[Optional[List[ChatMessageDict]], Optional[str]]: The prompt string to return if fetching the prompt fails. Important on the first call where no cached prompt is available. Follows Langfuse prompt formatting with double curly braces for variables. Defaults to None.
  • max_retries: Optional[int]: The maximum number of retries in case of API/network errors. Defaults to 2. The maximum value is 4. Retries have an exponential backoff with a maximum delay of 10 seconds.
  • fetch_timeout_seconds: Optional[int]: The timeout in milliseconds for fetching the prompt. Defaults to the default timeout set on the SDK, which is 5 seconds per default.
Returns:

The prompt object retrieved from the cache or directly fetched if not cached or expired of type

  • TextPromptClient, if type argument is 'text'.
  • ChatPromptClient, if type argument is 'chat'.
Raises:
  • Exception: Propagates any exceptions raised during the fetching of a new prompt, unless there is an
  • expired prompt in the cache, in which case it logs a warning and returns the expired prompt.
def create_prompt( self, *, name: str, prompt: Union[str, List[Union[langfuse.model.ChatMessageDict, langfuse.model.ChatMessageWithPlaceholdersDict_Message, langfuse.model.ChatMessageWithPlaceholdersDict_Placeholder]]], labels: List[str] = [], tags: Optional[List[str]] = None, type: Optional[Literal['chat', 'text']] = 'text', config: Optional[Any] = None, commit_message: Optional[str] = None) -> Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient]: 
3977    def create_prompt(
3978        self,
3979        *,
3980        name: str,
3981        prompt: Union[
3982            str, List[Union[ChatMessageDict, ChatMessageWithPlaceholdersDict]]
3983        ],
3984        labels: List[str] = [],
3985        tags: Optional[List[str]] = None,
3986        type: Optional[Literal["chat", "text"]] = "text",
3987        config: Optional[Any] = None,
3988        commit_message: Optional[str] = None,
3989    ) -> PromptClient:
3990        """Create a new prompt in Langfuse.
3991
3992        Keyword Args:
3993            name : The name of the prompt to be created.
3994            prompt : The content of the prompt to be created.
3995            is_active [DEPRECATED] : A flag indicating whether the prompt is active or not. This is deprecated and will be removed in a future release. Please use the 'production' label instead.
3996            labels: The labels of the prompt. Defaults to None. To create a default-served prompt, add the 'production' label.
3997            tags: The tags of the prompt. Defaults to None. Will be applied to all versions of the prompt.
3998            config: Additional structured data to be saved with the prompt. Defaults to None.
3999            type: The type of the prompt to be created. "chat" vs. "text". Defaults to "text".
4000            commit_message: Optional string describing the change.
4001
4002        Returns:
4003            TextPromptClient: The prompt if type argument is 'text'.
4004            ChatPromptClient: The prompt if type argument is 'chat'.
4005        """
4006        try:
4007            langfuse_logger.debug(f"Creating prompt {name=}, {labels=}")
4008
4009            if type == "chat":
4010                if not isinstance(prompt, list):
4011                    raise ValueError(
4012                        "For 'chat' type, 'prompt' must be a list of chat messages with role and content attributes."
4013                    )
4014                request: Union[CreateChatPromptRequest, CreateTextPromptRequest] = (
4015                    CreateChatPromptRequest(
4016                        name=name,
4017                        prompt=cast(Any, prompt),
4018                        labels=labels,
4019                        tags=tags,
4020                        config=config or {},
4021                        commit_message=commit_message,
4022                        type=CreateChatPromptType.CHAT,
4023                    )
4024                )
4025                server_prompt = self.api.prompts.create(request=request)
4026
4027                if self._resources is not None:
4028                    self._resources.prompt_cache.invalidate(name)
4029
4030                return ChatPromptClient(prompt=cast(Prompt_Chat, server_prompt))
4031
4032            if not isinstance(prompt, str):
4033                raise ValueError("For 'text' type, 'prompt' must be a string.")
4034
4035            request = CreateTextPromptRequest(
4036                name=name,
4037                prompt=prompt,
4038                labels=labels,
4039                tags=tags,
4040                config=config or {},
4041                commit_message=commit_message,
4042            )
4043
4044            server_prompt = self.api.prompts.create(request=request)
4045
4046            if self._resources is not None:
4047                self._resources.prompt_cache.invalidate(name)
4048
4049            return TextPromptClient(prompt=cast(Prompt_Text, server_prompt))
4050
4051        except Error as e:
4052            handle_fern_exception(e)
4053            raise e

Create a new prompt in Langfuse.

Keyword Args:
  • name : The name of the prompt to be created.
  • prompt : The content of the prompt to be created.
  • is_active [DEPRECATED] : A flag indicating whether the prompt is active or not. This is deprecated and will be removed in a future release. Please use the 'production' label instead.
  • labels: The labels of the prompt. Defaults to None. To create a default-served prompt, add the 'production' label.
  • tags: The tags of the prompt. Defaults to None. Will be applied to all versions of the prompt.
  • config: Additional structured data to be saved with the prompt. Defaults to None.
  • type: The type of the prompt to be created. "chat" vs. "text". Defaults to "text".
  • commit_message: Optional string describing the change.
Returns:

TextPromptClient: The prompt if type argument is 'text'. ChatPromptClient: The prompt if type argument is 'chat'.

def update_prompt(self, *, name: str, version: int, new_labels: List[str] = []) -> Any: 
4055    def update_prompt(
4056        self,
4057        *,
4058        name: str,
4059        version: int,
4060        new_labels: List[str] = [],
4061    ) -> Any:
4062        """Update an existing prompt version in Langfuse. The Langfuse SDK prompt cache is invalidated for all prompts witht he specified name.
4063
4064        Args:
4065            name (str): The name of the prompt to update.
4066            version (int): The version number of the prompt to update.
4067            new_labels (List[str], optional): New labels to assign to the prompt version. Labels are unique across versions. The "latest" label is reserved and managed by Langfuse. Defaults to [].
4068
4069        Returns:
4070            Prompt: The updated prompt from the Langfuse API.
4071
4072        """
4073        updated_prompt = self.api.prompt_version.update(
4074            name=self._url_encode(name),
4075            version=version,
4076            new_labels=new_labels,
4077        )
4078
4079        if self._resources is not None:
4080            self._resources.prompt_cache.invalidate(name)
4081
4082        return updated_prompt

Update an existing prompt version in Langfuse. The Langfuse SDK prompt cache is invalidated for all prompts witht he specified name.

Arguments:
  • name (str): The name of the prompt to update.
  • version (int): The version number of the prompt to update.
  • new_labels (List[str], optional): New labels to assign to the prompt version. Labels are unique across versions. The "latest" label is reserved and managed by Langfuse. Defaults to [].
Returns:

Prompt: The updated prompt from the Langfuse API.

def clear_prompt_cache(self) -> None: 
4097    def clear_prompt_cache(self) -> None:
4098        """Clear the entire prompt cache, removing all cached prompts.
4099
4100        This method is useful when you want to force a complete refresh of all
4101        cached prompts, for example after major updates or when you need to
4102        ensure the latest versions are fetched from the server.
4103        """
4104        if self._resources is not None:
4105            self._resources.prompt_cache.clear()

Clear the entire prompt cache, removing all cached prompts.

This method is useful when you want to force a complete refresh of all cached prompts, for example after major updates or when you need to ensure the latest versions are fetched from the server.

class LangfuseMedia: 
 99class LangfuseMedia:
100    """A class for wrapping media objects for upload to Langfuse.
101
102    This class handles the preparation and formatting of media content for Langfuse,
103    supporting both base64 data URIs and raw content bytes.
104
105    Args:
106        obj (Optional[object]): The source object to be wrapped. Can be accessed via the `obj` attribute.
107        base64_data_uri (Optional[str]): A base64-encoded data URI containing the media content
108            and content type (e.g., "data:image/jpeg;base64,/9j/4AAQ...").
109        content_type (Optional[str]): The MIME type of the media content when providing raw bytes.
110        content_bytes (Optional[bytes]): Raw bytes of the media content.
111        file_path (Optional[str]): The path to the file containing the media content. For relative paths,
112            the current working directory is used.
113
114    Raises:
115        ValueError: If neither base64_data_uri or the combination of content_bytes
116            and content_type is provided.
117    """
118
119    obj: object
120
121    _content_bytes: Optional[bytes]
122    _content_type: Optional[MediaContentType]
123    _source: Optional[str]
124    _media_id: Optional[str]
125
126    def __init__(
127        self,
128        *,
129        obj: Optional[object] = None,
130        base64_data_uri: Optional[str] = None,
131        content_type: Optional[MediaContentType] = None,
132        content_bytes: Optional[bytes] = None,
133        file_path: Optional[str] = None,
134    ):
135        """Initialize a LangfuseMedia object.
136
137        Args:
138            obj: The object to wrap.
139
140            base64_data_uri: A base64-encoded data URI containing the media content
141                and content type (e.g., "data:image/jpeg;base64,/9j/4AAQ...").
142            content_type: The MIME type of the media content when providing raw bytes or reading from a file.
143            content_bytes: Raw bytes of the media content.
144            file_path: The path to the file containing the media content. For relative paths,
145                the current working directory is used.
146        """
147        self.obj = obj
148
149        if base64_data_uri is not None:
150            parsed_data = self._parse_base64_data_uri(base64_data_uri)
151            self._content_bytes, self._content_type = parsed_data
152            self._source = "base64_data_uri"
153
154        elif content_bytes is not None and content_type is not None:
155            self._content_type = content_type
156            self._content_bytes = content_bytes
157            self._source = "bytes"
158        elif (
159            file_path is not None
160            and content_type is not None
161            and os.path.exists(file_path)
162        ):
163            self._content_bytes = self._read_file(file_path)
164            self._content_type = content_type if self._content_bytes else None
165            self._source = "file" if self._content_bytes else None
166        else:
167            logger.error(
168                "base64_data_uri, or content_bytes and content_type, or file_path must be provided to LangfuseMedia"
169            )
170
171            self._content_bytes = None
172            self._content_type = None
173            self._source = None
174
175        self._media_id = self._get_media_id()
176
177    def _read_file(self, file_path: str) -> Optional[bytes]:
178        try:
179            with open(file_path, "rb") as file:
180                return file.read()
181        except Exception as e:
182            logger.error(f"Error reading file at path {file_path}", exc_info=e)
183
184            return None
185
186    def _get_media_id(self) -> Optional[str]:
187        content_hash = self._content_sha256_hash
188
189        if content_hash is None:
190            return None
191
192        # Convert hash to base64Url
193        url_safe_content_hash = content_hash.replace("+", "-").replace("/", "_")
194
195        return url_safe_content_hash[:22]
196
197    @property
198    def _content_length(self) -> Optional[int]:
199        return len(self._content_bytes) if self._content_bytes else None
200
201    @property
202    def _content_sha256_hash(self) -> Optional[str]:
203        if self._content_bytes is None:
204            return None
205
206        sha256_hash_bytes = hashlib.sha256(self._content_bytes).digest()
207
208        return base64.b64encode(sha256_hash_bytes).decode("utf-8")
209
210    @property
211    def _reference_string(self) -> Optional[str]:
212        if self._content_type is None or self._source is None or self._media_id is None:
213            return None
214
215        return f"@@@langfuseMedia:type={self._content_type}|id={self._media_id}|source={self._source}@@@"
216
217    @staticmethod
218    def parse_reference_string(reference_string: str) -> ParsedMediaReference:
219        """Parse a media reference string into a ParsedMediaReference.
220
221        Example reference string:
222            "@@@langfuseMedia:type=image/jpeg|id=some-uuid|source=base64_data_uri@@@"
223
224        Args:
225            reference_string: The reference string to parse.
226
227        Returns:
228            A TypedDict with the media_id, source, and content_type.
229
230        Raises:
231            ValueError: If the reference string is empty or not a string.
232            ValueError: If the reference string does not start with "@@@langfuseMedia:type=".
233            ValueError: If the reference string does not end with "@@@".
234            ValueError: If the reference string is missing required fields.
235        """
236        if not reference_string:
237            raise ValueError("Reference string is empty")
238
239        if not isinstance(reference_string, str):
240            raise ValueError("Reference string is not a string")
241
242        if not reference_string.startswith("@@@langfuseMedia:type="):
243            raise ValueError(
244                "Reference string does not start with '@@@langfuseMedia:type='"
245            )
246
247        if not reference_string.endswith("@@@"):
248            raise ValueError("Reference string does not end with '@@@'")
249
250        content = reference_string[len("@@@langfuseMedia:") :].rstrip("@@@")
251
252        # Split into key-value pairs
253        pairs = content.split("|")
254        parsed_data = {}
255
256        for pair in pairs:
257            key, value = pair.split("=", 1)
258            parsed_data[key] = value
259
260        # Verify all required fields are present
261        if not all(key in parsed_data for key in ["type", "id", "source"]):
262            raise ValueError("Missing required fields in reference string")
263
264        return ParsedMediaReference(
265            media_id=parsed_data["id"],
266            source=parsed_data["source"],
267            content_type=cast(MediaContentType, parsed_data["type"]),
268        )
269
270    def _parse_base64_data_uri(
271        self, data: str
272    ) -> Tuple[Optional[bytes], Optional[MediaContentType]]:
273        # Example data URI: data:image/jpeg;base64,/9j/4AAQ...
274        try:
275            if not data or not isinstance(data, str):
276                raise ValueError("Data URI is not a string")
277
278            if not data.startswith("data:"):
279                raise ValueError("Data URI does not start with 'data:'")
280
281            header, actual_data = data[5:].split(",", 1)
282            if not header or not actual_data:
283                raise ValueError("Invalid URI")
284
285            # Split header into parts and check for base64
286            header_parts = header.split(";")
287            if "base64" not in header_parts:
288                raise ValueError("Data is not base64 encoded")
289
290            # Content type is the first part
291            content_type = header_parts[0]
292            if not content_type:
293                raise ValueError("Content type is empty")
294
295            return base64.b64decode(actual_data), cast(MediaContentType, content_type)
296
297        except Exception as e:
298            logger.error("Error parsing base64 data URI", exc_info=e)
299
300            return None, None
301
302    @staticmethod
303    def resolve_media_references(
304        *,
305        obj: T,
306        langfuse_client: "Langfuse",
307        resolve_with: Literal["base64_data_uri"],
308        max_depth: int = 10,
309        content_fetch_timeout_seconds: int = 10,
310    ) -> T:
311        """Replace media reference strings in an object with base64 data URIs.
312
313        This method recursively traverses an object (up to max_depth) looking for media reference strings
314        in the format "@@@langfuseMedia:...@@@". When found, it (synchronously) fetches the actual media content using
315        the provided Langfuse client and replaces the reference string with a base64 data URI.
316
317        If fetching media content fails for a reference string, a warning is logged and the reference
318        string is left unchanged.
319
320        Args:
321            obj: The object to process. Can be a primitive value, array, or nested object.
322                If the object has a __dict__ attribute, a dict will be returned instead of the original object type.
323            langfuse_client: Langfuse client instance used to fetch media content.
324            resolve_with: The representation of the media content to replace the media reference string with.
325                Currently only "base64_data_uri" is supported.
326            max_depth: Optional. Default is 10. The maximum depth to traverse the object.
327
328        Returns:
329            A deep copy of the input object with all media references replaced with base64 data URIs where possible.
330            If the input object has a __dict__ attribute, a dict will be returned instead of the original object type.
331
332        Example:
333            obj = {
334                "image": "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@",
335                "nested": {
336                    "pdf": "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@"
337                }
338            }
339
340            result = await LangfuseMedia.resolve_media_references(obj, langfuse_client)
341
342            # Result:
343            # {
344            #     "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
345            #     "nested": {
346            #         "pdf": "data:application/pdf;base64,JVBERi0xLjcK..."
347            #     }
348            # }
349        """
350
351        def traverse(obj: Any, depth: int) -> Any:
352            if depth > max_depth:
353                return obj
354
355            # Handle string
356            if isinstance(obj, str):
357                regex = r"@@@langfuseMedia:.+?@@@"
358                reference_string_matches = re.findall(regex, obj)
359                if len(reference_string_matches) == 0:
360                    return obj
361
362                result = obj
363                reference_string_to_media_content = {}
364                httpx_client = (
365                    langfuse_client._resources.httpx_client
366                    if langfuse_client._resources is not None
367                    else None
368                )
369
370                for reference_string in reference_string_matches:
371                    try:
372                        parsed_media_reference = LangfuseMedia.parse_reference_string(
373                            reference_string
374                        )
375                        media_data = langfuse_client.api.media.get(
376                            parsed_media_reference["media_id"]
377                        )
378                        media_content = (
379                            httpx_client.get(
380                                media_data.url,
381                                timeout=content_fetch_timeout_seconds,
382                            )
383                            if httpx_client is not None
384                            else httpx.get(
385                                media_data.url, timeout=content_fetch_timeout_seconds
386                            )
387                        )
388                        media_content.raise_for_status()
389
390                        base64_media_content = base64.b64encode(
391                            media_content.content
392                        ).decode()
393                        base64_data_uri = f"data:{media_data.content_type};base64,{base64_media_content}"
394
395                        reference_string_to_media_content[reference_string] = (
396                            base64_data_uri
397                        )
398                    except Exception as e:
399                        logger.warning(
400                            f"Error fetching media content for reference string {reference_string}: {e}"
401                        )
402                        # Do not replace the reference string if there's an error
403                        continue
404
405                for (
406                    ref_str,
407                    media_content_str,
408                ) in reference_string_to_media_content.items():
409                    result = result.replace(ref_str, media_content_str)
410
411                return result
412
413            # Handle arrays
414            if isinstance(obj, list):
415                return [traverse(item, depth + 1) for item in obj]
416
417            # Handle dictionaries
418            if isinstance(obj, dict):
419                return {key: traverse(value, depth + 1) for key, value in obj.items()}
420
421            # Handle objects:
422            if hasattr(obj, "__dict__"):
423                return {
424                    key: traverse(value, depth + 1)
425                    for key, value in obj.__dict__.items()
426                }
427
428            return obj
429
430        return cast(T, traverse(obj, 0))

A class for wrapping media objects for upload to Langfuse.

This class handles the preparation and formatting of media content for Langfuse, supporting both base64 data URIs and raw content bytes.

Arguments:
  • obj (Optional[object]): The source object to be wrapped. Can be accessed via the obj attribute.
  • base64_data_uri (Optional[str]): A base64-encoded data URI containing the media content and content type (e.g., "data:image/jpeg;base64,/9j/4AAQ...").
  • content_type (Optional[str]): The MIME type of the media content when providing raw bytes.
  • content_bytes (Optional[bytes]): Raw bytes of the media content.
  • file_path (Optional[str]): The path to the file containing the media content. For relative paths, the current working directory is used.
Raises:
  • ValueError: If neither base64_data_uri or the combination of content_bytes and content_type is provided.
LangfuseMedia( *, obj: Optional[object] = None, base64_data_uri: Optional[str] = None, content_type: Optional[langfuse.api.MediaContentType] = None, content_bytes: Optional[bytes] = None, file_path: Optional[str] = None) 
126    def __init__(
127        self,
128        *,
129        obj: Optional[object] = None,
130        base64_data_uri: Optional[str] = None,
131        content_type: Optional[MediaContentType] = None,
132        content_bytes: Optional[bytes] = None,
133        file_path: Optional[str] = None,
134    ):
135        """Initialize a LangfuseMedia object.
136
137        Args:
138            obj: The object to wrap.
139
140            base64_data_uri: A base64-encoded data URI containing the media content
141                and content type (e.g., "data:image/jpeg;base64,/9j/4AAQ...").
142            content_type: The MIME type of the media content when providing raw bytes or reading from a file.
143            content_bytes: Raw bytes of the media content.
144            file_path: The path to the file containing the media content. For relative paths,
145                the current working directory is used.
146        """
147        self.obj = obj
148
149        if base64_data_uri is not None:
150            parsed_data = self._parse_base64_data_uri(base64_data_uri)
151            self._content_bytes, self._content_type = parsed_data
152            self._source = "base64_data_uri"
153
154        elif content_bytes is not None and content_type is not None:
155            self._content_type = content_type
156            self._content_bytes = content_bytes
157            self._source = "bytes"
158        elif (
159            file_path is not None
160            and content_type is not None
161            and os.path.exists(file_path)
162        ):
163            self._content_bytes = self._read_file(file_path)
164            self._content_type = content_type if self._content_bytes else None
165            self._source = "file" if self._content_bytes else None
166        else:
167            logger.error(
168                "base64_data_uri, or content_bytes and content_type, or file_path must be provided to LangfuseMedia"
169            )
170
171            self._content_bytes = None
172            self._content_type = None
173            self._source = None
174
175        self._media_id = self._get_media_id()

Initialize a LangfuseMedia object.

Arguments:
  • obj: The object to wrap.
  • base64_data_uri: A base64-encoded data URI containing the media content and content type (e.g., "data:image/jpeg;base64,/9j/4AAQ...").
  • content_type: The MIME type of the media content when providing raw bytes or reading from a file.
  • content_bytes: Raw bytes of the media content.
  • file_path: The path to the file containing the media content. For relative paths, the current working directory is used.
obj: object
@staticmethod
def parse_reference_string(reference_string: str) -> langfuse.types.ParsedMediaReference: 
217    @staticmethod
218    def parse_reference_string(reference_string: str) -> ParsedMediaReference:
219        """Parse a media reference string into a ParsedMediaReference.
220
221        Example reference string:
222            "@@@langfuseMedia:type=image/jpeg|id=some-uuid|source=base64_data_uri@@@"
223
224        Args:
225            reference_string: The reference string to parse.
226
227        Returns:
228            A TypedDict with the media_id, source, and content_type.
229
230        Raises:
231            ValueError: If the reference string is empty or not a string.
232            ValueError: If the reference string does not start with "@@@langfuseMedia:type=".
233            ValueError: If the reference string does not end with "@@@".
234            ValueError: If the reference string is missing required fields.
235        """
236        if not reference_string:
237            raise ValueError("Reference string is empty")
238
239        if not isinstance(reference_string, str):
240            raise ValueError("Reference string is not a string")
241
242        if not reference_string.startswith("@@@langfuseMedia:type="):
243            raise ValueError(
244                "Reference string does not start with '@@@langfuseMedia:type='"
245            )
246
247        if not reference_string.endswith("@@@"):
248            raise ValueError("Reference string does not end with '@@@'")
249
250        content = reference_string[len("@@@langfuseMedia:") :].rstrip("@@@")
251
252        # Split into key-value pairs
253        pairs = content.split("|")
254        parsed_data = {}
255
256        for pair in pairs:
257            key, value = pair.split("=", 1)
258            parsed_data[key] = value
259
260        # Verify all required fields are present
261        if not all(key in parsed_data for key in ["type", "id", "source"]):
262            raise ValueError("Missing required fields in reference string")
263
264        return ParsedMediaReference(
265            media_id=parsed_data["id"],
266            source=parsed_data["source"],
267            content_type=cast(MediaContentType, parsed_data["type"]),
268        )

Parse a media reference string into a ParsedMediaReference.

Example reference string:

"@@@langfuseMedia:type=image/jpeg|id=some-uuid|source=base64_data_uri@@@"

Arguments:
  • reference_string: The reference string to parse.
Returns:

A TypedDict with the media_id, source, and content_type.

Raises:
  • ValueError: If the reference string is empty or not a string.
  • ValueError: If the reference string does not start with "@@@langfuseMedia:type=".
  • ValueError: If the reference string does not end with "@@@".
  • ValueError: If the reference string is missing required fields.
@staticmethod
def resolve_media_references( *, obj: ~T, langfuse_client: Langfuse, resolve_with: Literal['base64_data_uri'], max_depth: int = 10, content_fetch_timeout_seconds: int = 10) -> ~T: 
302    @staticmethod
303    def resolve_media_references(
304        *,
305        obj: T,
306        langfuse_client: "Langfuse",
307        resolve_with: Literal["base64_data_uri"],
308        max_depth: int = 10,
309        content_fetch_timeout_seconds: int = 10,
310    ) -> T:
311        """Replace media reference strings in an object with base64 data URIs.
312
313        This method recursively traverses an object (up to max_depth) looking for media reference strings
314        in the format "@@@langfuseMedia:...@@@". When found, it (synchronously) fetches the actual media content using
315        the provided Langfuse client and replaces the reference string with a base64 data URI.
316
317        If fetching media content fails for a reference string, a warning is logged and the reference
318        string is left unchanged.
319
320        Args:
321            obj: The object to process. Can be a primitive value, array, or nested object.
322                If the object has a __dict__ attribute, a dict will be returned instead of the original object type.
323            langfuse_client: Langfuse client instance used to fetch media content.
324            resolve_with: The representation of the media content to replace the media reference string with.
325                Currently only "base64_data_uri" is supported.
326            max_depth: Optional. Default is 10. The maximum depth to traverse the object.
327
328        Returns:
329            A deep copy of the input object with all media references replaced with base64 data URIs where possible.
330            If the input object has a __dict__ attribute, a dict will be returned instead of the original object type.
331
332        Example:
333            obj = {
334                "image": "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@",
335                "nested": {
336                    "pdf": "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@"
337                }
338            }
339
340            result = await LangfuseMedia.resolve_media_references(obj, langfuse_client)
341
342            # Result:
343            # {
344            #     "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
345            #     "nested": {
346            #         "pdf": "data:application/pdf;base64,JVBERi0xLjcK..."
347            #     }
348            # }
349        """
350
351        def traverse(obj: Any, depth: int) -> Any:
352            if depth > max_depth:
353                return obj
354
355            # Handle string
356            if isinstance(obj, str):
357                regex = r"@@@langfuseMedia:.+?@@@"
358                reference_string_matches = re.findall(regex, obj)
359                if len(reference_string_matches) == 0:
360                    return obj
361
362                result = obj
363                reference_string_to_media_content = {}
364                httpx_client = (
365                    langfuse_client._resources.httpx_client
366                    if langfuse_client._resources is not None
367                    else None
368                )
369
370                for reference_string in reference_string_matches:
371                    try:
372                        parsed_media_reference = LangfuseMedia.parse_reference_string(
373                            reference_string
374                        )
375                        media_data = langfuse_client.api.media.get(
376                            parsed_media_reference["media_id"]
377                        )
378                        media_content = (
379                            httpx_client.get(
380                                media_data.url,
381                                timeout=content_fetch_timeout_seconds,
382                            )
383                            if httpx_client is not None
384                            else httpx.get(
385                                media_data.url, timeout=content_fetch_timeout_seconds
386                            )
387                        )
388                        media_content.raise_for_status()
389
390                        base64_media_content = base64.b64encode(
391                            media_content.content
392                        ).decode()
393                        base64_data_uri = f"data:{media_data.content_type};base64,{base64_media_content}"
394
395                        reference_string_to_media_content[reference_string] = (
396                            base64_data_uri
397                        )
398                    except Exception as e:
399                        logger.warning(
400                            f"Error fetching media content for reference string {reference_string}: {e}"
401                        )
402                        # Do not replace the reference string if there's an error
403                        continue
404
405                for (
406                    ref_str,
407                    media_content_str,
408                ) in reference_string_to_media_content.items():
409                    result = result.replace(ref_str, media_content_str)
410
411                return result
412
413            # Handle arrays
414            if isinstance(obj, list):
415                return [traverse(item, depth + 1) for item in obj]
416
417            # Handle dictionaries
418            if isinstance(obj, dict):
419                return {key: traverse(value, depth + 1) for key, value in obj.items()}
420
421            # Handle objects:
422            if hasattr(obj, "__dict__"):
423                return {
424                    key: traverse(value, depth + 1)
425                    for key, value in obj.__dict__.items()
426                }
427
428            return obj
429
430        return cast(T, traverse(obj, 0))

Replace media reference strings in an object with base64 data URIs.

This method recursively traverses an object (up to max_depth) looking for media reference strings in the format "@@@langfuseMedia:...@@@". When found, it (synchronously) fetches the actual media content using the provided Langfuse client and replaces the reference string with a base64 data URI.

If fetching media content fails for a reference string, a warning is logged and the reference string is left unchanged.

Arguments:
  • obj: The object to process. Can be a primitive value, array, or nested object. If the object has a __dict__ attribute, a dict will be returned instead of the original object type.
  • langfuse_client: Langfuse client instance used to fetch media content.
  • resolve_with: The representation of the media content to replace the media reference string with. Currently only "base64_data_uri" is supported.
  • max_depth: Optional. Default is 10. The maximum depth to traverse the object.
Returns:

A deep copy of the input object with all media references replaced with base64 data URIs where possible. If the input object has a __dict__ attribute, a dict will be returned instead of the original object type.

Example:

obj = { "image": "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@", "nested": { "pdf": "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@" } }

result = await LangfuseMedia.resolve_media_references(obj, langfuse_client)

Result:

{

"image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",

"nested": {

"pdf": "data:application/pdf;base64,JVBERi0xLjcK..."

}

}

@dataclass(frozen=True)
class LangfuseMediaReference: 
24@dataclass(frozen=True)
25class LangfuseMediaReference:
26    """Resolved reference to media stored in Langfuse."""
27
28    media_id: str
29    content_type: str
30    url: str
31    url_expiry: Optional[str] = None
32    content_length: Optional[int] = None
33    reference_string: Optional[str] = None
34
35    def is_url_expired(self) -> bool:
36        """Return whether the signed URL is already expired."""
37        if self.url_expiry is None:
38            return False
39
40        expiry = self.url_expiry.replace("Z", "+00:00")
41
42        try:
43            expiry_datetime = datetime.fromisoformat(expiry)
44        except ValueError:
45            return False
46
47        if expiry_datetime.tzinfo is None:
48            expiry_datetime = expiry_datetime.replace(tzinfo=timezone.utc)
49
50        return expiry_datetime <= datetime.now(timezone.utc)
51
52    def fetch_bytes(
53        self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None
54    ) -> bytes:
55        """Fetch the media content from the signed URL.
56
57        Args:
58            timeout: Request timeout in seconds.
59            client: Optional httpx client to use for the request. Pass this to
60                honor custom transport settings (proxy, CA bundle, mTLS) — in
61                particular when multiple Langfuse clients are configured, since
62                the SDK cannot otherwise tell which client produced this
63                reference. When omitted, the single configured client is used,
64                falling back to a default httpx client.
65        """
66        from langfuse._client.resource_manager import LangfuseResourceManager
67
68        httpx_client = client or LangfuseResourceManager.get_singleton_httpx_client()
69        response = (
70            httpx_client.get(self.url, timeout=timeout)
71            if httpx_client is not None
72            else httpx.get(self.url, timeout=timeout)
73        )
74        response.raise_for_status()
75
76        return response.content
77
78    def fetch_base64(
79        self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None
80    ) -> str:
81        """Fetch media and return raw base64 without a data URI prefix.
82
83        See :meth:`fetch_bytes` for the ``client`` argument.
84        """
85        return base64.b64encode(
86            self.fetch_bytes(timeout=timeout, client=client)
87        ).decode()
88
89    def fetch_data_uri(
90        self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None
91    ) -> str:
92        """Fetch media and return it as a data URI.
93
94        See :meth:`fetch_bytes` for the ``client`` argument.
95        """
96        return f"data:{self.content_type};base64,{self.fetch_base64(timeout=timeout, client=client)}"

Resolved reference to media stored in Langfuse.

LangfuseMediaReference( media_id: str, content_type: str, url: str, url_expiry: Optional[str] = None, content_length: Optional[int] = None, reference_string: Optional[str] = None)
media_id: str
content_type: str
url: str
url_expiry: Optional[str] = None
content_length: Optional[int] = None
reference_string: Optional[str] = None
def is_url_expired(self) -> bool: 
35    def is_url_expired(self) -> bool:
36        """Return whether the signed URL is already expired."""
37        if self.url_expiry is None:
38            return False
39
40        expiry = self.url_expiry.replace("Z", "+00:00")
41
42        try:
43            expiry_datetime = datetime.fromisoformat(expiry)
44        except ValueError:
45            return False
46
47        if expiry_datetime.tzinfo is None:
48            expiry_datetime = expiry_datetime.replace(tzinfo=timezone.utc)
49
50        return expiry_datetime <= datetime.now(timezone.utc)

Return whether the signed URL is already expired.

def fetch_bytes( self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None) -> bytes: 
52    def fetch_bytes(
53        self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None
54    ) -> bytes:
55        """Fetch the media content from the signed URL.
56
57        Args:
58            timeout: Request timeout in seconds.
59            client: Optional httpx client to use for the request. Pass this to
60                honor custom transport settings (proxy, CA bundle, mTLS) — in
61                particular when multiple Langfuse clients are configured, since
62                the SDK cannot otherwise tell which client produced this
63                reference. When omitted, the single configured client is used,
64                falling back to a default httpx client.
65        """
66        from langfuse._client.resource_manager import LangfuseResourceManager
67
68        httpx_client = client or LangfuseResourceManager.get_singleton_httpx_client()
69        response = (
70            httpx_client.get(self.url, timeout=timeout)
71            if httpx_client is not None
72            else httpx.get(self.url, timeout=timeout)
73        )
74        response.raise_for_status()
75
76        return response.content

Fetch the media content from the signed URL.

Arguments:
  • timeout: Request timeout in seconds.
  • client: Optional httpx client to use for the request. Pass this to honor custom transport settings (proxy, CA bundle, mTLS) — in particular when multiple Langfuse clients are configured, since the SDK cannot otherwise tell which client produced this reference. When omitted, the single configured client is used, falling back to a default httpx client.
def fetch_base64( self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None) -> str: 
78    def fetch_base64(
79        self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None
80    ) -> str:
81        """Fetch media and return raw base64 without a data URI prefix.
82
83        See :meth:`fetch_bytes` for the ``client`` argument.
84        """
85        return base64.b64encode(
86            self.fetch_bytes(timeout=timeout, client=client)
87        ).decode()

Fetch media and return raw base64 without a data URI prefix.

See fetch_bytes() for the client argument.

def fetch_data_uri( self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None) -> str: 
89    def fetch_data_uri(
90        self, *, timeout: float = 30.0, client: Optional[httpx.Client] = None
91    ) -> str:
92        """Fetch media and return it as a data URI.
93
94        See :meth:`fetch_bytes` for the ``client`` argument.
95        """
96        return f"data:{self.content_type};base64,{self.fetch_base64(timeout=timeout, client=client)}"

Fetch media and return it as a data URI.

See fetch_bytes() for the client argument.

def get_client(*, public_key: Optional[str] = None) -> Langfuse: 
 65def get_client(*, public_key: Optional[str] = None) -> Langfuse:
 66    """Get or create a Langfuse client instance.
 67
 68    Returns an existing Langfuse client or creates a new one if none exists. In multi-project setups,
 69    providing a public_key is required. Multi-project support is experimental - see Langfuse docs.
 70
 71    Behavior:
 72    - Single project: Returns existing client or creates new one
 73    - Multi-project: Requires public_key to return specific client
 74    - No public_key in multi-project: Returns disabled client to prevent data leakage
 75
 76    The function uses a singleton pattern per public_key to conserve resources and maintain state.
 77
 78    Args:
 79        public_key (Optional[str]): Project identifier
 80            - With key: Returns client for that project
 81            - Without key: Returns single client or disabled client if multiple exist
 82
 83    Returns:
 84        Langfuse: Client instance in one of three states:
 85            1. Client for specified public_key
 86            2. Default client for single-project setup
 87            3. Disabled client when multiple projects exist without key
 88
 89    Security:
 90        Disables tracing when multiple projects exist without explicit key to prevent
 91        cross-project data leakage. Multi-project setups are experimental.
 92
 93    Example:
 94        ```python
 95        # Single project
 96        client = get_client()  # Default client
 97
 98        # In multi-project usage:
 99        client_a = get_client(public_key="project_a_key")  # Returns project A's client
100        client_b = get_client(public_key="project_b_key")  # Returns project B's client
101
102        # Without specific key in multi-project setup:
103        client = get_client()  # Returns disabled client for safety
104        ```
105    """
106    with LangfuseResourceManager._lock:
107        active_instances = LangfuseResourceManager._instances
108
109        # If no explicit public_key provided, check execution context
110        if not public_key:
111            public_key = _current_public_key.get(None)
112
113        if not public_key:
114            if len(active_instances) == 0:
115                # No clients initialized yet, create default instance
116                return Langfuse()
117
118            if len(active_instances) == 1:
119                # Only one client exists, safe to use without specifying key
120                instance = list(active_instances.values())[0]
121
122                # Initialize with the credentials bound to the instance
123                # This is important if the original instance was instantiated
124                # via constructor arguments
125                return _create_client_from_instance(instance)
126
127            else:
128                # Multiple clients exist but no key specified - disable tracing
129                # to prevent cross-project data leakage
130                langfuse_logger.warning(
131                    "No 'langfuse_public_key' passed to decorated function, but multiple langfuse clients are instantiated in current process. Skipping tracing for this function to avoid cross-project leakage."
132                )
133                return Langfuse(
134                    tracing_enabled=False, public_key="fake", secret_key="fake"
135                )
136
137        else:
138            # Specific key provided, look up existing instance
139            target_instance: Optional[LangfuseResourceManager] = active_instances.get(
140                public_key, None
141            )
142
143            if target_instance is None:
144                # No instance found with this key - client not initialized properly
145                langfuse_logger.warning(
146                    f"No Langfuse client with public key {public_key} has been initialized. Skipping tracing for decorated function."
147                )
148                return Langfuse(
149                    tracing_enabled=False, public_key="fake", secret_key="fake"
150                )
151
152            # target_instance is guaranteed to be not None at this point
153            return _create_client_from_instance(target_instance, public_key)

Get or create a Langfuse client instance.

Returns an existing Langfuse client or creates a new one if none exists. In multi-project setups, providing a public_key is required. Multi-project support is experimental - see Langfuse docs.

Behavior:

  • Single project: Returns existing client or creates new one
  • Multi-project: Requires public_key to return specific client
  • No public_key in multi-project: Returns disabled client to prevent data leakage

The function uses a singleton pattern per public_key to conserve resources and maintain state.

Arguments:
  • public_key (Optional[str]): Project identifier
    • With key: Returns client for that project
    • Without key: Returns single client or disabled client if multiple exist
Returns:

Langfuse: Client instance in one of three states: 1. Client for specified public_key 2. Default client for single-project setup 3. Disabled client when multiple projects exist without key

Security:

Disables tracing when multiple projects exist without explicit key to prevent cross-project data leakage. Multi-project setups are experimental.

Example:
# Single project
client = get_client()  # Default client

# In multi-project usage:
client_a = get_client(public_key="project_a_key")  # Returns project A's client
client_b = get_client(public_key="project_b_key")  # Returns project B's client

# Without specific key in multi-project setup:
client = get_client()  # Returns disabled client for safety
def observe( func: Optional[~F] = None, *, name: Optional[str] = None, as_type: Union[Literal['generation', 'embedding'], Literal['span', 'agent', 'tool', 'chain', 'retriever', 'evaluator', 'guardrail'], NoneType] = None, capture_input: Optional[bool] = None, capture_output: Optional[bool] = None, transform_to_string: Optional[Callable[[Iterable], str]] = None) -> Union[~F, Callable[[~F], ~F]]: 
 88    def observe(
 89        self,
 90        func: Optional[F] = None,
 91        *,
 92        name: Optional[str] = None,
 93        as_type: Optional[ObservationTypeLiteralNoEvent] = None,
 94        capture_input: Optional[bool] = None,
 95        capture_output: Optional[bool] = None,
 96        transform_to_string: Optional[Callable[[Iterable], str]] = None,
 97    ) -> Union[F, Callable[[F], F]]:
 98        """Wrap a function to create and manage Langfuse tracing around its execution, supporting both synchronous and asynchronous functions.
 99
100        This decorator provides seamless integration of Langfuse observability into your codebase. It automatically creates
101        spans or generations around function execution, capturing timing, inputs/outputs, and error states. The decorator
102        intelligently handles both synchronous and asynchronous functions, preserving function signatures and type hints.
103
104        Using OpenTelemetry's distributed tracing system, it maintains proper trace context propagation throughout your application,
105        enabling you to see hierarchical traces of function calls with detailed performance metrics and function-specific details.
106
107        Args:
108            func (Optional[Callable]): The function to decorate. When used with parentheses @observe(), this will be None.
109            name (Optional[str]): Custom name for the created trace or span. If not provided, the function name is used.
110            as_type (Optional[Literal]): Set the observation type. Supported values:
111                    "generation", "span", "agent", "tool", "chain", "retriever", "embedding", "evaluator", "guardrail".
112                    Observation types are highlighted in the Langfuse UI for filtering and visualization.
113                    The types "generation" and "embedding" create a span on which additional attributes such as model,
114                    usage_details, and cost_details can be set — use `as_type="generation"` for LLM calls and update the
115                    observation via `langfuse.update_current_generation(...)` inside the function.
116            capture_input (Optional[bool]): Whether to capture the function's arguments as the observation's input.
117                    Defaults to the LANGFUSE_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED environment variable (True if unset).
118                    Set to False for sensitive or very large inputs, then set input explicitly via
119                    `langfuse.update_current_span(input=...)` if needed.
120            capture_output (Optional[bool]): Whether to capture the function's return value as the observation's output.
121                    Same default and override mechanism as capture_input.
122            transform_to_string (Optional[Callable[[Iterable], str]]): For functions returning generators, joins the
123                    yielded chunks into the string stored as output. Without it, chunks are concatenated if all are
124                    strings, otherwise stored as a list.
125
126        Returns:
127            Callable: A wrapped version of the original function that automatically creates and manages Langfuse spans.
128
129        Example:
130            For general function tracing with automatic naming:
131            ```python
132            @observe()
133            def process_user_request(user_id, query):
134                # Function is automatically traced with name "process_user_request"
135                return get_response(query)
136            ```
137
138            For language model generation tracking:
139            ```python
140            from langfuse import get_client, observe
141
142            @observe(name="answer-generation", as_type="generation")
143            async def generate_answer(query):
144                # Creates a generation-type observation with extended LLM metrics
145                response = await openai.chat.completions.create(
146                    model="gpt-4",
147                    messages=[{"role": "user", "content": query}]
148                )
149                return response.choices[0].message.content
150            ```
151
152            Disabling input/output capture (e.g. for sensitive or large payloads):
153            ```python
154            @observe(capture_input=False, capture_output=False)
155            def handle_pii(user_record):
156                return process(user_record)
157            ```
158
159            For trace context propagation between functions:
160            ```python
161            @observe()
162            def main_process():
163                # Parent span is created
164                return sub_process()  # Child span automatically connected to parent
165
166            @observe()
167            def sub_process():
168                # Automatically becomes a child span of main_process
169                return "result"
170            ```
171
172        Raises:
173            Exception: Propagates any exceptions from the wrapped function after logging them in the trace.
174
175        Notes:
176            - The decorator preserves the original function's signature, docstring, and return type.
177            - Proper parent-child relationships between spans are automatically maintained.
178            - Special keyword arguments can be passed to control tracing:
179              - langfuse_trace_id: Explicitly set the trace ID for this function call
180              - langfuse_parent_observation_id: Explicitly set the parent span ID
181              - langfuse_public_key: Use a specific Langfuse project (when multiple clients exist)
182            - For async functions, the decorator returns an async function wrapper.
183            - For sync functions, the decorator returns a synchronous wrapper.
184        """
185        valid_types = set(get_observation_types_list(ObservationTypeLiteralNoEvent))
186        if as_type is not None and as_type not in valid_types:
187            logger.warning(
188                f"Invalid as_type '{as_type}'. Valid types are: {', '.join(sorted(valid_types))}. Defaulting to 'span'."
189            )
190            as_type = "span"
191
192        function_io_capture_enabled = os.environ.get(
193            LANGFUSE_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED, "True"
194        ).lower() not in ("false", "0")
195
196        should_capture_input = (
197            capture_input if capture_input is not None else function_io_capture_enabled
198        )
199
200        should_capture_output = (
201            capture_output
202            if capture_output is not None
203            else function_io_capture_enabled
204        )
205
206        def decorator(func: F) -> F:
207            return (
208                self._async_observe(
209                    func,
210                    name=name,
211                    as_type=as_type,
212                    capture_input=should_capture_input,
213                    capture_output=should_capture_output,
214                    transform_to_string=transform_to_string,
215                )
216                if asyncio.iscoroutinefunction(func)
217                else self._sync_observe(
218                    func,
219                    name=name,
220                    as_type=as_type,
221                    capture_input=should_capture_input,
222                    capture_output=should_capture_output,
223                    transform_to_string=transform_to_string,
224                )
225            )
226
227        """Handle decorator with or without parentheses.
228
229        This logic enables the decorator to work both with and without parentheses:
230        - @observe - Python passes the function directly to the decorator
231        - @observe() - Python calls the decorator first, which must return a function decorator
232
233        When called without arguments (@observe), the func parameter contains the function to decorate,
234        so we directly apply the decorator to it. When called with parentheses (@observe()),
235        func is None, so we return the decorator function itself for Python to apply in the next step.
236        """
237        if func is None:
238            return decorator
239        else:
240            return decorator(func)

Wrap a function to create and manage Langfuse tracing around its execution, supporting both synchronous and asynchronous functions.

This decorator provides seamless integration of Langfuse observability into your codebase. It automatically creates spans or generations around function execution, capturing timing, inputs/outputs, and error states. The decorator intelligently handles both synchronous and asynchronous functions, preserving function signatures and type hints.

Using OpenTelemetry's distributed tracing system, it maintains proper trace context propagation throughout your application, enabling you to see hierarchical traces of function calls with detailed performance metrics and function-specific details.

Arguments:
  • func (Optional[Callable]): The function to decorate. When used with parentheses @observe(), this will be None.
  • name (Optional[str]): Custom name for the created trace or span. If not provided, the function name is used.
  • as_type (Optional[Literal]): Set the observation type. Supported values: "generation", "span", "agent", "tool", "chain", "retriever", "embedding", "evaluator", "guardrail". Observation types are highlighted in the Langfuse UI for filtering and visualization. The types "generation" and "embedding" create a span on which additional attributes such as model, usage_details, and cost_details can be set — use as_type="generation" for LLM calls and update the observation via langfuse.update_current_generation(...) inside the function.
  • capture_input (Optional[bool]): Whether to capture the function's arguments as the observation's input. Defaults to the LANGFUSE_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED environment variable (True if unset). Set to False for sensitive or very large inputs, then set input explicitly via langfuse.update_current_span(input=...) if needed.
  • capture_output (Optional[bool]): Whether to capture the function's return value as the observation's output. Same default and override mechanism as capture_input.
  • transform_to_string (Optional[Callable[[Iterable], str]]): For functions returning generators, joins the yielded chunks into the string stored as output. Without it, chunks are concatenated if all are strings, otherwise stored as a list.
Returns:

Callable: A wrapped version of the original function that automatically creates and manages Langfuse spans.

Example:

For general function tracing with automatic naming:

@observe()
def process_user_request(user_id, query):
    # Function is automatically traced with name "process_user_request"
    return get_response(query)

For language model generation tracking:

from langfuse import get_client, observe

@observe(name="answer-generation", as_type="generation")
async def generate_answer(query):
    # Creates a generation-type observation with extended LLM metrics
    response = await openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": query}]
    )
    return response.choices[0].message.content

Disabling input/output capture (e.g. for sensitive or large payloads):

@observe(capture_input=False, capture_output=False)
def handle_pii(user_record):
    return process(user_record)

For trace context propagation between functions:

@observe()
def main_process():
    # Parent span is created
    return sub_process()  # Child span automatically connected to parent

@observe()
def sub_process():
    # Automatically becomes a child span of main_process
    return "result"
Raises:
  • Exception: Propagates any exceptions from the wrapped function after logging them in the trace.
Notes:
  • The decorator preserves the original function's signature, docstring, and return type.
  • Proper parent-child relationships between spans are automatically maintained.
  • Special keyword arguments can be passed to control tracing:
    • langfuse_trace_id: Explicitly set the trace ID for this function call
    • langfuse_parent_observation_id: Explicitly set the parent span ID
    • langfuse_public_key: Use a specific Langfuse project (when multiple clients exist)
  • For async functions, the decorator returns an async function wrapper.
  • For sync functions, the decorator returns a synchronous wrapper.
def propagate_attributes( *, user_id: Optional[str] = None, session_id: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, version: Optional[str] = None, tags: Optional[List[str]] = None, trace_name: Optional[str] = None, environment: Optional[str] = None, prompt: Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient, Mapping[str, Any], NoneType] = None, as_baggage: bool = False) -> opentelemetry.util._decorator._AgnosticContextManager[typing.Any]: 
115def propagate_attributes(
116    *,
117    user_id: Optional[str] = None,
118    session_id: Optional[str] = None,
119    metadata: Optional[Dict[str, Any]] = None,
120    version: Optional[str] = None,
121    tags: Optional[List[str]] = None,
122    trace_name: Optional[str] = None,
123    environment: Optional[str] = None,
124    prompt: Optional[Union[PromptClient, Mapping[str, Any]]] = None,
125    as_baggage: bool = False,
126) -> _AgnosticContextManager[Any]:
127    """Propagate trace-level attributes to all spans created within this context.
128
129    This context manager sets attributes on the currently active span AND automatically
130    propagates them to all new child spans created within the context. This is the
131    recommended way to set trace-level attributes like user_id, session_id,
132    environment, and metadata dimensions that should be consistently applied across
133    all observations in a trace.
134
135    This is a module-level function, not a method on the Langfuse client:
136    import it with `from langfuse import propagate_attributes`.
137
138    **IMPORTANT**: Call this as early as possible within your trace/workflow —
139    ideally wrapping the creation of your root span, or immediately inside it. Only
140    the currently active span and spans created after entering this context will have
141    these attributes. Pre-existing spans will NOT be retroactively updated.
142
143    **Why this matters**: Langfuse aggregation queries (e.g., total cost by user_id,
144    filtering by session_id) only include observations that have the attribute set.
145    If you call `propagate_attributes` late in your workflow, earlier spans won't be
146    included in aggregations for that attribute.
147
148    Args:
149        user_id: User identifier to associate with all spans in this context.
150            Must be US-ASCII string, ≤200 characters. Use this to track which user
151            generated each trace and enable e.g. per-user cost/performance analysis.
152        session_id: Session identifier to associate with all spans in this context.
153            Must be US-ASCII string, ≤200 characters. Use this to group related traces
154            within a user session (e.g., a conversation thread, multi-turn interaction).
155        metadata: Additional key-value metadata to propagate to all spans.
156            - Keys must be US-ASCII strings
157            - Values are coerced to strings
158            - Coerced values must be ≤200 characters
159            - Use for dimensions like internal correlating identifiers
160            - AVOID: large payloads or sensitive data
161        version: Version identfier for parts of your application that are independently versioned, e.g. agents
162        tags: List of tags to categorize the group of observations
163        trace_name: Name to assign to the trace. Must be US-ASCII string, ≤200 characters.
164            Use this to set a consistent trace name for all spans created within this context.
165        prompt: Langfuse prompt to link to generations created within this context.
166            Accepts a `PromptClient` returned by `langfuse.get_prompt(...)` or any
167            object/dict exposing `name` (string) and `version` (integer) — e.g.
168            `{"name": "my-prompt", "version": 3}`. This is the recommended way to
169            link prompts to generations emitted by auto-instrumentation libraries
170            (e.g. LiteLLM's `langfuse_otel`, OpenAI Agents SDK, OpenInference)
171            where you don't create the generation via the Langfuse SDK yourself.
172            The prompt link is only applied to generation-type observations by the
173            Langfuse backend. Fallback prompts are never linked. An explicit
174            `prompt` passed to `start_observation` / `update_current_generation`
175            takes precedence over the propagated one.
176        environment: Langfuse environment to assign to spans created in this context.
177            Must be a lowercase alphanumeric string with optional hyphens or underscores,
178            must be ≤40 characters, and must not start with "langfuse". This maps to
179            the first-class `langfuse.environment` attribute, not to trace metadata.
180            Use it for request-scoped environments, for example when one shared proxy
181            handles calls from dev, staging, qa, and prod. A propagated environment
182            takes precedence over the local client default configured via
183            `Langfuse(environment=...)` or `LANGFUSE_TRACING_ENVIRONMENT` for spans
184            created while this propagation context is active.
185        as_baggage: If True, propagates attributes using OpenTelemetry baggage for
186            cross-process/service propagation. **Security warning**: When enabled,
187            attribute values are added to HTTP headers on ALL outbound requests.
188            This includes `environment` as the `langfuse_environment` baggage entry.
189            Only enable if values are safe to transmit via HTTP headers and you need
190            cross-service tracing. Default: False.
191
192    Returns:
193        Context manager that propagates attributes to all child spans.
194
195    Example:
196        Basic usage with user and session tracking (note: `propagate_attributes` is a
197        top-level import, not a client method):
198
199        ```python
200        from langfuse import Langfuse, propagate_attributes
201
202        langfuse = Langfuse()
203
204        # Set attributes early: wrap everything inside the root span
205        with langfuse.start_as_current_observation(name="user_workflow") as span:
206            with propagate_attributes(
207                user_id="user_123",
208                session_id="session_abc",
209                environment="production",
210                metadata={"experiment": "variant_a"}
211            ):
212                # All spans created here will have user_id, session_id, environment, and metadata
213                with langfuse.start_as_current_observation(name="llm_call") as llm_span:
214                    # This span inherits user_id, session_id, environment, and experiment metadata
215                    ...
216
217                with langfuse.start_as_current_observation(
218                    name="completion", as_type="generation"
219                ) as gen:
220                    # This span also inherits all attributes
221                    ...
222        ```
223
224        Prompt linking with auto-instrumented libraries:
225
226        ```python
227        from langfuse import Langfuse, propagate_attributes
228
229        langfuse = Langfuse()
230        prompt = langfuse.get_prompt("my-prompt")
231
232        with propagate_attributes(prompt=prompt):
233            # Generations emitted by auto-instrumentation (LiteLLM langfuse_otel,
234            # OpenAI Agents SDK, OpenInference, ...) within this context are
235            # linked to the prompt version.
236            completion = litellm.completion(
237                model="gpt-4o",
238                messages=prompt.compile(topic="chickens"),
239            )
240        ```
241
242        Late propagation (anti-pattern):
243
244        ```python
245        with langfuse.start_as_current_observation(name="workflow") as span:
246            # These spans WON'T have user_id
247            early_span = langfuse.start_observation(name="early_work")
248            early_span.end()
249
250            # Set attributes in the middle
251            with propagate_attributes(user_id="user_123"):
252                # Only spans created AFTER this point will have user_id
253                late_span = langfuse.start_observation(name="late_work")
254                late_span.end()
255
256            # Result: Aggregations by user_id will miss "early_work" span
257        ```
258
259        Cross-service propagation with baggage (advanced):
260
261        ```python
262        # Service A - originating service
263        with langfuse.start_as_current_observation(name="api_request"):
264            with propagate_attributes(
265                user_id="user_123",
266                session_id="session_abc",
267                environment="staging",
268                as_baggage=True  # Propagate via HTTP headers
269            ):
270                # Make HTTP request to Service B
271                response = requests.get("https://service-b.example.com/api")
272                # user_id, session_id, and environment are now in HTTP headers
273
274        # Service B - downstream service
275        # OpenTelemetry will automatically extract baggage from HTTP headers
276        # and propagate attributes to spans in Service B. If Service B has a local
277        # Langfuse environment configured, the propagated environment wins for
278        # spans created within this context.
279        ```
280
281    Note:
282        - **Validation**: Attribute values (user_id, session_id, version, tags,
283          trace_name) must be strings ≤200 characters. Environment must also match
284          Langfuse's environment format: lowercase alphanumeric with optional
285          hyphens or underscores, must be ≤40 characters, and it must not start with "langfuse". Metadata
286          values are coerced to strings before the 200 character limit is applied.
287          Invalid values will be dropped with a warning logged.
288        - **OpenTelemetry**: This uses OpenTelemetry context propagation under the hood,
289          making it compatible with other OTel-instrumented libraries.
290
291    Raises:
292        No exceptions are raised. Invalid values are logged as warnings and dropped.
293
294    See also:
295        `Langfuse.start_as_current_observation` (create the root span this wraps),
296        https://langfuse.com/docs/observability/features/sessions,
297        https://langfuse.com/docs/observability/features/users,
298        https://langfuse.com/docs/observability/features/environments
299    """
300    return _propagate_attributes(
301        user_id=user_id,
302        session_id=session_id,
303        metadata=metadata,
304        version=version,
305        tags=tags,
306        trace_name=trace_name,
307        environment=environment,
308        prompt=prompt,
309        as_baggage=as_baggage,
310    )

Propagate trace-level attributes to all spans created within this context.

This context manager sets attributes on the currently active span AND automatically propagates them to all new child spans created within the context. This is the recommended way to set trace-level attributes like user_id, session_id, environment, and metadata dimensions that should be consistently applied across all observations in a trace.

This is a module-level function, not a method on the Langfuse client: import it with from langfuse import propagate_attributes.

IMPORTANT: Call this as early as possible within your trace/workflow — ideally wrapping the creation of your root span, or immediately inside it. Only the currently active span and spans created after entering this context will have these attributes. Pre-existing spans will NOT be retroactively updated.

Why this matters: Langfuse aggregation queries (e.g., total cost by user_id, filtering by session_id) only include observations that have the attribute set. If you call propagate_attributes late in your workflow, earlier spans won't be included in aggregations for that attribute.

Arguments:
  • user_id: User identifier to associate with all spans in this context. Must be US-ASCII string, ≤200 characters. Use this to track which user generated each trace and enable e.g. per-user cost/performance analysis.
  • session_id: Session identifier to associate with all spans in this context. Must be US-ASCII string, ≤200 characters. Use this to group related traces within a user session (e.g., a conversation thread, multi-turn interaction).
  • metadata: Additional key-value metadata to propagate to all spans.
    • Keys must be US-ASCII strings
    • Values are coerced to strings
    • Coerced values must be ≤200 characters
    • Use for dimensions like internal correlating identifiers
    • AVOID: large payloads or sensitive data
  • version: Version identfier for parts of your application that are independently versioned, e.g. agents
  • tags: List of tags to categorize the group of observations
  • trace_name: Name to assign to the trace. Must be US-ASCII string, ≤200 characters. Use this to set a consistent trace name for all spans created within this context.
  • prompt: Langfuse prompt to link to generations created within this context. Accepts a PromptClient returned by langfuse.get_prompt(...) or any object/dict exposing name (string) and version (integer) — e.g. {"name": "my-prompt", "version": 3}. This is the recommended way to link prompts to generations emitted by auto-instrumentation libraries (e.g. LiteLLM's langfuse_otel, OpenAI Agents SDK, OpenInference) where you don't create the generation via the Langfuse SDK yourself. The prompt link is only applied to generation-type observations by the Langfuse backend. Fallback prompts are never linked. An explicit prompt passed to start_observation / update_current_generation takes precedence over the propagated one.
  • environment: Langfuse environment to assign to spans created in this context. Must be a lowercase alphanumeric string with optional hyphens or underscores, must be ≤40 characters, and must not start with "langfuse". This maps to the first-class langfuse.environment attribute, not to trace metadata. Use it for request-scoped environments, for example when one shared proxy handles calls from dev, staging, qa, and prod. A propagated environment takes precedence over the local client default configured via Langfuse(environment=...) or LANGFUSE_TRACING_ENVIRONMENT for spans created while this propagation context is active.
  • as_baggage: If True, propagates attributes using OpenTelemetry baggage for cross-process/service propagation. Security warning: When enabled, attribute values are added to HTTP headers on ALL outbound requests. This includes environment as the langfuse_environment baggage entry. Only enable if values are safe to transmit via HTTP headers and you need cross-service tracing. Default: False.
Returns:

Context manager that propagates attributes to all child spans.

Example:

Basic usage with user and session tracking (note: propagate_attributes is a top-level import, not a client method):

from langfuse import Langfuse, propagate_attributes

langfuse = Langfuse()

# Set attributes early: wrap everything inside the root span
with langfuse.start_as_current_observation(name="user_workflow") as span:
    with propagate_attributes(
        user_id="user_123",
        session_id="session_abc",
        environment="production",
        metadata={"experiment": "variant_a"}
    ):
        # All spans created here will have user_id, session_id, environment, and metadata
        with langfuse.start_as_current_observation(name="llm_call") as llm_span:
            # This span inherits user_id, session_id, environment, and experiment metadata
            ...

        with langfuse.start_as_current_observation(
            name="completion", as_type="generation"
        ) as gen:
            # This span also inherits all attributes
            ...

Prompt linking with auto-instrumented libraries:

from langfuse import Langfuse, propagate_attributes

langfuse = Langfuse()
prompt = langfuse.get_prompt("my-prompt")

with propagate_attributes(prompt=prompt):
    # Generations emitted by auto-instrumentation (LiteLLM langfuse_otel,
    # OpenAI Agents SDK, OpenInference, ...) within this context are
    # linked to the prompt version.
    completion = litellm.completion(
        model="gpt-4o",
        messages=prompt.compile(topic="chickens"),
    )

Late propagation (anti-pattern):

with langfuse.start_as_current_observation(name="workflow") as span:
    # These spans WON'T have user_id
    early_span = langfuse.start_observation(name="early_work")
    early_span.end()

    # Set attributes in the middle
    with propagate_attributes(user_id="user_123"):
        # Only spans created AFTER this point will have user_id
        late_span = langfuse.start_observation(name="late_work")
        late_span.end()

    # Result: Aggregations by user_id will miss "early_work" span

Cross-service propagation with baggage (advanced):

# Service A - originating service
with langfuse.start_as_current_observation(name="api_request"):
    with propagate_attributes(
        user_id="user_123",
        session_id="session_abc",
        environment="staging",
        as_baggage=True  # Propagate via HTTP headers
    ):
        # Make HTTP request to Service B
        response = requests.get("https://service-b.example.com/api")
        # user_id, session_id, and environment are now in HTTP headers

# Service B - downstream service
# OpenTelemetry will automatically extract baggage from HTTP headers
# and propagate attributes to spans in Service B. If Service B has a local
# Langfuse environment configured, the propagated environment wins for
# spans created within this context.
Note:
  • Validation: Attribute values (user_id, session_id, version, tags, trace_name) must be strings ≤200 characters. Environment must also match Langfuse's environment format: lowercase alphanumeric with optional hyphens or underscores, must be ≤40 characters, and it must not start with "langfuse". Metadata values are coerced to strings before the 200 character limit is applied. Invalid values will be dropped with a warning logged.
  • OpenTelemetry: This uses OpenTelemetry context propagation under the hood, making it compatible with other OTel-instrumented libraries.
Raises:
  • No exceptions are raised. Invalid values are logged as warnings and dropped.
See also:

Langfuse.start_as_current_observation (create the root span this wraps), https://langfuse.com/docs/observability/features/sessions, https://langfuse.com/docs/observability/features/users, https://langfuse.com/docs/observability/features/environments

ObservationTypeLiteral = typing.Union[typing.Literal['generation', 'embedding'], typing.Literal['span', 'agent', 'tool', 'chain', 'retriever', 'evaluator', 'guardrail'], typing.Literal['event']]
class LangfuseSpan(langfuse._client.span.LangfuseObservationWrapper): 
1267class LangfuseSpan(LangfuseObservationWrapper):
1268    """Standard span implementation for general operations in Langfuse.
1269
1270    This class represents a general-purpose span that can be used to trace
1271    any operation in your application. It extends the base LangfuseObservationWrapper
1272    with specific methods for creating child spans, generations, and updating
1273    span-specific attributes. If possible, use a more specific type for
1274    better observability and insights.
1275    """
1276
1277    def __init__(
1278        self,
1279        *,
1280        otel_span: otel_trace_api.Span,
1281        langfuse_client: "Langfuse",
1282        input: Optional[Any] = None,
1283        output: Optional[Any] = None,
1284        metadata: Optional[Any] = None,
1285        environment: Optional[str] = None,
1286        release: Optional[str] = None,
1287        version: Optional[str] = None,
1288        level: Optional[SpanLevel] = None,
1289        status_message: Optional[str] = None,
1290    ):
1291        """Initialize a new LangfuseSpan.
1292
1293        Args:
1294            otel_span: The OpenTelemetry span to wrap
1295            langfuse_client: Reference to the parent Langfuse client
1296            input: Input data for the span (any JSON-serializable object)
1297            output: Output data from the span (any JSON-serializable object)
1298            metadata: Additional metadata to associate with the span
1299            environment: The tracing environment
1300            release: Release identifier for the application
1301            version: Version identifier for the code or component
1302            level: Importance level of the span (info, warning, error)
1303            status_message: Optional status message for the span
1304        """
1305        super().__init__(
1306            otel_span=otel_span,
1307            as_type="span",
1308            langfuse_client=langfuse_client,
1309            input=input,
1310            output=output,
1311            metadata=metadata,
1312            environment=environment,
1313            release=release,
1314            version=version,
1315            level=level,
1316            status_message=status_message,
1317        )

Standard span implementation for general operations in Langfuse.

This class represents a general-purpose span that can be used to trace any operation in your application. It extends the base LangfuseObservationWrapper with specific methods for creating child spans, generations, and updating span-specific attributes. If possible, use a more specific type for better observability and insights.

LangfuseSpan( *, otel_span: opentelemetry.trace.span.Span, langfuse_client: Langfuse, input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, environment: Optional[str] = None, release: Optional[str] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None) 
1277    def __init__(
1278        self,
1279        *,
1280        otel_span: otel_trace_api.Span,
1281        langfuse_client: "Langfuse",
1282        input: Optional[Any] = None,
1283        output: Optional[Any] = None,
1284        metadata: Optional[Any] = None,
1285        environment: Optional[str] = None,
1286        release: Optional[str] = None,
1287        version: Optional[str] = None,
1288        level: Optional[SpanLevel] = None,
1289        status_message: Optional[str] = None,
1290    ):
1291        """Initialize a new LangfuseSpan.
1292
1293        Args:
1294            otel_span: The OpenTelemetry span to wrap
1295            langfuse_client: Reference to the parent Langfuse client
1296            input: Input data for the span (any JSON-serializable object)
1297            output: Output data from the span (any JSON-serializable object)
1298            metadata: Additional metadata to associate with the span
1299            environment: The tracing environment
1300            release: Release identifier for the application
1301            version: Version identifier for the code or component
1302            level: Importance level of the span (info, warning, error)
1303            status_message: Optional status message for the span
1304        """
1305        super().__init__(
1306            otel_span=otel_span,
1307            as_type="span",
1308            langfuse_client=langfuse_client,
1309            input=input,
1310            output=output,
1311            metadata=metadata,
1312            environment=environment,
1313            release=release,
1314            version=version,
1315            level=level,
1316            status_message=status_message,
1317        )

Initialize a new LangfuseSpan.

Arguments:
  • otel_span: The OpenTelemetry span to wrap
  • langfuse_client: Reference to the parent Langfuse client
  • input: Input data for the span (any JSON-serializable object)
  • output: Output data from the span (any JSON-serializable object)
  • metadata: Additional metadata to associate with the span
  • environment: The tracing environment
  • release: Release identifier for the application
  • version: Version identifier for the code or component
  • level: Importance level of the span (info, warning, error)
  • status_message: Optional status message for the span
class LangfuseGeneration(langfuse._client.span.LangfuseObservationWrapper): 
1320class LangfuseGeneration(LangfuseObservationWrapper):
1321    """Specialized span implementation for AI model generations in Langfuse.
1322
1323    This class represents a generation span specifically designed for tracking
1324    AI/LLM operations. It extends the base LangfuseObservationWrapper with specialized
1325    attributes for model details, token usage, and costs.
1326    """
1327
1328    def __init__(
1329        self,
1330        *,
1331        otel_span: otel_trace_api.Span,
1332        langfuse_client: "Langfuse",
1333        input: Optional[Any] = None,
1334        output: Optional[Any] = None,
1335        metadata: Optional[Any] = None,
1336        environment: Optional[str] = None,
1337        release: Optional[str] = None,
1338        version: Optional[str] = None,
1339        level: Optional[SpanLevel] = None,
1340        status_message: Optional[str] = None,
1341        completion_start_time: Optional[datetime] = None,
1342        model: Optional[str] = None,
1343        model_parameters: Optional[Dict[str, MapValue]] = None,
1344        usage_details: Optional[Dict[str, int]] = None,
1345        cost_details: Optional[Dict[str, float]] = None,
1346        prompt: Optional[PromptClient] = None,
1347    ):
1348        """Initialize a new LangfuseGeneration span.
1349
1350        Args:
1351            otel_span: The OpenTelemetry span to wrap
1352            langfuse_client: Reference to the parent Langfuse client
1353            input: Input data for the generation (e.g., prompts)
1354            output: Output from the generation (e.g., completions)
1355            metadata: Additional metadata to associate with the generation
1356            environment: The tracing environment
1357            release: Release identifier for the application
1358            version: Version identifier for the model or component
1359            level: Importance level of the generation (info, warning, error)
1360            status_message: Optional status message for the generation
1361            completion_start_time: When the model started generating the response
1362            model: Name/identifier of the AI model used (e.g., "gpt-4")
1363            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1364            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1365            cost_details: Cost information for the model call
1366            prompt: Associated prompt template from Langfuse prompt management
1367        """
1368        super().__init__(
1369            as_type="generation",
1370            otel_span=otel_span,
1371            langfuse_client=langfuse_client,
1372            input=input,
1373            output=output,
1374            metadata=metadata,
1375            environment=environment,
1376            release=release,
1377            version=version,
1378            level=level,
1379            status_message=status_message,
1380            completion_start_time=completion_start_time,
1381            model=model,
1382            model_parameters=model_parameters,
1383            usage_details=usage_details,
1384            cost_details=cost_details,
1385            prompt=prompt,
1386        )

Specialized span implementation for AI model generations in Langfuse.

This class represents a generation span specifically designed for tracking AI/LLM operations. It extends the base LangfuseObservationWrapper with specialized attributes for model details, token usage, and costs.

LangfuseGeneration( *, otel_span: opentelemetry.trace.span.Span, langfuse_client: Langfuse, input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, environment: Optional[str] = None, release: Optional[str] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None, completion_start_time: Optional[datetime.datetime] = None, model: Optional[str] = None, model_parameters: Optional[Dict[str, Union[str, NoneType, int, float, bool, List[str]]]] = None, usage_details: Optional[Dict[str, int]] = None, cost_details: Optional[Dict[str, float]] = None, prompt: Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient, NoneType] = None) 
1328    def __init__(
1329        self,
1330        *,
1331        otel_span: otel_trace_api.Span,
1332        langfuse_client: "Langfuse",
1333        input: Optional[Any] = None,
1334        output: Optional[Any] = None,
1335        metadata: Optional[Any] = None,
1336        environment: Optional[str] = None,
1337        release: Optional[str] = None,
1338        version: Optional[str] = None,
1339        level: Optional[SpanLevel] = None,
1340        status_message: Optional[str] = None,
1341        completion_start_time: Optional[datetime] = None,
1342        model: Optional[str] = None,
1343        model_parameters: Optional[Dict[str, MapValue]] = None,
1344        usage_details: Optional[Dict[str, int]] = None,
1345        cost_details: Optional[Dict[str, float]] = None,
1346        prompt: Optional[PromptClient] = None,
1347    ):
1348        """Initialize a new LangfuseGeneration span.
1349
1350        Args:
1351            otel_span: The OpenTelemetry span to wrap
1352            langfuse_client: Reference to the parent Langfuse client
1353            input: Input data for the generation (e.g., prompts)
1354            output: Output from the generation (e.g., completions)
1355            metadata: Additional metadata to associate with the generation
1356            environment: The tracing environment
1357            release: Release identifier for the application
1358            version: Version identifier for the model or component
1359            level: Importance level of the generation (info, warning, error)
1360            status_message: Optional status message for the generation
1361            completion_start_time: When the model started generating the response
1362            model: Name/identifier of the AI model used (e.g., "gpt-4")
1363            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1364            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1365            cost_details: Cost information for the model call
1366            prompt: Associated prompt template from Langfuse prompt management
1367        """
1368        super().__init__(
1369            as_type="generation",
1370            otel_span=otel_span,
1371            langfuse_client=langfuse_client,
1372            input=input,
1373            output=output,
1374            metadata=metadata,
1375            environment=environment,
1376            release=release,
1377            version=version,
1378            level=level,
1379            status_message=status_message,
1380            completion_start_time=completion_start_time,
1381            model=model,
1382            model_parameters=model_parameters,
1383            usage_details=usage_details,
1384            cost_details=cost_details,
1385            prompt=prompt,
1386        )

Initialize a new LangfuseGeneration span.

Arguments:
  • otel_span: The OpenTelemetry span to wrap
  • langfuse_client: Reference to the parent Langfuse client
  • input: Input data for the generation (e.g., prompts)
  • output: Output from the generation (e.g., completions)
  • metadata: Additional metadata to associate with the generation
  • environment: The tracing environment
  • release: Release identifier for the application
  • version: Version identifier for the model or component
  • level: Importance level of the generation (info, warning, error)
  • status_message: Optional status message for the generation
  • completion_start_time: When the model started generating the response
  • model: Name/identifier of the AI model used (e.g., "gpt-4")
  • model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
  • usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
  • cost_details: Cost information for the model call
  • prompt: Associated prompt template from Langfuse prompt management
class LangfuseEvent(langfuse._client.span.LangfuseObservationWrapper): 
1389class LangfuseEvent(LangfuseObservationWrapper):
1390    """Specialized span implementation for Langfuse Events."""
1391
1392    def __init__(
1393        self,
1394        *,
1395        otel_span: otel_trace_api.Span,
1396        langfuse_client: "Langfuse",
1397        input: Optional[Any] = None,
1398        output: Optional[Any] = None,
1399        metadata: Optional[Any] = None,
1400        environment: Optional[str] = None,
1401        release: Optional[str] = None,
1402        version: Optional[str] = None,
1403        level: Optional[SpanLevel] = None,
1404        status_message: Optional[str] = None,
1405    ):
1406        """Initialize a new LangfuseEvent span.
1407
1408        Args:
1409            otel_span: The OpenTelemetry span to wrap
1410            langfuse_client: Reference to the parent Langfuse client
1411            input: Input data for the event
1412            output: Output from the event
1413            metadata: Additional metadata to associate with the generation
1414            environment: The tracing environment
1415            release: Release identifier for the application
1416            version: Version identifier for the model or component
1417            level: Importance level of the generation (info, warning, error)
1418            status_message: Optional status message for the generation
1419        """
1420        super().__init__(
1421            otel_span=otel_span,
1422            as_type="event",
1423            langfuse_client=langfuse_client,
1424            input=input,
1425            output=output,
1426            metadata=metadata,
1427            environment=environment,
1428            release=release,
1429            version=version,
1430            level=level,
1431            status_message=status_message,
1432        )
1433
1434    def update(
1435        self,
1436        *,
1437        name: Optional[str] = None,
1438        input: Optional[Any] = None,
1439        output: Optional[Any] = None,
1440        metadata: Optional[Any] = None,
1441        version: Optional[str] = None,
1442        level: Optional[SpanLevel] = None,
1443        status_message: Optional[str] = None,
1444        completion_start_time: Optional[datetime] = None,
1445        model: Optional[str] = None,
1446        model_parameters: Optional[Dict[str, MapValue]] = None,
1447        usage_details: Optional[Dict[str, int]] = None,
1448        cost_details: Optional[Dict[str, float]] = None,
1449        prompt: Optional[PromptClient] = None,
1450        **kwargs: Any,
1451    ) -> "LangfuseEvent":
1452        """Update is not allowed for LangfuseEvent because events cannot be updated.
1453
1454        This method logs a warning and returns self without making changes.
1455
1456        Returns:
1457            self: Returns the unchanged LangfuseEvent instance
1458        """
1459        langfuse_logger.warning(
1460            "Attempted to update LangfuseEvent observation. Events cannot be updated after creation."
1461        )
1462        return self

Specialized span implementation for Langfuse Events.

LangfuseEvent( *, otel_span: opentelemetry.trace.span.Span, langfuse_client: Langfuse, input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, environment: Optional[str] = None, release: Optional[str] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None) 
1392    def __init__(
1393        self,
1394        *,
1395        otel_span: otel_trace_api.Span,
1396        langfuse_client: "Langfuse",
1397        input: Optional[Any] = None,
1398        output: Optional[Any] = None,
1399        metadata: Optional[Any] = None,
1400        environment: Optional[str] = None,
1401        release: Optional[str] = None,
1402        version: Optional[str] = None,
1403        level: Optional[SpanLevel] = None,
1404        status_message: Optional[str] = None,
1405    ):
1406        """Initialize a new LangfuseEvent span.
1407
1408        Args:
1409            otel_span: The OpenTelemetry span to wrap
1410            langfuse_client: Reference to the parent Langfuse client
1411            input: Input data for the event
1412            output: Output from the event
1413            metadata: Additional metadata to associate with the generation
1414            environment: The tracing environment
1415            release: Release identifier for the application
1416            version: Version identifier for the model or component
1417            level: Importance level of the generation (info, warning, error)
1418            status_message: Optional status message for the generation
1419        """
1420        super().__init__(
1421            otel_span=otel_span,
1422            as_type="event",
1423            langfuse_client=langfuse_client,
1424            input=input,
1425            output=output,
1426            metadata=metadata,
1427            environment=environment,
1428            release=release,
1429            version=version,
1430            level=level,
1431            status_message=status_message,
1432        )

Initialize a new LangfuseEvent span.

Arguments:
  • otel_span: The OpenTelemetry span to wrap
  • langfuse_client: Reference to the parent Langfuse client
  • input: Input data for the event
  • output: Output from the event
  • metadata: Additional metadata to associate with the generation
  • environment: The tracing environment
  • release: Release identifier for the application
  • version: Version identifier for the model or component
  • level: Importance level of the generation (info, warning, error)
  • status_message: Optional status message for the generation
def update( self, *, name: Optional[str] = None, input: Optional[Any] = None, output: Optional[Any] = None, metadata: Optional[Any] = None, version: Optional[str] = None, level: Optional[Literal['DEBUG', 'DEFAULT', 'WARNING', 'ERROR']] = None, status_message: Optional[str] = None, completion_start_time: Optional[datetime.datetime] = None, model: Optional[str] = None, model_parameters: Optional[Dict[str, Union[str, NoneType, int, float, bool, List[str]]]] = None, usage_details: Optional[Dict[str, int]] = None, cost_details: Optional[Dict[str, float]] = None, prompt: Union[langfuse.model.TextPromptClient, langfuse.model.ChatPromptClient, NoneType] = None, **kwargs: Any) -> LangfuseEvent: 
1434    def update(
1435        self,
1436        *,
1437        name: Optional[str] = None,
1438        input: Optional[Any] = None,
1439        output: Optional[Any] = None,
1440        metadata: Optional[Any] = None,
1441        version: Optional[str] = None,
1442        level: Optional[SpanLevel] = None,
1443        status_message: Optional[str] = None,
1444        completion_start_time: Optional[datetime] = None,
1445        model: Optional[str] = None,
1446        model_parameters: Optional[Dict[str, MapValue]] = None,
1447        usage_details: Optional[Dict[str, int]] = None,
1448        cost_details: Optional[Dict[str, float]] = None,
1449        prompt: Optional[PromptClient] = None,
1450        **kwargs: Any,
1451    ) -> "LangfuseEvent":
1452        """Update is not allowed for LangfuseEvent because events cannot be updated.
1453
1454        This method logs a warning and returns self without making changes.
1455
1456        Returns:
1457            self: Returns the unchanged LangfuseEvent instance
1458        """
1459        langfuse_logger.warning(
1460            "Attempted to update LangfuseEvent observation. Events cannot be updated after creation."
1461        )
1462        return self

Update is not allowed for LangfuseEvent because events cannot be updated.

This method logs a warning and returns self without making changes.

Returns:

self: Returns the unchanged LangfuseEvent instance

class LangfuseOtelSpanAttributes: 
28class LangfuseOtelSpanAttributes:
29    # Langfuse-Trace attributes
30    TRACE_NAME = "langfuse.trace.name"
31    TRACE_USER_ID = "user.id"
32    TRACE_SESSION_ID = "session.id"
33    TRACE_TAGS = "langfuse.trace.tags"
34    TRACE_PUBLIC = "langfuse.trace.public"
35    TRACE_METADATA = "langfuse.trace.metadata"
36    TRACE_INPUT = "langfuse.trace.input"
37    TRACE_OUTPUT = "langfuse.trace.output"
38
39    # Langfuse-observation attributes
40    OBSERVATION_TYPE = "langfuse.observation.type"
41    OBSERVATION_METADATA = "langfuse.observation.metadata"
42    OBSERVATION_LEVEL = "langfuse.observation.level"
43    OBSERVATION_STATUS_MESSAGE = "langfuse.observation.status_message"
44    OBSERVATION_INPUT = "langfuse.observation.input"
45    OBSERVATION_OUTPUT = "langfuse.observation.output"
46
47    # Langfuse-observation of type Generation attributes
48    OBSERVATION_COMPLETION_START_TIME = "langfuse.observation.completion_start_time"
49    OBSERVATION_MODEL = "langfuse.observation.model.name"
50    OBSERVATION_MODEL_PARAMETERS = "langfuse.observation.model.parameters"
51    OBSERVATION_USAGE_DETAILS = "langfuse.observation.usage_details"
52    OBSERVATION_COST_DETAILS = "langfuse.observation.cost_details"
53    OBSERVATION_PROMPT_NAME = "langfuse.observation.prompt.name"
54    OBSERVATION_PROMPT_VERSION = "langfuse.observation.prompt.version"
55
56    # General
57    ENVIRONMENT = "langfuse.environment"
58    RELEASE = "langfuse.release"
59    VERSION = "langfuse.version"
60
61    # Internal
62    AS_ROOT = "langfuse.internal.as_root"
63    IS_APP_ROOT = "langfuse.internal.is_app_root"
64
65    # Experiments
66    EXPERIMENT_ID = "langfuse.experiment.id"
67    EXPERIMENT_NAME = "langfuse.experiment.name"
68    EXPERIMENT_DESCRIPTION = "langfuse.experiment.description"
69    EXPERIMENT_METADATA = "langfuse.experiment.metadata"
70    EXPERIMENT_DATASET_ID = "langfuse.experiment.dataset.id"
71    EXPERIMENT_ITEM_ID = "langfuse.experiment.item.id"
72    EXPERIMENT_ITEM_EXPECTED_OUTPUT = "langfuse.experiment.item.expected_output"
73    EXPERIMENT_ITEM_METADATA = "langfuse.experiment.item.metadata"
74    EXPERIMENT_ITEM_ROOT_OBSERVATION_ID = "langfuse.experiment.item.root_observation_id"
TRACE_NAME = 'langfuse.trace.name'
TRACE_USER_ID = 'user.id'
TRACE_SESSION_ID = 'session.id'
TRACE_TAGS = 'langfuse.trace.tags'
TRACE_PUBLIC = 'langfuse.trace.public'
TRACE_METADATA = 'langfuse.trace.metadata'
TRACE_INPUT = 'langfuse.trace.input'
TRACE_OUTPUT = 'langfuse.trace.output'
OBSERVATION_TYPE = 'langfuse.observation.type'
OBSERVATION_METADATA = 'langfuse.observation.metadata'
OBSERVATION_LEVEL = 'langfuse.observation.level'
OBSERVATION_STATUS_MESSAGE = 'langfuse.observation.status_message'
OBSERVATION_INPUT = 'langfuse.observation.input'
OBSERVATION_OUTPUT = 'langfuse.observation.output'
OBSERVATION_COMPLETION_START_TIME = 'langfuse.observation.completion_start_time'
OBSERVATION_MODEL = 'langfuse.observation.model.name'
OBSERVATION_MODEL_PARAMETERS = 'langfuse.observation.model.parameters'
OBSERVATION_USAGE_DETAILS = 'langfuse.observation.usage_details'
OBSERVATION_COST_DETAILS = 'langfuse.observation.cost_details'
OBSERVATION_PROMPT_NAME = 'langfuse.observation.prompt.name'
OBSERVATION_PROMPT_VERSION = 'langfuse.observation.prompt.version'
ENVIRONMENT = 'langfuse.environment'
RELEASE = 'langfuse.release'
VERSION = 'langfuse.version'
AS_ROOT = 'langfuse.internal.as_root'
IS_APP_ROOT = 'langfuse.internal.is_app_root'
EXPERIMENT_ID = 'langfuse.experiment.id'
EXPERIMENT_NAME = 'langfuse.experiment.name'
EXPERIMENT_DESCRIPTION = 'langfuse.experiment.description'
EXPERIMENT_METADATA = 'langfuse.experiment.metadata'
EXPERIMENT_DATASET_ID = 'langfuse.experiment.dataset.id'
EXPERIMENT_ITEM_ID = 'langfuse.experiment.item.id'
EXPERIMENT_ITEM_EXPECTED_OUTPUT = 'langfuse.experiment.item.expected_output'
EXPERIMENT_ITEM_METADATA = 'langfuse.experiment.item.metadata'
EXPERIMENT_ITEM_ROOT_OBSERVATION_ID = 'langfuse.experiment.item.root_observation_id'
class LangfuseAgent(langfuse._client.span.LangfuseObservationWrapper): 
1465class LangfuseAgent(LangfuseObservationWrapper):
1466    """Agent observation for reasoning blocks that act on tools using LLM guidance."""
1467
1468    def __init__(self, **kwargs: Any) -> None:
1469        """Initialize a new LangfuseAgent span."""
1470        kwargs["as_type"] = "agent"
1471        super().__init__(**kwargs)

Agent observation for reasoning blocks that act on tools using LLM guidance.

LangfuseAgent(**kwargs: Any) 
1468    def __init__(self, **kwargs: Any) -> None:
1469        """Initialize a new LangfuseAgent span."""
1470        kwargs["as_type"] = "agent"
1471        super().__init__(**kwargs)

Initialize a new LangfuseAgent span.

class LangfuseTool(langfuse._client.span.LangfuseObservationWrapper): 
1474class LangfuseTool(LangfuseObservationWrapper):
1475    """Tool observation representing external tool calls, e.g., calling a weather API."""
1476
1477    def __init__(self, **kwargs: Any) -> None:
1478        """Initialize a new LangfuseTool span."""
1479        kwargs["as_type"] = "tool"
1480        super().__init__(**kwargs)

Tool observation representing external tool calls, e.g., calling a weather API.

LangfuseTool(**kwargs: Any) 
1477    def __init__(self, **kwargs: Any) -> None:
1478        """Initialize a new LangfuseTool span."""
1479        kwargs["as_type"] = "tool"
1480        super().__init__(**kwargs)

Initialize a new LangfuseTool span.

class LangfuseChain(langfuse._client.span.LangfuseObservationWrapper): 
1483class LangfuseChain(LangfuseObservationWrapper):
1484    """Chain observation for connecting LLM application steps, e.g. passing context from retriever to LLM."""
1485
1486    def __init__(self, **kwargs: Any) -> None:
1487        """Initialize a new LangfuseChain span."""
1488        kwargs["as_type"] = "chain"
1489        super().__init__(**kwargs)

Chain observation for connecting LLM application steps, e.g. passing context from retriever to LLM.

LangfuseChain(**kwargs: Any) 
1486    def __init__(self, **kwargs: Any) -> None:
1487        """Initialize a new LangfuseChain span."""
1488        kwargs["as_type"] = "chain"
1489        super().__init__(**kwargs)

Initialize a new LangfuseChain span.

class LangfuseEmbedding(langfuse._client.span.LangfuseObservationWrapper): 
1501class LangfuseEmbedding(LangfuseObservationWrapper):
1502    """Embedding observation for LLM embedding calls, typically used before retrieval."""
1503
1504    def __init__(self, **kwargs: Any) -> None:
1505        """Initialize a new LangfuseEmbedding span."""
1506        kwargs["as_type"] = "embedding"
1507        super().__init__(**kwargs)

Embedding observation for LLM embedding calls, typically used before retrieval.

LangfuseEmbedding(**kwargs: Any) 
1504    def __init__(self, **kwargs: Any) -> None:
1505        """Initialize a new LangfuseEmbedding span."""
1506        kwargs["as_type"] = "embedding"
1507        super().__init__(**kwargs)

Initialize a new LangfuseEmbedding span.

class LangfuseEvaluator(langfuse._client.span.LangfuseObservationWrapper): 
1510class LangfuseEvaluator(LangfuseObservationWrapper):
1511    """Evaluator observation for assessing relevance, correctness, or helpfulness of LLM outputs."""
1512
1513    def __init__(self, **kwargs: Any) -> None:
1514        """Initialize a new LangfuseEvaluator span."""
1515        kwargs["as_type"] = "evaluator"
1516        super().__init__(**kwargs)

Evaluator observation for assessing relevance, correctness, or helpfulness of LLM outputs.

LangfuseEvaluator(**kwargs: Any) 
1513    def __init__(self, **kwargs: Any) -> None:
1514        """Initialize a new LangfuseEvaluator span."""
1515        kwargs["as_type"] = "evaluator"
1516        super().__init__(**kwargs)

Initialize a new LangfuseEvaluator span.

class LangfuseRetriever(langfuse._client.span.LangfuseObservationWrapper): 
1492class LangfuseRetriever(LangfuseObservationWrapper):
1493    """Retriever observation for data retrieval steps, e.g. vector store or database queries."""
1494
1495    def __init__(self, **kwargs: Any) -> None:
1496        """Initialize a new LangfuseRetriever span."""
1497        kwargs["as_type"] = "retriever"
1498        super().__init__(**kwargs)

Retriever observation for data retrieval steps, e.g. vector store or database queries.

LangfuseRetriever(**kwargs: Any) 
1495    def __init__(self, **kwargs: Any) -> None:
1496        """Initialize a new LangfuseRetriever span."""
1497        kwargs["as_type"] = "retriever"
1498        super().__init__(**kwargs)

Initialize a new LangfuseRetriever span.

class LangfuseGuardrail(langfuse._client.span.LangfuseObservationWrapper): 
1519class LangfuseGuardrail(LangfuseObservationWrapper):
1520    """Guardrail observation for protection e.g. against jailbreaks or offensive content."""
1521
1522    def __init__(self, **kwargs: Any) -> None:
1523        """Initialize a new LangfuseGuardrail span."""
1524        kwargs["as_type"] = "guardrail"
1525        super().__init__(**kwargs)

Guardrail observation for protection e.g. against jailbreaks or offensive content.

LangfuseGuardrail(**kwargs: Any) 
1522    def __init__(self, **kwargs: Any) -> None:
1523        """Initialize a new LangfuseGuardrail span."""
1524        kwargs["as_type"] = "guardrail"
1525        super().__init__(**kwargs)

Initialize a new LangfuseGuardrail span.

class Evaluation: 
101class Evaluation:
102    """Represents an evaluation result for an experiment item or an entire experiment run.
103
104    This class provides a strongly-typed way to create evaluation results in evaluator functions.
105    Users must use keyword arguments when instantiating this class.
106
107    Attributes:
108        name: Unique identifier for the evaluation metric. Should be descriptive
109            and consistent across runs (e.g., "accuracy", "bleu_score", "toxicity").
110            Used for aggregation and comparison across experiment runs.
111        value: The evaluation score or result. Can be:
112            - Numeric (int/float): For quantitative metrics like accuracy (0.85), BLEU (0.42)
113            - String: For categorical results like "positive", "negative", "neutral"
114            - Boolean: For binary assessments like "passes_safety_check"
115        comment: Optional human-readable explanation of the evaluation result.
116            Useful for providing context, explaining scoring rationale, or noting
117            special conditions. Displayed in Langfuse UI for interpretability.
118        metadata: Optional structured metadata about the evaluation process.
119            Can include confidence scores, intermediate calculations, model versions,
120            or any other relevant technical details.
121        data_type: Optional score data type. Required if value is not NUMERIC.
122            One of NUMERIC, CATEGORICAL, or BOOLEAN. Defaults to NUMERIC.
123        config_id: Optional Langfuse score config ID.
124
125    Examples:
126        Basic accuracy evaluation:
127        ```python
128        from langfuse import Evaluation
129
130        def accuracy_evaluator(*, input, output, expected_output=None, **kwargs):
131            if not expected_output:
132                return Evaluation(name="accuracy", value=0, comment="No expected output")
133
134            is_correct = output.strip().lower() == expected_output.strip().lower()
135            return Evaluation(
136                name="accuracy",
137                value=1.0 if is_correct else 0.0,
138                comment="Correct answer" if is_correct else "Incorrect answer"
139            )
140        ```
141
142        Multi-metric evaluator:
143        ```python
144        def comprehensive_evaluator(*, input, output, expected_output=None, **kwargs):
145            return [
146                Evaluation(name="length", value=len(output), comment=f"Output length: {len(output)} chars"),
147                Evaluation(name="has_greeting", value="hello" in output.lower(), comment="Contains greeting"),
148                Evaluation(
149                    name="quality",
150                    value=0.85,
151                    comment="High quality response",
152                    metadata={"confidence": 0.92, "model": "gpt-4"}
153                )
154            ]
155        ```
156
157        Categorical evaluation:
158        ```python
159        def sentiment_evaluator(*, input, output, **kwargs):
160            sentiment = analyze_sentiment(output)  # Returns "positive", "negative", or "neutral"
161            return Evaluation(
162                name="sentiment",
163                value=sentiment,
164                comment=f"Response expresses {sentiment} sentiment",
165                data_type="CATEGORICAL"
166            )
167        ```
168
169        Failed evaluation with error handling:
170        ```python
171        def external_api_evaluator(*, input, output, **kwargs):
172            try:
173                score = external_api.evaluate(output)
174                return Evaluation(name="external_score", value=score)
175            except Exception as e:
176                return Evaluation(
177                    name="external_score",
178                    value=0,
179                    comment=f"API unavailable: {e}",
180                    metadata={"error": str(e), "retry_count": 3}
181                )
182        ```
183
184    Note:
185        All arguments must be passed as keywords. Positional arguments are not allowed
186        to ensure code clarity and prevent errors from argument reordering.
187    """
188
189    def __init__(
190        self,
191        *,
192        name: str,
193        value: Union[int, float, str, bool],
194        comment: Optional[str] = None,
195        metadata: Optional[Dict[str, Any]] = None,
196        data_type: Optional[ExperimentScoreType] = None,
197        config_id: Optional[str] = None,
198    ):
199        """Initialize an Evaluation with the provided data.
200
201        Args:
202            name: Unique identifier for the evaluation metric.
203            value: The evaluation score or result.
204            comment: Optional human-readable explanation of the result.
205            metadata: Optional structured metadata about the evaluation process.
206            data_type: Optional score data type (NUMERIC, CATEGORICAL, or BOOLEAN).
207            config_id: Optional Langfuse score config ID.
208
209        Note:
210            All arguments must be provided as keywords. Positional arguments will raise a TypeError.
211        """
212        self.name = name
213        self.value = value
214        self.comment = comment
215        self.metadata = metadata
216        self.data_type = data_type
217        self.config_id = config_id

Represents an evaluation result for an experiment item or an entire experiment run.

This class provides a strongly-typed way to create evaluation results in evaluator functions. Users must use keyword arguments when instantiating this class.

Attributes:
  • name: Unique identifier for the evaluation metric. Should be descriptive and consistent across runs (e.g., "accuracy", "bleu_score", "toxicity"). Used for aggregation and comparison across experiment runs.
  • value: The evaluation score or result. Can be:
    • Numeric (int/float): For quantitative metrics like accuracy (0.85), BLEU (0.42)
    • String: For categorical results like "positive", "negative", "neutral"
    • Boolean: For binary assessments like "passes_safety_check"
  • comment: Optional human-readable explanation of the evaluation result. Useful for providing context, explaining scoring rationale, or noting special conditions. Displayed in Langfuse UI for interpretability.
  • metadata: Optional structured metadata about the evaluation process. Can include confidence scores, intermediate calculations, model versions, or any other relevant technical details.
  • data_type: Optional score data type. Required if value is not NUMERIC. One of NUMERIC, CATEGORICAL, or BOOLEAN. Defaults to NUMERIC.
  • config_id: Optional Langfuse score config ID.
Examples:

Basic accuracy evaluation:

from langfuse import Evaluation

def accuracy_evaluator(*, input, output, expected_output=None, **kwargs):
    if not expected_output:
        return Evaluation(name="accuracy", value=0, comment="No expected output")

    is_correct = output.strip().lower() == expected_output.strip().lower()
    return Evaluation(
        name="accuracy",
        value=1.0 if is_correct else 0.0,
        comment="Correct answer" if is_correct else "Incorrect answer"
    )

Multi-metric evaluator:

def comprehensive_evaluator(*, input, output, expected_output=None, **kwargs):
    return [
        Evaluation(name="length", value=len(output), comment=f"Output length: {len(output)} chars"),
        Evaluation(name="has_greeting", value="hello" in output.lower(), comment="Contains greeting"),
        Evaluation(
            name="quality",
            value=0.85,
            comment="High quality response",
            metadata={"confidence": 0.92, "model": "gpt-4"}
        )
    ]

Categorical evaluation:

def sentiment_evaluator(*, input, output, **kwargs):
    sentiment = analyze_sentiment(output)  # Returns "positive", "negative", or "neutral"
    return Evaluation(
        name="sentiment",
        value=sentiment,
        comment=f"Response expresses {sentiment} sentiment",
        data_type="CATEGORICAL"
    )

Failed evaluation with error handling:

def external_api_evaluator(*, input, output, **kwargs):
    try:
        score = external_api.evaluate(output)
        return Evaluation(name="external_score", value=score)
    except Exception as e:
        return Evaluation(
            name="external_score",
            value=0,
            comment=f"API unavailable: {e}",
            metadata={"error": str(e), "retry_count": 3}
        )
Note:

All arguments must be passed as keywords. Positional arguments are not allowed to ensure code clarity and prevent errors from argument reordering.

Evaluation( *, name: str, value: Union[int, float, str, bool], comment: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, data_type: Optional[Literal['NUMERIC', 'CATEGORICAL', 'BOOLEAN']] = None, config_id: Optional[str] = None) 
189    def __init__(
190        self,
191        *,
192        name: str,
193        value: Union[int, float, str, bool],
194        comment: Optional[str] = None,
195        metadata: Optional[Dict[str, Any]] = None,
196        data_type: Optional[ExperimentScoreType] = None,
197        config_id: Optional[str] = None,
198    ):
199        """Initialize an Evaluation with the provided data.
200
201        Args:
202            name: Unique identifier for the evaluation metric.
203            value: The evaluation score or result.
204            comment: Optional human-readable explanation of the result.
205            metadata: Optional structured metadata about the evaluation process.
206            data_type: Optional score data type (NUMERIC, CATEGORICAL, or BOOLEAN).
207            config_id: Optional Langfuse score config ID.
208
209        Note:
210            All arguments must be provided as keywords. Positional arguments will raise a TypeError.
211        """
212        self.name = name
213        self.value = value
214        self.comment = comment
215        self.metadata = metadata
216        self.data_type = data_type
217        self.config_id = config_id

Initialize an Evaluation with the provided data.

Arguments:
  • name: Unique identifier for the evaluation metric.
  • value: The evaluation score or result.
  • comment: Optional human-readable explanation of the result.
  • metadata: Optional structured metadata about the evaluation process.
  • data_type: Optional score data type (NUMERIC, CATEGORICAL, or BOOLEAN).
  • config_id: Optional Langfuse score config ID.
Note:

All arguments must be provided as keywords. Positional arguments will raise a TypeError.

name
value
comment
metadata
data_type
config_id
class EvaluatorInputs: 
 38class EvaluatorInputs:
 39    """Input data structure for evaluators, returned by mapper functions.
 40
 41    This class provides a strongly-typed container for transforming API response
 42    objects (traces, observations) into the standardized format expected
 43    by evaluator functions. It ensures consistent access to input, output, expected
 44    output, and metadata regardless of the source entity type.
 45
 46    Attributes:
 47        input: The input data that was provided to generate the output being evaluated.
 48            For traces, this might be the initial prompt or request. For observations,
 49            this could be the span's input. The exact meaning depends on your use case.
 50        output: The actual output that was produced and needs to be evaluated.
 51            For traces, this is typically the final response. For observations,
 52            this might be the generation output or span result.
 53        expected_output: Optional ground truth or expected result for comparison.
 54            Used by evaluators to assess correctness. May be None if no ground truth
 55            is available for the entity being evaluated.
 56        metadata: Optional structured metadata providing additional context for evaluation.
 57            Can include information about the entity, execution context, user attributes,
 58            or any other relevant data that evaluators might use.
 59
 60    Examples:
 61        Simple mapper for traces:
 62        ```python
 63        from langfuse import EvaluatorInputs
 64
 65        def trace_mapper(trace):
 66            return EvaluatorInputs(
 67                input=trace.input,
 68                output=trace.output,
 69                expected_output=None,  # No ground truth available
 70                metadata={"user_id": trace.user_id, "tags": trace.tags}
 71            )
 72        ```
 73
 74        Mapper for observations extracting specific fields:
 75        ```python
 76        def observation_mapper(observation):
 77            # Extract input/output from observation's data
 78            input_data = observation.input if hasattr(observation, 'input') else None
 79            output_data = observation.output if hasattr(observation, 'output') else None
 80
 81            return EvaluatorInputs(
 82                input=input_data,
 83                output=output_data,
 84                expected_output=None,
 85                metadata={
 86                    "observation_type": observation.type,
 87                    "model": observation.model,
 88                    "latency_ms": observation.end_time - observation.start_time
 89                }
 90            )
 91        ```
 92        ```
 93
 94    Note:
 95        All arguments must be passed as keywords when instantiating this class.
 96    """
 97
 98    def __init__(
 99        self,
100        *,
101        input: Any,
102        output: Any,
103        expected_output: Any = None,
104        metadata: Optional[Dict[str, Any]] = None,
105    ):
106        """Initialize EvaluatorInputs with the provided data.
107
108        Args:
109            input: The input data for evaluation.
110            output: The output data to be evaluated.
111            expected_output: Optional ground truth for comparison.
112            metadata: Optional additional context for evaluation.
113
114        Note:
115            All arguments must be provided as keywords.
116        """
117        self.input = input
118        self.output = output
119        self.expected_output = expected_output
120        self.metadata = metadata

Input data structure for evaluators, returned by mapper functions.

This class provides a strongly-typed container for transforming API response objects (traces, observations) into the standardized format expected by evaluator functions. It ensures consistent access to input, output, expected output, and metadata regardless of the source entity type.

Attributes:
  • input: The input data that was provided to generate the output being evaluated. For traces, this might be the initial prompt or request. For observations, this could be the span's input. The exact meaning depends on your use case.
  • output: The actual output that was produced and needs to be evaluated. For traces, this is typically the final response. For observations, this might be the generation output or span result.
  • expected_output: Optional ground truth or expected result for comparison. Used by evaluators to assess correctness. May be None if no ground truth is available for the entity being evaluated.
  • metadata: Optional structured metadata providing additional context for evaluation. Can include information about the entity, execution context, user attributes, or any other relevant data that evaluators might use.
Examples:

Simple mapper for traces:

from langfuse import EvaluatorInputs

def trace_mapper(trace):
    return EvaluatorInputs(
        input=trace.input,
        output=trace.output,
        expected_output=None,  # No ground truth available
        metadata={"user_id": trace.user_id, "tags": trace.tags}
    )

Mapper for observations extracting specific fields:

def observation_mapper(observation):
    # Extract input/output from observation's data
    input_data = observation.input if hasattr(observation, 'input') else None
    output_data = observation.output if hasattr(observation, 'output') else None

    return EvaluatorInputs(
        input=input_data,
        output=output_data,
        expected_output=None,
        metadata={
            "observation_type": observation.type,
            "model": observation.model,
            "latency_ms": observation.end_time - observation.start_time
        }
    )

```

Note:

All arguments must be passed as keywords when instantiating this class.

EvaluatorInputs( *, input: Any, output: Any, expected_output: Any = None, metadata: Optional[Dict[str, Any]] = None) 
 98    def __init__(
 99        self,
100        *,
101        input: Any,
102        output: Any,
103        expected_output: Any = None,
104        metadata: Optional[Dict[str, Any]] = None,
105    ):
106        """Initialize EvaluatorInputs with the provided data.
107
108        Args:
109            input: The input data for evaluation.
110            output: The output data to be evaluated.
111            expected_output: Optional ground truth for comparison.
112            metadata: Optional additional context for evaluation.
113
114        Note:
115            All arguments must be provided as keywords.
116        """
117        self.input = input
118        self.output = output
119        self.expected_output = expected_output
120        self.metadata = metadata

Initialize EvaluatorInputs with the provided data.

Arguments:
  • input: The input data for evaluation.
  • output: The output data to be evaluated.
  • expected_output: Optional ground truth for comparison.
  • metadata: Optional additional context for evaluation.
Note:

All arguments must be provided as keywords.

input
output
expected_output
metadata
class MapperFunction(typing.Protocol): 
123class MapperFunction(Protocol):
124    """Protocol defining the interface for mapper functions in batch evaluation.
125
126    Mapper functions transform API response objects (traces or observations)
127    into the standardized EvaluatorInputs format that evaluators expect. This abstraction
128    allows you to define how to extract and structure evaluation data from different
129    entity types.
130
131    Mapper functions must:
132    - Accept a single item parameter (trace, observation)
133    - Return an EvaluatorInputs instance with input, output, expected_output, metadata
134    - Can be either synchronous or asynchronous
135    - Should handle missing or malformed data gracefully
136    """
137
138    def __call__(
139        self,
140        *,
141        item: Union["TraceWithFullDetails", "ObservationsView"],
142        **kwargs: Dict[str, Any],
143    ) -> Union[EvaluatorInputs, Awaitable[EvaluatorInputs]]:
144        """Transform an API response object into evaluator inputs.
145
146        This method defines how to extract evaluation-relevant data from the raw
147        API response object. The implementation should map entity-specific fields
148        to the standardized input/output/expected_output/metadata structure.
149
150        Args:
151            item: The API response object to transform. The type depends on the scope:
152                - TraceWithFullDetails: When evaluating traces
153                - ObservationsView: When evaluating observations
154
155        Returns:
156            EvaluatorInputs: A structured container with:
157                - input: The input data that generated the output
158                - output: The output to be evaluated
159                - expected_output: Optional ground truth for comparison
160                - metadata: Optional additional context
161
162            Can return either a direct EvaluatorInputs instance or an awaitable
163            (for async mappers that need to fetch additional data).
164
165        Examples:
166            Basic trace mapper:
167            ```python
168            def map_trace(trace):
169                return EvaluatorInputs(
170                    input=trace.input,
171                    output=trace.output,
172                    expected_output=None,
173                    metadata={"trace_id": trace.id, "user": trace.user_id}
174                )
175            ```
176
177            Observation mapper with conditional logic:
178            ```python
179            def map_observation(observation):
180                # Extract fields based on observation type
181                if observation.type == "GENERATION":
182                    input_data = observation.input
183                    output_data = observation.output
184                else:
185                    # For other types, use different fields
186                    input_data = observation.metadata.get("input")
187                    output_data = observation.metadata.get("output")
188
189                return EvaluatorInputs(
190                    input=input_data,
191                    output=output_data,
192                    expected_output=None,
193                    metadata={"obs_id": observation.id, "type": observation.type}
194                )
195            ```
196
197            Async mapper (if additional processing needed):
198            ```python
199            async def map_trace_async(trace):
200                # Could do async processing here if needed
201                processed_output = await some_async_transformation(trace.output)
202
203                return EvaluatorInputs(
204                    input=trace.input,
205                    output=processed_output,
206                    expected_output=None,
207                    metadata={"trace_id": trace.id}
208                )
209            ```
210        """
211        ...

Protocol defining the interface for mapper functions in batch evaluation.

Mapper functions transform API response objects (traces or observations) into the standardized EvaluatorInputs format that evaluators expect. This abstraction allows you to define how to extract and structure evaluation data from different entity types.

Mapper functions must:

  • Accept a single item parameter (trace, observation)
  • Return an EvaluatorInputs instance with input, output, expected_output, metadata
  • Can be either synchronous or asynchronous
  • Should handle missing or malformed data gracefully
MapperFunction(*args, **kwargs) 
1927def _no_init_or_replace_init(self, *args, **kwargs):
1928    cls = type(self)
1929
1930    if cls._is_protocol:
1931        raise TypeError('Protocols cannot be instantiated')
1932
1933    # Already using a custom `__init__`. No need to calculate correct
1934    # `__init__` to call. This can lead to RecursionError. See bpo-45121.
1935    if cls.__init__ is not _no_init_or_replace_init:
1936        return
1937
1938    # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`.
1939    # The first instantiation of the subclass will call `_no_init_or_replace_init` which
1940    # searches for a proper new `__init__` in the MRO. The new `__init__`
1941    # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent
1942    # instantiation of the protocol subclass will thus use the new
1943    # `__init__` and no longer call `_no_init_or_replace_init`.
1944    for base in cls.__mro__:
1945        init = base.__dict__.get('__init__', _no_init_or_replace_init)
1946        if init is not _no_init_or_replace_init:
1947            cls.__init__ = init
1948            break
1949    else:
1950        # should not happen
1951        cls.__init__ = object.__init__
1952
1953    cls.__init__(self, *args, **kwargs)
class CompositeEvaluatorFunction(typing.Protocol): 
214class CompositeEvaluatorFunction(Protocol):
215    """Protocol defining the interface for composite evaluator functions.
216
217    Composite evaluators create aggregate scores from multiple item-level evaluations.
218    This is commonly used to compute weighted averages, combined metrics, or other
219    composite assessments based on individual evaluation results.
220
221    Composite evaluators:
222    - Accept the same inputs as item-level evaluators (input, output, expected_output, metadata)
223      plus the list of evaluations
224    - Return either a single Evaluation, a list of Evaluations, or a dict
225    - Can be either synchronous or asynchronous
226    - Have access to both raw item data and evaluation results
227    """
228
229    def __call__(
230        self,
231        *,
232        input: Optional[Any] = None,
233        output: Optional[Any] = None,
234        expected_output: Optional[Any] = None,
235        metadata: Optional[Dict[str, Any]] = None,
236        evaluations: List[Evaluation],
237        **kwargs: Dict[str, Any],
238    ) -> Union[
239        Evaluation,
240        List[Evaluation],
241        Dict[str, Any],
242        Awaitable[Evaluation],
243        Awaitable[List[Evaluation]],
244        Awaitable[Dict[str, Any]],
245    ]:
246        r"""Create a composite evaluation from item-level evaluation results.
247
248        This method combines multiple evaluation scores into a single composite metric.
249        Common use cases include weighted averages, pass/fail decisions based on multiple
250        criteria, or custom scoring logic that considers multiple dimensions.
251
252        Args:
253            input: The input data that was provided to the system being evaluated.
254            output: The output generated by the system being evaluated.
255            expected_output: The expected/reference output for comparison (if available).
256            metadata: Additional metadata about the evaluation context.
257            evaluations: List of evaluation results from item-level evaluators.
258                Each evaluation contains name, value, comment, and metadata.
259
260        Returns:
261            Can return any of:
262            - Evaluation: A single composite evaluation result
263            - List[Evaluation]: Multiple composite evaluations
264            - Dict: A dict that will be converted to an Evaluation
265                - name: Identifier for the composite metric (e.g., "composite_score")
266                - value: The computed composite value
267                - comment: Optional explanation of how the score was computed
268                - metadata: Optional details about the composition logic
269
270            Can return either a direct Evaluation instance or an awaitable
271            (for async composite evaluators).
272
273        Examples:
274            Simple weighted average:
275            ```python
276            def weighted_composite(*, input, output, expected_output, metadata, evaluations):
277                weights = {
278                    "accuracy": 0.5,
279                    "relevance": 0.3,
280                    "safety": 0.2
281                }
282
283                total_score = 0.0
284                total_weight = 0.0
285
286                for eval in evaluations:
287                    if eval.name in weights and isinstance(eval.value, (int, float)):
288                        total_score += eval.value * weights[eval.name]
289                        total_weight += weights[eval.name]
290
291                final_score = total_score / total_weight if total_weight > 0 else 0.0
292
293                return Evaluation(
294                    name="composite_score",
295                    value=final_score,
296                    comment=f"Weighted average of {len(evaluations)} metrics"
297                )
298            ```
299
300            Pass/fail composite based on thresholds:
301            ```python
302            def pass_fail_composite(*, input, output, expected_output, metadata, evaluations):
303                # Must pass all criteria
304                thresholds = {
305                    "accuracy": 0.7,
306                    "safety": 0.9,
307                    "relevance": 0.6
308                }
309
310                passes = True
311                failing_metrics = []
312
313                for metric, threshold in thresholds.items():
314                    eval_result = next((e for e in evaluations if e.name == metric), None)
315                    if eval_result and isinstance(eval_result.value, (int, float)):
316                        if eval_result.value < threshold:
317                            passes = False
318                            failing_metrics.append(metric)
319
320                return Evaluation(
321                    name="passes_all_checks",
322                    value=passes,
323                    comment=f"Failed: {', '.join(failing_metrics)}" if failing_metrics else "All checks passed",
324                    data_type="BOOLEAN"
325                )
326            ```
327
328            Async composite with external scoring:
329            ```python
330            async def llm_composite(*, input, output, expected_output, metadata, evaluations):
331                # Use LLM to synthesize multiple evaluation results
332                eval_summary = "\n".join(
333                    f"- {e.name}: {e.value}" for e in evaluations
334                )
335
336                prompt = f"Given these evaluation scores:\n{eval_summary}\n"
337                prompt += f"For the output: {output}\n"
338                prompt += "Provide an overall quality score from 0-1."
339
340                response = await openai.chat.completions.create(
341                    model="gpt-4",
342                    messages=[{"role": "user", "content": prompt}]
343                )
344
345                score = float(response.choices[0].message.content.strip())
346
347                return Evaluation(
348                    name="llm_composite_score",
349                    value=score,
350                    comment="LLM-synthesized composite score"
351                )
352            ```
353
354            Context-aware composite:
355            ```python
356            def context_composite(*, input, output, expected_output, metadata, evaluations):
357                # Adjust weighting based on metadata
358                base_weights = {"accuracy": 0.5, "speed": 0.3, "cost": 0.2}
359
360                # If metadata indicates high importance, prioritize accuracy
361                if metadata and metadata.get('importance') == 'high':
362                    weights = {"accuracy": 0.7, "speed": 0.2, "cost": 0.1}
363                else:
364                    weights = base_weights
365
366                total = sum(
367                    e.value * weights.get(e.name, 0)
368                    for e in evaluations
369                    if isinstance(e.value, (int, float))
370                )
371
372                return Evaluation(
373                    name="weighted_composite",
374                    value=total,
375                    comment="Context-aware weighted composite"
376                )
377            ```
378        """
379        ...

Protocol defining the interface for composite evaluator functions.

Composite evaluators create aggregate scores from multiple item-level evaluations. This is commonly used to compute weighted averages, combined metrics, or other composite assessments based on individual evaluation results.

Composite evaluators:

  • Accept the same inputs as item-level evaluators (input, output, expected_output, metadata) plus the list of evaluations
  • Return either a single Evaluation, a list of Evaluations, or a dict
  • Can be either synchronous or asynchronous
  • Have access to both raw item data and evaluation results
CompositeEvaluatorFunction(*args, **kwargs) 
1927def _no_init_or_replace_init(self, *args, **kwargs):
1928    cls = type(self)
1929
1930    if cls._is_protocol:
1931        raise TypeError('Protocols cannot be instantiated')
1932
1933    # Already using a custom `__init__`. No need to calculate correct
1934    # `__init__` to call. This can lead to RecursionError. See bpo-45121.
1935    if cls.__init__ is not _no_init_or_replace_init:
1936        return
1937
1938    # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`.
1939    # The first instantiation of the subclass will call `_no_init_or_replace_init` which
1940    # searches for a proper new `__init__` in the MRO. The new `__init__`
1941    # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent
1942    # instantiation of the protocol subclass will thus use the new
1943    # `__init__` and no longer call `_no_init_or_replace_init`.
1944    for base in cls.__mro__:
1945        init = base.__dict__.get('__init__', _no_init_or_replace_init)
1946        if init is not _no_init_or_replace_init:
1947            cls.__init__ = init
1948            break
1949    else:
1950        # should not happen
1951        cls.__init__ = object.__init__
1952
1953    cls.__init__(self, *args, **kwargs)
class EvaluatorStats: 
382class EvaluatorStats:
383    """Statistics for a single evaluator's performance during batch evaluation.
384
385    This class tracks detailed metrics about how a specific evaluator performed
386    across all items in a batch evaluation run. It helps identify evaluator issues,
387    understand reliability, and optimize evaluation pipelines.
388
389    Attributes:
390        name: The name of the evaluator function (extracted from __name__).
391        total_runs: Total number of times the evaluator was invoked.
392        successful_runs: Number of times the evaluator completed successfully.
393        failed_runs: Number of times the evaluator raised an exception or failed.
394        total_scores_created: Total number of evaluation scores created by this evaluator.
395            Can be higher than successful_runs if the evaluator returns multiple scores.
396
397    Examples:
398        Accessing evaluator stats from batch evaluation result:
399        ```python
400        result = client.run_batched_evaluation(...)
401
402        for stats in result.evaluator_stats:
403            print(f"Evaluator: {stats.name}")
404            print(f"  Success rate: {stats.successful_runs / stats.total_runs:.1%}")
405            print(f"  Scores created: {stats.total_scores_created}")
406
407            if stats.failed_runs > 0:
408                print(f"  ⚠️  Failed {stats.failed_runs} times")
409        ```
410
411        Identifying problematic evaluators:
412        ```python
413        result = client.run_batched_evaluation(...)
414
415        # Find evaluators with high failure rates
416        for stats in result.evaluator_stats:
417            failure_rate = stats.failed_runs / stats.total_runs
418            if failure_rate > 0.1:  # More than 10% failures
419                print(f"⚠️  {stats.name} has {failure_rate:.1%} failure rate")
420                print(f"    Consider debugging or removing this evaluator")
421        ```
422
423    Note:
424        All arguments must be passed as keywords when instantiating this class.
425    """
426
427    def __init__(
428        self,
429        *,
430        name: str,
431        total_runs: int = 0,
432        successful_runs: int = 0,
433        failed_runs: int = 0,
434        total_scores_created: int = 0,
435    ):
436        """Initialize EvaluatorStats with the provided metrics.
437
438        Args:
439            name: The evaluator function name.
440            total_runs: Total number of evaluator invocations.
441            successful_runs: Number of successful completions.
442            failed_runs: Number of failures.
443            total_scores_created: Total scores created by this evaluator.
444
445        Note:
446            All arguments must be provided as keywords.
447        """
448        self.name = name
449        self.total_runs = total_runs
450        self.successful_runs = successful_runs
451        self.failed_runs = failed_runs
452        self.total_scores_created = total_scores_created

Statistics for a single evaluator's performance during batch evaluation.

This class tracks detailed metrics about how a specific evaluator performed across all items in a batch evaluation run. It helps identify evaluator issues, understand reliability, and optimize evaluation pipelines.

Attributes:
  • name: The name of the evaluator function (extracted from __name__).
  • total_runs: Total number of times the evaluator was invoked.
  • successful_runs: Number of times the evaluator completed successfully.
  • failed_runs: Number of times the evaluator raised an exception or failed.
  • total_scores_created: Total number of evaluation scores created by this evaluator. Can be higher than successful_runs if the evaluator returns multiple scores.
Examples:

Accessing evaluator stats from batch evaluation result:

result = client.run_batched_evaluation(...)

for stats in result.evaluator_stats:
    print(f"Evaluator: {stats.name}")
    print(f"  Success rate: {stats.successful_runs / stats.total_runs:.1%}")
    print(f"  Scores created: {stats.total_scores_created}")

    if stats.failed_runs > 0:
        print(f"  ⚠️  Failed {stats.failed_runs} times")

Identifying problematic evaluators:

result = client.run_batched_evaluation(...)

# Find evaluators with high failure rates
for stats in result.evaluator_stats:
    failure_rate = stats.failed_runs / stats.total_runs
    if failure_rate > 0.1:  # More than 10% failures
        print(f"⚠️  {stats.name} has {failure_rate:.1%} failure rate")
        print(f"    Consider debugging or removing this evaluator")
Note:

All arguments must be passed as keywords when instantiating this class.

EvaluatorStats( *, name: str, total_runs: int = 0, successful_runs: int = 0, failed_runs: int = 0, total_scores_created: int = 0) 
427    def __init__(
428        self,
429        *,
430        name: str,
431        total_runs: int = 0,
432        successful_runs: int = 0,
433        failed_runs: int = 0,
434        total_scores_created: int = 0,
435    ):
436        """Initialize EvaluatorStats with the provided metrics.
437
438        Args:
439            name: The evaluator function name.
440            total_runs: Total number of evaluator invocations.
441            successful_runs: Number of successful completions.
442            failed_runs: Number of failures.
443            total_scores_created: Total scores created by this evaluator.
444
445        Note:
446            All arguments must be provided as keywords.
447        """
448        self.name = name
449        self.total_runs = total_runs
450        self.successful_runs = successful_runs
451        self.failed_runs = failed_runs
452        self.total_scores_created = total_scores_created

Initialize EvaluatorStats with the provided metrics.

Arguments:
  • name: The evaluator function name.
  • total_runs: Total number of evaluator invocations.
  • successful_runs: Number of successful completions.
  • failed_runs: Number of failures.
  • total_scores_created: Total scores created by this evaluator.
Note:

All arguments must be provided as keywords.

name
total_runs
successful_runs
failed_runs
total_scores_created
class BatchEvaluationResumeToken: 
455class BatchEvaluationResumeToken:
456    """Token for resuming a failed batch evaluation run.
457
458    This class encapsulates all the information needed to resume a batch evaluation
459    that was interrupted or failed partway through. It uses timestamp-based filtering
460    to avoid re-processing items that were already evaluated, even if the underlying
461    dataset changed between runs.
462
463    Attributes:
464        scope: The type of items being evaluated ("traces", "observations").
465        filter: The original JSON filter string used to query items.
466        last_processed_timestamp: ISO 8601 timestamp of the last successfully processed item.
467            Used to construct a filter that only fetches items after this timestamp.
468        last_processed_id: The ID of the last successfully processed item, for reference.
469        items_processed: Count of items successfully processed before interruption.
470
471    Examples:
472        Resuming a failed batch evaluation:
473        ```python
474        # Initial run that fails partway through
475        try:
476            result = client.run_batched_evaluation(
477                scope="traces",
478                mapper=my_mapper,
479                evaluators=[evaluator1, evaluator2],
480                filter='{"tags": ["production"]}',
481                max_items=10000
482            )
483        except Exception as e:
484            print(f"Evaluation failed: {e}")
485
486            # Save the resume token
487            if result.resume_token:
488                # Store resume token for later (e.g., in a file or database)
489                import json
490                with open("resume_token.json", "w") as f:
491                    json.dump({
492                        "scope": result.resume_token.scope,
493                        "filter": result.resume_token.filter,
494                        "last_timestamp": result.resume_token.last_processed_timestamp,
495                        "last_id": result.resume_token.last_processed_id,
496                        "items_done": result.resume_token.items_processed
497                    }, f)
498
499        # Later, resume from where it left off
500        with open("resume_token.json") as f:
501            token_data = json.load(f)
502
503        resume_token = BatchEvaluationResumeToken(
504            scope=token_data["scope"],
505            filter=token_data["filter"],
506            last_processed_timestamp=token_data["last_timestamp"],
507            last_processed_id=token_data["last_id"],
508            items_processed=token_data["items_done"]
509        )
510
511        # Resume the evaluation
512        result = client.run_batched_evaluation(
513            scope="traces",
514            mapper=my_mapper,
515            evaluators=[evaluator1, evaluator2],
516            resume_from=resume_token
517        )
518
519        print(f"Processed {result.total_items_processed} additional items")
520        ```
521
522        Handling partial completion:
523        ```python
524        result = client.run_batched_evaluation(...)
525
526        if not result.completed:
527            print(f"Evaluation incomplete. Processed {result.resume_token.items_processed} items")
528            print(f"Last item: {result.resume_token.last_processed_id}")
529            print(f"Resume from: {result.resume_token.last_processed_timestamp}")
530
531            # Optionally retry automatically
532            if result.resume_token:
533                print("Retrying...")
534                result = client.run_batched_evaluation(
535                    scope=result.resume_token.scope,
536                    mapper=my_mapper,
537                    evaluators=my_evaluators,
538                    resume_from=result.resume_token
539                )
540        ```
541
542    Note:
543        All arguments must be passed as keywords when instantiating this class.
544        The timestamp-based approach means that items created after the initial run
545        but before the timestamp will be skipped. This is intentional to avoid
546        duplicates and ensure consistent evaluation.
547    """
548
549    def __init__(
550        self,
551        *,
552        scope: str,
553        filter: Optional[str],
554        last_processed_timestamp: str,
555        last_processed_id: str,
556        items_processed: int,
557    ):
558        """Initialize BatchEvaluationResumeToken with the provided state.
559
560        Args:
561            scope: The scope type ("traces", "observations").
562            filter: The original JSON filter string.
563            last_processed_timestamp: ISO 8601 timestamp of last processed item.
564            last_processed_id: ID of last processed item.
565            items_processed: Count of items processed before interruption.
566
567        Note:
568            All arguments must be provided as keywords.
569        """
570        self.scope = scope
571        self.filter = filter
572        self.last_processed_timestamp = last_processed_timestamp
573        self.last_processed_id = last_processed_id
574        self.items_processed = items_processed

Token for resuming a failed batch evaluation run.

This class encapsulates all the information needed to resume a batch evaluation that was interrupted or failed partway through. It uses timestamp-based filtering to avoid re-processing items that were already evaluated, even if the underlying dataset changed between runs.

Attributes:
  • scope: The type of items being evaluated ("traces", "observations").
  • filter: The original JSON filter string used to query items.
  • last_processed_timestamp: ISO 8601 timestamp of the last successfully processed item. Used to construct a filter that only fetches items after this timestamp.
  • last_processed_id: The ID of the last successfully processed item, for reference.
  • items_processed: Count of items successfully processed before interruption.
Examples:

Resuming a failed batch evaluation:

# Initial run that fails partway through
try:
    result = client.run_batched_evaluation(
        scope="traces",
        mapper=my_mapper,
        evaluators=[evaluator1, evaluator2],
        filter='{"tags": ["production"]}',
        max_items=10000
    )
except Exception as e:
    print(f"Evaluation failed: {e}")

    # Save the resume token
    if result.resume_token:
        # Store resume token for later (e.g., in a file or database)
        import json
        with open("resume_token.json", "w") as f:
            json.dump({
                "scope": result.resume_token.scope,
                "filter": result.resume_token.filter,
                "last_timestamp": result.resume_token.last_processed_timestamp,
                "last_id": result.resume_token.last_processed_id,
                "items_done": result.resume_token.items_processed
            }, f)

# Later, resume from where it left off
with open("resume_token.json") as f:
    token_data = json.load(f)

resume_token = BatchEvaluationResumeToken(
    scope=token_data["scope"],
    filter=token_data["filter"],
    last_processed_timestamp=token_data["last_timestamp"],
    last_processed_id=token_data["last_id"],
    items_processed=token_data["items_done"]
)

# Resume the evaluation
result = client.run_batched_evaluation(
    scope="traces",
    mapper=my_mapper,
    evaluators=[evaluator1, evaluator2],
    resume_from=resume_token
)

print(f"Processed {result.total_items_processed} additional items")

Handling partial completion:

result = client.run_batched_evaluation(...)

if not result.completed:
    print(f"Evaluation incomplete. Processed {result.resume_token.items_processed} items")
    print(f"Last item: {result.resume_token.last_processed_id}")
    print(f"Resume from: {result.resume_token.last_processed_timestamp}")

    # Optionally retry automatically
    if result.resume_token:
        print("Retrying...")
        result = client.run_batched_evaluation(
            scope=result.resume_token.scope,
            mapper=my_mapper,
            evaluators=my_evaluators,
            resume_from=result.resume_token
        )
Note:

All arguments must be passed as keywords when instantiating this class. The timestamp-based approach means that items created after the initial run but before the timestamp will be skipped. This is intentional to avoid duplicates and ensure consistent evaluation.

BatchEvaluationResumeToken( *, scope: str, filter: Optional[str], last_processed_timestamp: str, last_processed_id: str, items_processed: int) 
549    def __init__(
550        self,
551        *,
552        scope: str,
553        filter: Optional[str],
554        last_processed_timestamp: str,
555        last_processed_id: str,
556        items_processed: int,
557    ):
558        """Initialize BatchEvaluationResumeToken with the provided state.
559
560        Args:
561            scope: The scope type ("traces", "observations").
562            filter: The original JSON filter string.
563            last_processed_timestamp: ISO 8601 timestamp of last processed item.
564            last_processed_id: ID of last processed item.
565            items_processed: Count of items processed before interruption.
566
567        Note:
568            All arguments must be provided as keywords.
569        """
570        self.scope = scope
571        self.filter = filter
572        self.last_processed_timestamp = last_processed_timestamp
573        self.last_processed_id = last_processed_id
574        self.items_processed = items_processed

Initialize BatchEvaluationResumeToken with the provided state.

Arguments:
  • scope: The scope type ("traces", "observations").
  • filter: The original JSON filter string.
  • last_processed_timestamp: ISO 8601 timestamp of last processed item.
  • last_processed_id: ID of last processed item.
  • items_processed: Count of items processed before interruption.
Note:

All arguments must be provided as keywords.

scope
filter
last_processed_timestamp
last_processed_id
items_processed
class BatchEvaluationResult: 
577class BatchEvaluationResult:
578    r"""Complete result structure for batch evaluation execution.
579
580    This class encapsulates comprehensive statistics and metadata about a batch
581    evaluation run, including counts, evaluator-specific metrics, timing information,
582    error details, and resume capability.
583
584    Attributes:
585        total_items_fetched: Total number of items fetched from the API.
586        total_items_processed: Number of items successfully evaluated.
587        total_items_failed: Number of items that failed during evaluation.
588        total_scores_created: Total scores created by all item-level evaluators.
589        total_composite_scores_created: Scores created by the composite evaluator.
590        total_evaluations_failed: Number of individual evaluator failures across all items.
591        evaluator_stats: List of per-evaluator statistics (success/failure rates, scores created).
592        resume_token: Token for resuming if evaluation was interrupted (None if completed).
593        completed: True if all items were processed, False if stopped early or failed.
594        duration_seconds: Total time taken to execute the batch evaluation.
595        failed_item_ids: List of IDs for items that failed evaluation.
596        error_summary: Dictionary mapping error types to occurrence counts.
597        has_more_items: True if max_items limit was reached but more items exist.
598        item_evaluations: Dictionary mapping item IDs to their evaluation results (both regular and composite).
599
600    Examples:
601        Basic result inspection:
602        ```python
603        result = client.run_batched_evaluation(...)
604
605        print(f"Processed: {result.total_items_processed}/{result.total_items_fetched}")
606        print(f"Scores created: {result.total_scores_created}")
607        print(f"Duration: {result.duration_seconds:.2f}s")
608        print(f"Success rate: {result.total_items_processed / result.total_items_fetched:.1%}")
609        ```
610
611        Detailed analysis with evaluator stats:
612        ```python
613        result = client.run_batched_evaluation(...)
614
615        print(f"\n📊 Batch Evaluation Results")
616        print(f"{'='*50}")
617        print(f"Items processed: {result.total_items_processed}")
618        print(f"Items failed: {result.total_items_failed}")
619        print(f"Scores created: {result.total_scores_created}")
620
621        if result.total_composite_scores_created > 0:
622            print(f"Composite scores: {result.total_composite_scores_created}")
623
624        print(f"\n📈 Evaluator Performance:")
625        for stats in result.evaluator_stats:
626            success_rate = stats.successful_runs / stats.total_runs if stats.total_runs > 0 else 0
627            print(f"\n  {stats.name}:")
628            print(f"    Success rate: {success_rate:.1%}")
629            print(f"    Scores created: {stats.total_scores_created}")
630            if stats.failed_runs > 0:
631                print(f"    ⚠️  Failures: {stats.failed_runs}")
632
633        if result.error_summary:
634            print(f"\n⚠️  Errors encountered:")
635            for error_type, count in result.error_summary.items():
636                print(f"    {error_type}: {count}")
637        ```
638
639        Handling incomplete runs:
640        ```python
641        result = client.run_batched_evaluation(...)
642
643        if not result.completed:
644            print("⚠️  Evaluation incomplete!")
645
646            if result.resume_token:
647                print(f"Processed {result.resume_token.items_processed} items before failure")
648                print(f"Use resume_from parameter to continue from:")
649                print(f"  Timestamp: {result.resume_token.last_processed_timestamp}")
650                print(f"  Last ID: {result.resume_token.last_processed_id}")
651
652        if result.has_more_items:
653            print(f"ℹ️  More items available beyond max_items limit")
654        ```
655
656        Performance monitoring:
657        ```python
658        result = client.run_batched_evaluation(...)
659
660        items_per_second = result.total_items_processed / result.duration_seconds
661        avg_scores_per_item = result.total_scores_created / result.total_items_processed
662
663        print(f"Performance metrics:")
664        print(f"  Throughput: {items_per_second:.2f} items/second")
665        print(f"  Avg scores/item: {avg_scores_per_item:.2f}")
666        print(f"  Total duration: {result.duration_seconds:.2f}s")
667
668        if result.total_evaluations_failed > 0:
669            failure_rate = result.total_evaluations_failed / (
670                result.total_items_processed * len(result.evaluator_stats)
671            )
672            print(f"  Evaluation failure rate: {failure_rate:.1%}")
673        ```
674
675    Note:
676        All arguments must be passed as keywords when instantiating this class.
677    """
678
679    def __init__(
680        self,
681        *,
682        total_items_fetched: int,
683        total_items_processed: int,
684        total_items_failed: int,
685        total_scores_created: int,
686        total_composite_scores_created: int,
687        total_evaluations_failed: int,
688        evaluator_stats: List[EvaluatorStats],
689        resume_token: Optional[BatchEvaluationResumeToken],
690        completed: bool,
691        duration_seconds: float,
692        failed_item_ids: List[str],
693        error_summary: Dict[str, int],
694        has_more_items: bool,
695        item_evaluations: Dict[str, List["Evaluation"]],
696    ):
697        """Initialize BatchEvaluationResult with comprehensive statistics.
698
699        Args:
700            total_items_fetched: Total items fetched from API.
701            total_items_processed: Items successfully evaluated.
702            total_items_failed: Items that failed evaluation.
703            total_scores_created: Scores from item-level evaluators.
704            total_composite_scores_created: Scores from composite evaluator.
705            total_evaluations_failed: Individual evaluator failures.
706            evaluator_stats: Per-evaluator statistics.
707            resume_token: Token for resuming (None if completed).
708            completed: Whether all items were processed.
709            duration_seconds: Total execution time.
710            failed_item_ids: IDs of failed items.
711            error_summary: Error types and counts.
712            has_more_items: Whether more items exist beyond max_items.
713            item_evaluations: Dictionary mapping item IDs to their evaluation results.
714
715        Note:
716            All arguments must be provided as keywords.
717        """
718        self.total_items_fetched = total_items_fetched
719        self.total_items_processed = total_items_processed
720        self.total_items_failed = total_items_failed
721        self.total_scores_created = total_scores_created
722        self.total_composite_scores_created = total_composite_scores_created
723        self.total_evaluations_failed = total_evaluations_failed
724        self.evaluator_stats = evaluator_stats
725        self.resume_token = resume_token
726        self.completed = completed
727        self.duration_seconds = duration_seconds
728        self.failed_item_ids = failed_item_ids
729        self.error_summary = error_summary
730        self.has_more_items = has_more_items
731        self.item_evaluations = item_evaluations
732
733    def __str__(self) -> str:
734        """Return a formatted string representation of the batch evaluation results.
735
736        Returns:
737            A multi-line string with a summary of the evaluation results.
738        """
739        lines = []
740        lines.append("=" * 60)
741        lines.append("Batch Evaluation Results")
742        lines.append("=" * 60)
743
744        # Summary statistics
745        lines.append(f"\nStatus: {'Completed' if self.completed else 'Incomplete'}")
746        lines.append(f"Duration: {self.duration_seconds:.2f}s")
747        lines.append(f"\nItems fetched: {self.total_items_fetched}")
748        lines.append(f"Items processed: {self.total_items_processed}")
749
750        if self.total_items_failed > 0:
751            lines.append(f"Items failed: {self.total_items_failed}")
752
753        # Success rate
754        if self.total_items_fetched > 0:
755            success_rate = self.total_items_processed / self.total_items_fetched * 100
756            lines.append(f"Success rate: {success_rate:.1f}%")
757
758        # Scores created
759        lines.append(f"\nScores created: {self.total_scores_created}")
760        if self.total_composite_scores_created > 0:
761            lines.append(f"Composite scores: {self.total_composite_scores_created}")
762
763        total_scores = self.total_scores_created + self.total_composite_scores_created
764        lines.append(f"Total scores: {total_scores}")
765
766        # Evaluator statistics
767        if self.evaluator_stats:
768            lines.append("\nEvaluator Performance:")
769            for stats in self.evaluator_stats:
770                lines.append(f"  {stats.name}:")
771                if stats.total_runs > 0:
772                    success_rate = (
773                        stats.successful_runs / stats.total_runs * 100
774                        if stats.total_runs > 0
775                        else 0
776                    )
777                    lines.append(
778                        f"    Runs: {stats.successful_runs}/{stats.total_runs} "
779                        f"({success_rate:.1f}% success)"
780                    )
781                    lines.append(f"    Scores created: {stats.total_scores_created}")
782                    if stats.failed_runs > 0:
783                        lines.append(f"    Failed runs: {stats.failed_runs}")
784
785        # Performance metrics
786        if self.total_items_processed > 0 and self.duration_seconds > 0:
787            items_per_sec = self.total_items_processed / self.duration_seconds
788            lines.append("\nPerformance:")
789            lines.append(f"  Throughput: {items_per_sec:.2f} items/second")
790            if self.total_scores_created > 0:
791                avg_scores = self.total_scores_created / self.total_items_processed
792                lines.append(f"  Avg scores per item: {avg_scores:.2f}")
793
794        # Errors and warnings
795        if self.error_summary:
796            lines.append("\nErrors encountered:")
797            for error_type, count in self.error_summary.items():
798                lines.append(f"  {error_type}: {count}")
799
800        # Incomplete run information
801        if not self.completed:
802            lines.append("\nWarning: Evaluation incomplete")
803            if self.resume_token:
804                lines.append(
805                    f"  Last processed: {self.resume_token.last_processed_timestamp}"
806                )
807                lines.append(f"  Items processed: {self.resume_token.items_processed}")
808                lines.append("  Use resume_from parameter to continue")
809
810        if self.has_more_items:
811            lines.append("\nNote: More items available beyond max_items limit")
812
813        lines.append("=" * 60)
814        return "\n".join(lines)

Complete result structure for batch evaluation execution.

This class encapsulates comprehensive statistics and metadata about a batch evaluation run, including counts, evaluator-specific metrics, timing information, error details, and resume capability.

Attributes:
  • total_items_fetched: Total number of items fetched from the API.
  • total_items_processed: Number of items successfully evaluated.
  • total_items_failed: Number of items that failed during evaluation.
  • total_scores_created: Total scores created by all item-level evaluators.
  • total_composite_scores_created: Scores created by the composite evaluator.
  • total_evaluations_failed: Number of individual evaluator failures across all items.
  • evaluator_stats: List of per-evaluator statistics (success/failure rates, scores created).
  • resume_token: Token for resuming if evaluation was interrupted (None if completed).
  • completed: True if all items were processed, False if stopped early or failed.
  • duration_seconds: Total time taken to execute the batch evaluation.
  • failed_item_ids: List of IDs for items that failed evaluation.
  • error_summary: Dictionary mapping error types to occurrence counts.
  • has_more_items: True if max_items limit was reached but more items exist.
  • item_evaluations: Dictionary mapping item IDs to their evaluation results (both regular and composite).
Examples:

Basic result inspection:

result = client.run_batched_evaluation(...)

print(f"Processed: {result.total_items_processed}/{result.total_items_fetched}")
print(f"Scores created: {result.total_scores_created}")
print(f"Duration: {result.duration_seconds:.2f}s")
print(f"Success rate: {result.total_items_processed / result.total_items_fetched:.1%}")

Detailed analysis with evaluator stats:

result = client.run_batched_evaluation(...)

print(f"\n📊 Batch Evaluation Results")
print(f"{'='*50}")
print(f"Items processed: {result.total_items_processed}")
print(f"Items failed: {result.total_items_failed}")
print(f"Scores created: {result.total_scores_created}")

if result.total_composite_scores_created > 0:
    print(f"Composite scores: {result.total_composite_scores_created}")

print(f"\n📈 Evaluator Performance:")
for stats in result.evaluator_stats:
    success_rate = stats.successful_runs / stats.total_runs if stats.total_runs > 0 else 0
    print(f"\n  {stats.name}:")
    print(f"    Success rate: {success_rate:.1%}")
    print(f"    Scores created: {stats.total_scores_created}")
    if stats.failed_runs > 0:
        print(f"    ⚠️  Failures: {stats.failed_runs}")

if result.error_summary:
    print(f"\n⚠️  Errors encountered:")
    for error_type, count in result.error_summary.items():
        print(f"    {error_type}: {count}")

Handling incomplete runs:

result = client.run_batched_evaluation(...)

if not result.completed:
    print("⚠️  Evaluation incomplete!")

    if result.resume_token:
        print(f"Processed {result.resume_token.items_processed} items before failure")
        print(f"Use resume_from parameter to continue from:")
        print(f"  Timestamp: {result.resume_token.last_processed_timestamp}")
        print(f"  Last ID: {result.resume_token.last_processed_id}")

if result.has_more_items:
    print(f"ℹ️  More items available beyond max_items limit")

Performance monitoring:

result = client.run_batched_evaluation(...)

items_per_second = result.total_items_processed / result.duration_seconds
avg_scores_per_item = result.total_scores_created / result.total_items_processed

print(f"Performance metrics:")
print(f"  Throughput: {items_per_second:.2f} items/second")
print(f"  Avg scores/item: {avg_scores_per_item:.2f}")
print(f"  Total duration: {result.duration_seconds:.2f}s")

if result.total_evaluations_failed > 0:
    failure_rate = result.total_evaluations_failed / (
        result.total_items_processed * len(result.evaluator_stats)
    )
    print(f"  Evaluation failure rate: {failure_rate:.1%}")
Note:

All arguments must be passed as keywords when instantiating this class.

BatchEvaluationResult( *, total_items_fetched: int, total_items_processed: int, total_items_failed: int, total_scores_created: int, total_composite_scores_created: int, total_evaluations_failed: int, evaluator_stats: List[EvaluatorStats], resume_token: Optional[BatchEvaluationResumeToken], completed: bool, duration_seconds: float, failed_item_ids: List[str], error_summary: Dict[str, int], has_more_items: bool, item_evaluations: Dict[str, List[Evaluation]]) 
679    def __init__(
680        self,
681        *,
682        total_items_fetched: int,
683        total_items_processed: int,
684        total_items_failed: int,
685        total_scores_created: int,
686        total_composite_scores_created: int,
687        total_evaluations_failed: int,
688        evaluator_stats: List[EvaluatorStats],
689        resume_token: Optional[BatchEvaluationResumeToken],
690        completed: bool,
691        duration_seconds: float,
692        failed_item_ids: List[str],
693        error_summary: Dict[str, int],
694        has_more_items: bool,
695        item_evaluations: Dict[str, List["Evaluation"]],
696    ):
697        """Initialize BatchEvaluationResult with comprehensive statistics.
698
699        Args:
700            total_items_fetched: Total items fetched from API.
701            total_items_processed: Items successfully evaluated.
702            total_items_failed: Items that failed evaluation.
703            total_scores_created: Scores from item-level evaluators.
704            total_composite_scores_created: Scores from composite evaluator.
705            total_evaluations_failed: Individual evaluator failures.
706            evaluator_stats: Per-evaluator statistics.
707            resume_token: Token for resuming (None if completed).
708            completed: Whether all items were processed.
709            duration_seconds: Total execution time.
710            failed_item_ids: IDs of failed items.
711            error_summary: Error types and counts.
712            has_more_items: Whether more items exist beyond max_items.
713            item_evaluations: Dictionary mapping item IDs to their evaluation results.
714
715        Note:
716            All arguments must be provided as keywords.
717        """
718        self.total_items_fetched = total_items_fetched
719        self.total_items_processed = total_items_processed
720        self.total_items_failed = total_items_failed
721        self.total_scores_created = total_scores_created
722        self.total_composite_scores_created = total_composite_scores_created
723        self.total_evaluations_failed = total_evaluations_failed
724        self.evaluator_stats = evaluator_stats
725        self.resume_token = resume_token
726        self.completed = completed
727        self.duration_seconds = duration_seconds
728        self.failed_item_ids = failed_item_ids
729        self.error_summary = error_summary
730        self.has_more_items = has_more_items
731        self.item_evaluations = item_evaluations

Initialize BatchEvaluationResult with comprehensive statistics.

Arguments:
  • total_items_fetched: Total items fetched from API.
  • total_items_processed: Items successfully evaluated.
  • total_items_failed: Items that failed evaluation.
  • total_scores_created: Scores from item-level evaluators.
  • total_composite_scores_created: Scores from composite evaluator.
  • total_evaluations_failed: Individual evaluator failures.
  • evaluator_stats: Per-evaluator statistics.
  • resume_token: Token for resuming (None if completed).
  • completed: Whether all items were processed.
  • duration_seconds: Total execution time.
  • failed_item_ids: IDs of failed items.
  • error_summary: Error types and counts.
  • has_more_items: Whether more items exist beyond max_items.
  • item_evaluations: Dictionary mapping item IDs to their evaluation results.
Note:

All arguments must be provided as keywords.

total_items_fetched
total_items_processed
total_items_failed
total_scores_created
total_composite_scores_created
total_evaluations_failed
evaluator_stats
resume_token
completed
duration_seconds
failed_item_ids
error_summary
has_more_items
item_evaluations
class RunnerContext: 
1062class RunnerContext:
1063    """Wraps :meth:`Langfuse.run_experiment` with CI-injected defaults.
1064
1065    Intended for use with the ``langfuse/experiment-action`` GitHub Action
1066    (https://github.com/langfuse/experiment-action). The action builds a
1067    ``RunnerContext`` before invoking the user's ``experiment(context)``
1068    function. Defaults set here (dataset, metadata tags) are applied when
1069    the user omits them on the :meth:`run_experiment` call; users can
1070    override any default by passing the corresponding argument explicitly.
1071    """
1072
1073    def __init__(
1074        self,
1075        *,
1076        client: "Langfuse",
1077        data: Optional[ExperimentData] = None,
1078        dataset_version: Optional[datetime] = None,
1079        metadata: Optional[Dict[str, str]] = None,
1080    ):
1081        """Build a ``RunnerContext`` populated with defaults for ``run_experiment``.
1082
1083        Typically called by the ``langfuse/experiment-action`` GitHub Action,
1084        not by end users directly. Every field except ``client`` is optional:
1085        fields left as ``None`` simply mean the corresponding argument must be
1086        supplied on the :meth:`run_experiment` call.
1087
1088        Args:
1089            client: Initialized Langfuse SDK client used to execute the
1090                experiment. The action creates this from the
1091                ``langfuse_public_key`` / ``langfuse_secret_key`` /
1092                ``langfuse_base_url`` inputs.
1093            data: Default dataset items to run the experiment on. Accepts
1094                either ``List[LocalExperimentItem]`` or ``List[DatasetItem]``.
1095                Injected by the action when ``dataset_name`` is configured.
1096                If ``None``, the user must pass ``data=`` to
1097                :meth:`run_experiment`.
1098            dataset_version: Optional pinned dataset version. Injected by the
1099                action when ``dataset_version`` is configured.
1100            metadata: Default metadata attached to every experiment trace and
1101                the dataset run. The action injects GitHub-sourced tags (SHA,
1102                PR link, workflow run link, branch, GH user, etc.). Merged
1103                with any ``metadata`` passed to :meth:`run_experiment`, with
1104                user-supplied keys winning on collision.
1105        """
1106        self.client = client
1107        self.data = data
1108        self.dataset_version = dataset_version
1109        self.metadata = metadata
1110
1111    def run_experiment(
1112        self,
1113        *,
1114        name: str,
1115        run_name: Optional[str] = None,
1116        description: Optional[str] = None,
1117        data: Optional[ExperimentData] = None,
1118        task: TaskFunction,
1119        evaluators: List[EvaluatorFunction] = [],
1120        composite_evaluator: Optional["CompositeEvaluatorFunction"] = None,
1121        run_evaluators: List[RunEvaluatorFunction] = [],
1122        max_concurrency: int = 50,
1123        metadata: Optional[Dict[str, str]] = None,
1124        _dataset_version: Optional[datetime] = None,
1125    ) -> ExperimentResult:
1126        resolved_data = data if data is not None else self.data
1127        if resolved_data is None:
1128            raise ValueError(
1129                "`data` must be provided either on the RunnerContext or the run_experiment call"
1130            )
1131
1132        resolved_dataset_version = (
1133            _dataset_version if _dataset_version is not None else self.dataset_version
1134        )
1135
1136        merged_metadata: Optional[Dict[str, str]]
1137        if self.metadata is None and metadata is None:
1138            merged_metadata = None
1139        else:
1140            merged_metadata = {**(self.metadata or {}), **(metadata or {})}
1141
1142        return self.client.run_experiment(
1143            name=name,
1144            run_name=run_name,
1145            description=description,
1146            data=resolved_data,
1147            task=task,
1148            evaluators=evaluators,
1149            composite_evaluator=composite_evaluator,
1150            run_evaluators=run_evaluators,
1151            max_concurrency=max_concurrency,
1152            metadata=merged_metadata,
1153            _dataset_version=resolved_dataset_version,
1154        )

Wraps Langfuse.run_experiment() with CI-injected defaults.

Intended for use with the langfuse/experiment-action GitHub Action (https://github.com/langfuse/experiment-action). The action builds a RunnerContext before invoking the user's experiment(context) function. Defaults set here (dataset, metadata tags) are applied when the user omits them on the run_experiment() call; users can override any default by passing the corresponding argument explicitly.

RunnerContext( *, client: Langfuse, data: Union[List[langfuse.experiment.LocalExperimentItem], List[langfuse.api.DatasetItem], NoneType] = None, dataset_version: Optional[datetime.datetime] = None, metadata: Optional[Dict[str, str]] = None) 
1073    def __init__(
1074        self,
1075        *,
1076        client: "Langfuse",
1077        data: Optional[ExperimentData] = None,
1078        dataset_version: Optional[datetime] = None,
1079        metadata: Optional[Dict[str, str]] = None,
1080    ):
1081        """Build a ``RunnerContext`` populated with defaults for ``run_experiment``.
1082
1083        Typically called by the ``langfuse/experiment-action`` GitHub Action,
1084        not by end users directly. Every field except ``client`` is optional:
1085        fields left as ``None`` simply mean the corresponding argument must be
1086        supplied on the :meth:`run_experiment` call.
1087
1088        Args:
1089            client: Initialized Langfuse SDK client used to execute the
1090                experiment. The action creates this from the
1091                ``langfuse_public_key`` / ``langfuse_secret_key`` /
1092                ``langfuse_base_url`` inputs.
1093            data: Default dataset items to run the experiment on. Accepts
1094                either ``List[LocalExperimentItem]`` or ``List[DatasetItem]``.
1095                Injected by the action when ``dataset_name`` is configured.
1096                If ``None``, the user must pass ``data=`` to
1097                :meth:`run_experiment`.
1098            dataset_version: Optional pinned dataset version. Injected by the
1099                action when ``dataset_version`` is configured.
1100            metadata: Default metadata attached to every experiment trace and
1101                the dataset run. The action injects GitHub-sourced tags (SHA,
1102                PR link, workflow run link, branch, GH user, etc.). Merged
1103                with any ``metadata`` passed to :meth:`run_experiment`, with
1104                user-supplied keys winning on collision.
1105        """
1106        self.client = client
1107        self.data = data
1108        self.dataset_version = dataset_version
1109        self.metadata = metadata

Build a RunnerContext populated with defaults for run_experiment.

Typically called by the langfuse/experiment-action GitHub Action, not by end users directly. Every field except client is optional: fields left as None simply mean the corresponding argument must be supplied on the run_experiment() call.

Arguments:
  • client: Initialized Langfuse SDK client used to execute the experiment. The action creates this from the langfuse_public_key / langfuse_secret_key / langfuse_base_url inputs.
  • data: Default dataset items to run the experiment on. Accepts either List[LocalExperimentItem] or List[DatasetItem]. Injected by the action when dataset_name is configured. If None, the user must pass data= to run_experiment().
  • dataset_version: Optional pinned dataset version. Injected by the action when dataset_version is configured.
  • metadata: Default metadata attached to every experiment trace and the dataset run. The action injects GitHub-sourced tags (SHA, PR link, workflow run link, branch, GH user, etc.). Merged with any metadata passed to run_experiment(), with user-supplied keys winning on collision.
client
data
dataset_version
metadata
def run_experiment( self, *, name: str, run_name: Optional[str] = None, description: Optional[str] = None, data: Union[List[langfuse.experiment.LocalExperimentItem], List[langfuse.api.DatasetItem], NoneType] = None, task: langfuse.experiment.TaskFunction, evaluators: List[langfuse.experiment.EvaluatorFunction] = [], composite_evaluator: Optional[CompositeEvaluatorFunction] = None, run_evaluators: List[langfuse.experiment.RunEvaluatorFunction] = [], max_concurrency: int = 50, metadata: Optional[Dict[str, str]] = None, _dataset_version: Optional[datetime.datetime] = None) -> langfuse.experiment.ExperimentResult: 
1111    def run_experiment(
1112        self,
1113        *,
1114        name: str,
1115        run_name: Optional[str] = None,
1116        description: Optional[str] = None,
1117        data: Optional[ExperimentData] = None,
1118        task: TaskFunction,
1119        evaluators: List[EvaluatorFunction] = [],
1120        composite_evaluator: Optional["CompositeEvaluatorFunction"] = None,
1121        run_evaluators: List[RunEvaluatorFunction] = [],
1122        max_concurrency: int = 50,
1123        metadata: Optional[Dict[str, str]] = None,
1124        _dataset_version: Optional[datetime] = None,
1125    ) -> ExperimentResult:
1126        resolved_data = data if data is not None else self.data
1127        if resolved_data is None:
1128            raise ValueError(
1129                "`data` must be provided either on the RunnerContext or the run_experiment call"
1130            )
1131
1132        resolved_dataset_version = (
1133            _dataset_version if _dataset_version is not None else self.dataset_version
1134        )
1135
1136        merged_metadata: Optional[Dict[str, str]]
1137        if self.metadata is None and metadata is None:
1138            merged_metadata = None
1139        else:
1140            merged_metadata = {**(self.metadata or {}), **(metadata or {})}
1141
1142        return self.client.run_experiment(
1143            name=name,
1144            run_name=run_name,
1145            description=description,
1146            data=resolved_data,
1147            task=task,
1148            evaluators=evaluators,
1149            composite_evaluator=composite_evaluator,
1150            run_evaluators=run_evaluators,
1151            max_concurrency=max_concurrency,
1152            metadata=merged_metadata,
1153            _dataset_version=resolved_dataset_version,
1154        )
class RegressionError(builtins.Exception): 
1157class RegressionError(Exception):
1158    """Raised by a user's ``experiment`` function to signal a CI gate failure.
1159
1160    Intended for use with the ``langfuse/experiment-action`` GitHub Action
1161    (https://github.com/langfuse/experiment-action). The action catches this
1162    exception and, when ``should_fail_on_error`` is enabled, fails the
1163    workflow run and renders a callout in the PR comment using
1164    ``metric``/``value``/``threshold`` if supplied, otherwise ``str(exc)``.
1165
1166    Callers choose one of three forms:
1167
1168    - ``RegressionError(result=r)`` — minimal, generic message.
1169    - ``RegressionError(result=r, message="...")`` — free-form message.
1170    - ``RegressionError(result=r, metric="acc", value=0.7, threshold=0.9)`` —
1171      structured; ``metric`` and ``value`` must be provided together so the
1172      action can render a targeted callout without ``None`` placeholders.
1173    """
1174
1175    @overload
1176    def __init__(self, *, result: ExperimentResult) -> None: ...
1177    @overload
1178    def __init__(self, *, result: ExperimentResult, message: str) -> None: ...
1179    @overload
1180    def __init__(
1181        self,
1182        *,
1183        result: ExperimentResult,
1184        metric: str,
1185        value: float,
1186        threshold: Optional[float] = None,
1187        message: Optional[str] = None,
1188    ) -> None: ...
1189    def __init__(
1190        self,
1191        *,
1192        result: ExperimentResult,
1193        metric: Optional[str] = None,
1194        value: Optional[float] = None,
1195        threshold: Optional[float] = None,
1196        message: Optional[str] = None,
1197    ):
1198        self.result = result
1199        self.metric = metric
1200        self.value = value
1201        self.threshold = threshold
1202        if message is not None:
1203            formatted = message
1204        elif metric is not None and value is not None:
1205            formatted = f"Regression on `{metric}`: {value} (threshold {threshold})"
1206        else:
1207            formatted = "Experiment regression detected"
1208        super().__init__(formatted)

Raised by a user's experiment function to signal a CI gate failure.

Intended for use with the langfuse/experiment-action GitHub Action (https://github.com/langfuse/experiment-action). The action catches this exception and, when should_fail_on_error is enabled, fails the workflow run and renders a callout in the PR comment using metric/value/threshold if supplied, otherwise str(exc).

Callers choose one of three forms:

  • RegressionError(result=r) — minimal, generic message.
  • RegressionError(result=r, message="...") — free-form message.
  • RegressionError(result=r, metric="acc", value=0.7, threshold=0.9) — structured; metric and value must be provided together so the action can render a targeted callout without None placeholders.
RegressionError( *, result: langfuse.experiment.ExperimentResult, metric: Optional[str] = None, value: Optional[float] = None, threshold: Optional[float] = None, message: Optional[str] = None) 
1189    def __init__(
1190        self,
1191        *,
1192        result: ExperimentResult,
1193        metric: Optional[str] = None,
1194        value: Optional[float] = None,
1195        threshold: Optional[float] = None,
1196        message: Optional[str] = None,
1197    ):
1198        self.result = result
1199        self.metric = metric
1200        self.value = value
1201        self.threshold = threshold
1202        if message is not None:
1203            formatted = message
1204        elif metric is not None and value is not None:
1205            formatted = f"Regression on `{metric}`: {value} (threshold {threshold})"
1206        else:
1207            formatted = "Experiment regression detected"
1208        super().__init__(formatted)
result
metric
value
threshold
__version__ = '4.14.0'
def is_default_export_span(span: opentelemetry.sdk.trace.ReadableSpan) -> bool: 
105def is_default_export_span(span: ReadableSpan) -> bool:
106    """Return whether a span should be exported by default."""
107    return (
108        is_langfuse_span(span) or is_genai_span(span) or is_known_llm_instrumentor(span)
109    )

Return whether a span should be exported by default.

def is_langfuse_span(span: opentelemetry.sdk.trace.ReadableSpan) -> bool: 
68def is_langfuse_span(span: ReadableSpan) -> bool:
69    """Return whether the span was created by the Langfuse SDK tracer."""
70    return (
71        span.instrumentation_scope is not None
72        and span.instrumentation_scope.name == LANGFUSE_TRACER_NAME
73    )

Return whether the span was created by the Langfuse SDK tracer.

def is_genai_span(span: opentelemetry.sdk.trace.ReadableSpan) -> bool: 
76def is_genai_span(span: ReadableSpan) -> bool:
77    """Return whether the span has any ``gen_ai.*`` semantic convention attribute."""
78    if span.attributes is None:
79        return False
80
81    return any(
82        isinstance(key, str) and key.startswith("gen_ai")
83        for key in span.attributes.keys()
84    )

Return whether the span has any gen_ai.* semantic convention attribute.

def is_known_llm_instrumentor(span: opentelemetry.sdk.trace.ReadableSpan) -> bool: 
 92def is_known_llm_instrumentor(span: ReadableSpan) -> bool:
 93    """Return whether the span comes from a known LLM instrumentation scope."""
 94    if span.instrumentation_scope is None:
 95        return False
 96
 97    scope_name = span.instrumentation_scope.name
 98
 99    return any(
100        _matches_scope_prefix(scope_name, prefix)
101        for prefix in KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES
102    )

Return whether the span comes from a known LLM instrumentation scope.

KNOWN_LLM_INSTRUMENTATION_SCOPE_PREFIXES = frozenset({'autogen-core', 'opentelemetry.instrumentation.vertexai', 'opentelemetry.instrumentation.sagemaker', 'opentelemetry.instrumentation.agno', 'vllm', 'opentelemetry.instrumentation.ollama', 'opentelemetry.instrumentation.writer', 'opentelemetry.instrumentation.groq', 'opentelemetry.instrumentation.langchain', 'opentelemetry.instrumentation.together', 'opentelemetry.instrumentation.mistralai', 'opentelemetry.instrumentation.voyageai', 'litellm', 'haystack', 'opentelemetry.instrumentation.alephalpha', 'langsmith', 'opentelemetry.instrumentation.crewai', 'opentelemetry.instrumentation.transformers', 'opentelemetry.instrumentation.cohere', 'opentelemetry.instrumentation.google_generativeai', 'opentelemetry.instrumentation.bedrock', 'opentelemetry.instrumentation.openai', 'openinference', 'opentelemetry.instrumentation.replicate', 'langfuse-sdk', 'strands-agents', 'opentelemetry.instrumentation.watsonx', 'opentelemetry.instrumentation.openai_v2', 'opentelemetry.instrumentation.llamaindex', 'agent_framework', 'opentelemetry.instrumentation.openai_agents', 'ai', 'opentelemetry.instrumentation.anthropic', 'pydantic-ai', 'opentelemetry.instrumentation.haystack'})
class MaskOtelSpansFunction(typing.Protocol): 
224class MaskOtelSpansFunction(Protocol):
225    """Function protocol for export-stage OpenTelemetry span masking.
226
227    `mask_otel_spans` runs after Langfuse decides which spans this client should
228    export and after export-stage media handling has converted supported media
229    payloads into Langfuse media references. It affects only the spans exported
230    by this Langfuse client. If the same OpenTelemetry spans are sent to another
231    exporter, that exporter receives its own unmodified copy.
232
233    The function is synchronous. It usually runs on the OpenTelemetry batch span
234    processor worker thread; during `flush()` and shutdown it may run on the
235    caller thread. Keep it deterministic and fast, and avoid relying on request
236    locals, the current active span, or async I/O.
237
238    Return `None` to leave the whole batch unchanged, or return
239    `MaskOtelSpansResult` with sparse patches for the spans that should change.
240
241    Example:
242        ```python
243        from typing import Optional
244
245        from langfuse import Langfuse
246        from langfuse.types import (
247            MaskOtelSpansParams,
248            MaskOtelSpansResult,
249            OtelSpanPatch,
250        )
251
252        def mask_otel_spans(
253            *, params: MaskOtelSpansParams
254        ) -> Optional[MaskOtelSpansResult]:
255            patches = {}
256
257            for identifier, span in params.spans.items():
258                if span.instrumentation_scope_name == "openai":
259                    patches[identifier] = OtelSpanPatch(
260                        delete_attributes=(
261                            "gen_ai.prompt.0.content",
262                            "gen_ai.completion.0.content",
263                        ),
264                        set_attributes={"masking.applied": True},
265                    )
266
267            return MaskOtelSpansResult(span_patches=patches)
268
269        langfuse = Langfuse(mask_otel_spans=mask_otel_spans)
270        ```
271    """
272
273    def __call__(
274        self, *, params: MaskOtelSpansParams
275    ) -> Optional[MaskOtelSpansResult]: ...

Function protocol for export-stage OpenTelemetry span masking.

mask_otel_spans runs after Langfuse decides which spans this client should export and after export-stage media handling has converted supported media payloads into Langfuse media references. It affects only the spans exported by this Langfuse client. If the same OpenTelemetry spans are sent to another exporter, that exporter receives its own unmodified copy.

The function is synchronous. It usually runs on the OpenTelemetry batch span processor worker thread; during flush() and shutdown it may run on the caller thread. Keep it deterministic and fast, and avoid relying on request locals, the current active span, or async I/O.

Return None to leave the whole batch unchanged, or return MaskOtelSpansResult with sparse patches for the spans that should change.

Example:
from typing import Optional

from langfuse import Langfuse
from langfuse.types import (
    MaskOtelSpansParams,
    MaskOtelSpansResult,
    OtelSpanPatch,
)

def mask_otel_spans(
    *, params: MaskOtelSpansParams
) -> Optional[MaskOtelSpansResult]:
    patches = {}

    for identifier, span in params.spans.items():
        if span.instrumentation_scope_name == "openai":
            patches[identifier] = OtelSpanPatch(
                delete_attributes=(
                    "gen_ai.prompt.0.content",
                    "gen_ai.completion.0.content",
                ),
                set_attributes={"masking.applied": True},
            )

    return MaskOtelSpansResult(span_patches=patches)

langfuse = Langfuse(mask_otel_spans=mask_otel_spans)
MaskOtelSpansFunction(*args, **kwargs) 
1927def _no_init_or_replace_init(self, *args, **kwargs):
1928    cls = type(self)
1929
1930    if cls._is_protocol:
1931        raise TypeError('Protocols cannot be instantiated')
1932
1933    # Already using a custom `__init__`. No need to calculate correct
1934    # `__init__` to call. This can lead to RecursionError. See bpo-45121.
1935    if cls.__init__ is not _no_init_or_replace_init:
1936        return
1937
1938    # Initially, `__init__` of a protocol subclass is set to `_no_init_or_replace_init`.
1939    # The first instantiation of the subclass will call `_no_init_or_replace_init` which
1940    # searches for a proper new `__init__` in the MRO. The new `__init__`
1941    # replaces the subclass' old `__init__` (ie `_no_init_or_replace_init`). Subsequent
1942    # instantiation of the protocol subclass will thus use the new
1943    # `__init__` and no longer call `_no_init_or_replace_init`.
1944    for base in cls.__mro__:
1945        init = base.__dict__.get('__init__', _no_init_or_replace_init)
1946        if init is not _no_init_or_replace_init:
1947            cls.__init__ = init
1948            break
1949    else:
1950        # should not happen
1951        cls.__init__ = object.__init__
1952
1953    cls.__init__(self, *args, **kwargs)
@dataclass(frozen=True)
class MaskOtelSpansParams: 
123@dataclass(frozen=True)
124class MaskOtelSpansParams:
125    """Input passed to an export-stage OpenTelemetry span masking function.
126
127    A single call receives one OpenTelemetry export batch, not necessarily a
128    complete trace, request, or Langfuse observation tree. Batch contents depend
129    on OpenTelemetry span processor settings such as `flush_at`,
130    `flush_interval`, explicit `flush()`, and shutdown.
131
132    Example:
133        ```python
134        from typing import Optional
135
136        from langfuse.types import (
137            MaskOtelSpansParams,
138            MaskOtelSpansResult,
139            OtelSpanPatch,
140        )
141
142        def mask_otel_spans(
143            *, params: MaskOtelSpansParams
144        ) -> Optional[MaskOtelSpansResult]:
145            patches = {}
146
147            for identifier, span in params.spans.items():
148                if "http.request.header.authorization" in span.attributes:
149                    patches[identifier] = OtelSpanPatch(
150                        delete_attributes=("http.request.header.authorization",),
151                        set_attributes={"security.redacted": True},
152                    )
153
154            return MaskOtelSpansResult(span_patches=patches)
155        ```
156
157    Attributes:
158        spans: Read-only mapping from stable span identifiers to span snapshots.
159            Return patches using keys from this mapping.
160    """
161
162    spans: Mapping[OtelSpanIdentifier, OtelSpanData]

Input passed to an export-stage OpenTelemetry span masking function.

A single call receives one OpenTelemetry export batch, not necessarily a complete trace, request, or Langfuse observation tree. Batch contents depend on OpenTelemetry span processor settings such as flush_at, flush_interval, explicit flush(), and shutdown.

Example:
from typing import Optional

from langfuse.types import (
    MaskOtelSpansParams,
    MaskOtelSpansResult,
    OtelSpanPatch,
)

def mask_otel_spans(
    *, params: MaskOtelSpansParams
) -> Optional[MaskOtelSpansResult]:
    patches = {}

    for identifier, span in params.spans.items():
        if "http.request.header.authorization" in span.attributes:
            patches[identifier] = OtelSpanPatch(
                delete_attributes=("http.request.header.authorization",),
                set_attributes={"security.redacted": True},
            )

    return MaskOtelSpansResult(span_patches=patches)
Attributes:
  • spans: Read-only mapping from stable span identifiers to span snapshots. Return patches using keys from this mapping.
MaskOtelSpansParams( spans: Mapping[OtelSpanIdentifier, OtelSpanData])
spans: Mapping[OtelSpanIdentifier, OtelSpanData]
@dataclass(frozen=True)
class MaskOtelSpansResult: 
200@dataclass(frozen=True)
201class MaskOtelSpansResult:
202    """Patches returned by a `mask_otel_spans` function.
203
204    Omit spans that do not need changes. A mapping value of `None` also leaves
205    that span unchanged. Returning an invalid patch to drop a span is not a
206    supported API; use `should_export_span` when you need span-level export
207    filtering.
208
209    If `mask_otel_spans` raises or returns an object that is not a
210    `MaskOtelSpansResult`, Langfuse drops the whole export batch. If one
211    individual `OtelSpanPatch` is invalid, Langfuse drops only that span from
212    the export batch.
213
214    Attributes:
215        span_patches: Mapping from identifiers in `MaskOtelSpansParams.spans` to
216            sparse attribute patches.
217    """
218
219    span_patches: Mapping[OtelSpanIdentifier, Optional[OtelSpanPatch]] = field(
220        default_factory=lambda: MappingProxyType({})
221    )

Patches returned by a mask_otel_spans function.

Omit spans that do not need changes. A mapping value of None also leaves that span unchanged. Returning an invalid patch to drop a span is not a supported API; use should_export_span when you need span-level export filtering.

If mask_otel_spans raises or returns an object that is not a MaskOtelSpansResult, Langfuse drops the whole export batch. If one individual OtelSpanPatch is invalid, Langfuse drops only that span from the export batch.

Attributes:
MaskOtelSpansResult( span_patches: Mapping[OtelSpanIdentifier, Optional[OtelSpanPatch]] = <factory>)
span_patches: Mapping[OtelSpanIdentifier, Optional[OtelSpanPatch]]
@dataclass(frozen=True)
class OtelSpanData: 
 82@dataclass(frozen=True)
 83class OtelSpanData:
 84    """Read-only OpenTelemetry span snapshot passed to `mask_otel_spans`.
 85
 86    The snapshot contains the span data that Langfuse is about to export after
 87    the SDK has applied `should_export_span` filtering and export-stage media
 88    processing. The mappings are immutable views and mutating them is not
 89    supported; return an `OtelSpanPatch` to change exported attributes.
 90
 91    `mask_otel_spans` can only change span attributes. It cannot change the
 92    span name, IDs, parent relationship, resource attributes, events, links, or
 93    instrumentation scope.
 94
 95    Attributes:
 96        trace_id: Lowercase 32-character hexadecimal OpenTelemetry trace ID.
 97        span_id: Lowercase 16-character hexadecimal OpenTelemetry span ID.
 98        parent_span_id: Lowercase hexadecimal parent span ID, or `None` for a
 99            root span or when the parent is not available.
100        name: OpenTelemetry span name.
101        instrumentation_scope_name: Name of the instrumentation scope that
102            emitted the span, for example `openai` or `langfuse`.
103        instrumentation_scope_version: Version of the instrumentation scope, if
104            the instrumentation library provided one.
105        attributes: Read-only attributes that will be exported unless patched.
106            Values use OpenTelemetry `AttributeValue` types: strings, booleans,
107            numbers, or homogeneous sequences of those scalar values.
108        resource_attributes: Read-only resource attributes from the span's
109            OpenTelemetry resource. These are available for decisions only and
110            cannot be patched through `mask_otel_spans`.
111    """
112
113    trace_id: str
114    span_id: str
115    parent_span_id: Optional[str]
116    name: str
117    instrumentation_scope_name: Optional[str]
118    instrumentation_scope_version: Optional[str]
119    attributes: Mapping[str, AttributeValue]
120    resource_attributes: Mapping[str, AttributeValue]

Read-only OpenTelemetry span snapshot passed to mask_otel_spans.

The snapshot contains the span data that Langfuse is about to export after the SDK has applied should_export_span filtering and export-stage media processing. The mappings are immutable views and mutating them is not supported; return an OtelSpanPatch to change exported attributes.

mask_otel_spans can only change span attributes. It cannot change the span name, IDs, parent relationship, resource attributes, events, links, or instrumentation scope.

Attributes:
  • trace_id: Lowercase 32-character hexadecimal OpenTelemetry trace ID.
  • span_id: Lowercase 16-character hexadecimal OpenTelemetry span ID.
  • parent_span_id: Lowercase hexadecimal parent span ID, or None for a root span or when the parent is not available.
  • name: OpenTelemetry span name.
  • instrumentation_scope_name: Name of the instrumentation scope that emitted the span, for example openai or langfuse.
  • instrumentation_scope_version: Version of the instrumentation scope, if the instrumentation library provided one.
  • attributes: Read-only attributes that will be exported unless patched. Values use OpenTelemetry AttributeValue types: strings, booleans, numbers, or homogeneous sequences of those scalar values.
  • resource_attributes: Read-only resource attributes from the span's OpenTelemetry resource. These are available for decisions only and cannot be patched through mask_otel_spans.
OtelSpanData( trace_id: str, span_id: str, parent_span_id: Optional[str], name: str, instrumentation_scope_name: Optional[str], instrumentation_scope_version: Optional[str], attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]], resource_attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]])
trace_id: str
span_id: str
parent_span_id: Optional[str]
name: str
instrumentation_scope_name: Optional[str]
instrumentation_scope_version: Optional[str]
attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]]
resource_attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]]
@dataclass(frozen=True)
class OtelSpanIdentifier: 
65@dataclass(frozen=True)
66class OtelSpanIdentifier:
67    """Stable key for one OpenTelemetry span in a masking batch.
68
69    Use this object as the key when returning a patch for a span. It is a
70    frozen, hashable dataclass, so the safest pattern is to reuse the exact
71    identifier object from `MaskOtelSpansParams.spans` instead of rebuilding it.
72
73    Attributes:
74        trace_id: Lowercase 32-character hexadecimal OpenTelemetry trace ID.
75        span_id: Lowercase 16-character hexadecimal OpenTelemetry span ID.
76    """
77
78    trace_id: str
79    span_id: str

Stable key for one OpenTelemetry span in a masking batch.

Use this object as the key when returning a patch for a span. It is a frozen, hashable dataclass, so the safest pattern is to reuse the exact identifier object from MaskOtelSpansParams.spans instead of rebuilding it.

Attributes:
  • trace_id: Lowercase 32-character hexadecimal OpenTelemetry trace ID.
  • span_id: Lowercase 16-character hexadecimal OpenTelemetry span ID.
OtelSpanIdentifier(trace_id: str, span_id: str)
trace_id: str
span_id: str
@dataclass(frozen=True)
class OtelSpanPatch: 
165@dataclass(frozen=True)
166class OtelSpanPatch:
167    """Attribute changes to apply to one OpenTelemetry span before export.
168
169    Patches are sparse: include only the attributes that should change. Langfuse
170    deletes `delete_attributes` first and then applies `set_attributes`, so a key
171    present in both fields is exported with the value from `set_attributes`.
172
173    Attribute values must be valid OpenTelemetry attributes: strings, booleans,
174    integers, floats, or homogeneous sequences of those scalar types. If one
175    value is not valid for OpenTelemetry, Langfuse removes that attribute from
176    the export rather than sending an invalid span.
177
178    Example:
179        ```python
180        OtelSpanPatch(
181            delete_attributes=("gen_ai.prompt.0.content",),
182            set_attributes={
183                "gen_ai.prompt.redacted": True,
184                "app.masking.rule": "drop_prompt_text",
185            },
186        )
187        ```
188
189    Attributes:
190        set_attributes: Attribute values to add or replace on the exported span.
191        delete_attributes: Attribute keys to remove from the exported span.
192    """
193
194    set_attributes: Mapping[str, AttributeValue] = field(
195        default_factory=lambda: MappingProxyType({})
196    )
197    delete_attributes: Sequence[str] = field(default_factory=tuple)

Attribute changes to apply to one OpenTelemetry span before export.

Patches are sparse: include only the attributes that should change. Langfuse deletes delete_attributes first and then applies set_attributes, so a key present in both fields is exported with the value from set_attributes.

Attribute values must be valid OpenTelemetry attributes: strings, booleans, integers, floats, or homogeneous sequences of those scalar types. If one value is not valid for OpenTelemetry, Langfuse removes that attribute from the export rather than sending an invalid span.

Example:
OtelSpanPatch(
    delete_attributes=("gen_ai.prompt.0.content",),
    set_attributes={
        "gen_ai.prompt.redacted": True,
        "app.masking.rule": "drop_prompt_text",
    },
)
Attributes:
  • set_attributes: Attribute values to add or replace on the exported span.
  • delete_attributes: Attribute keys to remove from the exported span.
OtelSpanPatch( set_attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]] = <factory>, delete_attributes: Sequence[str] = <factory>)
set_attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]]
delete_attributes: Sequence[str]