horus-runtime 0.1.0__py3-none-any.whl

horus_builtin/__init__.py

@@ -0,0 +1,17 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#

horus_builtin/artifact/__init__.py

@@ -0,0 +1,17 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#

horus_builtin/artifact/file.py

@@ -0,0 +1,51 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Implementation of the FileArtifact class, which represents a local
+file artifact in the Horus runtime.
+"""
+
+from horus_builtin.event.artifact_event import ArtifactEventsEnum
+from horus_runtime.core.artifact.base import BaseArtifact
+
+
+class FileArtifact(BaseArtifact[str]):
+    """
+    Represents a local file artifact.
+    """
+
+    kind: str = "file"
+
+    def read(self) -> str:
+        """
+        Read and deserialize the contents of the file artifact.
+
+        Returns:
+            The full text content of the file.
+        """
+        txt = self.path.read_text()
+        self._emit_event(ArtifactEventsEnum.READ)
+        return txt
+
+    def write(self, value: str) -> None:
+        """
+        Write text content to the file artifact path.
+        """
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(value)
+        self._emit_event(ArtifactEventsEnum.WRITE)

horus_builtin/artifact/folder.py

@@ -0,0 +1,153 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Implementation of the FolderArtifact class, which represents a local
+folder/directory artifact in the Horus runtime.
+"""
+
+import hashlib
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from horus_builtin.event.artifact_event import ArtifactEventsEnum
+from horus_runtime.core.artifact.base import BaseArtifact
+from horus_runtime.i18n import tr as _
+
+
+class FolderArtifact(BaseArtifact[Path]):
+    """
+    Represents a local folder artifact.
+    """
+
+    kind: str = "folder"
+
+    def exists(self) -> bool:
+        """
+        Check if the folder specified by the path exists and is a directory.
+        """
+        return self.path.is_dir()
+
+    @property
+    def hash(self) -> str | None:
+        """
+        Computes the hash of the folder and its contents by recursively hashing
+        all files in the folder. The hash is computed by combining the relative
+        paths and contents of all files in the folder, ensuring that changes to
+        any file or the addition/removal of files will result in a different
+        hash.
+        """
+        if not self.exists():
+            return None
+
+        sha256 = hashlib.sha256()
+
+        # 1. Get all files and sort them by relative path for determinism
+        # We use rglob("*") to get everything, but only hash files
+        paths = sorted([p for p in self.path.rglob("*") if p.is_file()])
+
+        for path in paths:
+            relative_path = path.relative_to(self.path).as_posix()
+            sha256.update(relative_path.encode("utf-8"))
+
+            # Hash the file contents
+            sha256.update(self.hash_file(path))
+
+        return sha256.hexdigest()
+
+    def read(self) -> Path:
+        """
+        Return the canonical directory path for this artifact.
+        """
+        self._emit_event(ArtifactEventsEnum.READ)
+        return self.path
+
+    def write(self, value: Path) -> None:
+        """
+        Materialize this folder artifact from another local directory.
+
+        WARNING: THIS WILL OVERWRITE ANY EXISTING CONTENT AT THE ARTIFACT PATH.
+        """
+        source_path = Path(value).resolve()
+        if not source_path.is_dir():
+            raise ValueError(
+                _("Expected directory path, got %(source_path)s")
+                % {"source_path": source_path}
+            )
+
+        if self.path.exists():
+            shutil.rmtree(self.path)
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copytree(source_path, self.path)
+        self._emit_event(ArtifactEventsEnum.WRITE)
+
+    def package(self) -> Path:
+        """
+        Archive the folder into a zip file and return the archive path.
+        """
+        if not self.exists():
+            raise FileNotFoundError(self.path)
+
+        # Create a temporary file to be used as the archive path.
+        # shutil.make_archive requires a base name without extension,
+        # so we create a temp file and then remove it after archiving.
+        fd, arch_p = tempfile.mkstemp()
+        os.close(fd)
+        archive_path = Path(arch_p)
+
+        shutil.make_archive(
+            base_name=str(archive_path),
+            format="zip",
+            root_dir=self.path,
+        )
+
+        # shutil.make_archive adds .zip, so remove the temp
+        # file and use the generated archive
+        archive_file = archive_path.with_suffix(".zip")
+        if archive_path.exists():
+            archive_path.unlink()
+
+        self._emit_event(ArtifactEventsEnum.PACKAGE)
+        return archive_file
+
+    def unpackage(self, package_path: Path) -> None:
+        """
+        Extract a packaged folder archive into the canonical directory path.
+        """
+        package_path = Path(package_path).resolve()
+
+        if self.path.exists():
+            shutil.rmtree(self.path)
+
+        self.path.mkdir(parents=True, exist_ok=True)
+        shutil.unpack_archive(
+            filename=str(package_path),
+            extract_dir=str(self.path),
+        )
+        self._emit_event(ArtifactEventsEnum.UNPACKAGE)
+
+    def delete(self) -> None:
+        """
+        Deletes the artifact from its location by deleting the folder at the
+        specified path.
+        """
+        if self.exists():
+            shutil.rmtree(self.path)
+            self._emit_event(ArtifactEventsEnum.DELETE)

