# langfuse/langfuse-python architecture

> Architecture diagram of the GitHub repository langfuse/langfuse-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/langfuse/langfuse-python
- Repository: https://github.com/langfuse/langfuse-python

## Overview

#### Overview

Langfuse Python SDK is a client library for Langfuse observability and evaluation services. The current v4 path is OpenTelemetry-based: application code obtains a client with `get_client()`, creates nested observations or uses `@observe`, and flushes emitted data. The package also covers prompts, datasets, experiments, scores, media, integrations, and REST API access.

#### Core components

- **Public SDK surface — `langfuse/__init__.py`**  
  Exposes the package-level entry points used by application code, including the documented `get_client()` flow. Runtime configuration is supplied externally, including `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and `LANGFUSE_BASE_URL`.

- **OpenTelemetry client and instrumentation — `langfuse/_client`**  
  Implements client lifecycle, observation/span handling, decorators, attribute propagation, filtering, serialization, and span export/processing. This is the main runtime instrumentation area for `start_as_current_observation`, nested spans/generations, and flushing telemetry to Langfuse.

- **Asynchronous work management — `langfuse/_task_manager`**  
  Owns process-local work queues and consumers for media uploads and score ingestion. It is an implementation area for deferred background submission rather than a durable repository-backed store.

- **Generated REST API — `langfuse/api`**  
  Provides the broad service API surface, organized into resource clients such as observations, ingestion, prompts, datasets, scores, sessions, projects, and health. Resource-specific `client.py`, `raw_client.py`, and `types` packages represent the public API operations and request/response models. `langfuse/api/core` supplies shared HTTP, serialization, error, pagination, and request infrastructure.

- **Evaluation and experiment workflows — `langfuse/experiment.py` and `langfuse/batch_evaluation.py`**  
  Contains higher-level support for experiments, batch evaluation, and regression-style evaluation workflows described by the README. These complement the lower-level generated API and score models.

- **Provider integrations — `langfuse/openai.py` and `langfuse/langchain`**  
  Adapts OpenAI and LangChain usage to the SDK’s observability model. `langfuse/langchain/CallbackHandler.py` is the main LangChain callback implementation; application code and provider libraries remain external actors.

- **Additional domain helpers — `langfuse/media.py` and `langfuse/model.py`**  
  Provides package-level helpers for media and model-related functionality, alongside corresponding generated API resources.

#### Relationships

Application code calls the package entry points in `langfuse/__init__.py` or uses the OpenAI/LangChain integration modules. The client/instrumentation subsystem owns observation context and export processing; its emitted telemetry is sent to the external Langfuse service through the SDK’s HTTP/API infrastructure. The task manager owns deferred media and score submission work.

Higher-level experiment and evaluation helpers use the SDK’s domain/API capabilities, while `langfuse/api` remains the general REST client boundary for callers needing direct resource operations. `langfuse/api/legacy` is a separate compatibility surface for deprecated v1-style APIs; the README identifies the older tracing client API as deprecated for new instrumentation.

#### State and external boundaries

Runtime buffering and queues are process-local implementation areas visible under the client and task-manager directories. No repository-local durable database is evident in the supplied tree. The main external boundary is the Langfuse HTTP service; application code, OpenAI, LangChain, and other model providers supply the workload being instrumented.

Main entry points: [`langfuse/api`](https://github.com/langfuse/langfuse-python/tree/main/langfuse/api) (Generated REST API), [`langfuse/_client`](https://github.com/langfuse/langfuse-python/tree/main/langfuse/_client) (OTel client and instrumentation), [`langfuse/openai.py`](https://github.com/langfuse/langfuse-python/blob/main/langfuse/openai.py) (OpenAI integration), [`langfuse/langchain`](https://github.com/langfuse/langfuse-python/tree/main/langfuse/langchain) (LangChain integration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_public_sdk["Public SDK surface<br/>package entry point<br/>[__init__.py]"]
  node_otel_client["OTel client and instrumentation<br/>runtime instrumentation"]
  node_task_manager["Task manager<br/>background work manager"]
end

subgraph group_api_domain["API and domain"]
  node_rest_api["Generated REST API<br/>REST client"]
  node_legacy_api["Legacy API<br/>compatibility API"]
  node_evaluation["Evaluation workflows<br/>experiment and evaluation support<br/>[experiment.py]"]
  node_batch_evaluation["Batch evaluation"]
  node_media["Media helpers<br/>domain helper<br/>[media.py]"]
  node_model["Model helpers<br/>domain helper<br/>[model.py]"]
end

subgraph group_integrations["Integrations"]
  node_openai_integration["OpenAI integration<br/>provider integration<br/>[openai.py]"]
  node_langchain_integration["LangChain integration<br/>provider integration"]
end

node_application(("Application code<br/>external consumer"))
node_langfuse_service{{"Langfuse service<br/>external HTTP service"}}
node_openai{{"OpenAI<br/>external provider"}}
node_langchain{{"LangChain<br/>external provider"}}

node_application -->|"calls"| node_public_sdk
node_public_sdk -->|"provides access to"| node_otel_client
node_application -->|"uses"| node_openai_integration
node_application -->|"uses"| node_langchain_integration
node_openai_integration -->|"adapts to"| node_otel_client
node_langchain_integration -->|"adapts to"| node_otel_client
node_openai -->|"supplies workload to"| node_openai_integration
node_langchain -->|"supplies workload to"| node_langchain_integration
node_otel_client -->|"exports telemetry through"| node_rest_api
node_otel_client -->|"sends telemetry to"| node_langfuse_service
node_task_manager -->|"submits deferred work through"| node_rest_api
node_rest_api -->|"calls"| node_langfuse_service
node_evaluation -->|"uses"| node_rest_api
node_batch_evaluation -->|"uses"| node_rest_api
node_media -->|"uses"| node_rest_api
node_model -->|"uses"| node_rest_api

click node_public_sdk "https://github.com/langfuse/langfuse-python/blob/main/langfuse/__init__.py"
click node_otel_client "https://github.com/langfuse/langfuse-python/tree/main/langfuse/_client"
click node_task_manager "https://github.com/langfuse/langfuse-python/tree/main/langfuse/_task_manager"
click node_rest_api "https://github.com/langfuse/langfuse-python/tree/main/langfuse/api"
click node_legacy_api "https://github.com/langfuse/langfuse-python/tree/main/langfuse/api/legacy"
click node_evaluation "https://github.com/langfuse/langfuse-python/blob/main/langfuse/experiment.py"
click node_batch_evaluation "https://github.com/langfuse/langfuse-python/blob/main/langfuse/batch_evaluation.py"
click node_media "https://github.com/langfuse/langfuse-python/blob/main/langfuse/media.py"
click node_model "https://github.com/langfuse/langfuse-python/blob/main/langfuse/model.py"
click node_openai_integration "https://github.com/langfuse/langfuse-python/blob/main/langfuse/openai.py"
click node_langchain_integration "https://github.com/langfuse/langfuse-python/tree/main/langfuse/langchain"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_sdk,node_otel_client,node_task_manager toneBlue
class node_rest_api,node_legacy_api,node_evaluation,node_batch_evaluation,node_media,node_model toneAmber
class node_openai_integration,node_langchain_integration toneMint
class node_application,node_langfuse_service,node_openai,node_langchain toneNeutral
```

