Repository navigation
v2.0.0
stepscribe 2.0.0 (2026-11-06)
This release is compared with 0.1.4, the previous release (tagged v0.1.4).
The first list is only what changes behaviour for people who already use stepscribe. Everything new is
listed in full under "Everything new in 2.0.0". The report schema stays 0.6.0 and is not tied to the package version.
Changes that alter existing behaviour
- Floating-part wording. A part with no fastener, pivot or joint evidence tying it to the rest used to be called "not connected to the ground link" (weak spot W001 and its risk phrase, the floating list of the kinematics text, and the matching interview question). It now says "has no fastener, pivot or joint evidence linking it to the ground link (it may still touch other parts)" where the file or the designer names the ground link, and "... linking it to the rest of the assembly" otherwise, because touching parts without such evidence are not "unconnected". Only these sentences change; a report that has such a finding differs from an older one in those strings alone (the same inputs were run through the code before and after: the only differing strings are these sentences).
- Contact kinds. Parts that touch at an edge or a point are reported as
edge_or_point("A touches at an edge or point B.") instead ofpointorline; the split was not reliably decidable. Older saved reports and cached exports withpointorlinestill load and are read asedge_or_point. - Image labels carry IDs only. No part name is drawn or captioned on any image, the basic set included (the assembly legend, the part-panel title, the link legend and the image descriptions used to carry names). The names stay in the Markdown text, labelled as data. The golden
two_plates_assembly_FULL.mdchanged for this reason. - Report schema 0.6.0 (unreleased, not tied to the package version) has new optional fields:
parts[].from_step,material_source: step_file,FastenerJoint.bore_pair, theKinematicModelheadline fields,KinJointdesigner fields,Understanding.kinematics_debugandload_path_note, new question kinds. A file that states none of this produces the samereport.jsonas before. - Headline wording and confidence. Every
Likely:headline now carries a confidence and its evidence; a chain of revolute joints readsLikely: 6-axis serial arm (confidence X; evidence ...)and its confidence is capped by the weakest joint; a single part's role phrase says "probably" from 0.60 and "possibly" from 0.30. - Fasteners. Pivot candidates and large coaxial bore pairs are no longer fasteners: they leave the "bolted to" relations, the fastener counts and the "fasteners missing?" questions and have their own sections in
02_assembly.md. - Hole edge distance is measured from the hole's side walls (a drill-point tip no longer counts).
- Hole edge distance for a counterbored or countersunk hole no longer counts the hole's own counterbore, countersink or the rounded mouth round it (a fillet at the mouth used to leave a corner touching the bore, so the distance read 0.0 mm). A counterbore with a flat in its wall (a D-shaped bore) is measured against that flat: the wall of the hole in the floor to the flat. Plain holes and plain round counterbores keep their numbers. A hole that read 0.0 mm (and so was skipped as breaking through the edge) can now appear as "too close to an edge", and some countersunk or counterbored holes on large parts report a larger distance than before.
- Process guesses. A part with complex or free-form geometry gets no process guess instead of a confident one.
- UI image sets. The page builds its pack with the chosen image set (basic, standard or full); the default is standard, so the UI now draws more images (hole map, three views, weak spots, ...) than before and takes longer on big files.
- CLI image set default stays
basic(today's images, apart from the IDs-only change above). - macOS. Free memory is read through
vm_stat; an unknown value caps the part-worker pool at 4 (it used to be unlimited).
Known limit
- Interference check. It reports measured overlaps. A very shallow overlap over a large mating face can be within modelling tolerance, and a part modelled inside a housing is reported as an overlap. Read the reported volume and contact area before drawing a conclusion.
Checked before release
- An old saved report (the pre-change report of a six-axis robot-arm model, schema 0.6.0 as written then) loads with the current models.
- Version strings: the package, the plugin, the marketplace entry and the two goldens all read 2.0.0;
tests/test_version_sites.pyfails if they disagree.
Everything new in 2.0.0
- Counterbore with a flat. A round counterbore that has one flat in its wall (a D-shaped bore) is described as such: "cbore dia 4.2 x 8.6 with a flat (3.6 across flats, flat 1.5 from the axis)", with the measured numbers in an optional
counterbore_flatfield of the hole inreport.json(absent for every other hole; schema stays 0.6.0). The axis-view image draws the across-flats dimension beside the hole label. Two or more flats (a double D, a hexagon) are not described.
Robot files from manufacturers (a six-axis industrial arm, for example): links, joints and a robot description.
- macOS: free memory is now read (
vm_stat), and an unknown value caps the pool.available_ram_bytes()returned nothing on macOS, so the worker count followed the CPU rule alone (up to 8 workers, each 0.4 GB or much more for a big part) and the bore split used a fixed rule. It now reads free + inactive + speculative pages times the page size from/usr/bin/vm_stat(2 s timeout; an empty or garbled answer, a timeout or a missing command gives no value, never an error) and the usual memory rule applies. When the value is not known on any OS, the pool is capped at 4 processes shared between the jobs instead of being unlimited. stepscribe --versionprints the package version (only the number) and exits;stepscribe versionstill prints the version with the OpenCASCADE build.- The JSON Schema of
report.jsonships in the wheel asstepscribe/schema/report.schema.json(the same bytes asschema/report.schema.jsonin the repository; the schema stays 0.6.0). A test builds the wheel and compares the two. - Install lines name the right package. The skill files, the MCP and robot-validation messages and the docs named the package without its
-cadsuffix, which on PyPI is a different project. They now saystepscribe-cad(pip install "stepscribe-cad[mcp]",stepscribe-cad[robot],stepscribe-cad[llm]), and a test fails if any file in the repository gets this wrong again. The 0.1.0 to 0.1.4 releases carry the wrong name in some messages and in the skill files; their PyPI project page and README were already right. - Names. An instance labelled only with an assembly-tree occurrence id (
NAUO4) now takes the product name (LINK3). - Links from names.
BASE,LINK<n>andAXIS<n>are found anywhere in a part name, with any prefix and a_body<k>suffix. With three or more numbered groups in a chain, bodies of one group are one link and different groups are never merged because they rest on each other. - Pivots and flanges. A coaxial hole stack that matches no screw size, at least 20 mm wide and as long as it is wide, is a pivot candidate (revolute about the bore) instead of a confidence-0 fastener that locked two links together. A large planar contact between two link groups is a revolute candidate about its normal; a bore that agrees raises the confidence, one that disagrees wins with a lower confidence and the flange reading is listed. Change the limits with
--pivot-min-diameterand--pivot-min-length-ratio; seedocs/kinematics.md. --debug-kinematics(onpackandexport) writesdata/kinematics_debug.mdand akinematics_debugsection inreport.json: for every contact, why it was merged or kept apart; for every unmatched hole stack, why it is not a fastener.- Designer input. A
kinematics:section indesign_context.yaml(base, and joints with type, axis, origin, range, positive direction) replaces what was detected and is marked "Confirmed by designer". New interview questions ask for the base link, the axis of joints known only from a flange, and the sign of positive motion. robot.jsonin the pack for a model with at least one revolute or prismatic joint: link frames, joint axes and origins, a DH-style table, mass and inertia per link (estimates), and joint limits only from the yaml.- Headline. A chain of revolute joints reads
Likely: 6-axis serial arm (confidence 0.70; evidence KJ1..KJ6, L0..L6), with the chain facts and a check of the usual 6-axis layout (a mismatch is written out and lowers the confidence; the confidence is capped by the weakest joint). Parts namedLINK<n>with no joint evidence read "Joint structure not determined", never "static structure". The overview, understanding file and single-file pack carry the same text. - Interview. For a robot the base link, the axis of flange-only joints, the sign of positive motion and the ranges come first. Answers are also written to the
kinematics:section, and undo removes them. --meshes(onpackandexport, robots only) also writesmeshes/: one visual and one collision binary STL per link, in metres, in the link frame, so mesh position plus link frame is the world position at the zero pose.robot.urdfthen has<visual>and<collision>per link. The collision mesh is a coarser tessellation within a triangle cap (--mesh-max-triangles, default 5000) and is always closed and consistently oriented: the deflection grows until both hold, and a link where none does gets the convex hull (numpy only), marked "collision: convex hull".--visual-triangle-cap Ncoarsens the visual meshes the same way (default: no cap). A visual mesh that is not closed is reported in the URDF header andmeshes/README.md, with "because the source solid is not closed" when the part's solid is not valid and closed. Mesh paths are relative to the URDF file, and its header says how to load them and lists each link's triangles and size. Same input, same bytes. Off by default: default packs and their cache keys are unchanged, and no mesh goes into the chat bundle or the MCP results.- Joint origins lie on their axis (common perpendicular from the previous axis); the raw point is kept as
evidence_point_mm. robot.urdfnext torobot.json: a draft in SI units (metres, kilograms) with no invented limits or masses; a joint with no known limits is writtencontinuous, and a forward-kinematics test checks the file against the detected frames.- Direction convention. One interview question asks which way positive motion goes for the whole arm, stated with the right-hand rule about each joint axis; a
cwanswer flips the axis once, answers are checked strictly, and range answers are grouped into one question. - Load paths say what they trace. Paths start at every part with at least 5 % of the total mass (volume when masses are unknown) and at every motor; it is a share threshold, not a top-N cap. The understanding file prints the rule and names the parts left out with their share (
load_path_noteinreport.json). - Complex or free-form geometry. A part with at least 100 faces that is not a closed solid, or has 15 % or more free-form faces, gets no process guess instead of a confident "3D printed" or "injection moulded"; its measured edge distances are still reported against the generic guideline, labelled as such. See
docs/kinematics.md. - Every
Likely:headline carries a confidence and evidence. The static-structure, single-part and general assembly headlines now readLikely: ... (confidence X; evidence ...); a single part's role phrase says "probably" from 0.60, "possibly" from 0.30 and is left out below that. - Pivot candidates are not fasteners. They no longer appear as "bolted to" relations, fastened load-path edges, single-fastener findings, "fasteners missing?" questions or fastener counts;
02_assembly.mdlists them under "Pivot candidates (not fasteners)". - Large coaxial bore pairs are not fasteners. An unmatched coaxial stack at or above the pivot minimum diameter is never a fastener joint: long enough it is a pivot candidate, too short it is a "large coaxial bore pair (locating feature or bearing seat)" in its own section of
02_assembly.md, with no bolted relation, fastened load-path edge, shopping-list entry or clamp. - Measurement change: hole edge distance. It is now measured from the hole's side walls to the other faces. The tip of a drill point is no longer counted, because it reaches past the wall and its gap to whatever lies below is not a lateral margin. A flat-bottomed hole is unchanged. Blind drilled holes whose point was the nearest feature now read a larger distance, so some "hole too close to an edge" findings change value or disappear.
- The pool size is logged and the memory limit is said in one sentence. The run records how many part workers were used, which rule chose the number (CPU cores, free memory, the unknown-memory cap, the
STEPSCRIBE_WORKERSoverride, or a small model) and the free memory it saw (data/timings.jsonnotepart_workers, and the progress line). When free memory is the limit, the progress line says "Using N of M possible part workers because free memory (X GiB now) is the limit; closing other programs frees memory and speeds this up." Results are unchanged. Per-worker peak was measured at 700 to 757 MB on a six-axis robot-arm model (not in the repository) against 411 MB assumed by the rule, so the budget is not lowered. - Linux: available memory is
MemAvailable, capped by the container's limit. The free-page count ofsysconfleaves out the page cache that can be given back, so the pool was smaller than the memory allowed on a machine that had read many files. The query now reads/proc/meminfoMemAvailableand, in a container, the cgroup v2 or v1 limit minus its use (the lower of the two); if/proc/meminfocannot be read it falls back to the free pages as before. Results are unchanged; only the pool size can differ. - Several files, a folder or a zip as one design:
stepscribe pack a.step b.step, a folder with--combine, or a.zip; the web page takes several files or a zip; every MCP tool that takes apathalso takes a zip, or a folder withcombine=true. Each file keeps its own coordinates;files:offsets and rotations indesign_context.yamlplace a file (rotation about X, then Y, then Z, in degrees, about the file's own origin, then the offset); a warning with a hedge line over the dependent sections appears when the files do not seem to share a coordinate frame; files with the same name get a suffix and the pack says so. Seedocs/multi_file.md. - Speed:
--timings(onexport) writesdata/timings.jsonwith the time of each stage, each part (with its face count) and the contact pair counts. Off by default; results are unchanged (the report is identical with and without it). - Speed: contact distances are computed once. The distance between two parts was computed twice (OpenCASCADE's constructor already does it, then
Perform()repeated it). It now runs once, on all threads. The distance, the closest points and every contact are unchanged (tests at the contact tolerance, just inside and just outside it); on a six-axis robot-arm model (not in the repository) the contact stage alone went from 467 s to 43 s (a stage time, not a whole run; same Windows laptop, stage-instrumented runs of a full export; this stage does not depend on the part pool, so it does not depend on free memory). - Speed: bore faces are found once. The part analysis already finds the concave cylinder and cone faces of every part (the expensive step of hole detection); the contact stage found them all again on a second copy of the shape. It now reuses them. The faces are the same, so holes, contacts and every other result are unchanged; this is part of the 467 s to 43 s contact-stage figure above (IRB1660, same laptop and runs).
- Deliberate change: one contact kind for edge and point touches. Parts that touch but not over a flat face or as a shaft in a bore are reported as
edge_or_point("A touches at an edge or point B.") instead ofpointorline. The split was not reliably decidable: it came from the closest-point solutions of the solver, whose number varied between runs, so the same file could read "touches at a point" one time and "touches along a line" the next. Nothing in the analysis used the difference. The report schema stays at 0.6.0, the version of this unreleased cycle:Contact.kindisplanar_face,cylindrical_fit,edge_or_pointornear_miss. Planar contacts and fits are unchanged. - Tests: a fast local run.
pytest -m "not slow"skips the 40 slowest tests (tests/slow_tests.txt); CI and releases still run every test. - Speed: hole detection of big parts uses the whole pool. Finding the concave faces of a part costs one ray cast per cylinder or cone face, and a big part's casts all ran in the one worker that analyses it, which made it the slowest thing in a robot-arm run. For parts with 300 faces or more the casts now go to the pool in chunks and the part's analysis starts with the bores found. The faces, holes and warnings are the same as before (tests compare the chunked and the serial result, and the reports of the test robots are identical). Every worker that casts rays holds its own copy of the part, so the split follows the same memory rule as the worker count (the estimate for the largest part, 60 % of the free memory): with too little free memory it is not used and the part's own worker does all the casts, with the same result. The whole run is only faster when memory allows more than one worker. All wall times below are full-export runs of that robot-arm model with the basic image set (images included), interference check off, on one Windows laptop, with the free memory fixed to the value shown: 309 s with the real free memory (5 processes, largest 734 MB, 1881 MB in total), 344 s with 1500 MB free (3 processes), 493 s with 500 MB free (serial, 1 worker). Before these speed changes the same full export took 947 s. Runs on 2026-11-02 on the same laptop were full packs with the standard image set (images included), interference check off, through the web page and
pack --images standard; with only 0.8 to 1.0 GiB free at the decision they got 1 worker and took 598 to 722 s wall, of which the part-analysis stage alone (analysis only, no images) was 388 to 472 s. So the pool size, and with it the time, follows the free memory of the moment: no fixed factor is claimed.--timingsand the log line "Using N of M possible part workers" show which one you got. Where the OS does not report free memory (macOS) it is used on a pool of at most 4 processes. - Older reports and cached exports still load. A saved
report.jsonor a finished export in the result cache from before this change (contact kindpointorline, "touches at a point" / "touches along a line") is read asedge_or_pointwith the new sentence instead of failing validation; anything else wrong with a report still fails. The export cache key now also includes the report schema version, so a future schema change is a cache miss, never an error. - Weak-spot wording about printed layers appears only when the process is a printed one.
- Build tests run hermetically (
--no-isolation, pinned hatchling) with one isolated CI job, and wait up to 30 minutes for a build (a heavily loaded machine once timed one out at 10 minutes). - Report schema 0.6.0 (new optional fields:
FastenerJoint.bore_pair, theKinematicModelheadline fields,KinJointdesigner fields,Understanding.kinematics_debugandload_path_note, new question kinds). - Image sets.
--images none|basic|standard|full(defaultbasic, today's images except for the deliberate change below) and--image-max-side(default 1200). The extra images carry IDs and numbers only, never a name from the file;images/INDEX.mdlists each one with what it shows, the IDs on it and the text it pairs with, and the caption is repeated next to the image reference in the part Markdown. Seedocs/images.md. First type: the hole map (standard): every hole circled and labelled with its ID and diameter, with pattern IDs. - Deliberate change to the basic image set: no part names on any image. Until now the legend of the assembly images (
PRT001 name), the title of the feature panel on the part images, the link legend ofkinematics_iso.png, and the image descriptions inFULL/the MCP view text carried part names from the file. All image sets now use IDs and numbers only (PRT001,L3 ground, 2 part(s)); the names stay in the Markdown text, where they are labelled as data. A test with a hostile part name checks every drawn label, every image description andimages/INDEX.mdfor all three sets. - Hole map: the holes of a pattern are one group. A part with a hole pattern of three or more holes used to get one overlapping label per hole (27 labels on a plate with three rows of nine). The holes of each such pattern now share a tint and one legend line (
P001 9x dia 6.0 thru, pitch 13.0); holes in no pattern, or in a smaller one, keep their own label. The outline colour still says through (red) or blind (blue). The pack text still lists the holes of each pattern. - Mass distribution and static joint loads (estimates). New section in
05_understanding.mdand new keys inrobot.json: principal moments, principal axes and radii of gyration about the centre of mass for every part, every link and the assembly (computed only for a valid closed solid with a known material or density; otherwisenot computed: <reason>), and the static holding torque (force for a prismatic joint) of each joint at the file's pose, gravity only, with an optionalpayload:(mass_kg,offset_mm) indesign_context.yaml. Labelled "static holding torque, gravity only, at this pose; not dynamic, not a motor selection". A joint is refused when a link beyond it has an unknown mass, geometry that is complex or free-form, or is not a closed solid. Estimates from CAD volume and density, not measurements; no support reactions, fastener loads, motor sizing or safety statements. - Three-view drawing (
standard): front, top and right views of each part on one sheet with the overall dimensions drawn and labelled. - Weak-spot overlay (
standard): each weak spot marked on its part with its ID; an edge-distance finding also shows the measured distance line. - Feature highlight (
full): holes, openings, bosses, fillets and chamfers in one colour per family with their IDs. - Section view (
full): a cut through each part along its widest bore, plane position stated, cut face in red; skipped with a note when the cut fails. - Contact map (
standard, assemblies): the parts of the largest touching pairs in colour with their contact IDs; the caption lists the pairs and patch areas. - Link colour map (
standard, robots): the assembly coloured by link group with link IDs only; the caption lists each link and its instances. - Kinematic diagram and joint axes (
standard, robots): a skeleton of link bars with the joint axes as labelled arrows over a faint outline, and the axes on the shaded model. - Joint ranges (
full): each joint with a designer range at both ends of it on the skeleton; skipped with a note without ranges. - Wall-thickness heat map (
full, where thickness data exists): the sampled wall thickness as coloured dots on the part, labelled an estimate, with the scale. - Robot validation (
stepscribe validate-robot <urdf or pack>, anddoctor --robot): layer 1 checks the URDF with no extra library (parses; one root; connected tree, no cycle; parents, children and mesh files exist; joints matchrobot.json; inertia positive definite with the triangle inequality), and simulator readiness is reported separately in plain words with the fix (no inertia, continuous joints, zero effort or velocity, no collision geometry). Layer 2 is a plug-in structure for an optional library that cross-checks forward kinematics at the zero pose and fixed random poses; no library is a dependency and none is chosen yet. Seedocs/robot_validation.md. - Data the STEP file already carries. Product description, colour, the material assigned to a part (name, description, density), presentation layers and dimensions with tolerances (PMI) are read through OpenCASCADE's document layer and reported as "From the STEP file:" statements (a stated fact, never "Likely:") in the part Markdown and as
from_stepinreport.json(only for a part whose file states one of them). Text from the file goes throughclean_nameand is a label. Material precedence: a designer value wins; otherwise the file's material sets the mass (material_source: step_file) with the density the file states (read as g/cm3, or kg/m3 by range) or the keyword table's; otherwise nothing changes. A stated linear distance or diameter is cross-checked against the geometry ("stated 25 +0.1/-0.1 mm; measured 25.02 mm"). Seedocs/step_data.md. - Optional extra
stepscribe-cad[robot](never a default dependency): MuJoCo 3.17.0 (Apache-2.0), about 80 MB installed, does both layer-2 jobs ofvalidate-robot: its forward kinematics are compared with stepscribe's own at the zero pose and four fixed random joint values (largest difference on the generated arm 5.7e-17 m; a flipped axis is detected), and it answers simulator readiness (R100toR103, MuJoCo's own reason when it refuses a file). No wheel for macOS on Intel: the extra installs nothing there. yourdfpy is supported but not in the extra (its dependencies add about 225 MB): install it yourself and use--backend yourdfpy. A new CI jobrobotinstalls the extra on Ubuntu, macOS (Apple silicon) and Windows for Python 3.11 to 3.13 and fails if a library test is skipped;pip-auditruns there as a warning. Details indocs/robot_validation.md.