docs: strengthen agent-facing deprecation banner on v3-stable - #1881
Conversation
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 <cursoragent@cursor.com>
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
Looks good, straightforward docs/metadata change. Reviewed the README banner rewording and Installation/Docs section updates, plus the pyproject.toml description field change — no code, version, or dependency changes; links in the new banner point to plausible current docs paths.
Extended reasoning...
Overview
The diff touches only README.md and pyproject.toml. README.md replaces the old "SDK was rewritten in v3" callout with a more detailed [!IMPORTANT] banner clarifying that this branch/package major (v3) is legacy and in maintenance mode, pointing readers to the v4 OpenTelemetry-based SDK, the v3-to-v4 upgrade guide, Observations API v2 / Metrics API v2, and data-freshness caveats. It also reorders/expands the Installation and Docs sections accordingly. pyproject.toml only changes the description metadata field to state the package is not the latest SDK; the version string (3.15.0) is untouched, and no dependencies, build config, or source code changed.
Security risks
None. This is documentation and package metadata only — no code paths, auth, crypto, or permission logic are touched. There is no injection or data-exposure risk from wording changes in a README or a PyPI description string.
Level of scrutiny
Low scrutiny is appropriate here: mechanical, self-contained documentation/metadata edits with no functional impact. This matches the CLAUDE.md guidance that pyproject.toml is an "Important File" primarily for Poetry configuration/dependencies/tool settings and version bumps (handled by CI) — this PR touches none of those, only the free-text description field.
Other factors
No test coverage is applicable or needed for a docs/metadata-only change. No CODEOWNERS restriction was found for README.md or pyproject.toml in this repo. The bug-hunting run reported no findings, and my own review of the diff surfaced nothing beyond straightforward wording/link changes.
Match v2-stable: do not tell agents how to keep installing the legacy major. Co-authored-by: Cursor <cursoragent@cursor.com>
…nstructor 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 <cursoragent@cursor.com>
|
Applied the same review logic as #1879:
The v3 pin-install line was already removed to match #1880. |
2 participants
Summary
[!IMPORTANT]banner at the top of the v3 README stating thatlangfusev3 is not the current Python SDK.pip install langfuseonmain/ v4), point at current docs / v3→v4 upgrade guide.langfuse>= 4.7.0, or any OTel exporter sendingx-langfuse-ingestion-version: 4) combined with the Observations API v2 and Metrics API v2. All other GET APIs from all SDK versions can be up to 10 minutes behind.descriptionso this major is labeled not-latest in registry metadata.Python counterpart of langfuse/langfuse-js#951 (legacy branch). Identical query/freshness wording as the
mainand v2-stable companions.Test plan
README.mdstate latest SDK ≠ this major, nameget_client()/start_as_current_observation, and tell agents not to use v3 for new workdescriptionupdateMade with Cursor
The PR appears safe to merge, with a non-blocking documentation issue affecting maintainers of existing v3 integrations.
Summary
This PR prominently identifies the branch and package metadata as legacy v3, directs new integrations to the OpenTelemetry-based v4 SDK, and documents recommended query APIs and data-freshness expectations.
Reviews (1) · Last reviewed commit: "docs: strengthen agent-facing deprecatio..."