Split gems into gems_craft/gems_runner (alternative to #243)

[aoustry]

Process ID

Process: GP-01

Description

Alternative split of the monolithic gems package into gems_craft and gems_runner, proposed as a counter-option to #243.

Both PRs agree on the goal: separate the solver-independent parts of GEMS from solve-time execution. They disagree on where the line goes.

#243's boundary is parsing vs. everything else. gems_craft there contains only the Pydantic YAML-schema layer (*Schema classes). The resolved domain objects — Model, Library, System, Component, PortsConnection — and the entire expression/ package (AST, parsing, linearity/indexing analysis) all move to gems_runner, bundled with the solver.

This PR's boundary is solver-dependency, not parsing. gems_craft contains everything with no dependency on linopy/xarray/highspy:

• The full domain model: model/ (Model, Library, Port*, Constraint, Parameter, Variable), study/ minus runner.py (System, Component, PortsConnection, Study, DataBase, resolve_components.py, folder.py, scenario_builder.py)
• YAML schema/parsing (as in Feature/submodule gems craft #243)
• optim_config/ (pure Pydantic + TYPE_CHECKING-only refs, no solver import)
• The structural half of expression/ — AST, parsing, degree.py/is_linear, indexing.py, uses_sum_connections_on.py — everything except evaluate.py

gems_runner is left with only genuinely solve-time code: expression/evaluate.py (its dual()/reduced_cost()/variable() handlers are solver-output-shaped, not general-purpose math — the one deliberate exception), simulation/*, session/*, study/runner.py, and the gemspy CLI (main/).

Why this matters: a System/Component CRUD-and-query API (editing systems, filtering components by properties, walking peer components through port connections) needs the resolved domain model, not the raw parsed schema. Under #243's split, building that API on gems_craft would require depending on gems_runner — pulling in the solver stack just to read/edit a system. Under this split, gems_craft is a complete, self-contained base for that API.

Packaging: kept as a single distribution (one pyproject.toml), not a two-wheel monorepo — lower risk, no CI/tooling restructuring. linopy/xarray/highspy move to a new runner optional-dependency extra so pip install gemspy alone never pulls in the solver stack, verified by installing gems_craft in a clean venv with zero extras and importing it successfully.

Impact Analysis

• expression/, model/, study/, optim_config/, simulation/, session/, main/ are all affected — file moves only, no logic changes. Every gems.* import across src/ and tests/ was mechanically rewritten to gems_craft.* / gems_runner.*.
• gems_runner.expression.evaluate gained two absolute imports (gems_craft.expression.expression, .indexing, .visitor) in place of what were same-package relative imports in the monolith, since evaluate.py now lives in a different package than the rest of expression/.
• pyproject.toml: dependencies trimmed to gems_craft's actual deps (numpy, pandas, PyYAML, pydantic, anytree, antlr4-python3-runtime); added [project.optional-dependencies].runner for linopy/xarray/highspy; gemspy script entry point repointed to gems_runner.main.main:main_cli; [tool.mypy] packages/overrides updated.
• .github/workflows/ci.yml: install step now requests --extra runner; coverage flags updated from --cov gems to --cov gems_craft --cov gems_runner.
• Solver output values: no change — this is a pure module-boundary refactor, no expression/model/simulation logic was touched.

Checklist

• Unit tests pass (pytest) — 547 passed, 1 xfailed (full suite incl. --group solvers)
• Type checking passes (mypy) — 60 source files, clean
• Formatting passes (black, isort)
• pyproject.toml version bumped if applicable — left alone per docs/agents/python-convention.md (version bumps are handled via the feat(release): commit workflow, not manual edits); changelog entry added under [Unreleased]
• AGENTS.md reviewed for impact and updated if needed — architecture section rewritten for the two-package structure

---

Generated by Claude Code