### Production Setup

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/configuration.md

Example configuration for a production environment.

```python
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
    base_url="https://cloud.langfuse.com",
    environment="production",
    release="v1.2.3",
    timeout=10,
    debug=False,
    sample_rate=1.0  # Sample all traces in production
)
```

--------------------------------

### Example: Start and Update Generation

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Demonstrates how to start a new generation, perform an LLM call, and then update the generation with its output and usage details using `start_as_current_generation` and `update_current_generation`.

```python
with langfuse.start_as_current_generation(
    name="llm-call",
    model="gpt-4",
    input={"query": "explain AI"}
) as generation:
    # Generate response...
    response = "AI is..."
    
    # Update with results
    langfuse.update_current_generation(
        output=response,
        usage_details={"prompt_tokens": 10, "completion_tokens": 50}
    )
```

--------------------------------

### Development Setup with Debug Logging

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/configuration.md

Example configuration for a development environment with debug logging enabled.

```python
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
    environment="development",
    debug=True,
    sample_rate=0.5  # Sample 50% of traces in development
)
```

--------------------------------

### Multi-Project Setup

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/INDEX.md

Examples for initializing Langfuse clients for multiple projects or using get_client.

```python
# Project A
client_a = Langfuse(public_key="pk_a", secret_key="sk_a")

# Project B  
client_b = Langfuse(public_key="pk_b", secret_key="sk_b")

# Or use get_client
from langfuse import get_client
client = get_client(public_key="pk_a")
```

--------------------------------

### Accessing Media Metadata in Observations

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/media-handling.md

Example showing how to start an observation with media and the resulting media reference structure after flushing.

```python
span = langfuse.start_observation(
    name="media-processing",
    input={"image": "/path/to/image.png"}
)

# After flushing, media is converted to reference
# {
#     "media_id": "media_...",
#     "source": "/path/to/image.png",
#     "content_type": "image/png"
# }
```

--------------------------------

### Install Langfuse Python SDK

Source: https://github.com/langfuse/langfuse-python/blob/main/README.md

Install the Langfuse Python SDK using pip. This command installs the latest version of the library.

```bash
pip install langfuse
```

--------------------------------

### TextPromptClient.compile example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/types.md

Example of compiling a TextPromptClient instance with user input and context.

```python
prompt = TextPromptClient(...)  # Retrieved from Langfuse
compiled = prompt.compile(user_input="hello", context="greeting")
```

--------------------------------

### ChatPromptClient.compile example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/types.md

Example of compiling a ChatPromptClient instance with system instructions and a user query.

```python
prompt = ChatPromptClient(...)  # Retrieved from Langfuse
messages = prompt.compile(
    system_instruction=[{"role": "system", "content": "You are helpful"}],
    user_query="What is AI?"
)
```

--------------------------------

### start_as_current_observation example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example usage of `start_as_current_observation` as a context manager.

```python
with parent.start_as_current_observation(name="child-operation") as child:
    # Child is now the current observation
    # Any nested operations will have child as parent
    pass
```

--------------------------------

### create_event Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Example demonstrating how to create an event using `create_event`.

```python
from langfuse.types import TraceContext

trace_context = TraceContext(trace_id="my-trace-id")
event = langfuse.create_event(
    trace_context=trace_context,
    name="user-action",
    input={"action": "button-click"},
)
```

--------------------------------

### start_observation Examples

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Examples demonstrating how to create a basic span and a generation observation using the `start_observation` method.

```python
# Create a basic span
span = langfuse.start_observation(name="my-operation")

# Create a generation observation with model details
generation = langfuse.start_observation(
    name="llm-call",
    as_type="generation",
    model="gpt-4",
    input={"prompt": "explain machine learning"},
    model_parameters={"temperature": 0.7},
)
```

--------------------------------

### end method example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of how to start an observation and then call the `end` method.

```python
span = langfuse.start_observation(name="operation")
# ... do work ...
span.end()
```

--------------------------------

### LocalExperimentItem Usage Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/experiments-and-evaluation.md

Example of how to define a list of LocalExperimentItem objects.

```python
items: List[LocalExperimentItem] = [
    {
        "input": "What is the capital of France?",
        "expected_output": "Paris",
        "metadata": {"difficulty": "easy", "category": "geography"}
    },
    {
        "input": "Summarize this article: ...",
        "expected_output": "Expected summary...",
        "metadata": {"difficulty": "hard", "category": "summarization"}
    },
]
```