## Components

### Runtime

Instrumentation and deferred work management.

- [Public SDK surface](https://github.com/langfuse/langfuse-python/blob/main/langfuse/__init__.py): package entry point · `langfuse/__init__.py`
- [OTel client and instrumentation](https://github.com/langfuse/langfuse-python/tree/main/langfuse/_client): runtime instrumentation · Manages observation context, telemetry processing, and flushing. · `langfuse/_client`
- [Task manager](https://github.com/langfuse/langfuse-python/tree/main/langfuse/_task_manager): background work manager · Queues deferred media uploads and score submissions. · `langfuse/_task_manager`

### API and domain

REST access and higher-level workflows.

- [Generated REST API](https://github.com/langfuse/langfuse-python/tree/main/langfuse/api): REST client · Provides resource clients and shared HTTP infrastructure. · `langfuse/api`
- [Legacy API](https://github.com/langfuse/langfuse-python/tree/main/langfuse/api/legacy): compatibility API · Separate deprecated v1-style compatibility surface. · `langfuse/api/legacy`
- [Evaluation workflows](https://github.com/langfuse/langfuse-python/blob/main/langfuse/experiment.py): experiment and evaluation support · `langfuse/experiment.py`
- [Batch evaluation](https://github.com/langfuse/langfuse-python/blob/main/langfuse/batch_evaluation.py): batch evaluation support · `langfuse/batch_evaluation.py`
- [Media helpers](https://github.com/langfuse/langfuse-python/blob/main/langfuse/media.py): domain helper · `langfuse/media.py`
- [Model helpers](https://github.com/langfuse/langfuse-python/blob/main/langfuse/model.py): domain helper · `langfuse/model.py`

### Integrations

Provider-specific observability adapters.

- [OpenAI integration](https://github.com/langfuse/langfuse-python/blob/main/langfuse/openai.py): provider integration · `langfuse/openai.py`
- [LangChain integration](https://github.com/langfuse/langfuse-python/tree/main/langfuse/langchain): provider integration · `langfuse/langchain`

### Other components

- **Application code**: external consumer · Supplies workloads and uses the SDK.
- **Langfuse service**: external HTTP service
- **OpenAI**: external provider
- **LangChain**: external provider

## Connections

- Application code → Public SDK surface: calls
- Public SDK surface → OTel client and instrumentation: provides access to
- Application code → OpenAI integration: uses
- Application code → LangChain integration: uses
- OpenAI integration → OTel client and instrumentation: adapts to
- LangChain integration → OTel client and instrumentation: adapts to
- OpenAI → OpenAI integration: supplies workload to
- LangChain → LangChain integration: supplies workload to
- OTel client and instrumentation → Generated REST API: exports telemetry through
- OTel client and instrumentation → Langfuse service: sends telemetry to
- Task manager → Generated REST API: submits deferred work through
- Generated REST API → Langfuse service: calls
- Evaluation workflows → Generated REST API: uses
- Batch evaluation → Generated REST API: uses
- Media helpers → Generated REST API: uses
- Model helpers → Generated REST API: uses
