stepscribe-cad 0.1.0__tar.gz

stepscribe_cad-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "stepscribe",
+  "description": "Plugins for understanding STEP CAD files of mechanical designs and robots.",
+  "owner": {
+    "name": "idris sadiq"
+  },
+  "plugins": [
+    {
+      "name": "stepscribe",
+      "source": "./plugins/stepscribe",
+      "description": "Analyse STEP files offline: measured facts, how the design moves, weak spots, and portable Markdown exports.",
+      "version": "0.1.0",
+      "license": "AGPL-3.0-only",
+      "keywords": ["cad", "step", "robotics", "mechanical", "design-review"]
+    }
+  ]
+}

stepscribe_cad-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+* text=auto eol=lf
+*.png binary
+*.step binary
+*.stp binary
+*.zip binary

stepscribe_cad-0.1.0/.github/skills/stepscribe/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: stepscribe
+description: Analyze STEP CAD files (.step/.stp) of mechanical designs and robots - dimensions, holes, fasteners, assembly structure, how the design moves, weak spots - and hand over portable Markdown. Use when the user shares or mentions a STEP file, asks what a CAD model is or how it works, wants a design review, or wants a text description of a 3D model.
+license: AGPL-3.0-only
+compatibility: Needs Python 3.11+ with the stepscribe package (pip install stepscribe, or "stepscribe[mcp]" for the MCP server). Works offline.
+---
+
+# stepscribe: understand a STEP file
+
+stepscribe reads a STEP file and writes measured facts (sizes, holes, fasteners, contacts) plus rule-based
+inferences ("Likely: ..." with a confidence). It uses no AI model and no network. You add the judgement.
+
+**Never invent a number.** Every dimension, count or position you state comes from stepscribe output or a
+tool call. If a number is missing, measure it with a tool or say it is unknown.
+
+## 1. Check the environment
+
+Run `python scripts/check_env.py` (in this skill's folder). It prints the stepscribe version and whether
+the MCP server dependencies are present. It never installs anything.
+
+If stepscribe is missing, **ask the user before installing** (`pip install stepscribe`, or
+`pip install "stepscribe[mcp]"` for the MCP server). If installing is not possible here, say so plainly and
+suggest running `stepscribe export robot.step` on their own machine and uploading the exported files
+(`robot_FULL.md`, or the `chat_bundle/` folder for small chats) instead.
+
+## 2. Prefer the MCP tools, otherwise the CLI
+
+MCP tools: `start_analysis`, `get_job_status`, `export_pack`, `get_overview`, `get_part`, `list_holes`,
+`list_cutouts`, `get_relations`, `measure_distance`, `section`, `render_view`, `find_parts`,
+`get_questions`, `submit_answer`, `get_shopping_list`, `diff`.
+
+CLI equivalents: `stepscribe export FILE`, `stepscribe questions FILE --json`, `stepscribe answer FILE --id ID
+--value V` (also `--skip`, `--not-sure`, `--undo`), `stepscribe kinematics FILE`, `stepscribe weak-spots FILE`.
+
+## 3. Expect long runs
+
+Real assemblies take minutes. Call `start_analysis` (it returns at once with an ETA and whether the result is
+cached), tell the user the ETA ("about 3 minutes"), then poll `get_job_status` every 20 to 30 seconds and give
+a short progress line each time. Do not claim results before the job is done.
+
+## 4. Export, then read
+
+Call `export_pack` with the job id. Read `MANIFEST.md`, then `<name>_SMALL.md` (or COMPACT or FULL if your
+context allows). If you can see images, look at the assembly iso and exploded views. The layout of the files
+is in `references/pack_format.md`.
+
+## 5. Give a short summary
+
+Two to five sentences with IDs: what it is, overall size, number of parts, how it moves (joints and what
+drives them), and the top risks. Separate measured facts, designer-confirmed facts and "Likely:" inferences.
+
+## 6. Offer the interview
+
+Say: "I have N questions that would sharpen the analysis. Want to go through them? You can skip any." Then
+follow `references/interview_guide.md`: one question per message, numbered options with the tool's guess
+marked, and skip / not sure / back / done understood from the reply. Submit each answer with `submit_answer`
+(or `stepscribe answer`). Export again at the end.
+
+Everything stays in this chat: ask questions as messages, show images inline as image content (or describe
+them and give the file path), and hand results over as files and text.
+
+## 7. Review when asked
+
+Follow `references/review_checklist.md`. Prioritise by severity. Challenge inferences that look wrong. State
+your assumptions (material, process, loads) when the design context does not give them.
+
+## 8. Always finish with the portable files
+
+In one or two lines say where `<name>_FULL.md`, `<name>_SMALL.md`, the folder and the zip are, and that they
+can be pasted or uploaded into any other AI tool or document. If you can send files, send FULL.md and the zip.

stepscribe_cad-0.1.0/.github/skills/stepscribe/references/interview_guide.md

@@ -0,0 +1,42 @@
+# Running the designer interview in the chat
+
+The tool asks what geometry cannot tell: material, how parts are made, purpose, payload, what drives a joint.
+Each answer changes the analysis (mass, weak spots, tipping, roles), usually in well under a second.
+
+## Offer first
+
+"I have N questions that would sharpen the analysis (material, how it is made, what drives each joint). Want to
+go through them? You can skip any."
+
+If the user says no, move on. Do not ask again unless they bring it up.
+
+## One question per message
+
+Use `get_questions` (or `stepscribe questions FILE --json`). Take the first question and write:
+
+1. The question, in plain words.
+2. Why it matters (the `why` field), in one short sentence.
+3. Options as a numbered list. Mark the tool's guess: `2. 3D printed (FDM) (my guess)`. For a number or free text,
+   say what unit or format you want.
+4. If the client shows images, include the highlight image for the parts the question is about.
+5. A reminder in small words: *reply with a number or text; "skip", "not sure", "back" or "done" also work.*
+
+## Reading the reply
+
+- A number picks that option; text is the answer for free-text questions; "a, c" answers a multi-choice question.
+- "skip": submit with status `skipped` (the guess stays, unconfirmed).
+- "not sure": submit with status `not_sure` (the guess stays, marked as a soft fact).
+- "back": undo the last answer (`stepscribe answer FILE --undo`) and re-ask that question.
+- "done": stop asking.
+
+Submit with `submit_answer` (MCP) or `stepscribe answer FILE --id ID --value V [--note ...]`. Question IDs
+can change after an answer, so take the next ID from the reply or from a fresh question list.
+
+## After each answer
+
+Read the "what changed" line back in one short sentence ("Mass is now 109 g; tipping angle 3.5 degrees").
+If an answer conflicts with the geometry the tool says so; tell the user plainly and keep their answer.
+
+## At the end
+
+Run `export_pack` again so the files include the answers, then say where they are.

stepscribe_cad-0.1.0/.github/skills/stepscribe/references/pack_format.md

@@ -0,0 +1,39 @@
+# Reading a stepscribe export
+
+## Files
+
+| File | Use it for |
+|---|---|
+| `MANIFEST.md` | Which file to use where, with sizes and token estimates. Read it first. |
+| `<name>_SMALL.md` | Summary, kinematics, top weak spots, open questions, BOM, one paragraph per part. Fits small chats. |
+| `<name>_COMPACT.md` | The important parts in full detail, the rest as short paragraphs. |
+| `<name>_FULL.md` | Everything: all layers, every part in full, image descriptions, appendix. |
+| `chat_bundle/` | SMALL plus a few images, sized for free-tier upload. |
+| `pack/` | The multi-file pack (`00_READ_ME_FIRST.md`, `01_overview.md`, `02_assembly.md`, `03_parts/`, `05_understanding.md`). |
+| `data/report.json` | Every number, machine readable. `report.schema.json` describes it. |
+| `images/` | Labelled renders. The IDs in the labels are the IDs in the text. |
+
+## IDs
+
+PRT part, INS placed part (one copy of a part in the assembly), H hole, P hole pattern, CP cut-out pattern, C contact,
+J fastener joint, R relation, S slot, PK pocket, B boss, FL fillet, CH chamfer, L rigid link, KJ kinematic
+joint, M mechanism, LP load path, W weak spot, Q question. Face IDs look like F0001.
+
+## Fact or guess
+
+- No prefix: measured from the geometry.
+- `Likely:` an inference. The number is a confidence from 0 to 1 and the reason follows.
+- `Confirmed by designer:` the designer answered a question. Treat as fact, but if a "conflict" note says it
+  disagrees with the geometry, mention the conflict.
+- `Designer unsure:` a soft answer. Treat as a guess.
+
+## Units and frames
+
+Millimetres, degrees, grams. The text states the up and front axes. A hole direction points into the material
+from the entry face. Part files use the part's own frame; assembly placements give each placed part's position
+and rotation in world coordinates.
+
+## What stepscribe cannot know
+
+Threads, material (unless given), tolerances, loads and purpose, unless the designer supplied them. Say so
+when a conclusion depends on one of these.

stepscribe_cad-0.1.0/.github/skills/stepscribe/references/review_checklist.md

@@ -0,0 +1,65 @@
+# Design review checklist (for you, the AI, while reviewing)
+
+Work from the stepscribe output and tool measurements only. For each finding cite IDs and numbers, and say
+whether it rests on measured facts, designer-confirmed facts or "Likely:" inferences. If a needed number is
+missing, call a tool (`measure_distance`, `section`, `get_part`, `list_holes`) or say it is unknown.
+
+## Order of work
+
+1. Read MANIFEST, then SMALL or COMPACT or FULL. Look at the assembly images if you can see images.
+2. Go through the sections below. Note only what the data supports.
+3. Check the weak-spot table (W IDs) first: each has a number, a threshold and a suggestion. Decide which are
+   real problems and which are design advice (a "high" row is a rule-of-thumb breach, not a failure).
+4. Write the review: Summary, Critical issues, Important, Minor, Questions for the designer, What is done well.
+
+## Fasteners and joints
+
+- Do screw lengths fit the grip (stack thickness)? Short-screw rows (W) and the shopping list tell you.
+- Is a load-carrying joint held by a single fastener? Are there fasteners at all where parts only rest?
+- Are holes consistent in size across a joint (clearance vs tapped)? Mixed sizes in one stack are suspicious.
+- Is there room for a tool and a head (look at the spatial facts and the images)?
+
+## Edge distances and walls
+
+- Hole-to-edge distance against the guideline in the finding (it names the process it assumed). Check the
+  assumption: if the process is wrong, the finding changes.
+- Thinnest wall against the process minimum. A sampled wall is an estimate; confirm with `section` before
+  calling it critical.
+- Cut-out webs between openings, and sharp internal corners on printed or bent parts.
+
+## Fits and clearances
+
+- Cylindrical fits: clearance, line-to-line or interference. Is that right for a pivot, a press fit, a bearing seat?
+- Overlaps (interference rows): small volumes can be modelling tolerance or a screw inside its hole; large ones
+  are real collisions. Report the volume.
+- Bearing and shaft seats: do the diameters and widths match a standard size the tool names?
+
+## Kinematics
+
+- Does the joint list match the intended motion? Check axes, parents and children, and `Driven by`.
+- Is there a motor or servo for every joint that should be driven? What does the design say about limits?
+- Degrees of freedom, closed loops, floating parts (not connected to the ground link).
+
+## Stability and loads
+
+- Centre of mass against the support polygon; the tipping angle and the arm-extended case.
+- Load paths: what is the weakest connection on the way to the ground?
+- Cantilevers and unsupported spans next to heavy parts (motors, batteries).
+
+## Manufacturability
+
+- Is the inferred process plausible for each part? Is it consistent with the features (wall thickness, sharp
+  corners, thread-like holes, draft)?
+- Can each part be made as modelled (tool access, minimum radii, overhangs for printing)?
+
+## Assembly order
+
+- Can the parts go together in some order? Look for parts trapped by others, and fasteners that need access
+  that a later part blocks.
+
+## Style of the review
+
+- Prioritise by severity. Prefer few well-supported findings over a long list.
+- Challenge inferences that look wrong; say why with a number.
+- State your assumptions (material, process, loads) when the design context does not give them.
+- End with the questions whose answers would change your conclusions.

stepscribe_cad-0.1.0/.github/skills/stepscribe/scripts/check_env.py

@@ -0,0 +1,56 @@
+"""Print what is available for stepscribe: package version, OpenCASCADE, MCP. Never installs anything."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import importlib.util
+import sys
+
+
+def _has(module: str) -> bool:
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def _version(dist: str) -> str | None:
+    try:
+        return importlib.metadata.version(dist)
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def check() -> dict[str, object]:
+    """Facts about the environment, as a dict."""
+    version = _version("stepscribe-cad") or _version("stepscribe")
+    return {
+        "python": ".".join(str(n) for n in sys.version_info[:3]),
+        "python_ok": sys.version_info >= (3, 11),
+        "stepscribe": version,
+        "stepscribe_importable": _has("stepscribe"),
+        "opencascade": _has("OCP"),
+        "mcp_server": _has("mcp"),
+    }
+
+
+def main() -> int:
+    info = check()
+    print(
+        f"Python {info['python']}"
+        + ("" if info["python_ok"] else " (stepscribe needs 3.11 or newer)")
+    )
+    if info["stepscribe_importable"]:
+        print(f"stepscribe: installed ({info['stepscribe'] or 'version unknown'})")
+    else:
+        print("stepscribe: NOT installed. Ask the user before running: pip install stepscribe")
+    print("OpenCASCADE (OCP): " + ("available" if info["opencascade"] else "missing"))
+    print(
+        "MCP server dependencies: "
+        + ("available" if info["mcp_server"] else 'missing (pip install "stepscribe[mcp]")')
+    )
+    return 0 if info["stepscribe_importable"] and info["opencascade"] else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

stepscribe_cad-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "build/**"]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.11", "3.12"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Virtual display for the image renderer (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y xvfb libgl1-mesa-dri libglx-mesa0
+      - run: python -m pip install -e ".[dev,mcp,llm]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy stepscribe
+      - run: python scripts/sync_skills.py --check
+      - run: python scripts/check_release.py
+      - run: ${{ runner.os == 'Linux' && 'xvfb-run -a ' || '' }}pytest -q -p no:cacheprovider

stepscribe_cad-0.1.0/.github/workflows/cla.yml

@@ -0,0 +1,28 @@
+name: CLA Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, closed, synchronize]
+
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    steps:
+      - name: CLA Assistant
+        if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path-to-signatures: signatures/cla.json
+          path-to-document: https://github.com/idris900323/stepscribe/blob/main/CLA.md
+          branch: cla-signatures
+          allowlist: idris900323,bot*

stepscribe_cad-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: sudo apt-get update && sudo apt-get install -y xvfb libgl1-mesa-dri libglx-mesa0
+      - run: python -m pip install -e ".[dev,mcp,llm]"
+      - run: ruff check .
+      - run: mypy stepscribe
+      - run: python scripts/sync_skills.py --check
+      - run: python scripts/check_release.py --tag "${GITHUB_REF_NAME}"
+      - run: xvfb-run -a pytest -q -p no:cacheprovider
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - run: python scripts/sync_skills.py
+      - run: python scripts/check_release.py --tag "${GITHUB_REF_NAME}" --dist dist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Keep only the wheel and sdist for PyPI
+        run: rm -f dist/stepscribe-skill.zip
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*

stepscribe_cad-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+robot_steps/
+.venv/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+dist/
+tests/fixtures/step/
+out/
+
+# launch-video output
+brag-output/
+brag-output-*/

stepscribe_cad-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- **Measuring:** STEP reader (names, colours, tree, units), exact properties, holes (counterbores, countersinks, blind and through, edge distances), patterns, fillets, chamfers, bosses, slots, pockets, cut-outs (through, recess, stepped, notch), wall thickness, shape classes, standard parts (screws, bearings, motors, extrusions, boards).
+- **Assembly:** instances and transforms, bill of materials, planar and cylindrical contacts, fastener joints and shopping list, relations as sentences, optional interference check.
+- **Understanding layer:** ribs, gussets, symmetry, manufacturing process, links, joints (servo horns included), degrees of freedom, gears, belts, lead screws, load paths, weak spots, stability, part roles, designer questions and answers.
+- **Output:** context pack folder, labelled images with dimensions and joint arrows, `report.json` with a JSON Schema.
+- **Portable export** (`stepscribe export`): FULL, COMPACT and SMALL Markdown, a chat bundle, a manifest and a zip; reused from disk when nothing changed.
+- **AI integrations:** MCP server with background jobs and image content, an Agent Skill, a Claude Code plugin and marketplace with a reviewer agent, a non-interactive `answer` command. None of them start the local web page.
+- **Local web page** (`stepscribe ui`) with progress and ETA, an image viewer and the designer interview.
+- **Speed:** exact contact detection pruned by face boxes, parallel part analysis, fixes for quadratic loops on parts with hundreds of holes.
+- **License:** AGPL-3.0-only with dual licensing, CLA and trademark notice.

stepscribe_cad-0.1.0/CLA.md

@@ -0,0 +1,13 @@
+# Individual Contributor License Agreement
+
+> **Draft: to be reviewed by a lawyer before accepting outside contributions.**
+
+Thank you for contributing to stepscribe. This agreement is between you ("You") and idris sadiq ("the Maintainer"). It is adapted from the Apache Individual Contributor License Agreement. By commenting "I have read the CLA Document and I hereby sign the CLA" on a pull request, You accept these terms for all Contributions You submit to the project.
+
+"Contribution" means any code, documentation or other work that You intentionally submit to the project.
+
+1. **Copyright license.** You grant the Maintainer and recipients of software distributed by the Maintainer a perpetual, worldwide, non-exclusive, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense and distribute Your Contributions and derivative works, **under the GNU AGPL-3.0 or under any other license terms the Maintainer chooses, including commercial and closed-source licenses.**
+2. **Patent license.** You grant a perpetual, worldwide, non-exclusive, royalty-free, irrevocable patent license to make, use, sell, offer to sell, import and transfer the Contribution, for those patent claims You can license that are necessarily infringed by the Contribution alone or combined with the project. If You start patent litigation claiming that the project or a Contribution infringes a patent, the patent licenses You granted end on the date it is filed.
+3. **Your rights.** You keep the copyright in Your Contributions. You confirm that You are legally entitled to grant these licenses, that each Contribution is Your original work, and that if Your employer has rights to Your work, Your employer has allowed the Contribution.
+4. **Third-party material.** If You include work that is not Yours, You will say so and name its source and license in the pull request.
+5. **No warranty or obligation.** Contributions are provided "as is". You are not required to provide support. The Maintainer is not required to accept any Contribution.

stepscribe_cad-0.1.0/COMMERCIAL.md

@@ -0,0 +1,11 @@
+# Commercial use
+
+stepscribe is free and open source under the [GNU AGPL-3.0](LICENSE). Anyone may use, modify and share it under those terms. That includes the obligation to publish the source code of your version when you distribute it or offer it as a network service.
+
+If you want to embed stepscribe in a closed-source product, or run it as a closed hosted service, you can get a **commercial license** from the maintainer, which replaces the AGPL obligations for your use.
+
+Contact: `idris.connected@gmail.com`
+
+The analysis output stepscribe produces for your files belongs to you under either license.
+
+This is not legal advice; have the commercial terms reviewed before selling licenses.

stepscribe_cad-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing to stepscribe
+
+## License and CLA
+
+stepscribe is licensed under the [GNU AGPL-3.0](LICENSE) and is also offered under a commercial license (see [COMMERCIAL.md](COMMERCIAL.md)). To make that possible, every contributor signs the [CLA](CLA.md), which lets the maintainer relicense contributions. When you open your first pull request, a bot asks you to sign by commenting on the PR. You only sign once.
+
+Every Python file under `stepscribe/` starts with the SPDX line `# SPDX-License-Identifier: AGPL-3.0-only` and a copyright line. Keep them on new files.
+
+## Development
+
+```
+python -m venv .venv
+.venv\Scripts\activate          # Windows; on Linux/macOS: source .venv/bin/activate
+pip install -e ".[dev,mcp]"
+pytest
+ruff check .
+mypy
+```
+
+The agent skill lives in `skills/stepscribe/`. After changing it run `python scripts/sync_skills.py` to update the copies in `plugins/` and `.github/skills/` and the skill zip (CI fails if they differ). `python scripts/check_release.py` checks that the package, plugin and marketplace share one version.
+
+Rules the code follows: no network or LLM calls in the core, deterministic output, every number sourced from the STEP file, tests for new behaviour, full typing (mypy strict). Third-party STEP files stay out of the repository (`robot_steps/` is gitignored).
+
+Files use LF line endings (`.gitattributes` enforces this).