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

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]]: 
 992    def start_as_current_observation(
 993        self,
 994        *,
 995        trace_context: Optional[TraceContext] = None,
 996        name: str,
 997        as_type: ObservationTypeLiteralNoEvent = "span",
 998        input: Optional[Any] = None,
 999        output: Optional[Any] = None,
1000        metadata: Optional[Any] = None,
1001        version: Optional[str] = None,
1002        level: Optional[SpanLevel] = None,
1003        status_message: Optional[str] = None,
1004        completion_start_time: Optional[datetime] = None,
1005        model: Optional[str] = None,
1006        model_parameters: Optional[Dict[str, MapValue]] = None,
1007        usage_details: Optional[Dict[str, int]] = None,
1008        cost_details: Optional[Dict[str, float]] = None,
1009        prompt: Optional[PromptClient] = None,
1010        end_on_exit: Optional[bool] = None,
1011    ) -> Union[
1012        _AgnosticContextManager[LangfuseGeneration],
1013        _AgnosticContextManager[LangfuseSpan],
1014        _AgnosticContextManager[LangfuseAgent],
1015        _AgnosticContextManager[LangfuseTool],
1016        _AgnosticContextManager[LangfuseChain],
1017        _AgnosticContextManager[LangfuseRetriever],
1018        _AgnosticContextManager[LangfuseEvaluator],
1019        _AgnosticContextManager[LangfuseEmbedding],
1020        _AgnosticContextManager[LangfuseGuardrail],
1021    ]:
1022        """Create a new observation and set it as the current span in a context manager.
1023
1024        This method creates a new observation of the specified type and sets it as the
1025        current span within a context manager. Use this method with a 'with' statement to
1026        automatically handle the observation lifecycle within a code block.
1027
1028        The created observation will be the child of the current span in the context.
1029
1030        Args:
1031            trace_context: Optional context for connecting to an existing trace
1032            name: Name of the observation (e.g., function or operation name)
1033            as_type: Type of observation to create (defaults to "span")
1034            input: Input data for the operation (can be any JSON-serializable object)
1035            output: Output data from the operation (can be any JSON-serializable object)
1036            metadata: Additional metadata to associate with the observation
1037            version: Version identifier for the code or component
1038            level: Importance level of the observation (info, warning, error)
1039            status_message: Optional status message for the observation
1040            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.
1041
1042            The following parameters are available when as_type is: "generation" or "embedding".
1043            completion_start_time: When the model started generating the response
1044            model: Name/identifier of the AI model used (e.g., "gpt-4")
1045            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1046            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1047            cost_details: Cost information for the model call
1048            prompt: Associated prompt template from Langfuse prompt management
1049
1050        Returns:
1051            A context manager that yields the appropriate observation type based on as_type
1052
1053        Example:
1054            ```python
1055            # Create a span
1056            with langfuse.start_as_current_observation(name="process-query", as_type="span") as span:
1057                # Do work
1058                result = process_data()
1059                span.update(output=result)
1060
1061                # Create a child span automatically
1062                with span.start_as_current_observation(name="sub-operation") as child_span:
1063                    # Do sub-operation work
1064                    child_span.update(output="sub-result")
1065
1066            # Create a tool observation
1067            with langfuse.start_as_current_observation(name="web-search", as_type="tool") as tool:
1068                # Do tool work
1069                results = search_web(query)
1070                tool.update(output=results)
1071
1072            # Create a generation observation
1073            with langfuse.start_as_current_observation(
1074                name="answer-generation",
1075                as_type="generation",
1076                model="gpt-4"
1077            ) as generation:
1078                # Generate answer
1079                response = llm.generate(...)
1080                generation.update(output=response)
1081            ```
1082        """
1083        if as_type in get_observation_types_list(ObservationTypeGenerationLike):
1084            if trace_context:
1085                trace_id = trace_context.get("trace_id", None)
1086                parent_span_id = trace_context.get("parent_span_id", None)
1087
1088                if trace_id:
1089                    remote_parent_span = self._create_remote_parent_span(
1090                        trace_id=trace_id, parent_span_id=parent_span_id
1091                    )
1092
1093                    return cast(
1094                        Union[
1095                            _AgnosticContextManager[LangfuseGeneration],
1096                            _AgnosticContextManager[LangfuseEmbedding],
1097                        ],
1098                        self._create_span_with_parent_context(
1099                            as_type=as_type,
1100                            name=name,
1101                            remote_parent_span=remote_parent_span,
1102                            parent=None,
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            return cast(
1120                Union[
1121                    _AgnosticContextManager[LangfuseGeneration],
1122                    _AgnosticContextManager[LangfuseEmbedding],
1123                ],
1124                self._start_as_current_otel_span_with_processed_media(
1125                    as_type=as_type,
1126                    name=name,
1127                    end_on_exit=end_on_exit,
1128                    input=input,
1129                    output=output,
1130                    metadata=metadata,
1131                    version=version,
1132                    level=level,
1133                    status_message=status_message,
1134                    completion_start_time=completion_start_time,
1135                    model=model,
1136                    model_parameters=model_parameters,
1137                    usage_details=usage_details,
1138                    cost_details=cost_details,
1139                    prompt=prompt,
1140                ),
1141            )
1142
1143        if as_type in get_observation_types_list(ObservationTypeSpanLike):
1144            if trace_context:
1145                trace_id = trace_context.get("trace_id", None)
1146                parent_span_id = trace_context.get("parent_span_id", None)
1147
1148                if trace_id:
1149                    remote_parent_span = self._create_remote_parent_span(
1150                        trace_id=trace_id, parent_span_id=parent_span_id
1151                    )
1152
1153                    return cast(
1154                        Union[
1155                            _AgnosticContextManager[LangfuseSpan],
1156                            _AgnosticContextManager[LangfuseAgent],
1157                            _AgnosticContextManager[LangfuseTool],
1158                            _AgnosticContextManager[LangfuseChain],
1159                            _AgnosticContextManager[LangfuseRetriever],
1160                            _AgnosticContextManager[LangfuseEvaluator],
1161                            _AgnosticContextManager[LangfuseGuardrail],
1162                        ],
1163                        self._create_span_with_parent_context(
1164                            as_type=as_type,
1165                            name=name,
1166                            remote_parent_span=remote_parent_span,
1167                            parent=None,
1168                            end_on_exit=end_on_exit,
1169                            input=input,
1170                            output=output,
1171                            metadata=metadata,
1172                            version=version,
1173                            level=level,
1174                            status_message=status_message,
1175                        ),
1176                    )
1177
1178            return cast(
1179                Union[
1180                    _AgnosticContextManager[LangfuseSpan],
1181                    _AgnosticContextManager[LangfuseAgent],
1182                    _AgnosticContextManager[LangfuseTool],
1183                    _AgnosticContextManager[LangfuseChain],
1184                    _AgnosticContextManager[LangfuseRetriever],
1185                    _AgnosticContextManager[LangfuseEvaluator],
1186                    _AgnosticContextManager[LangfuseGuardrail],
1187                ],
1188                self._start_as_current_otel_span_with_processed_media(
1189                    as_type=as_type,
1190                    name=name,
1191                    end_on_exit=end_on_exit,
1192                    input=input,
1193                    output=output,
1194                    metadata=metadata,
1195                    version=version,
1196                    level=level,
1197                    status_message=status_message,
1198                ),
1199            )
1200
1201        # This should never be reached since all valid types are handled above
1202        langfuse_logger.warning(
1203            f"Unknown observation type: {as_type}, falling back to span"
1204        )
1205        return self._start_as_current_otel_span_with_processed_media(
1206            as_type="span",
1207            name=name,
1208            end_on_exit=end_on_exit,
1209            input=input,
1210            output=output,
1211            metadata=metadata,
1212            version=version,
1213            level=level,
1214            status_message=status_message,
1215        )

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: 
1407    def update_current_generation(
1408        self,
1409        *,
1410        name: Optional[str] = None,
1411        input: Optional[Any] = None,
1412        output: Optional[Any] = None,
1413        metadata: Optional[Any] = None,
1414        version: Optional[str] = None,
1415        level: Optional[SpanLevel] = None,
1416        status_message: Optional[str] = None,
1417        completion_start_time: Optional[datetime] = None,
1418        model: Optional[str] = None,
1419        model_parameters: Optional[Dict[str, MapValue]] = None,
1420        usage_details: Optional[Dict[str, int]] = None,
1421        cost_details: Optional[Dict[str, float]] = None,
1422        prompt: Optional[PromptClient] = None,
1423    ) -> None:
1424        """Update the current active generation span with new information.
1425
1426        This method updates the current generation span in the active context with
1427        additional information. It's useful for adding output, usage stats, or other
1428        details that become available during or after model generation.
1429
1430        Args:
1431            name: The generation name
1432            input: Updated input data for the model
1433            output: Output from the model (e.g., completions)
1434            metadata: Additional metadata to associate with the generation
1435            version: Version identifier for the model or component
1436            level: Importance level of the generation (info, warning, error)
1437            status_message: Optional status message for the generation
1438            completion_start_time: When the model started generating the response
1439            model: Name/identifier of the AI model used (e.g., "gpt-4")
1440            model_parameters: Parameters used for the model (e.g., temperature, max_tokens)
1441            usage_details: Token usage information (e.g., prompt_tokens, completion_tokens)
1442            cost_details: Cost information for the model call
1443            prompt: Associated prompt template from Langfuse prompt management
1444
1445        Example:
1446            ```python
1447            with langfuse.start_as_current_generation(name="answer-query") as generation:
1448                # Initial setup and API call
1449                response = llm.generate(...)
1450
1451                # Update with results that weren't available at creation time
1452                langfuse.update_current_generation(
1453                    output=response.text,
1454                    usage_details={
1455                        "prompt_tokens": response.usage.prompt_tokens,
1456                        "completion_tokens": response.usage.completion_tokens
1457                    }
1458                )
1459            ```
1460        """
1461        if not self._tracing_enabled:
1462            langfuse_logger.debug(
1463                "Operation skipped: update_current_generation - Tracing is disabled or client is in no-op mode."
1464            )
1465            return
1466
1467        current_otel_span = self._get_current_otel_span()
1468
1469        if current_otel_span is not None:
1470            generation = LangfuseGeneration(
1471                otel_span=current_otel_span, langfuse_client=self
1472            )
1473
1474            if name:
1475                current_otel_span.update_name(name)
1476
1477            generation.update(
1478                input=input,
1479                output=output,
1480                metadata=metadata,
1481                version=version,
1482                level=level,
1483                status_message=status_message,
1484                completion_start_time=completion_start_time,
1485                model=model,
1486                model_parameters=model_parameters,
1487                usage_details=usage_details,
1488                cost_details=cost_details,
1489                prompt=prompt,
1490            )

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: 
1492    def update_current_span(
1493        self,
1494        *,
1495        name: Optional[str] = None,
1496        input: Optional[Any] = None,
1497        output: Optional[Any] = None,
1498        metadata: Optional[Any] = None,
1499        version: Optional[str] = None,
1500        level: Optional[SpanLevel] = None,
1501        status_message: Optional[str] = None,
1502    ) -> None:
1503        """Update the current active span with new information.
1504
1505        This method updates the current span in the active context with
1506        additional information. It's useful for adding outputs or metadata
1507        that become available during execution.
1508
1509        Args:
1510            name: The span name
1511            input: Updated input data for the operation
1512            output: Output data from the operation
1513            metadata: Additional metadata to associate with the span
1514            version: Version identifier for the code or component
1515            level: Importance level of the span (info, warning, error)
1516            status_message: Optional status message for the span
1517
1518        Example:
1519            ```python
1520            with langfuse.start_as_current_observation(name="process-data") as span:
1521                # Initial processing
1522                result = process_first_part()
1523
1524                # Update with intermediate results
1525                langfuse.update_current_span(metadata={"intermediate_result": result})
1526
1527                # Continue processing
1528                final_result = process_second_part(result)
1529
1530                # Final update
1531                langfuse.update_current_span(output=final_result)
1532            ```
1533        """
1534        if not self._tracing_enabled:
1535            langfuse_logger.debug(
1536                "Operation skipped: update_current_span - Tracing is disabled or client is in no-op mode."
1537            )
1538            return
1539
1540        current_otel_span = self._get_current_otel_span()
1541
1542        if current_otel_span is not None:
1543            span_class = self._get_span_class(
1544                self._get_observation_type_from_otel_span(current_otel_span)
1545            )
1546            span = span_class(
1547                otel_span=current_otel_span,
1548                langfuse_client=self,
1549                environment=self._environment,
1550                release=self._release,
1551            )
1552
1553            if name:
1554                current_otel_span.update_name(name)
1555
1556            span.update(
1557                input=input,
1558                output=output,
1559                metadata=metadata,
1560                version=version,
1561                level=level,
1562                status_message=status_message,
1563            )

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: 
1565    @deprecated(
1566        "Trace-level input/output is deprecated. "
1567        "For trace attributes (user_id, session_id, tags, etc.), use propagate_attributes() instead. "
1568        "This method will be removed in a future major version."
1569    )
1570    def set_current_trace_io(
1571        self,
1572        *,
1573        input: Optional[Any] = None,
1574        output: Optional[Any] = None,
1575    ) -> None:
1576        """Set trace-level input and output for the current span's trace.
1577
1578        .. deprecated::
1579            This is a legacy method for backward compatibility with Langfuse platform
1580            features that still rely on trace-level input/output (e.g., legacy LLM-as-a-judge
1581            evaluators). It will be removed in a future major version.
1582
1583            For setting other trace attributes (user_id, session_id, metadata, tags, version),
1584            use :func:`langfuse.propagate_attributes` (top-level import) instead.
1585
1586        Args:
1587            input: Input data to associate with the trace.
1588            output: Output data to associate with the trace.
1589        """
1590        if not self._tracing_enabled:
1591            langfuse_logger.debug(
1592                "Operation skipped: set_current_trace_io - Tracing is disabled or client is in no-op mode."
1593            )
1594            return
1595
1596        current_otel_span = self._get_current_otel_span()
1597
1598        if current_otel_span is not None and current_otel_span.is_recording():
1599            span_class = self._get_span_class(
1600                self._get_observation_type_from_otel_span(current_otel_span)
1601            )
1602            span = span_class(
1603                otel_span=current_otel_span,
1604                langfuse_client=self,
1605                environment=self._environment,
1606                release=self._release,
1607            )
1608
1609            span.set_trace_io(
1610                input=input,
1611                output=output,
1612            )

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: 
1614    def set_current_trace_as_public(self) -> None:
1615        """Make the current trace publicly accessible via its URL.
1616
1617        When a trace is published, anyone with the trace link can view the full trace
1618        without needing to be logged in to Langfuse. This action cannot be undone
1619        programmatically - once published, the entire trace becomes public.
1620
1621        This is a convenience method that publishes the trace from the currently
1622        active span context. Use this when you want to make a trace public from
1623        within a traced function without needing direct access to the span object.
1624        """
1625        if not self._tracing_enabled:
1626            langfuse_logger.debug(
1627                "Operation skipped: set_current_trace_as_public - Tracing is disabled or client is in no-op mode."
1628            )
1629            return
1630
1631        current_otel_span = self._get_current_otel_span()
1632
1633        if current_otel_span is not None and current_otel_span.is_recording():
1634            span_class = self._get_span_class(
1635                self._get_observation_type_from_otel_span(current_otel_span)
1636            )
1637            span = span_class(
1638                otel_span=current_otel_span,
1639                langfuse_client=self,
1640                environment=self._environment,
1641            )
1642
1643            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: 
1645    def create_event(
1646        self,
1647        *,
1648        trace_context: Optional[TraceContext] = None,
1649        name: str,
1650        input: Optional[Any] = None,
1651        output: Optional[Any] = None,
1652        metadata: Optional[Any] = None,
1653        version: Optional[str] = None,
1654        level: Optional[SpanLevel] = None,
1655        status_message: Optional[str] = None,
1656    ) -> LangfuseEvent:
1657        """Create a new Langfuse observation of type 'EVENT'.
1658
1659        The created Langfuse Event observation will be the child of the current span in the context.
1660
1661        Args:
1662            trace_context: Optional context for connecting to an existing trace
1663            name: Name of the span (e.g., function or operation name)
1664            input: Input data for the operation (can be any JSON-serializable object)
1665            output: Output data from the operation (can be any JSON-serializable object)
1666            metadata: Additional metadata to associate with the span
1667            version: Version identifier for the code or component
1668            level: Importance level of the span (info, warning, error)
1669            status_message: Optional status message for the span
1670
1671        Returns:
1672            The Langfuse Event object
1673
1674        Example:
1675            ```python
1676            event = langfuse.create_event(name="process-event")
1677            ```
1678        """
1679        timestamp = time_ns()
1680
1681        if trace_context:
1682            trace_id = trace_context.get("trace_id", None)
1683            parent_span_id = trace_context.get("parent_span_id", None)
1684
1685            if trace_id:
1686                remote_parent_span = self._create_remote_parent_span(
1687                    trace_id=trace_id, parent_span_id=parent_span_id
1688                )
1689
1690                with otel_trace_api.use_span(
1691                    cast(otel_trace_api.Span, remote_parent_span)
1692                ):
1693                    otel_span = self._otel_tracer.start_span(
1694                        name=name, start_time=timestamp
1695                    )
1696                    otel_span.set_attribute(LangfuseOtelSpanAttributes.AS_ROOT, True)
1697
1698                    return cast(
1699                        LangfuseEvent,
1700                        LangfuseEvent(
1701                            otel_span=otel_span,
1702                            langfuse_client=self,
1703                            environment=self._environment,
1704                            release=self._release,
1705                            input=input,
1706                            output=output,
1707                            metadata=metadata,
1708                            version=version,
1709                            level=level,
1710                            status_message=status_message,
1711                        ).end(end_time=timestamp),
1712                    )
1713
1714        otel_span = self._otel_tracer.start_span(name=name, start_time=timestamp)
1715
1716        return cast(
1717            LangfuseEvent,
1718            LangfuseEvent(
1719                otel_span=otel_span,
1720                langfuse_client=self,
1721                environment=self._environment,
1722                release=self._release,
1723                input=input,
1724                output=output,
1725                metadata=metadata,
1726                version=version,
1727                level=level,
1728                status_message=status_message,
1729            ).end(end_time=timestamp),
1730        )

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: 
1819    @staticmethod
1820    def create_trace_id(*, seed: Optional[str] = None) -> str:
1821        """Create a unique trace ID for use with Langfuse.
1822
1823        This method generates a unique trace ID for use with various Langfuse APIs.
1824        It can either generate a random ID or create a deterministic ID based on
1825        a seed string.
1826
1827        Trace IDs must be 32 lowercase hexadecimal characters, representing 16 bytes.
1828        This method ensures the generated ID meets this requirement. If you need to
1829        correlate an external ID with a Langfuse trace ID, use the external ID as the
1830        seed to get a valid, deterministic Langfuse trace ID.
1831
1832        Args:
1833            seed: Optional string to use as a seed for deterministic ID generation.
1834                 If provided, the same seed will always produce the same ID.
1835                 If not provided, a random ID will be generated.
1836
1837        Returns:
1838            A 32-character lowercase hexadecimal string representing the Langfuse trace ID.
1839
1840        Example:
1841            ```python
1842            # Generate a random trace ID
1843            trace_id = langfuse.create_trace_id()
1844
1845            # Generate a deterministic ID based on a seed
1846            session_trace_id = langfuse.create_trace_id(seed="session-456")
1847
1848            # Correlate an external ID with a Langfuse trace ID
1849            external_id = "external-system-123456"
1850            correlated_trace_id = langfuse.create_trace_id(seed=external_id)
1851
1852            # Use the ID with trace context
1853            with langfuse.start_as_current_observation(
1854                name="process-request",
1855                trace_context={"trace_id": trace_id}
1856            ) as span:
1857                # Operation will be part of the specific trace
1858                pass
1859            ```
1860        """
1861        if not seed:
1862            trace_id_int = RandomIdGenerator().generate_trace_id()
1863
1864            return Langfuse._format_otel_trace_id(trace_id_int)
1865
1866        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: 
1948    def create_score(
1949        self,
1950        *,
1951        name: str,
1952        value: Union[float, str],
1953        session_id: Optional[str] = None,
1954        dataset_run_id: Optional[str] = None,
1955        trace_id: Optional[str] = None,
1956        observation_id: Optional[str] = None,
1957        score_id: Optional[str] = None,
1958        data_type: Optional[ScoreDataType] = None,
1959        comment: Optional[str] = None,
1960        config_id: Optional[str] = None,
1961        metadata: Optional[Any] = None,
1962        timestamp: Optional[datetime] = None,
1963        environment: Optional[str] = None,
1964    ) -> None:
1965        """Create a score for a specific trace or observation.
1966
1967        This method creates a score for evaluating a Langfuse trace or observation. Scores can be
1968        used to track quality metrics, user feedback, or automated evaluations.
1969
1970        Args:
1971            name: Name of the score (e.g., "relevance", "accuracy")
1972            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
1973            session_id: ID of the Langfuse session to associate the score with
1974            dataset_run_id: ID of the Langfuse dataset run to associate the score with
1975            trace_id: ID of the Langfuse trace to associate the score with
1976            observation_id: Optional ID of the specific observation to score. Trace ID must be provided too.
1977            score_id: Optional custom ID for the score (auto-generated if not provided)
1978            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
1979            comment: Optional comment or explanation for the score
1980            config_id: Optional ID of a score config defined in Langfuse
1981            metadata: Optional metadata to be attached to the score
1982            timestamp: Optional timestamp for the score (defaults to current UTC time)
1983            environment: Optional environment override for this score. If omitted,
1984                the score uses the client-level environment from
1985                `Langfuse(environment=...)` or `LANGFUSE_TRACING_ENVIRONMENT`.
1986                Langfuse observation wrapper methods pass their resolved span
1987                environment here so scores created via `span.score()` or
1988                `span.score_trace()` stay grouped with the scored observation or
1989                trace, including request-scoped environments propagated with
1990                `propagate_attributes(environment=...)`.
1991
1992        Example:
1993            ```python
1994            # Create a numeric score for accuracy
1995            langfuse.create_score(
1996                name="accuracy",
1997                value=0.92,
1998                trace_id="abcdef1234567890abcdef1234567890",
1999                data_type="NUMERIC",
2000                comment="High accuracy with minor irrelevant details"
2001            )
2002
2003            # Create a categorical score for sentiment
2004            langfuse.create_score(
2005                name="sentiment",
2006                value="positive",
2007                trace_id="abcdef1234567890abcdef1234567890",
2008                observation_id="abcdef1234567890",
2009                data_type="CATEGORICAL"
2010            )
2011            ```
2012        """
2013        if not self._tracing_enabled:
2014            return
2015
2016        score_id = score_id or self._create_observation_id()
2017
2018        try:
2019            new_body = ScoreBody(
2020                id=score_id,
2021                sessionId=session_id,
2022                datasetRunId=dataset_run_id,
2023                traceId=trace_id,
2024                observationId=observation_id,
2025                name=name,
2026                value=value,
2027                dataType=data_type,  # type: ignore
2028                comment=comment,
2029                configId=config_id,
2030                environment=environment or self._environment,
2031                metadata=metadata,
2032            )
2033
2034            event = {
2035                "id": self.create_trace_id(),
2036                "type": "score-create",
2037                "timestamp": timestamp or _get_timestamp(),
2038                "body": new_body,
2039            }
2040
2041            if self._resources is not None:
2042                # Force the score to be in sample if it was for a legacy trace ID, i.e. non-32 hexchar
2043                force_sample = (
2044                    not self._is_valid_trace_id(trace_id) if trace_id else True
2045                )
2046
2047                self._resources.add_score_task(
2048                    event,
2049                    force_sample=force_sample,
2050                )
2051
2052        except Exception as e:
2053            langfuse_logger.exception(
2054                f"Error creating score: Failed to process score event for trace_id={trace_id}, name={name}. Error: {e}"
2055            )

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: 
2118    def score_current_span(
2119        self,
2120        *,
2121        name: str,
2122        value: Union[float, str],
2123        score_id: Optional[str] = None,
2124        data_type: Optional[ScoreDataType] = None,
2125        comment: Optional[str] = None,
2126        config_id: Optional[str] = None,
2127        metadata: Optional[Any] = None,
2128    ) -> None:
2129        """Create a score for the current active span.
2130
2131        This method scores the currently active span in the context. It's a convenient
2132        way to score the current operation without needing to know its trace and span IDs.
2133        If the active span has a `langfuse.environment` attribute, including one
2134        set by `propagate_attributes(environment=...)`, the score uses that
2135        environment. Otherwise it uses the client-level environment.
2136
2137        Args:
2138            name: Name of the score (e.g., "relevance", "accuracy")
2139            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
2140            score_id: Optional custom ID for the score (auto-generated if not provided)
2141            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
2142            comment: Optional comment or explanation for the score
2143            config_id: Optional ID of a score config defined in Langfuse
2144            metadata: Optional metadata to be attached to the score
2145
2146        Example:
2147            ```python
2148            with langfuse.start_as_current_generation(name="answer-query") as generation:
2149                # Generate answer
2150                response = generate_answer(...)
2151                generation.update(output=response)
2152
2153                # Score the generation
2154                langfuse.score_current_span(
2155                    name="relevance",
2156                    value=0.85,
2157                    data_type="NUMERIC",
2158                    comment="Mostly relevant but contains some tangential information",
2159                    metadata={"model": "gpt-4", "prompt_version": "v2"}
2160                )
2161            ```
2162        """
2163        current_span = self._get_current_otel_span()
2164
2165        if current_span is not None:
2166            trace_id = self._get_otel_trace_id(current_span)
2167            observation_id = self._get_otel_span_id(current_span)
2168
2169            langfuse_logger.info(
2170                f"Score: Creating score name='{name}' value={value} for current span ({observation_id}) in trace {trace_id}"
2171            )
2172
2173            self.create_score(
2174                trace_id=trace_id,
2175                observation_id=observation_id,
2176                name=name,
2177                value=cast(str, value),
2178                score_id=score_id,
2179                data_type=cast(Literal["CATEGORICAL", "TEXT", "CORRECTION"], data_type),
2180                comment=comment,
2181                config_id=config_id,
2182                metadata=metadata,
2183                environment=get_string_span_attribute(
2184                    current_span, LangfuseOtelSpanAttributes.ENVIRONMENT
2185                ),
2186            )

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: 
2216    def score_current_trace(
2217        self,
2218        *,
2219        name: str,
2220        value: Union[float, str],
2221        score_id: Optional[str] = None,
2222        data_type: Optional[ScoreDataType] = None,
2223        comment: Optional[str] = None,
2224        config_id: Optional[str] = None,
2225        metadata: Optional[Any] = None,
2226    ) -> None:
2227        """Create a score for the current trace.
2228
2229        This method scores the trace of the currently active span. Unlike score_current_span,
2230        this method associates the score with the entire trace rather than a specific span.
2231        It's useful for scoring overall performance or quality of the entire operation.
2232        If the active span has a `langfuse.environment` attribute, including one
2233        set by `propagate_attributes(environment=...)`, the score uses that
2234        environment. Otherwise it uses the client-level environment.
2235
2236        Args:
2237            name: Name of the score (e.g., "user_satisfaction", "overall_quality")
2238            value: Score value (can be numeric for NUMERIC/BOOLEAN types or string for CATEGORICAL/TEXT/CORRECTION)
2239            score_id: Optional custom ID for the score (auto-generated if not provided)
2240            data_type: Type of score (NUMERIC, BOOLEAN, CATEGORICAL, TEXT, or CORRECTION)
2241            comment: Optional comment or explanation for the score
2242            config_id: Optional ID of a score config defined in Langfuse
2243            metadata: Optional metadata to be attached to the score
2244
2245        Example:
2246            ```python
2247            with langfuse.start_as_current_observation(name="process-user-request") as span:
2248                # Process request
2249                result = process_complete_request()
2250                span.update(output=result)
2251
2252                # Score the overall trace
2253                langfuse.score_current_trace(
2254                    name="overall_quality",
2255                    value=0.95,
2256                    data_type="NUMERIC",
2257                    comment="High quality end-to-end response",
2258                    metadata={"evaluator": "gpt-4", "criteria": "comprehensive"}
2259                )
2260            ```
2261        """
2262        current_span = self._get_current_otel_span()
2263
2264        if current_span is not None:
2265            trace_id = self._get_otel_trace_id(current_span)
2266
2267            langfuse_logger.info(
2268                f"Score: Creating score name='{name}' value={value} for entire trace {trace_id}"
2269            )
2270
2271            self.create_score(
2272                trace_id=trace_id,
2273                name=name,
2274                value=cast(str, value),
2275                score_id=score_id,
2276                data_type=cast(Literal["CATEGORICAL", "TEXT", "CORRECTION"], data_type),
2277                comment=comment,
2278                config_id=config_id,
2279                metadata=metadata,
2280                environment=get_string_span_attribute(
2281                    current_span, LangfuseOtelSpanAttributes.ENVIRONMENT
2282                ),
2283            )

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: 
2285    def flush(self) -> None:
2286        """Force flush all pending spans and events to the Langfuse API.
2287
2288        This method manually flushes any pending spans, scores, and other events to the
2289        Langfuse API. It's useful in scenarios where you want to ensure all data is sent
2290        before proceeding, without waiting for the automatic flush interval.
2291
2292        Example:
2293            ```python
2294            # Record some spans and scores
2295            with langfuse.start_as_current_observation(name="operation") as span:
2296                # Do work...
2297                pass
2298
2299            # Ensure all data is sent to Langfuse before proceeding
2300            langfuse.flush()
2301
2302            # Continue with other work
2303            ```
2304
2305        Note:
2306            `flush()` guarantees data was *delivered* to the API, not that it is
2307            *readable* yet: server-side ingestion is asynchronous, so flushed data
2308            may not be queryable for 15-30 seconds —
2309            `api.observations.get_many(trace_id=...)` may return empty results and
2310            `api.trace.get()` may raise `langfuse.api.NotFoundError` right after a
2311            successful flush. See the `api` property docs for a bounded retry
2312            pattern, or
2313            https://langfuse.com/docs/api-and-data-platform/features/query-via-sdk#ingestion-lag
2314        """
2315        if self._resources is not None:
2316            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: 
2318    def shutdown(self) -> None:
2319        """Shut down the Langfuse client and flush all pending data.
2320
2321        This method cleanly shuts down the Langfuse client, ensuring all pending data
2322        is flushed to the API and all background threads are properly terminated.
2323
2324        It's important to call this method when your application is shutting down to
2325        prevent data loss and resource leaks. For most applications, using the client
2326        as a context manager or relying on the automatic shutdown via atexit is sufficient.
2327
2328        Example:
2329            ```python
2330            # Initialize Langfuse
2331            langfuse = Langfuse(public_key="...", secret_key="...")
2332
2333            # Use Langfuse throughout your application
2334            # ...
2335
2336            # When application is shutting down
2337            langfuse.shutdown()
2338            ```
2339        """
2340        if self._resources is not None:
2341            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]: 
2343    def get_current_trace_id(self) -> Optional[str]:
2344        """Get the trace ID of the current active span.
2345
2346        This method retrieves the trace ID from the currently active span in the context.
2347        It can be used to get the trace ID for referencing in logs, external systems,
2348        or for creating related operations.
2349
2350        Returns:
2351            The current trace ID as a 32-character lowercase hexadecimal string,
2352            or None if there is no active span.
2353
2354        Example:
2355            ```python
2356            with langfuse.start_as_current_observation(name="process-request") as span:
2357                # Get the current trace ID for reference
2358                trace_id = langfuse.get_current_trace_id()
2359
2360                # Use it for external correlation
2361                log.info(f"Processing request with trace_id: {trace_id}")
2362
2363                # Or pass to another system
2364                external_system.process(data, trace_id=trace_id)
2365            ```
2366        """
2367        if not self._tracing_enabled:
2368            langfuse_logger.debug(
2369                "Operation skipped: get_current_trace_id - Tracing is disabled or client is in no-op mode."
2370            )
2371            return None
2372
2373        current_otel_span = self._get_current_otel_span()
2374
2375        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]: 
2377    def get_current_observation_id(self) -> Optional[str]:
2378        """Get the observation ID (span ID) of the current active span.
2379
2380        This method retrieves the observation ID from the currently active span in the context.
2381        It can be used to get the observation ID for referencing in logs, external systems,
2382        or for creating scores or other related operations.
2383
2384        Returns:
2385            The current observation ID as a 16-character lowercase hexadecimal string,
2386            or None if there is no active span.
2387
2388        Example:
2389            ```python
2390            with langfuse.start_as_current_observation(name="process-user-query") as span:
2391                # Get the current observation ID
2392                observation_id = langfuse.get_current_observation_id()
2393
2394                # Store it for later reference
2395                cache.set(f"query_{query_id}_observation", observation_id)
2396
2397                # Process the query...
2398            ```
2399        """
2400        if not self._tracing_enabled:
2401            langfuse_logger.debug(
2402                "Operation skipped: get_current_observation_id - Tracing is disabled or client is in no-op mode."
2403            )
2404            return None
2405
2406        current_otel_span = self._get_current_otel_span()
2407
2408        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]: 
2421    def get_trace_url(self, *, trace_id: Optional[str] = None) -> Optional[str]:
2422        """Get the URL to view a trace in the Langfuse UI.
2423
2424        This method generates a URL that links directly to a trace in the Langfuse UI.
2425        It's useful for providing links in logs, notifications, or debugging tools.
2426
2427        Args:
2428            trace_id: Optional trace ID to generate a URL for. If not provided,
2429                     the trace ID of the current active span will be used.
2430
2431        Returns:
2432            A URL string pointing to the trace in the Langfuse UI,
2433            or None if the project ID couldn't be retrieved or no trace ID is available.
2434
2435        Example:
2436            ```python
2437            # Get URL for the current trace
2438            with langfuse.start_as_current_observation(name="process-request") as span:
2439                trace_url = langfuse.get_trace_url()
2440                log.info(f"Processing trace: {trace_url}")
2441
2442            # Get URL for a specific trace
2443            specific_trace_url = langfuse.get_trace_url(trace_id="1234567890abcdef1234567890abcdef")
2444            send_notification(f"Review needed for trace: {specific_trace_url}")
2445            ```
2446        """
2447        final_trace_id = trace_id or self.get_current_trace_id()
2448        if not final_trace_id:
2449            return None
2450
2451        project_id = self._get_project_id()
2452
2453        return (
2454            f"{self._base_url}/project/{project_id}/traces/{final_trace_id}"
2455            if project_id and final_trace_id
2456            else None
2457        )

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: 
2459    def get_dataset(
2460        self,
2461        name: str,
2462        *,
2463        fetch_items_page_size: Optional[int] = 50,
2464        version: Optional[datetime] = None,
2465    ) -> "DatasetClient":
2466        """Fetch a dataset by its name.
2467
2468        Args:
2469            name: The name of the dataset to fetch.
2470            fetch_items_page_size: All items of the dataset will be fetched in chunks of this size. Defaults to 50.
2471            version: Retrieve dataset items as they existed at this specific point in time (UTC).
2472                If provided, returns the state of items at the specified UTC timestamp.
2473                If not provided, returns the latest version. Must be a timezone-aware datetime object in UTC.
2474
2475        Returns:
2476            DatasetClient: The dataset with the given name.
2477        """
2478        try:
2479            langfuse_logger.debug(f"Getting datasets {name}")
2480            dataset = self.api.datasets.get(dataset_name=self._url_encode(name))
2481
2482            dataset_items: List[DatasetItem] = []
2483            page = 1
2484
2485            while True:
2486                new_items = self.api.dataset_items.list(
2487                    dataset_name=self._url_encode(name, is_url_param=True),
2488                    page=page,
2489                    limit=fetch_items_page_size,
2490                    version=version,
2491                )
2492                dataset_items.extend(
2493                    self._hydrate_dataset_item_media_references(item)
2494                    for item in new_items.data
2495                )
2496
2497                if new_items.meta.total_pages <= page:
2498                    break
2499
2500                page += 1
2501
2502            return DatasetClient(
2503                dataset=dataset,
2504                items=dataset_items,
2505                version=version,
2506                langfuse_client=self,
2507            )
2508
2509        except Error as e:
2510            handle_fern_exception(e)
2511            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: 
2513    def get_dataset_run(
2514        self, *, dataset_name: str, run_name: str
2515    ) -> DatasetRunWithItems:
2516        """Fetch a dataset run by dataset name and run name.
2517
2518        Args:
2519            dataset_name (str): The name of the dataset.
2520            run_name (str): The name of the run.
2521
2522        Returns:
2523            DatasetRunWithItems: The dataset run with its items.
2524        """
2525        try:
2526            return cast(
2527                DatasetRunWithItems,
2528                self.api.datasets.get_run(
2529                    dataset_name=self._url_encode(dataset_name),
2530                    run_name=self._url_encode(run_name),
2531                    request_options=None,
2532                ),
2533            )
2534        except Error as e:
2535            handle_fern_exception(e)
2536            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: 
2538    def get_dataset_runs(
2539        self,
2540        *,
2541        dataset_name: str,
2542        page: Optional[int] = None,
2543        limit: Optional[int] = None,
2544    ) -> PaginatedDatasetRuns:
2545        """Fetch all runs for a dataset.
2546
2547        Args:
2548            dataset_name (str): The name of the dataset.
2549            page (Optional[int]): Page number, starts at 1.
2550            limit (Optional[int]): Limit of items per page.
2551
2552        Returns:
2553            PaginatedDatasetRuns: Paginated list of dataset runs.
2554        """
2555        try:
2556            return cast(
2557                PaginatedDatasetRuns,
2558                self.api.datasets.get_runs(
2559                    dataset_name=self._url_encode(dataset_name),
2560                    page=page,
2561                    limit=limit,
2562                    request_options=None,
2563                ),
2564            )
2565        except Error as e:
2566            handle_fern_exception(e)
2567            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: 
2569    def delete_dataset_run(
2570        self, *, dataset_name: str, run_name: str
2571    ) -> DeleteDatasetRunResponse:
2572        """Delete a dataset run and all its run items. This action is irreversible.
2573
2574        Args:
2575            dataset_name (str): The name of the dataset.
2576            run_name (str): The name of the run.
2577
2578        Returns:
2579            DeleteDatasetRunResponse: Confirmation of deletion.
2580        """
2581        try:
2582            return cast(
2583                DeleteDatasetRunResponse,
2584                self.api.datasets.delete_run(
2585                    dataset_name=self._url_encode(dataset_name),
2586                    run_name=self._url_encode(run_name),
2587                    request_options=None,
2588                ),
2589            )
2590        except Error as e:
2591            handle_fern_exception(e)
2592            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: 
2594    def run_experiment(
2595        self,
2596        *,
2597        name: str,
2598        run_name: Optional[str] = None,
2599        description: Optional[str] = None,
2600        data: ExperimentData,
2601        task: TaskFunction,
2602        evaluators: List[EvaluatorFunction] = [],
2603        composite_evaluator: Optional[CompositeEvaluatorFunction] = None,
2604        run_evaluators: List[RunEvaluatorFunction] = [],
2605        max_concurrency: int = 50,
2606        metadata: Optional[Dict[str, str]] = None,
2607        _dataset_version: Optional[datetime] = None,
2608    ) -> ExperimentResult:
2609        """Run an experiment on a dataset with automatic tracing and evaluation.
2610
2611        This method executes a task function on each item in the provided dataset,
2612        automatically traces all executions with Langfuse for observability, runs
2613        item-level and run-level evaluators on the outputs, and returns comprehensive
2614        results with evaluation metrics.
2615
2616        The experiment system provides:
2617        - Automatic tracing of all task executions
2618        - Concurrent processing with configurable limits
2619        - Comprehensive error handling that isolates failures
2620        - Integration with Langfuse datasets for experiment tracking
2621        - Flexible evaluation framework supporting both sync and async evaluators
2622
2623        Args:
2624            name: Human-readable name for the experiment. Used for identification
2625                in the Langfuse UI.
2626            run_name: Optional exact name for the experiment run. If provided, this will be
2627                used as the exact dataset run name if the `data` contains Langfuse dataset items.
2628                If not provided, this will default to the experiment name appended with an ISO timestamp.
2629            description: Optional description explaining the experiment's purpose,
2630                methodology, or expected outcomes.
2631            data: Array of data items to process. Can be either:
2632                - List of dict-like items with 'input', 'expected_output', 'metadata' keys
2633                - List of Langfuse DatasetItem objects from dataset.items
2634            task: Function that processes each data item and returns output.
2635                Must accept 'item' as keyword argument and can return sync or async results.
2636                The task function signature should be: task(*, item, **kwargs) -> Any
2637            evaluators: List of functions to evaluate each item's output individually.
2638                Each evaluator receives input, output, expected_output, and metadata.
2639                Can return single Evaluation dict or list of Evaluation dicts.
2640            composite_evaluator: Optional function that creates composite scores from item-level evaluations.
2641                Receives the same inputs as item-level evaluators (input, output, expected_output, metadata)
2642                plus the list of evaluations from item-level evaluators. Useful for weighted averages,
2643                pass/fail decisions based on multiple criteria, or custom scoring logic combining multiple metrics.
2644            run_evaluators: List of functions to evaluate the entire experiment run.
2645                Each run evaluator receives all item_results and can compute aggregate metrics.
2646                Useful for calculating averages, distributions, or cross-item comparisons.
2647            max_concurrency: Maximum number of concurrent task executions (default: 50).
2648                Controls the number of items processed simultaneously. Adjust based on
2649                API rate limits and system resources.
2650            metadata: Optional metadata dictionary to attach to all experiment traces.
2651                This metadata will be included in every trace created during the experiment.
2652                If `data` are Langfuse dataset items, the metadata will be attached to the dataset run, too.
2653
2654        Returns:
2655            ExperimentResult containing:
2656            - run_name: The experiment run name. This is equal to the dataset run name if experiment was on Langfuse dataset.
2657            - item_results: List of results for each processed item with outputs and evaluations
2658            - run_evaluations: List of aggregate evaluation results for the entire run
2659            - experiment_id: Stable identifier for the experiment run across all items
2660            - dataset_run_id: ID of the dataset run (if using Langfuse datasets)
2661            - dataset_run_url: Direct URL to view results in Langfuse UI (if applicable)
2662
2663        Raises:
2664            ValueError: If required parameters are missing or invalid
2665            Exception: If experiment setup fails (individual item failures are handled gracefully)
2666
2667        Examples:
2668            Basic experiment with local data:
2669            ```python
2670            def summarize_text(*, item, **kwargs):
2671                return f"Summary: {item['input'][:50]}..."
2672
2673            def length_evaluator(*, input, output, expected_output=None, **kwargs):
2674                return {
2675                    "name": "output_length",
2676                    "value": len(output),
2677                    "comment": f"Output contains {len(output)} characters"
2678                }
2679
2680            result = langfuse.run_experiment(
2681                name="Text Summarization Test",
2682                description="Evaluate summarization quality and length",
2683                data=[
2684                    {"input": "Long article text...", "expected_output": "Expected summary"},
2685                    {"input": "Another article...", "expected_output": "Another summary"}
2686                ],
2687                task=summarize_text,
2688                evaluators=[length_evaluator]
2689            )
2690
2691            print(f"Processed {len(result.item_results)} items")
2692            for item_result in result.item_results:
2693                print(f"Input: {item_result.item['input']}")
2694                print(f"Output: {item_result.output}")
2695                print(f"Evaluations: {item_result.evaluations}")
2696            ```
2697
2698            Advanced experiment with async task and multiple evaluators:
2699            ```python
2700            async def llm_task(*, item, **kwargs):
2701                # Simulate async LLM call
2702                response = await openai_client.chat.completions.create(
2703                    model="gpt-4",
2704                    messages=[{"role": "user", "content": item["input"]}]
2705                )
2706                return response.choices[0].message.content
2707
2708            def accuracy_evaluator(*, input, output, expected_output=None, **kwargs):
2709                if expected_output and expected_output.lower() in output.lower():
2710                    return {"name": "accuracy", "value": 1.0, "comment": "Correct answer"}
2711                return {"name": "accuracy", "value": 0.0, "comment": "Incorrect answer"}
2712
2713            def toxicity_evaluator(*, input, output, expected_output=None, **kwargs):
2714                # Simulate toxicity check
2715                toxicity_score = check_toxicity(output)  # Your toxicity checker
2716                return {
2717                    "name": "toxicity",
2718                    "value": toxicity_score,
2719                    "comment": f"Toxicity level: {'high' if toxicity_score > 0.7 else 'low'}"
2720                }
2721
2722            def average_accuracy(*, item_results, **kwargs):
2723                accuracies = [
2724                    eval.value for result in item_results
2725                    for eval in result.evaluations
2726                    if eval.name == "accuracy"
2727                ]
2728                return {
2729                    "name": "average_accuracy",
2730                    "value": sum(accuracies) / len(accuracies) if accuracies else 0,
2731                    "comment": f"Average accuracy across {len(accuracies)} items"
2732                }
2733
2734            result = langfuse.run_experiment(
2735                name="LLM Safety and Accuracy Test",
2736                description="Evaluate model accuracy and safety across diverse prompts",
2737                data=test_dataset,  # Your dataset items
2738                task=llm_task,
2739                evaluators=[accuracy_evaluator, toxicity_evaluator],
2740                run_evaluators=[average_accuracy],
2741                max_concurrency=5,  # Limit concurrent API calls
2742                metadata={"model": "gpt-4", "temperature": 0.7}
2743            )
2744            ```
2745
2746            Using with Langfuse datasets:
2747            ```python
2748            # Get dataset from Langfuse
2749            dataset = langfuse.get_dataset("my-eval-dataset")
2750
2751            result = dataset.run_experiment(
2752                name="Production Model Evaluation",
2753                description="Monthly evaluation of production model performance",
2754                task=my_production_task,
2755                evaluators=[accuracy_evaluator, latency_evaluator]
2756            )
2757
2758            # Results automatically linked to dataset in Langfuse UI
2759            print(f"View results: {result['dataset_run_url']}")
2760            ```
2761
2762        Note:
2763            - Task and evaluator functions can be either synchronous or asynchronous
2764            - Individual item failures are logged but don't stop the experiment
2765            - All executions are automatically traced and visible in Langfuse UI
2766            - When using Langfuse datasets, results are automatically linked for easy comparison
2767            - This method works in both sync and async contexts (Jupyter notebooks, web apps, etc.)
2768            - Async execution is handled automatically with smart event loop detection
2769        """
2770        return cast(
2771            ExperimentResult,
2772            run_async_safely(
2773                self._run_experiment_async(
2774                    name=name,
2775                    run_name=self._create_experiment_run_name(
2776                        name=name, run_name=run_name
2777                    ),
2778                    description=description,
2779                    data=data,
2780                    task=task,
2781                    evaluators=evaluators or [],
2782                    composite_evaluator=composite_evaluator,
2783                    run_evaluators=run_evaluators or [],
2784                    max_concurrency=max_concurrency,
2785                    metadata=metadata,
2786                    dataset_version=_dataset_version,
2787                ),
2788            ),
2789        )

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: 
3239    def run_batched_evaluation(
3240        self,
3241        *,
3242        scope: Literal["traces", "observations"],
3243        mapper: MapperFunction,
3244        filter: Optional[str] = None,
3245        fetch_batch_size: int = 50,
3246        fetch_trace_fields: Optional[str] = None,
3247        max_items: Optional[int] = None,
3248        max_retries: int = 3,
3249        evaluators: List[EvaluatorFunction],
3250        composite_evaluator: Optional[CompositeEvaluatorFunction] = None,
3251        max_concurrency: int = 5,
3252        metadata: Optional[Dict[str, Any]] = None,
3253        _add_observation_scores_to_trace: bool = False,
3254        _additional_trace_tags: Optional[List[str]] = None,
3255        resume_from: Optional[BatchEvaluationResumeToken] = None,
3256        verbose: bool = False,
3257    ) -> BatchEvaluationResult:
3258        """Fetch traces or observations and run evaluations on each item.
3259
3260        This method provides a powerful way to evaluate existing data in Langfuse at scale.
3261        It fetches items based on filters, transforms them using a mapper function, runs
3262        evaluators on each item, and creates scores that are linked back to the original
3263        entities. This is ideal for:
3264
3265        - Running evaluations on production traces after deployment
3266        - Backtesting new evaluation metrics on historical data
3267        - Batch scoring of observations for quality monitoring
3268        - Periodic evaluation runs on recent data
3269
3270        The method uses a streaming/pipeline approach to process items in batches, making
3271        it memory-efficient for large datasets. It includes comprehensive error handling,
3272        retry logic, and resume capability for long-running evaluations.
3273
3274        Args:
3275            scope: The type of items to evaluate. Must be one of:
3276                - "traces": Evaluate complete traces with all their observations
3277                - "observations": Evaluate individual observations (spans, generations, events)
3278            mapper: Function that transforms API response objects into evaluator inputs.
3279                Receives a trace/observation object and returns an EvaluatorInputs
3280                instance with input, output, expected_output, and metadata fields.
3281                Can be sync or async.
3282            evaluators: List of evaluation functions to run on each item. Each evaluator
3283                receives the mapped inputs and returns Evaluation object(s). Evaluator
3284                failures are logged but don't stop the batch evaluation.
3285            filter: Optional JSON filter string for querying items (same format as Langfuse API). Examples:
3286                - '{"tags": ["production"]}'
3287                - '{"user_id": "user123", "timestamp": {"operator": ">", "value": "2024-01-01"}}'
3288                Default: None (fetches all items).
3289            fetch_batch_size: Number of items to fetch per API call and hold in memory.
3290                Larger values may be faster but use more memory. Default: 50.
3291            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'.
3292            max_items: Maximum total number of items to process. If None, processes all
3293                items matching the filter. Useful for testing or limiting evaluation runs.
3294                Default: None (process all).
3295            max_concurrency: Maximum number of items to evaluate concurrently. Controls
3296                parallelism and resource usage. Default: 5.
3297            composite_evaluator: Optional function that creates a composite score from
3298                item-level evaluations. Receives the original item and its evaluations,
3299                returns a single Evaluation. Useful for weighted averages or combined metrics.
3300                Default: None.
3301            metadata: Optional metadata dict to add to all created scores. Useful for
3302                tracking evaluation runs, versions, or other context. Default: None.
3303            max_retries: Maximum number of retry attempts for failed batch fetches.
3304                Uses exponential backoff (1s, 2s, 4s). Default: 3.
3305            verbose: If True, logs progress information to console. Useful for monitoring
3306                long-running evaluations. Default: False.
3307            resume_from: Optional resume token from a previous incomplete run. Allows
3308                continuing evaluation after interruption or failure. Default: None.
3309
3310
3311        Returns:
3312            BatchEvaluationResult containing:
3313                - total_items_fetched: Number of items fetched from API
3314                - total_items_processed: Number of items successfully evaluated
3315                - total_items_failed: Number of items that failed evaluation
3316                - total_scores_created: Scores created by item-level evaluators
3317                - total_composite_scores_created: Scores created by composite evaluator
3318                - total_evaluations_failed: Individual evaluator failures
3319                - evaluator_stats: Per-evaluator statistics (success rate, scores created)
3320                - resume_token: Token for resuming if incomplete (None if completed)
3321                - completed: True if all items processed
3322                - duration_seconds: Total execution time
3323                - failed_item_ids: IDs of items that failed
3324                - error_summary: Error types and counts
3325                - has_more_items: True if max_items reached but more exist
3326
3327        Raises:
3328            ValueError: If invalid scope is provided.
3329
3330        Examples:
3331            Basic trace evaluation:
3332            ```python
3333            from langfuse import Langfuse, EvaluatorInputs, Evaluation
3334
3335            client = Langfuse()
3336
3337            # Define mapper to extract fields from traces
3338            def trace_mapper(trace):
3339                return EvaluatorInputs(
3340                    input=trace.input,
3341                    output=trace.output,
3342                    expected_output=None,
3343                    metadata={"trace_id": trace.id}
3344                )
3345
3346            # Define evaluator
3347            def length_evaluator(*, input, output, expected_output, metadata):
3348                return Evaluation(
3349                    name="output_length",
3350                    value=len(output) if output else 0
3351                )
3352
3353            # Run batch evaluation
3354            result = client.run_batched_evaluation(
3355                scope="traces",
3356                mapper=trace_mapper,
3357                evaluators=[length_evaluator],
3358                filter='{"tags": ["production"]}',
3359                max_items=1000,
3360                verbose=True
3361            )
3362
3363            print(f"Processed {result.total_items_processed} traces")
3364            print(f"Created {result.total_scores_created} scores")
3365            ```
3366
3367            Evaluation with composite scorer:
3368            ```python
3369            def accuracy_evaluator(*, input, output, expected_output, metadata):
3370                # ... evaluation logic
3371                return Evaluation(name="accuracy", value=0.85)
3372
3373            def relevance_evaluator(*, input, output, expected_output, metadata):
3374                # ... evaluation logic
3375                return Evaluation(name="relevance", value=0.92)
3376
3377            def composite_evaluator(*, item, evaluations):
3378                # Weighted average of evaluations
3379                weights = {"accuracy": 0.6, "relevance": 0.4}
3380                total = sum(
3381                    e.value * weights.get(e.name, 0)
3382                    for e in evaluations
3383                    if isinstance(e.value, (int, float))
3384                )
3385                return Evaluation(
3386                    name="composite_score",
3387                    value=total,
3388                    comment=f"Weighted average of {len(evaluations)} metrics"
3389                )
3390
3391            result = client.run_batched_evaluation(
3392                scope="traces",
3393                mapper=trace_mapper,
3394                evaluators=[accuracy_evaluator, relevance_evaluator],
3395                composite_evaluator=composite_evaluator,
3396                filter='{"user_id": "important_user"}',
3397                verbose=True
3398            )
3399            ```
3400
3401            Handling incomplete runs with resume:
3402            ```python
3403            # Initial run that may fail or timeout
3404            result = client.run_batched_evaluation(
3405                scope="observations",
3406                mapper=obs_mapper,
3407                evaluators=[my_evaluator],
3408                max_items=10000,
3409                verbose=True
3410            )
3411
3412            # Check if incomplete
3413            if not result.completed and result.resume_token:
3414                print(f"Processed {result.resume_token.items_processed} items before interruption")
3415
3416                # Resume from where it left off
3417                result = client.run_batched_evaluation(
3418                    scope="observations",
3419                    mapper=obs_mapper,
3420                    evaluators=[my_evaluator],
3421                    resume_from=result.resume_token,
3422                    verbose=True
3423                )
3424
3425            print(f"Total items processed: {result.total_items_processed}")
3426            ```
3427
3428            Monitoring evaluator performance:
3429            ```python
3430            result = client.run_batched_evaluation(...)
3431
3432            for stats in result.evaluator_stats:
3433                success_rate = stats.successful_runs / stats.total_runs
3434                print(f"{stats.name}:")
3435                print(f"  Success rate: {success_rate:.1%}")
3436                print(f"  Scores created: {stats.total_scores_created}")
3437
3438                if stats.failed_runs > 0:
3439                    print(f"  ⚠️  Failed {stats.failed_runs} times")
3440            ```
3441
3442        Note:
3443            - Evaluator failures are logged but don't stop the batch evaluation
3444            - Individual item failures are tracked but don't stop processing
3445            - Fetch failures are retried with exponential backoff
3446            - All scores are automatically flushed to Langfuse at the end
3447            - The resume mechanism uses timestamp-based filtering to avoid duplicates
3448        """
3449        runner = BatchEvaluationRunner(self)
3450
3451        return cast(
3452            BatchEvaluationResult,
3453            run_async_safely(
3454                runner.run_async(
3455                    scope=scope,
3456                    mapper=mapper,
3457                    evaluators=evaluators,
3458                    filter=filter,
3459                    fetch_batch_size=fetch_batch_size,
3460                    fetch_trace_fields=fetch_trace_fields,
3461                    max_items=max_items,
3462                    max_concurrency=max_concurrency,
3463                    composite_evaluator=composite_evaluator,
3464                    metadata=metadata,
3465                    _add_observation_scores_to_trace=_add_observation_scores_to_trace,
3466                    _additional_trace_tags=_additional_trace_tags,
3467                    max_retries=max_retries,
3468                    verbose=verbose,
3469                    resume_from=resume_from,
3470                )
3471            ),
3472        )

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: 
3474    def auth_check(self) -> bool:
3475        """Check if the provided credentials (public and secret key) are valid.
3476
3477        Raises:
3478            Exception: If no projects were found for the provided credentials.
3479
3480        Note:
3481            This method is blocking. It is discouraged to use it in production code.
3482        """
3483        try:
3484            projects = self.api.projects.get()
3485            langfuse_logger.debug(
3486                f"Auth check successful, found {len(projects.data)} projects"
3487            )
3488            if len(projects.data) == 0:
3489                raise Exception(
3490                    "Auth check failed, no project found for the keys provided."
3491                )
3492            return True
3493
3494        except AttributeError as e:
3495            langfuse_logger.warning(
3496                f"Auth check failed: Client not properly initialized. Error: {e}"
3497            )
3498            return False
3499
3500        except Error as e:
3501            handle_fern_exception(e)
3502            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: 
3504    def create_dataset(
3505        self,
3506        *,
3507        name: str,
3508        description: Optional[str] = None,
3509        metadata: Optional[Any] = None,
3510        input_schema: Optional[Any] = None,
3511        expected_output_schema: Optional[Any] = None,
3512    ) -> Dataset:
3513        """Create a dataset with the given name on Langfuse.
3514
3515        Args:
3516            name: Name of the dataset to create.
3517            description: Description of the dataset. Defaults to None.
3518            metadata: Additional metadata. Defaults to None.
3519            input_schema: JSON Schema for validating dataset item inputs. When set, all new items will be validated against this schema.
3520            expected_output_schema: JSON Schema for validating dataset item expected outputs. When set, all new items will be validated against this schema.
3521
3522        Returns:
3523            Dataset: The created dataset as returned by the Langfuse API.
3524        """
3525        try:
3526            langfuse_logger.debug(f"Creating datasets {name}")
3527
3528            result = self.api.datasets.create(
3529                name=name,
3530                description=description,
3531                metadata=metadata,
3532                input_schema=input_schema,
3533                expected_output_schema=expected_output_schema,
3534            )
3535
3536            return cast(Dataset, result)
3537
3538        except Error as e:
3539            handle_fern_exception(e)
3540            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: 
3542    def create_dataset_item(
3543        self,
3544        *,
3545        dataset_name: str,
3546        input: Optional[Any] = None,
3547        expected_output: Optional[Any] = None,
3548        metadata: Optional[Any] = None,
3549        source_trace_id: Optional[str] = None,
3550        source_observation_id: Optional[str] = None,
3551        status: Optional[DatasetStatus] = None,
3552        id: Optional[str] = None,
3553    ) -> DatasetItem:
3554        """Create a dataset item.
3555
3556        Upserts if an item with id already exists.
3557
3558        Args:
3559            dataset_name: Name of the dataset in which the dataset item should be created.
3560            input: Input data. Defaults to None. Can contain any dict, list or scalar.
3561            expected_output: Expected output data. Defaults to None. Can contain any dict, list or scalar.
3562            metadata: Additional metadata. Defaults to None. Can contain any dict, list or scalar.
3563            source_trace_id: Id of the source trace. Defaults to None.
3564            source_observation_id: Id of the source observation. Defaults to None.
3565            status: Status of the dataset item. Defaults to ACTIVE for newly created items.
3566            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.
3567
3568        Returns:
3569            DatasetItem: The created dataset item as returned by the Langfuse API.
3570
3571        Example:
3572            ```python
3573            from langfuse import Langfuse
3574
3575            langfuse = Langfuse()
3576
3577            # Uploading items to the Langfuse dataset named "capital_cities"
3578            langfuse.create_dataset_item(
3579                dataset_name="capital_cities",
3580                input={"input": {"country": "Italy"}},
3581                expected_output={"expected_output": "Rome"},
3582                metadata={"foo": "bar"}
3583            )
3584            ```
3585        """
3586        try:
3587            langfuse_logger.debug(f"Creating dataset item for dataset {dataset_name}")
3588
3589            # Media uploads must reference the (dataset, item) they belong to, and
3590            # the item need not exist yet — so settle on the item id up front and
3591            # reuse it for the create call below.
3592            item_id = id if id is not None else str(uuid.uuid4())
3593
3594            # Single pass per field: swap each LangfuseMedia for its reference
3595            # string (derived from content, not the upload) and collect the media
3596            # still to upload, deduped by media id and tagged with its field.
3597            pending_media: Dict[str, Tuple[LangfuseMedia, str]] = {}
3598            input = self._process_dataset_item_media(
3599                data=input,
3600                pending_media=pending_media,
3601                field=DatasetItemMediaReferenceField.INPUT.value,
3602            )
3603            expected_output = self._process_dataset_item_media(
3604                data=expected_output,
3605                pending_media=pending_media,
3606                field=DatasetItemMediaReferenceField.EXPECTED_OUTPUT.value,
3607            )
3608            metadata = self._process_dataset_item_media(
3609                data=metadata,
3610                pending_media=pending_media,
3611                field=DatasetItemMediaReferenceField.METADATA.value,
3612            )
3613
3614            # The upload needs the dataset id, but the create API only takes the
3615            # name. Resolve it once, and only when there is actually media to
3616            # upload — a plain item pays no extra datasets.get round-trip.
3617            if pending_media:
3618                assert self._resources is not None
3619                dataset_id = self.api.datasets.get(self._url_encode(dataset_name)).id
3620                for media, field in pending_media.values():
3621                    self._resources._media_manager._upload_media_sync(
3622                        media=media,
3623                        dataset_id=dataset_id,
3624                        dataset_item_id=item_id,
3625                        field=field,
3626                    )
3627
3628            result = self.api.dataset_items.create(
3629                dataset_name=dataset_name,
3630                input=input,
3631                expected_output=expected_output,
3632                metadata=metadata,
3633                source_trace_id=source_trace_id,
3634                source_observation_id=source_observation_id,
3635                status=status,
3636                id=item_id,
3637            )
3638
3639            return cast(DatasetItem, result)
3640        except Error as e:
3641            handle_fern_exception(e)
3642            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: 
3768    def resolve_media_references(
3769        self,
3770        *,
3771        obj: Any,
3772        resolve_with: Literal["base64_data_uri"],
3773        max_depth: int = 10,
3774        content_fetch_timeout_seconds: int = 5,
3775    ) -> Any:
3776        """Replace media reference strings in an object with base64 data URIs.
3777
3778        This method recursively traverses an object (up to max_depth) looking for media reference strings
3779        in the format "@@@langfuseMedia:...@@@". When found, it (synchronously) fetches the actual media content using
3780        the provided Langfuse client and replaces the reference string with a base64 data URI.
3781
3782        If fetching media content fails for a reference string, a warning is logged and the reference
3783        string is left unchanged.
3784
3785        Args:
3786            obj: The object to process. Can be a primitive value, array, or nested object.
3787                If the object has a __dict__ attribute, a dict will be returned instead of the original object type.
3788            resolve_with: The representation of the media content to replace the media reference string with.
3789                Currently only "base64_data_uri" is supported.
3790            max_depth: int: The maximum depth to traverse the object. Default is 10.
3791            content_fetch_timeout_seconds: int: The timeout in seconds for fetching media content. Default is 5.
3792
3793        Returns:
3794            A deep copy of the input object with all media references replaced with base64 data URIs where possible.
3795            If the input object has a __dict__ attribute, a dict will be returned instead of the original object type.
3796
3797        Example:
3798            obj = {
3799                "image": "@@@langfuseMedia:type=image/jpeg|id=123|source=bytes@@@",
3800                "nested": {
3801                    "pdf": "@@@langfuseMedia:type=application/pdf|id=456|source=bytes@@@"
3802                }
3803            }
3804
3805            result = await LangfuseMedia.resolve_media_references(obj, langfuse_client)
3806
3807            # Result:
3808            # {
3809            #     "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
3810            #     "nested": {
3811            #         "pdf": "data:application/pdf;base64,JVBERi0xLjcK..."
3812            #     }
3813            # }
3814        """
3815        return LangfuseMedia.resolve_media_references(
3816            langfuse_client=self,
3817            obj=obj,
3818            resolve_with=resolve_with,
3819            max_depth=max_depth,
3820            content_fetch_timeout_seconds=content_fetch_timeout_seconds,
3821        )

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]: 
3851    def get_prompt(
3852        self,
3853        name: str,
3854        *,
3855        version: Optional[int] = None,
3856        label: Optional[str] = None,
3857        type: Literal["chat", "text"] = "text",
3858        cache_ttl_seconds: Optional[int] = None,
3859        fallback: Union[Optional[List[ChatMessageDict]], Optional[str]] = None,
3860        max_retries: Optional[int] = None,
3861        fetch_timeout_seconds: Optional[int] = None,
3862    ) -> PromptClient:
3863        """Get a prompt.
3864
3865        This method attempts to fetch the requested prompt from the local cache. If the prompt is not found
3866        in the cache or if the cached prompt has expired, it will try to fetch the prompt from the server again
3867        and update the cache. If fetching the new prompt fails, and there is an expired prompt in the cache, it will
3868        return the expired prompt as a fallback.
3869
3870        Args:
3871            name (str): The name of the prompt to retrieve.
3872
3873        Keyword Args:
3874            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.
3875            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.
3876            cache_ttl_seconds: Optional[int]: Time-to-live in seconds for caching the prompt. Must be specified as a
3877            keyword argument. If not set, defaults to 60 seconds. Disables caching if set to 0.
3878            type: Literal["chat", "text"]: The type of the prompt to retrieve. Defaults to "text".
3879            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.
3880            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.
3881            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.
3882
3883        Returns:
3884            The prompt object retrieved from the cache or directly fetched if not cached or expired of type
3885            - TextPromptClient, if type argument is 'text'.
3886            - ChatPromptClient, if type argument is 'chat'.
3887
3888        Raises:
3889            Exception: Propagates any exceptions raised during the fetching of a new prompt, unless there is an
3890            expired prompt in the cache, in which case it logs a warning and returns the expired prompt.
3891        """
3892        if self._resources is None:
3893            raise Error(
3894                "SDK is not correctly initialized. Check the init logs for more details."
3895            )
3896        if version is not None and label is not None:
3897            raise ValueError("Cannot specify both version and label at the same time.")
3898
3899        if not name:
3900            raise ValueError("Prompt name cannot be empty.")
3901
3902        cache_key = PromptCache.generate_cache_key(name, version=version, label=label)
3903        bounded_max_retries = self._get_bounded_max_retries(
3904            max_retries, default_max_retries=2, max_retries_upper_bound=4
3905        )
3906
3907        langfuse_logger.debug(f"Getting prompt '{cache_key}'")
3908        cached_prompt = self._resources.prompt_cache.get(cache_key)
3909
3910        if cached_prompt is None or cache_ttl_seconds == 0:
3911            langfuse_logger.debug(
3912                f"Prompt '{cache_key}' not found in cache or caching disabled."
3913            )
3914            try:
3915                return self._fetch_prompt_and_update_cache(
3916                    name,
3917                    version=version,
3918                    label=label,
3919                    ttl_seconds=cache_ttl_seconds,
3920                    max_retries=bounded_max_retries,
3921                    fetch_timeout_seconds=fetch_timeout_seconds,
3922                )
3923            except Exception as e:
3924                if fallback:
3925                    langfuse_logger.warning(
3926                        f"Returning fallback prompt for '{cache_key}' due to fetch error: {e}"
3927                    )
3928
3929                    fallback_client_args: Dict[str, Any] = {
3930                        "name": name,
3931                        "prompt": fallback,
3932                        "type": type,
3933                        "version": version or 0,
3934                        "config": {},
3935                        "labels": [label] if label else [],
3936                        "tags": [],
3937                    }
3938
3939                    if type == "text":
3940                        return TextPromptClient(
3941                            prompt=Prompt_Text(**fallback_client_args),
3942                            is_fallback=True,
3943                        )
3944
3945                    if type == "chat":
3946                        return ChatPromptClient(
3947                            prompt=Prompt_Chat(**fallback_client_args),
3948                            is_fallback=True,
3949                        )
3950
3951                raise e
3952
3953        if cached_prompt.is_expired():
3954            langfuse_logger.debug(f"Stale prompt '{cache_key}' found in cache.")
3955            try:
3956                # refresh prompt in background thread, refresh_prompt deduplicates tasks
3957                langfuse_logger.debug(f"Refreshing prompt '{cache_key}' in background.")
3958
3959                def refresh_task() -> None:
3960                    self._fetch_prompt_and_update_cache(
3961                        name,
3962                        version=version,
3963                        label=label,
3964                        ttl_seconds=cache_ttl_seconds,
3965                        max_retries=bounded_max_retries,
3966                        fetch_timeout_seconds=fetch_timeout_seconds,
3967                    )
3968
3969                self._resources.prompt_cache.add_refresh_prompt_task_if_current(
3970                    cache_key,
3971                    cached_prompt,
3972                    refresh_task,
3973                )
3974                langfuse_logger.debug(
3975                    f"Returning stale prompt '{cache_key}' from cache."
3976                )
3977                # return stale prompt
3978                return cached_prompt.value
3979
3980            except Exception as e:
3981                langfuse_logger.warning(
3982                    f"Error when refreshing cached prompt '{cache_key}', returning cached version. Error: {e}"
3983                )
3984                # creation of refresh prompt task failed, return stale prompt
3985                return cached_prompt.value
3986
3987        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]: 
4089    def create_prompt(
4090        self,
4091        *,
4092        name: str,
4093        prompt: Union[
4094            str, List[Union[ChatMessageDict, ChatMessageWithPlaceholdersDict]]
4095        ],
4096        labels: List[str] = [],
4097        tags: Optional[List[str]] = None,
4098        type: Optional[Literal["chat", "text"]] = "text",
4099        config: Optional[Any] = None,
4100        commit_message: Optional[str] = None,
4101    ) -> PromptClient:
4102        """Create a new prompt in Langfuse.
4103
4104        Keyword Args:
4105            name : The name of the prompt to be created.
4106            prompt : The content of the prompt to be created.
4107            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.
4108            labels: The labels of the prompt. Defaults to None. To create a default-served prompt, add the 'production' label.
4109            tags: The tags of the prompt. Defaults to None. Will be applied to all versions of the prompt.
4110            config: Additional structured data to be saved with the prompt. Defaults to None.
4111            type: The type of the prompt to be created. "chat" vs. "text". Defaults to "text".
4112            commit_message: Optional string describing the change.
4113
4114        Returns:
4115            TextPromptClient: The prompt if type argument is 'text'.
4116            ChatPromptClient: The prompt if type argument is 'chat'.
4117        """
4118        try:
4119            langfuse_logger.debug(f"Creating prompt {name=}, {labels=}")
4120
4121            if type == "chat":
4122                if not isinstance(prompt, list):
4123                    raise ValueError(
4124                        "For 'chat' type, 'prompt' must be a list of chat messages with role and content attributes."
4125                    )
4126                request: Union[CreateChatPromptRequest, CreateTextPromptRequest] = (
4127                    CreateChatPromptRequest(
4128                        name=name,
4129                        prompt=cast(Any, prompt),
4130                        labels=labels,
4131                        tags=tags,
4132                        config=config or {},
4133                        commit_message=commit_message,
4134                        type=CreateChatPromptType.CHAT,
4135                    )
4136                )
4137                server_prompt = self.api.prompts.create(request=request)
4138
4139                if self._resources is not None:
4140                    self._resources.prompt_cache.invalidate(name)
4141
4142                return ChatPromptClient(prompt=cast(Prompt_Chat, server_prompt))
4143
4144            if not isinstance(prompt, str):
4145                raise ValueError("For 'text' type, 'prompt' must be a string.")
4146
4147            request = CreateTextPromptRequest(
4148                name=name,
4149                prompt=prompt,
4150                labels=labels,
4151                tags=tags,
4152                config=config or {},
4153                commit_message=commit_message,
4154            )
4155
4156            server_prompt = self.api.prompts.create(request=request)
4157
4158            if self._resources is not None:
4159                self._resources.prompt_cache.invalidate(name)
4160
4161            return TextPromptClient(prompt=cast(Prompt_Text, server_prompt))
4162
4163        except Error as e:
4164            handle_fern_exception(e)
4165            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: 
4167    def update_prompt(
4168        self,
4169        *,
4170        name: str,
4171        version: int,
4172        new_labels: List[str] = [],
4173    ) -> Any:
4174        """Update an existing prompt version in Langfuse. The Langfuse SDK prompt cache is invalidated for all prompts witht he specified name.
4175
4176        Args:
4177            name (str): The name of the prompt to update.
4178            version (int): The version number of the prompt to update.
4179            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 [].
4180
4181        Returns:
4182            Prompt: The updated prompt from the Langfuse API.
4183
4184        """
4185        updated_prompt = self.api.prompt_version.update(
4186            name=self._url_encode(name),
4187            version=version,
4188            new_labels=new_labels,
4189        )
4190
4191        if self._resources is not None:
4192            self._resources.prompt_cache.invalidate(name)
4193
4194        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: 
4209    def clear_prompt_cache(self) -> None:
4210        """Clear the entire prompt cache, removing all cached prompts.
4211
4212        This method is useful when you want to force a complete refresh of all
4213        cached prompts, for example after major updates or when you need to
4214        ensure the latest versions are fetched from the server.
4215        """
4216        if self._resources is not None:
4217            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: 
1071class RunnerContext:
1072    """Wraps :meth:`Langfuse.run_experiment` with CI-injected defaults.
1073
1074    Intended for use with the ``langfuse/experiment-action`` GitHub Action
1075    (https://github.com/langfuse/experiment-action). The action builds a
1076    ``RunnerContext`` before invoking the user's ``experiment(context)``
1077    function. Defaults set here (dataset, metadata tags) are applied when
1078    the user omits them on the :meth:`run_experiment` call; users can
1079    override any default by passing the corresponding argument explicitly.
1080    """
1081
1082    def __init__(
1083        self,
1084        *,
1085        client: "Langfuse",
1086        data: Optional[ExperimentData] = None,
1087        dataset_version: Optional[datetime] = None,
1088        metadata: Optional[Dict[str, str]] = None,
1089    ):
1090        """Build a ``RunnerContext`` populated with defaults for ``run_experiment``.
1091
1092        Typically called by the ``langfuse/experiment-action`` GitHub Action,
1093        not by end users directly. Every field except ``client`` is optional:
1094        fields left as ``None`` simply mean the corresponding argument must be
1095        supplied on the :meth:`run_experiment` call.
1096
1097        Args:
1098            client: Initialized Langfuse SDK client used to execute the
1099                experiment. The action creates this from the
1100                ``langfuse_public_key`` / ``langfuse_secret_key`` /
1101                ``langfuse_base_url`` inputs.
1102            data: Default dataset items to run the experiment on. Accepts
1103                either ``List[LocalExperimentItem]`` or ``List[DatasetItem]``.
1104                Injected by the action when ``dataset_name`` is configured.
1105                If ``None``, the user must pass ``data=`` to
1106                :meth:`run_experiment`.
1107            dataset_version: Optional pinned dataset version. Injected by the
1108                action when ``dataset_version`` is configured.
1109            metadata: Default metadata attached to every experiment trace and
1110                the dataset run. The action injects GitHub-sourced tags (SHA,
1111                PR link, workflow run link, branch, GH user, etc.). Merged
1112                with any ``metadata`` passed to :meth:`run_experiment`, with
1113                user-supplied keys winning on collision.
1114        """
1115        self.client = client
1116        self.data = data
1117        self.dataset_version = dataset_version
1118        self.metadata = metadata
1119
1120    def run_experiment(
1121        self,
1122        *,
1123        name: str,
1124        run_name: Optional[str] = None,
1125        description: Optional[str] = None,
1126        data: Optional[ExperimentData] = None,
1127        task: TaskFunction,
1128        evaluators: List[EvaluatorFunction] = [],
1129        composite_evaluator: Optional["CompositeEvaluatorFunction"] = None,
1130        run_evaluators: List[RunEvaluatorFunction] = [],
1131        max_concurrency: int = 50,
1132        metadata: Optional[Dict[str, str]] = None,
1133        _dataset_version: Optional[datetime] = None,
1134    ) -> ExperimentResult:
1135        resolved_data = data if data is not None else self.data
1136        if resolved_data is None:
1137            raise ValueError(
1138                "`data` must be provided either on the RunnerContext or the run_experiment call"
1139            )
1140
1141        resolved_dataset_version = (
1142            _dataset_version if _dataset_version is not None else self.dataset_version
1143        )
1144
1145        merged_metadata: Optional[Dict[str, str]]
1146        if self.metadata is None and metadata is None:
1147            merged_metadata = None
1148        else:
1149            merged_metadata = {**(self.metadata or {}), **(metadata or {})}
1150
1151        return self.client.run_experiment(
1152            name=name,
1153            run_name=run_name,
1154            description=description,
1155            data=resolved_data,
1156            task=task,
1157            evaluators=evaluators,
1158            composite_evaluator=composite_evaluator,
1159            run_evaluators=run_evaluators,
1160            max_concurrency=max_concurrency,
1161            metadata=merged_metadata,
1162            _dataset_version=resolved_dataset_version,
1163        )

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) 
1082    def __init__(
1083        self,
1084        *,
1085        client: "Langfuse",
1086        data: Optional[ExperimentData] = None,
1087        dataset_version: Optional[datetime] = None,
1088        metadata: Optional[Dict[str, str]] = None,
1089    ):
1090        """Build a ``RunnerContext`` populated with defaults for ``run_experiment``.
1091
1092        Typically called by the ``langfuse/experiment-action`` GitHub Action,
1093        not by end users directly. Every field except ``client`` is optional:
1094        fields left as ``None`` simply mean the corresponding argument must be
1095        supplied on the :meth:`run_experiment` call.
1096
1097        Args:
1098            client: Initialized Langfuse SDK client used to execute the
1099                experiment. The action creates this from the
1100                ``langfuse_public_key`` / ``langfuse_secret_key`` /
1101                ``langfuse_base_url`` inputs.
1102            data: Default dataset items to run the experiment on. Accepts
1103                either ``List[LocalExperimentItem]`` or ``List[DatasetItem]``.
1104                Injected by the action when ``dataset_name`` is configured.
1105                If ``None``, the user must pass ``data=`` to
1106                :meth:`run_experiment`.
1107            dataset_version: Optional pinned dataset version. Injected by the
1108                action when ``dataset_version`` is configured.
1109            metadata: Default metadata attached to every experiment trace and
1110                the dataset run. The action injects GitHub-sourced tags (SHA,
1111                PR link, workflow run link, branch, GH user, etc.). Merged
1112                with any ``metadata`` passed to :meth:`run_experiment`, with
1113                user-supplied keys winning on collision.
1114        """
1115        self.client = client
1116        self.data = data
1117        self.dataset_version = dataset_version
1118        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: 
1120    def run_experiment(
1121        self,
1122        *,
1123        name: str,
1124        run_name: Optional[str] = None,
1125        description: Optional[str] = None,
1126        data: Optional[ExperimentData] = None,
1127        task: TaskFunction,
1128        evaluators: List[EvaluatorFunction] = [],
1129        composite_evaluator: Optional["CompositeEvaluatorFunction"] = None,
1130        run_evaluators: List[RunEvaluatorFunction] = [],
1131        max_concurrency: int = 50,
1132        metadata: Optional[Dict[str, str]] = None,
1133        _dataset_version: Optional[datetime] = None,
1134    ) -> ExperimentResult:
1135        resolved_data = data if data is not None else self.data
1136        if resolved_data is None:
1137            raise ValueError(
1138                "`data` must be provided either on the RunnerContext or the run_experiment call"
1139            )
1140
1141        resolved_dataset_version = (
1142            _dataset_version if _dataset_version is not None else self.dataset_version
1143        )
1144
1145        merged_metadata: Optional[Dict[str, str]]
1146        if self.metadata is None and metadata is None:
1147            merged_metadata = None
1148        else:
1149            merged_metadata = {**(self.metadata or {}), **(metadata or {})}
1150
1151        return self.client.run_experiment(
1152            name=name,
1153            run_name=run_name,
1154            description=description,
1155            data=resolved_data,
1156            task=task,
1157            evaluators=evaluators,
1158            composite_evaluator=composite_evaluator,
1159            run_evaluators=run_evaluators,
1160            max_concurrency=max_concurrency,
1161            metadata=merged_metadata,
1162            _dataset_version=resolved_dataset_version,
1163        )
class RegressionError(builtins.Exception): 
1166class RegressionError(Exception):
1167    """Raised by a user's ``experiment`` function to signal a CI gate failure.
1168
1169    Intended for use with the ``langfuse/experiment-action`` GitHub Action
1170    (https://github.com/langfuse/experiment-action). The action catches this
1171    exception and, when ``should_fail_on_error`` is enabled, fails the
1172    workflow run and renders a callout in the PR comment using
1173    ``metric``/``value``/``threshold`` if supplied, otherwise ``str(exc)``.
1174
1175    Callers choose one of three forms:
1176
1177    - ``RegressionError(result=r)`` — minimal, generic message.
1178    - ``RegressionError(result=r, message="...")`` — free-form message.
1179    - ``RegressionError(result=r, metric="acc", value=0.7, threshold=0.9)`` —
1180      structured; ``metric`` and ``value`` must be provided together so the
1181      action can render a targeted callout without ``None`` placeholders.
1182    """
1183
1184    @overload
1185    def __init__(self, *, result: ExperimentResult) -> None: ...
1186    @overload
1187    def __init__(self, *, result: ExperimentResult, message: str) -> None: ...
1188    @overload
1189    def __init__(
1190        self,
1191        *,
1192        result: ExperimentResult,
1193        metric: str,
1194        value: float,
1195        threshold: Optional[float] = None,
1196        message: Optional[str] = None,
1197    ) -> None: ...
1198    def __init__(
1199        self,
1200        *,
1201        result: ExperimentResult,
1202        metric: Optional[str] = None,
1203        value: Optional[float] = None,
1204        threshold: Optional[float] = None,
1205        message: Optional[str] = None,
1206    ):
1207        self.result = result
1208        self.metric = metric
1209        self.value = value
1210        self.threshold = threshold
1211        if message is not None:
1212            formatted = message
1213        elif metric is not None and value is not None:
1214            formatted = f"Regression on `{metric}`: {value} (threshold {threshold})"
1215        else:
1216            formatted = "Experiment regression detected"
1217        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) 
1198    def __init__(
1199        self,
1200        *,
1201        result: ExperimentResult,
1202        metric: Optional[str] = None,
1203        value: Optional[float] = None,
1204        threshold: Optional[float] = None,
1205        message: Optional[str] = None,
1206    ):
1207        self.result = result
1208        self.metric = metric
1209        self.value = value
1210        self.threshold = threshold
1211        if message is not None:
1212            formatted = message
1213        elif metric is not None and value is not None:
1214            formatted = f"Regression on `{metric}`: {value} (threshold {threshold})"
1215        else:
1216            formatted = "Experiment regression detected"
1217        super().__init__(formatted)
result
metric
value
threshold
__version__ = '4.14.1'
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({'opentelemetry.instrumentation.openai', 'opentelemetry.instrumentation.watsonx', 'opentelemetry.instrumentation.bedrock', 'opentelemetry.instrumentation.voyageai', 'pydantic-ai', 'opentelemetry.instrumentation.mistralai', 'opentelemetry.instrumentation.openai_v2', 'opentelemetry.instrumentation.agno', 'langsmith', 'agent_framework', 'opentelemetry.instrumentation.alephalpha', 'opentelemetry.instrumentation.groq', 'opentelemetry.instrumentation.vertexai', 'langfuse-sdk', 'openinference', 'autogen-core', 'opentelemetry.instrumentation.replicate', 'vllm', 'opentelemetry.instrumentation.google_generativeai', 'opentelemetry.instrumentation.langchain', 'opentelemetry.instrumentation.sagemaker', 'haystack', 'opentelemetry.instrumentation.cohere', 'ai', 'strands-agents', 'opentelemetry.instrumentation.crewai', 'opentelemetry.instrumentation.haystack', 'opentelemetry.instrumentation.writer', 'opentelemetry.instrumentation.transformers', 'opentelemetry.instrumentation.openai_agents', 'opentelemetry.instrumentation.anthropic', 'opentelemetry.instrumentation.together', 'litellm', 'opentelemetry.instrumentation.llamaindex', 'opentelemetry.instrumentation.ollama'})
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]