code0-hercules 1.3.0__py3-none-any.whl

hercules/internal/schema.py

@@ -0,0 +1,158 @@
+"""Schema registry plus TypeScript type-string and rule generation.
+
+Data types are described with Pydantic models. Registered models are keyed by
+class; when a registered model appears nested inside another type it is rendered
+as its identifier instead of being inlined, which lets recursive and
+mutually-recursive data types resolve by reference (mirroring the TypeScript SDK's
+``zod-schema`` behaviour).
+
+The Pydantic ``model_json_schema()`` output is pre-processed here (references to
+registered models become ``tsType`` identifier hints, non-registered nested models
+are inlined, titles are stripped) and then handed to the Node helper, which turns
+it into an inline TypeScript type expression.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Type
+
+from pydantic import BaseModel
+
+from tucana.generated.shared import data_type_pb2
+from hercules.internal.tsgen import json_schema_to_ts
+
+SchemaModel = Type[BaseModel]
+
+# Maps a registered Pydantic model class -> its data-type identifier.
+_registry: Dict[SchemaModel, str] = {}
+
+
+def register_schema(model: SchemaModel, identifier: str) -> None:
+    _registry[model] = identifier
+
+
+def get_registered_identifier(model: SchemaModel) -> Optional[str]:
+    return _registry.get(model)
+
+
+def _registered_names() -> Dict[str, str]:
+    """Map each registered model's JSON-schema definition name to its identifier."""
+    return {model.__name__: identifier for model, identifier in _registry.items()}
+
+
+# JSON-schema annotation keywords that describe rather than shape a type. They
+# would otherwise surface as JSDoc comments / noise in the emitted type string.
+_ANNOTATION_KEYS = ("title", "description", "default", "examples", "$comment")
+
+
+def _strip_annotations(node: Any) -> None:
+    if isinstance(node, dict):
+        for key in _ANNOTATION_KEYS:
+            node.pop(key, None)
+        for value in node.values():
+            _strip_annotations(value)
+    elif isinstance(node, list):
+        for item in node:
+            _strip_annotations(item)
+
+
+def _resolve(
+    node: Any,
+    defs: Dict[str, Any],
+    names: Dict[str, str],
+    self_name: str,
+    self_identifier: Optional[str],
+    stack: List[str],
+) -> Any:
+    """Recursively rewrite ``$ref`` nodes.
+
+    References to registered models (and self-references) become ``tsType``
+    identifier hints; references to non-registered nested models are inlined so
+    the whole type collapses into a single expression. A non-registered recursive
+    reference cannot be inlined and raises.
+    """
+    if isinstance(node, list):
+        return [
+            _resolve(item, defs, names, self_name, self_identifier, stack)
+            for item in node
+        ]
+    if not isinstance(node, dict):
+        return node
+
+    ref = node.get("$ref")
+    if isinstance(ref, str) and ref.startswith("#/$defs/"):
+        ref_name = ref.split("/")[-1]
+        if ref_name in names:
+            return {"tsType": names[ref_name]}
+        if ref_name == self_name and self_identifier is not None:
+            return {"tsType": self_identifier}
+        if ref_name in stack:
+            subject = (
+                f'data type "{self_identifier}"' if self_identifier else "the schema"
+            )
+            raise ValueError(
+                f"Cannot generate a type string for {subject}: it contains "
+                f"recursive schemas that cannot be inlined. Register each "
+                f"recursive schema as its own data type so it can be referenced "
+                f"by identifier."
+            )
+        target = defs.get(ref_name, {})
+        return _resolve(
+            target, defs, names, self_name, self_identifier, stack + [ref_name]
+        )
+
+    result: Dict[str, Any] = {}
+    for key, value in node.items():
+        if key in _ANNOTATION_KEYS:
+            continue
+        result[key] = _resolve(
+            value, defs, names, self_name, self_identifier, stack
+        )
+    return result
+
+
+def pydantic_to_type_string(model: SchemaModel) -> str:
+    schema = model.model_json_schema()
+    defs = schema.pop("$defs", {})
+
+    self_identifier = _registry.get(model)
+    names = _registered_names()
+
+    ref = schema.get("$ref")
+    if isinstance(ref, str) and ref.startswith("#/$defs/"):
+        # Self-recursive models put the body under ``$defs`` and make the root a ref.
+        self_name = ref.split("/")[-1]
+        body: Any = defs.get(self_name, {})
+    else:
+        self_name = schema.get("title") or model.__name__
+        body = schema
+
+    resolved = _resolve(body, defs, names, self_name, self_identifier, [self_name])
+    _strip_annotations(resolved)
+
+    name = self_identifier or model.__name__
+    return json_schema_to_ts(resolved, name)
+
+
+def pydantic_to_rules(model: SchemaModel) -> List[data_type_pb2.DefinitionDataTypeRule]:
+    schema = model.model_json_schema()
+    rules: List[data_type_pb2.DefinitionDataTypeRule] = []
+
+    pattern = schema.get("pattern")
+    if pattern:
+        rules.append(
+            data_type_pb2.DefinitionDataTypeRule(
+                regex=data_type_pb2.DataTypeRegexRuleConfig(pattern=pattern)
+            )
+        )
+
+    minimum = schema.get("minimum")
+    maximum = schema.get("maximum")
+    if minimum is not None and maximum is not None:
+        rules.append(
+            data_type_pb2.DefinitionDataTypeRule(
+                number_range=data_type_pb2.DataTypeNumberRangeRuleConfig(
+                    **{"from": int(minimum), "to": int(maximum)}
+                )
+            )
+        )
+    return rules

