@datalayer/agent-runtimes 1.0.2 → 1.0.4

package/scripts/codegen/generate_tools.py

@@ -0,0 +1,346 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""
+Generate Python and TypeScript code from YAML tool specifications.
+"""
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from versioning import ensure_spec_version, version_suffix
+
+
+def _fmt_list(items: list[str]) -> str:
+    if not items:
+        return "[]"
+    return "[" + ", ".join(f'"{item}"' for item in items) + "]"
+
+
+def _require_runtime(spec: dict[str, Any]) -> dict[str, str]:
+    runtime = spec.get("runtime")
+    if not isinstance(runtime, dict):
+        raise ValueError(
+            f"Tool '{spec.get('id', '<unknown>')}' is missing required 'runtime' object"
+        )
+
+    language = runtime.get("language")
+    package = runtime.get("package")
+    method = runtime.get("method")
+
+    if language not in {"python", "typescript"}:
+        raise ValueError(
+            f"Tool '{spec.get('id', '<unknown>')}' has invalid runtime.language '{language}'. "
+            "Expected 'python' or 'typescript'."
+        )
+
+    if not package or not method:
+        raise ValueError(
+            f"Tool '{spec.get('id', '<unknown>')}' runtime must define non-empty 'package' and 'method'"
+        )
+
+    return {
+        "language": str(language),
+        "package": str(package),
+        "method": str(method),
+    }
+
+
+def _requires_approval(spec: dict[str, Any]) -> bool:
+    explicit = spec.get("requires_approval")
+    if explicit is not None:
+        return bool(explicit)
+    return str(spec.get("approval", "auto")).lower() == "manual"
+
+
+def _timeout_hms(spec: dict[str, Any]) -> str | None:
+    raw = spec.get("timeout")
+    if raw in (None, ""):
+        return None
+    value = str(raw).strip()
+    if not re.fullmatch(r"(?i)(?:\d+mo|\d+d|\d+h|\d+m|\d+s)+", value):
+        raise ValueError(
+            f"Tool '{spec.get('id', '<unknown>')}' has invalid timeout '{raw}'. "
+            "Expected duration format like '0h5m0s', '2d6h', or '1mo2d3h4m5s'."
+        )
+    return value
+
+
+def load_tool_specs(specs_dir: Path) -> list[dict[str, Any]]:
+    specs: list[dict[str, Any]] = []
+    for yaml_file in sorted(specs_dir.glob("*.yaml")):
+        with open(yaml_file) as f:
+            spec = yaml.safe_load(f)
+            ensure_spec_version(spec)
+            specs.append(spec)
+    return specs
+
+
+def generate_python_code(specs: list[dict[str, Any]]) -> str:
+    lines = [
+        "# Copyright (c) 2025-2026 Datalayer, Inc.",
+        "# Distributed under the terms of the Modified BSD License.",
+        '"""',
+        "Tool Catalog.",
+        "",
+        "Predefined runtime tools that can be attached to agents.",
+        "",
+        "This file is AUTO-GENERATED from YAML specifications.",
+        "DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        '"""',
+        "",
+        "from typing import Dict, List",
+        "",
+        "from agent_runtimes.types import ToolRuntimeSpec, ToolSpec",
+        "",
+        "",
+        "# " + "=" * 76,
+        "# Tool Definitions",
+        "# " + "=" * 76,
+        "",
+    ]
+
+    for spec in specs:
+        tool_id = spec["id"]
+        version = spec["version"]
+        const_name = (
+            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+        )
+        runtime = _require_runtime(spec)
+        requires_approval = _requires_approval(spec)
+        timeout = _timeout_hms(spec)
+        icon = f'"{spec.get("icon")}"' if spec.get("icon") else "None"
+        emoji = f'"{spec.get("emoji")}"' if spec.get("emoji") else "None"
+        timeout_py = f'"{timeout}"' if timeout else "None"
+
+        lines.extend(
+            [
+                f"{const_name} = ToolSpec(",
+                f'    id="{tool_id}",',
+                f'    version="{version}",',
+                f'    name="{spec["name"]}",',
+                f'    description="{spec.get("description", "")}",',
+                f"    tags={_fmt_list(spec.get('tags', []))},",
+                f"    enabled={spec.get('enabled', True)},",
+                f'    approval="{spec.get("approval", "auto")}",',
+                f"    timeout={timeout_py},",
+                f"    requires_approval={requires_approval},",
+                "    runtime=ToolRuntimeSpec(",
+                f'        language="{runtime["language"]}",',
+                f'        package="{runtime["package"]}",',
+                f'        method="{runtime["method"]}",',
+                "    ),",
+                f"    icon={icon},",
+                f"    emoji={emoji},",
+                ")",
+                "",
+            ]
+        )
+
+    lines.extend(
+        [
+            "# " + "=" * 76,
+            "# Tool Catalog",
+            "# " + "=" * 76,
+            "",
+            "TOOL_CATALOG: Dict[str, ToolSpec] = {",
+        ]
+    )
+
+    for spec in specs:
+        tool_id = spec["id"]
+        version = spec["version"]
+        const_name = (
+            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+        )
+        lines.append(f'    "{tool_id}": {const_name},')
+
+    lines.extend(
+        [
+            "}",
+            "",
+            "",
+            "def get_tool_spec(tool_id: str) -> ToolSpec | None:",
+            '    """Get a tool specification by ID (accepts both bare and versioned refs)."""',
+            "    spec = TOOL_CATALOG.get(tool_id)",
+            "    if spec is not None:",
+            "        return spec",
+            "    base, _, ver = tool_id.rpartition(':')",
+            "    if base and '.' in ver:",
+            "        return TOOL_CATALOG.get(base)",
+            "    return None",
+            "",
+            "",
+            "def list_tool_specs() -> List[ToolSpec]:",
+            '    """List all tool specifications."""',
+            "    return list(TOOL_CATALOG.values())",
+            "",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
+    lines = [
+        "/*",
+        " * Copyright (c) 2025-2026 Datalayer, Inc.",
+        " * Distributed under the terms of the Modified BSD License.",
+        " */",
+        "",
+        "/**",
+        " * Tool Catalog",
+        " *",
+        " * Predefined runtime tools that can be attached to agents.",
+        " *",
+        " * This file is AUTO-GENERATED from YAML specifications.",
+        " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        " */",
+        "",
+        "import type { ToolSpec } from '../types';",
+        "",
+        "// " + "=" * 76,
+        "// Tool Definitions",
+        "// " + "=" * 76,
+        "",
+    ]
+
+    for spec in specs:
+        tool_id = spec["id"]
+        version = spec["version"]
+        const_name = (
+            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+        )
+        runtime = _require_runtime(spec)
+        requires_approval = _requires_approval(spec)
+        timeout = _timeout_hms(spec)
+        tags_json = str(spec.get("tags", [])).replace("'", '"')
+        icon = f"'{spec.get('icon')}'" if spec.get("icon") else "undefined"
+        emoji = f"'{spec.get('emoji')}'" if spec.get("emoji") else "undefined"
+        timeout_ts = f"'{timeout}'" if timeout else "undefined"
+
+        lines.extend(
+            [
+                f"export const {const_name}: ToolSpec = {{",
+                f"  id: '{tool_id}',",
+                f"  version: '{version}',",
+                f"  name: '{spec['name']}',",
+                f"  description: '{spec.get('description', '')}',",
+                f"  tags: {tags_json},",
+                f"  enabled: {str(spec.get('enabled', True)).lower()},",
+                f"  approval: '{spec.get('approval', 'auto')}',",
+                f"  timeout: {timeout_ts},",
+                f"  requiresApproval: {str(requires_approval).lower()},",
+                "  runtime: {",
+                f"    language: '{runtime['language']}',",
+                f"    package: '{runtime['package']}',",
+                f"    method: '{runtime['method']}',",
+                "  },",
+                f"  icon: {icon},",
+                f"  emoji: {emoji},",
+                "};",
+                "",
+            ]
+        )
+
+    lines.extend(
+        [
+            "// " + "=" * 76,
+            "// Tool Catalog",
+            "// " + "=" * 76,
+            "",
+            "export const TOOL_CATALOG: Record<string, ToolSpec> = {",
+        ]
+    )
+
+    for spec in specs:
+        tool_id = spec["id"]
+        version = spec["version"]
+        const_name = (
+            f"{tool_id.upper().replace('-', '_')}_TOOL_SPEC{version_suffix(version)}"
+        )
+        lines.append(f"  '{tool_id}': {const_name},")
+
+    lines.extend(
+        [
+            "};",
+            "",
+            "export function getToolSpecs(): ToolSpec[] {",
+            "  return Object.values(TOOL_CATALOG);",
+            "}",
+            "",
+            "function resolveToolId(toolId: string): string {",
+            "  if (toolId in TOOL_CATALOG) return toolId;",
+            "  const idx = toolId.lastIndexOf(':');",
+            "  if (idx > 0) {",
+            "    const base = toolId.slice(0, idx);",
+            "    if (base in TOOL_CATALOG) return base;",
+            "  }",
+            "  return toolId;",
+            "}",
+            "",
+            "export function getToolSpec(toolId: string): ToolSpec | undefined {",
+            "  return TOOL_CATALOG[resolveToolId(toolId)];",
+            "}",
+            "",
+        ]
+    )
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate Python and TypeScript code from YAML tool specifications"
+    )
+    parser.add_argument(
+        "--specs-dir",
+        type=Path,
+        required=True,
+        help="Directory containing YAML specification files",
+    )
+    parser.add_argument(
+        "--python-output",
+        type=Path,
+        required=True,
+        help="Output path for generated Python file",
+    )
+    parser.add_argument(
+        "--typescript-output",
+        type=Path,
+        required=True,
+        help="Output path for generated TypeScript file",
+    )
+
+    args = parser.parse_args()
+
+    if not args.specs_dir.exists():
+        print(f"Error: Specs directory does not exist: {args.specs_dir}")
+        sys.exit(1)
+
+    print(f"Loading tool specs from {args.specs_dir}...")
+    specs = load_tool_specs(args.specs_dir)
+    print(f"Loaded {len(specs)} tool specifications")
+
+    print("Generating Python code...")
+    python_code = generate_python_code(specs)
+    args.python_output.parent.mkdir(parents=True, exist_ok=True)
+    args.python_output.write_text(python_code)
+    print(f"✓ Generated {args.python_output}")
+
+    print("Generating TypeScript code...")
+    typescript_code = generate_typescript_code(specs)
+    args.typescript_output.parent.mkdir(parents=True, exist_ok=True)
+    args.typescript_output.write_text(typescript_code)
+    print(f"✓ Generated {args.typescript_output}")
+
+    print(f"\n✓ Successfully generated code from {len(specs)} tool specs")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/codegen/generate_triggers.py

@@ -0,0 +1,295 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""
+Generate Python and TypeScript code from YAML trigger specifications.
+
+Usage:
+    python generate_triggers.py \\
+      --specs-dir specs/triggers \\
+      --python-output agent_runtimes/specs/triggers.py \\
+      --typescript-output src/specs/triggers.ts
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from versioning import ensure_spec_version, version_suffix
+
+
+def _esc(text: str) -> str:
+    """Escape single quotes for TypeScript string literals."""
+    return text.replace("'", "\\'")
+
+
+def _esc_dq(text: str) -> str:
+    """Escape double quotes for Python string literals."""
+    return text.replace('"', '\\"')
+
+
+def load_specs(specs_dir: Path) -> list[dict[str, Any]]:
+    """Load all YAML specifications from a directory (including subdirectories)."""
+    specs = []
+    for yaml_file in sorted(specs_dir.rglob("*.yaml")):
+        with open(yaml_file) as f:
+            spec = yaml.safe_load(f)
+            ensure_spec_version(spec)
+            specs.append(spec)
+    return specs
+
+
+def _py_field(f: dict[str, Any]) -> str:
+    """Format a TriggerField as a Python dict literal."""
+    parts = [
+        f'"name": "{f["name"]}"',
+        f'"label": "{f["label"]}"',
+        f'"type": "{f["type"]}"',
+        f'"required": {str(f["required"])}',
+    ]
+    if "placeholder" in f:
+        parts.append(f'"placeholder": "{_esc_dq(f["placeholder"])}"')
+    if "help" in f:
+        parts.append(f'"help": "{_esc_dq(f["help"])}"')
+    if "font" in f:
+        parts.append(f'"font": "{f["font"]}"')
+    return "{" + ", ".join(parts) + "}"
+
+
+def _ts_field(f: dict[str, Any]) -> str:
+    """Format a TriggerField as a TypeScript object literal."""
+    parts = [
+        f"name: '{f['name']}'",
+        f"label: '{_esc(f['label'])}'",
+        f"type: '{f['type']}'",
+        f"required: {'true' if f['required'] else 'false'}",
+    ]
+    if "placeholder" in f:
+        parts.append(f"placeholder: '{_esc(f['placeholder'])}'")
+    if "help" in f:
+        parts.append(f"help: '{_esc(f['help'])}'")
+    if "font" in f:
+        parts.append(f"font: '{f['font']}'")
+    return "{ " + ", ".join(parts) + " }"
+
+
+def generate_python_code(specs: list[dict[str, Any]]) -> str:
+    """Generate Python code from trigger specifications."""
+    lines = [
+        "# Copyright (c) 2025-2026 Datalayer, Inc.",
+        "# Distributed under the terms of the Modified BSD License.",
+        '"""',
+        "Trigger Catalog.",
+        "",
+        "Predefined trigger type configurations.",
+        "",
+        "This file is AUTO-GENERATED from YAML specifications.",
+        "DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        '"""',
+        "",
+        "from typing import Dict, List",
+        "",
+        "from agent_runtimes.types import TriggerField, TriggerSpec",
+        "",
+        "",
+        "# " + "=" * 76,
+        "# Trigger Definitions",
+        "# " + "=" * 76,
+        "",
+    ]
+
+    for spec in specs:
+        trigger_id = spec["id"]
+        version = spec["version"]
+        const_name = f"{trigger_id.upper().replace('-', '_')}_TRIGGER_SPEC{version_suffix(version)}"
+        desc = _esc_dq(spec.get("description", "").strip().replace("\n", " "))
+        fields = spec.get("fields", [])
+
+        lines.extend(
+            [
+                f"{const_name} = TriggerSpec(",
+                f'    id="{trigger_id}",',
+                f'    version="{version}",',
+                f'    name="{spec["name"]}",',
+                f'    description="{desc}",',
+                f'    type="{spec["type"]}",',
+            ]
+        )
+        if fields:
+            field_strs = [_py_field(f) for f in fields]
+            lines.append("    fields=[")
+            for fs in field_strs:
+                lines.append(f"        TriggerField(**{fs}),")
+            lines.append("    ],")
+        lines.extend([")", ""])
+
+    lines.extend(
+        [
+            "# " + "=" * 76,
+            "# Trigger Catalog",
+            "# " + "=" * 76,
+            "",
+            "TRIGGER_CATALOG: Dict[str, TriggerSpec] = {",
+        ]
+    )
+    for spec in specs:
+        trigger_id = spec["id"]
+        version = spec["version"]
+        const_name = f"{trigger_id.upper().replace('-', '_')}_TRIGGER_SPEC{version_suffix(version)}"
+        lines.append(f'    "{trigger_id}": {const_name},')
+    lines.extend(
+        [
+            "}",
+            "",
+            "",
+            "def get_trigger_spec(trigger_id: str) -> TriggerSpec | None:",
+            '    """Get a trigger specification by ID (accepts both bare and versioned refs)."""',
+            "    spec = TRIGGER_CATALOG.get(trigger_id)",
+            "    if spec is not None:",
+            "        return spec",
+            "    base, _, ver = trigger_id.rpartition(':')",
+            "    if base and '.' in ver:",
+            "        return TRIGGER_CATALOG.get(base)",
+            "    return None",
+            "",
+            "",
+            "def list_trigger_specs() -> List[TriggerSpec]:",
+            '    """List all trigger specifications."""',
+            "    return list(TRIGGER_CATALOG.values())",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def generate_typescript_code(specs: list[dict[str, Any]]) -> str:
+    """Generate TypeScript code from trigger specifications."""
+    lines = [
+        "/*",
+        " * Copyright (c) 2025-2026 Datalayer, Inc.",
+        " * Distributed under the terms of the Modified BSD License.",
+        " */",
+        "",
+        "/**",
+        " * Trigger Catalog",
+        " *",
+        " * Predefined trigger type configurations.",
+        " *",
+        " * This file is AUTO-GENERATED from YAML specifications.",
+        " * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.",
+        " */",
+        "",
+        "import type { TriggerSpec } from '../types';",
+        "",
+        "// " + "=" * 76,
+        "// Trigger Definitions",
+        "// " + "=" * 76,
+        "",
+    ]
+
+    for spec in specs:
+        trigger_id = spec["id"]
+        version = spec["version"]
+        const_name = f"{trigger_id.upper().replace('-', '_')}_TRIGGER_SPEC{version_suffix(version)}"
+        desc = _esc(spec.get("description", "").strip().replace("\n", " "))
+        fields = spec.get("fields", [])
+
+        lines.extend(
+            [
+                f"export const {const_name}: TriggerSpec = {{",
+                f"  id: '{trigger_id}',",
+                f"  version: '{version}',",
+                f"  name: '{_esc(spec['name'])}',",
+                f"  description: '{desc}',",
+                f"  type: '{spec['type']}',",
+            ]
+        )
+        if fields:
+            field_strs = [_ts_field(f) for f in fields]
+            lines.append("  fields: [")
+            for fs in field_strs:
+                lines.append(f"    {fs},")
+            lines.append("  ],")
+        else:
+            lines.append("  fields: [],")
+        lines.extend(["};", ""])
+
+    lines.extend(
+        [
+            "// " + "=" * 76,
+            "// Trigger Catalog",
+            "// " + "=" * 76,
+            "",
+            "export const TRIGGER_CATALOG: Record<string, TriggerSpec> = {",
+        ]
+    )
+    for spec in specs:
+        trigger_id = spec["id"]
+        version = spec["version"]
+        const_name = f"{trigger_id.upper().replace('-', '_')}_TRIGGER_SPEC{version_suffix(version)}"
+        lines.append(f"  '{trigger_id}': {const_name},")
+    lines.extend(
+        [
+            "};",
+            "",
+            "export function getTriggerSpecs(): TriggerSpec[] {",
+            "  return Object.values(TRIGGER_CATALOG);",
+            "}",
+            "",
+            "function resolveTriggerIdTs(triggerId: string): string {",
+            "  if (triggerId in TRIGGER_CATALOG) return triggerId;",
+            "  const idx = triggerId.lastIndexOf(':');",
+            "  if (idx > 0) {",
+            "    const base = triggerId.slice(0, idx);",
+            "    if (base in TRIGGER_CATALOG) return base;",
+            "  }",
+            "  return triggerId;",
+            "}",
+            "",
+            "export function getTriggerSpec(triggerId: string): TriggerSpec | undefined {",
+            "  return TRIGGER_CATALOG[resolveTriggerIdTs(triggerId)];",
+            "}",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Generate Python and TypeScript code from YAML trigger specifications"
+    )
+    parser.add_argument("--specs-dir", type=Path, required=True)
+    parser.add_argument("--python-output", type=Path, required=True)
+    parser.add_argument("--typescript-output", type=Path, required=True)
+    args = parser.parse_args()
+
+    if not args.specs_dir.exists():
+        print(f"Error: Specs directory does not exist: {args.specs_dir}")
+        sys.exit(1)
+
+    print(f"Loading trigger specs from {args.specs_dir}...")
+    specs = load_specs(args.specs_dir)
+    print(f"Loaded {len(specs)} trigger specifications")
+
+    print("Generating Python code...")
+    python_code = generate_python_code(specs)
+    args.python_output.parent.mkdir(parents=True, exist_ok=True)
+    args.python_output.write_text(python_code)
+    print(f"✓ Generated {args.python_output}")
+
+    print("Generating TypeScript code...")
+    typescript_code = generate_typescript_code(specs)
+    args.typescript_output.parent.mkdir(parents=True, exist_ok=True)
+    args.typescript_output.write_text(typescript_code)
+    print(f"✓ Generated {args.typescript_output}")
+
+    print(f"\n✓ Successfully generated code from {len(specs)} trigger specs")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/codegen/versioning.py

@@ -0,0 +1,53 @@
+# Copyright (c) 2025-2026 Datalayer, Inc.
+# Distributed under the terms of the Modified BSD License.
+
+"""Helpers for versioned spec IDs and generated symbol names."""
+
+from __future__ import annotations
+
+from typing import Any, Tuple
+
+DEFAULT_SPEC_VERSION = "0.0.1"
+
+
+def ensure_spec_version(
+    spec: dict[str, Any], *, default: str = DEFAULT_SPEC_VERSION
+) -> str:
+    """Ensure a spec dict has a version and return it."""
+    version = str(spec.get("version") or default)
+    spec["version"] = version
+    return version
+
+
+def split_spec_ref(
+    ref: str | None, *, default: str = DEFAULT_SPEC_VERSION
+) -> Tuple[str, str]:
+    """Split a ref like ``name:0.0.1`` into ``(name, 0.0.1)``.
+
+    Uses rsplit so values that include ``:`` (e.g. model IDs) are preserved.
+    """
+    value = (ref or "").strip()
+    if not value:
+        return "", default
+    base, sep, version = value.rpartition(":")
+    if sep and version and _looks_like_version(version):
+        return base, version
+    return value, default
+
+
+def versioned_ref(ref: str, version: str) -> str:
+    """Build ``name:version`` references."""
+    return f"{ref}:{version}"
+
+
+def version_suffix(version: str) -> str:
+    """Build symbol-safe suffix (e.g. 0.0.1 -> _0_0_1)."""
+    normalized = version.replace(".", "_").replace("-", "_")
+    return f"_{normalized}"
+
+
+def _looks_like_version(value: str) -> bool:
+    parts = value.split(".")
+    if not parts:
+        return False
+    return all(part.isdigit() for part in parts)