Release v3.0.0: Answer API, Speakeasy removal, flattened API surface

[tyler5673]

youdotcom 3.0.0

Adds the Answer API, removes the Agents API, and flattens the sub-SDK layer into direct methods on You. The SDK is also off code generation now: hand-maintained, with scripts/check_drift.py catching what the generator used to prevent.

Major bump because of the removals. Supersedes #31, which was numbered 2.6.0.

Upgrade impact

Change	Affects	Action
Agents API removed	Callers of you.agents*	Pin youdotcom<3, or call POST /v1/agents/runs directly
search_helpers, you.search_post() removed	Callers of either	Use you.search()
__gen_version__, SPEAKEASY_GENERATOR_VERSION removed	Anything reading generator metadata	Use __version__
Empty api_key_auth raises	os.getenv("YDC_API_KEY", "")	Drop the "" default
Context managers close both transports	Sync and async calls on one instance	One instance per flavor
search(language=None) sends no language	Explicit language=None	Omit the argument to keep EN

Everything else in this release is additive. you.search.unified() and you.contents.generate() continue to work behind shims that emit DeprecationWarning.

Architecture

One class, direct methods

The sub-SDK layer is gone. Search, ContentsSDK, Agents, and Runs were each BaseSDK subclasses reached through a lazy-import mechanism on You: a _sub_sdk_map, a dynamic_import() helper with its own retry-on-KeyError loop, and __getattr__ / __dir__ overrides to make the attributes appear. A call spent three hops getting to the HTTP client, and the machinery defeated static analysis on the way.

# 2.5.x
you.search.unified(query=..., language=models.Language.EN, include_domains="a.com,b.com")

# 3.0.0
you.search(query=..., language="en", include_domains=["a.com", "b.com"])

Every operation is now a method on You. The dynamic import machinery is deleted outright, signatures take plain strings instead of enum imports, and domain lists are lists rather than comma-joined strings. Async is a real method with a real signature, not a **kwargs forwarder. The old spellings survive as thin deprecation shims that translate arguments and delegate.

Hand-maintained, with drift detection

Dropping Speakeasy means dropping the guarantee that the SDK matches the published spec. That guarantee is worth replacing rather than losing, so scripts/check_drift.py now diffs endpoints, server URLs, enum values, request parameters, and response fields against the live OpenAPI documents on every PR and weekly on a schedule. Codegen enforced conformance by construction; this enforces it by observation, and reports rather than rewrites.

Breaking changes

Agents API removed

you.agents(), you.agents_async(), the you.agents.runs sub-SDK shim, and all associated model and error classes are deleted. The endpoint itself is unaffected. Only SDK support is withdrawn.

Empty API key is rejected at construction

# 2.5.x, silently fell through to YDC_API_KEY / YOU_API_KEY_AUTH
You(api_key_auth=os.getenv("YDC_API_KEY", ""))

# 3.0.0, ValueError naming the likely cause
You(api_key_auth=os.getenv("YDC_API_KEY"))   # None requests the env lookup

Every endpoint requires a key, so "" was never a meaningful argument. It indicates a key was expected and did not arrive. Rationale for rejecting rather than ignoring is under Review notes.

Callables are resolved lazily and therefore validated on first use.

Context managers release both transports

You instantiates a sync and an async transport. Previously __exit__ closed only the sync client and __aexit__ only the async one, leaking whichever the block did not use. Both now close both.

# No longer valid: the transports are closed on block exit
with You(api_key_auth=key) as you:
    you.search(query="...")
await you.search_async(query="...")

Caller-supplied transports are still never closed by the SDK.

search(language=...)

Call	2.5.x	3.0.0
you.search(query=q)	EN	EN
you.search(query=q, language="fr")	FR	FR
you.search(query=q, language=None)	EN	field omitted

There was previously no way to issue an unfiltered query.

Added

Answer API

res = you.answer(query="What caused the 2008 financial crisis?")
res.answer                    # markdown with inline [[1, 2]] citations
res.citations[0].source       # source URL
res.citations[0].excerpts     # supporting excerpts
res.results.web               # results used during synthesis

POST /v1/answer on api.you.com, sync and async, with freshness, country, language, and the three domain controls. Full error coverage including 402.

PaymentRequiredResponseError

First-class 402 handling with the quota fields parsed out: upgrade_url, limit, used, period, reset_at.

Case-insensitive enum parameters

country, language, safesearch, livecrawl, livecrawl_formats, and freshness accept plain strings in any case and normalize to the casing the API expects. Enum members continue to work. This behavior was already documented; it is now implemented. The same path corrects the separator in uppercase date ranges (2026-01-01TO2026-02-01 becomes ...to...).

Expanded 422/500 models

UnprocessableEntityResponseErrorData gains detail (FastAPI) and errors (JSON:API) alongside error; InternalServerErrorResponseData gains errors. All observed response shapes now deserialize. Additive.

Drift detection

scripts/check_drift.py, described under Architecture. Non-blocking on every PR, scheduled weekly, and it files or updates a single tracking issue when it finds something.

Security

Debug logging emitted the API key in plaintext. Authorization, X-API-Key, Cookie, and Set-Cookie are now redacted before request and response headers reach the logger, on both transports.

Debug logging is off by default, since get_default_logger() returns a NoOpLogger unless YOU_DEBUG is set, so a default configuration never wrote these values anywhere. The exposure was limited to callers who deliberately enabled debug output, either through YOU_DEBUG or by passing their own debug_logger. For those callers the key appeared in plaintext in whatever sink the logger was wired to. If that describes your deployment and those logs left the host, rotate the key.

