chore(api)!: drop references to API types removed from the v4 spec

[hassiebp]

What does this PR do?

This prepares the SDK for the upcoming API client regeneration, which drops the v4-deprecated read endpoints and their types (langfuse/langfuse#18335). Without this PR, the regenerated client would fail to import.

• langfuse/model.py: stops re-exporting DatasetRun, Observation and TraceWithFullDetails, which the regenerated client removes. An AST scan of every hand-written langfuse.api import in langfuse/, tests/ and scripts/, checked against the full list of types #18335 deletes, found no other references.
• Langfuse.api / flush() docstrings: they no longer point to api.trace.get / api.trace.list, TraceWithDetails / TraceWithFullDetails, or api.legacy.observations_v1 / metrics_v1. They now describe the v4 read path: api.observations.get_many (v2), api.scores_v3 and api.experiments. They also no longer end on a dangling "retry with a deadline:" with no example.
• Two unit tests stop monkeypatching api.dataset_run_items.create. That resource is removed by the regen, so setattr on it would raise AttributeError, and the runner no longer calls it anyway.

langfuse/api/** itself is untouched; the regen replaces it.

Breaking for SDK users: from langfuse.model import DatasetRun, Observation, TraceWithFullDetails no longer works. These were v3 response types, and v4 has no equivalent endpoints.

Type of change

• Bug fix
• New feature
• Breaking change
• Refactor
• Documentation update
• Tooling, CI, or repo maintenance

Verification

uv run --frozen ruff check .                       # All checks passed!
uv run --frozen mypy langfuse --no-error-summary   # clean
uv run --frozen pytest -n auto tests/unit          # 782 passed, 2 skipped
python -c "import langfuse, langfuse.model"        # ok

Checklist

• I self-reviewed the diff using code_review.md.
• I added or updated tests for behavior changes.
• I updated docs, examples, or .env.template if needed.
• I did not hand-edit generated files; if generated files changed, I used the upstream regeneration path.
• I did not commit secrets or credentials.

  

Confidence Score: 5/5

The PR appears safe to merge with its stated breaking changes.

What we checked:

• Read example remains callable: get_many accepts both trace_id and fields, so the documented call matches the generated client.

Summary

Prepares handwritten SDK code for the upcoming generated API client update.

• Removes three old type exports from langfuse.model.
• Updates read guidance to use observations, scores, and experiments.
• Removes test patches against an unused API resource.
• No actionable issues found.

hassiebp explicitly acknowledges the three removed public imports as an intentional breaking change because their read endpoints are being removed.

_{Reviews (1) · Last reviewed commit: "chore(api): drop references to API types..." · Reviewed by Greptile}

[github-actions]

@claude review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-07T21:26:33.627828Z	25cd3c0	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

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.}

[claude]

LGTM, straightforward docstring/import/test cleanup. What was reviewed: the docstring edits in langfuse/_client/client.py (api property and flush()) replacing v1 trace-get/list references with the v2 observations API; the removal of unused DatasetRun, Observation, TraceWithFullDetails re-exports in langfuse/model.py (confirmed no other references to these names remain in langfuse/, tests/, outside the untouched generated langfuse/api/ package); and the two test files dropping now-invalid dataset_run_items.create monkeypatches/assertions, consistent with that call path no longer being exercised.

Extended reasoning...

Diff touches only docstrings, two re-exported type imports, and two unit test monkeypatch removals; no security-sensitive surface (auth, crypto, data exposure) is involved. Verified via grep that the removed names (DatasetRun, Observation, TraceWithFullDetails, dataset_run_items) have no remaining hand-written references outside the generated, untouched langfuse/api package, matching the PR author's stated AST-scan verification. Change is small, mechanical, and self-contained, matching approval criteria.