--------------------------------

### Prompts

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/api-client.md

Examples for getting, listing, and creating text and chat prompts using the Langfuse API client.

```python
# Get prompt
prompt = langfuse.api.prompts.get(name="my-prompt")

# List prompts
prompts = langfuse.api.prompts.list()

# Create text prompt
prompt = langfuse.api.prompts.create(
    name="greeting",
    prompt="Hello {{name}}!",
    is_active=True
)

# Create chat prompt
prompt = langfuse.api.prompts.create(
    name="conversation",
    prompt=[
        {"role": "system", "content": "You are helpful"},
        {"role": "user", "content": "{{user_input}}"}
    ],
    is_active=True
)
```

--------------------------------

### Setup And Quality Commands

Source: https://github.com/langfuse/langfuse-python/blob/main/AGENTS.md

Commands for setting up the development environment and running quality checks.

```bash
uv sync --locked
uv run pre-commit install
uv run --frozen ruff check .
uv run --frozen ruff format .
uv run --frozen mypy langfuse --no-error-summary
bash scripts/codex/quick-check.sh
```

--------------------------------

### get_client usage

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/decorators-and-utilities.md

Demonstrates how to use `get_client` for single and multi-project setups.

```python
from langfuse import get_client

# Single project usage
client = get_client()

# Multi-project usage
client_a = get_client(public_key="project_a_key")
client_b = get_client(public_key="project_b_key")
```

--------------------------------

### Basic Setup

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/configuration.md

Basic Langfuse client initialization using environment variables or explicit parameters.

```python
from langfuse import Langfuse

# Using environment variables
langfuse = Langfuse()

# Or explicit parameters
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
)
```

--------------------------------

### Sessions

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/api-client.md

Examples for listing and getting sessions using the Langfuse API client.

```python
# List sessions
sessions = langfuse.api.sessions.list()

# Get specific session
session = langfuse.api.sessions.get(session_id="session-id")
```

--------------------------------

### start_as_current_observation Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Examples demonstrating how to use `start_as_current_observation` as a context manager and with nested spans.

```python
# Using as a context manager
with langfuse.start_as_current_observation(name="process-request") as span:
    # Code here runs within the span context
    response = process_data()
    span.update(output=response)

# Nested spans automatically establish parent-child relationships
with langfuse.start_as_current_observation(name="parent-operation") as parent:
    with parent.start_as_current_observation(name="child-operation") as child:
        # child automatically has parent as its parent span
        pass
```

--------------------------------

### Datasets

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/api-client.md

Examples for listing, getting, creating, and deleting datasets using the Langfuse API client.

```python
# List datasets
datasets = langfuse.api.datasets.list()

# Get specific dataset
dataset = langfuse.api.datasets.get(dataset_id="dataset-id")

# Create dataset
new_dataset = langfuse.api.datasets.create(
    name="my-dataset",
    description="Test dataset"
)

# Delete dataset
langfuse.api.datasets.delete(dataset_id="dataset-id")
```

--------------------------------

### ParsedMediaReference Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/types.md

An example of creating an instance of ParsedMediaReference.

```python
from langfuse.types import ParsedMediaReference

media_ref = ParsedMediaReference(
    media_id="media-123",
    source="/path/to/image.png",
    content_type="image/png"
)
```

--------------------------------

### Installation

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/openai-integration.md

Command to install Langfuse and OpenAI Python packages.

```bash
pip install langfuse openai
```

--------------------------------

### Install Dependencies

Source: https://github.com/langfuse/langfuse-python/blob/main/CONTRIBUTING.md

Installs project dependencies using `uv`.

```bash
uv sync --locked
```

--------------------------------

### Multi-Project Setup

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/decorators-and-utilities.md

Illustrates how to route operations to different Langfuse projects in a multi-project environment.

```python
@observe()  # Uses current public_key context
def operation_a():
    return "result_a"

# Explicitly specify project
from langfuse._client.get_client import _set_current_public_key

with _set_current_public_key("project-b-public-key"):
    operation_a()  # Routed to project B's Langfuse client
```

--------------------------------

### Variable Reference

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/configuration.md

Example environment variables for configuring the Langfuse SDK.

