Skip to content

Generate static type stubs for the generic compute engine - #409

Draft
amirabbas-jalali-bentley wants to merge 2 commits into
SeequentEvo:resolve-compute-references-and-outputsfrom
amirabbas-jalali-bentley:add-compute-engine-type-stubs
Draft

amirabbas-jalali-bentley wants to merge 2 commits into
SeequentEvo:resolve-compute-references-and-outputsfrom
amirabbas-jalali-bentley:add-compute-engine-type-stubs

Conversation

@amirabbas-jalali-bentley

@amirabbas-jalali-bentley amirabbas-jalali-bentley commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Description

Part 4 of 6 in the generic compute engine series (stacked on #395 -> #407 -> #408, targeting resolve-compute-references-and-outputs).

ComputeClient resolves topics, tasks, parameters, and hydrated results dynamically from the live discovery catalogue at runtime. This PR adds an offline .pyi stub generator (evo.compute._stubgen), a sanitised point-in-time snapshot of the task catalogue, and a generated engine.pyi + py.typed marker so editors and static type checkers (mypy and pyright) get full autocomplete and static parameter/result checking without changing runtime behavior.

Changes

  • evo.compute._stubgen:
    • python -m evo.compute._stubgen generate (and --check for CI) renders src/evo/compute/engine.pyi offline from packages/evo-compute/stubs/snapshot/ and formats it reproducibly with ruff.
    • python -m evo.compute._stubgen capture captures a sanitised task snapshot from a live discovery endpoint, stripping deployment-specific URLs and keys and skipping scratch test* topics.
    • Emits topic-scoped TypedDict parameter definitions (with ObjectInput / AttributeInput / FileInput shorthands matching ReferenceResolver and SearchNeighborhood structural recognition), TaskResult / ResultNode subclasses for hydrated outputs, and __getattr__ fallbacks so tasks added after the snapshot remain callable without false static errors.
  • Bundled snapshot & py.typed:
    • Ships src/evo/compute/py.typed and src/evo/compute/engine.pyi (98 tasks across 10 topics), which griffe also merges into the MkDocs ComputeClient reference page.
  • SearchNeighborhood wire round-trip: accepts wire-shaped ellipsoid_ranges dictionaries when validating SearchNeighborhood.
  • Makefile & CI: adds make stubs-compute, make check-stubs-compute, make check-types-compute, and a check-stubs job in .github/workflows/on-pull-request.yaml enforcing stub freshness and running mypy and pyright against positive/negative typing fixtures (stubs/checks/usage_ok.py and usage_bad.py).

No breaking changes; runtime execution remains live and discovery-driven.

Testing

  • test_stubgen.py (54 tests) covers determinism, stub freshness against ComputeClient signatures, reference shorthands, topic/name collisions, deep-validation agreement across the snapshot, and real mypy + pyright runs on usage_ok.py / usage_bad.py.
  • evo-compute tests: 776 passed, 2 skipped (54 new, 620 subtests). ruff check, ruff format --check, uv lock --check, and pre-commit hooks pass.

Checklist

  • I have read the contributing guide and the code of conduct

Add offline stub generator (evo.compute._stubgen), py.typed marker,
captured task catalogue snapshot, and generated engine.pyi so static
type checkers and editors get autocomplete and parameter/result checking
for ComputeClient while keeping runtime execution discovery-driven.

Also adds Makefile targets and a CI check verifying stub freshness and
running mypy and pyright against positive and negative typing examples.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant