donna 0.2.0__py3-none-any.whl

donna/machine/sessions.py

@@ -0,0 +1,215 @@
+import functools
+from typing import Callable, ParamSpec
+
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.domain.ids import ActionRequestId, FullArtifactId, FullArtifactSectionId, WorldId
+from donna.machine import errors as machine_errors
+from donna.machine.operations import OperationMeta
+from donna.machine.state import ConsistentState, MutableState
+from donna.protocol.cell_shortcuts import operation_succeeded
+from donna.protocol.cells import Cell
+from donna.world import artifacts
+from donna.world import tmp as world_tmp
+from donna.world.config import config
+from donna.world.worlds.base import World
+
+
+def _errors_to_cells(errors: ErrorsList) -> list[Cell]:
+    return [error.node().info() for error in errors]
+
+
+@unwrap_to_error
+def _session() -> Result[World, ErrorsList]:
+    world = config().get_world(WorldId("session")).unwrap()
+
+    if not world.is_initialized():
+        world.initialize(reset=False)
+
+    return Ok(world)
+
+
+@unwrap_to_error
+def _load_state() -> Result[ConsistentState, ErrorsList]:
+    content = _session().unwrap().read_state("state.json").unwrap()
+    if content is None:
+        return Err([machine_errors.SessionStateNotInitialized()])
+
+    return Ok(ConsistentState.from_json(content.decode("utf-8")))
+
+
+@unwrap_to_error
+def _save_state(state: ConsistentState) -> Result[None, ErrorsList]:
+    _session().unwrap().write_state("state.json", state.to_json().encode("utf-8")).unwrap()
+    return Ok(None)
+
+
+@unwrap_to_error
+def _state_run(mutator: MutableState) -> Result[None, ErrorsList]:
+    while mutator.has_work():
+        mutator.exectute_next_work_unit().unwrap()
+        _save_state(mutator.freeze()).unwrap()
+
+    return Ok(None)
+
+
+@unwrap_to_error
+def _state_cells() -> Result[list[Cell], ErrorsList]:
+    return Ok(_load_state().unwrap().node().details())
+
+
+P = ParamSpec("P")
+
+
+def _session_required(func: Callable[P, list[Cell]]) -> Callable[P, list[Cell]]:
+    # TODO: refactor to catch domain exception from load_state
+    #       when we implement domain exceptions
+    @functools.wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> list[Cell]:
+        state_result = _load_state()
+        if state_result.is_err():
+            return _errors_to_cells(state_result.unwrap_err())
+
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def start() -> list[Cell]:
+    world_tmp.clear()
+    session_result = _session()
+    if session_result.is_err():
+        return _errors_to_cells(session_result.unwrap_err())
+
+    session_result.unwrap().initialize(reset=True)
+
+    save_result = _save_state(MutableState.build().freeze())
+    if save_result.is_err():
+        return _errors_to_cells(save_result.unwrap_err())
+
+    return [operation_succeeded("Started new session.")]
+
+
+def clear() -> list[Cell]:
+    world_tmp.clear()
+    session_result = _session()
+    if session_result.is_err():
+        return _errors_to_cells(session_result.unwrap_err())
+
+    session_result.unwrap().initialize(reset=True)
+    return [operation_succeeded("Cleared session.")]
+
+
+@_session_required
+def continue_() -> list[Cell]:
+    state_result = _load_state()
+    if state_result.is_err():
+        return _errors_to_cells(state_result.unwrap_err())
+
+    mutator = state_result.unwrap().mutator()
+    run_result = _state_run(mutator)
+    if run_result.is_err():
+        return _errors_to_cells(run_result.unwrap_err())
+
+    cells_result = _state_cells()
+    if cells_result.is_err():
+        return _errors_to_cells(cells_result.unwrap_err())
+
+    return cells_result.unwrap()
+
+
+@_session_required
+def status() -> list[Cell]:
+    state_result = _load_state()
+    if state_result.is_err():
+        return _errors_to_cells(state_result.unwrap_err())
+
+    return [state_result.unwrap().node().info()]
+
+
+@_session_required
+def details() -> list[Cell]:
+    state_result = _load_state()
+    if state_result.is_err():
+        return _errors_to_cells(state_result.unwrap_err())
+
+    return state_result.unwrap().node().details()
+
+
+@_session_required
+def start_workflow(artifact_id: FullArtifactId) -> list[Cell]:
+    workflow_result = artifacts.load_artifact(artifact_id)
+    if workflow_result.is_err():
+        return _errors_to_cells(workflow_result.unwrap_err())
+
+    workflow = workflow_result.unwrap()
+    primary_section_result = workflow.primary_section()
+    if primary_section_result.is_err():
+        return _errors_to_cells(primary_section_result.unwrap_err())
+
+    primary_section = primary_section_result.unwrap()
+
+    state_result = _load_state()
+    if state_result.is_err():
+        return _errors_to_cells(state_result.unwrap_err())
+
+    mutator = state_result.unwrap().mutator()
+    mutator.start_workflow(workflow.id.to_full_local(primary_section.id))
+    save_result = _save_state(mutator.freeze())
+    if save_result.is_err():
+        return _errors_to_cells(save_result.unwrap_err())
+
+    run_result = _state_run(mutator)
+    if run_result.is_err():
+        return _errors_to_cells(run_result.unwrap_err())
+
+    cells_result = _state_cells()
+    if cells_result.is_err():
+        return _errors_to_cells(cells_result.unwrap_err())
+
+    return cells_result.unwrap()
+
+
+@unwrap_to_error
+def _validate_operation_transition(
+    state: MutableState, request_id: ActionRequestId, next_operation_id: FullArtifactSectionId
+) -> Result[None, ErrorsList]:
+    operation_id = state.get_action_request(request_id).unwrap().operation_id
+    workflow = artifacts.load_artifact(operation_id.full_artifact_id).unwrap()
+    operation = workflow.get_section(operation_id.local_id).unwrap()
+
+    assert isinstance(operation.meta, OperationMeta)
+
+    if next_operation_id.local_id not in operation.meta.allowed_transtions:
+        return Err(
+            [machine_errors.InvalidOperationTransition(operation_id=operation_id, next_operation_id=next_operation_id)]
+        )
+
+    return Ok(None)
+
+
+@_session_required
+def complete_action_request(request_id: ActionRequestId, next_operation_id: FullArtifactSectionId) -> list[Cell]:
+    state_result = _load_state()
+    if state_result.is_err():
+        return _errors_to_cells(state_result.unwrap_err())
+
+    mutator = state_result.unwrap().mutator()
+    transition_result = _validate_operation_transition(mutator, request_id, next_operation_id)
+    if transition_result.is_err():
+        return _errors_to_cells(transition_result.unwrap_err())
+
+    mutator.complete_action_request(request_id, next_operation_id)
+    save_result = _save_state(mutator.freeze())
+    if save_result.is_err():
+        return _errors_to_cells(save_result.unwrap_err())
+
+    run_result = _state_run(mutator)
+    if run_result.is_err():
+        return _errors_to_cells(run_result.unwrap_err())
+
+    cells_result = _state_cells()
+    if cells_result.is_err():
+        return _errors_to_cells(cells_result.unwrap_err())
+
+    return cells_result.unwrap()