Fixed

• Teardown could mask the caller's exception. A failing client close inside __exit__ propagated in place of whatever exception was leaving the with block, so the user saw a teardown error instead of their own. Now guarded, consistent with close_clients.
• SDKConfiguration.retry_config had a non-functional default. The field used pydantic.Field(default_factory=...) on a stdlib @dataclass, which does not interpret FieldInfo and left the descriptor itself as the default. Now dataclasses.field.
• Security.serialize_model never matched its own field. optional_fields contained "ApiKeyAuth" against a field named api_key_auth, so a None key was serialized rather than omitted.
• _populate_from_globals compared strings by identity. is not in place of !=, correct only while the strings happen to be interned.
• Async methods were untyped. search_async() and contents_async() were **kwargs: Any wrappers, erasing their signatures for type checkers and IDEs. They are now the implementations, with explicit parameters. This also resolved the one pylint error in the tree.
• Test transports leaked. 72 unclosed sockets across the suite. Ownership moved to the shared test factories, and filterwarnings plus a gc.collect() in teardown now fail the build on a regression.

Internal

Speakeasy removal is complete: all generation banners, YDCUserAgentOverrideHook, _hooks/registration.py, overlays/python_overlay.yaml, and the .speakeasy/ gitignore entries. __user_agent__ derives from the resolved __version__. Custom user agents set via sdk_configuration.user_agent continue to be honored.

Dead code removal takes mypy's footprint from 105 source files to 80: agent models and errors, 36 orphaned doc files, and Go handlers for agents and GET /v1/search.

The README is rewritten for a hand-maintained SDK, 663 lines down to 403, organized by capability rather than by mechanism. A LICENSE file is committed for the first time.

CI

• Mock server readiness is polled against /_mockserver/health and fails the job on timeout, instead of proceeding into misleading test failures.
• Dev tooling installs from the pyproject dependency group rather than a duplicated list in the workflow. The two had already diverged: pyright is declared in the group but was never installed or run in CI.
• pylint gates rather than running under continue-on-error. --enable=E covers the error tier, undefined names and bad call signatures and unreachable code, which is the same class mypy already gates on, and a step that cannot fail cannot enforce it. The check pays for itself here: the untyped-async defect under Fixed surfaced as E1125.
• The drift workflow updates its existing issue instead of filing a duplicate weekly, renders its output correctly, and distinguishes a broken checker (exit 3, job fails) from genuine drift (exit 1) and a transient fetch failure (exit 2). Previously an internal error exited 1 and would have been filed as drift.
• dependabot moved from the pip ecosystem to uv, which is what actually maintains uv.lock.
• Matrix widened to Python 3.10 through 3.13, and concurrency added.

Verification

Unit + mock server tests	249 pass (154 before)
Performance tests	29 pass
mypy	clean, 80 source files
pylint	10.00/10
Drift check	clean against live specs
Matrix	3.10, 3.11, 3.12, 3.13

New coverage targets what previously shipped untested: header redaction, empty-key rejection, dual-transport teardown and its exception-masking property, and the normalization and language matrices including the deprecated shim path.

Every README code example was executed against a mock transport rather than eyeballed, and every documentation link was resolved with a control request to confirm the docs host returns 404 for bad paths rather than an SPA shell.

Review notes

Three items are judgment calls rather than mechanical fixes, and are the ones worth scrutiny:

1. Rejecting an empty API key is a deliberate behavior change. The alternative, treating "" as an opt-out, was considered and rejected: no endpoint supports unauthenticated access, so the only reachable outcome was a 401, and an immediate ValueError names the defect better than a delayed HTTP error.
2. Closing both transports on either exit fixes a leak but ends mixed sync/async use of a single instance. Documented in MIGRATION with the supported pattern.
3. Gating on pylint is safe only while the tree stays clean. The <5 pin bounds new checks to a dependabot PR rather than an unrelated feature branch.

[factory-droid]

Droid finished @tyler5673's task —— View job

---

---

Review summary

The PR is a large, well-structured v3 surface refactor with drift-checking and expanded test coverage, and no high-confidence correctness or security issues stood out in review. One README warning line still contradicts the new credential-redaction behavior for debug logging.

[factory-droid]

Droid finished @tyler5673's task —— View job

---

---

Review summary

Overall the v3.0.0 refactor looks solid and well-tested. One concrete correctness bug remains in query param serialization merging, and two small hardening items are worth addressing (clearer lifecycle error when reused after close, and percent-encoding path parameters to prevent path injection).

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Review summary

Overall the v3.0.0 refactor looks solid and well-scoped. One CI-blocking issue stands out: the workflow’s dependency-group install command is missing a target, which is likely to fail before tests run.

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Droid finished reviewing PR #32.

---

Review summary

The v3.0.0 refactor looks solid and well-tested. One small documentation issue remains: the README debug logging snippet is missing an import logging.

Posted 1 inline comment.

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Droid finished reviewing PR #32.

---

Review summary

No candidate inline comments were provided for Phase 2 validation, so nothing was posted. At the current head SHA, no high-confidence, actionable correctness or security issues remain outstanding in this PR.

Posted 0 inline comments.

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Droid finished reviewing PR #32.

---

Review summary

No candidate inline comments were provided for Phase 2 validation, so nothing was posted. At the current head SHA, no high-confidence, actionable correctness or security issues remain outstanding in this PR.

Posted 0 inline comments.