horus_builtin/artifact/json.py

@@ -0,0 +1,59 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Implementation of the FolderArtifact class, which represents a local
+folder/directory artifact in the Horus runtime.
+"""
+
+import json
+from typing import Any, cast
+
+from horus_builtin.event.artifact_event import ArtifactEventsEnum
+from horus_runtime.core.artifact.base import BaseArtifact
+
+
+class JSONArtifact[T: Any = Any](BaseArtifact[T]):
+    """
+    Represents a JSON-serializable Python object artifact.
+    The artifact is materialized as a JSON file on disk.
+    """
+
+    kind: str = "json"
+
+    def read(self) -> T:
+        """
+        Read and deserialize the JSON artifact contents.
+
+        Warning: This method assumes that the JSON file is well-formed and that
+        the contents can be deserialized into the expected type `T`. For more
+        robust handling, consider using PydanticArtifact, which provides
+        validation and error handling for deserialization.
+        """
+        with open(self.path) as f:
+            j_contet = json.load(f)
+        self._emit_event(ArtifactEventsEnum.READ)
+
+        return cast(T, j_contet)
+
+    def write(self, value: T) -> None:
+        """
+        Serialize and write the JSON artifact contents.
+        """
+        with open(self.path, "w") as f:
+            json.dump(value, f)
+        self._emit_event(ArtifactEventsEnum.WRITE)

horus_builtin/artifact/pickle.py

@@ -0,0 +1,56 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Implementation of PickleArtifact, which serializes arbitrary Python objects
+to disk using the pickle protocol.
+"""
+
+import pickle
+from typing import Any, cast
+
+from horus_builtin.event.artifact_event import ArtifactEventsEnum
+from horus_runtime.core.artifact.base import BaseArtifact
+
+
+class PickleArtifact[T: Any = Any](BaseArtifact[T]):
+    """
+    Represents a pickled Python object artifact.
+    The artifact is materialized as a pickle file on disk.
+
+    Warning: pickle is not secure against malformed or maliciously crafted
+    data. Never unpickle data from untrusted sources.
+    """
+
+    kind: str = "pickle"
+
+    def read(self) -> T:
+        """
+        Deserialize the artifact from the pickle file.
+        """
+        with open(self.path, "rb") as f:
+            obj = pickle.load(f)
+        self._emit_event(ArtifactEventsEnum.READ)
+        return cast(T, obj)
+
+    def write(self, value: T) -> None:
+        """
+        Serialize and write the object to the pickle file.
+        """
+        with open(self.path, "wb") as f:
+            pickle.dump(value, f)
+        self._emit_event(ArtifactEventsEnum.WRITE)

horus_builtin/event/__init__.py

@@ -0,0 +1,17 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#

horus_builtin/event/artifact_event.py

@@ -0,0 +1,48 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+ArtifactEvent. Emitted when an artifact is created, updated, or deleted.
+"""
+
+from enum import Enum
+from typing import ClassVar
+
+from horus_runtime.event.base import BaseEvent
+
+
+class ArtifactEventsEnum(Enum):
+    """
+    Standard artifact events.
+    """
+
+    DELETE = "deleted"
+    PACKAGE = "packaged"
+    UNPACKAGE = "unpackaged"
+    READ = "read"
+    WRITE = "written"
+
+
+class ArtifactEvent(BaseEvent):
+    """
+    Event emitted when an artifact is created, updated, or deleted.
+    """
+
+    add_to_registry: ClassVar[bool] = True
+    event_type: str = "artifact_event"
+    event_name: ArtifactEventsEnum
+    artifact_id: str

horus_builtin/event/log_subscriber.py

@@ -0,0 +1,54 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Logging subscriber for horus-runtime events.
+"""
+
+from horus_runtime.event.base import BaseEvent
+from horus_runtime.event.subscriber import BaseEventSubscriber
+from horus_runtime.logging import horus_logger
+
+
+class LogsSubscriber(BaseEventSubscriber):
+    """
+    A simple event subscriber that logs all events using loguru.
+    """
+
+    subscriber_type: str = "loguru"
+
+    def setup(self) -> None:
+        """
+        No setup needed for this subscriber.
+        """
+        pass
+
+    def handle(self, event: BaseEvent) -> None:
+        """
+        Handle an incoming event by logging it using loguru's bind.
+        """
+        # Secure the message by escaping any potential markup characters
+        safe_message = (event.message or "").replace("<", r"\<")
+
+        horus_logger.log.opt(colors=True).log(
+            event.level,
+            "<cyan>[{source}]</cyan> <yellow>[{event_type}]</yellow> "
+            "{safe_message}",
+            source=event.source,
+            event_type=event.event_type,
+            safe_message=safe_message,
+        )

