ADR-011 — SDK generators, minimum Python and licence (T45)
Status: accepted (2026-11-12). Scope: sdk/python (extractit-sdk), sdk/typescript
(@extractit/sdk) and packages/viewer (@extractit/react). The package names are
provisional: the product name is pending and the rename is a mechanical commit.
Decision
| Piece | Choice | Why |
|---|---|---|
| Python client | openapi-python-client 0.30.0 (MIT) → sdk/python/src/extractit_sdk/_generated |
Active, OpenAPI 3.0/3.1, typed attrs models, sync and async over httpx. |
| TypeScript client | @hey-api/openapi-ts 0.99 (MIT; plugins sdk, typescript, zod) → sdk/typescript/src/generated |
The Studio already generates its client with it (packages/api-gen); one tool, one version. |
| Fern | Discarded | Its repository warns it is no longer maintained and local generation only covers the legacy Docker generator groups. Revisit only if active local generators are published. |
| Hand-written layer | Retries, errors, builder, SSE, webhooks, schema bridges, typed results | The only place with product behaviour; the generators cannot express it. |
| Licence | Apache-2.0 for the SDKs and the viewer | Same as the core; generated files carry the SPDX header. |
The generated code is versioned and regenerated by one command (make sdk-regen, i.e.
python3 sdk/scripts/regen.py); the sdk-regen CI job regenerates it from openapi/openapi.json
and fails on any git diff. The generator versions are pinned, so a generator upgrade is a visible
commit.
The snapshot is normalized before generation (sdk/scripts/prepare_openapi.py)
FastAPI emits X-Input and X-Output schemas with the same title (ClassifyNode-Input,
ClassifyNode-Output...). Both generators fold the titles to one class name and drop operations
(duplicate models). The script renames them to XInput/XOutput, sets title to the key, removes
inline titles and turns free JSON maps into additionalProperties: true. openapi/openapi.json is
never modified. With it, 119/119 operationIds are generated with no warnings (hypothesis H4
validated from the first day, against the OpenAPI of T12 and the routers of T17/T26/T28/T34/T39).
Python minimum is 3.11, not 3.10
The generated client imports httpx2 (needs Python ≥ 3.11) and typing.Self. The research allowed
this fallback ("sube el mínimo y se anota en el ADR"): requires-python = ">=3.11", matrix 3.11–3.13.
The core project already requires 3.11.
Coverage and exemptions
scripts/check_sdk_coverage.py maps every operationId of the snapshot to a method of each SDK
(generated function, or the ergonomic wrapper that replaces it) and exits 1 on any operation
without one. sdk/exemptions.toml lists only the SSE endpoint (stream_run_events), implemented by
hand (sse.py/sse.ts: fetch streaming, Last-Event-ID, de-duplication by sequence) and tested;
it is marked pending-contract because the endpoint is not in the snapshot until T27 lands.
Consequences
max_retries=3means three retries (up to four attempts); 503, 503, 200 is three attempts.parse(tier="auto")of the builder maps toParseConfig{profile: "default"}(the node config is closed and has notier).- The Python layer depends on
httpx2(the generated client's transport); tests injecthttpx2.MockTransportbecauserespxdoes not patchhttpx2. - Python imports from the core are forbidden for
extractit_sdk(sdk/python/.importlinter). - The viewer logic (
geometry,shapes,PolygonOverlay) lives in@extractit/reactand the Studio consumes it as a workspace dependency;web/src/viewer/{geometry,shapes}.tsre-export it. - Nothing is published from this repository: the
sdk-publish-*jobs only run onv*tags.
Amendment (T47): the MCP server is generated from the same OpenAPI
Decision. The MCP server is generated with FastMCP (Apache-2.0, 4.2.0 pinned) from the
operations of openapi/openapi.json tagged mcp (white list: RouteMap(tags={"mcp"}, TOOL) then
RouteMap(EXCLUDE)), named by operationId, plus four curated tools that are not routes
(extract_document, diff_versions, explain_field, request_approval). It replaces the
earlier plan of a fully hand-written MCP server: business logic lives once, in the API, and tools
call it in process with the caller's identity, so scopes, RLS, limits and RFC 9457 errors are
inherited. src/extractit/mcp/tool_inventory.json pins the tool set; CI fails on drift.
Hypothesis H3 (validated on 2026-11-13). A 5-route spike (get_me, list_projects,
get_project, list_workflows, get_workflow) with FastMCP 4.2.0: tag filtering, stable names,
annotations through mcp_component_fn, the stateless Streamable HTTP mode, Middleware
(on_list_tools/on_call_tool), MultiAuth and RemoteAuthProvider all behave as documented.
Plan B (tools written by hand over the SDK, +1.5 d) was not needed. Findings: FastMCP 4 uses
httpx2 (its ASGI transport carries the in-process calls); the PRM route it builds only exists
with the path suffix and renders root issuers with a trailing slash, so the gateway serves the RFC
9728 document itself on both paths.
Docs portal. MkDocs Material 9.8.x is pinned. Material declares end of life on 2027-05-05 and
recommends Zensical (MIT), which reads mkdocs.yml: the migration is planned for before that date
(swap the builder in make docs, keep pymdownx.snippets, re-check the no-CDN scan). llms.txt
is produced by docs/gen/llms.py (plan B of mkdocs-llmstxt, which is in maintenance).