modulor 0.5.0__py3-none-any.whl

modulor/__init__.py

@@ -0,0 +1,43 @@
+"""Modulor — agent-native 2D drafting + 3D modeling.
+
+No GUI. The entire tool is a set of JSON commands ("ops") applied to a
+JSON document, reachable four ways:
+
+  CLI batch     modulor run model.json script.json
+  CLI pipe      modulor repl model.json        (JSON Lines in/out)
+  MCP server    modulor mcp                    (for MCP-speaking agents)
+  Python        from modulor import Cad
+
+>>> cad = Cad("house.json", units="mm")
+>>> cad("add_wall", path=[[0, 0], [6000, 0]], thickness=200)
+{'ok': True, 'op': 'add_wall', 'created': ['e1'], 'length': 6000.0}
+>>> cad("render", path="plan.png")
+>>> cad.save()
+"""
+from .document import Document
+from .engine import BatchError, execute, run_batch
+from .errors import CadError
+
+__version__ = "0.5.0"
+__all__ = ["Cad", "Document", "CadError", "BatchError",
+           "execute", "run_batch", "__version__"]
+
+
+class Cad:
+    """Convenience wrapper for Python-side agents and scripts."""
+
+    def __init__(self, path: str | None = None, units: str = "mm"):
+        if path:
+            self.doc = Document.open_or_create(path, units=units)
+        else:
+            self.doc = Document(units=units)
+
+    def __call__(self, op: str, **params) -> dict:
+        return execute(self.doc, {"op": op, **params})
+
+    def run(self, commands) -> list[dict]:
+        return run_batch(self.doc, commands)
+
+    def save(self, path: str | None = None):
+        self.doc.save(path)
+        return self.doc.path

modulor/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

modulor/cli.py

