Contributing and releases

This guide is for contributors updating code, examples, and documentation. Start with the locked environment and validation commands, then follow the PR review steps. Use the architecture sections to locate the implementation of a behavior; the final sections cover documentation hosting and releases.

Use uv 0.13.1 or newer. The library and CI support Python 3.11 through 3.15. Documentation tooling requires Python 3.12 or newer. Notebook tooling is an optional dependency group. All environments share the root uv.lock. The docs group includes pandas and Polars for Sphinx-tested recipes, which the ordinary pytest suite excludes.

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
$ uv run --locked --group docs sphinx-build --fail-on-warning --keep-going \
    --builder=doctest docs docs/_build/doctest
$ uv run --locked --group docs sphinx-build --fail-on-warning --keep-going \
    --builder=html docs docs/_build/html

Use .. doctest:: with imports, setup, and expected results. Named groups give examples independent namespaces, as in the DataFrame recipes. Use .. testcode:: and .. testoutput:: for non-interactive examples. Sphinx runs these blocks with the docs dependencies; pytest’s --doctest-glob=*.rst also runs interactive prompts outside the recipe page. For a focused check, run uv run --locked --dev pytest --no-cov docs/modelling.rst.

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.

When Node.js is available, pytest also exercises the frontend’s proposal state against real Flask response fixtures. It covers bulk vector edits, subsequent coordinate edits, restoring a vector while retaining a separate target, and preserving the applied case after rejection. This optional check does not replace visual browser review and adds no runtime dependency to the library.

Keep regressions focused on distinct behavior and independent mathematical checks. Share immutable cases and baseline results through module-scoped fixtures when several tests use the same inputs. Keep fresh execution where it checks that replacement or assumption changes preserve the earlier branch. Combine overlapping checks instead of repeating full symbolic or numerical studies; retain distinct boundary cases and method gates.

CI runs the complete suite on every supported Python version. Python 3.14 collects full-library coverage; the other versions run without tracing. Test jobs retain the 15-minute limit and export their full-suite results. The full local coverage command in AGENTS.md remains the required validation before committing.

Measure slow tests before changing their implementation:

$ uv run --locked --dev pytest --no-cov --durations=25 \
    tests/modello/contrib/test_verification*.py
$ uv run --locked --dev python -m cProfile -o /tmp/verification-tests.prof \
    -m pytest --no-cov tests/modello/contrib/test_verification_piecewise.py
$ uv run --locked --dev python -c \
    "import pstats; \
    pstats.Stats('/tmp/verification-tests.prof').sort_stats('cumulative').print_stats(25)"

Use the same interpreter and coverage settings for before/after timings. Inspect repeated domain proofs, expression binding, and solver work separately; profiling overhead itself is not a CI runtime measurement. Performance changes must retain source guards, proof scopes, and assumption-context isolation.

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, then install the locked GUI extra and exercise the gallery and its assets. 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.

Review before a PR

Before pushing changes for a PR or creating/updating one, ask the coding agent to spawn a fresh pre_pr_review subagent. It compares the complete branch with the PR’s target branch, including relevant local changes. The reviewer checks documentation and Python changes, then suggests a concise PR title and body describing the final behavior. Address actionable findings and reassess affected areas after further edits or target changes.

For example, ask: “Spawn pre_pr_review to review this branch against origin/master before updating its PR.” For an existing PR, use its actual base branch; the feature branch’s tracking upstream is not its review target.

The custom Codex agent is defined in .codex/agents/pre_pr_review.toml. Its main prompt selects focused documents under .codex/agents/pre_pr_review/ after inspecting the branch. They cover Sphinx documentation, Python code with docstrings and comments, modelling architecture, tests, diagnostic contracts, visual examples, and PR descriptions. Load only the areas relevant to the change. If custom agent roles are unavailable, AGENTS.md instructs the coding agent to pass the same prompt to a general subagent.

Install the Git reminders in this checkout:

$ git config extensions.worktreeConfig true
$ git config --worktree core.hooksPath .githooks

The hook setting applies only to this checkout, including when working in a linked worktree. Check any existing core.hooksPath setting and hooks before replacing them. Repeat setup for new clones or worktrees as needed.

The pre-commit and pre-push hooks print a short prompt asking the coding agent whether a fresh review is needed. They are non-blocking reminders: they do not start a model, read answers from the terminal, or verify that a review took place. AGENTS.md requires the coding agent to complete the review before a PR push or creation/update, including updates made without a Git push.

