Skip to content

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=3 means three retries (up to four attempts); 503, 503, 200 is three attempts.
  • parse(tier="auto") of the builder maps to ParseConfig{profile: "default"} (the node config is closed and has no tier).
  • The Python layer depends on httpx2 (the generated client's transport); tests inject httpx2.MockTransport because respx does not patch httpx2.
  • Python imports from the core are forbidden for extractit_sdk (sdk/python/.importlinter).
  • The viewer logic (geometry, shapes, PolygonOverlay) lives in @extractit/react and the Studio consumes it as a workspace dependency; web/src/viewer/{geometry,shapes}.ts re-export it.
  • Nothing is published from this repository: the sdk-publish-* jobs only run on v* 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).