v2.6.0: Direct methods on You, Answer API, keyless search, Speakeasy removal

[tyler5673]

Summary

Version 2.6.0 — major version with breaking changes. Direct methods on You replace sub-SDKs, Answer API added, search_helpers merged into you.search() (keyless-capable), Speakeasy artifacts removed, dev dependencies updated.

Breaking Changes

Sub-SDKs and search_helpers module removed. Methods are now direct on You:

Old (removed)	New
you.agents.runs.create(request=...)	you.agents(request=...)
you.agents.runs.create_async(request=...)	you.agents_async(request=...)
you.search.unified(query=...)	you.search(query=...) (POST /v1/agents/search)
you.search_post(query=...)	you.search(query=...)
you.search_post_async(query=...)	you.search_async(query=...)
you.contents.generate(urls=...)	you.contents(urls=...)
you.contents.generate_async(urls=...)	you.contents_async(urls=...)
search_helpers.search(client, query=...)	you.search(query=...)
search_helpers.search_async(client, query=...)	you.search_async(query=...)

GET /v1/search (you.search.unified()) is removed. POST /v1/search (you.search_post()) is removed. Both are replaced by you.search() which targets POST /v1/agents/search (keyless-capable proxy).

New Features

• you.answer() / you.answer_async() — POST /v1/answer. Synthesized markdown answers with inline citations. Requires API key.
• you.search() is now keyless-capable — targets POST /v1/agents/search. No API key needed for free tier (100 queries/day, count ≤ 50, no livecrawl). With a key, proxy forwards to full search.
• PaymentRequiredResponseError (402) — first-class error class replacing FreeTierLimitError. Structured data: error, message, upgrade_url, limit, used, period, reset_at.
• 422/500 error models expanded — detail (FastAPI array) and errors (JSON:API array) fields added. Backward compatible.

Other Changes

• Host: ydc-index.io → api.you.com for all search/contents endpoints
• Speakeasy removal: All "DO NOT EDIT" disclaimers (101 files), YDCUserAgentOverrideHook (no-op), __gen_version__
• __user_agent__ derived from resolved __version__ at runtime
• Dead code removal: _hooks/registration.py, models/answerop.py, models/searchpostop.py, unused imports
• search() server_url fix: Now respects custom server_url (was hardcoded to SEARCH_POST_OP_SERVERS[0])
• answer() type annotations: country/language aligned to enum types with .upper() normalization
• CI: Removed unused pylint/pyright installs, added mypy step

Dependency Updates (dev only)

• mypy: 1.15.0 → >=2.3.0
• pylint: 3.2.3 → >=4.0.0
• pytest: >=8.0.0 → >=9.0.0
• pytest-asyncio: >=0.24.0 → >=1.0.0
• Runtime deps (httpx, httpcore, pydantic) unchanged — already at latest stable

Test Coverage

• 54 unit tests (MockTransport) — all pass
• 3 mock server keyless tests (Go mock server, no API key) — all pass
• 117 mock server tests (Go) — all pass
• 45 performance tests — all pass
• 5 live keyless tests (real API, no API key) — all pass
• mypy 2.3.0 clean (104 files)

Tickets

• DX-694: SDK keyless search route (/v1/agents/search)
• DX-308: Answer API (you.answer())

Migration

See MIGRATION.md for the full 2.5.0 → 2.6.0 migration guide.

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid finished @tyler5673's task —— View job

---

The PR is solid and well-tested (Answer SDK, keyless search helpers, expanded error models). Main follow-ups are tightening docs to match actual routing behavior and reducing the risk of leaking API keys via debug logging.

[factory-droid]

[P1] Fix changelog claim about default search endpoint

The changelog says the keyless proxy at api.you.com/v1/agents/search “is now the default for all search operations”, but the generated Search SDK methods still target /v1/search (GET/POST). This is likely to mislead users; please scope the statement to search_helpers.search() / search_async().

[factory-droid]

[P1] [security] Redact sensitive data in debug logs

BaseSDK.do_request() logs full request headers and bodies at debug level, which can include X-API-Key and other sensitive data. Even with the new README warning, it’s easy for debug logging to be enabled in real deployments, so redacting known-secret headers (and potentially large bodies) before logging would materially reduce the risk of credential leakage via logs.

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Solid update overall. Remaining follow-ups are to fix CONTRIBUTING dev install docs, avoid eager request/response body materialization in debug logging, and update the README server_url example to https://api.you.com.

[factory-droid]

[P1] Fix dev dependency install instructions

CONTRIBUTING.md recommends pip install -e ".[dev]", but this repo defines dev tools under [dependency-groups].dev (not project.optional-dependencies), so pip will not install pytest/mypy/pylint via that extra. This leaves contributors without the documented tooling unless they happen to install it separately; either add a real dev extra in pyproject.toml or update the docs to the supported install flow (for example uv sync --dev plus editable install).

