code0-hercules 1.6.0__tar.gz → 1.7.0__tar.gz

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code0-hercules
-Version: 1.6.0
+Version: 1.7.0
 Summary: Python SDK for the hercules action runner
 License-Expression: MIT
 Project-URL: Repository, https://github.com/code0-tech/hercules
@@ -8,7 +8,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: grpcio>=1.64
 Requires-Dist: protobuf>=5.0
-Requires-Dist: tucana>=0.0.82
+Requires-Dist: tucana>=0.0.83
 Requires-Dist: pydantic>=2
 Provides-Extra: codegen
 Requires-Dist: datamodel-code-generator>=0.25; extra == "codegen"

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/code0_hercules.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code0-hercules
-Version: 1.6.0
+Version: 1.7.0
 Summary: Python SDK for the hercules action runner
 License-Expression: MIT
 Project-URL: Repository, https://github.com/code0-tech/hercules
@@ -8,7 +8,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: grpcio>=1.64
 Requires-Dist: protobuf>=5.0
-Requires-Dist: tucana>=0.0.82
+Requires-Dist: tucana>=0.0.83
 Requires-Dist: pydantic>=2
 Provides-Extra: codegen
 Requires-Dist: datamodel-code-generator>=0.25; extra == "codegen"

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/code0_hercules.egg-info/SOURCES.txt

@@ -238,6 +238,7 @@ hercules/internal/literal.py
 hercules/internal/module_builder.py
 hercules/internal/pydantic_codegen.py
 hercules/internal/schema.py
+hercules/internal/sub_flow_function.py
 hercules/internal/tsgen.py
 hercules/manager/__init__.py
 hercules/manager/base.py
@@ -248,6 +249,7 @@ hercules/manager/flow.py
 hercules/manager/function.py
 hercules/manager/runtime_event.py
 hercules/manager/runtime_function.py
+hercules/manager/sub_flow_function.py
 hercules/map/__init__.py
 hercules/map/datatype.py
 hercules/map/event.py
@@ -261,6 +263,7 @@ hercules/models/function.py
 hercules/models/runtime_event.py
 hercules/models/runtime_function.py
 tests/test_datatype.py
+tests/test_execution.py
 tests/test_export.py
 tests/test_index.py
 tests/test_literal.py

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/code0_hercules.egg-info/requires.txt

@@ -1,6 +1,6 @@
 grpcio>=1.64
 protobuf>=5.0
-tucana>=0.0.82
+tucana>=0.0.83
 pydantic>=2
 
 [codegen]

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/hercules/__init__.py

@@ -18,6 +18,8 @@ from hercules.types import (
     RuntimeError,
     RuntimeFlowTypeSetting_UniquenessScope,
     SubFlow,
+    SubFlowFunctionDefinition,
+    SubFlowFunctionSchema,
     Translation,
 )
 from hercules.events import CodeZeroEvent
@@ -55,6 +57,10 @@ from hercules.manager.flow import FlowManager
 from hercules.manager.function import FunctionManager
 from hercules.manager.runtime_event import RuntimeEventManager
 from hercules.manager.runtime_function import RuntimeFunctionManager
+from hercules.manager.sub_flow_function import (
+    SUB_FLOW_FUNCTION_TTL_SECONDS,
+    SubFlowFunctionManager,
+)
 from hercules.models.datatype import DataTypeProps, DataTypeRunnable
 from hercules.models.event import EventModel, EventSettingProps
 from hercules.models.function import FunctionParameterProps, FunctionProps