```bash
# Authentication
export LANGFUSE_PUBLIC_KEY="your-public-key"
export LANGFUSE_SECRET_KEY="your-secret-key"

# Server Configuration
export LANGFUSE_BASE_URL="https://your-langfuse-instance.com"
export LANGFUSE_TIMEOUT="10"

# Tracing Configuration
export LANGFUSE_DEBUG="false"
export LANGFUSE_TRACING_ENABLED="true"
export LANGFUSE_FLUSH_AT="512"
export LANGFUSE_FLUSH_INTERVAL="5"

# Release and Environment
export LANGFUSE_RELEASE="1.0.0"
export LANGFUSE_TRACING_ENVIRONMENT="production"

# Media Upload
export LANGFUSE_MEDIA_UPLOAD_THREAD_COUNT="1"

# Sampling
export LANGFUSE_SAMPLE_RATE="1.0"

# Observability Decorator
export LANGFUSE_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED="true"
```

--------------------------------

### Media

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/api-client.md

Examples for getting media upload URLs, uploading files, and retrieving media using the Langfuse API client.

```python
# Get media upload URL
upload_response = langfuse.api.media.upload_url(
    file_name="image.png",
    file_size=1024,
    content_type="image/png"
)

# Upload file using the provided URL
import requests
with open("image.png", "rb") as f:
    requests.put(upload_response.upload_url, data=f)

# Retrieve media
media = langfuse.api.media.get(media_id="media-id")
```

--------------------------------

### EvaluatorInputs Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/batch-evaluation.md

Example of creating an `EvaluatorInputs` instance from trace data.

```python
from langfuse import EvaluatorInputs

# From trace data
evaluator_inputs = EvaluatorInputs(
    input=trace.input,
    output=trace.output,
    expected_output=expected_response,
    metadata={"user_id": trace.user_id, "tags": trace.tags}
)
```

--------------------------------

### Langfuse Configuration with OpenAI

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/openai-integration.md

Example showing how to initialize Langfuse normally, and OpenAI calls will be automatically tracked.

```python
from langfuse import Langfuse
from langfuse.openai import openai

# Initialize Langfuse normally
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
)

# Use OpenAI as normal - tracking is automatic
response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
)
```

--------------------------------

### Self-Hosted Instance

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/configuration.md

Example configuration for connecting to a self-hosted Langfuse instance.

```python
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
    base_url="https://langfuse.mycompany.com",
)
```

--------------------------------

### Example: Generate Trace IDs

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Demonstrates how to generate both random and deterministic trace IDs using `Langfuse.create_trace_id`.

```python
# Generate random trace ID
trace_id = Langfuse.create_trace_id()

# Generate deterministic trace ID
trace_id = Langfuse.create_trace_id(seed="user-123")
```

--------------------------------

### evaluate_batch Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/batch-evaluation.md

Example demonstrating how to use `client.evaluate_batch` with a mapper function and an evaluator function.

```python
from langfuse import EvaluatorInputs

# Define mapper
def map_trace(*, item, **kwargs) -> EvaluatorInputs:
    return EvaluatorInputs(
        input=item.input,
        output=item.output,
        expected_output=None,
        metadata={"trace_id": item.id}
    )

# Define evaluators
def eval_accuracy(*, evaluator_inputs: EvaluatorInputs, **kwargs):
    # Calculate accuracy
    score = len(evaluator_inputs.output) > 10
    return {
        "name": "has_content",
        "value": score,
        "data_type": "BOOLEAN"
    }
```

--------------------------------

### MaskFunction Example Implementation

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/types.md

An example demonstrating how to implement a custom MaskFunction to mask PII and use it with the Langfuse client.

```python
from langfuse.types import MaskFunction

def mask_pii(*, data: Any, **kwargs) -> Any:
    # Custom masking logic
    if isinstance(data, dict):
        if "api_key" in data:
            data["api_key"] = "***MASKED***"
    return data

# Use with client
langfuse = Langfuse(mask=mask_pii)
```

--------------------------------

### Run Experiment on Dataset

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/experiments-and-evaluation.md

Example of running an experiment using a dataset from Langfuse.

