lobole 0.1.0__py3-none-any.whl

lobole/__init__.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Elias Högbom Aronsson and Loböle contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Drive a running Loböle instance from Python (docs/scripting/README.md).
+
+    from lobole import connect
+    app = connect()                 # the one running instance, or port=
+    part = app.part("bracket")
+
+`Client` is the plain JSON-RPC client (dict in, dict out); `App` is the SDK
+over it, with the whole RPC surface generated from the running app's
+`describe` and geometry handles instead of transcribed numbers. Every error
+either raises is a `LoboleError`; a refused call is a `Refused`
+(lobole.errors).
+"""
+from lobole.client import Client
+from lobole.errors import (BudgetExceeded, ConnectionLost, InternalError,
+                           InvalidArgument, LoboleError, MissingArgument,
+                           NonFiniteError, Refused, SdkError, StaleRevision,
+                           StaleSnapshot, UnknownArgument)
+from lobole.sdk import App, connect
+
+__all__ = [
+    "App", "BudgetExceeded", "Client", "ConnectionLost", "InternalError",
+    "InvalidArgument", "LoboleError", "MissingArgument", "NonFiniteError",
+    "Refused", "SdkError", "StaleRevision", "StaleSnapshot",
+    "UnknownArgument", "connect"]

lobole/client.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Elias Högbom Aronsson and Loböle contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Remote-control client for Loböle (start the app with --remote <port>).
+
+Library:
+    from lobole.client import Client
+    d = Client(8437)
+    d.call("add_feature", feature={"type": "Box", "name": "Box 1",
+                                   "on": "Top",
+                                   "width": 2, "depth": 2, "height": 2})
+    print(d.call("get_state"))
+
+CLI:
+    python3 -m lobole.client <port> <method> ['<params-json>']
+    python3 -m lobole.client 8437 get_state
+    python3 -m lobole.client 8437 menu_click '{"path": "File/New"}'
+    python3 -m lobole.client 8437 screenshot '{"path": "/tmp/shot.png"}'
+"""
+import json
+import socket
+import sys
+import time
+
+from lobole.errors import (ConnectionLost, LoboleError, NonFiniteError,
+                           Refused, UnknownArgument, refusal)
+
+
+def _check_result(method, result):
+    """A strict client holds an answer to its row's typed `returns` column
+    (docs/scripting/rpc.md#typed-results): every smoke runs strict, so a
+    key the handler adds, drops or retypes without its row fails the test
+    that saw it, instead of reaching a caller as a KeyError."""
+    from lobole.rpc import RESULT_SCHEMAS
+    schema = RESULT_SCHEMAS.get(method)
+    if schema is None:
+        return
+    from lobole.contracts import validate
+    try:
+        validate(schema, result, method, "/result")
+    except Refused as e:
+        raise LoboleError(f"{method}: the answer breaks its returns "
+                          f"contract — {e}") from None
+
+
+class Client:
+    """`strict`: an answer holding a non-finite number raises NonFiniteError
+    instead of warning. Unset, it follows LOBOLE_REMOTE_STRICT=1, which
+    tests/smoke_app.py sets, so every smoke runs strict."""
+
+    def __init__(self, port, host="127.0.0.1", timeout=60.0, strict=None):
+        self.sock = socket.create_connection((host, port), timeout=timeout)
+        self.file = self.sock.makefile("rw")
+        self._id = 0
+        if strict is None:
+            import os
+            strict = os.environ.get("LOBOLE_REMOTE_STRICT") == "1"
+        self.strict = strict
+
+    # `method` is POSITIONAL-ONLY, so an RPC with a parameter of that name —
+    # `describe {method}` — is reachable as call("describe", method="x"). It
+    # used to be an ordinary argument, the keyword collided with it, and the
+    # workaround was to know to use request() instead.
+    def call(self, method, /, **params):
+        return self.request(method, params)
+
+    def help(self, method=""):
+        """What `method` does and takes — `method_help` below, the same
+        answer the MCP server's help() gives. With no method, the index.
+        `call("help", method=...)` and `request("help", ...)` reach it too:
+        the MCP instructions tell an agent to ask help(), and over this
+        client that used to be "unknown method"."""
+        return method_help(self.call, method)
+
+    # Params as a DICT rather than keywords.
+    def request(self, method, params=None, timeout=None):
+        """`timeout` (seconds) overrides the connection default for THIS
+        call. A modal solve on a fine mesh outlived the 60 s default, the
+        client died mid-call, and the server finished anyway — which reads
+        as a hang followed by a mystery. mesh_study/run_study want a long
+        one (or run_study {async: true} + study_status polling)."""
+        # `help` is answered here, from `describe`, rather than being a
+        # second copy of the method table in the app (method_help).
+        if method == "help":
+            extra = sorted(set(params or {}) - {"method"})
+            if extra:
+                raise UnknownArgument(
+                    f"unknown parameter(s) {extra} for 'help'. Accepted: "
+                    "method",
+                    {"operation": "help", "code": "unknown_argument",
+                     "path": f"/params/{extra[0]}", "param": extra[0],
+                     "expected": ["method"],
+                     "observed": (params or {})[extra[0]],
+                     "accepted": ["method"]})
+            return self.help((params or {}).get("method", ""))
+        self._id += 1
+        request = {"id": self._id, "method": method, "params": {} if params is None else params}
+        previous = self.sock.gettimeout()
+        if timeout is not None:
+            self.sock.settimeout(timeout)
+        try:
+            self.file.write(json.dumps(request, allow_nan=False) + "\n")
+            self.file.flush()
+            while True:
+                line = self.file.readline()
+                if not line:
+                    raise ConnectionLost(f"{method}: the app disconnected "
+                                         "before answering")
+                msg = json.loads(line)
+                # A line the server could not parse is answered with a null
+                # id (it cannot know ours); with one request in flight it is
+                # this one's, and waiting for our id would wait forever.
+                if msg.get("id") is None and str(
+                        msg.get("error", "")).startswith("parse:"):
+                    raise refusal(msg["error"], msg.get("diagnostic"))
+                if msg.get("id") == self._id:
+                    if "nonfinite" in msg:
+                        said = (f"{method}: the answer held non-finite "
+                                f"numbers, sent as null, at "
+                                f"{', '.join(msg['nonfinite'][:5])}")
+                        if self.strict:
+                            raise NonFiniteError(said, msg["nonfinite"],
+                                                 msg.get("result"))
+                        import warnings
+                        warnings.warn(said, RuntimeWarning, stacklevel=3)
+                    if "error" in msg:
+                        raise refusal(msg["error"], msg.get("diagnostic"))
+                    if self.strict:
+                        _check_result(method, msg.get("result"))
+                    return msg.get("result")
+        finally:
+            if timeout is not None:
+                self.sock.settimeout(previous)
+
+    def close(self):
+        # makefile() dups the socket fd — close BOTH, or the server never
+        # sees EOF and keeps serving a ghost client.
+        #
+        # The server accepts up to EIGHT clients (RemoteServer.cpp's
+        # runaway-connection backstop) and drains them through ONE main-thread
+        # queue, so it is execution that is serialized, not connection. An
+        # earlier note here said it handled one client at a time; it does not,
+        # and several agents driving several instances is the point of
+        # docs/scripting/README.md#fan-out-several-agents-several-parts-one-project.
+        self.file.close()
+        self.sock.close()
+
+    @staticmethod
+    def instances():
+        """Running instances that announced themselves, newest first.
+
+        Each is {"pid", "port", "mode": "gui"|"headless"|"offscreen",
+        "started"}. The open project is not here — it changes while the
+        instance runs; `ping` reports it. The app
+        writes one file per open remote port under
+        $XDG_STATE_HOME/lobole/instances (see src/remote/InstanceRegistry.h);
+        a crash leaves the file behind, so the pid is the truth. Entries whose
+        process is gone are skipped, and removed when we own them.
+        """
+        import os
+        import pathlib
+        state = os.environ.get("XDG_STATE_HOME") or os.path.expanduser(
+            "~/.local/state")
+        directory = pathlib.Path(state) / "lobole" / "instances"
+        found = []
+        for path in sorted(directory.glob("*.json")) if (
+                directory.is_dir()) else []:
+            try:
+                info = json.loads(path.read_text())
+                pid = int(info.get("pid", 0))
+                os.kill(pid, 0)  # liveness, not a signal
+            except PermissionError:
+                pass  # someone else's process: alive, just not ours to poke
+            except (OSError, ValueError, json.JSONDecodeError):
+                try:
+                    path.unlink()  # stale or unreadable: it announces nothing
+                except OSError:
+                    pass
+                continue
+            found.append(info)
+        return sorted(found, key=lambda i: i.get("started", 0), reverse=True)
+
+    @staticmethod
+    def wait_for(port, timeout=30.0, strict=None):
+        """Connect, retrying while the app starts up."""
+        deadline = time.time() + timeout
+        last = None
+        while time.time() < deadline:
+            try:
+                return Client(port, strict=strict)
+            except OSError as e:
+                last = e
+                time.sleep(0.3)
+        raise TimeoutError(f"Loböle not reachable on port {port}: {last}")
+
+
+def method_help(call, method="", reference=None):
+    """help(method) for every client: what the method does, the parameter
+    keys it takes, and what it returns, from the app's own `describe` row.
+
+    Shared by this client and the MCP server (lobole.mcp), so the
+    two cannot drift into different answers. `call(name, **params)` reaches
+    the app. `reference` is a client's own prose for methods it wraps,
+    {method: {"doc": ..., ...}}: the MCP server passes the tool descriptions
+    it keeps out of the context, and they win over the app's one-liner;
+    the parameters, their types and the answer are always the app's row. An
+    unknown method is refused naming close matches — the app's for its own
+    methods, plus the close ones among `reference`.
+    """
+    reference = reference or {}
+    if not method:
+        rows = call("describe")["methods"]
+        return {"methods": sorted({r["name"] for r in rows} | set(reference)),
+                "hint": "help('add_mate') for one method; describe() for "
+                        "the app's type tables and enums"}
+    try:
+        row = call("describe", method=method)["methods"][0]
+    except Refused as e:
+        # A client's own name for something that is not an RPC (the MCP
+        # server's ui_action) has only its prose.
+        if method in reference:
+            return {"method": method, **reference[method]}
+        import difflib
+        near = [n for n in difflib.get_close_matches(method, sorted(reference),
+                                                     n=5)
+                if n not in str(e)]
+        raise type(e)(str(e) + (f"; also {', '.join(near)}" if near else ""),
+                      e.diagnostic) from None
+    out = {"method": method,
+           "doc": reference.get(method, {}).get("doc") or row.get("doc", "")}
+    if row.get("params_free_form"):
+        out["params_free_form"] = True
+    else:
+        out["params"] = row.get("params", [])
+    # A typed method (docs/scripting/rpc.md#typed-contracts): each key's
+    # type in words, from the same schema the server validates against.
+    schema = row.get("request_schema") or {}
+    if schema.get("properties"):
+        from lobole.contracts import describe
+        required = set(schema.get("required", []))
+        out["param_types"] = {
+            k: describe(s) + ("" if k in required else " (optional)")
+            for k, s in schema["properties"].items()}
+    for key in ("returns", "requires_part_doc"):
+        if key in row:
+            out[key] = row[key]
+    return out
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(__doc__)
+        return 2
+    port = int(sys.argv[1])
+    method = sys.argv[2]
+    params = json.loads(sys.argv[3]) if len(sys.argv) > 3 else {}
+    d = Client(port)
+    try:
+        print(json.dumps(d.request(method, params), indent=2))
+    finally:
+        d.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lobole/components.py

