code0-hercules 1.3.0__py3-none-any.whl

hercules/definitions/taurus_text/runtime_functions/std_text_uppercase.py

@@ -0,0 +1,18 @@
+from hercules.models.runtime_function import RuntimeFunctionRunnable
+from hercules.decorators.meta import Alias, Description, DisplayIcon, DisplayMessage, Identifier, Name, Signature
+from hercules.decorators.runtime_function import OmitRuntimeFunction
+from hercules.decorators.function import Parameter
+
+
+@OmitRuntimeFunction()
+@Identifier("std::text::uppercase")
+@Signature("(value: TEXT): TEXT")
+@Name({"code": "en-US", "content": "Uppercase"})
+@Description({"code": "en-US", "content": "Transforms all letters in the text to their uppercase equivalents."})
+@DisplayMessage({"code": "en-US", "content": "Uppercase ${value}"})
+@Alias({"code": "en-US", "content": "uppercase;text;string;std"})
+@DisplayIcon("tabler:abc")
+@Parameter({"runtime_name": "value", "name": [{"code": "en-US", "content": "Text Value"}], "description": [{"code": "en-US", "content": "Converts all characters in the input text to uppercase."}]})
+class StdTextUppercase(RuntimeFunctionRunnable):
+    def run(self, *args):
+        raise NotImplementedError("StdTextUppercase.run() is not implemented")

hercules/events.py

@@ -0,0 +1,23 @@
+"""Event names (port of ``src/events.ts``)."""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CodeZeroEvent(str, Enum):
+    error = "error"
+    connected = "connected"
+    stream_message_received = "streamMessageReceived"
+    stream_message_sent = "streamMessageSent"
+    module_updated = "moduleUpdated"
+    execution_request_received = "executionRequestReceived"
+    sub_flow_execution_response_received = "subFlowExecutionResponseReceived"
+    flow_execution_response_received = "flowExecutionResponseReceived"
+    flow_updated = "flowUpdated"
+    flow_deleted = "flowDeleted"
+
+    def __str__(self) -> str:  # so it can be used interchangeably with the value
+        return self.value
+
+
+__all__ = ["CodeZeroEvent"]

hercules/internal/connection.py