Reading the core

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

  1. ModelloMetaNamespace in modello/_model.py collects scalar expressions, vectors, 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. _algebra() in _problem.py creates an evaluated view of those equations. _expressions.py resolves directed definitions within local binder scopes, evaluates SymPy operators, and leaves ordinary algebraic cycles for the joint solver. This view is shared by construction, audits, and solution families; the original snapshot remains unchanged. Both the resolver and evaluator use one argument-rebuilding path to retain denominator domains and pending operators. A per-problem memo prevents repeated expansion of shared dependency graphs. Limits remain unevaluated until their free quantities are substituted, preserving exceptional parameter values that generic limit evaluation can discard.

  4. 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.

  5. 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. Independent observations and outputs are substituted in batches; cyclic joins retain a chart coordinate. Remaining operators are checked after observations and conditions have resolved their bounds. 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. ModelProblem.vector_definitions retains complete vector formulas in the same scope. Both GUI equations and LaTeX exports consume this public view instead of reconstructing formulas from scalar constraints. _printing.py adds scoped LaTeX labels; native vector printing remains in vectors.py. Text and LaTeX contexts receive the explicit vector schema, including public and chart aliases. They choose names within the current component without guessing vector identities from their scalar coordinate paths.

Keep behavior for a closed enum on the enum itself. Use match with a final assert_never case so type checking rejects a missing implementation when a member is added. Python 3.11 provides native StrEnum and assert_never. _values.py holds structural input types; _symbols.py owns independent quantity identities and local indices. vectors.py implements immutable scalar containers and finite comprehensions without importing model or GUI machinery. Its shared container reader checks native array rank and matrix orientation for construction and observations. _scalar_expression sympifies scalar inputs without evaluating them; _rebind preserves source denominator domains while renaming declarations. Scalar and model vectors share size and integer-position validation. Vector coordinates use normal scalar field records. _paths.py shares coordinate traversal and bracketed display paths across consumers. The GUI separates layout and permissions, MathML printing, bounded input parsing, and vector summaries under _gui/. Finance and time-series examples stay above these layers.

contrib/verification binds scoped claims to immutable problem snapshots and refreshes definition reports through an opt-in VerificationModel subclass hook. Proof attempts retain parameter guards, inference-rule premises, and unresolved outcomes. Method contracts select the evidence they consume. Numerical and plotting dependencies remain in optional example methods; the symbolic extension imports neither. Report JSON is a descriptive audit export; it cannot reconstruct a context. The record-review example connects exact stationary candidates to a concavity argument, then rechecks the same premises after replacing its response curve.

Keep the extension boundary at evidence and proof policy. Core model declarations must preserve the meaning of their equations before any extension can inspect them. The shared symbolic changes have the following scope:

_reconstruction.py

Rebind and reconstruct expressions without losing operand domains or local binder identities. A held 0*log(x) and a selector involving log(x) must still be undefined at zero in an ordinary Modello. Equal native Subs expressions can have different local coordinates; tree-rewrite caches must preserve both scopes.

_evaluation.py

Evaluate native calculus operations and finite indexed data. Resolved operands use the shared reconstruction layer, so construction and evaluation preserve the same source domains and local coordinates.

_expressions.py

Preserve declaration sources and expand directed dependencies with local coordinates protected. The resolver factory separates dependency ordering from evaluation, so ordinary solving and symbolic inspection share cycle handling without forcing either consumer to execute native operators.

_operators.py

Retain domain guards inside their binders and handle empty reductions using native identities, including a zero-length integral whose inactive body contains a cycle. Reversed discrete bounds retain SymPy semantics.

contrib/verification

Interpret obligations, quantify domains, retain source guards used by proofs, deduplicate premises and observations, evaluate native-operation preconditions, apply inference rules, classify evidence, and gate methods.

Core modules import no extension, including inside functions. They do not register proof predicates or select verification policies. Keep general fixes in core only when plain-model regressions establish their behavior; keep verification-specific interpretation and bookkeeping in the extension.

series.py declares relative recurrences. contrib/stochastic.py provides the opt-in Itô extension; the core resolver uses scoped declaration hooks without importing domain extensions. contrib/validation.py compiles causal model-vector laws over indexed observations, reusing the core definition resolver and ModelProblem.check. Its stateless callable checks a window’s final row; iter_results manages bounded history. Results add row labels, rule names, and coverage. DataFrame projection lives in documentation recipes. Core imports load neither the extension nor DataFrame libraries. _shapes.py solves symbolic finite axes from observation lengths before scalar coordinates are compiled. Shape specialization produces a cached subclass; it does not mutate the reusable declaration. The GUI creates a fresh finite context for each proposed window, preserving original observations and restore behavior.