```python
# Get dataset from Langfuse
dataset = langfuse.get_dataset("dataset-name")

# Define task
def my_task(*, item, **kwargs):
    return process_item(item["input"])

# Define evaluator
def my_evaluator(*, output, expected_output=None, **kwargs):
    if not expected_output:
        return Evaluation(name="accuracy", value=0)
    
    is_correct = output == expected_output
    return Evaluation(
        name="accuracy",
        value=1.0 if is_correct else 0.0
    )

# Run experiment
experiment = langfuse.run_experiment(
    name="my-experiment",
    dataset=dataset,
    task=my_task,
    evaluators=[my_evaluator],
)

# Access results
print(f"Accuracy: {experiment.summary['accuracy']}")
```

--------------------------------

### start_observation example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of how to create a child observation from a parent span.

```python
# Create a parent span
parent = langfuse.start_observation(name="parent-operation")

# Create a child observation (becomes child of parent automatically)
child = parent.start_observation(
    name="child-operation",
    as_type="generation",
    model="gpt-4"
)
```

--------------------------------

### Include Comments for Context

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/experiments-and-evaluation.md

Example showing how to provide explanations for evaluation results using comments.

```python
# Good
Evaluation(
    name="accuracy",
    value=0.85,
    comment="5 out of 8 questions answered correctly"
)

# Less helpful
Evaluation(name="accuracy", value=0.85)
```

--------------------------------

### Codex Cloud Setup Script

Source: https://github.com/langfuse/langfuse-python/blob/main/CONTRIBUTING.md

Sets the setup script for the Codex cloud environment.

```bash
bash scripts/codex/setup.sh
```

--------------------------------

### With start_as_current_observation

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/openai-integration.md

Example showing how to use `start_as_current_observation` with the Langfuse OpenAI integration to establish nested spans.

```python
from langfuse import Langfuse
from langfuse.openai import openai

langfuse = Langfuse()

with langfuse.start_as_current_observation(
    name="answer-generation",
    as_type="generation"
) as span:
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "What is AGI?"}],
    )
    result = response.choices[0].message.content
    span.update(output=result)
    
# Nested spans automatically established
```

--------------------------------

### Run Experiment on Local Data

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/experiments-and-evaluation.md

Example of running an experiment using local data.

```python
items = [
    {"input": "Hello", "expected_output": "Hi"},
    {"input": "Goodbye", "expected_output": "Bye"},
]

experiment = langfuse.run_experiment(
    name="local-experiment",
    data=items,
    task=my_task,
    evaluators=[my_evaluator],
)
```

--------------------------------

### Synchronous Task Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/experiments-and-evaluation.md

Example of a synchronous task function that processes input and returns output.

```python
def task_function(*, item, **kwargs) -> str:
    """Simple task that processes input and returns output"""
    prompt = item["input"]
    response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content
```

--------------------------------

### Start a Guardrail Observation

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of how to start a guardrail observation using the Langfuse client.

```python
guardrail = langfuse.start_observation(
    name="safety-check",
    as_type="guardrail"
)
```

--------------------------------

### Async Function Tracing

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/decorators-and-utilities.md

Example showing how to apply the `@observe()` decorator to an asynchronous function.

```python
@observe()
async def fetch_data(url):
    # Async function is automatically traced
    response = await http_client.get(url)
    return response.json()
```

--------------------------------

### Azure OpenAI Support

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/openai-integration.md

Example of using Azure OpenAI client with automatic Langfuse tracking.

```python
from langfuse.openai import AzureOpenAI

# Use Azure OpenAI with automatic Langfuse tracking
client = AzureOpenAI(
    api_key="your-azure-api-key",
    api_version="2024-02-15-preview",
    azure_endpoint="https://your-resource.openai.azure.com/",
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}],
)

# Automatically logged to Langfuse
```

--------------------------------

### Multi-Project Setup

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/configuration.md

Shows how to initialize Langfuse for multiple projects using separate instances or by leveraging get_client for automatic management.

```python
# Project A
langfuse_a = Langfuse(public_key="pk_project_a", secret_key="sk_a")

# Project B
langfuse_b = Langfuse(public_key="pk_project_b", secret_key="sk_b")

# Or use get_client for automatic management
from langfuse import get_client

client_a = get_client(public_key="pk_project_a")
client_b = get_client(public_key="pk_project_b")
```

--------------------------------

### Traces

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/api-client.md

Examples for getting, listing, and deleting traces using the Langfuse API client.

