Imported from SiennaDai/modeling (AGENTS.md). Install upstream with npx skills add SiennaDai/modeling. Copyright stays with the author.

Repository Instructions

Purpose

This repository is a Python execution toolkit for mathematical modeling competitions. It supplies reusable computation, experiment execution, and artifact export. It does not own model selection, model validity judgments, or paper composition.

Read docs/architecture.md before making architectural changes and docs/agent-contract.md before changing ownership boundaries.

Project boundary

• Keep the reusable toolkit and all competition work inside this repository.
• Put event-specific data, code, configuration, results, and model records under competitions/<event>/.
• Do not search sibling projects for modeling context or runtime dependencies.
• Treat competitions/<event>/data/raw/ as read-only.
• Write generated event artifacts only under that event's outputs/ directory.

Ownership boundaries

Modeling work

For formulation, solution analysis, validation, sensitivity, uncertainty, robustness, or decision analysis:

• read and call src/mmkit;
• copy or adapt public recipes inside the current competition directory;
• create event-specific scripts only under competitions/<event>/;
• keep model assumptions, parameters, and domain rules out of the public package;
• do not modify src/mmkit, public recipes, dependency files, or public tests unless the user explicitly authorizes a core-library implementation task;
• report a reusable-library gap with its mathematical contract and a minimal event-local example.

Core-library work

For implementation, maintenance, debugging, refactoring, dependency changes, and software testing:

• treat src/mmkit, recipes, package configuration, and tests as Coding Agent-owned surfaces;
• require a sufficiently specified mathematical contract before implementing a modeling method;
• make the smallest reusable change and preserve event-specific behavior in its event directory;
• add focused tests and fresh verification for changed public behavior;
• do not infer model assumptions merely to simplify an API.

API rules

• Prefer explicit functions and small structured result objects over a universal model base class.
• Never silently choose indicator direction, weights, missing-value treatment, split points, parameter ranges, probability distributions, objectives, constraints, or variable domains.
• Preserve important intermediate values, warnings, numerical status, solver status, and configuration metadata.
• Use exceptions for inputs or states that make the requested computation invalid.
• Record recoverable numerical or batch-run issues explicitly; never skip them silently.
• Keep public APIs free of event-specific column names, paths, constants, and assumptions.

Reproducibility

• Use uv and the committed lock file for dependency management once the Python project is initialized.
• Avoid network-dependent runtime behavior in core competition paths.
• Make random seeds explicit and record them in formal runs.
• Preserve raw inputs and write derived files to designated output directories.
• Expose solver status and relevant package or solver versions in saved run metadata.

Documentation and recipes

• Keep documentation concise and operational; do not build a duplicate modeling knowledge base.
• Public docstrings must state inputs, outputs, errors, warnings, and modeling choices the caller must supply.
• Recipes are executable Python scripts that call the public package; they must not duplicate algorithm implementations.
• Do not maintain parallel Notebook and Python-script versions of the same public recipe.
• Provide project-level run entry points only; do not add a CLI for every algorithm.

Scope control

• A successful computation does not establish model validity.
• Passing software tests does not establish that a model is fit for a real decision.
• Keep one-off competition code event-local until it has a clear cross-event contract and independent tests.
• Do not add algorithms speculatively; prioritize gaps demonstrated by real competition work.