agentcad 0.1.0__tar.gz

agentcad-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: agentcad
+Version: 0.1.0
+Summary: CLI CAD tool for AI agents. Write CadQuery scripts, get STEP files, renders, and metrics.
+Author: James Dillard
+License: BSL-1.1
+Project-URL: Repository, https://github.com/jdilla1277/agentcad
+Keywords: cad,agent,cadquery,3d,geometry,ai,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: cadquery>=2.0
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"

agentcad-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentcad"
+version = "0.1.0"
+description = "CLI CAD tool for AI agents. Write CadQuery scripts, get STEP files, renders, and metrics."
+requires-python = ">=3.10,<3.13"
+license = {text = "BSL-1.1"}
+authors = [{name = "James Dillard"}]
+keywords = ["cad", "agent", "cadquery", "3d", "geometry", "ai", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = ["click>=8.0", "cadquery>=2.0"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.0.0"]
+
+[project.urls]
+Repository = "https://github.com/jdilla1277/agentcad"
+
+
+[project.scripts]
+agentcad = "agentcad.cli:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]

agentcad-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentcad-0.1.0/src/agentcad/cli.py

@@ -0,0 +1,271 @@
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+
+from agentcad.session_log import SessionLogger
+from agentcad.commands.context import context
+from agentcad.commands.daemon_cmd import daemon
+from agentcad.commands.diff import diff
+from agentcad.commands.docs import docs
+from agentcad.commands.export_cmd import export_cmd
+from agentcad.commands.feedback import feedback
+from agentcad.commands.init import init
+from agentcad.commands.inspect_cmd import inspect_cmd
+from agentcad.commands.render import render
+from agentcad.commands.run import run
+from agentcad.commands.skill import skill
+from agentcad.commands.view import view
+
+
+_BRIEFING = """\b
+EXAMPLE SESSION
+  $ agentcad init --name myproject
+  {"command": "init", "status": "success", "project": "myproject"}
+\b
+  Write a script — no imports needed, cq and show_object are pre-injected:
+    box = cq.Workplane('XY').box(10, 20, 5)
+    show_object(box)
+\b
+  $ agentcad run box.py --output first --render iso --preview
+  {"command": "run", "status": "success", "version": 1, "label": "first",
+   "outputs": {"step": "v1_first/output.step", "script": "v1_first/script.py"},
+   "metrics": {"dimensions": {"x": 10.0, "y": 20.0, "z": 5.0},
+               "volume": 1000.0, "surface_area": 700.0, "face_count": 6,
+               "edge_count": 12, "is_valid": true, ...},
+   "preview": "v1_first/preview.png",
+   "renders": {"iso": "v1_first/renders/iso.png"}}
+
+\b
+  Version directory layout:
+    v1_first/
+      output.step       STEP geometry
+      script.py         copy of the executed script
+      meta.json         full run metadata
+      preview.png       256x256 iso preview (when --preview used)
+      renders/          PNG views (when --render used)
+        iso.png
+
+\b
+WRITING SCRIPTS
+  show_object(result) is required — it tells agentcad what geometry to output.
+  These names are pre-injected (no import needed):
+    cq             cadquery module
+    show_object    surfaces geometry to agentcad (required — at least one call)
+    translate      translate(shape, x, y, z)
+    rotate         rotate(shape, axis, angle_deg) — axis: 'X'/'Y'/'Z'
+                   Right-hand rule: positive = counterclockwise from + axis
+    mirror_fuse    mirror_fuse(shape, plane='XZ') — mirror + boolean fuse
+    loft_sections  loft_sections(sections, smooth=True) — loft wires into solid
+    tapered_sweep  tapered_sweep(spine, radii) — circles along spine
+    naca_wire      naca_wire(y, le_x, te_x, thickness, profile='0012')
+
+\b
+  .val().wrapped — extracting a TopoDS_Shape from CadQuery's fluent API:
+    CadQuery methods return Workplane objects. The helpers (translate, rotate,
+    etc.) operate on raw TopoDS_Shape. To bridge them:
+      part = cq.Workplane('XY').box(10, 20, 5).val().wrapped  # -> TopoDS_Shape
+      moved = translate(part, 50, 0, 0)                       # -> TopoDS_Shape
+
+\b
+  Showing helper output:
+    Helpers return TopoDS_Shape. To pass back to show_object:
+      shape = cq.Shape.cast(topo_shape)
+      show_object(cq.Workplane('XY').newObject([shape]))
+    Or use multiple show_object() calls — agentcad auto-compounds them.
+
+\b
+  Explicit imports still work (adding 'import cadquery as cq' is harmless).
+  For OCP internals (e.g. OCP.gp, OCP.BRepPrimAPI), import manually.
+
+\b
+COMMANDS
+  agentcad init [--name NAME]
+    Initialize project. Creates agentcad.json manifest.
+
+\b
+  agentcad run SCRIPT --output LABEL [flags]
+    Execute script, produce versioned STEP + metrics.
+    --render VIEWS   PNG views: front,back,left,right,top,bottom,iso,
+                     'all', custom angle az:el (e.g. 45:30),
+                     or mixed (front,right,45:30).
+    --export FMT     Mesh export: stl, glb (GLB auto-colors per-solid).
+    --preview        Quick 256x256 iso PNG.
+    --params K=V,..  Override top-level script constants.
+    --dry-run        Metrics only — no version consumed, no disk artifacts.
+
+\b
+  agentcad render STEP --view SPEC [--zoom N] [--focus x,y,z] [--no-fit] [--name LABEL]
+    Render PNG views of an existing STEP file. Same view spec as --render.
+    Use this for post-hoc rendering with camera control (zoom, focus).
+
+\b
+  agentcad export STEP --format stl,glb,obj
+    Export STEP to mesh formats. GLB auto-colors individual solids.
+
+\b
+  agentcad inspect STEP
+    Topology report: solid_count, shell_count, shells (open/closed + face
+    count per shell), face_count, face_orientations (forward/reversed),
+    edge_count, free_edge_count, is_valid.
+
+\b
+  agentcad diff REF1 REF2        Compare versions (by number or label).
+  agentcad context               Project state: versions, current, tool_version.
+  agentcad view FILE             Open GLB/STEP in browser (three.js). STEP auto-converts.
+  agentcad daemon start|stop|status   Background worker — eliminates 3-5s cold start.
+  agentcad docs [SECTION]        Deep-dive docs (15 sections).
+
+\b
+RESPONSE SCHEMA
+  Every command returns JSON with "command" and "status" keys.
+    "success"          — completed normally.
+    "failed"           — script error. Version IS consumed. Creates v{N}_{label}_failed/.
+    "error"            — CLI error (bad args, missing file). No version consumed. No disk artifacts.
+    "validation_error" — static check failed (syntax, missing show_object, bad import).
+                         No version consumed. No disk artifacts. Instant (<100ms).
+
+\b
+METRICS (in every successful run response)
+  bounding_box   {x: [min,max], y: [min,max], z: [min,max]}
+  dimensions     {x, y, z}       bbox extents
+  volume         float            unit-agnostic (CadQuery defaults mm -> mm^3)
+  surface_area   float
+  center_of_mass {x, y, z}
+  face_count     int              unique faces
+  edge_count     int              unique edges
+  is_valid       bool             BRepCheck shape validity
+  Tip: verify geometry from metrics alone — check volume, dimensions, face_count
+  before rendering. Use 'agentcad diff' to compare metrics across versions.
+
+\b
+PARAMETRIC SCRIPTS
+  Top-level assignments become overridable parameters:
+    length = 50.0
+    width = 20.0
+    result = cq.Workplane('XY').box(length, width, 10)
+    show_object(result)
+  $ agentcad run script.py --output v2 --params length=100,width=30
+  Types auto-coerced: bool ('true'/'false') > int > float > string.
+  Unknown param name -> "error" status with available names (no version consumed).
+
+\b
+CADQUERY PATTERNS
+  Build at origin, then position:
+    part = cq.Workplane('XY').box(10, 20, 5).val().wrapped
+    placed = translate(part, 50, 0, 0)
+\b
+  Angled positioning (build along Z, rotate, translate to attachment):
+    arm = cq.Workplane('XY').circle(5).extrude(120).val().wrapped
+    tilted = rotate(arm, 'Y', 30)
+    placed = translate(tilted, 0, 0, 8)
+\b
+  Compound vs Union:
+    cq.Compound.makeCompound([...])  spatial grouping, parts stay separate
+    .union()                         boolean fuse into single solid
+\b
+  Revolve: axis is relative to workplane origin, not sketch pen position.
+    .move() shifts pen without moving origin — trap. Use .transformed(offset=(...)).
+\b
+  Workplane stacking:
+    .transformed(offset=(x,y,z))  shift origin in local coords
+    .workplane(offset=N)          stack along normal
+    .center(x, y)                 move pen relative to origin
+    .move(x, y)                   move pen only (origin stays)
+\b
+  twistExtrude performance:
+    For profiles with >100 points, use polyline() instead of spline().
+    1000-point spline + twistExtrude can take 5+ minutes; polyline < 1 min.
+
+\b
+DEBUGGING
+  Geometry wrong? Check metrics first — volume and dimensions catch most issues.
+  $ agentcad run script.py --output test --dry-run        # metrics, no disk artifacts
+  $ agentcad inspect v1_test/output.step                  # topology deep-dive
+    Hollow shape?     -> free_edge_count > 0, shell not closed
+    Inverted normals? -> face_orientations imbalanced
+    Invalid?          -> is_valid: false
+  $ agentcad render v1_test/output.step --view all        # visual from 4 angles
+  Then iterate: fix script, run with new --output label.
+
+\b
+MCP INTEGRATION
+  For native tool integration with Claude Code, Cursor, Windsurf, or any
+  MCP-compatible agent, install the MCP extra and add to your .mcp.json:
+
+  pip install agentcad[mcp]
+
+  .mcp.json:
+    {"agentcad": {"command": "python", "args": ["-m", "agentcad.mcp"]}}
+
+  This exposes all agentcad commands as native agent tools — no CLI
+  parsing needed. The agent calls run(), inspect(), docs() etc. directly.
+"""
+
+
+class _LoggingGroup(click.Group):
+    """Click Group that auto-logs every command invocation to session.jsonl."""
+
+    def invoke(self, ctx):
+        captured = []
+        original_echo = click.echo
+
+        def _capturing_echo(message=None, **kwargs):
+            if message is not None:
+                captured.append(str(message))
+            original_echo(message, **kwargs)
+
+        click.echo = _capturing_echo
+        try:
+            return super().invoke(ctx)
+        finally:
+            click.echo = original_echo
+            self._log_session(ctx, captured)
+
+    def _log_session(self, ctx, captured):
+        if os.environ.get("AGENTCAD_NO_LOG"):
+            return
+        # Find the subcommand name and args
+        cmd_name = ctx.invoked_subcommand
+        if not cmd_name or cmd_name == "feedback":
+            return
+        # Parse the last JSON output (commands may echo multiple things)
+        result = {}
+        for line in reversed(captured):
+            try:
+                result = json.loads(line)
+                break
+            except (json.JSONDecodeError, TypeError):
+                continue
+        # Collect the raw args from sys.argv
+        args = sys.argv[2:] if len(sys.argv) > 2 else []
+        try:
+            logger = SessionLogger(Path.cwd())
+            logger.log(cmd_name, {"argv": args}, result)
+        except Exception:
+            pass  # Never let logging break the CLI
+
+
+@click.group(
+    cls=_LoggingGroup,
+    epilog=_BRIEFING,
+    context_settings=dict(max_content_width=120),
+)
+def cli():
+    """agentcad — CLI CAD tool for AI agents. All output is JSON."""
+
+
+cli.add_command(context)
+cli.add_command(daemon)
+cli.add_command(diff)
+cli.add_command(docs)
+cli.add_command(export_cmd)
+cli.add_command(feedback)
+cli.add_command(init)
+cli.add_command(inspect_cmd)
+cli.add_command(render)
+cli.add_command(run)
+cli.add_command(skill)
+cli.add_command(view)

agentcad-0.1.0/src/agentcad/commands/context.py

@@ -0,0 +1,36 @@
+import json
+
+import click
+
+from agentcad.manifest import load_manifest
+
+TOOL_VERSION = "0.1.0"
+
+
+@click.command()
+def context():
+    """Show the current project context."""
+    manifest = load_manifest(command="context")
+
+    versions = manifest.get("versions", [])
+    current = manifest.get("current", None)
+
+    versions_summary = [
+        {
+            "version": v["version"],
+            "label": v["label"],
+            "status": v["status"],
+            "path": v["path"],
+        }
+        for v in versions
+    ]
+
+    click.echo(json.dumps({
+        "command": "context",
+        "status": "success",
+        "project": manifest["name"],
+        "tool_version": TOOL_VERSION,
+        "current": current,
+        "version_count": len(versions),
+        "versions": versions_summary,
+    }))

agentcad-0.1.0/src/agentcad/commands/daemon_cmd.py

@@ -0,0 +1,59 @@
+import json
+
+import click
+
+from agentcad.daemon import (
+    _default_pid_path,
+    _default_socket_path,
+    daemon_status,
+    start_daemon,
+    stop_daemon,
+)
+
+
+def _socket_path():
+    return _default_socket_path()
+
+
+def _pid_path():
+    return _default_pid_path()
+
+
+@click.group()
+def daemon():
+    """Manage the agentcad background daemon."""
+
+
+@daemon.command()
+def start():
+    """Start the daemon worker."""
+    result = start_daemon(
+        socket_path=_socket_path(),
+        pid_path=_pid_path(),
+    )
+    ok = result.get("started", False) or "already running" in result.get("message", "").lower()
+    output = {"command": "daemon", "status": "success" if ok else "error", **result}
+    click.echo(json.dumps(output))
+
+
+@daemon.command()
+def stop():
+    """Stop the daemon worker."""
+    result = stop_daemon(
+        socket_path=_socket_path(),
+        pid_path=_pid_path(),
+    )
+    ok = result.get("stopped", False)
+    output = {"command": "daemon", "status": "success" if ok else "error", **result}
+    click.echo(json.dumps(output))
+
+
+@daemon.command()
+def status():
+    """Check daemon status."""
+    result = daemon_status(
+        socket_path=_socket_path(),
+        pid_path=_pid_path(),
+    )
+    output = {"command": "daemon", "status": "success", **result}
+    click.echo(json.dumps(output))

agentcad-0.1.0/src/agentcad/commands/diff.py

@@ -0,0 +1,141 @@
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from agentcad.manifest import load_manifest
+
+
+def _resolve_version(manifest, ref):
+    """Resolve a version reference (number or label) to a manifest version entry."""
+    versions = manifest.get("versions", [])
+
+    # Try as version number first
+    try:
+        num = int(ref)
+        for v in versions:
+            if v["version"] == num:
+                return v
+    except ValueError:
+        pass
+
+    # Try as label
+    for v in versions:
+        if v["label"] == ref:
+            return v
+
+    return None
+
+
+def _load_version_meta(version_entry):
+    """Load meta.json for a version entry."""
+    path = Path.cwd() / version_entry["path"] / "meta.json"
+    return json.loads(path.read_text())
+
+
+def _compute_set_diff(old_keys, new_keys):
+    """Compute added/removed/unchanged between two sets of keys."""
+    old_set = set(old_keys)
+    new_set = set(new_keys)
+    return {
+        "added": sorted(new_set - old_set),
+        "removed": sorted(old_set - new_set),
+        "unchanged": sorted(old_set & new_set),
+    }
+
+
+def _scalar_diff(old_val, new_val):
+    """Return None if same, {from, to} if different."""
+    if old_val == new_val:
+        return None
+    return {"from": old_val, "to": new_val}
+
+
+@click.command()
+@click.argument("ref1")
+@click.argument("ref2")
+def diff(ref1, ref2):
+    """Compare two versions of a model."""
+    manifest = load_manifest(command="diff")
+
+    v1_entry = _resolve_version(manifest, ref1)
+    if v1_entry is None:
+        click.echo(json.dumps({
+            "command": "diff",
+            "status": "error",
+            "message": f"Version '{ref1}' not found",
+        }))
+        sys.exit(1)
+
+    v2_entry = _resolve_version(manifest, ref2)
+    if v2_entry is None:
+        click.echo(json.dumps({
+            "command": "diff",
+            "status": "error",
+            "message": f"Version '{ref2}' not found",
+        }))
+        sys.exit(1)
+
+    meta1 = _load_version_meta(v1_entry)
+    meta2 = _load_version_meta(v2_entry)
+
+    # Compute changes
+    changes = {
+        "label": _scalar_diff(meta1.get("label"), meta2.get("label")),
+        "status": _scalar_diff(meta1.get("status"), meta2.get("status")),
+        "outputs": _compute_set_diff(
+            meta1.get("outputs", {}).keys(),
+            meta2.get("outputs", {}).keys(),
+        ),
+        "renders": _compute_set_diff(
+            meta1.get("renders", {}).keys(),
+            meta2.get("renders", {}).keys(),
+        ),
+    }
+
+    # Compare metrics if present in either version
+    m1 = meta1.get("metrics", {})
+    m2 = meta2.get("metrics", {})
+    if m1 or m2:
+        all_keys = sorted(set(m1.keys()) | set(m2.keys()))
+        changes["metrics"] = {
+            k: _scalar_diff(m1.get(k), m2.get(k)) for k in all_keys
+        }
+
+    # Compare params if present in either version
+    p1 = meta1.get("params", {})
+    p2 = meta2.get("params", {})
+    if p1 or p2:
+        all_param_keys = sorted(set(p1.keys()) | set(p2.keys()))
+        changes["params"] = {
+            k: _scalar_diff(p1.get(k), p2.get(k)) for k in all_param_keys
+        }
+
+    # Compare parts if present in either version
+    parts1 = {p["name"]: p for p in meta1.get("parts", [])}
+    parts2 = {p["name"]: p for p in meta2.get("parts", [])}
+    if parts1 or parts2:
+        parts_changes = {
+            "names": _compute_set_diff(parts1.keys(), parts2.keys()),
+        }
+        shared = sorted(set(parts1.keys()) & set(parts2.keys()))
+        for name in shared:
+            p1_part = parts1[name]
+            p2_part = parts2[name]
+            part_diff = {"color": _scalar_diff(p1_part.get("color"), p2_part.get("color"))}
+            m1_metrics = p1_part.get("metrics", {})
+            m2_metrics = p2_part.get("metrics", {})
+            all_mkeys = sorted(set(m1_metrics.keys()) | set(m2_metrics.keys()))
+            for k in all_mkeys:
+                part_diff[k] = _scalar_diff(m1_metrics.get(k), m2_metrics.get(k))
+            parts_changes[name] = part_diff
+        changes["parts"] = parts_changes
+
+    click.echo(json.dumps({
+        "command": "diff",
+        "status": "success",
+        "v1": {"version": meta1["version"], "label": meta1["label"]},
+        "v2": {"version": meta2["version"], "label": meta2["label"]},
+        "changes": changes,
+    }))