donna/machine/state.py

@@ -0,0 +1,244 @@
+import copy
+import textwrap
+from typing import Sequence, cast
+
+import pydantic
+
+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 (
+    ActionRequestId,
+    FullArtifactSectionId,
+    InternalId,
+    TaskId,
+    WorkUnitId,
+)
+from donna.machine import errors as machine_errors
+from donna.machine.action_requests import ActionRequest
+from donna.machine.changes import (
+    Change,
+    ChangeAddTask,
+    ChangeAddWorkUnit,
+    ChangeRemoveActionRequest,
+    ChangeRemoveTask,
+    ChangeRemoveWorkUnit,
+)
+from donna.machine.tasks import Task, WorkUnit
+from donna.protocol.cells import Cell
+from donna.protocol.nodes import Node
+
+
+class BaseState(BaseEntity):
+    tasks: list[Task]
+    work_units: list[WorkUnit]
+    action_requests: list[ActionRequest]
+    started: bool
+    last_id: int
+
+    def has_work(self) -> bool:
+        return bool(self.work_units)
+
+    def node(self) -> "StateNode":
+        return StateNode(self)
+
+    ###########
+    # Accessors
+    ###########
+
+    @property
+    def current_task(self) -> Task:
+        return self.tasks[-1]
+
+    def get_action_request(self, request_id: ActionRequestId) -> Result[ActionRequest, ErrorsList]:
+        for request in self.action_requests:
+            if request.id == request_id:
+                return Ok(request)
+
+        return Err([machine_errors.ActionRequestNotFound(request_id=request_id)])
+
+    # Currently we execute first work unit found for the current task
+    # Since we only append work units, this effectively works as a queue per task
+    # In the future we may want to have more sophisticated scheduling
+    def get_next_work_unit(self) -> WorkUnit | None:
+        for work_unit in self.work_units:
+            if work_unit.task_id != self.current_task.id:
+                continue
+
+            return work_unit
+
+        return None
+
+
+class ConsistentState(BaseState):
+
+    def mutator(self) -> "MutableState":
+        return MutableState.model_validate(copy.deepcopy(self.model_dump()))
+
+
+class MutableState(BaseState):
+    model_config = pydantic.ConfigDict(frozen=False)
+
+    @classmethod
+    def build(cls) -> "MutableState":
+        return cls(
+            tasks=[],
+            action_requests=[],
+            work_units=[],
+            started=False,
+            last_id=0,
+        )
+
+    def freeze(self) -> ConsistentState:
+        return ConsistentState.model_validate(copy.deepcopy(self.model_dump()))
+
+    ################
+    # Ids generation
+    ################
+
+    def next_id(self, prefix: str) -> InternalId:
+        self.last_id += 1
+        new_id = InternalId.build(prefix, self.last_id)
+        return new_id
+
+    def next_task_id(self) -> TaskId:
+        return cast(TaskId, self.next_id("T"))
+
+    def next_work_unit_id(self) -> WorkUnitId:
+        return cast(WorkUnitId, self.next_id("WU"))
+
+    def next_action_request_id(self) -> ActionRequestId:
+        return cast(ActionRequestId, self.next_id("AR"))
+
+    ##########
+    # Mutators
+    ##########
+
+    def mark_started(self) -> None:
+        self.started = True
+
+    def add_action_request(self, action_request: ActionRequest) -> None:
+        action_request.id = self.next_action_request_id()
+        self.action_requests.append(action_request)
+
+    def add_work_unit(self, work_unit: WorkUnit) -> None:
+        self.work_units.append(work_unit)
+
+    def add_task(self, task: Task) -> None:
+        self.tasks.append(task)
+
+    def remove_action_request(self, request_id: ActionRequestId) -> None:
+        self.action_requests = [request for request in self.action_requests if request.id != request_id]
+
+    def remove_work_unit(self, work_unit_id: WorkUnitId) -> None:
+        self.work_units = [unit for unit in self.work_units if unit.id != work_unit_id]
+
+    def remove_task(self, task_id: TaskId) -> None:
+        self.tasks = [task for task in self.tasks if task.id != task_id]
+
+    def apply_changes(self, changes: Sequence[Change]) -> None:
+        for change in changes:
+            change.apply_to(self)
+
+    ####################
+    # Complex operations
+    ####################
+
+    def complete_action_request(self, request_id: ActionRequestId, next_operation_id: FullArtifactSectionId) -> None:
+        changes = [
+            ChangeAddWorkUnit(task_id=self.current_task.id, operation_id=next_operation_id),
+            ChangeRemoveActionRequest(action_request_id=request_id),
+        ]
+        self.apply_changes(changes)
+
+    def start_workflow(self, full_operation_id: FullArtifactSectionId) -> None:
+        changes = [ChangeAddTask(operation_id=full_operation_id)]
+        self.apply_changes(changes)
+
+    def finish_workflow(self, task_id: TaskId) -> None:
+        changes = [ChangeRemoveTask(task_id=task_id)]
+        self.apply_changes(changes)
+
+    @unwrap_to_error
+    def exectute_next_work_unit(self) -> Result[None, ErrorsList]:
+        next_work_unit = self.get_next_work_unit()
+        assert next_work_unit is not None
+
+        changes = next_work_unit.run(self.current_task).unwrap()
+        changes.append(ChangeRemoveWorkUnit(work_unit_id=next_work_unit.id))
+
+        self.apply_changes(changes)
+        return Ok(None)
+
+
+class StateNode(Node):
+    __slots__ = ("_state",)
+
+    def __init__(self, state: BaseState) -> None:
+        self._state = state
+
+    def status(self) -> Cell:
+        if not self._state.started:
+            message = textwrap.dedent(
+                """
+            The session has not been started yet. You can safely start a new session and then run a workflow.
+                """
+            )
+
+        elif not self._state.tasks:
+            message = textwrap.dedent(
+                """
+            The session is IDLE. There are no active tasks.
+
+            - If the developer asked you to start working on a new task, you can do so by initiating a new workflow.
+            - If you have been working on a task, consider it completed and REPORT THE RESULTS TO THE DEVELOPER.
+                """
+            )
+
+        elif self._state.work_units:
+            message = textwrap.dedent(
+                """
+            The session has PENDING WORK UNITS. Donna has work to complete.
+
+            - If the developer asked you to start working on a new task, you MUST warn that there are pending work
+              units and ask if you should start a new session or continue working on the current work units.
+            - If you have been working on a task, you can continue session.
+                """
+            )
+
+        elif self._state.action_requests:
+            message = textwrap.dedent(
+                """
+            The session is AWAITING YOUR ACTION. You have pending action requests to address.
+
+            - If the developer asked you to start working on a new task, you MUST ask if you should start a new session
+              or continue working on the current action requests.
+            - Otherwise, you MUST address the pending action requests before proceeding.
+                """
+            )
+
+        elif self._state.tasks:
+            message = textwrap.dedent(
+                """
+            The session has unfinished TASKS but no pending work units or action requests.
+
+            - If the developer asked you to start working on a new task , you MUST ask if you should start a new
+              session or run a new workflow in the current one.
+            - If you have been working on a task, you can consider it completed and output the results to the
+              developer.
+                """
+            )
+
+        else:
+            raise machine_errors.SessionStateStatusInvalid()
+
+        return Cell.build_markdown(
+            kind="session_state_status",
+            content=message,
+            tasks=len(self._state.tasks),
+            queued_work_units=len(self._state.work_units),
+            pending_action_requests=len(self._state.action_requests),
+        )
+
+    def references(self) -> list[Node]:
+        return [action_request.node() for action_request in self._state.action_requests]