@@ -0,0 +1,156 @@
+# SPDX-FileCopyrightText: Elias Högbom Aronsson and Loböle contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Explicit ownership and staged updates for single-part Python generators.
+
+The application owns the manifest and undoable apply. This module plans builder
+work and assigns stable feature IDs while creating a disposable staging part.
+"""
+from collections import defaultdict
+from dataclasses import dataclass
+import uuid
+
+from lobole.sdk import Part, SdkError
+
+
+class _StagingPart(Part):
+    def __init__(self, app, slot, features):
+        super().__init__(app, slot)
+        self._keys = {}
+        ordinal = defaultdict(int)
+        for f in features:
+            stem = (f['type'], f.get('name', ''))
+            key = (*stem, ordinal[stem])
+            ordinal[stem] += 1
+            self._keys[key] = f['id']
+        self._seen = defaultdict(int)
+        self._next = max((f['id'] for f in features), default=0) + 1
+
+    def _stable_id(self, type_, name):
+        stem = (type_, name)
+        key = (*stem, self._seen[stem])
+        self._seen[stem] += 1
+        fid = self._keys.get(key)
+        if fid is None:
+            fid = self._next
+            self._next += 1
+        return fid
+
+    def _add(self, feature):
+        name = feature.get('name', '')
+        if feature['type'] in _PRIMITIVES:
+            # A primitive is stored as the features it expands to, a Sketch
+            # named "<name> sketch" and the solid named <name>
+            # (docs/modeling/README.md#primitives): pin both, as they are
+            # what the manifest holds.
+            solid = self._stable_id(_PRIMITIVES[feature['type']], name)
+            sketch = self._stable_id('Sketch', name + ' sketch')
+            return super()._add(dict(feature, ids=[solid, sketch]))
+        return super()._add(dict(feature,
+                                 id=self._stable_id(feature['type'], name)))
+
+
+# What a primitive's solid is stored as.
+_PRIMITIVES = {'Box': 'Extrude', 'Cylinder': 'Extrude', 'Sphere': 'Revolve'}
+
+
+class _BuilderApp:
+    def __init__(self, app, name, staging):
+        self._app, self._name, self._staging = app, name, staging
+
+    def part(self, name, create=True, reuse=False):
+        # The staging part IS the builder's own part, whichever of create /
+        # reuse the builder says (a builder shared with a full build may say
+        # reuse=True); only opening someone else's is a different request.
+        if not create:
+            raise SdkError('a component builder builds its part; it cannot '
+                           f'open an existing one ({name!r}, create=False)')
+        if name != self._name:
+            raise SdkError('a component builder must create exactly its declared part')
+        self._staging.activate()
+        return self._staging
+
+    def __getattr__(self, key):
+        return getattr(self._app, key)
+
+
+@dataclass
+class ComponentUpdate:
+    app: object
+    part: Part
+    staging: Part | None
+    fingerprint: str
+    before: dict
+    source: dict | None
+    report: dict
+
+    def apply(self):
+        if self.staging is None:
+            now = self.app.component_status(part_id=self.part.id)
+            if now['revision'] != self.before['revision'] or now['state'] != 'owned':
+                raise SdkError('component changed after the reuse plan')
+            return self.part
+        self.report = self.app.update_component(
+            part_id=self.part.id, source_part_id=self.staging.id,
+            fingerprint=self.fingerprint,
+            expected_revision=self.before['revision'],
+            source_revision=self.source['revision'], apply=True)
+        self.discard()
+        return self.part
+
+    def discard(self):
+        if self.staging is not None:
+            self.app.delete_part(part=self.staging.id)
+            self.staging = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.discard()
+
+
+def claim(part, *, namespace, key, fingerprint):
+    before = part.app.component_status(part_id=part.id)
+    return part.app.claim_component(part_id=part.id, namespace=namespace,
+                                    key=key, fingerprint=fingerprint,
+                                    expected_revision=before['revision'])
+
+
+def plan(app, *, namespace, key, fingerprint, builder):
+    """Build only when needed; caller reviews .report before explicit apply().
+
+    fingerprint must include all builder inputs and dependencies. The caller
+    declares it: undeclared ambient inputs must not be treated as cacheable.
+    Existing feature names/types plus ordinal within duplicates are stable keys;
+    rename/retirement conflicts are refused rather than guessed.
+    """
+    before = app.component_status(namespace=namespace, key=key)
+    if before['state'] != 'owned':
+        raise SdkError(f'component {namespace}/{key}: {before["state"]}; '
+                       'claim fresh output explicitly, resolve human edits before updating')
+    slot = next((p for p in app.parts() if p['id'] == before['part_id']), None)
+    if slot is None:
+        raise SdkError('component part disappeared')
+    part = Part(app, slot)
+    if before['generator']['fingerprint'] == fingerprint:
+        return ComponentUpdate(app, part, None, fingerprint, before, None,
+                               dict(action='reuse', part_id=part.id, applied=False))
+    features = part.state()['features']
+    slot = app.add_part(name='staging-' + uuid.uuid4().hex)
+    # add_part returns id plus index/name depending on the server version.
+    staging = _StagingPart(app, dict(id=slot['id'], name=slot.get('name', 'staging')), features)
+    staging.name = part.name
+    try:
+        made = builder(_BuilderApp(app, part.name, staging))
+        if not isinstance(made, Part) or made.id != staging.id:
+            raise SdkError('component builder did not return its staging part')
+        source = app.component_status(part_id=staging.id)
+        report = app.update_component(part_id=part.id, source_part_id=staging.id,
+                                      fingerprint=fingerprint,
+                                      expected_revision=before['revision'],
+                                      source_revision=source['revision'], apply=False)
+        return ComponentUpdate(app, part, staging, fingerprint, before, source, report)
+    except BaseException:
+        app.delete_part(part=staging.id)
+        raise

lobole/contracts.py

@@ -0,0 +1,181 @@
+# SPDX-FileCopyrightText: Elias Högbom Aronsson and Loböle contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Runtime validation of the documented contract JSON Schema subset.
+
+The client-side twin of ValidateInspectionValue (src/remote/InspectionContracts.h):
+the same walk in the same order, building the same diagnostic, so a preflight
+refusal and the server's name the same fault field for field
+(docs/scripting/rpc.md#structured-errors).
+"""
+import json
+import math
+
+from lobole.errors import Refused, refusal
+
+
+def _accepted(schema):
+    out = list(schema.get('enum', []))
+    for alt in schema.get('anyOf', []):
+        out += alt.get('enum', [])
+    return out
+
+
+def _num(v):
+    return str(int(v)) if float(v).is_integer() and abs(v) < 1e18 else repr(v)
+
+
+def describe(schema):
+    """A schema in words, as the server's DescribeSchema says it."""
+    if 'anyOf' in schema:
+        return ' or '.join(describe(a) for a in schema['anyOf'])
+    if 'enum' in schema:
+        vals = [v if isinstance(v, str) else json.dumps(v) for v in schema['enum']]
+        if len(vals) == 1:
+            return f'"{vals[0]}"'
+        more = f', +{len(vals) - 12} more' if len(vals) > 12 else ''
+        return 'one of: ' + ', '.join(vals[:12]) + more
+    if 'type' not in schema:
+        return 'any value'
+    t = schema['type']
+    s = dict(integer='an integer', number='a number', string='a string',
+             boolean='true or false', object='an object', null='null',
+             array='an array').get(t, t)
+    for key, op in (('minimum', '>='), ('exclusiveMinimum', '>'),
+                    ('maximum', '<='), ('exclusiveMaximum', '<')):
+        if key in schema:
+            s += f' {op} {_num(schema[key])}'
+    if 'minLength' in schema:
+        s += f' of at least {_num(schema["minLength"])} character(s)'
+    if t == 'object' and 'properties' in schema:
+        s += ' {' + ', '.join(schema['properties']) + '}'
+    if t == 'array':
+        lo, hi = 'minItems' in schema, 'maxItems' in schema
+        if lo and hi and schema['minItems'] == schema['maxItems']:
+            s += f' of {_num(schema["minItems"])}'
+        elif lo or hi:
+            s += (f' of {_num(schema["minItems"]) if lo else "0"}..'
+                  f'{_num(schema["maxItems"]) if hi else "any"}')
+        if 'items' in schema:
+            s += (' × ' if lo or hi else ' of ') + describe(schema['items'])
+        if schema.get('uniqueItems'):
+            s += ', no repeats'
+    return s
+
+
+def contract_refusal(operation, code, path, expected, observed, message=None,
+                     accepted=None):
+    """A client preflight refusal: the Refused subclass the server would
+    raise for `code`, with the diagnostic it would send (lobole.errors)."""
+    diagnostic = dict(operation=operation, code=code, path=path,
+                      expected=expected, observed=observed)
+    if path.startswith('/params/'):
+        diagnostic['param'] = path[len('/params/'):].split('/')[0]
+    if accepted:
+        diagnostic['accepted'] = accepted
+    return refusal(message or
+                   f'{operation}: {code} at {path}; expected {expected}',
+                   diagnostic)
+
+
+def _where(path):
+    return 'its params' if path == '/params' else f"'{path[len('/params/'):]}'"
+
+
+def _shown(value):
+    try:
+        s = json.dumps(value)
+    except (TypeError, ValueError):
+        s = repr(value)
+    return s if len(s) <= 80 else s[:77] + '...'
+
+
+def _is_number(value):
+    return (isinstance(value, (int, float)) and not isinstance(value, bool)
+            and (isinstance(value, int) or math.isfinite(value)))
+
+
+def accepts(schema, value):
+    try:
+        validate(schema, value, '', '/params')
+        return True
+    except Refused:
+        return False
+
+
+def validate(schema, value, operation, path='/params'):
+    def fail(expected=schema):
+        # A vocabulary's remedy for the usual mistake rides as `description`.
+        hint = expected.get('description') or next(
+            (a['description'] for a in expected.get('anyOf', [])
+             if a.get('description')), '')
+        raise contract_refusal(
+            operation, 'invalid_argument', path, expected, value,
+            f'{operation}: {_where(path)} must be {describe(expected)}; '
+            f'got {_shown(value)}' + (f'. {hint}' if hint else ''),
+            _accepted(expected))
+
+    if 'anyOf' in schema:
+        if any(accepts(alt, value) for alt in schema['anyOf']):
+            return
+        fail()
+    number = _is_number(value)
+    if 'type' in schema:
+        kind = schema['type']
+        valid = {'object': isinstance(value, dict),
+                 'array': isinstance(value, (list, tuple)),
+                 'string': isinstance(value, str),
+                 'boolean': isinstance(value, bool),
+                 'null': value is None,
+                 'number': number,
+                 'integer': number and (isinstance(value, int) or value.is_integer())}
+        if not valid[kind]:
+            fail()
+    if 'enum' in schema and value not in schema['enum']:
+        fail()
+    if number:
+        if 'minimum' in schema and value < schema['minimum']:
+            fail()
+        if 'maximum' in schema and value > schema['maximum']:
+            fail()
+        if 'exclusiveMinimum' in schema and value <= schema['exclusiveMinimum']:
+            fail()
+        if 'exclusiveMaximum' in schema and value >= schema['exclusiveMaximum']:
+            fail()
+    if isinstance(value, str) and len(value) < schema.get('minLength', 0):
+        fail()
+    if isinstance(value, dict) and 'properties' in schema:
+        props = schema['properties']
+        # Sorted: the server's objects iterate in key order. Unknown keys
+        # first, then missing ones, then each value -- the server's order.
+        for key in sorted(value):
+            # An open object (a result's `{..., *}`) carries keys it does
+            # not list. Every request schema closes its objects, so this is
+            # still the server's walk for everything the server validates.
+            if key not in props and \
+                    schema.get('additionalProperties', True) is False:
+                at = path + '/' + key
+                raise contract_refusal(
+                    operation, 'unknown_argument', at, props, value[key],
+                    f'{operation}: unknown parameter {_where(at)}; it takes: '
+                    + ', '.join(sorted(props)), sorted(props))
+        for key in schema.get('required', []):
+            if key not in value:
+                at = path + '/' + key
+                raise contract_refusal(
+                    operation, 'missing_argument', at, props[key], None,
+                    f'{operation}: missing required parameter {_where(at)} '
+                    f'({describe(props[key])})')
+        for key in sorted(value):
+            if key in props:
+                validate(props[key], value[key], operation, path + '/' + key)
+    if isinstance(value, (list, tuple)):
+        if len(value) < schema.get('minItems', 0):
+            fail()
+        if 'maxItems' in schema and len(value) > schema['maxItems']:
+            fail()
+        for i, item in enumerate(value):
+            if 'items' in schema:
+                validate(schema['items'], item, operation, path + '/' + str(i))
+            if schema.get('uniqueItems') and item in value[:i]:
+                fail()