novaflow-types 0.1.0__tar.gz

novaflow_types-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+**/kubeconfig*
+**/.env
+**/.venv
+**/__pycache__/
+**/.ruff_cache/
+.DS_Store
+logs/
+
+__pycache__
+py_test
+.pytest_cache/
+
+node_modules
+profiling-data/
+
+.opencode
+.claude/settings.local.json
+.claude/worktrees/
+.claude/scheduled_tasks.lock
+
+# Debug / ad-hoc data dumps
+globals_dump*.json
+wandelbox-4qq9rq.yaml
+
+# Working-scratch investigations — fine to write into docs/investigations/
+# locally, but the tree must not be committed. Load-bearing facts go inline
+# at the citation site (ADR / spec / code docstring); see AGENTS.md
+# § Response Length.
+docs/investigations/
+
+# Playwright MCP session scratch (console logs + page snapshots)
+.playwright-mcp/

novaflow_types-0.1.0/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.formatOnPaste": true,
+    "editor.formatOnSave": true
+}

novaflow_types-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: novaflow-types
+Version: 0.1.0
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: wandelbots-api-client==26.3.0
+Description-Content-Type: text/markdown
+
+# novaflow-types
+
+Pydantic models for the NovaFlow behavior-tree platform — the shared
+vocabulary used across the stack: tree nodes (`BehaviorTree`, `ActionNode`,
+sequences, decorators, …), robotics data types (`Pose`, `Joints`,
+`MotionTarget`, …), action I/O schemas, and the structural type identity
+(content-hashed `type_id`) that decides node compatibility.
+
+```bash
+pip install novaflow-types
+```
+
+Typical uses:
+
+- Build NovaFlow behavior trees programmatically in Python and serialize
+  them to the JSON the Forest API imports (`BehaviorTree.model_dump_json()`).
+- Author custom action services — this package comes in transitively with
+  the `wandelbots-novaflow` runtime SDK.
+
+The package also ships the committed Nova API spec it validates types
+against; the pinned `wandelbots-api-client` version is the single source
+of truth for Nova type identity across the stack.
+
+## Versioning
+
+Pre-1.0: this package tracks internal NovaFlow development. Breaking
+changes can happen on any minor release — **pin your version**. Published
+versions are immutable; nothing breaks under you until you upgrade.

novaflow_types-0.1.0/README.md

@@ -0,0 +1,28 @@
+# novaflow-types
+
+Pydantic models for the NovaFlow behavior-tree platform — the shared
+vocabulary used across the stack: tree nodes (`BehaviorTree`, `ActionNode`,
+sequences, decorators, …), robotics data types (`Pose`, `Joints`,
+`MotionTarget`, …), action I/O schemas, and the structural type identity
+(content-hashed `type_id`) that decides node compatibility.
+
+```bash
+pip install novaflow-types
+```
+
+Typical uses:
+
+- Build NovaFlow behavior trees programmatically in Python and serialize
+  them to the JSON the Forest API imports (`BehaviorTree.model_dump_json()`).
+- Author custom action services — this package comes in transitively with
+  the `wandelbots-novaflow` runtime SDK.
+
+The package also ships the committed Nova API spec it validates types
+against; the pinned `wandelbots-api-client` version is the single source
+of truth for Nova type identity across the stack.
+
+## Versioning
+
+Pre-1.0: this package tracks internal NovaFlow development. Breaking
+changes can happen on any minor release — **pin your version**. Published
+versions are immutable; nothing breaks under you until you upgrade.