```python
# Get trace details
trace = langfuse.api.trace.get(trace_id="my-trace-id")

# List traces
traces = langfuse.api.trace.list(limit=100)

# Delete trace
langfuse.api.trace.delete(trace_id="my-trace-id")
```

--------------------------------

### Archiving Datasets

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/datasets-and-errors.md

Example of listing active datasets and a note on archiving.

```python
# List only active datasets
active = langfuse.api.datasets.list(status="ACTIVE")

# Archive a dataset (no direct method, use description or deletion)
# Typically done through UI
```

--------------------------------

### Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Demonstrates how to initialize the Langfuse client and create a trace with nested generation spans, including updating generation details and scoring.

```python
from langfuse import Langfuse

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

# Create a trace span
with langfuse.start_as_current_observation(name="process-query") as span:
    # Your application code here
    
    # Create a nested generation span for an LLM call
    with span.start_as_current_generation(
        name="generate-response",
        model="gpt-4",
        input={"query": "Tell me about AI"},
        model_parameters={"temperature": 0.7, "max_tokens": 500}
    ) as generation:
        # Generate response here
        response = "AI is a field of computer science..."
        
        generation.update(
            output=response,
            usage_details={"prompt_tokens": 10, "completion_tokens": 50},
            cost_details={"total_cost": 0.0023}
        )
        
        # Score the generation
        generation.score(name="relevance", value=0.95, data_type="NUMERIC")
```

--------------------------------

### Retriever with Document

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/media-handling.md

Example of using documents as input within a retriever observation type.

```python
with langfuse.start_as_current_observation(
    name="document-retrieval",
    as_type="retriever",
    input={
        "query": "annual reports",
        "documents": [
            "/path/to/report.pdf",
            "/path/to/summary.pdf"
        ]
    }
) as retriever:
    results = retrieve_documents()
    retriever.update(output={"results": results})
```

--------------------------------

### Generation with Image Input

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/media-handling.md

Example of using an image as input within a generation observation type.

```python
from langfuse import Langfuse

langfuse = Langfuse()

with langfuse.start_as_current_generation(
    name="gpt-vision-call",
    model="gpt-4-vision",
    input={
        "image": "/path/to/image.jpg",
        "question": "Describe this image"
    }
) as gen:
    # Call vision API
    response = call_vision_api(image_path)
    
    gen.update(
        output={"description": response}
    )
```

--------------------------------

### Event with Screenshot

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/media-handling.md

Example of including a screenshot as input within an event observation type.

```python
event = langfuse.create_event(
    trace_context=trace_context,
    name="ui-interaction",
    input={
        "action": "button_click",
        "screenshot": "/path/to/screenshot.png"
    }
)
```

--------------------------------

### Dataset Client Operations

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/datasets-and-errors.md

Examples of how to use the Langfuse API client to list, get, create, and delete datasets.

```python
langfuse = Langfuse()

# List all datasets
datasets = langfuse.api.datasets.list()

# Get specific dataset
dataset = langfuse.api.datasets.get(dataset_id="dataset-id")

# Create new dataset
dataset = langfuse.api.datasets.create(
    name="test-dataset",
    description="Test data for experiments"
)

# Delete dataset
langfuse.api.datasets.delete(dataset_id="dataset-id")
```

--------------------------------

### Dataset Run Client Operations

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/datasets-and-errors.md

Examples of how to track experiment runs on datasets, including listing, getting, and deleting runs.

```python
# List dataset runs
runs = langfuse.api.datasets.get_dataset_runs(dataset_id="dataset-id")

# Get specific run
run = langfuse.api.datasets.get_dataset_run(dataset_run_id="run-id")

# Delete run
langfuse.api.datasets.delete_dataset_run(dataset_run_id="run-id")
```

--------------------------------

### Build Documentation

Source: https://github.com/langfuse/langfuse-python/blob/main/AGENTS.md

Commands to build the project documentation using uv and pdoc.

```bash
uv build --no-sources
uv run --group docs pdoc -o docs/ --docformat google --logo "https://langfuse.com/langfuse_logo.svg" langfuse
```

--------------------------------

### Example: Set Current Trace Input/Output

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Demonstrates how to use `set_current_trace_io` to record the overall input and output for the root span of a trace.

```python
with langfuse.start_as_current_observation(name="main-trace") as trace:
    # ... do work ...
    langfuse.set_current_trace_io(
        input={"user_query": "..."},
        output={"response": "..."}
    )
```

