donna 0.2.0__py3-none-any.whl

donna/primitives/operations/run_script.py

@@ -0,0 +1,250 @@
+import os
+import subprocess  # noqa: S404
+import tempfile
+from typing import TYPE_CHECKING, ClassVar, Iterator, cast
+
+import pydantic
+
+from donna.core import errors as core_errors
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result
+from donna.domain.ids import ArtifactSectionId, FullArtifactId
+from donna.machine.artifacts import Artifact, ArtifactSection, ArtifactSectionConfig, ArtifactSectionMeta
+from donna.machine.errors import ArtifactValidationError
+from donna.machine.operations import OperationConfig, OperationKind, OperationMeta
+from donna.world import markdown
+from donna.world.sources.markdown import MarkdownSectionMixin
+
+if TYPE_CHECKING:
+    from donna.machine.changes import Change
+    from donna.machine.tasks import Task, WorkUnit
+
+
+class InternalError(core_errors.InternalError):
+    """Base class for internal errors in donna.primitives.operations.run_script."""
+
+
+class RunScriptMissingGotoOnSuccess(ArtifactValidationError):
+    code: str = "donna.workflows.run_script_missing_goto_on_success"
+    message: str = "Run script operation `{error.section_id}` must define `goto_on_success`."
+    ways_to_fix: list[str] = [
+        'Add `goto_on_success = "<next_operation_id>"` to the operation config block.',
+    ]
+
+
+class RunScriptMissingGotoOnFailure(ArtifactValidationError):
+    code: str = "donna.workflows.run_script_missing_goto_on_failure"
+    message: str = "Run script operation `{error.section_id}` must define `goto_on_failure`."
+    ways_to_fix: list[str] = [
+        'Add `goto_on_failure = "<next_operation_id>"` to the operation config block.',
+    ]
+
+
+class RunScriptMissingScriptBlock(ArtifactValidationError):
+    code: str = "donna.workflows.run_script_missing_script_block"
+    message: str = "Run script operation `{error.section_id}` must include a single `donna script` code block."
+    ways_to_fix: list[str] = [
+        "Add exactly one fenced code block starting with ` ``` donna script ` in the operation body.",
+    ]
+
+
+class RunScriptMultipleScriptBlocks(ArtifactValidationError):
+    code: str = "donna.workflows.run_script_multiple_script_blocks"
+    message: str = "Run script operation `{error.section_id}` must include exactly one `donna script` code block."
+    ways_to_fix: list[str] = [
+        "Remove extra `donna script` code blocks so only one remains in the operation body.",
+    ]
+
+
+class RunScriptGotoOnCodeIncludesZero(ArtifactValidationError):
+    code: str = "donna.workflows.run_script_goto_on_code_includes_zero"
+    message: str = "Run script operation `{error.section_id}` must not map exit code 0 in `goto_on_code`."
+    ways_to_fix: list[str] = [
+        "Remove the `0` entry from `goto_on_code` and use `goto_on_success` instead.",
+    ]
+
+
+class RunScriptInvalidExitCode(ArtifactValidationError):
+    code: str = "donna.workflows.run_script_invalid_exit_code"
+    message: str = "Run script operation `{error.section_id}` has invalid exit code `{error.exit_code}`."
+    ways_to_fix: list[str] = [
+        'Use integer exit code keys in `goto_on_code` (e.g., `"1" = "next_op"`).',
+    ]
+    exit_code: str
+
+
+class RunScriptConfig(OperationConfig):
+    save_stdout_to: str | None = None
+    save_stderr_to: str | None = None
+    goto_on_success: ArtifactSectionId | None = None
+    goto_on_failure: ArtifactSectionId | None = None
+    goto_on_code: dict[str, ArtifactSectionId] = pydantic.Field(default_factory=dict)
+    timeout: int = 60
+
+
+class RunScriptMeta(OperationMeta):
+    script: str | None = None
+    save_stdout_to: str | None = None
+    save_stderr_to: str | None = None
+    goto_on_success: ArtifactSectionId | None = None
+    goto_on_failure: ArtifactSectionId | None = None
+    goto_on_code: dict[str, ArtifactSectionId] = pydantic.Field(default_factory=dict)
+    timeout: int = 60
+
+    def select_next_operation(self, exit_code: int) -> ArtifactSectionId:
+        if exit_code == 0:
+            next_operation = self.goto_on_success
+        else:
+            next_operation = self.goto_on_code.get(str(exit_code))
+            if next_operation is None:
+                next_operation = self.goto_on_failure
+
+        assert next_operation is not None
+        return next_operation
+
+
+class RunScript(MarkdownSectionMixin, OperationKind):
+    config_class: ClassVar[type[RunScriptConfig]] = RunScriptConfig
+
+    def markdown_construct_meta(
+        self,
+        artifact_id: "FullArtifactId",
+        source: markdown.SectionSource,
+        section_config: ArtifactSectionConfig,
+        description: str,
+        primary: bool = False,
+    ) -> Result[ArtifactSectionMeta, ErrorsList]:
+        run_config = cast(RunScriptConfig, section_config)
+        scripts = source.scripts()
+        if not scripts:
+            return Err([RunScriptMissingScriptBlock(artifact_id=artifact_id, section_id=run_config.id)])
+        if len(scripts) > 1:
+            return Err([RunScriptMultipleScriptBlocks(artifact_id=artifact_id, section_id=run_config.id)])
+
+        script = scripts[0]
+        allowed_transitions: set[ArtifactSectionId] = set()
+
+        if run_config.goto_on_success is not None:
+            allowed_transitions.add(run_config.goto_on_success)
+
+        if run_config.goto_on_failure is not None:
+            allowed_transitions.add(run_config.goto_on_failure)
+
+        if run_config.goto_on_code:
+            allowed_transitions.update(run_config.goto_on_code.values())
+
+        return Ok(
+            RunScriptMeta(
+                fsm_mode=run_config.fsm_mode,
+                allowed_transtions=allowed_transitions,
+                script=script,
+                save_stdout_to=run_config.save_stdout_to,
+                save_stderr_to=run_config.save_stderr_to,
+                goto_on_success=run_config.goto_on_success,
+                goto_on_failure=run_config.goto_on_failure,
+                goto_on_code=dict(run_config.goto_on_code),
+                timeout=run_config.timeout,
+            )
+        )
+
+    def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
+        from donna.machine.changes import ChangeAddWorkUnit, ChangeSetTaskContext
+
+        meta = cast(RunScriptMeta, operation.meta)
+
+        script = meta.script
+        assert script is not None
+
+        stdout, stderr, exit_code = _run_script(script, meta.timeout)
+
+        if meta.save_stdout_to is not None:
+            yield ChangeSetTaskContext(task_id=task.id, key=meta.save_stdout_to, value=stdout)
+
+        if meta.save_stderr_to is not None:
+            yield ChangeSetTaskContext(task_id=task.id, key=meta.save_stderr_to, value=stderr)
+
+        next_operation = meta.select_next_operation(exit_code)
+        full_operation_id = unit.operation_id.full_artifact_id.to_full_local(next_operation)
+
+        yield ChangeAddWorkUnit(task_id=task.id, operation_id=full_operation_id)
+
+    def validate_section(  # noqa: CCR001
+        self, artifact: Artifact, section_id: ArtifactSectionId
+    ) -> Result[None, ErrorsList]:
+        section = artifact.get_section(section_id).unwrap()
+
+        meta = cast(RunScriptMeta, section.meta)
+
+        errors: ErrorsList = []
+
+        if meta.goto_on_success is None:
+            errors.append(RunScriptMissingGotoOnSuccess(artifact_id=artifact.id, section_id=section_id))
+
+        if meta.goto_on_failure is None:
+            errors.append(RunScriptMissingGotoOnFailure(artifact_id=artifact.id, section_id=section_id))
+
+        for code in meta.goto_on_code:
+            try:
+                parsed = int(code)
+            except ValueError:
+                errors.append(
+                    RunScriptInvalidExitCode(
+                        artifact_id=artifact.id,
+                        section_id=section_id,
+                        exit_code=code,
+                    )
+                )
+                continue
+
+            if parsed == 0:
+                errors.append(RunScriptGotoOnCodeIncludesZero(artifact_id=artifact.id, section_id=section_id))
+
+        if errors:
+            return Err(errors)
+
+        return Ok(None)
+
+
+def _run_script(script: str, timeout: int) -> tuple[str, str, int]:  # noqa: CCR001
+    temp_path = None
+
+    try:
+        with tempfile.NamedTemporaryFile("w", prefix="donna-script-", delete=False) as temp:
+            temp.write(script)
+            temp.flush()
+            temp_path = temp.name
+
+        os.chmod(temp_path, 0o700)
+
+        try:
+            result = subprocess.run(  # noqa: S603
+                [temp_path],
+                capture_output=True,
+                text=True,
+                env=os.environ.copy(),
+                stdin=subprocess.DEVNULL,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            stdout = _coerce_output(exc.stdout)
+            stderr = _coerce_output(exc.stderr)
+            return stdout, stderr, 124
+
+        return _coerce_output(result.stdout), _coerce_output(result.stderr), result.returncode
+    finally:
+        if temp_path is not None:
+            try:
+                os.remove(temp_path)
+            except FileNotFoundError:
+                pass
+
+
+def _coerce_output(value: str | bytes | None) -> str:
+    if value is None:
+        return ""
+
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+
+    return value

donna/protocol/cell_shortcuts.py

@@ -0,0 +1,9 @@
+from donna.protocol.cells import Cell, MetaValue
+
+
+def operation_succeeded(message: str, **meta: MetaValue) -> Cell:
+    return Cell.build(kind="operation_succeeded", media_type="text/markdown", content=message, **meta)
+
+
+def operation_failed(message: str, **meta: MetaValue) -> Cell:
+    return Cell.build(kind="operation_failed", media_type="text/markdown", content=message, **meta)

donna/protocol/cells.py

@@ -0,0 +1,44 @@
+import base64
+import uuid
+
+import pydantic
+
+from donna.core.entities import BaseEntity
+
+MetaValue = str | int | bool | None
+
+
+def to_meta_value(value: object) -> MetaValue:
+    if isinstance(value, (str, int, bool)) or value is None:
+        return value
+
+    return str(value)
+
+
+class Cell(BaseEntity):
+    id: uuid.UUID = pydantic.Field(default_factory=uuid.uuid4)
+    kind: str
+    media_type: str | None
+    content: str | None
+    meta: dict[str, MetaValue] = pydantic.Field(default_factory=dict)
+
+    @classmethod
+    def build(cls, kind: str, media_type: str | None, content: str | None, **meta: MetaValue) -> "Cell":
+        if media_type is None and content is not None:
+            from donna.protocol.errors import ContentWithoutMediaType
+
+            raise ContentWithoutMediaType()
+
+        return cls(kind=kind, media_type=media_type, content=content, meta=meta)
+
+    @classmethod
+    def build_meta(cls, kind: str, **meta: MetaValue) -> "Cell":
+        return cls.build(kind=kind, media_type=None, content=None, **meta)
+
+    @classmethod
+    def build_markdown(cls, kind: str, content: str, **meta: MetaValue) -> "Cell":
+        return cls.build(kind=kind, media_type="text/markdown", content=content, **meta)
+
+    @property
+    def short_id(self) -> str:
+        return base64.urlsafe_b64encode(self.id.bytes).rstrip(b"=").decode()

donna/protocol/errors.py

@@ -0,0 +1,17 @@
+from donna.core import errors as core_errors
+
+
+class InternalError(core_errors.InternalError):
+    """Base class for internal errors in donna.protocol."""
+
+
+class ModeNotSet(InternalError):
+    message: str = "Mode is not set. Pass -p <mode> to the CLI."
+
+
+class UnsupportedFormatterMode(InternalError):
+    message: str = "Formatter for mode '{mode}' is not implemented."
+
+
+class ContentWithoutMediaType(InternalError):
+    message: str = "Cannot set content when media_type is None."

donna/protocol/formatters/automation.py

@@ -0,0 +1,25 @@
+import json
+
+from donna.protocol.cells import Cell
+from donna.protocol.formatters.base import Formatter as BaseFormatter
+
+
+class Formatter(BaseFormatter):
+
+    def format_cell(self, cell: Cell, single_mode: bool) -> bytes:
+        data: dict[str, str | int | bool | None] = {"id": cell.short_id}
+
+        for meta_key, meta_value in sorted(cell.meta.items()):
+            data[meta_key] = meta_value
+
+        data["content"] = cell.content.strip() if cell.content else None
+
+        return json.dumps(data, ensure_ascii=False, indent=None, separators=(",", ":"), sort_keys=True).encode()
+
+    def format_log(self, cell: Cell, single_mode: bool) -> bytes:
+        return self.format_cells([cell])
+
+    def format_cells(self, cells: list[Cell]) -> bytes:
+        single_mode = len(cells) == 1
+        formatted_cells = [self.format_cell(cell, single_mode=single_mode) for cell in cells]
+        return b"\n".join(formatted_cells)

donna/protocol/formatters/base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+
+from donna.protocol.cells import Cell
+
+
+class Formatter(ABC):
+
+    @abstractmethod
+    def format_cell(self, cell: Cell, single_mode: bool) -> bytes: ...  # noqa: E704
+
+    @abstractmethod
+    def format_log(self, cell: Cell, single_mode: bool) -> bytes: ...  # noqa: E704
+
+    @abstractmethod
+    def format_cells(self, cells: list[Cell]) -> bytes: ...  # noqa: E704

donna/protocol/formatters/human.py

@@ -0,0 +1,36 @@
+from donna.protocol.cells import Cell
+from donna.protocol.formatters.base import Formatter as BaseFormatter
+
+
+class Formatter(BaseFormatter):
+
+    def format_cell(self, cell: Cell, single_mode: bool) -> bytes:
+        id = cell.short_id
+
+        lines = []
+
+        if not single_mode:
+            lines = [f"----- DONNA CELL {id} -----"]
+
+        lines.append(f"kind = {cell.kind}")
+
+        if cell.media_type is not None:
+            lines.append(f"media_type = {cell.media_type}")
+
+        for meta_key, meta_value in sorted(cell.meta.items()):
+            lines.append(f"{meta_key} = {meta_value}")
+
+        if cell.content:
+            lines.append("")
+            lines.append(cell.content.strip())
+
+        return "\n".join(lines).encode()
+
+    def format_log(self, cell: Cell, single_mode: bool) -> bytes:
+        message = cell.content.strip() if cell.content else ""
+        return f"DONNA LOG: {message}".strip().encode()
+
+    def format_cells(self, cells: list[Cell]) -> bytes:
+        single_mode = len(cells) == 1
+        formatted_cells = [self.format_cell(cell, single_mode=single_mode) for cell in cells]
+        return b"\n\n".join(formatted_cells)

donna/protocol/formatters/llm.py

@@ -0,0 +1,39 @@
+from donna.protocol.cells import Cell
+from donna.protocol.formatters.base import Formatter as BaseFormatter
+
+
+class Formatter(BaseFormatter):
+
+    def format_cell(self, cell: Cell, single_mode: bool) -> bytes:  # noqa: CCR001
+        id = cell.short_id
+
+        lines = []
+
+        if not single_mode:
+            lines = [f"--DONNA-CELL {id} BEGIN--"]
+
+        lines.append(f"kind={cell.kind}")
+
+        if cell.media_type is not None:
+            lines.append(f"media_type={cell.media_type}")
+
+        for meta_key, meta_value in sorted(cell.meta.items()):
+            lines.append(f"{meta_key}={meta_value}")
+
+        if cell.content:
+            lines.append("")
+            lines.append(cell.content.strip())
+
+        if not single_mode:
+            lines.append(f"--DONNA-CELL {id} END--")
+
+        return "\n".join(lines).strip().encode()
+
+    def format_log(self, cell: Cell, single_mode: bool) -> bytes:
+        message = cell.content.strip() if cell.content else ""
+        return f"DONNA LOG: {message}".strip().encode()
+
+    def format_cells(self, cells: list[Cell]) -> bytes:
+        single_mode = len(cells) == 1
+        formatted_cells = [self.format_cell(cell, single_mode=single_mode) for cell in cells]
+        return b"\n\n".join(formatted_cells)

donna/protocol/modes.py

@@ -0,0 +1,40 @@
+import enum
+
+from donna.protocol.errors import ModeNotSet, UnsupportedFormatterMode
+from donna.protocol.formatters.automation import Formatter as AutomationFormatter
+from donna.protocol.formatters.base import Formatter
+from donna.protocol.formatters.human import Formatter as HumanFormatter
+from donna.protocol.formatters.llm import Formatter as LLMFormatter
+
+
+class Mode(enum.StrEnum):
+    human = "human"
+    llm = "llm"
+    automation = "automation"
+
+
+_MODE: Mode | None = None
+
+
+def set_mode(mode: Mode) -> None:
+    global _MODE
+    _MODE = mode
+
+
+def mode() -> Mode:
+    if _MODE is None:
+        raise ModeNotSet()
+
+    return _MODE
+
+
+def get_cell_formatter() -> Formatter:
+    match mode():
+        case Mode.human:
+            return HumanFormatter()
+        case Mode.llm:
+            return LLMFormatter()
+        case Mode.automation:
+            return AutomationFormatter()
+        case _:
+            raise UnsupportedFormatterMode(mode=mode())

donna/protocol/nodes.py

@@ -0,0 +1,59 @@
+from abc import ABC, abstractmethod
+
+from donna.protocol.cells import Cell
+
+
+class Node(ABC):
+    """Node of Donna's knowledge graph.
+
+    The concept of knowledge graph is highly experimental and subject to change.
+
+    Its primary purpose is to simplify navigation through different Donna's entities
+    and to provide a unified interface for retrieving information about them.
+
+    There are two types of child nodes:
+
+    - References — nodes that are referenced by this artifact, but not a part of it.
+                   An artifact does not include information from referenced nodes
+                   in its info.
+                   An artifact include references in its details and index.
+    - Components — nodes that are inseparable parts of this artifact.
+                   An artifact includes information from them in its info.
+                   An artifact does not include components in its details and index,
+    """
+
+    __slots__ = ()
+
+    @abstractmethod
+    def status(self) -> Cell:
+        """Returns short info about only this node."""
+        ...
+
+    def info(self) -> Cell:
+        """Returns full info about only this node."""
+        return self.status()
+
+    def details(self) -> list[Cell]:
+        """Returns info about the node and its children.
+
+        The node decides itself which children to include with what level of detail.
+        """
+        cells = [self.info()]
+        cells.extend(child.info() for child in self.references())
+
+        return cells
+
+    def index(self) -> list[Cell]:
+        """Returns status of itself and all its children."""
+        cells = [self.status()]
+        cells.extend(child.status() for child in self.references())
+
+        return cells
+
+    def references(self) -> list["Node"]:
+        """Return all nodes that are referenced by this one"""
+        return []
+
+    def components(self) -> list["Node"]:
+        """Return all nodes that are iseparable parts of this one."""
+        return []

donna/world/artifacts.py

@@ -0,0 +1,122 @@
+import pathlib
+
+from donna.core.entities import BaseEntity
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.domain.ids import FullArtifactId, FullArtifactIdPattern, WorldId
+from donna.machine.artifacts import Artifact
+from donna.machine.tasks import Task, WorkUnit
+from donna.world import errors
+from donna.world.config import config
+from donna.world.templates import RenderMode
+
+
+class ArtifactRenderContext(BaseEntity):
+    primary_mode: RenderMode
+    current_task: Task | None = None
+    current_work_unit: WorkUnit | None = None
+
+
+class ArtifactUpdateError(errors.WorldError):
+    cell_kind: str = "artifact_update_error"
+    artifact_id: FullArtifactId
+    path: pathlib.Path
+
+    def content_intro(self) -> str:
+        return f"Error updating artifact '{self.artifact_id}' from the path '{self.path}'"
+
+
+class CanNotUpdateReadonlyWorld(ArtifactUpdateError):
+    code: str = "donna.world.cannot_update_readonly_world"
+    message: str = "Cannot upload artifact to the read-only world `{error.world_id}`"
+    world_id: WorldId
+
+
+class InputPathHasNoExtension(ArtifactUpdateError):
+    code: str = "donna.world.input_path_has_no_extension"
+    message: str = "Input path has no extension to determine artifact source type"
+
+
+class NoSourceForArtifactExtension(ArtifactUpdateError):
+    code: str = "donna.world.no_source_for_artifact_extension"
+    message: str = "No source found for artifact extension of input path"
+
+
+@unwrap_to_error
+def artifact_file_extension(full_id: FullArtifactId) -> Result[str, ErrorsList]:
+    world = config().get_world(full_id.world_id).unwrap()
+    return Ok(world.file_extension_for(full_id.artifact_id).unwrap().lstrip("."))
+
+
+@unwrap_to_error
+def fetch_artifact(full_id: FullArtifactId, output: pathlib.Path) -> Result[None, ErrorsList]:
+    world = config().get_world(full_id.world_id).unwrap()
+    content = world.fetch_source(full_id.artifact_id).unwrap()
+
+    with output.open("wb") as f:
+        f.write(content)
+
+    return Ok(None)
+
+
+@unwrap_to_error
+def update_artifact(full_id: FullArtifactId, input: pathlib.Path) -> Result[None, ErrorsList]:
+    world = config().get_world(full_id.world_id).unwrap()
+
+    if world.readonly:
+        return Err([CanNotUpdateReadonlyWorld(artifact_id=full_id, path=input, world_id=world.id)])
+
+    source_suffix = input.suffix.lower()
+    content_bytes = input.read_bytes()
+
+    if not source_suffix:
+        return Err([InputPathHasNoExtension(artifact_id=full_id, path=input)])
+
+    source_config = config().find_source_for_extension(source_suffix)
+    if source_config is None:
+        return Err([NoSourceForArtifactExtension(artifact_id=full_id, path=input)])
+
+    render_context = ArtifactRenderContext(primary_mode=RenderMode.view)
+    test_artifact = source_config.construct_artifact_from_bytes(full_id, content_bytes, render_context).unwrap()
+    validation_result = test_artifact.validate_artifact()
+
+    validation_result.unwrap()
+    world.update(full_id.artifact_id, content_bytes, source_suffix).unwrap()
+
+    return Ok(None)
+
+
+@unwrap_to_error
+def load_artifact(
+    full_id: FullArtifactId, render_context: ArtifactRenderContext | None = None
+) -> Result[Artifact, ErrorsList]:
+    if render_context is None:
+        render_context = ArtifactRenderContext(primary_mode=RenderMode.view)
+
+    world = config().get_world(full_id.world_id).unwrap()
+    return Ok(world.fetch(full_id.artifact_id, render_context).unwrap())
+
+
+def list_artifacts(  # noqa: CCR001
+    pattern: FullArtifactIdPattern, render_context: ArtifactRenderContext | None = None
+) -> Result[list[Artifact], ErrorsList]:
+
+    if render_context is None:
+        render_context = ArtifactRenderContext(primary_mode=RenderMode.view)
+
+    artifacts: list[Artifact] = []
+    errors: ErrorsList = []
+
+    for world in reversed(config().worlds_instances):
+        for artifact_id in world.list_artifacts(pattern):
+            full_id = FullArtifactId((world.id, artifact_id))
+            artifact_result = load_artifact(full_id, render_context)
+            if artifact_result.is_err():
+                errors.extend(artifact_result.unwrap_err())
+                continue
+            artifacts.append(artifact_result.unwrap())
+
+    if errors:
+        return Err(errors)
+
+    return Ok(artifacts)