feat(api): update API spec from langfuse/langfuse 2eaf041

[langfuse-bot]

Disclaimer: Experimental PR review

Greptile Summary

This auto-generated PR (via Fern) reshapes the Langfuse Python SDK's API module layout to promote v2 endpoints as the canonical defaults and move v1 legacy endpoints under a new langfuse.api.legacy.* namespace.

Key changes:

• client.metrics now calls api/public/v2/metrics instead of api/public/metrics. This is a silent breaking change for any caller using the "traces" view or high-cardinality grouping dimensions — both will begin receiving 400 errors without any code change on the caller's side. The old v1 behavior is preserved at client.legacy.metrics_v1.
• client.observations now exposes ObservationsV2Meta / ObservationsV2Response (previously observations_v2); old v1 types (Observations, ObservationsViews) are under client.legacy.observations_v1.
• client.scores replaces the former client.score_v2; old client.score is now client.legacy.score_v1.
• Top-level exports removed: CreateScoreRequest, CreateScoreResponse, MetricsResponse, Observations, ObservationsViews. Callers importing these directly from langfuse.api will get ImportError / AttributeError at runtime.
• New inline imports (from … import … # noqa: E402) inside property methods follow a pattern already present in the codebase but violate the project's custom import-ordering rule across all new and modified client files.

Confidence Score: 3/5

• Mostly safe to merge, but contains a silent breaking change: client.metrics now silently calls the v2 endpoint, which rejects previously valid "traces" view queries.
• The reorganisation logic is correct and consistent throughout the generated code. However, the metrics client endpoint promotion (v1→v2) is silent — no deprecation warning, no version bump signal at the call site — meaning users relying on the "traces" view or high-cardinality dimensions will receive unexpected 400 errors after upgrading. The inline-import pattern violates the custom rule but is a pre-existing style issue in the codebase. Removed top-level exports (CreateScoreRequest, MetricsResponse, etc.) are additional breaking changes that should be called out in the changelog.
• langfuse/api/metrics/raw_client.py — endpoint silently promoted to v2; langfuse/api/__init__.py — multiple symbols removed from public exports.

Important Files Changed

Filename	Overview
langfuse/api/init.py	Public API surface reshaped: MetricsResponse, Observations, ObservationsViews, CreateScoreRequest, CreateScoreResponse removed from top-level exports and replaced with v2 equivalents; old names are now accessible via legacy.*.
langfuse/api/client.py	Client properties reorganized: metrics_v2, observations_v2, score, and score_v2 removed; legacy and scores added. New legacy and scores properties use inline imports inside methods, violating the top-level import convention.
langfuse/api/legacy/client.py	New file aggregating legacy (v1) sub-clients: metrics_v1, observations_v1, score_v1. All six sub-client properties (sync + async) use inline imports inside method bodies, inconsistent with the project's top-level import convention.
langfuse/api/metrics/raw_client.py	Endpoint silently promoted from api/public/metrics (v1) to api/public/v2/metrics (v2) and response type changed to MetricsV2Response. This is a silent breaking change for existing callers relying on the "traces" view or high-cardinality group dimensions.
langfuse/api/legacy/metrics_v1/raw_client.py	New file providing the original v1 metrics endpoint (api/public/metrics) wrapped as RawMetricsV1Client. Logic is correct and path imports updated properly for the deeper nesting level.
langfuse/api/legacy/observations_v1/raw_client.py	Renamed from observations_v2/raw_client.py; URL corrected to api/public/observations (v1) and a new get method added for single-observation retrieval. Import paths updated for the deeper nesting. Looks correct.
langfuse/api/scores/client.py	Renamed from score_v2/client.py to scores/client.py with classes renamed accordingly. No logic changes detected.
langfuse/api/legacy/score_v1/raw_client.py	Renamed from score/raw_client.py; import paths updated for the additional nesting level. No functional changes.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[LangfuseAPI / AsyncLangfuseAPI] --> B[client.metrics\n→ api/public/v2/metrics\nMetricsV2Response]
    A --> C[client.observations\n→ api/public/v2/observations\nObservationsV2Response]
    A --> D[client.scores\n→ /scores endpoints\nGetScoresResponse]
    A --> E[client.legacy\nLegacyClient]
    E --> F[legacy.metrics_v1\n→ api/public/metrics\nMetricsResponse]
    E --> G[legacy.observations_v1\n→ api/public/observations\nObservationsViews]
    E --> H[legacy.score_v1\n→ /score endpoints\nCreateScoreResponse]

    subgraph Removed
        R1[client.metrics_v2 ✗]
        R2[client.observations_v2 ✗]
        R3[client.score ✗]
        R4[client.score_v2 ✗]
    end

    style B fill:#f9a,stroke:#c00
    style Removed fill:#fee,stroke:#c00

Loading

_{Last reviewed commit: 2bd5eb4}

Greptile also left 1 inline comment on this PR.

Context used:

• Rule from dashboard - Move imports to the top of the module instead of placing them within functions or methods. (source)

[greptile-apps]

Silent endpoint promotion may break existing callers

RawMetricsClient.metrics (and its async counterpart) previously called api/public/metrics (the v1 endpoint). After this PR it calls api/public/v2/metrics. Any code that was already using client.metrics.metrics(...) will silently start hitting the v2 endpoint, which has different semantics:

• The "traces" view is no longer supported and will now return a 400 error.
• High-cardinality dimensions such as userId and sessionId cannot be used as grouping dimensions in v2, raising 400 errors where they previously worked.
• Default row_limit changes to 100 (vs. unspecified before).

The legacy v1 endpoint is still available at client.legacy.metrics_v1.metrics(...), but users who don't read release notes will hit unexpected 400s. Consider adding a deprecation warning or release note callout in the changelog.