--------------------------------

### LangfuseEvent example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseEvent` observation.

```python
event = langfuse.create_event(
    trace_context=trace_context,
    name="user-action",
    input={"action": "click"}
)
```

--------------------------------

### LangfuseSpan example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a generic `LangfuseSpan` observation.

```python
span = langfuse.start_observation(
    name="my-operation",
    as_type="span",
    input={"data": "input"},
    output={"result": "output"}
)
```

--------------------------------

### LangfuseEvaluator example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseEvaluator` observation for evaluation operations.

```python
evaluator = langfuse.start_observation(
    name="quality-check",
    as_type="evaluator",
    input={"output": response}
)
```

--------------------------------

### LangfuseEmbedding example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseEmbedding` observation for embedding operations.

```python
embedding = langfuse.start_observation(
    name="embed-text",
    as_type="embedding",
    model="text-embedding-3-small"
)
```

--------------------------------

### LangfuseRetriever example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseRetriever` observation for retrieval operations.

```python
retriever = langfuse.start_observation(
    name="document-retrieval",
    as_type="retriever",
    input={"query": "search term"}
)
```

--------------------------------

### With start_observation

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/openai-integration.md

Example demonstrating how to use `start_observation` to create a parent span, with the OpenAI call becoming a child span.

```python
from langfuse import Langfuse
from langfuse.openai import openai

langfuse = Langfuse()

# Create a parent span
parent = langfuse.start_observation(name="parent-operation")

# Make OpenAI call within parent context
response = openai.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Say hello"}],
)

# OpenAI call becomes child of parent span
parent.end()
```

--------------------------------

### LangfuseChain example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseChain` observation for chain-of-thought operations.

```python
chain = langfuse.start_observation(
    name="processing-chain",
    as_type="chain"
)
```

--------------------------------

### Basic Function Tracing

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/decorators-and-utilities.md

Example demonstrating how to use the `@observe()` decorator for basic tracing of a synchronous function.

```python
from langfuse import observe

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

--------------------------------

### LangfuseTool example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseTool` observation for tool calls.

```python
tool = langfuse.start_observation(
    name="calculator",
    as_type="tool",
    input={"expression": "2+2"}
)
```

--------------------------------

### Accessing the API Client

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/api-client.md

Demonstrates how to initialize the Langfuse client and access its synchronous and asynchronous API clients.

```python
from langfuse import Langfuse

langfuse = Langfuse(public_key="...", secret_key="...")

# Synchronous API client
api = langfuse.api

# Asynchronous API client
async_api = langfuse.async_api
```

--------------------------------

### LangfuseAgent example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseAgent` observation for agentic operations.

```python
agent = langfuse.start_observation(
    name="agent-loop",
    as_type="agent",
    input={"task": "answer question"}
)
```

--------------------------------

### LangfuseGeneration example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of creating a `LangfuseGeneration` observation for LLM calls.

```python
generation = langfuse.start_observation(
    name="llm-call",
    as_type="generation",
    model="gpt-4",
    model_parameters={"temperature": 0.7},
    input={"prompt": "hello"},
    output={"response": "hi"}
)
```

--------------------------------

### Solution for 'No Langfuse client with public key X has been initialized'

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/datasets-and-errors.md

How to resolve the error when `get_client()` is called before initialization by ensuring the client is initialized first.

```python
# Initialize client first
langfuse_a = Langfuse(public_key="key_a", secret_key="secret_a")

# Then get it
client_a = get_client(public_key="key_a")
```

--------------------------------

### Example: Make Current Trace Public

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/langfuse-client.md

Shows how to use `set_current_trace_as_public` to enable public access to a trace without requiring authentication.

```python
with langfuse.start_as_current_observation(name="my-trace") as trace:
    # ... do work ...
    langfuse.set_current_trace_as_public()  # Make this trace publicly accessible
```

--------------------------------

### Create a Trace

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/INDEX.md

Creates a trace using `start_as_current_observation` and updates its output.

```python
with langfuse.start_as_current_observation(name="main-operation") as span:
    # Your code here
    result = process_data()
    span.update(output=result)
```

--------------------------------

### Creating and Populating a Dataset

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/datasets-and-errors.md

Example workflow for creating a new dataset and adding multiple items to it.

