carterkit 0.1.0__tar.gz

carterkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carter Beaudoin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

carterkit-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: carterkit
+Version: 0.1.0
+Summary: Build and drive CAR-TER layouts from Python — the control docs are the library.
+Author: Carter Beaudoin
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Mariner10/carterkit
+Project-URL: Repository, https://github.com/Mariner10/carterkit
+Keywords: car-ter,carter,iot,dashboard,remote,meshsocket,layout
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Framework :: AsyncIO
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: meshsocket>=0.1
+Requires-Dist: cryptography>=42
+Dynamic: license-file
+
+# carterkit
+
+[![PyPI](https://img.shields.io/pypi/v/carterkit.svg)](https://pypi.org/project/carterkit/)
+[![Downloads](https://static.pepy.tech/badge/carterkit)](https://pepy.tech/project/carterkit)
+[![Python versions](https://img.shields.io/pypi/pyversions/carterkit.svg)](https://pypi.org/project/carterkit/)
+
+Build and drive [CAR-TER](https://carterbeaudoin.net/CAR-TER) layouts from Python.
+
+**The control docs are the library.** Every control's schema, fields, and examples
+are parsed at runtime from the ControlDocs markdown bundled inside the package — the
+exact same docs the CAR-TER app renders — so the catalog never drifts from the
+definitions.
+
+```bash
+pip install carterkit
+```
+
+## Explore the controls (zero config)
+
+```python
+import carterkit
+
+carterkit.controls()            # {type: schema} for every placeable control
+carterkit.doc("gauge")          # full parsed doc: fields, themeFields, examples
+print(carterkit.doc_markdown("gauge"))   # the rendered documentation prose
+carterkit.examples("button")    # documented example snippets
+```
+
+## Build a layout
+
+```python
+from carterkit import LayoutBuffer, validate_layout
+
+b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
+b.add_control({"type": "gauge", "id": "cpu", "label": "CPU", "min": 0, "max": 100},
+              default_span=[2, 2])
+b.add_control({"type": "button", "id": "refresh", "label": "Refresh"})
+
+layout = b.layout
+findings = validate_layout(layout)      # schema + grid lint against the bundled catalog
+print(carterkit.format_findings(findings))
+```
+
+`infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
+`codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
+`theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
+
+## Drive a device
+
+```python
+import asyncio
+from carterkit import CarterClient
+
+async def main():
+    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                     channel="home", role="device", name="my-hub")
+    c.on("toggle", lambda d: {"ok": True, **d})
+    await c.connect()
+    await c.broadcast("reading", {"temp_c": 21.4})
+    await asyncio.sleep(60)
+    await c.close()
+
+asyncio.run(main())
+```
+
+End-to-end encryption (ChaCha20-Poly1305 + per-session salt) is transparent when you
+pass an `e2ee_key`. Send a push to every device on a Connect+ account with
+`CarterClient.notify(...)` or the stdlib-only `carterkit.notify_http(...)`.
+
+## Built on
+
+[`meshsocket`](https://pypi.org/project/meshsocket/) — the WebSocket mesh transport.
+
+The ControlDocs are vendored from the CAR-TER app repo; refresh them with
+`scripts/sync-controldocs.sh`.

carterkit-0.1.0/README.md

@@ -0,0 +1,75 @@
+# carterkit
+
+[![PyPI](https://img.shields.io/pypi/v/carterkit.svg)](https://pypi.org/project/carterkit/)
+[![Downloads](https://static.pepy.tech/badge/carterkit)](https://pepy.tech/project/carterkit)
+[![Python versions](https://img.shields.io/pypi/pyversions/carterkit.svg)](https://pypi.org/project/carterkit/)
+
+Build and drive [CAR-TER](https://carterbeaudoin.net/CAR-TER) layouts from Python.
+
+**The control docs are the library.** Every control's schema, fields, and examples
+are parsed at runtime from the ControlDocs markdown bundled inside the package — the
+exact same docs the CAR-TER app renders — so the catalog never drifts from the
+definitions.
+
+```bash
+pip install carterkit
+```
+
+## Explore the controls (zero config)
+
+```python
+import carterkit
+
+carterkit.controls()            # {type: schema} for every placeable control
+carterkit.doc("gauge")          # full parsed doc: fields, themeFields, examples
+print(carterkit.doc_markdown("gauge"))   # the rendered documentation prose
+carterkit.examples("button")    # documented example snippets
+```
+
+## Build a layout
+
+```python
+from carterkit import LayoutBuffer, validate_layout
+
+b = LayoutBuffer.blank(name="Dashboard", columns=4, rows=4)
+b.add_control({"type": "gauge", "id": "cpu", "label": "CPU", "min": 0, "max": 100},
+              default_span=[2, 2])
+b.add_control({"type": "button", "id": "refresh", "label": "Refresh"})
+
+layout = b.layout
+findings = validate_layout(layout)      # schema + grid lint against the bundled catalog
+print(carterkit.format_findings(findings))
+```
+
+`infer.build_layout(payload)` generates a wired layout from a sample telemetry dict;
+`codegen.generate_service_stub(layout)` emits a runnable MeshSocket server skeleton;
+`theming.theme_for(...)` and `tune.tune_gauge(...)` round out the authoring tools.
+
+## Drive a device
+
+```python
+import asyncio
+from carterkit import CarterClient
+
+async def main():
+    c = CarterClient(gateway_url="ws://localhost:18080", token="<mesh token>",
+                     channel="home", role="device", name="my-hub")
+    c.on("toggle", lambda d: {"ok": True, **d})
+    await c.connect()
+    await c.broadcast("reading", {"temp_c": 21.4})
+    await asyncio.sleep(60)
+    await c.close()
+
+asyncio.run(main())
+```
+
+End-to-end encryption (ChaCha20-Poly1305 + per-session salt) is transparent when you
+pass an `e2ee_key`. Send a push to every device on a Connect+ account with
+`CarterClient.notify(...)` or the stdlib-only `carterkit.notify_http(...)`.
+
+## Built on
+
+[`meshsocket`](https://pypi.org/project/meshsocket/) — the WebSocket mesh transport.
+
+The ControlDocs are vendored from the CAR-TER app repo; refresh them with
+`scripts/sync-controldocs.sh`.

carterkit-0.1.0/carterkit/__init__.py

@@ -0,0 +1,69 @@
+"""carterkit — build and drive CAR-TER layouts from Python.
+
+The control vocabulary *is* the bundled documentation: every control's schema,
+fields, and examples are parsed at runtime from the ControlDocs markdown shipped
+inside this package (``carterkit/controldocs/``) — the same docs the CAR-TER app
+renders. So the docs never drift from the definitions; they are one and the same.
+
+Quick map:
+  - ``controls()`` / ``doc()`` / ``examples()`` — the docs-as-catalog surface
+  - ``LayoutBuffer`` — incrementally build a layout (auto-placement, dedupe)
+  - ``validate_layout()`` — schema + grid lint against the bundled catalog
+  - ``infer`` / ``codegen`` / ``theming`` / ``tune`` — generate layouts, servers, themes
+  - ``CarterClient`` / ``notify_http`` — connect over MeshSocket, push, send alerts
+"""
+from importlib.resources import files
+from pathlib import Path
+
+from . import catalog, grid, codegen, infer, theming, tune
+from .buffer import LayoutBuffer, BufferError
+from .validate import validate_layout as _validate_layout, format_findings
+from .client import CarterClient, notify_http, CarterNotifyError
+
+__version__ = "0.1.0"
+
+#: The layout/wire protocol version carterkit emits and understands. The JSON
+#: contract — not this Python API — is the real compatibility boundary across the
+#: app, the relay, and this library; unknown fields are tolerated on read.
+PROTOCOL_VERSION = 1
+
+
+def controldocs_dir() -> Path:
+    """Filesystem path to the bundled ControlDocs markdown (the source of truth)."""
+    return Path(files(__package__) / "controldocs")
+
+
+def controls(types=None, include_theme: bool = False) -> dict:
+    """Machine-readable schema for every placeable control, keyed by layout ``type``."""
+    return catalog.build_catalog(controldocs_dir(), types=types, include_theme=include_theme)
+
+
+def doc(control: str):
+    """Full parsed doc (fields, themeFields, body, examples) for a control type or node_id."""
+    return catalog.resolve_doc(controldocs_dir(), control)
+
+
+def doc_markdown(control: str):
+    """The control's human/AI documentation prose (the rendered markdown body)."""
+    d = doc(control)
+    return d["body"] if d else None
+
+
+def examples(control: str):
+    """Documented example snippets for a control: ``[{"name", "json"}, ...]``."""
+    return catalog.get_examples(controldocs_dir(), control)
+
+
+def validate_layout(layout: dict, catalog_: dict = None) -> list:
+    """Lint a layout (schema + grid). Defaults to the bundled control catalog."""
+    return _validate_layout(layout, catalog_ if catalog_ is not None else controls(include_theme=True))
+
+
+__all__ = [
+    "__version__", "PROTOCOL_VERSION",
+    "CarterClient", "notify_http", "CarterNotifyError",
+    "LayoutBuffer", "BufferError",
+    "controls", "doc", "doc_markdown", "examples", "validate_layout",
+    "format_findings", "controldocs_dir",
+    "catalog", "grid", "codegen", "infer", "theming", "tune",
+]

carterkit-0.1.0/carterkit/buffer.py

@@ -0,0 +1,230 @@
+"""Working-layout buffer + incremental patch ops.
+
+The headline authoring model: instead of re-emitting an 800-line layout on every
+change, the LLM issues surgical operations against a server-held draft. The buffer
+keeps the full document; each op mutates it and the result is pushed to the device as
+a full layout (which it already knows how to render). Pure (no I/O, no socket) so it
+is fully unit-testable; the async push/save live in server.py.
+
+Top-level children (controls + groups) of a tab are addressable by id. Editing inside
+a group is not yet supported (ids inside groups still count for uniqueness).
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Optional
+
+from . import grid as gridmod
+
+DEFAULT_COLUMNS = 4
+DEFAULT_ROWS = 8
+
+
+class BufferError(Exception):
+    """Raised on an invalid buffer operation (rendered to the user as a tool error)."""
+
+
+class LayoutBuffer:
+    def __init__(self, layout: dict):
+        self.layout = layout
+
+    # ─── construction ────────────────────────────────────────────────────────
+
+    @classmethod
+    def blank(cls, name: str = "Untitled", columns: int = DEFAULT_COLUMNS,
+              rows: int = DEFAULT_ROWS, accent: str = "#667eea",
+              tab_title: str = "Tab 1", tab_icon: str = "house.fill") -> "LayoutBuffer":
+        return cls({
+            "name": name,
+            "version": 1,
+            "accentColor": accent,
+            "tabs": [{
+                "title": tab_title,
+                "icon": tab_icon,
+                "grid": {"columns": columns, "rows": rows},
+                "children": [],
+            }],
+        })
+
+    @classmethod
+    def from_layout(cls, layout: dict) -> "LayoutBuffer":
+        if not isinstance(layout, dict) or "tabs" not in layout:
+            raise BufferError("source layout must be an object with a 'tabs' array")
+        return cls(copy.deepcopy(layout))
+
+    # ─── access ──────────────────────────────────────────────────────────────
+
+    @property
+    def tabs(self) -> list:
+        return self.layout.setdefault("tabs", [])
+
+    def _tab(self, i: int) -> dict:
+        tabs = self.tabs
+        if i < 0 or i >= len(tabs):
+            raise BufferError(f"tab index {i} out of range (have {len(tabs)} tab(s))")
+        return tabs[i]
+
+    @staticmethod
+    def _grid_dims(tab: dict) -> tuple[int, int]:
+        g = tab.get("grid") or {}
+        return int(g.get("columns", DEFAULT_COLUMNS)), int(g.get("rows", DEFAULT_ROWS))
+
+    def all_ids(self) -> set[str]:
+        ids: set[str] = set()
+
+        def walk(children):
+            for ch in children or []:
+                if isinstance(ch, dict):
+                    if "id" in ch:
+                        ids.add(ch["id"])
+                    if ch.get("type") == "group":
+                        walk(ch.get("children"))
+
+        for tab in self.tabs:
+            walk(tab.get("children"))
+        return ids
+
+    def unique_id(self, base: str) -> str:
+        base = base or "control"
+        ids = self.all_ids()
+        if base not in ids:
+            return base
+        i = 2
+        while f"{base}-{i}" in ids:
+            i += 1
+        return f"{base}-{i}"
+
+    def find(self, control_id: str) -> Optional[tuple[int, int, dict]]:
+        """Locate a top-level child by id -> (tab_index, child_index, child)."""
+        for ti, tab in enumerate(self.tabs):
+            for ci, ch in enumerate(tab.get("children", [])):
+                if isinstance(ch, dict) and ch.get("id") == control_id:
+                    return ti, ci, ch
+        return None
+
+    # ─── mutations ───────────────────────────────────────────────────────────
+
+    def add_control(self, control: dict, tab_index: int = 0,
+                    position: Optional[list[int]] = None,
+                    default_span: Optional[list[int]] = None) -> dict:
+        if not isinstance(control, dict) or "type" not in control:
+            raise BufferError("control must be an object with a 'type'")
+        control = copy.deepcopy(control)
+        control["id"] = self.unique_id(control.get("id") or control["type"])
+
+        tab = self._tab(tab_index)
+        children = tab.setdefault("children", [])
+        cols, rows = self._grid_dims(tab)
+
+        if control.get("span") is None and default_span and default_span != [1, 1]:
+            control["span"] = default_span
+        span = control.get("span") or [1, 1]
+
+        if position is None:
+            slot = gridmod.find_slot(children, cols, rows, span)
+            if slot is None:
+                raise BufferError(
+                    f"no free {span} slot in tab {tab_index} ({rows}x{cols} grid). "
+                    f"Grow the grid (add_tab/edit grid) or pass an explicit position.")
+            position = slot
+        control["position"] = position
+        children.append(control)
+        return control
+
+    def update_control(self, control_id: str, patch: dict) -> dict:
+        found = self.find(control_id)
+        if not found:
+            raise BufferError(f"no control '{control_id}' in the buffer")
+        ch = found[2]
+        for k, v in patch.items():
+            if v is None:
+                ch.pop(k, None)
+            else:
+                ch[k] = v
+        return ch
+
+    def remove_control(self, control_id: str) -> dict:
+        found = self.find(control_id)
+        if not found:
+            raise BufferError(f"no control '{control_id}' in the buffer")
+        ti, ci, _ = found
+        return self.tabs[ti]["children"].pop(ci)
+
+    def move_control(self, control_id: str, position: Optional[list[int]] = None,
+                     span: Optional[list[int]] = None,
+                     tab_index: Optional[int] = None) -> dict:
+        found = self.find(control_id)
+        if not found:
+            raise BufferError(f"no control '{control_id}' in the buffer")
+        ti, ci, ch = found
+        if tab_index is not None and tab_index != ti:
+            ch = self.tabs[ti]["children"].pop(ci)
+            self._tab(tab_index).setdefault("children", []).append(ch)
+        if position is not None:
+            ch["position"] = position
+        if span is not None:
+            ch["span"] = span
+        return ch
+
+    def add_tab(self, title: str, icon: str = "square.grid.2x2",
+                columns: int = DEFAULT_COLUMNS, rows: int = DEFAULT_ROWS) -> int:
+        self.tabs.append({
+            "title": title, "icon": icon,
+            "grid": {"columns": columns, "rows": rows}, "children": [],
+        })
+        return len(self.tabs) - 1
+
+    def add_group(self, group: dict, tab_index: int = 0,
+                  position: Optional[list[int]] = None) -> dict:
+        group = copy.deepcopy(group)
+        group["type"] = "group"
+        group["id"] = self.unique_id(group.get("id") or "group")
+        tab = self._tab(tab_index)
+        children = tab.setdefault("children", [])
+        cols, rows = self._grid_dims(tab)
+        span = group.get("span") or [1, 1]
+        if position is None:
+            slot = gridmod.find_slot(children, cols, rows, span)
+            if slot is None:
+                raise BufferError(f"no free {span} slot in tab {tab_index} for the group")
+            position = slot
+        group["position"] = position
+        children.append(group)
+        return group
+
+    # ─── views ───────────────────────────────────────────────────────────────
+
+    def issues(self) -> list[dict]:
+        """Placement issues across all tabs, each tagged with its tab index."""
+        out: list[dict] = []
+        for ti, tab in enumerate(self.tabs):
+            cols, rows = self._grid_dims(tab)
+            for issue in gridmod.validate_placement(tab.get("children", []), cols, rows):
+                out.append({"tab": ti, **issue})
+        return out
+
+    def summary(self, show_grids: bool = True) -> str:
+        name = self.layout.get("name", "Untitled")
+        accent = self.layout.get("accentColor")
+        head = f"**{name}**" + (f" · accent {accent}" if accent else "")
+        lines = [head]
+        for ti, tab in enumerate(self.tabs):
+            cols, rows = self._grid_dims(tab)
+            children = tab.get("children", [])
+            lines.append(f"\nTab {ti}: {tab.get('title','?')} ({tab.get('icon','')}) "
+                         f"— {rows}x{cols}, {len(children)} item(s)")
+            for ch in children:
+                pos = ch.get("position")
+                span = ch.get("span")
+                extra = f" span {span}" if span and span != [1, 1] else ""
+                lines.append(f"  - {ch.get('id','?')} ({ch.get('type','?')}) @ {pos}{extra}")
+            if show_grids and children:
+                lines.append(gridmod.render_grid(children, cols, rows))
+        problems = self.issues()
+        if problems:
+            lines.append("\n⚠ placement issues:")
+            for p in problems:
+                ids = p.get("ids") or [p.get("id")]
+                lines.append(f"  - [tab {p['tab']}] {p['kind']}: {', '.join(ids)} — {p['detail']}")
+        return "\n".join(lines)