Contributing and releases

Use uv 0.13.1 or newer. The library and CI support Python 3.10 through 3.15. Documentation tooling requires Python 3.12 or newer; notebook tooling has its own optional Python 3.11+ group. All environments share the root uv.lock.

Reading the core

Follow a model from its class body to its populated instances:

  1. ModelloMetaNamespace in modello/_model.py collects scalar expressions, components, and inherited replacements. compile() produces one _ModelDefinition containing the field paths and scoped equations. Each _Definition keeps an equation together with its origin path, including separate definitions of the same aliased quantity. ModelloMeta attaches this declaration and the compiled annotations to the class.

  2. inspect_model() calls _prepare_problem() in diagnostics.py to bind fresh symbols and create a ModelProblem snapshot. _InputCapture in _inputs.py appends scalar and component observations in that scope. It retains each copied value’s supplied or inferred origin and groups all values from a component under its constructor argument. Preparation does not solve.

  3. Modello.__init__() prepares the problem, generates joint candidates, selects one compatible with the declared assumptions, and calls _populate() to materialize the complete component tree. Symbolic construction accepts undecided assumptions. Diagnostic audits require a checked, closed witness before claiming consistency.

  4. SolutionFamily._prepare() in solutions.py gives the same snapshot an explicit coordinate domain. _FamilyReduction owns the evolving coordinate expressions: first substitute isolated quantities, then eliminate rational affine joins. The family retains all original equations and every field’s domain as predicates, including conditions on eliminated quantities. Backend failures retain the conditions and record a SolutionIssue. cases() audits each finite state before populating a freshly bound model tree.

Shared problem records live in _problem.py. Runtime imports point downwards through records, declarations, input capture, solution families, diagnosis, and the public namespace; reverse type references use TYPE_CHECKING. The GUI and numerical example adapters consume the compiled declaration’s fields.

GUI presentation stays above these layers. Quantity joins a model field to its labels and display units; CheckedCases owns finite alternatives and the observations that distinguish them. Coordinates retains the family’s free quantities and checks point previews or reference sections. FamilyPlot samples a section through validated PlotWindow intervals and audits each candidate against the original model. FamilyView composes these concepts into the browser protocol without turning a preview into an observation.

In the browser, SampleGrid owns sample adjacency and gaps. Flat and surface projections map that grid onto the screen; SampleChart creates the SVG and inspection controls. ChartSession retains chart preferences and discards responses to superseded questions. Keep geometry independent of DOM rendering and keep these presentation types out of the solver.

Validation

Install the locked development environment and run the complete test suite, including doctests:

$ uv sync --locked --dev --group docs --python 3.12
$ uv run --locked --dev pytest

Unset PYTEST_DISABLE_PLUGIN_AUTOLOAD before running pytest if your shell defines it. CI also checks formatting, lint, types, documentation, and both distribution formats. The commands are maintained in AGENTS.md and .github/workflows/ci.yml.

Mirror source packages under tests/ and use test_<module>.py, omitting a module’s leading underscore. Use test_init.py for package entry points and keep repository-wide checks at the test root.

Keep regressions focused on distinct behavior and independent mathematical checks. Refresh dependencies with uv lock --upgrade and commit uv.lock. Dependabot proposes grouped weekly dependency and GitHub Actions updates. Workflows do not schedule rebuilds.

Distribution checks install the wheel outside the checkout, rebuild the source distribution, and repeat the runtime and typing checks. They also exercise the packaged examples and fixtures. Builds use the installed, locked backend. Start with an empty dist directory so the checks receive exactly one wheel and one source distribution.

The wheel bundles the examples modules and fixtures. modello[examples] selects their optional runtime requirements; currently these are satisfied by the standard library and the core SymPy dependency, so the extra’s requirement list is empty. Add future example-specific dependencies to this extra. Package selection and data files belong in the setuptools configuration, independently of dependency selection.

Read the Docs

Open docs/_build/html/index.html to preview the documentation. CI builds Sphinx with warnings as errors. The root .readthedocs.yaml configures the same Sphinx source and documentation dependency group on Python 3.12, following the Read the Docs uv configuration reference.

The existing modello project on Read the Docs tracks master for its latest version and builds pull request previews. Enable version tags after they include the documentation configuration. Project connections and version activation are managed in Read the Docs service settings.

Example guides live under docs/examples/<example>/ beneath the Examples section. Keep each guide focused on the modelling idea it demonstrates. Portfolio modules and fixtures are grouped in examples/portfolio/; examples/data.py, examples/named_members.py, and examples/symbolic.py hold experimental data, named-projection, and numerical-evaluation helpers. Keep example-specific behavior in those layers.

Diagrams use the .. mermaid:: directive from sphinxcontrib-mermaid in reStructuredText pages. The documentation dependency group enables the extension for local, CI, and Read the Docs HTML builds.

Publishing

Publish a GitHub release for a version tag such as v0.2.0. The release workflow runs the full CI matrix, documentation build, and distribution checks on that release commit. It verifies that the tag still points to the commit, normalizes the tag as a package version, and rejects development or local versions. The installed wheel and rebuilt source distribution must both match the release version.

Validated distributions pass through an immutable workflow artifact to a separate publishing job. Only that job receives id-token: write and the pypi environment. Configure PyPI Trusted Publishing for the Code0x58/modello repository, publish.yml workflow, and pypi environment. Active publishing runs for the same release tag are allowed to finish.

When CODECOV_TOKEN is configured, CI uploads coverage and test results to Codecov. The uploads are skipped without the token.