```python
# Create dataset
dataset = langfuse.api.datasets.create(
    name="qa-dataset",
    description="Question-answer pairs"
)

# Add items
items = [
    {"input": "What is 2+2?", "expected_output": "4"},
    {"input": "What is the capital of France?", "expected_output": "Paris"},
    {"input": "What is AI?", "expected_output": "Artificial Intelligence"}
]

for item in items:
    langfuse.api.dataset_items.create(
        dataset_id=dataset.id,
        input=item["input"],
        expected_output=item["expected_output"],
        metadata={"source": "trivia"}
    )
```

--------------------------------

### BatchEvaluationResult Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/batch-evaluation.md

Example demonstrating how to access and print statistics from a `BatchEvaluationResult` object.

```python
result = langfuse.evaluate_batch(...)

for evaluator_name, stats in result.stats.items():
    print(f"{evaluator_name}:")
    print(f"  Evaluated: {stats.evaluated_count}")
    print(f"  Errors: {stats.error_count}")
    if stats.error_messages:
        print(f"  Errors: {stats.error_messages}")
```

--------------------------------

### set_trace_as_public example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of how to make an entire trace public from a nested observation.

```python
with langfuse.start_as_current_observation(name="main") as main_span:
    with main_span.start_as_current_observation(name="child") as child:
        child.set_trace_as_public()  # Makes the entire trace public
```

--------------------------------

### set_trace_io example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of how to set the input/output of the root trace from a nested observation.

```python
with langfuse.start_as_current_observation(name="main") as main_span:
    with main_span.start_as_current_observation(name="child") as child:
        # Set input/output of the root trace
        child.set_trace_io(
            input={"query": "..."},
            output={"response": "..."}
        )
```

--------------------------------

### Troubleshooting: Ensure Langfuse client is initialized

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/openai-integration.md

Code snippet demonstrating the correct order of initialization for Langfuse and OpenAI to ensure tracking.

```python
from langfuse import Langfuse
from langfuse.openai import openai
   
langfuse = Langfuse(public_key="...", secret_key="...")
# Now use openai - it will be tracked
```

--------------------------------

### Evaluation Examples

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/experiments-and-evaluation.md

Demonstrates how to create different types of evaluation results (numeric, categorical, boolean, with metadata).

```python
from langfuse import Evaluation

# Numeric evaluation
result = Evaluation(
    name="accuracy",
    value=0.95,
    comment="Correct answer",
    data_type="NUMERIC"
)

# Categorical evaluation
result = Evaluation(
    name="sentiment",
    value="positive",
    comment="Response expresses positive sentiment",
    data_type="CATEGORICAL"
)

# Boolean evaluation
result = Evaluation(
    name="is_safe",
    value=True,
    comment="Response passes safety checks",
    data_type="BOOLEAN"
)

# With metadata
result = Evaluation(
    name="complexity",
    value=0.78,
    comment="Moderate complexity",
    metadata={"model": "gpt-4", "temperature": 0.7}
)
```

--------------------------------

### propagate_attributes Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/decorators-and-utilities.md

Example demonstrating how to use `propagate_attributes` to propagate trace context.

```python
from langfuse import propagate_attributes
from langfuse.types import TraceContext

# Create a trace in one context
trace = langfuse.start_observation(name="root")

# Propagate it to another context (e.g., spawned thread/task)
with propagate_attributes(trace_context=TraceContext(trace_id=trace.trace_id)):
    # Operations here are part of the same trace
    child = langfuse.start_observation(name="child")  # Has trace as parent
```

--------------------------------

### Enabling Debug Logging for Upload Status

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/media-handling.md

Example demonstrating how to enable debug logging to monitor the status of background media uploads.

```python
import logging
from langfuse.logger import langfuse_logger

# Enable logging to see upload status
langfuse_logger.setLevel(logging.DEBUG)

span = langfuse.start_observation(
    name="operation",
    input={"large_file": "/path/to/50mb-file.pdf"}
)

# Upload happens in background thread
# Check logs for upload status
```

--------------------------------

### score_trace example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example of how to score an entire trace within a trace context.

```python
# Within a trace context
with langfuse.start_as_current_observation(name="main-trace") as trace:
    # ... do work ...
    
    # Score the entire trace
    trace.score_trace(name="success", value=True, data_type="BOOLEAN")
```

