feat(api): update API spec from langfuse/langfuse 3fedbb7

[langfuse-bot]

Disclaimer: Experimental PR review

Greptile Summary

This auto-generated PR (via Fern from the upstream langfuse/langfuse spec at 3fedbb7) restructures the Python SDK's API surface by introducing a legacy namespace for older v1 endpoints and promoting the v2 endpoints to top-level modules.

Key changes:

• New legacy namespace: The score, score_v2, metrics_v2, and observations_v2 modules/client properties are retired and their v1 equivalents are re-homed under langfuse.api.legacy (accessible as client.legacy.score_v1, client.legacy.metrics_v1, client.legacy.observations_v1).
• Scores consolidation: score_v2 is renamed/promoted to scores (client.scores), now the primary scores endpoint.
• Type promotions: MetricsV2Response moves from langfuse.api.metrics_v2 → langfuse.api.metrics; ObservationsV2Meta / ObservationsV2Response move from langfuse.api.observations_v2 → langfuse.api.observations.
• Breaking removals from langfuse.api: CreateScoreRequest, CreateScoreResponse, MetricsResponse, Observations, ObservationsViews, and the module-level aliases score, score_v2, metrics_v2, observations_v2 are no longer exported at the top level. Users who import these directly will need to update to langfuse.api.legacy.*.
• Import placement: The new langfuse/api/legacy/client.py file and the new properties in langfuse/api/client.py follow the same existing lazy-import-inside-property pattern used throughout the codebase, but this pattern violates the project's rule of placing imports at the top of the module.

Confidence Score: 3/5

• The PR introduces breaking API surface changes that will affect users importing removed symbols; review for impact before merging.
• The restructuring is internally consistent and the new legacy namespace preserves v1 functionality, but several publicly exported types (CreateScoreRequest, CreateScoreResponse, MetricsResponse, Observations, ObservationsViews) and client properties (score, score_v2, metrics_v2, observations_v2) are removed from the top-level langfuse.api module without a deprecation shim. Any user code importing from these paths will break at runtime. Additionally, the new legacy/client.py introduces inline imports inside property methods, violating the project's import organization rule.
• langfuse/api/__init__.py (removed exports), langfuse/api/client.py (removed properties), and langfuse/api/legacy/client.py (inline imports).

Important Files Changed

Filename	Overview
langfuse/api/init.py	Top-level re-exports updated: score, score_v2, metrics_v2, observations_v2 modules removed; legacy and scores added. CreateScoreRequest, CreateScoreResponse, MetricsResponse, Observations, and ObservationsViews removed from __all__ and _dynamic_imports, which is a breaking public API change for existing users.
langfuse/api/client.py	Client class updated: removed score, score_v2, metrics_v2, observations_v2 properties; added legacy and scores properties. New properties use inline imports inside property methods (custom rule violation), consistent with existing pre-existing pattern throughout this file.
langfuse/api/legacy/init.py	New legacy namespace __init__.py correctly re-exports CreateScoreRequest, CreateScoreResponse, MetricsResponse, Observations, and ObservationsViews from their new sub-modules with proper lazy loading.
langfuse/api/legacy/client.py	New LegacyClient and AsyncLegacyClient grouping the v1 sub-clients. All lazy-loaded property imports are placed inside method bodies, violating the project's import-at-top-of-module rule (applies to lines 38, 46, 56, 84, 92, 102).
langfuse/api/legacy/metrics_v1/client.py	New MetricsV1Client wrapping the legacy /api/public/metrics endpoint (v1). All imports are top-level; implementation is clean.
langfuse/api/legacy/observations_v1/client.py	Renamed/moved from observations_v2/client.py; client now targets the v1 api/public/observations endpoint with offset/page-based pagination (instead of cursor-based), and adds a get() single-observation method. Clean implementation.
langfuse/api/scores/client.py	New ScoresClient (renamed from ScoreV2Client) for the /api/public/scores endpoint. Supports get_many() with rich filtering (field groups, environment, trace_tags, etc.) and get_by_id(). Clean implementation.
langfuse/api/scores/types/get_scores_response_data.py	Discriminated union type for score response data with four variants (Numeric, Categorical, Boolean, Correction), each using a data_type discriminator field. Correct use of pydantic's Field(discriminator=...) pattern.
langfuse/api/metrics/types/metrics_v2response.py	Moved from metrics_v2/types/metrics_v2response.py; unchanged content, just import path updated. Clean.
langfuse/api/observations/types/observations_v2response.py	New type file in observations module for ObservationsV2Response (cursor-based pagination). Uses optional cursor for next-page navigation.

Sequence Diagram

sequenceDiagram
participant User
participant LangfuseAPI
participant LegacyClient
participant ScoresClient
participant RawScoresClient
participant HTTP as HTTP (Langfuse Server)
Note over User,HTTP: New scores endpoint (v2 promoted)
User->>LangfuseAPI: .scores.get_many(...)
LangfuseAPI->>ScoresClient: lazy init ScoresClient
ScoresClient->>RawScoresClient: get_many(...)
RawScoresClient->>HTTP: GET /api/public/scores
HTTP-->>RawScoresClient: GetScoresResponse (discriminated union)
RawScoresClient-->>ScoresClient: HttpResponse[GetScoresResponse]
ScoresClient-->>User: GetScoresResponse.data
Note over User,HTTP: Legacy score v1 endpoint
User->>LangfuseAPI: .legacy.score_v1.create(...)
LangfuseAPI->>LegacyClient: lazy init LegacyClient
LegacyClient->>LegacyClient: lazy init ScoreV1Client
LegacyClient->>HTTP: POST /api/public/scores
HTTP-->>LegacyClient: CreateScoreResponse
LegacyClient-->>User: CreateScoreResponse
Note over User,HTTP: Legacy observations v1 endpoint
User->>LangfuseAPI: .legacy.observations_v1.get_many(...)
LangfuseAPI->>LegacyClient: lazy init LegacyClient
LegacyClient->>LegacyClient: lazy init ObservationsV1Client
LegacyClient->>HTTP: GET /api/public/observations (page-based)
HTTP-->>LegacyClient: ObservationsViews
LegacyClient-->>User: ObservationsViews

Loading

_{Last reviewed commit: b5ca2ce}

Context used:

• Rule used - Move imports to the top of the module instead of p... (source)

Learnt From
langfuse/langfuse-python#1387