_operators.py supplies their common scoped-expression protocol: operators identify local coordinates and the arguments in which those coordinates are protected while model definitions expand. They produce scalar expressions for the existing algebra boundary. Series and laws are template declarations in the compiled model, with fresh function identities in each component and problem. ModelProblem.templates exposes those scoped originals to printing and GUI equations. Population and numerical views retain the originals and bind their scalar parameters together, so a copied law cannot keep obsolete coefficients.

Delegate scalar algebra to SymPy: check_assumptions checks compatibility, Sum evaluates geometric weights in affine recurrences, and a shared derivative-based recognizer identifies affine drift and diffusion. Keep the recognizer independent of polynomial syntax: parameter-dependent Piecewise expressions can be affine without being accepted by as_poly. Local state variables retain the declared domain and the Itô law’s real-state premise.

model_vectors.py builds typed collections and compiles relative field laws into ordinary scalar definitions. _model_laws.py separates structural declaration records from immutable source templates: normalize the entire record on inheritance and keep source formulas distinct from finite expansion. Preserve equations already declared by member schemas. The compiler stores ordered field updates; only the inspection template retains complete source equations. Deferred laws must trigger shape preparation rather than disappearing from a finite solve.

_collections.py holds deferred locations and typed sparse observations without importing model construction. Population allocates canonical components once and connects their views. Structural shape/index binding precedes scalar solving. The GUI’s _gui/collections.py summarizes nested model members and observation origins; its labels preserve canonical API paths for navigation.

Keep the four-step feature walkthrough small. Reuse the existing geometry and portfolio models; examples/gallery/models.py holds the calibration equations. The portfolio guide and gallery share AccountSequence from examples/portfolio/models.py. catalog.py separates tutorial steps from domain extensions and supplies one shared question progression. extensions.py holds specialist models; examples/series.py supports the scalar-series guide independently of the GUI. app.py mounts the existing explorer through Werkzeug, preserving URL prefixes for assets and API requests. Add an example when it demonstrates a distinct idea, and derive scenario smoke tests from the catalog. Keep mathematical regressions in focused library tests, independent of the gallery’s menu and wording.

Two sequence evaluation strategies

The public choice is explained in Choose a sequence representation. Both laws are immutable SymPy Basic declarations; their calculated quantities are scalar Expr objects. The common scoped-expression protocol retains identity and lexical bindings. Neither is a wrapper around IndexedBase or a native SymPy sequence class.

  • Series names a scalar family; its terms retain their series identity and coordinate. Recurrence stores a causal transition and contiguous history. It evaluates required positions while caching each value with its cumulative domain condition. Affine formulas and rsolve results are used only after checking boundary values, the transition, and the state domains. rsolve receives an ordinary SymPy Function equation.

  • ModelVector retains typed members. model_recurrence first records a deferred field update; its ModelRecurrence template retains source equations. Once shape is known, the compiler instantiates scalar equations across the finite window. Ordinary model solving handles these jointly with member equations and observations, including current or future references.

Share position handling rather than these two solvers. In _evaluation.py, _relative_expression protects local binders and guards relative input selections, propagating through moving reduction bounds. _indexed_value binds a position using the common substitution and finite-reduction machinery. Conditional scalar evaluation keeps the value separate from its domain, so substitution cannot hide undefined inputs or accumulate nested validity wrappers. test_sequence_parity runs finite causal problems through both representations; it also checks the intentional difference between a queried prefix and an entire finite window.

SymPy’s RecursiveSeq does not replace the domain-carrying, scoped history required here. The upstream-only tests also reproduce incorrect nonzero-origin queries in SymPy 1.14.0. Native Subs applies replacements in order; delegate that ordering instead of rebuilding it as a dependency graph. Overlapping compound binders can nevertheless compare equal despite different results, conflating inputs inside native expression caches before Modello receives them. Strict upstream xfails isolate these defects; library contracts must pass normally.

Other adapters follow the same rule: preserve exceptional parameter cases while delegating supported scalar algebra to SymPy. Scoped expansion diagnoses implicit calculus through cyclic definitions; unknown assumptions remain distinct from disproven ones. Finite data reductions and explicit zero-rate kernels avoid slower generic symbolic work without discarding valid cases.

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.