@@ -0,0 +1,37 @@
+"""gRPC connection (port of ``src/internal/connection.ts``).
+
+Opens the bi-directional ``ActionTransferService.Transfer`` stream and sends the
+initial ``ActionLogon`` request. Uses ``grpc.aio`` for an async streaming client.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import grpc
+
+from tucana.generated.aquila import action_pb2, action_pb2_grpc
+from tucana.generated.shared import module_pb2
+
+
+async def create_connection(
+    module: module_pb2.Module,
+    auth_token: str,
+    aquila_url: str,
+    grpc_options: Optional[list] = None,
+) -> Tuple[grpc.aio.Channel, "grpc.aio.StreamStreamCall"]:
+    channel = grpc.aio.insecure_channel(aquila_url, options=grpc_options)
+    stub = action_pb2_grpc.ActionTransferServiceStub(channel)
+
+    # Bi-directional stream. Authorization is passed as call metadata.
+    stream = stub.Transfer(metadata=(("authorization", auth_token),))
+
+    await stream.write(
+        action_pb2.ActionTransferRequest(
+            logon=action_pb2.ActionLogon(
+                module=module,
+                scaling_option=action_pb2.ActionLogon.ScalingOption.SPLIT,
+            )
+        )
+    )
+
+    return channel, stream

hercules/internal/literal.py

@@ -0,0 +1,113 @@
+"""Inline ``${signature}`` reference resolution (port of ``src/internal/literal.ts``).
+
+Resolves an ``aquila.ActionLiteralValue`` into a plain Python value, substituting
+every ``${signature}`` placeholder inside a (possibly nested) string leaf with the
+value of the matching inline reference.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Optional
+
+from hercules._tucana.helpers import PlainValue, to_allowed_value
+from hercules.types import RuntimeError
+from tucana.generated.shared import struct_pb2
+
+__all__ = ["resolve_literal", "resolve_node_value", "to_sub_flow_caller"]
+
+# Matches every ``${signature}`` placeholder inside a string.
+_REFERENCE_PATTERN = re.compile(r"\$\{([^}]+)\}")
+# Matches a string that consists of exactly one ``${signature}`` placeholder.
+# ``\A``/``\Z`` (not ``^``/``$``) so a trailing newline is not treated as a sole match,
+# mirroring JavaScript's ``$`` anchor.
+_SOLE_REFERENCE_PATTERN = re.compile(r"\A\$\{([^}]+)\}\Z")
+
+
+def to_sub_flow_caller(action, sub_flow):
+    """Wrap a sub flow value in an awaitable caller exposing its declared I/O schema."""
+
+    async def caller(*args):
+        return await action.execute_sub_flow(sub_flow, *args)
+
+    # Expose the sub flow's declared I/O so the handler can inspect it.
+    caller.input_schema = sub_flow.input_schema
+    caller.output_schema = sub_flow.output_schema
+    return caller
+
+
+def resolve_node_value(action, node):
+    """Resolve a single parameter node into a concrete value.
+
+    Literal values have their inline ``${signature}`` references substituted; sub
+    flows become awaitable callers. A missing node resolves to ``None``.
+    """
+    which = node.WhichOneof("value") if node is not None else None
+    if which == "literal_value":
+        return resolve_literal(action, node.literal_value)
+    if which == "sub_flow":
+        return to_sub_flow_caller(action, node.sub_flow)
+    return None
+
+
+def resolve_literal(action, literal):
+    """Resolve an ``ActionLiteralValue`` into a plain value.
+
+    A string that is exactly ``${signature}`` adopts the referenced value verbatim
+    (preserving its type); mixed strings interpolate the referenced value as text.
+    Unknown signatures are left untouched.
+    """
+    references = {}
+    for reference in literal.references:
+        references[reference.signature] = resolve_node_value(action, reference.value)
+    if literal.HasField("value"):
+        return _resolve_value(literal.value, references)
+    return None
+
+
+def _resolve_value(value: struct_pb2.Value, references: dict):
+    kind = value.WhichOneof("kind")
+    if kind == "string_value":
+        return _resolve_string(value.string_value, references)
+    if kind == "struct_value":
+        return {k: _resolve_value(v, references) for k, v in value.struct_value.fields.items()}
+    if kind == "list_value":
+        return [_resolve_value(v, references) for v in value.list_value.values]
+    # Numbers, booleans and null cannot carry placeholders.
+    return to_allowed_value(value)
+
+
+def _resolve_string(raw: str, references: dict):
+    sole = _SOLE_REFERENCE_PATTERN.match(raw)
+    if sole is not None:
+        signature = sole.group(1)
+        # Adopt the referenced value verbatim so its type (number, dict, sub flow, ...) is preserved.
+        return references[signature] if signature in references else raw
+
+    def replace(match: "re.Match[str]") -> str:
+        signature = match.group(1)
+        if signature in references:
+            return _stringify_reference(signature, references[signature])
+        return match.group(0)
+
+    return _REFERENCE_PATTERN.sub(replace, raw)
+
+
+def _stringify_reference(signature: str, value: Optional[PlainValue]) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if callable(value):
+        # A sub flow has no textual form, so it cannot be interpolated into a string.
+        raise RuntimeError(
+            "INLINE_REFERENCE_NOT_STRINGIFIABLE",
+            f"Inline reference ${{{signature}}} resolves to a sub flow and cannot be interpolated into a string",
+        )
+    if isinstance(value, bool):
+        # Match the cross-SDK textual form ("true"/"false"), not Python's "True"/"False".
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    # dict / list -> compact JSON, matching the TS ``JSON.stringify`` output.
+    return json.dumps(value, separators=(",", ":"))

hercules/internal/module_builder.py