hercules/internal/tsgen.py

@@ -0,0 +1,93 @@
+"""Bridge to the bundled Node schema-conversion helper (``hercules/_tsgen``).
+
+The helper handles the two directions that have no good pure-Python equivalent:
+
+* a Pydantic JSON schema -> an inline TypeScript type expression
+  (via ``json-schema-to-typescript``)
+* a TypeScript type expression -> a JSON schema
+  (via ``ts-json-schema-generator``)
+
+Node must be installed. The helper's own npm dependencies are installed lazily on
+first use if ``node_modules`` is missing.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+_TSGEN_DIR = Path(__file__).resolve().parent.parent / "_tsgen"
+_CONVERT = _TSGEN_DIR / "convert.mjs"
+
+
+class TsGenError(RuntimeError):
+    """Raised when the Node schema-conversion helper cannot run or fails."""
+
+
+@lru_cache(maxsize=1)
+def _node() -> str:
+    node = shutil.which("node")
+    if node is None:
+        raise TsGenError(
+            "Node.js is required for TypeScript <-> Pydantic schema conversion "
+            "but 'node' was not found on PATH. Install Node.js to continue."
+        )
+    return node
+
+
+@lru_cache(maxsize=1)
+def _ensure_dependencies() -> None:
+    if (_TSGEN_DIR / "node_modules").is_dir():
+        return
+    npm = shutil.which("npm")
+    if npm is None:
+        raise TsGenError(
+            f"The Node helper dependencies are not installed and 'npm' was not "
+            f"found on PATH. Run 'npm install' in {_TSGEN_DIR} manually."
+        )
+    result = subprocess.run(
+        [npm, "install"],
+        cwd=_TSGEN_DIR,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise TsGenError(
+            f"Failed to install Node helper dependencies in {_TSGEN_DIR}:\n"
+            f"{result.stderr.strip()}"
+        )
+
+
+def _run(request: Dict[str, Any]) -> Dict[str, Any]:
+    _ensure_dependencies()
+    result = subprocess.run(
+        [_node(), str(_CONVERT)],
+        input=json.dumps(request),
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise TsGenError(result.stderr.strip() or "Node helper failed.")
+    return json.loads(result.stdout)
+
+
+def json_schema_to_ts(schema: Dict[str, Any], name: str) -> str:
+    """Compile a (pre-processed) JSON schema into an inline TypeScript type string."""
+    return _run({"mode": "json_schema_to_ts", "schema": schema, "name": name})["type"]
+
+
+def ts_to_json_schema(
+    ts_type: str, name: str, preamble: Optional[str] = None
+) -> Dict[str, Any]:
+    """Convert a TypeScript type expression into a JSON schema."""
+    request: Dict[str, Any] = {
+        "mode": "ts_to_json_schema",
+        "ts": ts_type,
+        "name": name,
+    }
+    if preamble:
+        request["preamble"] = preamble
+    return _run(request)["schema"]

hercules/manager/base.py

@@ -0,0 +1,73 @@
+"""Base manager (port of ``src/manager/BaseManager.ts``)."""
+from __future__ import annotations
+
+from typing import Callable, Dict, Generic, Iterator, List, Optional, Tuple, TypeVar
+
+K = TypeVar("K")
+V = TypeVar("V")
+T = TypeVar("T")
+
+
+class BaseManager(Generic[K, V]):
+    def __init__(self) -> None:
+        self.cache: Dict[K, V] = {}
+
+    @property
+    def size(self) -> int:
+        return len(self.cache)
+
+    def get(self, key: K) -> Optional[V]:
+        return self.cache.get(key)
+
+    def has(self, key: K) -> bool:
+        return key in self.cache
+
+    def set(self, key: K, value: V) -> "BaseManager[K, V]":
+        self.cache[key] = value
+        return self
+
+    def delete(self, key: K) -> bool:
+        if key in self.cache:
+            del self.cache[key]
+            return True
+        return False
+
+    def clear(self) -> None:
+        self.cache.clear()
+
+    def values(self) -> List[V]:
+        return list(self.cache.values())
+
+    def keys(self) -> List[K]:
+        return list(self.cache.keys())
+
+    def entries(self) -> List[Tuple[K, V]]:
+        return list(self.cache.items())
+
+    def find(self, predicate: Callable[[V, K], bool]) -> Optional[V]:
+        for key, value in self.cache.items():
+            if predicate(value, key):
+                return value
+        return None
+
+    def filter(self, predicate: Callable[[V, K], bool]) -> List[V]:
+        return [value for key, value in self.cache.items() if predicate(value, key)]
+
+    def map(self, fn: Callable[[V, K], T]) -> List[T]:
+        return [fn(value, key) for key, value in self.cache.items()]
+
+    def some(self, predicate: Callable[[V, K], bool]) -> bool:
+        return any(predicate(value, key) for key, value in self.cache.items())
+
+    def every(self, predicate: Callable[[V, K], bool]) -> bool:
+        return all(predicate(value, key) for key, value in self.cache.items())
+
+    def for_each(self, fn: Callable[[V, K], None]) -> None:
+        for key, value in self.cache.items():
+            fn(value, key)
+
+    def __iter__(self) -> Iterator[Tuple[K, V]]:
+        return iter(self.cache.items())
+
+    def __len__(self) -> int:
+        return len(self.cache)

hercules/manager/config.py

@@ -0,0 +1,45 @@
+"""Config manager (port of ``src/manager/config-manager.ts``)."""
+from __future__ import annotations
+
+from typing import List
+
+from hercules._tucana.helpers import construct_value, to_allowed_value
+from hercules.manager.base import BaseManager
+from hercules.types import ProjectConfiguration
+
+
+class ConfigManager(BaseManager):
+    def update(self, configs: List) -> None:
+        self.clear()
+        for config in configs:
+            module_configurations = list(config.module_configurations)
+
+            def make_find_config(mcs):
+                def find_config(identifier):
+                    mc = next(
+                        (c for c in mcs if c.identifier == identifier), None
+                    )
+                    if mc is None:
+                        return None
+                    return to_allowed_value(
+                        mc.value if mc.HasField("value") else construct_value(None)
+                    )
+
+                return find_config
+
+            self.set(
+                config.project_id,
+                ProjectConfiguration(
+                    project_id=config.project_id,
+                    config_values=[
+                        {
+                            "identifier": mc.identifier,
+                            "value": to_allowed_value(
+                                mc.value if mc.HasField("value") else construct_value(None)
+                            ),
+                        }
+                        for mc in module_configurations
+                    ],
+                    find_config=make_find_config(module_configurations),
+                ),
+            )

hercules/manager/datatype.py

@@ -0,0 +1,8 @@
+"""Data type manager (port of ``src/manager/DataTypeManager.ts``)."""
+from __future__ import annotations
+
+from hercules.manager.base import BaseManager
+
+
+class DataTypeManager(BaseManager):
+    pass

hercules/manager/event.py

@@ -0,0 +1,8 @@
+"""Event manager (port of ``src/manager/EventManager.ts``)."""
+from __future__ import annotations
+
+from hercules.manager.base import BaseManager
+
+
+class EventManager(BaseManager):
+    pass

hercules/manager/flow.py

@@ -0,0 +1,12 @@
+"""Flow manager (port of ``src/manager/FlowManager.ts``).
+
+Registry of the action's own flows, kept in sync via ActionFlowUpdate messages.
+Keyed by flow id.
+"""
+from __future__ import annotations
+
+from hercules.manager.base import BaseManager
+
+
+class FlowManager(BaseManager):
+    pass

hercules/manager/function.py

@@ -0,0 +1,8 @@
+"""Function manager (port of ``src/manager/FunctionManager.ts``)."""
+from __future__ import annotations
+
+from hercules.manager.base import BaseManager
+
+
+class FunctionManager(BaseManager):
+    pass

hercules/manager/runtime_event.py

@@ -0,0 +1,8 @@
+"""Runtime event manager (port of ``src/manager/RuntimeEventManager.ts``)."""
+from __future__ import annotations
+
+from hercules.manager.base import BaseManager
+
+
+class RuntimeEventManager(BaseManager):
+    pass

hercules/manager/runtime_function.py

@@ -0,0 +1,8 @@
+"""Runtime function manager (port of ``src/manager/RuntimeFunctionManager.ts``)."""
+from __future__ import annotations
+
+from hercules.manager.base import BaseManager
+
+
+class RuntimeFunctionManager(BaseManager):
+    pass

hercules/map/datatype.py

@@ -0,0 +1,41 @@
+"""Data type mapping (port of ``src/map/datatype.map.ts``)."""
+from __future__ import annotations
+
+from hercules._metadata import get_metadata
+from hercules.internal.schema import register_schema
+from hercules.models.datatype import DataTypeProps
+
+
+def data_type_map(klass: type) -> DataTypeProps:
+    identifier = get_metadata("hercules:identifier", klass)
+    name = get_metadata("hercules:name", klass) or []
+    display_message = get_metadata("hercules:display_message", klass) or []
+    alias = get_metadata("hercules:alias", klass) or []
+    generic_keys = get_metadata("hercules:generic_keys", klass) or []
+
+    if not identifier:
+        raise ValueError(
+            f"Data type class {klass.__name__} is missing an identifier. "
+            f'Add @Identifier("your_identifier") to the class.'
+        )
+
+    schema = get_metadata("hercules:schema", klass)
+    if schema is None:
+        raise ValueError(
+            f"Data type class {klass.__name__} is missing a schema. "
+            f"Add @Schema(MyModel) with a Pydantic model to the class."
+        )
+
+    register_schema(schema, identifier)
+
+    type_string = get_metadata("hercules:type_string", klass)
+
+    return DataTypeProps(
+        identifier=identifier,
+        schema=schema,
+        name=name,
+        display_message=display_message,
+        alias=alias,
+        generic_keys=generic_keys,
+        type_string=type_string,
+    )

hercules/map/event.py

@@ -0,0 +1,74 @@
+"""Event mapping (port of ``src/map/event.map.ts``)."""
+from __future__ import annotations
+
+from dataclasses import fields, replace
+from typing import List
+
+from hercules._metadata import get_metadata, get_own_metadata
+from hercules.map.runtime_event import runtime_event_map
+from hercules.models.event import EventModel, EventSettingProps
+
+
+def _merge_setting(base: EventSettingProps, override: EventSettingProps) -> EventSettingProps:
+    # Mirror `{...rs, ...override}`: only the properties the override actually set
+    # (non-None) replace the runtime event's setting.
+    changes = {
+        f.name: getattr(override, f.name)
+        for f in fields(override)
+        if f.name != "identifier" and getattr(override, f.name) is not None
+    }
+    return replace(base, **changes)
+
+
+def event_map(klass: type) -> EventModel:
+    parent_class = klass.__bases__[0]
+    runtime_event = runtime_event_map(parent_class)
+
+    identifier = get_metadata("hercules:identifier", klass)
+    signature = get_metadata("hercules:signature", klass)
+    settings: List[EventSettingProps] = (
+        get_own_metadata("hercules:flow_settings", klass) or []
+    )
+    name = get_metadata("hercules:name", klass)
+    description = get_metadata("hercules:description", klass)
+    documentation = get_metadata("hercules:documentation", klass)
+    display_message = get_metadata("hercules:display_message", klass)
+    alias = get_metadata("hercules:alias", klass)
+    display_icon = get_metadata("hercules:display_icon", klass)
+    editable = get_metadata("hercules:editable", klass)
+    editable = editable if editable is not None else False
+
+    if not identifier:
+        raise ValueError(
+            f"Event class {klass.__name__} is missing an identifier. "
+            f'Add @Identifier("your_identifier") to the class.'
+        )
+
+    runtime_settings = runtime_event.settings or []
+    for es in settings:
+        if not any(s.identifier == es.identifier for s in runtime_settings):
+            raise ValueError(
+                f'Event class {klass.__name__} has a setting "{es.identifier}" '
+                f"that does not exist in its runtime event."
+            )
+
+    # Settings come from the runtime event (in its order); the event class only
+    # overrides individual properties per identifier.
+    merged_settings: List[EventSettingProps] = []
+    for rs in runtime_settings:
+        override = next((s for s in settings if s.identifier == rs.identifier), None)
+        merged_settings.append(_merge_setting(rs, override) if override else replace(rs))
+
+    return EventModel(
+        runtime_identifier=runtime_event.identifier,
+        identifier=identifier,
+        signature=signature or runtime_event.signature,
+        settings=merged_settings,
+        name=name or runtime_event.name,
+        description=description or runtime_event.description,
+        documentation=documentation or runtime_event.documentation,
+        display_message=display_message or runtime_event.display_message,
+        alias=alias or runtime_event.alias,
+        display_icon=display_icon or runtime_event.display_icon,
+        editable=editable,
+    )

hercules/map/function.py

@@ -0,0 +1,76 @@
+"""Function mapping (port of ``src/map/function.map.ts``)."""
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import List
+
+from hercules._metadata import get_metadata
+from hercules.map.runtime_function import runtime_function_map
+from hercules.models.function import FunctionParameterProps, FunctionProps
+
+
+def function_map(klass: type) -> FunctionProps:
+    parent_class = klass.__bases__[0]
+    runtime_function = runtime_function_map(parent_class)
+
+    identifier = get_metadata("hercules:identifier", klass)
+    function_parameters: List[FunctionParameterProps] = (
+        get_metadata("hercules:function_parameters", klass) or []
+    )
+    name = get_metadata("hercules:name", klass)
+    display_message = get_metadata("hercules:display_message", klass)
+    description = get_metadata("hercules:description", klass)
+    deprecation_message = get_metadata("hercules:deprecation_message", klass)
+    alias = get_metadata("hercules:alias", klass)
+    documentation = get_metadata("hercules:documentation", klass)
+    signature = get_metadata("hercules:signature", klass)
+    display_icon = get_metadata("hercules:display_icon", klass)
+    throws_error = get_metadata("hercules:throws_error", klass)
+    design = get_metadata("hercules:design", klass)
+
+    runtime_params = runtime_function.parameters or []
+    if len(function_parameters) > len(runtime_params):
+        raise ValueError(
+            f"Function definition class {klass.__name__} has more function "
+            f"parameters than its runtime function."
+        )
+
+    for fp in function_parameters:
+        if not any(p.runtime_name == fp.runtime_name for p in runtime_params):
+            raise ValueError(
+                f"Function definition class {klass.__name__} has a function "
+                f'parameter "{fp.runtime_name}" that does not exist in its '
+                f"runtime function."
+            )
+
+    merged: List[FunctionParameterProps] = list(function_parameters)
+    for rp in runtime_params:
+        if not any(p.runtime_name == rp.runtime_name for p in merged):
+            merged.append(replace(rp, runtime_definition_name=rp.runtime_name))
+
+    return FunctionProps(
+        runtime_definition_name=runtime_function.runtime_name,
+        runtime_name=identifier or runtime_function.runtime_name,
+        signature=signature or runtime_function.signature,
+        throws_error=throws_error if throws_error is not None else runtime_function.throws_error,
+        alias=alias or runtime_function.alias,
+        description=description or runtime_function.description,
+        name=name or runtime_function.name,
+        documentation=documentation or runtime_function.documentation,
+        deprecation_message=deprecation_message or runtime_function.deprecation_message,
+        display_message=display_message or runtime_function.display_message,
+        display_icon=display_icon or runtime_function.display_icon,
+        design=design or runtime_function.design,
+        parameters=[
+            replace(
+                p,
+                runtime_definition_name=p.runtime_definition_name or p.runtime_name,
+                name=p.name or [],
+                description=p.description or [],
+                documentation=p.documentation or [],
+                hidden=p.hidden or False,
+                optional=p.optional or False,
+            )
+            for p in merged
+        ],
+    )

hercules/map/runtime_event.py

@@ -0,0 +1,43 @@
+"""Runtime event mapping (port of ``src/map/runtime_event.map.ts``)."""
+from __future__ import annotations
+
+from hercules._metadata import get_metadata
+from hercules.models.runtime_event import RuntimeEventProps
+
+
+def runtime_event_map(klass: type) -> RuntimeEventProps:
+    identifier = get_metadata("hercules:identifier", klass)
+    signature = get_metadata("hercules:signature", klass)
+    settings = get_metadata("hercules:flow_settings", klass) or []
+    name = get_metadata("hercules:name", klass) or []
+    description = get_metadata("hercules:description", klass) or []
+    documentation = get_metadata("hercules:documentation", klass) or []
+    display_message = get_metadata("hercules:display_message", klass) or []
+    alias = get_metadata("hercules:alias", klass) or []
+    display_icon = get_metadata("hercules:display_icon", klass)
+    editable = get_metadata("hercules:editable", klass)
+    editable = editable if editable is not None else False
+
+    if not identifier:
+        raise ValueError(
+            f"Runtime event class {klass.__name__} is missing an identifier. "
+            f'Add @Identifier("your_identifier") to the class.'
+        )
+    if not signature:
+        raise ValueError(
+            f"Runtime event class {klass.__name__} is missing a signature. "
+            f'Add @Signature("(): RETURN_TYPE") to the class.'
+        )
+
+    return RuntimeEventProps(
+        identifier=identifier,
+        signature=signature,
+        settings=settings,
+        name=name,
+        description=description,
+        documentation=documentation,
+        display_message=display_message,
+        alias=alias,
+        display_icon=display_icon,
+        editable=editable,
+    )