feat(api): add the itis_sumo.api consumer contract (cross-validate, grid/axes evaluation, Sobol, correlation, uncertainty propagation, MOGA, sampling)

[JavierGOrdonnez]

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Pull request overview

Adds a new consumer-facing API layer (itis_sumo.api) that exposes “tabular-in / typed-results-out” workflows (cross-validation, axes/grid evaluation, Sobol, correlations, uncertainty propagation, MOGA, and sampling), backed by a fit-then-query session engine and enforced by contract + integration tests. This aligns the codebase with the SPEC’s “consumer contract” boundary (no Dakota plumbing, no job vocabulary, stable error taxonomy, and controlled run-dir lifetimes).

Changes:

• Introduces itis_sumo.api surface: typed dataclasses, stable error taxonomy, and workflow entrypoints backed by an internal SumoSession.
• Extends evaluation internals to support manual uncertainty propagation with predictive uncertainty and adds uncertainty-summary statistics.
• Adds extensive contract/integration tests and updates docs/spec/navigation to reflect the new consumer API and vocabulary.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
uv.lock	Locks typing-extensions for Python < 3.11.
pyproject.toml	Adds typing-extensions dependency marker for Python < 3.11.
src/itis_sumo/evaluate/funs_evaluate.py	Adds manual UQ propagation with predictive uncertainty + uncertainty summarization; threads seed / has_eval_id_column through CV; adjusts Sobol handling of unsanitized names.
src/itis_sumo/evaluate/init.py	Re-exports export_sumo_model / import_sumo_model.
src/itis_sumo/core/init.py	Re-exports model-store APIs alongside Dakota primitives.
src/itis_sumo/api/init.py	Defines the public consumer API surface and __all__.
src/itis_sumo/api/errors.py	Introduces stable public error taxonomy (SumoError and subclasses).
src/itis_sumo/api/types.py	Adds frozen dataclass types for configs and workflow results.
src/itis_sumo/api/_session.py	Implements internal fit-then-query session with validation, run-dir lifetime rules, and engine error translation.
src/itis_sumo/api/workflows.py	Adds consumer workflow functions (CV, axes/grid, Sobol, correlations, uncertainty, optimize, sampling helpers).
tests/test_dakota_funs_evaluate.py	Extends tests for uncertainty summarization and reformats existing tests.
tests/test_api_workflows.py	Adds end-to-end integration tests for the consumer API workflows.
tests/test_api_contract.py	Adds contract tests enforcing public surface, vocabulary, error taxonomy, result shape, and run-dir lifecycle.
SPEC.md	Documents VOCAB and the consumer contract; updates roadmap entries reflecting the API spine.
mkdocs.yml	Adds Glossary and Consumer API pages to navigation.
docs/reference/glossary.md	Documents canonical vocabulary and domain vs distribution split.
docs/reference/api.md	Documents consumer API usage, workflows, config, and error taxonomy.
examples/headless_smoke.py	Formatting updates for readability.
docs/tutorials/getting-started.md	Updates install note + formatting adjustments in examples.
docs/tutorials/examples.md	Formatting adjustments in examples.
docs/how-to/sensitivity-analysis.md	Formatting adjustments in examples.
docs/how-to/moga.md	Formatting adjustments in examples.
docs/how-to/cross-validate.md	Formatting adjustments in examples.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.