donna 0.2.0__py3-none-any.whl

donna/primitives/artifacts/workflow.py

@@ -0,0 +1,195 @@
+from typing import TYPE_CHECKING, ClassVar, Iterable, cast
+
+from donna.core import errors as core_errors
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+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 FsmMode, OperationMeta
+from donna.machine.primitives import Primitive
+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.artifacts.workflow."""
+
+
+class WorkflowSectionMissingMetadata(InternalError):
+    message: str = "Workflow section is missing workflow metadata."
+
+
+class WrongStartOperation(ArtifactValidationError):
+    code: str = "donna.workflows.wrong_start_operation"
+    message: str = "Can not find the start operation `{error.start_operation_id}` in the workflow."
+    ways_to_fix: list[str] = ["Ensure that the artifact contains the section with the specified start operation ID."]
+    start_operation_id: ArtifactSectionId
+
+
+class SectionIsNotAnOperation(ArtifactValidationError):
+    code: str = "donna.workflows.section_is_not_an_operation"
+    message: str = "Section `{error.workflow_section_id}` is not an operation and cannot be part of the workflow."
+    ways_to_fix: list[str] = ["Ensure that the section has a kind of one of operation primitives."]
+    workflow_section_id: ArtifactSectionId
+
+
+class WorkflowSectionNotWorkflow(ArtifactValidationError):
+    code: str = "donna.workflows.section_not_workflow"
+    message: str = "Section `{error.section_id}` is not a workflow section."
+    ways_to_fix: list[str] = ["Ensure the section uses the workflow primitive and includes workflow metadata."]
+
+
+class FinalOperationHasTransitions(ArtifactValidationError):
+    code: str = "donna.workflows.final_operation_has_transitions"
+    message: str = "Final operation `{error.workflow_section_id}` should not have outgoing transitions."
+    ways_to_fix: list[str] = [
+        "Approach A: Remove all outgoing transitions from this operation.",
+        "Approach B: Change the `fsm_mode` of this operation from `final` to `normal`",
+        "Approach C: Remove the `fsm_mode` setting from this operation, as `normal` is the default.",
+    ]
+    workflow_section_id: ArtifactSectionId
+
+
+class NoOutgoingTransitions(ArtifactValidationError):
+    code: str = "donna.workflows.no_outgoing_transitions"
+    message: str = (
+        "Operation `{error.workflow_section_id}` must have at least one outgoing transition or be marked as final."
+    )
+    ways_to_fix: list[str] = [
+        "Approach A: Add at least one outgoing transition from this operation.",
+        "Approach B: Change the kind of this operation to `donna.lib.finish`",
+        "Approach C: Mark this operation as final by setting its `fsm_mode` to `final`.",
+    ]
+    workflow_section_id: ArtifactSectionId
+
+
+def find_workflow_sections(start_operation_id: ArtifactSectionId, artifact: Artifact) -> set[ArtifactSectionId]:
+    workflow_sections = set()
+    to_visit = [start_operation_id]
+
+    while to_visit:
+        current = to_visit.pop()
+
+        if current in workflow_sections:
+            continue
+
+        workflow_sections.add(current)
+
+        section_result = artifact.get_section(current)
+        if section_result.is_err():
+            continue
+
+        section = section_result.unwrap()
+
+        if not isinstance(section.meta, OperationMeta):
+            continue
+
+        to_visit.extend(section.meta.allowed_transtions)
+
+    return workflow_sections
+
+
+class WorkflowConfig(ArtifactSectionConfig):
+    start_operation_id: ArtifactSectionId
+
+
+class WorkflowMeta(ArtifactSectionMeta):
+    start_operation_id: ArtifactSectionId
+
+    def cells_meta(self) -> dict[str, object]:
+        return {"start_operation_id": str(self.start_operation_id)}
+
+
+class Workflow(MarkdownSectionMixin, Primitive):
+    config_class: ClassVar[type[WorkflowConfig]] = WorkflowConfig
+
+    def markdown_construct_meta(
+        self,
+        artifact_id: FullArtifactId,
+        source: markdown.SectionSource,
+        section_config: ArtifactSectionConfig,
+        description: str,
+        primary: bool = False,
+    ) -> Result[ArtifactSectionMeta, ErrorsList]:
+        workflow_config = cast(WorkflowConfig, section_config)
+        return Ok(WorkflowMeta(start_operation_id=workflow_config.start_operation_id))
+
+    def execute_section(self, task: "Task", unit: "WorkUnit", section: ArtifactSection) -> Iterable["Change"]:
+        from donna.machine.changes import ChangeAddWorkUnit
+
+        if not isinstance(section.meta, WorkflowMeta):
+            raise WorkflowSectionMissingMetadata()
+
+        full_id = section.artifact_id.to_full_local(section.meta.start_operation_id)
+
+        yield ChangeAddWorkUnit(task_id=task.id, operation_id=full_id)
+
+    @unwrap_to_error
+    def validate_section(  # noqa: CCR001, CFQ001
+        self, artifact: Artifact, section_id: ArtifactSectionId
+    ) -> Result[None, ErrorsList]:
+        section = artifact.get_section(section_id).unwrap()
+
+        if not isinstance(section.meta, WorkflowMeta):
+            return Err([WorkflowSectionNotWorkflow(artifact_id=artifact.id, section_id=section_id)])
+
+        start_operation_id = section.meta.start_operation_id
+
+        errors: ErrorsList = []
+
+        start_operation_result = artifact.get_section(start_operation_id)
+        if start_operation_result.is_err():
+            errors.extend(start_operation_result.unwrap_err())
+            errors.append(
+                WrongStartOperation(
+                    artifact_id=artifact.id, section_id=section_id, start_operation_id=start_operation_id
+                )
+            )
+
+        workflow_sections = find_workflow_sections(start_operation_id, artifact)
+
+        for workflow_section_id in workflow_sections:
+            workflow_section_result = artifact.get_section(workflow_section_id)
+            if workflow_section_result.is_err():
+                errors.extend(workflow_section_result.unwrap_err())
+                continue
+            workflow_section = workflow_section_result.unwrap()
+
+            if isinstance(workflow_section.meta, WorkflowMeta):
+                continue
+
+            if not isinstance(workflow_section.meta, OperationMeta):
+                errors.append(
+                    SectionIsNotAnOperation(
+                        artifact_id=artifact.id, section_id=section.id, workflow_section_id=workflow_section.id
+                    )
+                )
+                continue
+
+            if workflow_section.meta.fsm_mode == FsmMode.final and workflow_section.meta.allowed_transtions:
+                errors.append(
+                    FinalOperationHasTransitions(
+                        artifact_id=artifact.id, section_id=section_id, workflow_section_id=workflow_section.id
+                    )
+                )
+                continue
+
+            if workflow_section.meta.fsm_mode == FsmMode.final:
+                continue
+
+            if not workflow_section.meta.allowed_transtions:
+                errors.append(
+                    NoOutgoingTransitions(
+                        artifact_id=artifact.id, section_id=section_id, workflow_section_id=workflow_section.id
+                    )
+                )
+
+        if errors:
+            return Err(errors)
+
+        return Ok(None)

donna/primitives/directives/goto.py

@@ -0,0 +1,44 @@
+from typing import Any
+
+from jinja2.runtime import Context
+
+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 FullArtifactSectionId
+from donna.machine.templates import Directive, PreparedDirectiveResult
+from donna.protocol.modes import mode
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    cell_kind: str = "directive_error"
+
+
+class GoToInvalidArguments(EnvironmentError):
+    code: str = "donna.directives.goto.invalid_arguments"
+    message: str = "GoTo directive requires exactly one argument: next_operation_id (got {error.provided_count})."
+    ways_to_fix: list[str] = ["Provide exactly one argument: next_operation_id."]
+    provided_count: int
+
+
+class GoTo(Directive):
+    def _prepare_arguments(
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> PreparedDirectiveResult:
+        if argv is None or len(argv) != 1:
+            return Err([GoToInvalidArguments(provided_count=0 if argv is None else len(argv))])
+
+        artifact_id = context["artifact_id"]
+
+        next_operation_id = artifact_id.to_full_local(argv[0])
+
+        return Ok((next_operation_id,))
+
+    def render_view(self, context: Context, next_operation_id: FullArtifactSectionId) -> Result[Any, ErrorsList]:
+        protocol = mode().value
+        return Ok(f"donna -p {protocol} sessions action-request-completed <action-request-id> '{next_operation_id}'")
+
+    def render_analyze(self, context: Context, next_operation_id: FullArtifactSectionId) -> Result[Any, ErrorsList]:
+        return Ok(f"$$donna {self.analyze_id} {next_operation_id.local_id} donna$$")

donna/primitives/directives/task_variable.py

@@ -0,0 +1,73 @@
+from typing import Any, cast
+
+from jinja2.runtime import Context
+
+from donna.core import errors as core_errors
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result
+from donna.machine.templates import Directive, PreparedDirectiveResult
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    cell_kind: str = "directive_error"
+
+
+class TaskVariableInvalidArguments(EnvironmentError):
+    code: str = "donna.directives.task_variable.invalid_arguments"
+    message: str = "TaskVariable directive requires exactly one argument: variable_name (got {error.provided_count})."
+    ways_to_fix: list[str] = ["Provide exactly one argument: variable_name."]
+    provided_count: int
+
+
+class TaskVariableTaskContextMissing(EnvironmentError):
+    code: str = "donna.directives.task_variable.task_context_missing"
+    message: str = "TaskVariable directive requires task context, but none is available."
+    ways_to_fix: list[str] = ["Ensure the directive is rendered with a task context present."]
+
+
+class TaskVariable(Directive):
+    def _prepare_arguments(
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> PreparedDirectiveResult:
+        if argv is None or len(argv) != 1:
+            return Err([TaskVariableInvalidArguments(provided_count=0 if argv is None else len(argv))])
+
+        variable_name = str(argv[0])
+
+        return Ok((variable_name,))
+
+    def render_view(self, context: Context, variable_name: str) -> Result[Any, ErrorsList]:
+        return Ok(
+            "$$donna at the time of execution of this section here will placed a value "
+            f"of the task variable '{variable_name}' donna$$"
+        )
+
+    def render_execute(self, context: Context, variable_name: str) -> Result[Any, ErrorsList]:
+        task_context = self._resolve_task_context(context)
+        if task_context is None:
+            return Err([TaskVariableTaskContextMissing()])
+
+        if variable_name not in task_context:
+            # Since we render the whole artifact, instead of a particular executed section
+            # some variables may be missing
+            # TODO: we may want to timprove this behavior later to avoid possible confusion
+            return Ok(
+                f"$$donna {self.analyze_id} variable '{variable_name}' does not found. "
+                "If you are an LLM agent and see that message AS AN INSTRUCTION TO EXECUTE, "
+                "stop your work and notify developer about the problems in workflow donna$$"
+            )
+
+        return Ok(task_context[variable_name])
+
+    def _resolve_task_context(self, context: Context) -> dict[str, Any] | None:
+        task = context.get("current_task")
+        if task is not None and hasattr(task, "context"):
+            return cast(dict[str, Any], task.context)
+
+        task_context = context.get("task_context")
+        if isinstance(task_context, dict):
+            return cast(dict[str, Any], task_context)
+
+        return None

donna/primitives/directives/view.py

@@ -0,0 +1,45 @@
+from typing import Any
+
+from jinja2.runtime import Context
+
+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 FullArtifactId
+from donna.machine.templates import Directive, PreparedDirectiveResult
+from donna.protocol.modes import mode
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    cell_kind: str = "directive_error"
+
+
+class ViewInvalidArguments(EnvironmentError):
+    code: str = "donna.directives.view.invalid_arguments"
+    message: str = "View directive requires exactly one argument: specification_id (got {error.provided_count})."
+    ways_to_fix: list[str] = ["Provide exactly one argument: specification_id."]
+    provided_count: int
+
+
+class View(Directive):
+    def _prepare_arguments(
+        self,
+        context: Context,
+        *argv: Any,
+    ) -> PreparedDirectiveResult:
+        if argv is None or len(argv) != 1:
+            return Err([ViewInvalidArguments(provided_count=0 if argv is None else len(argv))])
+
+        artifact_id_result = FullArtifactId.parse(str(argv[0]))
+        errors = artifact_id_result.err()
+        if errors is not None:
+            return Err(errors)
+
+        artifact_id = artifact_id_result.ok()
+        assert artifact_id is not None
+
+        return Ok((artifact_id,))
+
+    def render_view(self, context: Context, specification_id: FullArtifactId) -> Result[Any, ErrorsList]:
+        protocol = mode().value
+        return Ok(f"donna -p {protocol} artifacts view '{specification_id}'")

donna/primitives/operations/finish_workflow.py

@@ -0,0 +1,37 @@
+from typing import TYPE_CHECKING, ClassVar, Iterator, Literal, cast
+
+from donna.core.errors import ErrorsList
+from donna.core.result import Ok, Result
+from donna.domain.ids import FullArtifactId
+from donna.machine.artifacts import ArtifactSection, ArtifactSectionConfig, ArtifactSectionMeta
+from donna.machine.operations import FsmMode, 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 FinishWorkflowConfig(OperationConfig):
+    fsm_mode: Literal[FsmMode.final] = FsmMode.final
+
+
+class FinishWorkflow(MarkdownSectionMixin, OperationKind):
+    def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
+        from donna.machine.changes import ChangeFinishTask
+
+        yield ChangeFinishTask(task_id=task.id)
+
+    config_class: ClassVar[type[FinishWorkflowConfig]] = FinishWorkflowConfig
+
+    def markdown_construct_meta(
+        self,
+        artifact_id: "FullArtifactId",
+        source: markdown.SectionSource,
+        section_config: ArtifactSectionConfig,
+        description: str,
+        primary: bool = False,
+    ) -> Result[ArtifactSectionMeta, ErrorsList]:
+        finish_config = cast(FinishWorkflowConfig, section_config)
+        return Ok(OperationMeta(fsm_mode=finish_config.fsm_mode, allowed_transtions=set()))

donna/primitives/operations/request_action.py

@@ -0,0 +1,89 @@
+import re
+from typing import TYPE_CHECKING, ClassVar, Iterator, cast
+
+import pydantic
+
+from donna.core.errors import ErrorsList
+from donna.core.result import Ok, Result
+from donna.domain import errors as domain_errors
+from donna.domain.ids import ArtifactSectionId, FullArtifactId
+from donna.machine.action_requests import ActionRequest
+from donna.machine.artifacts import ArtifactSection, ArtifactSectionConfig, ArtifactSectionMeta
+from donna.machine.operations import FsmMode, 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
+
+
+def extract_transitions(text: str) -> set[ArtifactSectionId]:
+    """Extracts all transitions from the text of action request.
+
+    Transition is specified as render of `goto` directive in the format:
+    ```
+    $$donna goto <full_artifact_local_id> donna$$
+    ```
+    """
+    pattern = r"\$\$donna\s+goto\s+([a-zA-Z0-9_\-./:]+)\s+donna\$\$"
+    matches = re.findall(pattern, text)
+
+    transitions: set[ArtifactSectionId] = set()
+
+    for match in matches:
+        transition_result = ArtifactSectionId.parse(match)
+        if transition_result.is_err():
+            raise domain_errors.InvalidIdentifier(value=match)
+        transitions.add(transition_result.unwrap())
+
+    return transitions
+
+
+class RequestActionConfig(OperationConfig):
+    @pydantic.field_validator("fsm_mode", mode="after")
+    @classmethod
+    def validate_fsm_mode(cls, v: FsmMode) -> FsmMode:
+        if v == FsmMode.final:
+            raise ValueError("RequestAction operation cannot have 'final' fsm_mode")
+
+        return v
+
+
+class RequestAction(MarkdownSectionMixin, OperationKind):
+    config_class: ClassVar[type[RequestActionConfig]] = RequestActionConfig
+
+    def markdown_construct_meta(
+        self,
+        artifact_id: "FullArtifactId",
+        source: markdown.SectionSource,
+        section_config: ArtifactSectionConfig,
+        description: str,
+        primary: bool = False,
+    ) -> Result[ArtifactSectionMeta, ErrorsList]:
+        request_config = cast(RequestActionConfig, section_config)
+        analysis = source.as_analysis_markdown(with_title=True)
+
+        return Ok(
+            OperationMeta(
+                fsm_mode=request_config.fsm_mode,
+                allowed_transtions=extract_transitions(analysis),
+            )
+        )
+
+    def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
+        from donna.machine.changes import ChangeAddActionRequest
+
+        context: dict[str, object] = {
+            "scheme": operation,
+            "task": task,
+            "work_unit": unit,
+        }
+
+        request_text = operation.description.format(**context)
+
+        full_operation_id = unit.operation_id
+
+        request = ActionRequest.build(request_text, full_operation_id)
+
+        yield ChangeAddActionRequest(action_request=request)