Know whether the right mesh screens will be ready before a job reaches the press.
中文说明 · Acceptance walkthrough · Input contract · Report contract
MeshReady is an offline planner for small screen-printing shops. Give it reusable screen pools by mesh count, recovery times, and a due-dated job queue. It simulates screen reuse, searches job orders, and produces evidence that says one of three honest things:
- every selected job finishes on time;
- the best found order is still late or the search budget ended; or
- a specific job is structurally impossible with the declared screen inventory.
It is a zero-runtime-dependency Python package, not a customer/order ERP and not a UI shell.
The committed examples/on-time.json is late in intake order:
| Queue | Order | Late jobs | Makespan |
|---|---|---|---|
| Intake | long-base → detail → rush-base |
1 | 160 min |
| MeshReady | rush-base → detail → long-base |
0 | 160 min |
The selected long-base job waits until minute 80 because its mesh 110 screen is still
recovering. That constraint is visible in JSON, CSV, and the standalone HTML report.
Install uv, clone the repository, then run:
uv sync --locked --all-extras --dev
uv run meshready validate examples/on-time.json
uv run meshready plan examples/on-time.json --out build/demo/on-timeExpected result:
PASS: 3 jobs on time; order=rush-base -> detail -> long-base
Reports: build/demo/on-time
Open build/demo/on-time/report.html locally or feed report.json/schedule.csv into
an existing shop workflow. MeshReady itself makes no network requests.
To install a published wheel, download it from GitHub Releases and run:
python -m pip install meshready-0.1.0-py3-none-any.whl
meshready versionA queue can be valid JSON and still be impossible to run. The shortage example needs two usable mesh 230 screens but declares only one:
uv run meshready plan examples/shortage.json --out build/demo/shortageThe command exits 1, still writes all three reports, and records:
{
"job_id": "halftone-pair",
"mesh": 230,
"required": 2,
"usable": 1,
"shortfall": 1
}That nonzero exit is part of the product: CI or another tool can stop on an unresolved screen shortage without scraping prose.
Times are nonnegative working minutes from the planning horizon, not timestamps. Each screen pool is one exact mesh count:
{
"schema_version": 1,
"shop": {
"name": "Demo shop",
"screen_recovery_minutes": 60,
"screen_pools": [
{"mesh": 110, "ready": 1, "recovering_at": [45], "locked": 0}
]
},
"jobs": [
{
"id": "festival-shirts",
"release_minute": 0,
"due_minute": 180,
"duration_minutes": 50,
"screens": [{"mesh": 110, "count": 1}]
}
]
}ready: usable at minute 0.recovering_at: usable at each listed minute.locked: inventory context that remains unavailable for the whole horizon.- A used screen returns at job completion plus
screen_recovery_minutes.
Unknown fields are rejected. See the complete v1 input contract.
meshready validate INPUT
meshready plan INPUT --out DIRECTORY [--max-states 250000]
meshready version| Exit | Meaning |
|---|---|
0 |
Valid input and an on-time selected schedule. |
1 |
Valid input, but impossible/late, or no on-time schedule before budget exhaustion. |
2 |
CLI usage, input, or output-boundary error. |
Planning writes exactly report.json, schedule.csv, and script-free report.html.
Every result exposes search.complete and search.proven_optimal; a truncated search
never claims a proof. See the report contract.
For each candidate order, a job waits for all three constraints: its release minute, the previous press completion, and the last screen it requires. Used screens re-enter their exact mesh pool after recovery. A deterministic bounded branch-and-bound search minimizes, in order:
- late-job count;
- total lateness;
- maximum lateness;
- makespan;
- press idle time;
- lexicographic job order as a stable tiebreaker.
The architecture note explains the data flow and proof limits.
MeshReady v0.1 models one sequential press, exact mesh pools, up to 16 jobs and 32 pools. It does not model parallel presses, staff, dryers, shifts, named/barcoded screens, garments, quotes, or invoices. Durations and recovery times are supplied estimates, so output is planning evidence—not a physical guarantee.
The narrow scope is deliberate. Gap research records the adjacent GitHub projects, commercial systems, practitioner evidence, rejected ideas, and the time-bounded differentiation claim behind this release.
uv run python scripts/check.pyThe gate checks lock consistency, formatting, lint, strict types, tests and coverage, all committed examples, wheel/sdist contents, and a clean-wheel console-script smoke test. Expected failures and repairs are listed in the acceptance walkthrough and troubleshooting guide.
Read CONTRIBUTING.md before proposing a schema or scope change. Correctness bugs are welcome; ERP/UI expansion needs real screen-shop evidence first. Report security-sensitive issues through the process in SECURITY.md.
Released under the MIT License.