Skip to content

feat(api): update API spec from langfuse/langfuse 0b6d4e6 - #1984

Closed
langfuse-bot wants to merge 1 commit into
mainfrom
api-spec-bot-0b6d4e6-38363549416-1
Closed

langfuse-bot wants to merge 1 commit into
mainfrom
api-spec-bot-0b6d4e6-38363549416-1

Conversation

@langfuse-bot

@langfuse-bot langfuse-bot commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

RetriggerConfidence Score: 4/5

Fix the legacy score adapter before merging; its calls now fail before reaching the server.

Summary

Updates the generated API clients with batch score writes, unstable skills APIs, GCS storage support, API-key names and expiry, and prompt filters.

  • Python callers can manage skill versions and retrieve their files.
  • Score creation accepts one score or a batch.
  • Prompt lists accept structured filters for matching versions.
  • API keys can have a name and an optional expiry time.
  • Blob storage integrations accept updated provider settings.
  • Legacy ingestion models carry sunset guidance and response metadata.
  • The legacy ingestion client no longer exposes the sdk-log event.
  • Generated API exports and supporting clients stay aligned with the refreshed spec.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Caller[Score caller] --> Choice{Call shape}
    Choice -->|request| Scores[Current scores client]
    Choice -->|name and value| Legacy[Legacy score adapter]
    Legacy --> Failure[TypeError before request]
    Scores --> API[Scores API]
    API --> Single[200: score ID]
    API --> Batch[202: accepted]
    API --> Partial[207: counts and errors]
Loading

Reviews (1) · Last reviewed commit: "feat(api): update API spec from langfuse..." · Reviewed by Greptile

@langfuse-bot
langfuse-bot requested a review from nimarb October 13, 2026 07:36
@github-actions

Copy link
Copy Markdown

@claude review

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

No review was started: this request came from a bot account. Manual reviews can only be requested by someone with write access to this repository. Ask a maintainer to comment @claude review, or have your automation post the comment from a user account with write access.

Tip: disable this comment in your organization's Code Review settings.

Comment on lines 36 to +41
def create(
self,
*,
name: str,
value: CreateScoreValue,
id: typing.Optional[str] = OMIT,
trace_id: typing.Optional[str] = OMIT,
session_id: typing.Optional[str] = OMIT,
observation_id: typing.Optional[str] = OMIT,
dataset_run_id: typing.Optional[str] = OMIT,
comment: typing.Optional[str] = OMIT,
metadata: typing.Optional[typing.Dict[str, typing.Any]] = OMIT,
environment: typing.Optional[str] = OMIT,
queue_id: typing.Optional[str] = OMIT,
data_type: typing.Optional[ScoreDataType] = OMIT,
config_id: typing.Optional[str] = OMIT,
source: typing.Optional[CreateScoreSource] = OMIT,
request: CreateScoresRequest,
request_options: typing.Optional[RequestOptions] = None,
) -> CreateScoreResponse:
) -> CreateScoresResponse:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Legacy score writes fail

ScoresClient.create now accepts only request=, but client.legacy.score_v1.create still forwards name=, value=, and the other old arguments. Every call through that method raises TypeError before sending a score. The async method has the same problem.

Update both legacy adapters and the generation patch to build CreateScoreRequest, or preserve the old arguments on the canonical methods.

Knowledge Base Used: API compatibility and transport

Prompt To Fix With AI
This is a comment left during a code review.
Path: langfuse/api/scores/client.py
Line: 36-41

Comment:
**Legacy score writes fail**

`ScoresClient.create` now accepts only `request=`, but `client.legacy.score_v1.create` still forwards `name=`, `value=`, and the other old arguments. Every call through that method raises `TypeError` before sending a score. The async method has the same problem.

Update both legacy adapters and the generation patch to build `CreateScoreRequest`, or preserve the old arguments on the canonical methods.

