zeon-project-scaffold 0.1.0__tar.gz

zeon_project_scaffold-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zeon Systems
+
+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.

zeon_project_scaffold-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: zeon-project-scaffold
+Version: 0.1.0
+Summary: Canonical Zeon project layout — shared by CLI `zeon init` and sync-service POST /projects.
+Author-email: Zeon Team <team@zeonsystems.app>
+License-Expression: MIT
+Project-URL: Homepage, https://zeonsystems.app
+Project-URL: Repository, https://github.com/ZeonSystems/everything-prototype-containers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Zeon Project Scaffold
+
+Canonical project layout and templates for Zeon projects.
+
+## Installation
+
+```bash
+pip install zeon-project-scaffold
+```
+
+## Usage
+
+This library is primarily used by the `zeon` CLI and the Zeon Sync service to ensure consistent project structures.

zeon_project_scaffold-0.1.0/README.md

@@ -0,0 +1,13 @@
+# Zeon Project Scaffold
+
+Canonical project layout and templates for Zeon projects.
+
+## Installation
+
+```bash
+pip install zeon-project-scaffold
+```
+
+## Usage
+
+This library is primarily used by the `zeon` CLI and the Zeon Sync service to ensure consistent project structures.

zeon_project_scaffold-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zeon-project-scaffold"
+version = "0.1.0"
+description = "Canonical Zeon project layout — shared by CLI `zeon init` and sync-service POST /projects."
+readme = "README.md"
+authors = [{ name = "Zeon Team", email = "team@zeonsystems.app" }]
+license = "MIT"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://zeonsystems.app"
+Repository = "https://github.com/ZeonSystems/everything-prototype-containers"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["project_scaffold*"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.package-data]
+project_scaffold = [
+    "templates/default/**/*",
+    "templates/default/.gitkeep",
+    "templates/default/**/.gitkeep",
+]

zeon_project_scaffold-0.1.0/setup.cfg

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

zeon_project_scaffold-0.1.0/src/project_scaffold/__init__.py

@@ -0,0 +1,40 @@
+"""Canonical Zeon project layout.
+
+A single source of truth for the file structure produced when a new project
+is created — used by both the CLI (`zeon init` writes to local disk) and
+the sync service (POST /projects seeds the initial commit's tree).
+
+Public API:
+  - ``iter_default_project_files()`` yields every file in the default scaffold
+    as ``(relative_path, bytes)`` pairs. The path uses forward slashes and is
+    project-relative.
+  - ``item_template(kind, name)`` yields the file map for a single new typed
+    item (``"skill"``, ``"workflow"``, ``"world"``, or ``"object"``). The
+    ``name`` must be a valid identifier — see :func:`validate_item_name`.
+  - ``ITEM_KINDS`` is the canonical set of typed item kinds.
+
+The templates themselves live as packaged resources under
+``project_scaffold/templates/default/``. Binary assets (``.npz`` and the
+like) are returned as raw bytes; text files use the on-disk encoding
+(UTF-8 in practice).
+"""
+
+from __future__ import annotations
+
+from ._scaffold import (
+    ITEM_KINDS,
+    ItemKind,
+    item_template,
+    iter_default_project_files,
+    primary_path_for,
+    validate_item_name,
+)
+
+__all__ = [
+    "ITEM_KINDS",
+    "ItemKind",
+    "item_template",
+    "iter_default_project_files",
+    "primary_path_for",
+    "validate_item_name",
+]

zeon_project_scaffold-0.1.0/src/project_scaffold/_scaffold.py