@@ -63,7 +69,8 @@ from hercules.models.runtime_function import RuntimeFunctionProps, RuntimeFuncti
 from hercules.action import Action, is_export_mode, registered_actions
 
 __all__ = [
-    "Translation", "PlainValue", "SubFlow", "FunctionContext",
+    "Translation", "PlainValue", "SubFlow", "SubFlowFunctionDefinition",
+    "SubFlowFunctionSchema", "FunctionContext",
     "ProjectConfiguration", "ConfigurationDefinition", "RuntimeError",
     "FlowTypeSetting_UniquenessScope", "RuntimeFlowTypeSetting_UniquenessScope",
     "CodeZeroEvent", "SchemaType",
@@ -73,7 +80,9 @@ __all__ = [
     "OmitFunction", "Design", "ThrowsError", "Parameter", "Schema", "TypeString",
     "EventSetting", "OmitEvent", "OmitRuntimeFunction",
     "BaseManager", "ConfigManager", "FlowManager", "FunctionManager",
-    "RuntimeFunctionManager", "DataTypeManager", "EventManager", "RuntimeEventManager",
+    "RuntimeFunctionManager", "SubFlowFunctionManager",
+    "SUB_FLOW_FUNCTION_TTL_SECONDS", "DataTypeManager",
+    "EventManager", "RuntimeEventManager",
     "FunctionProps", "FunctionParameterProps", "RuntimeFunctionProps",
     "RuntimeFunctionRunnable", "DataTypeProps", "DataTypeRunnable", "EventModel",
     "EventSettingProps", "RuntimeEventProps", "RuntimeEventRunnable",

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/hercules/action.py

@@ -22,6 +22,7 @@ from hercules.manager.flow import FlowManager
 from hercules.manager.function import FunctionManager
 from hercules.manager.runtime_event import RuntimeEventManager
 from hercules.manager.runtime_function import RuntimeFunctionManager
+from hercules.manager.sub_flow_function import SubFlowFunctionManager
 from hercules.map.datatype import data_type_map
 from hercules.map.event import event_map
 from hercules.map.function import function_map
@@ -29,7 +30,12 @@ from hercules.map.runtime_event import runtime_event_map
 from hercules.map.runtime_function import runtime_function_map
 from hercules.models.event import EventModel
 from hercules.models.function import FunctionProps
-from hercules.types import ConfigurationDefinition, RuntimeError, Translation
+from hercules.types import (
+    ConfigurationDefinition,
+    RuntimeError,
+    SubFlowFunctionDefinition,
+    Translation,
+)
 
 # Registry of actions constructed while exporting, so the CLI can find them.
 _REGISTERED_ACTIONS: List["Action"] = []
@@ -114,6 +120,7 @@ class Action(EventEmitter):
         self.flows = FlowManager()
         self.functions = FunctionManager()
         self.runtime_functions = RuntimeFunctionManager()
+        self.sub_flow_functions = SubFlowFunctionManager()
         self.data_types = DataTypeManager()
         self.events = EventManager()
         self.runtime_events = RuntimeEventManager()
@@ -165,6 +172,35 @@ class Action(EventEmitter):
                 ),
             )
 
+    def register_sub_flow_function(self, definition: SubFlowFunctionDefinition) -> str:
+        """Register a sub flow function returned from a ``run`` block.
+
+        Returns the identifier Aquila invokes it by. Each returned function gets its
+        own identifier, so repeatedly returning one (e.g. once per execution) never
+        overwrites a function a running flow still holds.
+
+        Aquila gives no signal that a flow is done with a function, so a registration
+        expires on its own 30 minutes after it was registered and can no longer be
+        invoked (see :class:`~hercules.manager.sub_flow_function.SubFlowFunctionManager`).
+        Call ``sub_flow_functions.delete(identifier)`` to drop one earlier.
+        """
+        identifier = f"{self._sub_flow_function_prefix}{definition.name}::{uuid.uuid4()}"
+        self.sub_flow_functions.set(identifier, definition)
+        return identifier
+
+    def is_sub_flow_function_identifier(self, identifier: str) -> bool:
+        """True for an identifier this action minted for a sub flow function.
+
+        Holds whether or not it is still registered. An execution request naming one
+        that is gone addresses a function that expired (or was deleted) rather than an
+        unknown one, which lets the execution handler report it as such.
+        """
+        return identifier.startswith(self._sub_flow_function_prefix)
+
+    @property
+    def _sub_flow_function_prefix(self) -> str:
+        return f"{self._identifier}::"
+
     def register_data_type_class(self, klass: type) -> None:
         definition = data_type_map(klass)
         self.data_types.set(definition.identifier, definition)

code0_hercules-1.7.0/hercules/actions/execution.py