horus_builtin/event/task_event.py

@@ -0,0 +1,33 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+HorusTaskEvent. Emitted when a HorusTask is executed.
+"""
+
+from horus_runtime.event.base import BaseEvent
+
+
+class HorusTaskEvent(BaseEvent):
+    """
+    Event emitted when a HorusTask is executed.
+    """
+
+    event_type: str = "horus_task_event"
+
+    task_id: str | None = None
+    task_name: str

horus_builtin/event/workflow_event.py

@@ -0,0 +1,32 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+HorusTaskEvent. Emitted when a HorusTask is executed.
+"""
+
+from horus_runtime.event.base import BaseEvent
+
+
+class HorusWorkflowEvent(BaseEvent):
+    """
+    Event emitted when a HorusWorkflow is executed.
+    """
+
+    event_type: str = "horus_workflow_event"
+
+    workflow_name: str

horus_builtin/executor/__init__.py

@@ -0,0 +1,17 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#

horus_builtin/executor/python_exec.py

@@ -0,0 +1,64 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Defines the PythonExecExecutor class, which represents an executor that runs a
+a Python code task in-process in the Horus runtime.
+"""
+
+from typing import TYPE_CHECKING, ClassVar
+
+from horus_builtin.runtime.python_string import PythonCodeStringRuntime
+from horus_runtime.context import HorusContext
+from horus_runtime.core.executor.base import BaseExecutor, RuntimeFilterType
+from horus_runtime.i18n import tr as _
+
+if TYPE_CHECKING:
+    from horus_runtime.core.task.base import BaseTask
+
+
+class PythonExecExecutor(BaseExecutor):
+    """
+    Run the tasks locally in the horus-runtime instance.
+    """
+
+    kind: str = "python"
+    kind_name: ClassVar[str] = "Python Exec"
+    kind_description: ClassVar[str] = _(
+        "Executes a Python code snippet in-process within the Horus runtime."
+    )
+
+    runtimes: ClassVar[RuntimeFilterType] = (PythonCodeStringRuntime,)
+
+    async def _execute(self, task: "BaseTask") -> None:
+        """
+        Runs the task in-process by executing the Python code specified in the
+        task's runtime.
+        """
+        assert isinstance(task.runtime, PythonCodeStringRuntime)
+        code = await task.runtime.setup_runtime(task)
+
+        ctx = HorusContext.get_context()
+
+        scope = {
+            "ctx": ctx,
+            "task": task,
+        }
+
+        # Security Warning: using exec to execute arbitrary code can be
+        # dangerous and should be done with caution.
+        exec(code, scope)

horus_builtin/executor/python_fn.py

@@ -0,0 +1,57 @@
+#
+# horus-runtime
+# Copyright (C) 2026 Temple Compute
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+"""
+Python executor for in-memory workflows in horus-runtime. (Function
+executor).
+"""
+
+from inspect import isawaitable
+from typing import ClassVar
+
+from horus_builtin.runtime.python import PythonFunctionRuntime
+from horus_runtime.core.executor.base import BaseExecutor, RuntimeFilterType
+from horus_runtime.core.task.base import BaseTask
+from horus_runtime.i18n import tr as _
+
+
+class PythonFunctionExecutor(BaseExecutor):
+    """
+    Executor for running Python functions in-memory.
+    """
+
+    kind: str = "python_function"
+    kind_name: ClassVar[str] = "Python Function Executor"
+    kind_description: ClassVar[str] = _(
+        "Executes a Python function in-memory within the Horus runtime."
+    )
+
+    runtimes: ClassVar[RuntimeFilterType] = (PythonFunctionRuntime,)
+
+    async def _execute(self, task: "BaseTask") -> None:
+        """
+        Executes the Python function specified in the task's runtime.
+        """
+        assert isinstance(task.runtime, PythonFunctionRuntime)
+
+        # Get the function and resolved arguments from the runtime.
+        func, args = await task.runtime.setup_runtime(task)
+
+        result = func(**args)
+
+        if isawaitable(result):
+            await result