@@ -0,0 +1,261 @@
+"""Module builder (port of ``src/internal/module-builder.ts``).
+
+Assembles the tucana ``shared.Module`` protobuf message from the registered
+definitions.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Union
+
+from hercules._tucana.helpers import construct_value
+from tucana.generated.shared import (
+    data_type_pb2,
+    flow_type_pb2,
+    function_pb2,
+    module_pb2,
+    runtime_flow_type_pb2,
+    runtime_function_pb2,
+    translation_pb2,
+)
+from hercules.models.datatype import DataTypeProps
+from hercules.models.event import EventModel
+from hercules.models.function import FunctionProps
+from hercules.models.runtime_event import RuntimeEventProps
+from hercules.models.runtime_function import RuntimeFunctionProps
+from hercules.types import ConfigurationDefinition, Translation
+
+_NONE = flow_type_pb2.FlowTypeSetting.UniquenessScope.NONE
+
+
+@dataclass
+class ModuleBuildData:
+    identifier: str
+    version: str
+    author: str
+    icon: str
+    documentation: str
+    name: List[Translation]
+    configuration_definitions: List[ConfigurationDefinition]
+    data_types: List[DataTypeProps]
+    events: List[EventModel]
+    runtime_events: List[RuntimeEventProps]
+    functions: List[FunctionProps]
+    runtime_functions: List[RuntimeFunctionProps]
+
+
+def _translations(items) -> List[translation_pb2.Translation]:
+    result = []
+    for item in items or []:
+        if isinstance(item, Translation):
+            result.append(translation_pb2.Translation(code=item.code, content=item.content))
+        elif isinstance(item, dict):
+            result.append(
+                translation_pb2.Translation(code=item["code"], content=item["content"])
+            )
+        else:
+            result.append(translation_pb2.Translation(code=item.code, content=item.content))
+    return result
+
+
+def _to_uniqueness_scope(unique: Optional[Union[int, str]]) -> int:
+    if unique is None:
+        return _NONE
+    if isinstance(unique, str):
+        scope = flow_type_pb2.FlowTypeSetting.UniquenessScope.Value(unique)
+        return scope
+    return unique
+
+
+def _config_def(def_: ConfigurationDefinition, version: str) -> module_pb2.ModuleConfigurationDefinition:
+    kwargs = dict(
+        identifier=def_.identifier,
+        name=_translations(def_.name),
+        description=_translations(def_.description),
+        type=def_.type,
+        linked_data_type_identifiers=def_.linked_data_types or [],
+        optional=def_.optional or False,
+        hidden=def_.hidden or False,
+    )
+    if def_.default_value is not None:
+        kwargs["default_value"] = construct_value(def_.default_value)
+    return module_pb2.ModuleConfigurationDefinition(**kwargs)
+
+
+def _data_type(dt: DataTypeProps, version: str) -> data_type_pb2.DefinitionDataType:
+    return data_type_pb2.DefinitionDataType(
+        identifier=dt.identifier,
+        name=_translations(dt.name),
+        alias=_translations(dt.alias),
+        rules=list(dt.rules or []),
+        generic_keys=list(dt.generic_keys or []),
+        type=dt.type,
+        linked_data_type_identifiers=[],
+        display_message=_translations(dt.display_message),
+        version=version,
+        definition_source="action",
+    )
+
+
+def _flow_type_setting(s, version: str) -> flow_type_pb2.FlowTypeSetting:
+    kwargs = dict(
+        identifier=s.identifier,
+        unique=_to_uniqueness_scope(s.unique),
+        name=_translations(s.name),
+        description=_translations(s.description),
+        optional=s.optional or False,
+        hidden=s.hidden or False,
+    )
+    if s.default_value is not None:
+        kwargs["default_value"] = construct_value(s.default_value)
+    return flow_type_pb2.FlowTypeSetting(**kwargs)
+
+
+def _flow_type(ft: EventModel, version: str) -> flow_type_pb2.FlowType:
+    return flow_type_pb2.FlowType(
+        identifier=ft.identifier,
+        settings=[_flow_type_setting(s, version) for s in (ft.settings or [])],
+        editable=ft.editable or False,
+        name=_translations(ft.name),
+        description=_translations(ft.description),
+        documentation=_translations(ft.documentation),
+        display_message=_translations(ft.display_message),
+        alias=_translations(ft.alias),
+        version=version,
+        display_icon=ft.display_icon or "tabler:note",
+        definition_source="action",
+        linked_data_type_identifiers=[],
+        signature=ft.signature,
+        runtime_identifier=ft.runtime_identifier or ft.identifier,
+    )
+
+
+def _runtime_flow_type_setting(s, version: str) -> runtime_flow_type_pb2.RuntimeFlowTypeSetting:
+    kwargs = dict(
+        identifier=s.identifier,
+        unique=_to_uniqueness_scope(s.unique),
+        name=_translations(s.name),
+        description=_translations(s.description),
+        optional=s.optional or False,
+        hidden=s.hidden or False,
+    )
+    if s.default_value is not None:
+        kwargs["default_value"] = construct_value(s.default_value)
+    return runtime_flow_type_pb2.RuntimeFlowTypeSetting(**kwargs)
+
+
+def _runtime_flow_type(rft: RuntimeEventProps, version: str) -> runtime_flow_type_pb2.RuntimeFlowType:
+    return runtime_flow_type_pb2.RuntimeFlowType(
+        identifier=rft.identifier,
+        runtime_settings=[_runtime_flow_type_setting(s, version) for s in (rft.settings or [])],
+        editable=rft.editable or False,
+        name=_translations(rft.name),
+        description=_translations(rft.description),
+        documentation=_translations(rft.documentation),
+        display_message=_translations(rft.display_message),
+        alias=_translations(rft.alias),
+        version=version,
+        display_icon=rft.display_icon or "tabler:note",
+        definition_source="action",
+        linked_data_type_identifiers=[],
+        signature=rft.signature,
+    )
+
+
+def _parameter_definition(p, version: str) -> function_pb2.ParameterDefinition:
+    kwargs = dict(
+        runtime_name=p.runtime_name,
+        runtime_definition_name=p.runtime_definition_name or p.runtime_name,
+        name=_translations(p.name),
+        description=_translations(p.description),
+        documentation=_translations(p.documentation),
+        hidden=p.hidden or False,
+        optional=p.optional or False,
+    )
+    if p.default_value is not None:
+        kwargs["default_value"] = construct_value(p.default_value)
+    return function_pb2.ParameterDefinition(**kwargs)
+
+
+def _function_definition(f: FunctionProps, version: str) -> function_pb2.FunctionDefinition:
+    kwargs = dict(
+        runtime_name=f.runtime_name,
+        runtime_definition_name=f.runtime_definition_name,
+        signature=f.signature,
+        throws_error=f.throws_error or False,
+        name=_translations(f.name),
+        description=_translations(f.description),
+        documentation=_translations(f.documentation),
+        deprecation_message=_translations(f.deprecation_message),
+        display_message=_translations(f.display_message),
+        alias=_translations(f.alias),
+        linked_data_type_identifiers=[],
+        display_icon=f.display_icon or "tabler:note",
+        version=version,
+        definition_source="action",
+        parameter_definitions=[_parameter_definition(p, version) for p in (f.parameters or [])],
+    )
+    if f.design is not None:
+        kwargs["design"] = f.design
+    return function_pb2.FunctionDefinition(**kwargs)
+
+
+def _runtime_parameter_definition(p, version: str) -> runtime_function_pb2.RuntimeParameterDefinition:
+    kwargs = dict(
+        runtime_name=p.runtime_name,
+        name=_translations(p.name),
+        description=_translations(p.description),
+        documentation=_translations(p.documentation),
+        hidden=p.hidden or False,
+        optional=p.optional or False,
+    )
+    if p.default_value is not None:
+        kwargs["default_value"] = construct_value(p.default_value)
+    return runtime_function_pb2.RuntimeParameterDefinition(**kwargs)
+
+
+def _runtime_function_definition(f: RuntimeFunctionProps, version: str) -> runtime_function_pb2.RuntimeFunctionDefinition:
+    kwargs = dict(
+        runtime_name=f.runtime_name,
+        signature=f.signature,
+        throws_error=f.throws_error or False,
+        name=_translations(f.name),
+        description=_translations(f.description),
+        documentation=_translations(f.documentation),
+        deprecation_message=_translations(f.deprecation_message),
+        display_message=_translations(f.display_message),
+        alias=_translations(f.alias),
+        linked_data_type_identifiers=[],
+        display_icon=f.display_icon or "tabler:note",
+        version=version,
+        definition_source="action",
+        runtime_parameter_definitions=[
+            _runtime_parameter_definition(p, version) for p in (f.parameters or [])
+        ],
+    )
+    if f.design is not None:
+        kwargs["design"] = f.design
+    return runtime_function_pb2.RuntimeFunctionDefinition(**kwargs)
+
+
+def build_module(data: ModuleBuildData) -> module_pb2.Module:
+    version = data.version
+    return module_pb2.Module(
+        identifier=data.identifier,
+        version=version,
+        author=data.author,
+        icon=data.icon,
+        documentation=data.documentation,
+        name=_translations(data.name),
+        description=[],
+        definition_source="action",
+        configurations=[_config_def(c, version) for c in data.configuration_definitions],
+        definition_data_types=[_data_type(dt, version) for dt in data.data_types],
+        flow_types=[_flow_type(ft, version) for ft in data.events],
+        runtime_flow_types=[_runtime_flow_type(rft, version) for rft in data.runtime_events],
+        function_definitions=[_function_definition(f, version) for f in data.functions],
+        runtime_function_definitions=[
+            _runtime_function_definition(f, version) for f in data.runtime_functions
+        ],
+        definitions=[],
+    )

hercules/internal/pydantic_codegen.py

@@ -0,0 +1,82 @@
+"""TypeScript type string -> Pydantic v2 model code.
+
+Pipeline:
+
+    TS type expression --(Node: ts-json-schema-generator)--> JSON schema
+                       --(datamodel-code-generator)--------> Pydantic v2 code
+
+``datamodel-code-generator`` does not parse TypeScript itself, so the TypeScript
+is first turned into a JSON schema by the bundled Node helper
+(:mod:`hercules.internal.tsgen`).
+
+Custom/referenced types that appear in the TypeScript (other data types) can be
+declared up front via ``preamble`` so the generator resolves them, e.g.
+``preamble="type CustomType = unknown;"``.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from hercules.internal.tsgen import ts_to_json_schema
+
+
+class PydanticCodegenError(RuntimeError):
+    """Raised when Pydantic code generation fails."""
+
+
+def _datamodel_codegen() -> str:
+    exe = shutil.which("datamodel-codegen")
+    if exe is None:
+        raise PydanticCodegenError(
+            "datamodel-code-generator is not installed. Install it with "
+            "'pip install datamodel-code-generator' (or the 'codegen' extra)."
+        )
+    return exe
+
+
+def ts_to_pydantic(
+    ts_type: str,
+    name: str,
+    *,
+    preamble: Optional[str] = None,
+    snake_case_fields: bool = False,
+) -> str:
+    """Convert a TypeScript type expression into Pydantic v2 model source code.
+
+    ``name`` becomes the root model's class name. Nested object types become
+    their own models; unions and custom references are preserved.
+    """
+    schema = ts_to_json_schema(ts_type, name, preamble)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        tmp_path = Path(tmp)
+        in_file = tmp_path / "schema.json"
+        out_file = tmp_path / "model.py"
+        in_file.write_text(json.dumps(schema))
+
+        cmd = [
+            _datamodel_codegen(),
+            "--input", str(in_file),
+            "--input-file-type", "jsonschema",
+            "--output", str(out_file),
+            "--output-model-type", "pydantic_v2.BaseModel",
+            "--class-name", name,
+            "--use-standard-collections",
+            "--use-union-operator",
+            "--disable-timestamp",
+            "--formatters", "black", "isort",
+        ]
+        if snake_case_fields:
+            cmd.append("--snake-case-field")
+
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            raise PydanticCodegenError(
+                result.stderr.strip() or "datamodel-code-generator failed."
+            )
+        return out_file.read_text()