From ced27bed2e01a7b2a476ecf5d6ee74d121ee59ec Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Tue, 15 Sep 2026 11:23:01 +0200 Subject: [PATCH 1/2] docs: strengthen agent-facing README so v2 APIs are not treated as current Coding agents still use Langfuse().trace() and GET /api/public/traces after pip install langfuse. Put the current OTEL APIs, Observations/Metrics v2 links, and the 10-minute freshness SLO in the first screen of the README. Co-authored-by: Cursor --- README.md | 14 +++++++++++--- pyproject.toml | 2 +- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2b2fd9d41..602859a5d 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,19 @@ [![Discord](https://img.shields.io/discord/1111061815649124414?style=flat-square&logo=Discord&logoColor=white&label=Discord&color=%23434EE4)](https://discord.gg/7NXusRtqYU) [![YC W23](https://img.shields.io/badge/Y%20Combinator-W23-orange?style=flat-square)](https://www.ycombinator.com/companies/langfuse) +> [!IMPORTANT] +> **This is the latest Langfuse Python SDK (v4, OpenTelemetry).** The legacy v2 client API (`Langfuse()`, `trace()`, `span()`, `generation()`, `api.trace.list`) is **deprecated**. Do **not** use it for new instrumentation. +> +> **Latest Python SDK (OpenTelemetry):** `pip install langfuse`. Use `get_client()` + `start_as_current_observation` / `@observe`. Prompts/datasets/scores: the same `langfuse` package. Docs: https://langfuse.com/docs/observability/sdk/overview. Upgrade: [v2 to v3](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v2-to-v3), [v3 to v4](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4). +> +> Query traces with [Observations API v2](https://langfuse.com/docs/api-and-data-platform/features/observations-api) (`GET /api/public/v2/observations`, [API reference](https://api.reference.langfuse.com/#tag/observationsv2)), not `GET /api/public/traces` / `api.trace.list`. +> +> **Data freshness:** the only real-time path is OpenTelemetry ingestion (this SDK at `langfuse` >= 4.7.0, or any OTel exporter sending `x-langfuse-ingestion-version: 4`) combined with the [Observations API v2](https://langfuse.com/docs/api-and-data-platform/features/observations-api) and [Metrics API v2](https://langfuse.com/docs/metrics/features/metrics-api). All other GET APIs from all SDK versions can be up to 10 minutes behind. + The [Langfuse](https://langfuse.com) Python SDK covers the full platform: **observability/tracing** (OpenTelemetry-based, with OpenAI and LangChain integrations), **datasets & experiments** (offline evaluation and regression testing of prompt/model changes, including [CI via GitHub Actions](https://github.com/langfuse/experiment-action)), **LLM-as-a-judge and custom evaluations/scores**, **prompt management**, and a **full REST API client**. ## Installation -> [!IMPORTANT] -> The SDK was rewritten in v4 and released in March 2026. Refer to the [v4 migration guide](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4) for instructions on updating your code. - ``` pip install langfuse ``` @@ -52,3 +58,5 @@ langfuse.flush() - Full documentation: https://langfuse.com/docs - Machine-readable docs index (for AI agents): https://langfuse.com/llms.txt - API reference of this package: https://python.reference.langfuse.com +- REST API reference (Observations API v2, Metrics API v2, Scores API v3): https://api.reference.langfuse.com +- Data freshness and real-time ingestion: https://langfuse.com/docs/compatibility#faq-delay diff --git a/pyproject.toml b/pyproject.toml index 4475c24c0..74b3ddfc8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "langfuse" version = "4.15.2" -description = "Langfuse Python SDK - LLM observability/tracing, datasets, experiments, LLM-as-a-judge evaluation, and prompt management" +description = "Langfuse Python SDK (v4, OpenTelemetry) - tracing via get_client() / start_as_current_observation, plus datasets, experiments, LLM-as-a-judge evaluation, and prompt management" readme = "README.md" authors = [{ name = "langfuse", email = "developers@langfuse.com" }] license = "MIT" From e96bf005ab6d1137b20a2127188aa9fc01072c5b Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Tue, 15 Sep 2026 12:12:51 +0200 Subject: [PATCH 2/2] docs: restore the v4 rewrite note and keep Langfuse() as a current constructor Keep the March 2026 migration callout in the banner, drop Langfuse() from the deprecated v2 API list, and restore the previous PyPI description. Co-authored-by: Cursor --- README.md | 4 +++- pyproject.toml | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 602859a5d..35b3bb5e7 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,9 @@ [![YC W23](https://img.shields.io/badge/Y%20Combinator-W23-orange?style=flat-square)](https://www.ycombinator.com/companies/langfuse) > [!IMPORTANT] -> **This is the latest Langfuse Python SDK (v4, OpenTelemetry).** The legacy v2 client API (`Langfuse()`, `trace()`, `span()`, `generation()`, `api.trace.list`) is **deprecated**. Do **not** use it for new instrumentation. +> The SDK was rewritten in v4 and released in March 2026. Refer to the [v4 migration guide](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4) for instructions on updating your code. +> +> **This is the latest Langfuse Python SDK (v4, OpenTelemetry).** The legacy v2 client API (`trace()`, `span()`, `generation()`, `api.trace.list`) is **deprecated**. Do **not** use it for new instrumentation. > > **Latest Python SDK (OpenTelemetry):** `pip install langfuse`. Use `get_client()` + `start_as_current_observation` / `@observe`. Prompts/datasets/scores: the same `langfuse` package. Docs: https://langfuse.com/docs/observability/sdk/overview. Upgrade: [v2 to v3](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v2-to-v3), [v3 to v4](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4). > diff --git a/pyproject.toml b/pyproject.toml index 74b3ddfc8..4475c24c0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "langfuse" version = "4.15.2" -description = "Langfuse Python SDK (v4, OpenTelemetry) - tracing via get_client() / start_as_current_observation, plus datasets, experiments, LLM-as-a-judge evaluation, and prompt management" +description = "Langfuse Python SDK - LLM observability/tracing, datasets, experiments, LLM-as-a-judge evaluation, and prompt management" readme = "README.md" authors = [{ name = "langfuse", email = "developers@langfuse.com" }] license = "MIT"