[th0rntwig]

🔴 Review tier: HIGH — human review required

• Contract: adds SDK methods and DTOs, and makes CirrusMetadata fields optional
• Release: merging to main publishes to PyPI
• Size: 4 files, +1368/−29, of which about 380 lines are tests
• Unverified: tested against mocks, not a deployed gateway

What this does

Adds wiki batch search, entity linking and QID lookup to the Python SDK, on both WikiAPI and AsyncWikiAPI:

Method	Route
search_wiki_batch	POST /v1/wiki/search/batch
link_entity	GET /v1/wiki/link-entity
link_entity_batch	POST /v1/wiki/link-entity/batch
get_entity	GET /v1/wiki/entity/{qid}
get_entity_batch	POST /v1/wiki/entity/batch

search_wiki also gains has_wikidata.

Contract

• Linking defaults match the API: relevance_threshold 0.40, ambiguity_margin 0.05, allow_ambiguous true, n_candidates 5, include_candidates false. Batch settings go in the request body.
• DTOs mirror the served contract: 235 WikidataMetadata fields in the same order as stories-service and the gateway, with all three chunk IDs declared.
• Absent values are None: there is no None-exclusion, so a dump includes unset fields as nulls.
• extra="allow" on WikidataMetadata and its value models: a property served after a caller's SDK version still arrives on model_extra. stories-service and the gateway keep the metadata model closed, because they decide what is public.
• Range limits stay on the server: n_candidates, thresholds and batch size vary by route or plan, so the gateway rejects out-of-range values. The SDK checks only empty entity names, empty QIDs and that entity_types and entity_descriptions match entities in length.

Worth checking

• Callers must check link_status before trusting linked_entity. It is null for no_match, and for ambiguous when allow_ambiguous is false.
• search_wiki defaults to n_documents=10, while the gateway defaults to 5. This predates the PR and is unchanged here.

Testing

pytest -q: 228 passed.

Rollout

Merge after the gateway is deployed (api !387), because merging publishes to PyPI and these methods call its routes. mcp-service installs the published SDK, so its new wiki tools can only be verified after this release.

Umbrella: em-hub/features/wiki-entity-linking/README.md

🤖 Generated with Claude Code