novaflow_types-0.1.0/generate_camera_registry_schema.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Generate JSON Schema for the ``registry_cameras`` KV wire payload.
+
+Read-side half of the wire-contract symmetry (#251) for camera feeds: connectors
+publish ``CameraRegistryEntry`` payloads into the ``registry_cameras`` KV bucket;
+this emits that Pydantic model as JSON Schema so canopy validates each entry on
+READ via ajv. Both ends share ONE contract, generated from the Pydantic source,
+so the schema can't drift from what producers write.
+
+Usage: uv run generate_camera_registry_schema.py ../json/camera_registry.schema.json
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from novaflow.types.comm.camera_registry import CameraRegistryEntry
+
+
+def generate() -> dict:
+    """Return the serialization-mode JSON Schema for a registry_cameras entry."""
+    # mode="serialization" → the shape actually written to KV (model_dump),
+    # which is what canopy parses and must validate.
+    schema = CameraRegistryEntry.model_json_schema(mode="serialization")
+    schema["$comment"] = (
+        "AUTO-GENERATED from the CameraRegistryEntry Pydantic model "
+        "(novaflow-schemas) — do NOT hand-edit; run scripts/generate-types.sh. "
+        "Read-side validation contract for canopy (#251)."
+    )
+    return schema
+
+
+def main() -> None:
+    schema = generate()
+    if len(sys.argv) > 1:
+        output_path = Path(sys.argv[1])
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w") as f:
+            json.dump(schema, f, indent=2)
+        print(f"Camera-registry schema written to {output_path}", file=sys.stderr)
+    else:
+        print(json.dumps(schema, indent=2))
+
+
+if __name__ == "__main__":
+    main()

novaflow_types-0.1.0/generate_comm_kv_schema.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Generate JSON Schema for the per-run KV *state* payloads canopy reads.
+
+This is the read-side half of the wire-contract symmetry (#251): the action /
+control-plane already validate these payloads against their Pydantic models on
+WRITE; this emits the same models as JSON Schema so canopy can validate them on
+READ via ajv.  Both ends then share ONE contract — generated from the Pydantic
+source, so the schema can't drift from what the writers produce.
+
+Output is a map keyed by the field name canopy sees after stripping the
+``{run_id}.`` prefix → that field's JSON Schema:
+
+    {"cursor": {...}, "scrub_state": {...}, "terminal": {...}, "speed": {...}}
+
+Only the *state* signals canopy reads are included.  ``progress`` is
+intentionally omitted: its KV body is ``{item_index, state}`` and canopy
+derives the index from the *key* (``progress.{N}``), so there is no dedicated
+KV model to validate against (``ProgressEvent`` is the richer *subject* model).
+
+Usage: uv run generate_comm_kv_schema.py ../json/comm_kv.schema.json
+"""
+
+import json
+import sys
+from pathlib import Path
+
+from novaflow.types.comm.programming import (
+    CursorEvent,
+    ProgrammingTerminalBody,
+    ScrubStateEvent,
+    SpeedRequest,
+)
+
+# Field name (as canopy sees it, post ``{run_id}.`` strip) → Pydantic model.
+# Keep in lockstep with the writers (cursor_cb / state_cb / _publish_session_
+# terminal / the speed KV write) and the read dispatch in
+# canopy/src/hooks/handleProgrammingSessionKvEntry.ts.
+_KV_FIELD_MODELS = {
+    "cursor": CursorEvent,
+    "scrub_state": ScrubStateEvent,
+    "terminal": ProgrammingTerminalBody,
+    "speed": SpeedRequest,
+}
+
+
+def generate() -> dict:
+    """Return ``{field: json_schema}`` for every validated KV state signal."""
+    out: dict = {
+        "//": (
+            "AUTO-GENERATED from Pydantic models (novaflow-schemas) — do NOT "
+            "hand-edit; run scripts/generate-types.sh.  Read-side validation "
+            "contract for canopy (#251); serialization mode (matches the bytes "
+            "on the wire)."
+        )
+    }
+    for field, model in _KV_FIELD_MODELS.items():
+        # mode="serialization" → the shape that's actually written to KV
+        # (``model_dump``), which is what canopy parses and must validate.
+        out[field] = model.model_json_schema(mode="serialization")
+    return out
+
+
+def main() -> None:
+    schema = generate()
+    if len(sys.argv) > 1:
+        output_path = Path(sys.argv[1])
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(output_path, "w") as f:
+            json.dump(schema, f, indent=2)
+        print(f"Comm-KV schema written to {output_path}", file=sys.stderr)
+    else:
+        print(json.dumps(schema, indent=2))
+
+
+if __name__ == "__main__":
+    main()

novaflow_types-0.1.0/generate_comm_registries.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Generate the TypeScript twins of the comm subject + KV-key registries from
+their Python source (#251).
+
+``subjects.py`` and ``kv_keys.py`` are the single source of truth for the
+per-run NATS subject + KV-key strings.  Their TS twins were previously
+HAND-mirrored and kept in sync only by twin tests — their own docstrings
+promised a codegen pipeline that was never built.  This is that pipeline: it
+reflects each Python helper and emits the equivalent TS, so the twins can't
+drift (the twin tests become a *verification* of the generated output, not a
+manual-sync chore).
+
+Emits two files:
+  - commSubjects.ts       ← novaflow.types.comm.subjects
+  - programmingKvKeys.ts  ← novaflow.types.comm.kv_keys
+
+Rules (kept deliberately simple, matching the existing twins):
+  * module-level UPPER_CASE ``str`` constant      → ``export const NAME = "...";``
+  * module-level function defined here, returns str → reflected TS function
+    (called with ``__param__`` sentinels; result becomes a template literal;
+    param types mapped str→string, int→number; names snake→camel).
+  * everything else (purge-suffix tuples, imports) is Python-only → skipped.
+
+Usage: uv run generate_comm_registries.py <out_dir>
+"""
+
+import inspect
+import sys
+from pathlib import Path
+from types import ModuleType
+
+from novaflow.types.comm import kv_keys as kv_keys_mod
+from novaflow.types.comm import subjects as subjects_mod
+
+# Keys cover both resolved types and their string names — modules using
+# ``from __future__ import annotations`` (PEP 563) expose annotations as
+# strings even with ``eval_str=True`` unavailable.
+_PY_TO_TS_TYPE = {str: "string", int: "number", "str": "string", "int": "number"}
+
+
+def _camel(snake: str) -> str:
+    head, *rest = snake.split("_")
+    return head + "".join(w[:1].upper() + w[1:] for w in rest)
+
+
+# Prettier's default print width.  We emit already-wrapped output so the
+# committed twins are byte-identical to the generator with NO external
+# formatter in the loop (deterministic across toolchains; #251 review).
+_PRINT_WIDTH = 80
+
+
+def _emit_function(name: str, fn) -> str | None:
+    try:
+        sig = inspect.signature(fn, eval_str=True)
+    except Exception:
+        sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+    sentinels = {p.name: f"__{p.name}__" for p in params}
+    try:
+        template = fn(*sentinels.values())
+    except Exception:
+        return None
+    if not isinstance(template, str):
+        return None
+    for p in params:
+        template = template.replace(sentinels[p.name], "${" + _camel(p.name) + "}")
+    ts_param_list = [
+        f"{_camel(p.name)}: {_PY_TO_TS_TYPE.get(p.annotation, 'string')}"
+        for p in params
+    ]
+    decl = f"export function {_camel(name)}({', '.join(ts_param_list)}): string {{"
+    if len(decl) <= _PRINT_WIDTH:
+        sig_block = decl
+    else:
+        # Mirror prettier: one param per line, indented, trailing comma.
+        wrapped = "".join(f"  {p},\n" for p in ts_param_list)
+        sig_block = (
+            f"export function {_camel(name)}(\n{wrapped}): string {{"
+        )
+    return f"{sig_block}\n  return `{template}`;\n}}"
+
+
+def _header(py_module: str) -> str:
+    # No trailing newline: blocks are joined with a blank line, so a
+    # trailing "\n" here would produce a double blank after the header.
+    return (
+        "// AUTO-GENERATED — DO NOT EDIT.\n"
+        f"// Source: {py_module}\n"
+        "// Regenerate via: bash scripts/generate-types.sh\n"
+        "// (TS twin of the Python subject/KV-key registry — #251 codegen.)"
+    )
+
+
+def emit_module(mod: ModuleType) -> str:
+    blocks: list[str] = [_header(mod.__name__)]
+    for name, obj in vars(mod).items():
+        if name.startswith("_"):
+            continue
+        if isinstance(obj, str) and name.isupper():
+            blocks.append(f'export const {name} = "{obj}";')
+        elif inspect.isfunction(obj) and getattr(obj, "__module__", None) == mod.__name__:
+            ts = _emit_function(name, obj)
+            if ts is None:
+                # A public, module-defined helper we cannot reflect. Failing
+                # loud beats silently dropping a wire helper from the TS twin
+                # (which would drift unnoticed until a downstream consumer
+                # broke).  Make it Python-only with a leading underscore, or
+                # teach _emit_function to handle it.
+                raise RuntimeError(
+                    f"cannot reflect public helper {name!r} in {mod.__name__} "
+                    "for TS codegen (returned non-str or raised). Prefix it "
+                    "with '_' if it is Python-only, or extend _emit_function."
+                )
+            blocks.append(ts)
+    return "\n\n".join(blocks) + "\n"
+
+
+_OUTPUTS = {
+    "commSubjects.ts": subjects_mod,
+    "programmingKvKeys.ts": kv_keys_mod,
+}
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("usage: generate_comm_registries.py <out_dir>", file=sys.stderr)
+        raise SystemExit(2)
+    out_dir = Path(sys.argv[1])
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for filename, mod in _OUTPUTS.items():
+        # Pin UTF-8: the header carries a non-ASCII em-dash, and the platform
+        # default encoding (cp1252 on Windows) would mangle it → drift between
+        # a Windows dev and Linux CI.  See AGENTS.md cross-platform rules.
+        (out_dir / filename).write_text(emit_module(mod), encoding="utf-8")
+        print(f"Wrote {out_dir / filename}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

novaflow_types-0.1.0/generate_global_type_catalog.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Generate canopy's registry-derived catalog of selectable global types (#420).
+
+canopy's globals "create new global" form used to hardcode a 7-item type list
+(``String``/``Float``/``Int``/``Bool``/``Pose``/``Joints``/``Any``) with
+hand-rolled defaults and schemas. That list (a) used **non-canonical** primitive
+names (``"String"`` resolves to NO structural id — ``"str"`` is the registry's
+name) so a global created with it failed closed when wired into a flow, and
+(b) couldn't offer the ~30 *other* registered Nova types (``Vector3d``,
+``LimitsOverride``, ``BlendingAuto/Position``, ``CubicSplineParameter``,
+``MotionRoutine*``, ``ApproachJoints*``, the IO specs, …).
+
+This generator emits one entry per registered type, keyed by its **canonical**
+registry name, with:
+  * ``jsonSchema``   — ``TypeAdapter(py_type).json_schema()`` (the type's schema,
+                       which ActionInputField dispatches its editor from), and
+  * ``defaultValue`` — a best-effort, total (never-raises) schema default the
+                       value editor seeds with and then refines.
+
+So the editor's dropdown == the registered (Nova) types with canonical names,
+and a global created from it stores a type expression that *resolves* (its
+structural id is non-null), instead of failing closed.
+
+Emits one file: ``globalTypeCatalog.ts``.
+
+Usage: uv run generate_global_type_catalog.py <out_dir>
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from pydantic import TypeAdapter
+
+from novaflow.types.data.registry import NOVAFLOW_TYPE_REGISTRY
+
+_HEADER = (
+    "// AUTO-GENERATED — DO NOT EDIT.\n"
+    "// Source: novaflow.types.data.registry.NOVAFLOW_TYPE_REGISTRY\n"
+    "// Regenerate via: bash scripts/generate-types.sh\n"
+    "// (canopy's registry-derived catalog of selectable global types — #420.\n"
+    "//  Drives the globals editor's type dropdown, per-type JSON schema, and\n"
+    "//  default value from the SAME registry control-plane uses, with the\n"
+    "//  canonical type names — so a created global stores a resolvable type.)"
+)
+
+_INTERFACE = (
+    "export interface GlobalTypeCatalogEntry {\n"
+    "  /** Canonical registry type name (e.g. \"str\", \"Pose\", \"Vector3d\"). */\n"
+    "  name: string;\n"
+    "  /** The type's JSON schema (ActionInputField dispatches its editor off this). */\n"
+    "  jsonSchema: Record<string, unknown>;\n"
+    "  /** Best-effort seed value for a fresh scalar global of this type. */\n"
+    "  defaultValue: unknown;\n"
+    "}"
+)
+
+_HELPER = """\
+const _BY_NAME: Record<string, GlobalTypeCatalogEntry> = Object.fromEntries(
+  GLOBAL_TYPE_CATALOG.map((e) => [e.name, e]),
+);
+
+/**
+ * Look up a catalog entry by its canonical registry name. Returns undefined
+ * for an unregistered name (the caller falls back to a null default / a
+ * pass-through schema).
+ */
+export function globalTypeEntry(
+  name: string,
+): GlobalTypeCatalogEntry | undefined {
+  return _BY_NAME[name];
+}"""
+
+
+def _resolve_ref(schema: dict[str, Any], defs: dict[str, Any]) -> dict[str, Any]:
+    """Resolve a single local ``$ref`` (``#/$defs/Name``) against ``defs``.
+
+    Only the local ``#/$defs/`` shape Pydantic emits is handled; anything else
+    (or a missing target) is returned unchanged so the caller degrades to the
+    empty/unresolved → ``null`` branch rather than raising."""
+    ref = schema.get("$ref")
+    if not isinstance(ref, str) or not ref.startswith("#/$defs/"):
+        return schema
+    return defs.get(ref[len("#/$defs/") :], {})
+
+
+def _default_for(schema: Any, defs: dict[str, Any]) -> Any:
+    """Total (never raises) recursive JSON-Schema default.
+
+    * ``"string"`` → ``""``; ``"number"``/``"integer"`` → ``0``;
+      ``"boolean"`` → ``False``; ``"array"`` → ``[]``.
+    * ``"object"`` → ``{prop: default(propSchema)}`` over ``properties`` (local
+      ``$ref`` resolved against ``$defs``).
+    * ``anyOf``/``oneOf`` → default of the first member.
+    * ``null`` / ``Any`` (``True`` / empty ``{}``) / unresolved → ``None``.
+
+    Best-effort: the value editor refines it. Kept total so a future type with
+    an exotic schema can never break codegen."""
+    if not isinstance(schema, dict) or not schema:
+        # ``None`` schema, ``True`` (Any), or empty ``{}`` → no default.
+        return None
+
+    schema = _resolve_ref(schema, defs)
+    if not isinstance(schema, dict) or not schema:
+        return None
+
+    for key in ("anyOf", "oneOf"):
+        members = schema.get(key)
+        if isinstance(members, list) and members:
+            return _default_for(members[0], defs)
+
+    t = schema.get("type")
+    if t == "string":
+        return ""
+    if t in ("number", "integer"):
+        return 0
+    if t == "boolean":
+        return False
+    if t == "array":
+        # Respect a fixed/min length so a constrained array (e.g. ``Vector3d`` /
+        # ``RotationVector`` — minItems=maxItems=3) gets a structurally VALID
+        # default: a min-length array of the item default (``[0, 0, 0]``), not
+        # an empty ``[]`` that violates the schema and breaks fixed-length
+        # editors (a 3-axis Pose/Vector editor that indexes [0..2]). A
+        # variable-length array (no ``minItems`` — e.g. ``Joints`` / ``list[T]``)
+        # legitimately stays ``[]``.
+        min_items = schema.get("minItems") or 0
+        items_schema = schema.get("items")
+        if min_items and isinstance(items_schema, dict):
+            return [_default_for(items_schema, defs) for _ in range(min_items)]
+        return []
+    if t == "null":
+        return None
+    if t == "object":
+        props = schema.get("properties")
+        if isinstance(props, dict):
+            return {k: _default_for(v, defs) for k, v in props.items()}
+        return {}
+    # No (or unrecognised) ``type`` and no union → unresolved.
+    return None
+
+
+def _entry(name: str, py_type: Any) -> dict[str, Any]:
+    """The catalog entry (name + json schema + default) for one registry type."""
+    schema = TypeAdapter(py_type).json_schema()
+    defs = schema.get("$defs", {}) if isinstance(schema, dict) else {}
+    return {
+        "name": name,
+        "jsonSchema": schema,
+        "defaultValue": _default_for(schema, defs),
+    }
+
+
+def emit() -> str:
+    """The full globalTypeCatalog.ts content (deterministic, pre-formatted)."""
+    rows: list[str] = []
+    for name in sorted(NOVAFLOW_TYPE_REGISTRY):
+        entry = _entry(name, NOVAFLOW_TYPE_REGISTRY[name])
+        # json.dumps with sorted keys for a stable, deterministic serialization
+        # that doesn't depend on dict insertion order across toolchains.
+        rows.append("  " + json.dumps(entry, sort_keys=True) + ",")
+    catalog = "\n".join(rows)
+    const = (
+        "export const GLOBAL_TYPE_CATALOG: GlobalTypeCatalogEntry[] = [\n"
+        f"{catalog}\n"
+        "];"
+    )
+    return f"{_HEADER}\n\n{_INTERFACE}\n\n{const}\n\n{_HELPER}\n"
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("usage: generate_global_type_catalog.py <out_dir>", file=sys.stderr)
+        raise SystemExit(2)
+    out = Path(sys.argv[1]) / "globalTypeCatalog.ts"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    # Pin UTF-8: the header carries a non-ASCII em-dash; cp1252 (Windows
+    # default) would mangle it → drift between a Windows dev and Linux CI.
+    out.write_text(emit(), encoding="utf-8")
+    print(f"Wrote {out}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()