**Knowledge Base Used:** [API compatibility and transport](https://app.greptile.com/personal-org-4986/-/custom-context/knowledge-base/langfuse/langfuse-python/-/docs/api-compatiblity-and-transport.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Examples
--------
from langfuse import LangfuseAPI
from langfuse.scores import CreateScoreRequest

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 New examples fail to import

The new examples import CreateScoreRequest from langfuse.scores, but that package does not exist. The skills examples likewise use the missing langfuse.unstable.skills package. Copying these imports fails before either example can run.

Use langfuse.api.scores and langfuse.api.unstable.skills throughout the added examples, including the batch example.

Knowledge Base Used: API client and service surface

Prompt To Fix With AI
This is a comment left during a code review.
Path: langfuse/api/scores/client.py
Line: 59

Comment:
**New examples fail to import**

The new examples import `CreateScoreRequest` from `langfuse.scores`, but that package does not exist. The skills examples likewise use the missing `langfuse.unstable.skills` package. Copying these imports fails before either example can run.

Use `langfuse.api.scores` and `langfuse.api.unstable.skills` throughout the added examples, including the batch example.

**Knowledge Base Used:** [API client and service surface](https://app.greptile.com/personal-org-4986/-/custom-context/knowledge-base/langfuse/langfuse-python/-/docs/api-client-and-service-surface.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Parameters
----------
sha256hashes : str
Comma-separated list of one to 50 canonical base64-encoded SHA-256 hashes from skill file manifests. URL-encode the value, including +, /, and = characters.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Hash instructions break file reads

get_file_contents tells users to URL-encode sha256hashes, but HTTPX already encodes the query values. Following the instruction turns %2B into %252B, so the server receives an encoded string rather than the original hash.

Tell callers to pass the raw comma-separated hashes. Correct the sync, async, and raw method docs.

Knowledge Base Used: API compatibility and transport

Prompt To Fix With AI
This is a comment left during a code review.
Path: langfuse/api/unstable/skills/client.py
Line: 262

Comment:
**Hash instructions break file reads**

`get_file_contents` tells users to URL-encode `sha256hashes`, but HTTPX already encodes the query values. Following the instruction turns `%2B` into `%252B`, so the server receives an encoded string rather than the original hash.

Tell callers to pass the raw comma-separated hashes. Correct the sync, async, and raw method docs.

**Knowledge Base Used:** [API compatibility and transport](https://app.greptile.com/personal-org-4986/-/custom-context/knowledge-base/langfuse/langfuse-python/-/docs/api-compatiblity-and-transport.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.


This endpoint implements the OTLP/HTTP specification for trace ingestion, providing native OpenTelemetry integration for Langfuse Observability.

Together with Observations API v2 and Metrics API v2, this is the only real-time write path. Other public API endpoints can delay data by about 10 minutes. Direct exporters must send `x-langfuse-ingestion-version: 4`; current Python and JS SDKs already do.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Real-time setup guidance is wrong

The new guidance says current Python SDKs already send x-langfuse-ingestion-version: 4, but this SDK's default exporter does not include that header. Users can wrongly assume that the documented real-time path is enabled.

Remove or qualify that claim, and explain how to supply the header until the default exporter adds it.

Prompt To Fix With AI
This is a comment left during a code review.
Path: langfuse/api/opentelemetry/client.py
Line: 41

Comment:
**Real-time setup guidance is wrong**

The new guidance says current Python SDKs already send `x-langfuse-ingestion-version: 4`, but this SDK's default exporter does not include that header. Users can wrongly assume that the documented real-time path is enabled.

Remove or qualify that claim, and explain how to supply the header until the default exporter adds it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Comment on lines 36 to +41
def create(
self,
*,
name: str,
value: CreateScoreValue,
id: typing.Optional[str] = OMIT,
trace_id: typing.Optional[str] = OMIT,
session_id: typing.Optional[str] = OMIT,
observation_id: typing.Optional[str] = OMIT,
dataset_run_id: typing.Optional[str] = OMIT,
comment: typing.Optional[str] = OMIT,
metadata: typing.Optional[typing.Dict[str, typing.Any]] = OMIT,
environment: typing.Optional[str] = OMIT,
queue_id: typing.Optional[str] = OMIT,
data_type: typing.Optional[ScoreDataType] = OMIT,
config_id: typing.Optional[str] = OMIT,
source: typing.Optional[CreateScoreSource] = OMIT,
request: CreateScoresRequest,
request_options: typing.Optional[RequestOptions] = None,
) -> CreateScoreResponse:
) -> CreateScoresResponse:

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Every call to the deprecated client.legacy.score_v1.create(...) alias, sync or async, now fails with TypeError. On the base branch it forwarded to scores.create and worked. The alias in langfuse/api/legacy/score_v1/client.py:54 and :147 still passes flat kwargs (name=, value=, trace_id=, ...). The regenerated scores.create at langfuse/api/scores/client.py:36 now takes only request: CreateScoresRequest. Fix: have both aliases build CreateScoreRequest(name=..., value=..., ...) and pass it as request=. Update scripts/patch_generated_score_compat.py's SYNC_CREATE_METHOD/ASYNC_CREATE_METHOD templates the same way, so the next regeneration does not bring the break back.

Why this was flagged

A user calls client.legacy.score_v1.create(name="accuracy", value=0.9, trace_id=...). This diff does not touch langfuse/api/legacy/score_v1/client.py. Its create (line 34) and async create (line 127) still call CanonicalScoresClient(...).create(name=name, value=value, id=id, ...) and the async equivalent. The regenerated ScoresClient.create / AsyncScoresClient.create (langfuse/api/scores/client.py:36 and :285) is keyword-only with only request and request_options. So the call raises TypeError: create() got an unexpected keyword argument 'name' before any HTTP request goes out. On the base branch the canonical create took these flat kwargs and the alias worked. The postprocessor does not catch this: once the legacy client already has create and the marker, patch_generated_api returns False without changes, and its templates still emit the flat-kwarg forwarding.

Verification: Trigger: any caller uses the deprecated client.legacy.score_v1.create(...) alias, sync or async. langfuse/api/legacy/score_v1/client.py is unchanged, and its create (lines 34-73) still passes flat kwargs. In langfuse/api/scores/client.py:36-41 the signature is now def create(self, *, request: CreateScoresRequest, request_options=None). In bf11ec1 the same method took those flat kwargs.

Comment on lines 36 to 40
def create(
self,
*,
name: str,
value: CreateScoreValue,
id: typing.Optional[str] = OMIT,
trace_id: typing.Optional[str] = OMIT,
session_id: typing.Optional[str] = OMIT,
observation_id: typing.Optional[str] = OMIT,
dataset_run_id: typing.Optional[str] = OMIT,
comment: typing.Optional[str] = OMIT,
metadata: typing.Optional[typing.Dict[str, typing.Any]] = OMIT,
environment: typing.Optional[str] = OMIT,
queue_id: typing.Optional[str] = OMIT,
data_type: typing.Optional[ScoreDataType] = OMIT,
config_id: typing.Optional[str] = OMIT,
source: typing.Optional[CreateScoreSource] = OMIT,
request: CreateScoresRequest,
request_options: typing.Optional[RequestOptions] = None,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 Users who call scores.create(name=..., value=..., trace_id=...) will get TypeError after this upgrade. This includes langfuse.api.scores.create and the async and raw variants. All three now take only request: CreateScoresRequest. They return a Union, CreateScoresResponse, instead of CreateScoreResponse. Fix: keep the flat-kwarg form working, at least during a deprecation period. For example, accept the old kwargs and wrap them in CreateScoreRequest when request is omitted. Alternatively, ship this as an explicitly breaking release, because the repo's compat postprocessor shows the flat signature is meant to stay stable.

Why this was flagged

On the base branch, ScoresClient.create, AsyncScoresClient.create and RawScoresClient.create took keyword arguments name, value, id, trace_id, session_id, observation_id, dataset_run_id, comment, metadata, environment, queue_id, data_type, config_id and source, and returned CreateScoreResponse. After this diff, langfuse/api/scores/client.py:36-40, :285-289 and langfuse/api/scores/raw_client.py:36-40, :468-472 accept only request and request_options. Any existing user code such as langfuse.api.scores.create(name="accuracy", value=0.9, trace_id=tid) raises TypeError at call time, and the score is lost. Code that reads .id from the result also has to deal with the new Union return type, since a batch result has no id. No shim or overload keeps the old form working. The repo-wide grep found no in-repo callers outside the generated docstrings, so only external SDK users hit this. scripts/patch_generated_score_compat.py shows the maintainers intend to preserve this flat signature.

Verification: In langfuse/api/scores/raw_client.py:36-40 the signature is now def create(self, *, request: CreateScoresRequest, request_options=None) -> HttpResponse[CreateScoresResponse], and client.py:36-40 and :285-289 are the same. Because the arguments are keyword-only, create(name=..., value=..., trace_id=...) raises TypeError (unexpected keyword 'name', missing 'request').

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant