Python SDK 2.5.0 (research background mode + frontier effort)

[tyler5673]

Summary

Python SDK 2.5.0 release introducing background-mode research: async task submission, polling, and streaming for long-running research tasks. Also adds the new frontier research effort tier for highest-quality, long-running research, and the new lite finance research effort tier for quick financial questions.

New Features

Method	Description
you.research(background=True)	Queues research tasks asynchronously, returns TaskResponse with task_id and stream_url instead of blocking for inline ResearchResponse
you.get_research_task(task_id=...)	Poll status of a background task via GET /v1/research/{task_id}, returns TaskDetail with result populated on completion
you.stream_research_task(task_id=..., from_id=0)	Stream real-time SSE events via GET /v1/research/{task_id}/stream. Terminal event names: response.done, complete, completed (success); error, failed, cancelled (failure)
ResearchEffort.FRONTIER	New highest-quality research effort tier. Runs over longer durations (up to 4 hours) with improved quality and accuracy. Only works with the task-based API (background=true); sending frontier without background=true returns a 422.
FinanceResearchEffort.LITE	New quick-response tier for the Finance Research API. Returns answers fast for straightforward financial questions. The default remains deep. No migration required; existing DEEP and EXHAUSTIVE values are unchanged.

Convenience Helpers (youdotcom.research_helpers)

Hand-maintained, regen-safe module:

Helper	Description
research_background() / _async()	Submit and return TaskResponse directly (no Union narrowing)
poll_research_task() / _async()	Poll until terminal status (completed, failed, cancelled). Defaults: interval_s=2.0, timeout_s=600.0. For frontier tasks, pass timeout_s=14400 explicitly.
research_and_wait() / _async()	Submit + stream SSE events until a terminal event arrives, then fetch the final TaskDetail. timeout_s auto-adjusts based on research_effort: 600s for standard/deep/exhaustive, 14400s (4 hours) for frontier. Bounded re-poll tolerates backend commit races.
stream_research() / _async()	Tolerant SSE iterator that surfaces undocumented event types as raw dicts instead of crashing (recommended over stream_research_task() for real tasks)

Key Changes

• you.research() return type widened to Union[ResearchResponse, TaskResponse]. Runtime behavior unchanged when background=False (default). Statically-typed callers accessing res.output may need an isinstance(res, ResearchResponse) narrow to satisfy mypy/pyright.
• New ResearchEffort.FRONTIER enum value for the highest-quality, longest-running research tier. Documented in CHANGELOG.md, MIGRATION.md, docs/models/researcheffort.md, and docs/sdks/you/README.md.
• New FinanceResearchEffort.LITE enum value for quick finance research answers. Documented in CHANGELOG.md, MIGRATION.md, docs/models/financeresearcheffort.md, and docs/sdks/you/README.md.
• New models: TaskResponse, TaskDetail, ResearchTaskStreamEvent, Event enum, and 8 typed error classes.
• stream_research recommended over stream_research_task for real tasks — the server emits intermediate workflow events not in the strict Event enum, which causes ResponseValidationError in the generated decoder. The tolerant helper surfaces them as raw dicts instead.
• Completion-race re-poll: _resolve_from_final_get re-polls up to 3 times when the stream signals OK but the GET status hasn't caught up, with a clear error for terminal non-completed vs. exhausted attempts.
• Sync/async timeout parity: both research_and_wait variants bound the SSE per-read timeout to timeout_s (or caller's timeout_ms when provided) and catch httpx.TimeoutException for graceful fallback.

Testing

• Unit tests with mockserver + httpx MockTransport (86 tests)
• Live tests pass against production API (frontier background: PASS ~10min, frontier 422: PASS, finance lite: SKIP until server deploys)
• pylint 10.00/10, mypy clean, Go mockserver builds clean
• Ponytail and honest code reviews completed; all P2 findings fixed
• New tests: test_research_frontier_effort_with_background, test_frontier_without_background_raises_422, test_finance_research_lite_effort, frontier auto-timeout, completion-race re-poll (sync+async), async httpx.ReadTimeout fallback

See CHANGELOG.md for full release notes and MIGRATION.md for upgrade guidance from 2.4.0.

[claude]

Review Summary — 2.5.0 (research background mode + frontier effort)

Reviewed with focus on the hand-maintained surfaces (research_helpers.py, tests/, CHANGELOG.md, MIGRATION.md, overlays/python_overlay.yaml, pyproject.toml). The auto-generated src/youdotcom/ churn was spot-checked, not line-reviewed. This is a high-quality PR — approve after the one minor doc nit below (non-blocking).

Code quality & correctness ✅

research_helpers.py is well-structured and the sync/async variants are faithful mirrors. I verified the important bits:

• Exception ordering in both research_and_wait variants is correct: httpx.TimeoutException (a subclass of httpx.TransportError) is caught before the TransportError fallback branch, so stalls → TimeoutError and genuine transport failures → poll fallback, as intended.
• Completion-race re-poll (_resolve_from_final_get) correctly distinguishes terminal-non-completed (raise immediately) from not-yet-committed (bounded re-poll), and detail is always bound before the post-loop RuntimeError.
• Total wall-clock deadline is enforced independently of the per-read SSE timeout (sync via in-loop deadline check + bounded read timeout; async via asyncio.wait_for).
• The double stream.close() in the sync mid-stream TransportError path is harmless — EventStream.close() delegates to httpx response.close(), which is idempotent.
• The tolerant _decode_raw_event / stream_research correctly surface undocumented event names as RawStreamEvent instead of failing pydantic validation, and _raise_stream_error mirrors the generated typed-error branches (401/403/404/500 → typed, else YouDefaultError).

Test coverage ✅ (excellent)

test_research_helpers.py (+1550) is thorough and non-vacuous — real assertions across: TaskResponse narrowing + TypeError guard, poll terminal/timeout/failed, research_and_wait OK/error/timeout/stream-close/re-poll-success/re-poll-exhausted/terminal-failed, frontier auto-timeout + explicit override, stream-open & mid-stream transport-error fallbacks, typed stream errors, and the tolerant decoder. Sync and async paths are both covered. test_research.py adds direct SDK-method coverage (background return type, get/stream methods, error paths, frontier-without-background → 422). The Go mockserver SSE framing, routing, and JSON payloads were separately verified to match both the generated Event-enum decoder and the tolerant helper decoder. (I was not able to execute the suite in this sandbox — approvals blocked python/pytest — so correctness is from static tracing, not a green run.)

Documentation ✅

CHANGELOG.md, MIGRATION.md, README, USAGE, and the model docs are accurate and consistent with the code (enum values, return-type widening, auto-timeout table, stream_research vs stream_research_task guidance). examples/api-example-calls.py additions are correct and match the documented usage.

Breaking changes ✅

The you.research() return type widening to Union[ResearchResponse, TaskResponse] is the only breaking change, and it's runtime-compatible (default background=False still returns ResearchResponse). MIGRATION.md documents this clearly, including the static-typing isinstance/cast note. New enum values are purely additive.

Security ✅

No hardcoded secrets, no injection surface. Test/mock credentials are obvious placeholders (test-api-key, all-zero UUIDs). Overlay changes are limited to additive enum values and additionalProperties: true on TaskDetail.result/input.

Minor / non-blocking

1. [inline] research_and_wait sync docstring claims the SSE per-read timeout can use timeout_ms "when provided", but the code always uses timeout_s; the async docstring is already correct.
2. Trivial: CHANGELOG.md dates 2.5.0 as 2026-07-20 while the PR merges 2026-07-23 — confirm the intended release date.
3. Optional: no explicit test for an async mid-stream (non-timeout) TransportError fallback — the sync equivalent and the async open-error/read-timeout cases are covered, so this is a small gap only.

🤖 Generated with Claude Code