@@ -0,0 +1,194 @@
+"""Execution request handler (port of ``src/actions/Execution.ts``)."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+from hercules._tucana.helpers import construct_value
+from tucana.generated.aquila import action_pb2
+from tucana.generated.shared import errors_pb2, execution_result_pb2
+from hercules.events import CodeZeroEvent
+from hercules.internal.literal import resolve_node_value
+from hercules.internal.sub_flow_function import (
+    as_sub_flow_function_definition,
+    build_sub_flow_function_result,
+)
+from hercules.types import ProjectConfiguration, RuntimeError
+
+packet_type = "execution"
+
+
+@dataclass
+class _ExecutionTarget:
+    """A function an execution request may address.
+
+    Either a registered runtime function or a sub flow function returned by one.
+    ``parameter_count`` is ``None`` for a sub flow function, which has no definition
+    declaring its parameters, so every parameter of the request is passed through.
+    """
+
+    handler: Callable[..., object]
+    parameter_count: Optional[int] = None
+
+
+def _now_micros() -> int:
+    return time.time_ns() // 1000
+
+
+def _resolve_target(action, identifier: str) -> Optional[_ExecutionTarget]:
+    func = action.runtime_functions.get(identifier)
+    if func is not None:
+        return _ExecutionTarget(func.handler, len(func.parameters or []))
+
+    sub_flow_function = action.sub_flow_functions.get(identifier)
+    if sub_flow_function is not None:
+        return _ExecutionTarget(sub_flow_function.run)
+
+    return None
+
+
+def _build_params(action, execution, target: _ExecutionTarget):
+    count = (
+        target.parameter_count
+        if target.parameter_count is not None
+        else len(execution.parameters)
+    )
+    params = []
+    for index in range(count):
+        field = execution.parameters[index] if index < len(execution.parameters) else None
+        params.append(resolve_node_value(action, field))
+    return params
+
+
+def _wants_context(handler, param_count: int) -> bool:
+    try:
+        sig = inspect.signature(handler)
+    except (TypeError, ValueError):
+        return False
+    positional = [
+        p
+        for p in sig.parameters.values()
+        if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    # A `*args` handler has no fixed positionals and never gets a context.
+    return len(positional) == param_count + 1
+
+
+def _to_node_value(action, value) -> execution_result_pb2.NodeValueExecutionResult:
+    """Wrap a handler's return value in a ``NodeValueExecutionResult``.
+
+    Raw data goes out as a value; a returned sub flow function is registered on the
+    action and reported as a ``SubFlowFunctionResult`` so the flow can invoke it later.
+    """
+    definition = as_sub_flow_function_definition(value)
+    if definition is not None:
+        return execution_result_pb2.NodeValueExecutionResult(
+            sub_flow_function_result=build_sub_flow_function_result(action, definition)
+        )
+    return execution_result_pb2.NodeValueExecutionResult(
+        raw_value=construct_value(value if value is not None else None)
+    )
+
+
+def handle(action, execution) -> None:
+    action.emit(CodeZeroEvent.execution_request_received, execution)
+
+    target = _resolve_target(action, execution.function_identifier)
+    if target is None:
+        if action.is_sub_flow_function_identifier(execution.function_identifier):
+            # A sub flow function this action returned earlier, whose maximum
+            # lifetime has passed (or which was deleted). Fail the node rather than
+            # staying silent, so the flow does not wait for a result that cannot come.
+            asyncio.ensure_future(
+                _send_error(
+                    action,
+                    execution,
+                    RuntimeError(
+                        "SUB_FLOW_FUNCTION_EXPIRED",
+                        f"Sub flow function {execution.function_identifier} is no "
+                        f"longer registered: its maximum lifetime has passed",
+                    ),
+                    _now_micros(),
+                )
+            )
+            return
+        print("Received execution request for unknown function:", execution.function_identifier)
+        return
+
+    params = _build_params(action, execution, target)
+
+    conf = action.configs.get(execution.project_id) or ProjectConfiguration(
+        project_id=0,
+        config_values=[],
+        find_config=lambda identifier: None,
+    )
+
+    from hercules.types import FunctionContext
+
+    context = FunctionContext(
+        project_id=execution.project_id,
+        execution_id=execution.execution_identifier,
+        matched_config=conf,
+        execute_flow=lambda flow_id, payload=None: action.execute_flow(flow_id, payload),
+    )
+
+    started_at = _now_micros()
+    handler = target.handler
+    all_params = (
+        [context, *params] if _wants_context(handler, len(params)) else params
+    )
+
+    asyncio.ensure_future(_run(action, execution, handler, all_params, started_at))
+
+
+async def _run(action, execution, handler, all_params, started_at) -> None:
+    try:
+        value = handler(*all_params)
+        if inspect.isawaitable(value):
+            value = await value
+        finished_at = _now_micros()
+        request = action_pb2.ActionTransferRequest(
+            result=action_pb2.ActionExecutionResponse(
+                execution_identifier=execution.execution_identifier,
+                node_result=execution_result_pb2.NodeExecutionResult(
+                    started_at=started_at,
+                    finished_at=finished_at,
+                    parameter_results=[],
+                    success=_to_node_value(action, value),
+                ),
+            )
+        )
+        await action.send(request)
+    except Exception as error:  # noqa: BLE001
+        await _send_error(action, execution, error, started_at)
+
+
+async def _send_error(action, execution, error, started_at) -> None:
+    """Report a failed execution back to Aquila."""
+    finished_at = _now_micros()
+    is_runtime_error = isinstance(error, RuntimeError)
+    proto_error = errors_pb2.Error(
+        code=error.code if is_runtime_error else "UNKNOWN_ERROR",
+        category="RUNTIME",
+        message=(error.description or str(error)) if is_runtime_error else str(error),
+        timestamp=finished_at,
+        version=action.version,
+    )
+    request = action_pb2.ActionTransferRequest(
+        result=action_pb2.ActionExecutionResponse(
+            execution_identifier=execution.execution_identifier,
+            node_result=execution_result_pb2.NodeExecutionResult(
+                started_at=started_at,
+                finished_at=finished_at,
+                parameter_results=[],
+                error=proto_error,
+            ),
+        )
+    )
+    try:
+        await action.send(request)
+    except Exception as err:  # noqa: BLE001
+        print("Failed to send execution error:", err)

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/hercules/internal/schema.py

@@ -133,6 +133,16 @@ def pydantic_to_type_string(model: SchemaModel) -> str:
     return json_schema_to_ts(resolved, name)
 
 
+def pydantic_to_json_schema(model: SchemaModel, mode: str) -> Dict[str, Any]:
+    """Convert a Pydantic model into a plain JSON schema dict.
+
+    ``mode`` picks which side of the model is described: ``"validation"`` for the
+    input it accepts, ``"serialization"`` for the output it produces (the Python
+    counterpart of the TypeScript SDK's zod ``io`` option).
+    """
+    return model.model_json_schema(mode=mode)
+
+
 def pydantic_to_rules(model: SchemaModel) -> List[data_type_pb2.DefinitionDataTypeRule]:
     schema = model.model_json_schema()
     rules: List[data_type_pb2.DefinitionDataTypeRule] = []

code0_hercules-1.7.0/hercules/internal/sub_flow_function.py

@@ -0,0 +1,86 @@
+"""Sub flow function support (port of ``src/internal/sub-flow-function.ts``).
+
+A runtime function's ``run`` may return a sub flow function instead of raw data.
+Hercules registers it on the action and reports it to Aquila as a
+``shared.SubFlowFunctionResult``, which the flow can then invoke like any sub flow.
+"""
+from __future__ import annotations
+
+from typing import Mapping, Optional
+
+from pydantic import BaseModel
+
+from hercules._tucana.helpers import construct_value
+from hercules.internal.schema import pydantic_to_json_schema
+from hercules.types import (
+    RuntimeError,
+    SubFlowFunctionDefinition,
+    SubFlowFunctionSchema,
+)
+from tucana.generated.shared import execution_result_pb2, flow_pb2, struct_pb2
+
+__all__ = ["as_sub_flow_function_definition", "build_sub_flow_function_result", "to_struct"]
+
+
+def as_sub_flow_function_definition(value) -> Optional[SubFlowFunctionDefinition]:
+    """Return ``value`` as a definition if ``run`` returned a sub flow function.
+
+    A sub flow function is told apart from raw data by its callable ``run``, which a
+    plain value never carries. Both a :class:`SubFlowFunctionDefinition` and a plain
+    mapping with the same keys are accepted.
+    """
+    if isinstance(value, SubFlowFunctionDefinition):
+        return value
+    if isinstance(value, Mapping) and callable(value.get("run")):
+        return SubFlowFunctionDefinition(
+            name=value.get("name"),
+            description=value.get("description") or "",
+            input_schema=value.get("input_schema") or {},
+            output_schema=value.get("output_schema") or {},
+            run=value["run"],
+        )
+    return None
+
+
+def _is_model(schema) -> bool:
+    return isinstance(schema, type) and issubclass(schema, BaseModel)
+
+
+def to_struct(schema: Optional[SubFlowFunctionSchema], mode: str) -> struct_pb2.Struct:
+    """Convert a declared schema into the ``shared.Struct`` the protobuf field expects.
+
+    A Pydantic model becomes a JSON schema first: ``mode`` is ``"validation"`` for a
+    function's input schema (what it accepts) and ``"serialization"`` for its output
+    schema (what it produces).
+    """
+    if isinstance(schema, struct_pb2.Struct):
+        return schema
+    if _is_model(schema):
+        return construct_value(pydantic_to_json_schema(schema, mode)).struct_value
+    return construct_value(schema or {}).struct_value
+
+
+def build_sub_flow_function_result(
+    action, definition: SubFlowFunctionDefinition
+) -> execution_result_pb2.SubFlowFunctionResult:
+    """Register the sub flow function and build the result reported back to Aquila.
+
+    The identifier in the result is the one Aquila sends back on an execution request
+    when the flow invokes the function.
+    """
+    if not definition.name:
+        raise RuntimeError(
+            "SUB_FLOW_FUNCTION_MISSING_NAME",
+            "A sub flow function returned from a run block must declare a name",
+        )
+    function_identifier = action.register_sub_flow_function(definition)
+    return execution_result_pb2.SubFlowFunctionResult(
+        function=flow_pb2.SubFlowFunction(
+            function_identifier=function_identifier,
+            definition_source="action",
+        ),
+        name=definition.name,
+        description=definition.description or "",
+        input_schema=to_struct(definition.input_schema, "validation"),
+        output_schema=to_struct(definition.output_schema, "serialization"),
+    )

code0_hercules-1.7.0/hercules/manager/sub_flow_function.py

@@ -0,0 +1,93 @@
+"""Sub flow function manager (port of ``src/manager/SubFlowFunctionManager.ts``)."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Dict, Optional
+
+from hercules.manager.base import BaseManager
+
+#: How long a returned sub flow function stays in memory and invocable: 30 minutes.
+SUB_FLOW_FUNCTION_TTL_SECONDS = 30 * 60
+
+
+class SubFlowFunctionManager(BaseManager):
+    """Sub flow functions a runtime function returned at execution time.
+
+    Keyed by the identifier reported to Aquila. Unlike the other managers this one is
+    not filled by registering classes up front: entries appear while the action runs
+    (see :meth:`hercules.action.Action.register_sub_flow_function`).
+
+    Each entry has a maximum lifetime of :data:`SUB_FLOW_FUNCTION_TTL_SECONDS`,
+    counted from when it was registered and never extended by an invocation, so a flow
+    that holds a function forever cannot grow the registry without bound. Expired
+    entries are dropped by a sweep scheduled for the next expiry, and on any read or
+    write, so an expired function is never invoked even if the sweep could not run
+    (there is no running event loop to schedule it on, for instance).
+    """
+
+    def __init__(self, ttl_seconds: float = SUB_FLOW_FUNCTION_TTL_SECONDS) -> None:
+        super().__init__()
+        self._ttl_seconds = ttl_seconds
+        # Expiry per key. Insertion order is expiry order, since the TTL is fixed.
+        self._expiries: Dict[str, float] = {}
+        self._sweep_handle: Optional[asyncio.TimerHandle] = None
+
+    @staticmethod
+    def _now() -> float:
+        # Monotonic, so a system clock change cannot postpone or trigger an expiry.
+        return time.monotonic()
+
+    def set(self, key, value):
+        # Re-insert the expiry so a replaced key moves to the back and the dict stays
+        # ordered by expiry.
+        self._expiries.pop(key, None)
+        super().set(key, value)
+        self._expiries[key] = self._now() + self._ttl_seconds
+        self.prune()
+        return self
+
+    def get(self, key):
+        self.prune()
+        return super().get(key)
+
+    def has(self, key) -> bool:
+        self.prune()
+        return super().has(key)
+
+    def delete(self, key) -> bool:
+        self._expiries.pop(key, None)
+        deleted = super().delete(key)
+        self._schedule_sweep(self._now())
+        return deleted
+
+    def clear(self) -> None:
+        self._expiries.clear()
+        super().clear()
+        self._schedule_sweep(self._now())
+
+    def prune(self, now: Optional[float] = None) -> None:
+        """Drop every entry whose lifetime has passed, then schedule the next sweep."""
+        if now is None:
+            now = self._now()
+        for key, expires_at in list(self._expiries.items()):
+            # Ordered by expiry, so the first entry still alive ends the sweep.
+            if expires_at > now:
+                break
+            del self._expiries[key]
+            super().delete(key)
+        self._schedule_sweep(now)
+
+    def _schedule_sweep(self, now: float) -> None:
+        if self._sweep_handle is not None:
+            self._sweep_handle.cancel()
+            self._sweep_handle = None
+        next_expiry = next(iter(self._expiries.values()), None)
+        if next_expiry is None:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            # No loop to schedule on; pruning on the next read or write still applies.
+            return
+        self._sweep_handle = loop.call_later(max(0.0, next_expiry - now), self.prune)

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/hercules/models/runtime_function.py

@@ -2,11 +2,16 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Callable, List, Optional
+from typing import Callable, List, Optional, Union
 
 from hercules._tucana.helpers import PlainValue
 from hercules.models.function import FunctionParameterProps
-from hercules.types import Translation
+from hercules.types import SubFlowFunctionDefinition, Translation
+
+#: What a runtime function's ``run`` may produce: raw data, or a
+#: :class:`~hercules.types.SubFlowFunctionDefinition` that Hercules registers and
+#: reports to Aquila as a ``shared.SubFlowFunctionResult``.
+RuntimeFunctionReturn = Union[PlainValue, SubFlowFunctionDefinition]
 
 
 class RuntimeFunctionRunnable:
@@ -20,7 +25,7 @@ class RuntimeFunctionRunnable:
 class RuntimeFunctionProps:
     runtime_name: str
     signature: str
-    handler: Callable[..., PlainValue]
+    handler: Callable[..., RuntimeFunctionReturn]
     parameters: Optional[List[FunctionParameterProps]] = None
     throws_error: Optional[bool] = None
     name: Optional[List[Translation]] = None

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/hercules/types.py

@@ -2,7 +2,9 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Awaitable, Callable, List, Optional, Protocol, Union
+from typing import Any, Awaitable, Callable, List, Optional, Protocol, Type, Union
+
+from pydantic import BaseModel
 
 from hercules._tucana.helpers import PlainValue
 from tucana.generated.shared.flow_type_pb2 import FlowTypeSetting
@@ -20,6 +22,8 @@ __all__ = [
     "RuntimeFlowTypeSetting_UniquenessScope",
     "Translation",
     "SubFlow",
+    "SubFlowFunctionSchema",
+    "SubFlowFunctionDefinition",
     "FunctionContext",
     "ProjectConfiguration",
     "ConfigurationDefinition",
@@ -48,6 +52,40 @@ class SubFlow(Protocol):
     def __call__(self, *args: PlainValue) -> Awaitable[PlainValue]: ...
 
 
+#: Describes a sub flow function's input or output. Normally a Pydantic model, which
+#: is converted to a JSON schema while the result is sent (the counterpart of the
+#: TypeScript SDK's zod schemas). A plain JSON schema dict or a ready-made ``Struct``
+#: (e.g. one taken from a :class:`SubFlow`) is passed through unchanged.
+SubFlowFunctionSchema = Union[Type[BaseModel], Struct, dict]
+
+
+@dataclass
+class SubFlowFunctionDefinition:
+    """A sub flow function returned from a runtime function's ``run`` in place of raw data.
+
+    Hercules registers :attr:`run` internally and reports the function to Aquila as a
+    ``shared.SubFlowFunctionResult``, so the flow can invoke it later like any other
+    sub flow. Name, description and I/O schema have to be declared here, because
+    nothing in the action's module definition describes a function created at runtime.
+
+    May also be returned as a plain dict with the same keys::
+
+        return SubFlowFunctionDefinition(
+            name="greet",
+            description="Greets a name",
+            input_schema=GreetInput,
+            output_schema=GreetOutput,
+            run=lambda name: f"Hello {name}",
+        )
+    """
+
+    name: str
+    description: str
+    input_schema: SubFlowFunctionSchema
+    output_schema: SubFlowFunctionSchema
+    run: Callable[..., Any]
+
+
 @dataclass
 class ProjectConfiguration:
     project_id: int

{code0_hercules-1.6.0 → code0_hercules-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code0-hercules"
-version = "1.6.0"
+version = "1.7.0"
 description = "Python SDK for the hercules action runner"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ license = "MIT"
 dependencies = [
     "grpcio>=1.64",
     "protobuf>=5.0",
-    "tucana>=0.0.82",
+    "tucana>=0.0.83",
     "pydantic>=2",
 ]