Skip to content
KanadeKPublic

About

Offline screen-printing mesh capacity planner with recovery-aware scheduling and evidence reports

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MeshReady

Know whether the right mesh screens will be ready before a job reaches the press.

CI Python 3.11+ License: MIT

中文说明 · 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 visible result

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.

Quick start from source

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-time

Expected 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 version

Real failure evidence

A 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/shortage

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

Input in one minute

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.

Commands and exit codes

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.

How the planner works

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:

  1. late-job count;
  2. total lateness;
  3. maximum lateness;
  4. makespan;
  5. press idle time;
  6. lexicographic job order as a stable tiebreaker.

The architecture note explains the data flow and proof limits.

Scope and 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.

Verify the whole release locally

uv run python scripts/check.py

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

Contributing and security

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.

About

Offline screen-printing mesh capacity planner with recovery-aware scheduling and evidence reports

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages