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

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

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

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

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

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

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

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

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

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

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

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

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

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]: 
3850    def get_prompt(
3851        self,
3852        name: str,
3853        *,
3854        version: Optional[int] = None,
3855        label: Optional[str] = None,
3856        type: Literal["chat", "text"] = "text",
3857        cache_ttl_seconds: Optional[int] = None,
3858        fallback: Union[Optional[List[ChatMessageDict]], Optional[str]] = None,
3859        max_retries: Optional[int] = None,
3860        fetch_timeout_seconds: Optional[int] = None,
3861    ) -> PromptClient:
3862        """Get a prompt.
3863
3864        This method attempts to fetch the requested prompt from the local cache. If the prompt is not found
3865        in the cache or if the cached prompt has expired, it will try to fetch the prompt from the server again
3866        and update the cache. If fetching the new prompt fails, and there is an expired prompt in the cache, it will
3867        return the expired prompt as a fallback.
3868
3869        Args:
3870            name (str): The name of the prompt to retrieve.
3871
3872        Keyword Args:
3873            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.
3874            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.
3875            cache_ttl_seconds: Optional[int]: Time-to-live in seconds for caching the prompt. Must be specified as a
3876            keyword argument. If not set, defaults to 60 seconds. Disables caching if set to 0.
3877            type: Literal["chat", "text"]: The type of the prompt to retrieve. Defaults to "text".
3878            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.
3879            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.
3880            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.
3881
3882        Returns:
3883            The prompt object retrieved from the cache or directly fetched if not cached or expired of type
3884            - TextPromptClient, if type argument is 'text'.
3885            - ChatPromptClient, if type argument is 'chat'.
3886
3887        Raises:
3888            Exception: Propagates any exceptions raised during the fetching of a new prompt, unless there is an
3889            expired prompt in the cache, in which case it logs a warning and returns the expired prompt.
3890        """
3891        if self._resources is None:
3892            raise Error(
3893                "SDK is not correctly initialized. Check the init logs for more details."
3894            )
3895        if version is not None and label is not None:
3896            raise ValueError("Cannot specify both version and label at the same time.")
3897
3898        if not name:
3899            raise ValueError("Prompt name cannot be empty.")
3900
3901        cache_key = PromptCache.generate_cache_key(name, version=version, label=label)
3902        bounded_max_retries = self._get_bounded_max_retries(
3903            max_retries, default_max_retries=2, max_retries_upper_bound=4
3904        )
3905
3906        langfuse_logger.debug(f"Getting prompt '{cache_key}'")
3907        cached_prompt = self._resources.prompt_cache.get(cache_key)
3908
3909        if cached_prompt is None or cache_ttl_seconds == 0:
3910            langfuse_logger.debug(
3911                f"Prompt '{cache_key}' not found in cache or caching disabled."
3912            )
3913            try:
3914                return self._fetch_prompt_and_update_cache(
3915                    name,
3916                    version=version,
3917                    label=label,
3918                    ttl_seconds=cache_ttl_seconds,
3919                    max_retries=bounded_max_retries,
3920                    fetch_timeout_seconds=fetch_timeout_seconds,
3921                )
3922            except Exception as e:
3923                if fallback:
3924                    langfuse_logger.warning(
3925                        f"Returning fallback prompt for '{cache_key}' due to fetch error: {e}"
3926                    )
3927
3928                    fallback_client_args: Dict[str, Any] = {
3929                        "name": name,
3930                        "prompt": fallback,
3931                        "type": type,
3932                        "version": version or 0,
3933                        "config": {},
3934                        "labels": [label] if label else [],
3935                        "tags": [],
3936                    }
3937
3938                    if type == "text":
3939                        return TextPromptClient(
3940                            prompt=Prompt_Text(**fallback_client_args),
3941                            is_fallback=True,
3942                        )
3943
3944                    if type == "chat":
3945                        return ChatPromptClient(
3946                            prompt=Prompt_Chat(**fallback_client_args),
3947                            is_fallback=True,
3948                        )
3949
3950                raise e
3951
3952        if cached_prompt.is_expired():
3953            langfuse_logger.debug(f"Stale prompt '{cache_key}' found in cache.")
3954            try:
3955                # refresh prompt in background thread, refresh_prompt deduplicates tasks
3956                langfuse_logger.debug(f"Refreshing prompt '{cache_key}' in background.")
3957
3958                def refresh_task() -> None:
3959                    self._fetch_prompt_and_update_cache(
3960                        name,
3961                        version=version,
3962                        label=label,
3963                        ttl_seconds=cache_ttl_seconds,
3964                        max_retries=bounded_max_retries,
3965                        fetch_timeout_seconds=fetch_timeout_seconds,
3966                    )
3967
3968                self._resources.prompt_cache.add_refresh_prompt_task_if_current(
3969                    cache_key,
3970                    cached_prompt,
3971                    refresh_task,
3972                )
3973                langfuse_logger.debug(
3974                    f"Returning stale prompt '{cache_key}' from cache."
3975                )
3976                # return stale prompt
3977                return cached_prompt.value
3978
3979            except Exception as e:
3980                langfuse_logger.warning(
3981                    f"Error when refreshing cached prompt '{cache_key}', returning cached version. Error: {e}"
3982                )
3983                # creation of refresh prompt task failed, return stale prompt
3984                return cached_prompt.value
3985
3986        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]: 
4088    def create_prompt(
4089        self,
4090        *,
4091        name: str,
4092        prompt: Union[
4093            str, List[Union[ChatMessageDict, ChatMessageWithPlaceholdersDict]]
4094        ],
4095        labels: List[str] = [],
4096        tags: Optional[List[str]] = None,
4097        type: Optional[Literal["chat", "text"]] = "text",
4098        config: Optional[Any] = None,
4099        commit_message: Optional[str] = None,
4100    ) -> PromptClient:
4101        """Create a new prompt in Langfuse.
4102
4103        Keyword Args:
4104            name : The name of the prompt to be created.
4105            prompt : The content of the prompt to be created.
4106            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.
4107            labels: The labels of the prompt. Defaults to None. To create a default-served prompt, add the 'production' label.
4108            tags: The tags of the prompt. Defaults to None. Will be applied to all versions of the prompt.
4109            config: Additional structured data to be saved with the prompt. Defaults to None.
4110            type: The type of the prompt to be created. "chat" vs. "text". Defaults to "text".
4111            commit_message: Optional string describing the change.
4112
4113        Returns:
4114            TextPromptClient: The prompt if type argument is 'text'.
4115            ChatPromptClient: The prompt if type argument is 'chat'.
4116        """
4117        try:
4118            langfuse_logger.debug(f"Creating prompt {name=}, {labels=}")
4119
4120            if type == "chat":
4121                if not isinstance(prompt, list):
4122                    raise ValueError(
4123                        "For 'chat' type, 'prompt' must be a list of chat messages with role and content attributes."
4124                    )
4125                request: Union[CreateChatPromptRequest, CreateTextPromptRequest] = (
4126                    CreateChatPromptRequest(
4127                        name=name,
4128                        prompt=cast(Any, prompt),
4129                        labels=labels,
4130                        tags=tags,
4131                        config=config or {},
4132                        commit_message=commit_message,
4133                        type=CreateChatPromptType.CHAT,
4134                    )
4135                )
4136                server_prompt = self.api.prompts.create(request=request)
4137
4138                if self._resources is not None:
4139                    self._resources.prompt_cache.invalidate(name)
4140
4141                return ChatPromptClient(prompt=cast(Prompt_Chat, server_prompt))
4142
4143            if not isinstance(prompt, str):
4144                raise ValueError("For 'text' type, 'prompt' must be a string.")
4145
4146            request = CreateTextPromptRequest(
4147                name=name,
4148                prompt=prompt,
4149                labels=labels,
4150                tags=tags,
4151                config=config or {},
4152                commit_message=commit_message,
4153            )
4154
4155            server_prompt = self.api.prompts.create(request=request)
4156
4157            if self._resources is not None:
4158                self._resources.prompt_cache.invalidate(name)
4159
4160            return TextPromptClient(prompt=cast(Prompt_Text, server_prompt))
4161
4162        except Error as e:
4163            handle_fern_exception(e)
4164            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: 
4166    def update_prompt(
4167        self,
4168        *,
4169        name: str,
4170        version: int,
4171        new_labels: List[str] = [],
4172    ) -> Any:
4173        """Update an existing prompt version in Langfuse. The Langfuse SDK prompt cache is invalidated for all prompts witht he specified name.
4174
4175        Args:
4176            name (str): The name of the prompt to update.
4177            version (int): The version number of the prompt to update.
4178            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 [].
4179
4180        Returns:
4181            Prompt: The updated prompt from the Langfuse API.
4182
4183        """
4184        updated_prompt = self.api.prompt_version.update(
4185            name=self._url_encode(name),
4186            version=version,
4187            new_labels=new_labels,
4188        )
4189
4190        if self._resources is not None:
4191            self._resources.prompt_cache.invalidate(name)
4192
4193        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: 
4208    def clear_prompt_cache(self) -> None:
4209        """Clear the entire prompt cache, removing all cached prompts.
4210
4211        This method is useful when you want to force a complete refresh of all
4212        cached prompts, for example after major updates or when you need to
4213        ensure the latest versions are fetched from the server.
4214        """
4215        if self._resources is not None:
4216            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]]: 
 91    def observe(
 92        self,
 93        func: Optional[F] = None,
 94        *,
 95        name: Optional[str] = None,
 96        as_type: Optional[ObservationTypeLiteralNoEvent] = None,
 97        capture_input: Optional[bool] = None,
 98        capture_output: Optional[bool] = None,
 99        transform_to_string: Optional[Callable[[Iterable], str]] = None,
100    ) -> Union[F, Callable[[F], F]]:
101        """Wrap a function to create and manage Langfuse tracing around its execution, supporting both synchronous and asynchronous functions.
102
103        This decorator provides seamless integration of Langfuse observability into your codebase. It automatically creates
104        spans or generations around function execution, capturing timing, inputs/outputs, and error states. The decorator
105        intelligently handles both synchronous and asynchronous functions, preserving function signatures and type hints.
106
107        Using OpenTelemetry's distributed tracing system, it maintains proper trace context propagation throughout your application,
108        enabling you to see hierarchical traces of function calls with detailed performance metrics and function-specific details.
109
110        Args:
111            func (Optional[Callable]): The function to decorate. When used with parentheses @observe(), this will be None.
112            name (Optional[str]): Custom name for the created trace or span. If not provided, the function name is used.
113            as_type (Optional[Literal]): Set the observation type. Supported values:
114                    "generation", "span", "agent", "tool", "chain", "retriever", "embedding", "evaluator", "guardrail".
115                    Observation types are highlighted in the Langfuse UI for filtering and visualization.
116                    The types "generation" and "embedding" create a span on which additional attributes such as model,
117                    usage_details, and cost_details can be set — use `as_type="generation"` for LLM calls and update the
118                    observation via `langfuse.update_current_generation(...)` inside the function.
119            capture_input (Optional[bool]): Whether to capture the function's arguments as the observation's input.
120                    Defaults to the LANGFUSE_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED environment variable (True if unset).
121                    Set to False for sensitive or very large inputs, then set input explicitly via
122                    `langfuse.update_current_span(input=...)` if needed.
123            capture_output (Optional[bool]): Whether to capture the function's return value as the observation's output.
124                    Same default and override mechanism as capture_input.
125            transform_to_string (Optional[Callable[[Iterable], str]]): For functions returning generators, joins the
126                    yielded chunks into the string stored as output. Without it, chunks are concatenated if all are
127                    strings, otherwise stored as a list.
128
129        Returns:
130            Callable: A wrapped version of the original function that automatically creates and manages Langfuse spans.
131
132        Example:
133            For general function tracing with automatic naming:
134            ```python
135            @observe()
136            def process_user_request(user_id, query):
137                # Function is automatically traced with name "process_user_request"
138                return get_response(query)
139            ```
140
141            For language model generation tracking:
142            ```python
143            from langfuse import get_client, observe
144
145            @observe(name="answer-generation", as_type="generation")
146            async def generate_answer(query):
147                # Creates a generation-type observation with extended LLM metrics
148                response = await openai.chat.completions.create(
149                    model="gpt-4",
150                    messages=[{"role": "user", "content": query}]
151                )
152                return response.choices[0].message.content
153            ```
154
155            Disabling input/output capture (e.g. for sensitive or large payloads):
156            ```python
157            @observe(capture_input=False, capture_output=False)
158            def handle_pii(user_record):
159                return process(user_record)
160            ```
161
162            For trace context propagation between functions:
163            ```python
164            @observe()
165            def main_process():
166                # Parent span is created
167                return sub_process()  # Child span automatically connected to parent
168
169            @observe()
170            def sub_process():
171                # Automatically becomes a child span of main_process
172                return "result"
173            ```
174
175        Raises:
176            Exception: Propagates any exceptions from the wrapped function after logging them in the trace.
177
178        Notes:
179            - The decorator preserves the original function's signature, docstring, and return type.
180            - Proper parent-child relationships between spans are automatically maintained.
181            - Special keyword arguments can be passed to control tracing:
182              - langfuse_trace_id: Explicitly set the trace ID for this function call
183              - langfuse_parent_observation_id: Explicitly set the parent span ID
184              - langfuse_public_key: Use a specific Langfuse project (when multiple clients exist)
185            - For async functions, the decorator returns an async function wrapper.
186            - For sync functions, the decorator returns a synchronous wrapper.
187        """
188        valid_types = set(get_observation_types_list(ObservationTypeLiteralNoEvent))
189        if as_type is not None and as_type not in valid_types:
190            logger.warning(
191                f"Invalid as_type '{as_type}'. Valid types are: {', '.join(sorted(valid_types))}. Defaulting to 'span'."
192            )
193            as_type = "span"
194
195        function_io_capture_enabled = os.environ.get(
196            LANGFUSE_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED, "True"
197        ).lower() not in ("false", "0")
198
199        should_capture_input = (
200            capture_input if capture_input is not None else function_io_capture_enabled
201        )
202
203        should_capture_output = (
204            capture_output
205            if capture_output is not None
206            else function_io_capture_enabled
207        )
208
209        def decorator(func: F) -> F:
210            return (
211                self._async_observe(
212                    func,
213                    name=name,
214                    as_type=as_type,
215                    capture_input=should_capture_input,
216                    capture_output=should_capture_output,
217                    transform_to_string=transform_to_string,
218                )
219                if asyncio.iscoroutinefunction(func)
220                else self._sync_observe(
221                    func,
222                    name=name,
223                    as_type=as_type,
224                    capture_input=should_capture_input,
225                    capture_output=should_capture_output,
226                    transform_to_string=transform_to_string,
227                )
228            )
229
230        """Handle decorator with or without parentheses.
231
232        This logic enables the decorator to work both with and without parentheses:
233        - @observe - Python passes the function directly to the decorator
234        - @observe() - Python calls the decorator first, which must return a function decorator
235
236        When called without arguments (@observe), the func parameter contains the function to decorate,
237        so we directly apply the decorator to it. When called with parentheses (@observe()),
238        func is None, so we return the decorator function itself for Python to apply in the next step.
239        """
240        if func is None:
241            return decorator
242        else:
243            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.2'
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.langchain', 'opentelemetry.instrumentation.replicate', 'opentelemetry.instrumentation.openai_agents', 'pydantic-ai', 'litellm', 'opentelemetry.instrumentation.mistralai', 'opentelemetry.instrumentation.anthropic', 'opentelemetry.instrumentation.openai_v2', 'opentelemetry.instrumentation.bedrock', 'opentelemetry.instrumentation.watsonx', 'opentelemetry.instrumentation.openai', 'opentelemetry.instrumentation.transformers', 'opentelemetry.instrumentation.cohere', 'langfuse-sdk', 'opentelemetry.instrumentation.sagemaker', 'strands-agents', 'opentelemetry.instrumentation.groq', 'opentelemetry.instrumentation.ollama', 'agent_framework', 'opentelemetry.instrumentation.writer', 'opentelemetry.instrumentation.together', 'opentelemetry.instrumentation.voyageai', 'openinference', 'opentelemetry.instrumentation.crewai', 'opentelemetry.instrumentation.llamaindex', 'ai', 'vllm', 'autogen-core', 'opentelemetry.instrumentation.haystack', 'haystack', 'langsmith', 'opentelemetry.instrumentation.vertexai', 'opentelemetry.instrumentation.alephalpha', 'opentelemetry.instrumentation.google_generativeai', 'opentelemetry.instrumentation.agno'})
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]