From 063607f6460125e1e72e5805bce9893f95f1326e Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Tue, 15 Sep 2026 11:23:02 +0200 Subject: [PATCH 1/3] docs: strengthen agent-facing deprecation banner on v3-stable Unpinned pip install langfuse installs v4. Make the v3 README state that this major is not current, name the latest OTEL APIs, and repeat the Observations/Metrics v2 freshness SLO. Co-authored-by: Cursor --- README.md | 25 +++++++++++++++++-------- pyproject.toml | 2 +- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 94dc1c1d3..8cb2fe18c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![Langfuse GitHub Banner](https://langfuse.com/langfuse_logo_white.png) -# Langfuse Python SDK +# Langfuse Python SDK (legacy v3) [![MIT License](https://img.shields.io/badge/License-MIT-red.svg?style=flat-square)](https://opensource.org/licenses/MIT) [![CI test status](https://img.shields.io/github/actions/workflow/status/langfuse/langfuse-python/ci.yml?style=flat-square&label=All%20tests)](https://github.com/langfuse/langfuse-python/actions/workflows/ci.yml?query=branch%3Amain) @@ -9,15 +9,24 @@ [![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) -## Installation - > [!IMPORTANT] -> The SDK was rewritten in v3 and released in June 2025. Refer to the [v3 migration guide](https://langfuse.com/docs/sdk/python/sdk-v3#upgrade-from-v2) for instructions on updating your code. +> **`langfuse` v3 is not the latest Langfuse Python SDK.** This branch publishes the **legacy** v3 client. Unpinned `pip install langfuse` installs the current v4. Do **not** use v3, or the older v2 client API (`Langfuse()`, `trace()`, `span()`, `generation()`, `api.trace.list`), for new instrumentation. +> +> **Latest Python SDK (OpenTelemetry)**, developed on [`main`](https://github.com/langfuse/langfuse-python/tree/main): `pip install langfuse`. Use `get_client()` + `start_as_current_observation` / `@observe`. Docs: https://langfuse.com/docs/observability/sdk/overview. Upgrade: [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 (`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. -``` -pip install langfuse -``` +## Installation + +This branch is the **legacy v3** SDK, in maintenance mode with critical bug fixes only. For new work, install the current v4 (`pip install langfuse`). To pin this legacy major: `pip install "langfuse>=3,<4"`. ## Docs -Please [see our docs](https://langfuse.com/docs/sdk/python/sdk-v3) for detailed information on this SDK. +- Current SDK guide: https://langfuse.com/docs/observability/sdk/overview +- v3 to v4 upgrade: https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4 +- Machine-readable docs index (for AI agents): https://langfuse.com/llms.txt +- 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 f46a38e73..02ec2cc64 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,7 +2,7 @@ name = "langfuse" version = "3.15.0" -description = "A client library for accessing langfuse" +description = "NOT the latest Langfuse Python SDK. Legacy v3 client - do not use for new instrumentation. Current SDK: pip install langfuse (v4, OpenTelemetry)" authors = ["langfuse "] license = "MIT" readme = "README.md" From ee77cba7bcc41f99dde6a0104c541c285131fbc2 Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Tue, 15 Sep 2026 12:13:05 +0200 Subject: [PATCH 2/3] docs: drop the v3 pin install line from the README Match v2-stable: do not tell agents how to keep installing the legacy major. Co-authored-by: Cursor --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8cb2fe18c..1acaf5a8a 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ ## Installation -This branch is the **legacy v3** SDK, in maintenance mode with critical bug fixes only. For new work, install the current v4 (`pip install langfuse`). To pin this legacy major: `pip install "langfuse>=3,<4"`. +This branch is the **legacy v3** SDK, in maintenance mode with critical bug fixes only. For new work, install the current v4 (`pip install langfuse`). ## Docs From 4444804f8452ddc96b4324d1b419c285fd0c9bf2 Mon Sep 17 00:00:00 2001 From: Max Deichmann Date: Tue, 15 Sep 2026 12:13:56 +0200 Subject: [PATCH 3/3] docs: restore the v3 rewrite note and keep Langfuse() as a current constructor Match main review feedback: keep the June 2025 rewrite callout, drop Langfuse() from the deprecated v2 API list, and restore the previous package 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 1acaf5a8a..d06e7c810 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] -> **`langfuse` v3 is not the latest Langfuse Python SDK.** This branch publishes the **legacy** v3 client. Unpinned `pip install langfuse` installs the current v4. Do **not** use v3, or the older v2 client API (`Langfuse()`, `trace()`, `span()`, `generation()`, `api.trace.list`), for new instrumentation. +> The SDK was rewritten in v3 and released in June 2025. Refer to the [v3 to v4 migration guide](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4) for instructions on updating your code. +> +> **`langfuse` v3 is not the latest Langfuse Python SDK.** This branch publishes the **legacy** v3 client. Unpinned `pip install langfuse` installs the current v4. Do **not** use v3, or the older v2 client API (`trace()`, `span()`, `generation()`, `api.trace.list`), for new instrumentation. > > **Latest Python SDK (OpenTelemetry)**, developed on [`main`](https://github.com/langfuse/langfuse-python/tree/main): `pip install langfuse`. Use `get_client()` + `start_as_current_observation` / `@observe`. Docs: https://langfuse.com/docs/observability/sdk/overview. Upgrade: [v3 to v4](https://langfuse.com/docs/observability/sdk/upgrade-path/python-v3-to-v4). > diff --git a/pyproject.toml b/pyproject.toml index 02ec2cc64..f46a38e73 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,7 +2,7 @@ name = "langfuse" version = "3.15.0" -description = "NOT the latest Langfuse Python SDK. Legacy v3 client - do not use for new instrumentation. Current SDK: pip install langfuse (v4, OpenTelemetry)" +description = "A client library for accessing langfuse" authors = ["langfuse "] license = "MIT" readme = "README.md"