[factory-droid]

[P2] Avoid eager request/response body materialization for debug logs

BaseSDK.do_request() always calls logger.debug(...) with get_body_content(req) and (for non-streaming) http_res.text; even when the default NoOpLogger is in use, those arguments are still evaluated, adding overhead and potentially materializing large payloads on every request. Consider guarding the body/response logging behind a real enabled check (for example, only compute/log body when debug_logger is not the no-op logger), while keeping exception logging intact.

[factory-droid]

[P3] Update README examples to the new api.you.com host

This PR switches the Search/Contents servers from https://ydc-index.io to https://api.you.com, but the README still contains examples that hardcode server_url="https://ydc-index.io" (for example, the per-operation override snippet). Updating those snippets will prevent users from copying an obsolete host and getting unexpected routing failures.

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Validated the remaining review items: the client context managers still leave one owned httpx client unclosed, keyless live tests can run during default test runs, and a couple of docs issues (dead anchors, incorrect Optional typing) remain.

[factory-droid]

[P1] Ensure both HTTP clients are closed for sync/async context managers

You.__init__ creates both a sync httpx.Client and an httpx.AsyncClient when callers don’t supply them, but __exit__ only closes the sync client and __aexit__ only closes the async client. This leaves one owned client unclosed for common usage (with You() as you: leaks the async client, async with You() as you: leaks the sync client), which can retain open connections and trigger resource warnings; consider closing/unsetting both clients in both exit paths, or lazily creating the async client only when needed.

[factory-droid]

[P1] Prevent keyless live tests from running in default unit test runs

TestLiveSearchHelpers now runs without an API key and makes real network calls, but the repo’s test runner (scripts/run_tests.sh) executes pytest tests/ -v without ignoring tests/test_live.py. As a result, a standard unit test invocation can start failing or hanging in CI and developer environments without outbound network access; gate keyless live tests behind an explicit opt-in (env var/pytest mark) or keep all of test_live.py skipped by default.

[factory-droid]

[P1] Fix broken anchors for new direct methods in You SDK docs

