BendSeq

Find an explainable press-brake bend order before you waste stock.

BendSeq is a local, standard-library Python CLI that exhaustively explores a bounded 2D sheet-metal profile, checks every candidate operation for self/tool collisions, and ranks the surviving sequences. It writes evidence you can inspect: JSON, CSV, a script-free HTML report, and a standalone SVG stage diagram.

It is not a decorative simulator and it does not ask you to trust a black-box answer. When no sequence survives, the report retains the bend, hold side, sweep percentage, segment, keep-out, and stable failure code that rejected each attempted transition.

Safety boundary: BendSeq is a planning aid, not certified CAM. A qualified press-brake operator must verify the real material, tooling, clearances, machine limits, and setup.

Why this project exists

Open-source sheet-metal tools such as FreeCAD SheetMetal focus on creating and unfolding parts. The sampled CNC Press Brake Simulator accepts a user-entered sequence, but its own roadmap lists accurate geometry and collision detection as future work. Full industrial systems solve a much wider CAD/CAM problem.

BendSeq deliberately occupies a smaller, testable gap:

• offline and dependency-free at runtime;
• exact search for 1-7 bends, not a suggested sequence entered by the user;
• both hold orientations and five sweep samples per candidate bend;
• self-collision, minimum-leg, precedence, and tool keep-out rejection;
• deterministic ranking and byte-identical reports for identical input;
• actionable evidence for both solved and unsolved jobs.

The research boundary and non-duplication rationale are recorded in docs/research.md.

Quick start

Requirements: Python 3.11-3.14 and uv.

git clone https://github.com/KanadeK/bendseq.git
cd bendseq
uv sync --locked
uv run bendseq check examples/hat-channel.json --strict
uv run bendseq solve examples/hat-channel.json --out build/hat-channel --limit 5

solve prints the selected order and creates exactly four files:

• build/hat-channel/report.html — human-readable stages and rejected alternatives;
• build/hat-channel/best-sequence.svg — standalone best-sequence strip;
• build/hat-channel/analysis.json — versioned complete evidence;
• build/hat-channel/summary.csv — ranked sequence table.

The output directory must not already exist. This makes accidental overwrite impossible and keeps repeatability checks honest.

Input model

examples/hat-channel.json is a complete solvable job. A job defines:

• segments: 2-8 positive open-chain leg lengths;
• bends: one joint per adjacent segment pair, with signed target angle, tool, and optional after dependencies;
• tools: minimum adjacent-leg length, clearance, and axis-aligned keep-out rectangles in local bend coordinates;
• units: mm or in.

Unknown fields, non-finite values, duplicate IDs, missing references, and precedence cycles fail at the input boundary. See docs/spec.md for the contract and docs/architecture.md for the geometry/search model.

Real failure fixtures

# Exit 2: E_PRECEDENCE_CYCLE
uv run bendseq check examples/invalid-cycle.json

# Exit 1 with report: E_MIN_LEG diagnostics
uv run bendseq solve examples/impossible-short-leg.json --out build/short-leg

# Exit 1 with report: E_TOOL_COLLISION diagnostics
uv run bendseq solve examples/impossible-collision.json --out build/collision

# Exit 2: E_UNKNOWN_FIELD
uv run bendseq check examples/invalid-schema.json

Valid-but-unsolved jobs still produce all four output files so the diagnostic evidence is not lost. Expected failures print a stable E_* code without a traceback. See docs/failure-recovery.md for the repair playbook.

Acceptance

The local gate used by CI is one command:

uv run python scripts/check.py

It verifies formatting, lint, strict typing, branch coverage, clean/warning/failure examples, deterministic artifacts, wheel/sdist contents, and an isolated installed-wheel CLI smoke test.

Focused commands:

uv run pytest tests/test_solver.py -q
uv run pytest --cov=bendseq --cov-branch --cov-report=term-missing
uv run ruff check .
uv run mypy src

Honest limitations

Version 0.1 models a constant cross-section as an open chain of straight 2D segments. It does not model thickness, bend radius, bend allowance, springback, tonnage, backgauges, curved/hemmed features, arbitrary 3D interference, robot motion, or NC generation. Fixed sweep sampling is explicitly part of the v0.1 model; it is not continuous collision certification.

If you need those guarantees, use machine-specific tooling and physical/operator validation.

Project documents

• docs/spec.md — public v0.1 behavior contract
• docs/architecture.md — state, geometry, ranking, and boundaries
• docs/failure-recovery.md — code-to-repair workflow
• docs/research.md — sampled alternatives and differentiation
• SECURITY.md — supported release and vulnerability reporting
• CONTRIBUTING.md — small, test-first contribution workflow

MIT licensed. See LICENSE.