donna/machine/tasks.py

@@ -0,0 +1,89 @@
+import copy
+import sys
+from typing import TYPE_CHECKING, Any
+
+import pydantic
+
+from donna.core.entities import BaseEntity
+from donna.core.errors import ErrorsList
+from donna.core.result import Ok, Result, unwrap_to_error
+from donna.domain.ids import FullArtifactSectionId, TaskId, WorkUnitId
+from donna.protocol.cells import Cell
+from donna.protocol.modes import get_cell_formatter
+
+if TYPE_CHECKING:
+    from donna.machine.changes import Change
+
+
+class Task(BaseEntity):
+    id: TaskId
+    context: dict[str, Any]
+
+    # TODO: we may want to make queue items frozen later
+    model_config = pydantic.ConfigDict(frozen=False)
+
+    @classmethod
+    def build(cls, id: TaskId) -> "Task":
+        return Task(
+            id=id,
+            context={},
+        )
+
+
+class WorkUnit(BaseEntity):
+    id: WorkUnitId
+    task_id: TaskId
+    operation_id: FullArtifactSectionId
+    context: dict[str, Any]
+
+    @classmethod
+    def build(
+        cls,
+        id: WorkUnitId,
+        task_id: TaskId,
+        operation_id: FullArtifactSectionId,
+        context: dict[str, Any] | None = None,
+    ) -> "WorkUnit":
+
+        if context is None:
+            context = {}
+
+        unit = cls(
+            task_id=task_id,
+            id=id,
+            operation_id=operation_id,
+            context=copy.deepcopy(context),
+        )
+
+        return unit
+
+    @unwrap_to_error
+    def run(self, task: Task) -> Result[list["Change"], ErrorsList]:
+        from donna.machine import artifacts as machine_artifacts
+        from donna.machine.primitives import resolve_primitive
+        from donna.world.artifacts import ArtifactRenderContext
+        from donna.world.templates import RenderMode
+
+        render_context = ArtifactRenderContext(
+            primary_mode=RenderMode.execute,
+            current_task=task,
+            current_work_unit=self,
+        )
+        operation = machine_artifacts.resolve(self.operation_id, render_context).unwrap()
+        operation_kind = resolve_primitive(operation.kind).unwrap()
+
+        ##########################
+        # We log each operation here to help agent display the progress to the user
+        # TODO: not a good solution from the agent perspective
+        #       let's hope there will some protocol appear that helps with that later
+        # TODO: not so good place for and way of logging, should do smth with that
+        log_message = f"{self.operation_id}: {operation.title}"
+        log_cell = Cell.build(kind="donna_log", media_type="text/plain", content=log_message)
+        formatter = get_cell_formatter()
+        sys.stdout.buffer.write(formatter.format_log(log_cell, single_mode=True) + b"\n\n")
+        sys.stdout.buffer.flush()
+        ##########################
+
+        changes = list(operation_kind.execute_section(task, self, operation))
+
+        return Ok(changes)

donna/machine/templates.py

@@ -0,0 +1,83 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+from jinja2.runtime import Context
+
+from donna.core.errors import ErrorsList
+from donna.core.result import Ok, Result
+from donna.machine import errors as machine_errors
+from donna.machine.primitives import Primitive
+
+if TYPE_CHECKING:
+    pass
+
+PreparedDirectiveArguments: TypeAlias = tuple[Any, ...]
+PreparedDirectiveResult: TypeAlias = Result[PreparedDirectiveArguments, ErrorsList]
+
+
+class DirectiveUnsupportedRenderMode(machine_errors.InternalError):
+    message: str = "Render mode {render_mode} not implemented in directive {directive_name}."
+    render_mode: Any
+    directive_name: str
+
+
+class Directive(Primitive, ABC):
+    analyze_id: str
+
+    def apply_directive(  # noqa: E704
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> Result[Any, ErrorsList]:
+        from donna.world import templates as world_templates
+
+        render_mode = context["render_mode"]
+        arguments_result = self._prepare_arguments(context, *argv)
+        if arguments_result.is_err():
+            return arguments_result
+
+        argv = arguments_result.unwrap()
+
+        match render_mode:
+            case world_templates.RenderMode.view:
+                return self.render_view(context, *argv)
+            case world_templates.RenderMode.execute:
+                return self.render_execute(context, *argv)
+            case world_templates.RenderMode.analysis:
+                return self.render_analyze(context, *argv)
+            case _:
+                raise DirectiveUnsupportedRenderMode(render_mode=render_mode, directive_name=self.__class__.__name__)
+
+    def _prepare_arguments(
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> PreparedDirectiveResult:
+        return Ok(argv)
+
+    @abstractmethod
+    def render_view(  # noqa: E704
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> Result[Any, ErrorsList]: ...
+
+    def render_execute(
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> Result[Any, ErrorsList]:
+        return self.render_view(context, *argv)
+
+    def render_analyze(
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> Result[str, ErrorsList]:
+        parts = [str(arg) for arg in argv]
+        arguments = " ".join(parts)
+
+        if arguments:
+            return Ok(f"$$donna {self.analyze_id} {arguments} donna$$")
+
+        return Ok(f"$$donna {self.analyze_id} donna$$")

donna/primitives/__init__.py

@@ -0,0 +1 @@
+"""Concrete implementations for Donna primitives."""

donna/primitives/artifacts/specification.py

@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING, ClassVar
+
+from donna.machine.artifacts import ArtifactSectionConfig
+from donna.machine.primitives import Primitive
+from donna.world.sources.markdown import MarkdownSectionMixin
+
+if TYPE_CHECKING:
+    pass
+
+
+class TextConfig(ArtifactSectionConfig):
+    pass
+
+
+class Text(MarkdownSectionMixin, Primitive):
+    config_class: ClassVar[type[TextConfig]] = TextConfig
+
+
+class Specification(MarkdownSectionMixin, Primitive):
+    pass