Repository navigation
docs: upgrade guides and changelog for Python SDK v5 and JS/TS SDK v6 - #4008
Conversation
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
…SDK v5 and JS/TS SDK v6 Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
|
@claude review |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ebc06fd79d
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: Hassieb Pakzad <hassiebp@users.noreply.github.com>
Co-authored-by: hassieb.pakzad <hassieb.pakzad@clickhouse.com>
…-migration-guides-84a8 Co-authored-by: hassieb.pakzad <hassieb.pakzad@clickhouse.com>
…cy score_v1 in SDK majors Co-authored-by: hassieb.pakzad <hassieb.pakzad@clickhouse.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2069475ebb
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| In Python SDK v5 and JS/TS SDK v6, metadata values can be strings, | ||
| numbers, booleans, lists, or objects, and each{" "} | ||
| <strong>value must be ≤200 characters as JSON</strong> (a string |
There was a problem hiding this comment.
Add a Markdown renderer for PropagationRestrictionsCallout: when readers use generated .md pages or PDFs, stripMdxForPlainMarkdown removes this unrecognized self-closing component, so the newly added v5/v6 metadata types and 200-character JSON limit disappear from pages such as the SDK instrumentation guide. This can cause Markdown consumers to send values the SDK silently drops; handle this component in lib/markdown-component-renderers.js and verify the generated output.
AGENTS.md reference: AGENTS.md:L59-L59
Useful? React with 👍 / 👎.
#4036) Co-authored-by: Cursor Agent <cursoragent@cursor.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cd3e50dc51
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "dataType": "NUMERIC", | ||
| "comment": "Factually correct" | ||
| }' | ||
| -d '[ |
There was a problem hiding this comment.
When a direct REST client targets self-hosted Langfuse v2/v3 or an older v4 release, these newly array-wrapped request bodies use the v4.59 batch contract, while those supported deployments expect the previous single-score object. The compatibility matrix still marks direct /api/public/scores ingestion as fully supported on v2 and v3, so copying any of the updated curl examples will fail there. Keep a compatible single-object example or separate the batch form with an explicit server requirement and availability banner.
AGENTS.md reference: AGENTS.md:L117-L117
Useful? React with 👍 / 👎.
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
…#4038) Co-authored-by: Cursor Agent <cursoragent@cursor.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b2a81667e6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 575496861a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| await startActiveObservation("request", async () => { | ||
| setActiveTraceIO({ input: query, output: result }); |
There was a problem hiding this comment.
When a reader copies either version of this example, startActiveObservation and the version-specific helper are undefined because the code block imports nothing from @langfuse/tracing. The final squashed version provides fresh evidence beyond the resolved thread: it consolidated the previously separate v5/v6 blocks and dropped the imports added in 7e53326, including updateActiveObservation. Split the versioned examples or restore the appropriate imports so each example remains self-contained.
AGENTS.md reference: AGENTS.md:L138-L138
Useful? React with 👍 / 👎.
| date: 2026-10-14 | ||
| title: Python SDK v5 and JS/TS SDK v6 | ||
| description: New SDK majors built for Langfuse v4, with experiment links, typed metadata filters, and compressed span export. A small upgrade for most users. | ||
| author: Hassieb |
There was a problem hiding this comment.
One more thought: should we prominently place the new SDKs on all the agentic interfaces of the docs page?
Maybe worth a chat with Lotte
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 33dba028a2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - **Python SDK v4** <a href="https://github.com/langfuse/langfuse-python"><img className="inline" alt="GitHub repository langfuse/langfuse-python" src="https://img.shields.io/badge/repo-langfuse--python-blue?style=flat-square&logo=GitHub" /></a> <a href="https://pypi.org/project/langfuse/"><img className="inline" src="https://img.shields.io/pypi/v/langfuse?style=flat-square&label=pypi+langfuse" alt="PyPi langfuse" /></a> | ||
| - **JS/TS SDK v5** <a href="https://github.com/langfuse/langfuse-js"><img className="inline" alt="GitHub repository langfuse/langfuse-js" src="https://img.shields.io/badge/repo-langfuse--js-blue?style=flat-square&logo=GitHub" /></a> <a href="https://www.npmjs.com/package/@langfuse/tracing"><img className="inline" src="https://img.shields.io/npm/v/@langfuse/tracing?style=flat-square&label=npm+@langfuse/tracing" alt="NPM @langfuse/tracing" /></a> | ||
| - **Python SDK v5** <a href="https://github.com/langfuse/langfuse-python"><img className="inline" alt="GitHub repository langfuse/langfuse-python" src="https://img.shields.io/badge/repo-langfuse--python-blue?style=flat-square&logo=GitHub" /></a> <a href="https://pypi.org/project/langfuse/"><img className="inline" src="https://img.shields.io/pypi/v/langfuse?style=flat-square&label=pypi+langfuse" alt="PyPi langfuse" /></a> | ||
| - **JS/TS SDK v6** <a href="https://github.com/langfuse/langfuse-js"><img className="inline" alt="GitHub repository langfuse/langfuse-js" src="https://img.shields.io/badge/repo-langfuse--js-blue?style=flat-square&logo=GitHub" /></a> <a href="https://www.npmjs.com/package/@langfuse/tracing"><img className="inline" src="https://img.shields.io/npm/v/@langfuse/tracing?style=flat-square&label=npm+@langfuse/tracing" alt="NPM @langfuse/tracing" /></a> |
There was a problem hiding this comment.
When this page presents JS/TS SDK v6 as current, its browser section still says @langfuse/browser sends scores to the ingestion API. The updated score documentation states that v6 sends each browser score to POST /api/public/scores and only v5 and earlier use ingestion, so readers auditing or migrating away from the deprecated ingestion endpoint receive contradictory guidance on the same SDK.
Useful? React with 👍 / 👎.
This branch was successfully deployed
3 participants
Docs for the upcoming Python SDK v5 (
prepare-v5-releasein langfuse-python) and JS/TS SDK v6 (prepare-v6-releasein langfuse-js). Both majors target Langfuse v4 only. This PR makes the docs current for the release on merge. Self-hosted deployments need Langfuse v4.59.0 or later, the single server floor for all v5/v6 features.What's included
Upgrade guides
Both guides tell readers that this is a small upgrade for most users. Each one has the same layout:
#previously-deprecated): removals that the previous major already marked deprecated (PythonDeprecationWarning/ docs notice, JS@deprecated), each worded as "Previously deprecated in vN, now removed" with the replacement. A line near the top says code without deprecation warnings is most likely affected only by the new breaks, which it names.POST /api/public/scores(207 handling), gzip, the v4 ingestion header, experiments via OpenTelemetry, in Python thegen_ai.prefix in the default span filter, and in JS client-side score validation.python-v4-to-v5.mdx. New: minimum versions (Langfuse v4.59.0, Python 3.11,openai>=1,langchain-core>=1) ·api.scorestakes request objects (scores.create(request=...),score_v1.delete→scores.delete) · batched evaluation. Previously deprecated: Public API methods (noapi.legacy) · trace I/O setters · dataset run helpers ·blocked_instrumentation_scopes.js-v5-to-v6.mdx. New: minimum versions (Langfuse v4.59.0, Node 22/ES2022,@langchain/core@^1) · the{}request placeholder beforerequestOptions(all 41 methods with routes, checked againstprepare-v6-releasewith the placeholder script's--list) ·api.scoresresponse union andscoreV1.delete→scores.delete. Previously deprecated:LangfuseClientaliases · Public API methods (noapi.legacy) · trace I/O setters ·item.link().Both guides say that
host/LANGFUSE_HOSTandLANGFUSE_BASEURLkeep working, and neither calls them deprecated.Changelog
content/changelog/2026-10-14-python-sdk-v5-js-sdk-v6.mdx(dated 2026-10-14). It leads with highlights and new features, followed by a short "Upgrading" section: the install commands, the minimum Langfuse, Python, and Node.js versions, and a pointer to each guide's "Are you affected?" list. It doesn't list breaking changes.Compatibility matrices
/docs/compatibility: Python SDK v5 and JS/TS SDK v6 rows. They're marked Unsupported on Langfuse Cloud v3 and Full on Cloud v4. Also added detail blocks (self-hosted: v4.59.0 or later), GA version rows, and FAQ notes./self-hosting/upgrade/versioning#sdk-server: the new rows are Unsupported on OSS v2 and v3 and≥ 4.59.0on OSS v4.≥ v4.59.0), the Read APIs v2 detail block, and the v3 → v4 server upgrade guide. They now say v5/v6 require Langfuse v4 and should be upgraded only after the server.Metadata
Both SDKs change how metadata is sent (langfuse-python#1958, langfuse-js#1005). The docs don't describe the wire encoding as such. They only state the user-facing result: on v4.59.0+, numbers and booleans keep their type, nested objects become filterable dotted paths, and propagated metadata accepts any JSON value up to 200 characters as JSON. The masking page keeps one note that
mask_otel_spanssees JSON-encoded metadata attributes in Python v5.Pages updated to the new SDK APIs
blocked_instrumentation_scopesmention.span.update/update_current_span) instead of the removed setters.should_export_span, and these pages sayblocked_instrumentation_scopeswas removed in v5.item.link()was removed in JS/TS v6.getPrompt→prompt.get(error handling FAQ, Vercel AI SDK)resolveMediaReferences→media.resolveReferences(multi-modality)createDataset→api.datasets.create(datasets)api.legacynamespace. Each removed resource (observations, metrics,score_v1/scoreV1create and delete) is listed with its replacement, along with the removedapi.scoresv2 reads.@langfuse/browserv6 sends toPOST /api/public/scores.timeout/LANGFUSE_TIMEOUT. The page previously said 20s for Python and 10s for JS; the Python figure was already wrong for v4.PropagationRestrictionsCallout: note typed metadata and dotted paths on v4.59.0+. Propagated metadata in v5/v6 accepts strings, numbers, booleans, lists, or objects up to 200 characters as JSON, and top-levelnull/Noneis dropped with a warning. The string-only rule now covers only userId, sessionId, version, tags, and traceName.set_trace_io()from the legacymaskscope list, and notes thatmask_otel_spanssees JSON-encoded metadata attributes in Python v5.API reference deep links
The regenerated API reference drops the deprecated endpoints, so links to them now point at their replacements on the current reference (
api.reference.langfuse.com). No page links to a legacy reference.GET /experimentsandGET /experiment-itemsfor dataset runs and run items; and OpenTelemetry ingestion for the dataset-run-item, ingestion, and legacy POST endpoints.DELETE /datasets/{name}/runs/{runName}has no replacement, so that cell has no link. Inline replacement links now use the current tag anchors (observations,metrics,scoresv3).GET /api/public/observations) without a link, and the v2 Observations links use the current tag anchor.TODO before merge
api.scores.deleteand "noapi.legacynamespace" depend on the API regeneration from langfuse#18694. Today,legacy.score_v1.delete/legacy.scoreV1.deletestill exist on the SDK PR branches.Not changed (intentional)
cookbook/example_data_migration*.ipynbstill callapi.legacy.score_v1.createandapi.datasets.get_runs, so they target SDK v4. They are now pinned tolangfuse>=4.8.1,<5. The-jpmdx was regenerated withscripts/update_cookbook_docs.sh. The English mdx got the same one-line pin by hand: regenerating it would also revert content that only exists in the generated mdx and has drifted from its notebook (the frontmattercategory, the Japanese link, and the v3 fallback notes).components/*/apiHandler.tsstill callsetActiveTraceIOagainst the installed JS SDK v5. Update them when the site's dependencies move to v6.datasetRunId) are unchanged.Verification
pnpm run format:check: All matched files use Prettier code style!node scripts/check-h1-headings.js: Success: All checked markdown/MDX files have at most one H1 heading./changelog/2026-10-14-python-sdk-v5-js-sdk-v6, both upgrade guides, the timeouts FAQ, the metadata, instrumentation, and users pages (callout variants), and the data migration cookbook. The new matrix rows render, and no4.XX.0placeholders or TODO markers remain in page content. Every in-page anchor in both guides resolves. No page links to the removed anchors (#metadata-json-encoding,#experiment-results,#sampled-out-scores,#timeouts,#browser-error-types).The PR appears safe to merge, with three non-blocking documentation fixes.
Summary
Adds Python SDK v5 and JS/TS SDK v6 upgrade guides and a release changelog.
Intentional exclusions acknowledged by hassiebp:
setActiveTraceIObecause the site's installed JS SDK remains v5. They will be updated when the site's dependencies move to v6.datasetRunIdnames remain unchanged intentionally.Reviews (1) · Last reviewed commit: "docs: document JSON-encoded SDK metadata..." · Reviewed by Greptile