@@ -0,0 +1,264 @@
+"""Command-line front-end.
+
+Everything reads/writes JSON on stdout so output is machine-parseable;
+exit code 0 = success, 1 = structured error, 2 = usage error.
+
+  modulor ops [name]              discover the API
+  modulor new DOC [--units mm]    create an empty document
+  modulor info DOC                document summary
+  modulor run DOC SCRIPT          run a JSON command batch (SCRIPT='-' = stdin)
+  modulor op DOC NAME [JSON]      run a single op
+  modulor repl DOC                JSON-Lines session over stdin/stdout
+  modulor mcp                     MCP stdio server
+"""
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import sys
+
+from .document import Document
+from .engine import BatchError, run_batch
+from .errors import CadError
+from .ops import describe_op, list_ops
+
+
+def main(argv=None) -> int:
+    # Windows consoles default to legacy encodings; force UTF-8 JSON I/O
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+
+    ap = argparse.ArgumentParser(prog="modulor",
+                                 description="Agent-native 2D/3D CAD")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_ops = sub.add_parser("ops", help="list ops / describe one op")
+    p_ops.add_argument("name", nargs="?", help="op name")
+
+    p_new = sub.add_parser("new", help="create an empty document")
+    p_new.add_argument("doc")
+    p_new.add_argument("--units", default="mm")
+
+    p_info = sub.add_parser("info", help="document summary")
+    p_info.add_argument("doc")
+
+    p_chk = sub.add_parser("check",
+                           help="validate a document file against the "
+                                "modulor/1 format (structure + geometry; "
+                                "full JSON Schema if jsonschema is installed)")
+    p_chk.add_argument("doc")
+    p_chk.add_argument("--strict", action="store_true",
+                       help="conformance mode: fail (instead of skipping) "
+                            "when the jsonschema package is unavailable")
+
+    p_run = sub.add_parser("run", help="run a JSON command batch against a doc")
+    p_run.add_argument("doc")
+    p_run.add_argument("script", help="JSON file with a command array, or '-'")
+    p_run.add_argument("--units", default="mm", help="units if doc is created")
+    p_run.add_argument("--as-recipe", action="store_true",
+                       help="store the script as the document's recipe and "
+                            "regenerate from it (parametric workflow)")
+    p_run.add_argument("--pretty", action="store_true")
+
+    p_op = sub.add_parser("op", help="run a single op")
+    p_op.add_argument("doc")
+    p_op.add_argument("name")
+    p_op.add_argument("params", nargs="?", default="{}",
+                      help='op params as JSON, e.g. {"start":[0,0],"end":[1,0]}')
+    p_op.add_argument("--units", default="mm")
+    p_op.add_argument("--pretty", action="store_true")
+
+    p_repl = sub.add_parser("repl", help="JSON-Lines session (one batch per line)")
+    p_repl.add_argument("doc")
+    p_repl.add_argument("--units", default="mm")
+
+    p_srv = sub.add_parser("serve",
+                           help="read-only browser viewer that live-follows "
+                                "the document as agents edit it")
+    p_srv.add_argument("doc")
+    p_srv.add_argument("--port", type=int, default=8400)
+    p_srv.add_argument("--host", default="127.0.0.1")
+    p_srv.add_argument("--no-open", action="store_true",
+                       help="don't launch a browser")
+
+    sub.add_parser("mcp", help="serve the Model Context Protocol over stdio")
+
+    args = ap.parse_args(argv)
+
+    try:
+        if args.cmd == "ops":
+            if args.name:
+                _emit(describe_op(args.name))
+            else:
+                _emit({"ops": list_ops(),
+                       "usage": "modulor ops <name> for parameter details"})
+            return 0
+        if args.cmd == "new":
+            doc = Document(units=args.units)
+            doc.save(args.doc)
+            _emit({"ok": True, "doc": args.doc, "units": doc.units})
+            return 0
+        if args.cmd == "info":
+            doc = Document.load(args.doc)
+            results = run_batch(doc, [{"op": "doc_info"}])
+            _emit(results[0])
+            return 0
+        if args.cmd == "check":
+            return _cmd_check(args)
+        if args.cmd == "run":
+            return _cmd_run(args)
+        if args.cmd == "op":
+            return _cmd_op(args)
+        if args.cmd == "repl":
+            return _cmd_repl(args)
+        if args.cmd == "serve":
+            from .viewer.server import serve as serve_viewer
+            serve_viewer(args.doc, host=args.host, port=args.port,
+                         open_browser=not args.no_open)
+            return 0
+        if args.cmd == "mcp":
+            from .mcp_server import serve
+            serve()
+            return 0
+    except CadError as e:
+        _emit({"ok": False, "error": e.to_dict()})
+        return 1
+    except FileNotFoundError as e:
+        _emit({"ok": False, "error": {"code": "file_not_found", "message": str(e)}})
+        return 1
+    except json.JSONDecodeError as e:
+        _emit({"ok": False, "error": {"code": "bad_json",
+                                      "message": f"invalid JSON: {e}"}})
+        return 1
+    return 2
+
+
+def _cmd_check(args) -> int:
+    """Conformance check for modulor/1 documents — usable against files
+    written by ANY implementation, not just this one.
+
+    Three layers: structural load, geometric validation (the 'validate'
+    op), and — when the optional jsonschema package is available — strict
+    validation against the packaged document.schema.json.
+    """
+    with open(args.doc, "r", encoding="utf-8") as f:
+        raw = json.load(f)
+    doc = Document.from_dict(raw)  # structural: raises bad_format
+
+    problems = run_batch(doc, [{"op": "validate"}])[0]["problems"]
+
+    schema_status = "skipped (pip install modulor[check] to enable)"
+    schema_errors: list[str] = []
+    try:
+        import jsonschema
+    except ImportError:
+        jsonschema = None
+    if jsonschema is None and args.strict:
+        _emit({"ok": False, "doc": args.doc,
+               "error": {"code": "bad_format",
+                         "message": "--strict requires the jsonschema package "
+                                    "for full conformance validation",
+                         "hint": "pip install modulor[check]"}})
+        return 1
+    if jsonschema is not None:
+        import os as _os
+        schema_path = _os.path.join(_os.path.dirname(__file__),
+                                    "document.schema.json")
+        with open(schema_path, "r", encoding="utf-8") as f:
+            schema = json.load(f)
+        validator = jsonschema.Draft202012Validator(schema)
+        schema_errors = [f"{e.json_path}: {e.message[:160]}"
+                         for e in validator.iter_errors(raw)][:20]
+        schema_status = "ok" if not schema_errors else "failed"
+
+    ok = not problems and not schema_errors
+    _emit({"ok": ok, "doc": args.doc,
+           "format": raw.get("format"), "units": doc.units,
+           "entities": len(doc.entities),
+           "geometry_problems": problems,
+           "schema": schema_status,
+           "schema_errors": schema_errors})
+    return 0 if ok else 1
+
+
+def _cmd_run(args) -> int:
+    if args.script == "-":
+        commands = json.loads(sys.stdin.buffer.read().decode("utf-8-sig"))
+    else:
+        with open(args.script, "r", encoding="utf-8-sig") as f:
+            commands = json.load(f)
+    doc = Document.open_or_create(args.doc, units=args.units)
+    if getattr(args, "as_recipe", False):
+        if isinstance(commands, dict):
+            commands = [commands]
+        commands = [{"op": "recipe_set", "commands": commands, "run": True}]
+    try:
+        results = run_batch(doc, commands)
+    except BatchError as e:
+        _emit({"ok": False, "error": e.to_dict(), "results": e.results,
+               "doc": args.doc, "saved": False}, args.pretty)
+        return 1
+    doc.save()
+    _emit({"ok": True, "results": results, "doc": args.doc, "saved": True},
+          args.pretty)
+    return 0
+
+
+def _cmd_op(args) -> int:
+    params = json.loads(args.params)
+    if not isinstance(params, dict):
+        raise CadError("bad_json", "params must be a JSON object")
+    doc = Document.open_or_create(args.doc, units=args.units)
+    try:
+        results = run_batch(doc, [{"op": args.name, **params}])
+    except BatchError as e:
+        _emit({"ok": False, "error": e.to_dict(), "doc": args.doc,
+               "saved": False}, args.pretty)
+        return 1
+    doc.save()
+    _emit({**results[0], "doc": args.doc, "saved": True}, args.pretty)
+    return 0
+
+
+def _cmd_repl(args) -> int:
+    """One JSON command (or array) per input line -> one JSON result line.
+
+    The document is saved after every successful line; a failed line is
+    rolled back by reloading the last saved state, so each line is atomic.
+    """
+    doc = Document.open_or_create(args.doc, units=args.units)
+    doc.save()
+    stdin = io.TextIOWrapper(sys.stdin.buffer, encoding="utf-8-sig")
+    _emit({"ok": True, "ready": True, "doc": args.doc,
+           "hint": 'one JSON command or array per line; {"op":"help"} lists ops'})
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        if line in ("exit", "quit"):
+            break
+        try:
+            commands = json.loads(line)
+            results = run_batch(doc, commands)
+            doc.save()
+            _emit({"ok": True, "results": results, "saved": True})
+        except json.JSONDecodeError as e:
+            _emit({"ok": False, "error": {"code": "bad_json",
+                                          "message": f"invalid JSON: {e}"}})
+        except BatchError as e:
+            doc = Document.load(args.doc)  # roll back this line
+            _emit({"ok": False, "error": e.to_dict(), "results": e.results,
+                   "saved": False})
+    return 0
+
+
+def _emit(obj, pretty: bool = False):
+    print(json.dumps(obj, ensure_ascii=False,
+                     indent=2 if pretty else None))
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