--------------------------------

### Asynchronous Task Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/experiments-and-evaluation.md

Example of an asynchronous task function for concurrent execution.

```python
async def async_task(*, item, **kwargs) -> str:
    """Async task for concurrent execution"""
    prompt = item["input"]
    response = await openai.AsyncOpenAI().chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content
```

--------------------------------

### Sampling Configuration (10% Sample Rate)

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/configuration.md

Example of setting a sample_rate of 0.1 to sample 10% of traces, useful for reducing data volume and costs in high-traffic applications.

```python
# Sample 10% of traces (useful for cost reduction)
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
    sample_rate=0.1,
)
```

--------------------------------

### create_event example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/observations.md

Example usage of `create_event` to add a checkpoint event within an operation.

```python
with span.start_as_current_observation(name="operation") as op:
    event = op.create_event(name="checkpoint", input={"milestone": "reached"})
```

--------------------------------

### Configuring Batching for Media Uploads

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/media-handling.md

Setting `flush_at` and `flush_interval` parameters to batch media uploads more efficiently.

```python
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
    flush_at=512,      # Batch before flushing
    flush_interval=5,  # Flush every 5 seconds
)
```

--------------------------------

### Synchronous Evaluator Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/batch-evaluation.md

Example of a synchronous evaluator function that calculates a relevance score.

```python
def evaluate_relevance(*, evaluator_inputs: EvaluatorInputs, **kwargs) -> Evaluation:
    output = evaluator_inputs.output
    expected = evaluator_inputs.expected_output
    
    # Calculate relevance score
    score = calculate_similarity(output, expected)
    
    return {
        "name": "relevance",
        "value": score,
        "data_type": "NUMERIC",
        "comment": f"Output similarity to expected: {score}"
    }
```

--------------------------------

### Using the Async API

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/api-client.md

Shows how to use the asynchronous version of the Langfuse API with `async/await` for operations like fetching traces.

```python
import asyncio

async def fetch_traces():
    traces = await langfuse.async_api.trace.list(limit=10)
    for trace in traces:
        print(f"Trace: {trace.id}")

asyncio.run(fetch_traces())
```

--------------------------------

### Run SDK Reference Locally

Source: https://github.com/langfuse/langfuse-python/blob/main/CONTRIBUTING.md

Command to serve the SDK reference documentation locally for viewing.

```sh
uv run --group docs pdoc --docformat google --logo "https://langfuse.com/langfuse_logo.svg" langfuse
```

--------------------------------

### Synchronous Mapper Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/batch-evaluation.md

Example of a synchronous mapper function that transforms trace details into `EvaluatorInputs`.

```python
def map_trace(*, item: TraceWithFullDetails, **kwargs) -> EvaluatorInputs:
    return EvaluatorInputs(
        input=item.input,
        output=item.output,
        expected_output=None,
        metadata={"trace_id": item.id, "user": item.user_id}
    )
```

--------------------------------

### Media Upload Configuration

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/media-handling.md

Example of configuring media upload behavior, specifically setting the number of concurrent upload threads.

```python
langfuse = Langfuse(
    public_key="pk_...",
    secret_key="sk_...",
    media_upload_thread_count=3  # Number of concurrent uploads (default: 1)
)
```

--------------------------------

### TraceContext Example Usage

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/types.md

Examples of creating and using a TraceContext with and without a parent span ID when creating an observation.

```python
from langfuse.types import TraceContext

# Create trace context
context = TraceContext(trace_id="my-trace-id")

# With parent span
context = TraceContext(
    trace_id="my-trace-id",
    parent_span_id="parent-span-id"
)

# Use in observation
event = langfuse.create_event(
    trace_context=context,
    name="checkpoint"
)
```

--------------------------------

### Asynchronous Mapper Example

Source: https://github.com/langfuse/langfuse-python/blob/main/_autodocs/batch-evaluation.md

Example of an asynchronous mapper function that can perform async processing before returning `EvaluatorInputs`.

```python
async def map_trace_async(*, item: TraceWithFullDetails, **kwargs) -> EvaluatorInputs:
    # Could do async processing here
    processed_output = await some_async_transformation(item.output)
    
    return EvaluatorInputs(
        input=item.input,
        output=processed_output,
        expected_output=None,
        metadata={"trace_id": item.id}
    )
```