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