modulor/document.py

@@ -0,0 +1,248 @@
+"""Document model: a JSON-serializable scene of layers, materials and entities.
+
+The whole document is plain data (dicts/lists) so it round-trips losslessly
+through JSON and is trivially inspectable by agents. Entity ids are "e1",
+"e2", ... and never reused within a document.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+from .errors import CadError
+
+FORMAT = "modulor/1"
+# documents written before the rename remain readable forever
+LEGACY_FORMATS = ("nativecad/1",)
+UNITS = ("mm", "cm", "m", "in", "ft")
+
+DEFAULT_LAYER = {"color": "#222222", "visible": True, "line_width": 1.0}
+DEFAULT_MATERIAL = {"color": "#9aa0a6", "metallic": 0.0, "roughness": 0.8}
+
+ENTITY_TYPES_2D = ("line", "polyline", "spline", "circle", "arc", "region",
+                   "text", "dim", "dim_angular", "dim_radial", "wall",
+                   "grid", "room")
+ENTITY_TYPES_3D = ("solid",)
+ENTITY_TYPES = ENTITY_TYPES_2D + ENTITY_TYPES_3D
+
+
+class Document:
+    def __init__(self, units: str = "mm", name: str = "untitled"):
+        if units not in UNITS:
+            raise CadError("bad_param", f"unknown units {units!r}",
+                           hint=f"use one of {UNITS}")
+        self.units = units
+        self.meta = {"name": name, "created": _now(), "modified": _now()}
+        self.layers: dict[str, dict] = {"0": dict(DEFAULT_LAYER)}
+        self.materials: dict[str, dict] = {"default": dict(DEFAULT_MATERIAL)}
+        self.entities: dict[str, dict] = {}
+        self.params: dict[str, float] = {}     # named design parameters
+        self.levels: dict[str, dict] = {}      # name -> {elevation, height}
+        self.recipe: list[dict] = []           # the program that built this doc
+        self._counter = 0
+        self.path: str | None = None  # where this doc lives on disk, if anywhere
+
+    # ------------------------------------------------------------- expressions
+
+    def resolve(self, value):
+        """Number params accept expression strings: 'bay*3+200',
+        'level("L2")', 'grid_x("B")'. Returns a float."""
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            return float(value)
+        if not isinstance(value, str):
+            raise CadError("bad_param", f"expected number or expression, "
+                                        f"got {value!r}")
+        from .expr import eval_expr
+
+        def level(name, _key="elevation"):
+            if name not in self.levels:
+                raise CadError("not_found", f"no level named {name!r}",
+                               hint=f"levels: {sorted(self.levels)}")
+            return float(self.levels[name]["elevation"])
+
+        def level_top(name):
+            lv = self.levels.get(name)
+            if lv is None:
+                raise CadError("not_found", f"no level named {name!r}")
+            return float(lv["elevation"]) + float(lv.get("height", 0.0))
+
+        def _grid_lookup(axis, label):
+            label = str(label)
+            for ent in self.entities.values():
+                if ent.get("type") != "grid":
+                    continue
+                labels = ent[f"{axis}_labels"]
+                coords = ent[f"{axis}s"]
+                if label in labels:
+                    return float(coords[labels.index(label)])
+            raise CadError("not_found", f"no grid line labeled {label!r} "
+                                        f"on the {axis} axis")
+
+        out = eval_expr(value, extra_names=dict(self.params),
+                        extra_funcs={"level": level, "level_top": level_top,
+                                     "grid_x": lambda s: _grid_lookup("x", s),
+                                     "grid_y": lambda s: _grid_lookup("y", s)})
+        import math
+        if not math.isfinite(out):
+            raise CadError("bad_expr",
+                           f"expression {value!r} produced a non-finite number")
+        return out
+
+    # ------------------------------------------------------------- ids
+
+    def new_id(self) -> str:
+        self._counter += 1
+        return f"e{self._counter}"
+
+    # ------------------------------------------------------------- entities
+
+    def add_entity(self, etype: str, data: dict, layer: str = "0",
+                   tag: str | None = None) -> str:
+        if etype not in ENTITY_TYPES:
+            raise CadError("bad_type", f"unknown entity type {etype!r}")
+        if layer not in self.layers:
+            # auto-create layers on first use: agents shouldn't have to
+            # pre-declare every layer
+            self.layers[layer] = dict(DEFAULT_LAYER)
+        eid = self.new_id()
+        ent = {"type": etype, "layer": layer, **data}
+        if tag:
+            ent["tag"] = tag
+        self.entities[eid] = ent
+        return eid
+
+    def get_entity(self, eid: str) -> dict:
+        if not isinstance(eid, str):
+            raise CadError("bad_selector",
+                           f"entity ids are strings, got {eid!r}")
+        if eid not in self.entities:
+            # ids are generated lowercase ("e7") but renders display them in a
+            # caps-only stroke font; accept "E7" so reading an image works
+            low = eid.lower() if isinstance(eid, str) else eid
+            if low in self.entities:
+                return self.entities[low]
+            raise CadError("not_found", f"entity {eid!r} does not exist",
+                           hint="use the 'list' op to see existing ids")
+        return self.entities[eid]
+
+    def delete_entities(self, ids) -> int:
+        n = 0
+        for eid in ids:
+            if eid in self.entities:
+                del self.entities[eid]
+                n += 1
+        return n
+
+    # ------------------------------------------------------------- selectors
+
+    def select(self, sel) -> list[str]:
+        """Resolve a selector to entity ids (in creation order).
+
+        Selector forms:
+          "all"                      -> every entity
+          "e12"                      -> single id
+          ["e1", "e2"]               -> list of ids (errors on unknown id)
+          {"ids": [...], "tags": [...], "layers": [...], "types": [...]}
+                                     -> AND of the given filters
+        """
+        if sel is None or sel == "all":
+            return list(self.entities.keys())
+        norm = lambda e: e if e in self.entities else \
+            (e.lower() if isinstance(e, str) else e)  # noqa: E731
+        if isinstance(sel, str):
+            self.get_entity(sel)
+            return [norm(sel)]
+        if isinstance(sel, list):
+            for eid in sel:
+                self.get_entity(eid)
+            return [norm(e) for e in sel]
+        if isinstance(sel, dict):
+            ids = sel.get("ids")
+            if ids:
+                ids = [norm(e) for e in ids]
+            tags = sel.get("tags") or ([sel["tag"]] if sel.get("tag") else None)
+            layers = sel.get("layers") or ([sel["layer"]] if sel.get("layer") else None)
+            types = sel.get("types") or ([sel["type"]] if sel.get("type") else None)
+            if ids:
+                for eid in ids:
+                    self.get_entity(eid)
+            out = []
+            for eid, ent in self.entities.items():
+                if ids and eid not in ids:
+                    continue
+                if tags and ent.get("tag") not in tags:
+                    continue
+                if layers and ent.get("layer") not in layers:
+                    continue
+                if types and ent.get("type") not in types:
+                    continue
+                out.append(eid)
+            return out
+        raise CadError("bad_selector", f"cannot interpret selector {sel!r}",
+                       hint='use "all", an id, a list of ids, or '
+                            '{"layers": [...], "types": [...], "tags": [...]}')
+
+    # ------------------------------------------------------------- io
+
+    def to_dict(self) -> dict:
+        return {
+            "format": FORMAT,
+            "units": self.units,
+            "meta": self.meta,
+            "counter": self._counter,
+            "layers": self.layers,
+            "materials": self.materials,
+            "params": self.params,
+            "levels": self.levels,
+            "recipe": self.recipe,
+            "entities": self.entities,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Document":
+        if d.get("format") not in (FORMAT, *LEGACY_FORMATS):
+            raise CadError("bad_format", f"not a {FORMAT} document")
+        doc = cls(units=d.get("units", "mm"))
+        doc.meta = d.get("meta", doc.meta)
+        doc._counter = int(d.get("counter", 0))
+        doc.layers = d.get("layers", doc.layers)
+        doc.materials = d.get("materials", doc.materials)
+        doc.params = d.get("params", {})
+        doc.levels = d.get("levels", {})
+        doc.recipe = d.get("recipe", [])
+        doc.entities = d.get("entities", {})
+        return doc
+
+    def save(self, path: str | None = None):
+        path = path or self.path
+        if not path:
+            raise CadError("no_path", "document has no file path")
+        self.meta["modified"] = _now()
+        d = os.path.dirname(os.path.abspath(path))
+        if d and not os.path.isdir(d):
+            os.makedirs(d, exist_ok=True)
+        tmp = path + ".tmp"
+        with open(tmp, "w", encoding="utf-8") as f:
+            json.dump(self.to_dict(), f, ensure_ascii=False, separators=(",", ":"))
+        os.replace(tmp, path)
+        self.path = path
+
+    @classmethod
+    def load(cls, path: str) -> "Document":
+        with open(path, "r", encoding="utf-8") as f:
+            doc = cls.from_dict(json.load(f))
+        doc.path = path
+        return doc
+
+    @classmethod
+    def open_or_create(cls, path: str, units: str = "mm") -> "Document":
+        if os.path.exists(path):
+            return cls.load(path)
+        doc = cls(units=units, name=os.path.splitext(os.path.basename(path))[0])
+        doc.path = path
+        return doc
+
+
+def _now() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%S")