@@ -0,0 +1,339 @@
+"""Implementation of the public scaffold API.
+
+Two surfaces:
+
+1. Default project — :func:`iter_default_project_files` walks the packaged
+   ``templates/default/`` tree and yields every file. This is what backs
+   ``zeon init`` and the sync service's initial-commit seed.
+
+2. Typed items — :func:`item_template` returns the file map for a new
+   skill / workflow / world / object by rendering minimal in-code templates.
+   These are kept deliberately small so a fresh item is a clean canvas; the
+   bundled examples (``grab_object``, ``pick_place``, ``bowl_bottle``) are
+   the *reference* of what a richer item looks like. The object kind emits
+   only empty URDF + YAML placeholders — the generator that fills them
+   lives elsewhere and is wired in later.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+import json
+from pathlib import Path
+import re
+from typing import Iterator, Literal
+
+ItemKind = Literal["skill", "workflow", "world", "object"]
+ITEM_KINDS: tuple[ItemKind, ...] = ("skill", "workflow", "world", "object")
+
+# Identifier rules: lowercase letter or underscore start, then any of
+# ``[a-z0-9_-]``. 1–64 chars. Both dashes and underscores are accepted in the
+# folder/file name — but skill Python function names get dashes mapped to
+# underscores via :func:`_py_identifier` since dashes are illegal in Python
+# identifiers.
+_NAME_RE = re.compile(r"^[a-z_][a-z0-9_-]{0,63}$")
+
+
+def validate_item_name(name: str) -> str:
+    """Return ``name`` unchanged if valid, else raise ``ValueError``.
+
+    The rules: lowercase, starts with ``[a-z_]``, then any of ``[a-z0-9_-]``,
+    length 1–64. Spaces, uppercase letters, and other punctuation are
+    rejected — callers should slug-ify user input before calling.
+    """
+    if not isinstance(name, str) or not _NAME_RE.match(name):
+        raise ValueError(
+            f"invalid item name {name!r}: must match {_NAME_RE.pattern} "
+            "(lowercase, alphanumerics + underscore + hyphen, 1–64 chars)"
+        )
+    return name
+
+
+def _py_identifier(name: str) -> str:
+    """Convert a slug to a legal Python identifier.
+
+    Skills compile to a Python function whose name must match ``[a-zA-Z_]\\w*``,
+    so dashes in user-chosen slugs are rewritten to underscores for the
+    function definition while the folder and ``skill_id`` keep the original.
+    """
+    return name.replace("-", "_")
+
+
+# ---------------------------------------------------------------------------
+# Default project scaffold
+# ---------------------------------------------------------------------------
+
+
+def _template_root() -> Path:
+    """Return the on-disk path of the bundled default-template directory."""
+    pkg = resources.files("project_scaffold").joinpath("templates/default")
+    return Path(str(pkg))
+
+
+def iter_default_project_files() -> Iterator[tuple[str, bytes]]:
+    """Yield every file in the default project scaffold.
+
+    Each pair is ``(relative_path, content)`` where ``relative_path`` is
+    project-rooted with forward-slash separators and ``content`` is the raw
+    file bytes. The default scaffold currently includes:
+
+      - ``CLAUDE.md`` (project notes)
+      - ``skills/.gitkeep`` + the example skills (grab/move/drop object)
+      - ``workflows/.gitkeep`` + the example workflow (pick_place)
+      - ``worlds/.gitkeep`` + the example world (bowl_bottle)
+      - ``objects/.gitkeep`` + placeholder objects (bowl, bottle) — empty
+        URDF + YAML; the heavy mesh assets live in the global mesh-database
+        namespace served by the sync-service, not in the project tree.
+
+    Order within the iterator is unspecified; callers that need a stable
+    order should sort by path.
+    """
+    root = _template_root()
+    for path in _walk_files(root):
+        rel = path.relative_to(root).as_posix()
+        yield rel, path.read_bytes()
+
+
+def _walk_files(root: Path) -> Iterator[Path]:
+    """Depth-first walk yielding every file under ``root``."""
+    for entry in sorted(root.iterdir()):
+        if entry.is_dir():
+            yield from _walk_files(entry)
+        elif entry.is_file():
+            yield entry
+
+
+# ---------------------------------------------------------------------------
+# Typed item templates
+# ---------------------------------------------------------------------------
+
+
+def item_template(
+    kind: str, name: str, *, global_object: str | None = None
+) -> Iterator[tuple[str, bytes]]:
+    """Yield files for a newly-created typed item.
+
+    ``kind`` is one of :data:`ITEM_KINDS`. ``name`` must pass
+    :func:`validate_item_name`. Returned paths are project-relative.
+
+    ``global_object`` is only meaningful when ``kind == "object"``. When
+    provided, the rendered ``<name>.object_model.yaml`` carries a single
+    ``global_object: <global_object>`` line at the top — a hint to the
+    future populator that this project-bound object should draw its
+    geometry from the named mesh-database row. The URDF stays empty;
+    anchors/parts/articulations stay empty. The link is metadata only,
+    not content (D3 of the plan).
+
+    Passing ``global_object`` for a non-object kind is a programming
+    error — raises ``ValueError`` rather than silently dropping it.
+    """
+    validate_item_name(name)
+    if global_object is not None:
+        # Reuse the same name regex — global-object names must follow the
+        # same rules as project-bound names (they're mesh-database `name`
+        # PKs, also validated by `validate_item_name` on the server).
+        validate_item_name(global_object)
+    if kind == "skill":
+        if global_object is not None:
+            raise ValueError(
+                "global_object is only valid for kind='object'"
+            )
+        yield from _skill_files(name)
+    elif kind == "workflow":
+        if global_object is not None:
+            raise ValueError(
+                "global_object is only valid for kind='object'"
+            )
+        yield from _workflow_files(name)
+    elif kind == "world":
+        if global_object is not None:
+            raise ValueError(
+                "global_object is only valid for kind='object'"
+            )
+        yield from _world_files(name)
+    elif kind == "object":
+        yield from _object_files(name, global_object=global_object)
+    else:
+        raise ValueError(
+            f"unknown item kind: {kind!r}; expected one of {ITEM_KINDS}"
+        )
+
+
+def primary_path_for(kind: str, name: str) -> str:
+    """Return the file path a freshly-created item is expected to be opened at.
+
+    The CLI prints this as an "edit <path> to get started" hint after writing
+    the template files; the sync service surfaces it in the IDE's scaffold
+    response so Monaco lands on the right file. Kept here so every consumer
+    agrees on which file is the "primary" one for each kind:
+
+    - skill    → ``skills/{name}/robotic_code.py``        (the implementation file)
+    - workflow → ``workflows/{name}.json``                (the graph)
+    - world    → ``worlds/{name}/world_state.json``        (the scene state)
+    - object   → ``objects/{name}/{name}.object_model.yaml`` (anchors/parts/articulations)
+    """
+    validate_item_name(name)
+    if kind == "skill":
+        return f"skills/{name}/robotic_code.py"
+    if kind == "workflow":
+        return f"workflows/{name}.json"
+    if kind == "world":
+        return f"worlds/{name}/world_state.json"
+    if kind == "object":
+        return f"objects/{name}/{name}.object_model.yaml"
+    raise ValueError(
+        f"unknown item kind: {kind!r}; expected one of {ITEM_KINDS}"
+    )
+
+
+def _skill_files(name: str) -> Iterator[tuple[str, bytes]]:
+    base = f"skills/{name}"
+    py_name = _py_identifier(name)
+    yield f"{base}/metadata.yaml", _SKILL_METADATA.format(name=name).encode()
+    yield (
+        f"{base}/robotic_code.py",
+        _SKILL_ROBOTIC_CODE.format(name=name, py_name=py_name).encode(),
+    )
+    yield f"{base}/modules.py", _SKILL_MODULES.encode()
+
+
+def _workflow_files(name: str) -> Iterator[tuple[str, bytes]]:
+    body = {
+        "graph_id": name,
+        "name": name,
+        "description": "",
+        "nodes": [
+            {"node_id": "start", "node_type": "start", "metadata": {"label": "Start"}},
+            {"node_id": "end", "node_type": "end", "metadata": {"label": "End"}},
+        ],
+        "edges": [
+            {
+                "edge_id": "e0",
+                "from_node": "start",
+                "to_node": "end",
+                "condition": "unconditional",
+            }
+        ],
+    }
+    yield f"workflows/{name}.json", (json.dumps(body, indent=2) + "\n").encode()
+
+
+def _object_files(
+    name: str, *, global_object: str | None = None
+) -> Iterator[tuple[str, bytes]]:
+    base = f"objects/{name}"
+    yield f"{base}/{name}.urdf", _OBJECT_URDF.format(name=name).encode()
+    # When linked to a mesh-database row, prepend a `global_object: <name>`
+    # line to the YAML. This is metadata only — anchors/parts/articulations
+    # stay empty; the URDF stays the same empty placeholder.
+    if global_object is not None:
+        yaml_body = (
+            f"global_object: {global_object}\n"
+            + _OBJECT_YAML.format(name=name)
+        )
+    else:
+        yaml_body = _OBJECT_YAML.format(name=name)
+    yield f"{base}/{name}.object_model.yaml", yaml_body.encode()
+
+
+def _world_files(name: str) -> Iterator[tuple[str, bytes]]:
+    body = {
+        "version": "2.0",
+        "config": {
+            "tensor_device": "cuda",
+            "enable_blox": False,
+            "create_workspace_boundaries": False,
+        },
+        "objects": {},
+        "metadata": {
+            "name": name,
+            "description": "",
+            "source": "manual",
+        },
+    }
+    yield (
+        f"worlds/{name}/world_state.json",
+        (json.dumps(body, indent=2) + "\n").encode(),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Templates kept as constants so the package has no runtime branching when
+# rendering. Indentation matches what a user would expect to see on disk.
+# ---------------------------------------------------------------------------
+
+_SKILL_METADATA = """\
+# Skill: {name}
+skill_id: {name}
+version: "1.0.0"
+description: ""
+
+parameters: []
+
+preconditions: {{}}
+postconditions: {{}}
+"""
+
+_SKILL_ROBOTIC_CODE = '''\
+from .modules import *
+
+OBJECT_VARIABLES = {{}}
+
+
+def {py_name}():
+    """Skill implementation for {name}."""
+    # TODO: Implement skill logic here.
+    return {{"success": True}}
+'''
+
+_SKILL_MODULES = """\
+from execution.skill_editing.execution_functions import *
+"""
+
+# Object templates are deliberately minimal placeholders — just enough for
+# the zeon_robotics `load_object_model()` schema to validate without raising.
+# The future populator (lives in another part of the codebase) fills in real
+# kinematics, anchors, parts, and articulation presets. Until then, a
+# project-bound object renders as an invisible identity-frame at the root.
+#
+# Three things the schema requires we MUST emit:
+#   1. `urdf: <name>.urdf`        — yaml's link to its companion file
+#   2. `articulations.default`    — even with empty joints (matches a
+#                                   URDF that has zero actuated joints)
+#   3. `anchors.object`           — REQUIRED_ANCHORS = {"object"} on the
+#                                   schema; identity transform on the URDF's
+#                                   single `base` link
+#
+# Anything beyond this is content (anchors with real poses, parts that
+# reference geometry-bearing links, etc.) and is the populator's job.
+#
+# Verified live: load_object_model against this pair returns an ObjectModel
+# with parts=[], articulations=['default'], anchors=['object']. Verifying
+# regression test lives at
+# services/execution/src/execution/mesh_database/tests/test_scaffold_compat.py.
+_OBJECT_URDF = """\
+<?xml version='1.0' encoding='utf-8'?>
+<robot name="{name}">
+  <link name="base" />
+</robot>
+"""
+
+_OBJECT_YAML = """\
+# {name} object model — populated later
+urdf: {name}.urdf
+
+parts: {{}}
+
+articulations:
+  default:
+    description: "Empty default articulation"
+    joints: {{}}
+
+anchors:
+  object:
+    parent_link: base
+    description: "Object reference frame"
+    link_T_anchor:
+      xyz: [0.0, 0.0, 0.0]
+      wxyz: [1.0, 0.0, 0.0, 0.0]
+"""

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/CLAUDE.md

@@ -0,0 +1 @@
+# Project notes

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/objects/bottle/bottle.object_model.yaml

@@ -0,0 +1,17 @@
+# bottle object model — populated later
+urdf: bottle.urdf
+
+parts: {}
+
+articulations:
+  default:
+    description: "Empty default articulation"
+    joints: {}
+
+anchors:
+  object:
+    parent_link: base
+    description: "Object reference frame"
+    link_T_anchor:
+      xyz: [0.0, 0.0, 0.0]
+      wxyz: [1.0, 0.0, 0.0, 0.0]

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/objects/bottle/bottle.urdf

@@ -0,0 +1,4 @@
+<?xml version='1.0' encoding='utf-8'?>
+<robot name="bottle">
+  <link name="base" />
+</robot>

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/objects/bowl/bowl.object_model.yaml

@@ -0,0 +1,17 @@
+# bowl object model — populated later
+urdf: bowl.urdf
+
+parts: {}
+
+articulations:
+  default:
+    description: "Empty default articulation"
+    joints: {}
+
+anchors:
+  object:
+    parent_link: base
+    description: "Object reference frame"
+    link_T_anchor:
+      xyz: [0.0, 0.0, 0.0]
+      wxyz: [1.0, 0.0, 0.0, 0.0]

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/objects/bowl/bowl.urdf

@@ -0,0 +1,4 @@
+<?xml version='1.0' encoding='utf-8'?>
+<robot name="bowl">
+  <link name="base" />
+</robot>

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/skills/drop_object/metadata.yaml

@@ -0,0 +1,40 @@
+# Skill Metadata: Drop Object
+# Manipulation skill for releasing a grasped object at a destination
+
+skill_id: drop_object
+version: "1.0.0"
+description: "Release a grasped object at a specified destination and open gripper"
+
+parameters:
+  - name: destination
+    type: object
+    description: "Destination to drop the object to"
+    required: true
+
+  - name: object
+    type: object
+    description: "Object to be dropped"
+    required: true
+
+preconditions:
+  object_grasped: true
+  gripper_closed: true
+  destination_accessible: true
+
+postconditions:
+  object_released: true
+  gripper_open: true
+  object_at_destination: true
+
+safety_rules:
+  - "Minimum release height: 0.1m above destination"
+  - "Gripper must fully open before retreat"
+  - "Collision detection must be enabled"
+  - "Emergency stop button must be accessible"
+  - "Object detachment must be synchronized"
+
+tags:
+  - manipulation
+  - gripper
+  - pick-and-place
+  - release

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/skills/drop_object/modules.py

@@ -0,0 +1 @@
+from execution.skill_editing.execution_functions import *

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/skills/drop_object/robotic_code.py

@@ -0,0 +1,47 @@
+import time
+
+from execution.skill_editing.execution_functions import (
+    capture_image,
+    detach_object_from_arm,
+    move_arm,
+    set_gripper,
+)
+
+
+def drop_object():
+    destination = globals().get("OBJECT_VARIABLES", {}).get("destination", [0.5, -0.1, 0.15])
+    destination_position = [destination[0], destination[1], destination[2]]
+
+    object_id = globals().get("OBJECT_IDS", {}).get("object", "object")
+
+    move_arm(
+        arm="left_arm",
+        position=[destination_position[0], destination_position[1], destination_position[2] + 0.15],
+        orientation=[2.792021, -1.158447, -1.477334],
+        safe=False,
+        speed=100,
+    )
+
+    # Step 2: Detach object from arm and sync world
+    detach_object_from_arm(object_id)
+
+    # Step 3: Open gripper
+    set_gripper(arm="left_arm", width_m=0.08)
+    time.sleep(2)
+
+    # Step 4: Move back up
+    move_arm(
+        arm="left_arm",
+        position=[destination_position[0], destination_position[1], destination_position[2] + 0.2],
+        orientation=[1.085106, -1.490891, 0.235473],
+        safe=False,
+        speed=100,
+    )
+
+    # Step 5: Close gripper
+    set_gripper(arm="left_arm", width_m=0.0)
+
+    # Step 6: Capture image with right arm for testing
+    capture_image(arm="right_arm", capture_name="drop_object_final")
+
+    return {"success": True}

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/skills/grab_object/metadata.yaml

@@ -0,0 +1,34 @@
+# Skill Metadata: Grab Object (Pick & Place variant)
+# Pick and place manipulation skill for grasping objects with annotation-based positioning
+
+skill_id: grab_object
+version: "1.0.0"
+description: "Grasp an object using annotation-based positioning with the left arm gripper"
+
+parameters:
+  - name: object
+    type: object
+    description: "Object to be grabbed"
+    required: true
+
+preconditions:
+  gripper_open: true
+  object_visible: true
+  left_arm_available: true
+  workspace_clear: true
+  annotations_loaded: true
+
+postconditions:
+  object_grasped: true
+  gripper_closed: true
+  object_attached_to_arm: true
+# world_state_prime:
+#   object_positions:
+#     bowl: [0.2, -0.3, 0.0, 1.0, 0.0, 0.0, 0.0] # [x, y, z, qw, qx, qy, qz] format matching state_manager.py
+#   object_types:
+#     bowl: bowl
+#   robot_state:
+#     left_arm_tcp_pose: [0.250, -0.240, 0.209, -3.130, -0.029, -1.548]
+#     right_arm_tcp_pose: [-0.007, -0.387, 0.230, 3.007, -0.949, 0.121]
+#     left_arm_gripper_width: 0.08 # Gripper width in meters (open)
+#     right_arm_gripper_width: 0.0 # Gripper width in meters (closed)

zeon_project_scaffold-0.1.0/src/project_scaffold/templates/default/skills/grab_object/modules.py

@@ -0,0 +1 @@
+from execution.skill_editing.execution_functions import *