docs: strengthen agent-facing deprecation banner on v2-stable

[maxdeichmann]

Summary

• Put an agent-facing [!IMPORTANT] banner at the top of the v2 README stating that langfuse v2 is not the current Python SDK.
• Name the current install path (pip install langfuse on main / v4), point at current docs / v2→v3 / v3→v4 upgrade guides.
• Link the read APIs and state the data freshness SLO: 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 and Metrics API v2. All other GET APIs from all SDK versions can be up to 10 minutes behind.
• Update the PyPI description so this major is labeled deprecated in registry metadata.

Python counterpart of langfuse/langfuse-js#951 (legacy branch). Identical query/freshness wording as the main and v3-stable companions.

Test plan

• Confirm first 15 lines of README.md state latest SDK ≠ this major, name get_client() / start_as_current_observation, and tell agents not to use v2 for new work
• Confirm the Observations API v2 and Metrics API v2 doc links resolve
• After merge: a v2 patch publish is still required for PyPI consumers to see the README/description update

Made with Cursor

Confidence Score: 5/5

This docs-only change appears safe to merge.

Summary

The PR clearly marks the v2 Python SDK as deprecated and points new users and coding agents to the current v4 OpenTelemetry SDK. It also explains the real-time data path and repeats the warning in the package metadata shown by PyPI.

• Adds an agent-facing README banner with current install, upgrade, API, and freshness guidance.
• Separates legacy v2 installation and interfaces from current v4 documentation.
• Labels the v2 package as deprecated in pyproject.toml.

Diagram

sequenceDiagram
    actor User
    participant README
    participant Pip as pip
    participant V4 as Langfuse v4
    participant V2 as Langfuse v2
    participant API as Langfuse APIs
    actor Publisher
    participant PyPI

    User->>README: Read legacy warning
    alt New work
        User->>Pip: pip install langfuse
        Pip-->>User: Install current v4
        User->>V4: Use get_client and observations
        V4->>API: Send OpenTelemetry ingestion v4
        User->>API: Read Observations API v2 or Metrics API v2
        API-->>User: Return the real-time path
    else Legacy v2 maintenance
        User->>Pip: "pip install langfuse>=2,<3"
        Pip-->>User: Install legacy v2
        User->>V2: Use legacy client
        User->>API: Call other GET APIs
        API-->>User: Data may lag up to 10 minutes
    end
    Publisher->>PyPI: Publish next v2 patch
    PyPI-->>User: Show deprecated v2 package summary

Loading

_{Reviews (1) · Last reviewed commit: "docs: strengthen agent-facing deprecatio..."}

[claude]

Looks good, straightforward documentation/metadata change. Reviewed the README banner rewrite and the pyproject.toml description field update — both are text-only, consistent with each other, and contain no code or dependency changes. Links added point to plausible current-SDK docs pages; nothing to verify functionally.

Extended reasoning...

Overview

The diff touches only README.md and pyproject.toml. It rewrites the top banner and several sections of the README to mark this branch as the deprecated v2 SDK, redirect users to the current v4 (OpenTelemetry-based) SDK, and point at new Observations API v2 / Metrics API v2 docs instead of the old traces API. pyproject.toml's description field is changed similarly, from a generic description to an explicit deprecation notice. No source code, build configuration, dependencies, or version numbers were touched.

Security risks

None. This is pure prose/metadata — no code execution paths, no auth, no data handling changed. The only risk vector would be malicious links, but the links point to langfuse.com and github.com/langfuse domains consistent with the project's own documentation, not to attacker-controlled destinations.

Level of scrutiny

Low scrutiny is appropriate here. This is a documentation-only change with no functional or behavioral impact on the package; the "code" affected is a string literal in pyproject.toml and a markdown file. It matches the exact pattern of a stated companion PR that already merged for the JS SDK and the analogous main/v3-stable branches, per the PR description.

Other factors

No CODEOWNERS restriction was found for README.md or pyproject.toml. The PR conversation timeline shows no outstanding CHANGES_REQUESTED or unresolved third-party objections. The bug hunting system reported no findings, and my own read of the diff found nothing incorrect or inconsistent (the version number 2.60.10 is unchanged, which is correct since this is a docs-only change, not a release).