The “Available Operations” list adds answer, create_run, search_unified, and generate_contents links (for example #create_run), but there are no corresponding sections in this doc, so those links (and the README links that point here) are dead. Add the missing sections/anchors or change the links to point at the actual pages so users can navigate to the new API surface.

[factory-droid]

[P1] Correct AnswerRequestBody docs for optional domain lists

include_domains, exclude_domains, and boost_domains are documented as List[str], but the SDK model treats them as optional and omits them when unset. Updating the docs to Optional[List[str]] avoids misleading users into thinking they must always provide these fields or that empty lists are semantically required.

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Two doc and model hygiene follow-ups remain: avoid mutable defaults in the new Answer response models by using Field(default_factory=...), and align the migration guide’s “major version” wording with the actual 2.6.0 SemVer versioning (or bump to 3.0.0 if intended).

[factory-droid]

[P2] Prefer Field(default_factory=...) for Answer model defaults

These new Answer models use =[] and AnswerResults() as defaults (AnswerResults.web, AnswerResponse.citations, AnswerCitation.excerpts, AnswerSearchResult.snippets, AnswerResponse.results). Switching to pydantic.Field(default_factory=list) (and Field(default_factory=AnswerResults) for results) avoids mutable-default footguns and keeps the model definitions consistent with common pydantic style.

[factory-droid]

[P2] Migration guide: “major version” wording vs SemVer 2.6.0

The 2.5.0 → 2.6.0 section calls this a “major version release,” but the package version is 2.6.0 and the changelog explicitly states Semantic Versioning; consider rephrasing this as “breaking changes” (or bumping to 3.0.0 if a semver-major is intended) to avoid confusing upgrade guidance.

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Overall the PR looks solid and consistent across SDK surfaces, with broad doc/test updates to support the new direct methods. The main remaining issue is a docs example that can raise an IndexError on valid responses with empty citation excerpts.

[factory-droid]

[P1] Guard against empty citation excerpts in docs example

The Answer API can omit excerpts or return an empty list (the model defaults excerpts to []), so indexing citation.excerpts[0] in this example can raise IndexError; use a conditional fallback before printing.

Suggested change

	print(f" [{citation.source}] {citation.excerpts[0]}")
	excerpt = citation.excerpts[0] if citation.excerpts else ""
	print(f" [{citation.source}] {excerpt}")

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Found four small, high-signal follow-ups: the Answer API model docs should mark several optional fields as Optional, and CI installs mypy/pylint/pyright without running them.

[factory-droid]

[P1] Fix AnswerCitation.excerpts type in docs

AnswerCitation.excerpts is Optional[List[str]] in code (it can be missing/null), but the docs currently show it as List[str], which is misleading for users and static type checkers.

Suggested change

	| `excerpts` | List[*str*] | :heavy_minus_sign: | Verbatim excerpts from the cited source that support the answer. |
	| `excerpts` | Optional[List[*str*]] | :heavy_minus_sign: | Verbatim excerpts from the cited source that support the answer. |

[factory-droid]

[P1] Fix AnswerSearchResult.snippets type in docs

AnswerSearchResult.snippets is Optional[List[str]] in code (it can be missing/null), but the docs currently show it as List[str], which can lead to incorrect client assumptions.

Suggested change

	| `snippets` | List[*str*] | :heavy_minus_sign: | Text snippets from the search result that preview its content. |
	| `snippets` | Optional[List[*str*]] | :heavy_minus_sign: | Text snippets from the search result that preview its content. |

[factory-droid]

[P1] Mark AnswerResponse optional fields as Optional in docs

In code, AnswerResults.web, AnswerResponse.citations, and AnswerResponse.results are all optional, but the docs currently present them as non-optional types, which can cause confusion and incorrect type expectations.

Suggested change

	| `web` | List[[models.AnswerSearchResult](../models/answersearchresult.md)] | :heavy_minus_sign: | All web search results considered during answer synthesis. |
	## AnswerResponse
	| Field | Type | Required | Description |
	|-------|------|----------|-------------|
	| `answer` | *str* | :heavy_check_mark: | The synthesized response with numbered inline citations that reference items in the `citations` array. |
	| `citations` | List[[models.AnswerCitation](../models/answercitation.md)] | :heavy_minus_sign: | The sources cited in the answer, in citation order. |
	| `results` | [models.AnswerResults](#answerresults) | :heavy_minus_sign: | Search results grouped by result type. |
	| `web` | Optional[List[[models.AnswerSearchResult](../models/answersearchresult.md)]] | :heavy_minus_sign: | All web search results considered during answer synthesis. |
	## AnswerResponse
	| Field | Type | Required | Description |
	|-------|------|----------|-------------|
	| `answer` | *str* | :heavy_check_mark: | The synthesized response with numbered inline citations that reference items in the `citations` array. |
	| `citations` | Optional[List[[models.AnswerCitation](../models/answercitation.md)]] | :heavy_minus_sign: | The sources cited in the answer, in citation order. |
	| `results` | [Optional[models.AnswerResults]](#answerresults) | :heavy_minus_sign: | Search results grouped by result type. |

[factory-droid]

[P3] Avoid installing unused lint/type tools in CI

This workflow only runs pytest, but it also installs mypy, pylint, and pyright, which adds CI time and can introduce avoidable breakage when those tools release new versions; either add steps to run them, or keep installs limited to what this job executes.

Suggested change

	pip install mypy pylint pyright pytest pytest-asyncio
	pip install pytest pytest-asyncio

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid finished @tyler5673's task —— View job

---

Most items in this batch were already raised in existing PR comments. The remaining high-impact follow-up is to keep CI offline-safe by excluding tests/test_live.py, since it now contains keyless tests that perform real network calls by default.

[factory-droid]

[P1] Exclude live API tests from CI runs

The CI job runs pytest tests/ without ignoring tests/test_live.py, and this PR added keyless live tests that make real network calls even when no API key is set, which will make CI flaky/offline-failing and can burn rate limits; align CI with CONTRIBUTING by ignoring the live test module (or add an explicit opt-in marker and exclude it in CI).

Suggested change

	run: pytest tests/ -v --tb=short -x
	run: pytest tests/ -v --tb=short -x --ignore=tests/test_live.py

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid encountered an error —— View job

---

Droid is reviewing code and running a security check…

[factory-droid]

Droid finished @tyler5673's task —— View job

---

The PR is cohesive and well-scoped (direct You methods, Answer API, keyless search routing, and expanded error models). The main remaining issues are small but user-facing, a typing mismatch in answer()’s locale parameters and Answer docs that should more clearly state the API key requirement.

[factory-droid]

[P1] Align Answer country/language types with accepted strings

You.answer() is typed as country: Optional[models.Country] / language: Optional[models.Language], but the implementation still treats them as strings (isinstance(..., str) with .upper() normalization) and the docs present them as Optional[str]; this mismatch breaks static typing for callers passing plain strings and is inconsistent with You.search() which is typed as Optional[str]. Consider changing these parameters to Optional[str] (or Optional[Union[str, models.Country]] / Optional[Union[str, models.Language]]) to reflect actual supported inputs.

[factory-droid]

[P1] Document that Answer requires an API key

This page doesn’t explicitly call out that you.answer() requires an API key (unlike you.search(), which is keyless-capable), so users can easily copy/paste the snippet without realizing why they get auth failures. Add a short “Requires API key” note near the overview (and optionally near the example) to prevent confusion.