Generate SDK from the Omni OpenAPI spec

[jdavidson]

Summary

Replaces the hand-written OmniAPI class (~30 endpoints, drifted from the API) with a client generated from the official OpenAPI 3.1 spec — 195 operations across 22 resource groups, 597 typed models, sync + async — plus a small hand-written helper layer for the query → pyarrow flow.

How it works

• spec/openapi.json is vendored from the omni repo (also served at <instance>/openapi.json).
• scripts/preprocess_spec.py collapses zod-to-openapi allOf description wrappers and stubs ~15 recursive document-layout/vis schemas as free-form dicts (the only spec constructs openapi-python-client can't model).
• scripts/generate.sh regenerates omni_python_sdk/ from the spec (deterministic via pinned PYTHONHASHSEED), preserving the hand-written omni_python_sdk/helpers.py.
• CI runs the test suite on Python 3.10/3.12 and a drift check that regenerates from the checked-in spec and fails on any diff.

Breaking changes (v1.0.0)

• OmniAPI is gone. client_from_env() + run_query_blocking() in omni_python_sdk.helpers cover the old query flow; everything else is omni_python_sdk.api.<tag>.<operation>.sync(client=client, ...). Migration table in the README.
• Errors now raise (httpx exceptions / typed responses) instead of printing and returning None.
• Python floor moves 3.9 → 3.10; packaging moves to pyproject.toml (hatchling), and the broken dotenv dependency name is fixed (python-dotenv).
• Known gap: the PNG response of GET /api/v1/ai/jobs/{jobId}/vis is omitted (generator doesn't support image/png); the old /embed/sso/generate-url endpoint isn't in the public spec — the embed example calls it via the raw httpx escape hatch.

Examples & tests

• All examples ported; examples/model.py previously called a method that didn't exist (update_field) and now works via models_update_field.
• New pytest suite: client smoke tests, an all-195-endpoints import check, and mocked-transport tests for the NDJSON + Arrow IPC query decode. Existing semantic-view example tests still pass.

Verification

• pytest — 15 passed (fresh venv, editable install)
• examples/tests unittest suite — 6 passed
• scripts/generate.sh run 3× → identical output (drift check is stable)
• All examples compile; no OmniAPI references remain
• Live smoke test against a real instance — passed: whoami, models_list (20 models), topic fetch, and a LIMIT-1 query decoded to a 1×1 pyarrow.Table

🤖 Generated with Claude Code

[jdavidson]

For reviewers — how to review this PR: generated files are now marked linguist-generated (collapsed by default in the Files tab). The reviewable surface is just: spec/openapi.json provenance, omni_python_sdk/helpers.py, scripts/, tests/, examples/, pyproject.toml, workflows, and the README — roughly 1,500 lines. The generated ~85k lines don't need eyes: CI's drift check regenerates from the checked-in spec and fails on any difference, so the generated code is provably a pure function of the spec.

Also added since the PR opened: spec/provenance.json (records the omni repo commit each spec sync came from), dropped the derived openapi.processed.json from version control, and documented the generated-code review contract + semver policy in the README.