donna 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

donna/machine/tasks.py

@@ -1,15 +1,12 @@
 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
+from donna.protocol.utils import instant_output
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change
@@ -19,9 +16,6 @@ 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(
@@ -61,8 +55,8 @@ class WorkUnit(BaseEntity):
     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
+        from donna.workspaces.artifacts import ArtifactRenderContext
+        from donna.workspaces.templates import RenderMode
 
         render_context = ArtifactRenderContext(
             primary_mode=RenderMode.execute,
@@ -72,17 +66,9 @@ class WorkUnit(BaseEntity):
         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()
-        ##########################
+        instant_output([log_cell])
 
         changes = list(operation_kind.execute_section(task, self, operation))
 

donna/machine/templates.py

@@ -28,11 +28,12 @@ class Directive(Primitive, ABC):
         self,
         context: Context,
         *argv: Any,
+        **kwargs: Any,
     ) -> Result[Any, ErrorsList]:
-        from donna.world import templates as world_templates
+        from donna.workspaces import templates as world_templates
 
         render_mode = context["render_mode"]
-        arguments_result = self._prepare_arguments(context, *argv)
+        arguments_result = self._prepare_arguments(context, *argv, **kwargs)
         if arguments_result.is_err():
             return arguments_result
 
@@ -52,6 +53,7 @@ class Directive(Primitive, ABC):
         self,
         context: Context,
         *argv: Any,
+        **kwargs: Any,
     ) -> PreparedDirectiveResult:
         return Ok(argv)
 

donna/primitives/artifacts/specification.py

@@ -1,8 +1,10 @@
 from typing import TYPE_CHECKING, ClassVar
 
+import pydantic
+
 from donna.machine.artifacts import ArtifactSectionConfig
 from donna.machine.primitives import Primitive
-from donna.world.sources.markdown import MarkdownSectionMixin
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     pass
@@ -16,5 +18,14 @@ class Text(MarkdownSectionMixin, Primitive):
     config_class: ClassVar[type[TextConfig]] = TextConfig
 
 
+class SpecificationConfig(ArtifactSectionConfig):
+    @pydantic.field_validator("tags", mode="after")
+    @classmethod
+    def ensure_specification_tag(cls, value: list[str]) -> list[str]:
+        if "specification" in value:
+            return value
+        return [*value, "specification"]
+
+
 class Specification(MarkdownSectionMixin, Primitive):
-    pass
+    config_class: ClassVar[type[SpecificationConfig]] = SpecificationConfig

donna/primitives/artifacts/workflow.py

@@ -1,5 +1,7 @@
 from typing import TYPE_CHECKING, ClassVar, Iterable, 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, unwrap_to_error
@@ -8,8 +10,8 @@ from donna.machine.artifacts import Artifact, ArtifactSection, ArtifactSectionCo
 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
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change
@@ -97,6 +99,13 @@ def find_workflow_sections(start_operation_id: ArtifactSectionId, artifact: Arti
 class WorkflowConfig(ArtifactSectionConfig):
     start_operation_id: ArtifactSectionId
 
+    @pydantic.field_validator("tags", mode="after")
+    @classmethod
+    def ensure_workflow_tag(cls, value: list[str]) -> list[str]:
+        if "workflow" in value:
+            return value
+        return [*value, "workflow"]
+
 
 class WorkflowMeta(ArtifactSectionMeta):
     start_operation_id: ArtifactSectionId

donna/primitives/directives/list.py

@@ -0,0 +1,86 @@
+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 FullArtifactIdPattern
+from donna.machine.templates import Directive, PreparedDirectiveResult
+from donna.protocol.modes import mode
+
+
+class EnvironmentError(core_errors.EnvironmentError):
+    cell_kind: str = "directive_error"
+
+
+class ListInvalidArguments(EnvironmentError):
+    code: str = "donna.directives.list.invalid_arguments"
+    message: str = (
+        "List directive requires exactly one positional argument: artifact_id_pattern (got {error.provided_count})."
+    )
+    ways_to_fix: list[str] = ["Provide exactly one argument: artifact_id_pattern."]
+    provided_count: int
+
+
+class ListInvalidKeyword(EnvironmentError):
+    code: str = "donna.directives.list.invalid_keyword"
+    message: str = "List directive accepts only the `tags` keyword argument (got {error.keyword})."
+    ways_to_fix: list[str] = ["Remove unsupported keyword arguments."]
+    keyword: str
+
+
+class ListInvalidTags(EnvironmentError):
+    code: str = "donna.directives.list.invalid_tags"
+    message: str = "List directive `tags` must be a list of strings."
+    ways_to_fix: list[str] = ["Provide tags as a list of strings, e.g. tags=['tag1', 'tag2']."]
+
+
+class List(Directive):
+    def _prepare_arguments(  # noqa: CCR001
+        self,
+        context: Context,
+        *argv: Any,
+        **kwargs: Any,
+    ) -> PreparedDirectiveResult:
+        if argv is None or len(argv) != 1:
+            return Err([ListInvalidArguments(provided_count=0 if argv is None else len(argv))])
+
+        for keyword in kwargs:
+            if keyword != "tags":
+                return Err([ListInvalidKeyword(keyword=keyword)])
+
+        artifact_pattern_result = FullArtifactIdPattern.parse(str(argv[0]))
+        errors = artifact_pattern_result.err()
+        if errors is not None:
+            return Err(errors)
+
+        artifact_pattern = artifact_pattern_result.ok()
+        assert artifact_pattern is not None
+
+        tags = kwargs.get("tags")
+        if tags is None:
+            tags_list: list[str] = []
+        elif isinstance(tags, (list, tuple, set)):
+            tags_list = [str(tag) for tag in tags]
+        else:
+            return Err([ListInvalidTags()])
+
+        return Ok((artifact_pattern, tags_list))
+
+    def render_view(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
+        protocol = mode().value
+        tags_args = " ".join(f"--tag '{tag}'" for tag in tags)
+        tag_suffix = f" {tags_args}" if tags_args else ""
+        return Ok(f"{artifact_pattern} (donna -p {protocol} artifacts list '{artifact_pattern}'{tag_suffix})")
+
+    def render_analyze(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
+        if not tags:
+            return Ok(f"$$donna {self.analyze_id} {artifact_pattern} donna$$")
+
+        tags_marker = ",".join(tags)
+        return Ok(f"$$donna {self.analyze_id} {artifact_pattern} tags={tags_marker} donna$$")

donna/primitives/directives/view.py

@@ -5,7 +5,7 @@ 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.domain.ids import FullArtifactIdPattern
 from donna.machine.templates import Directive, PreparedDirectiveResult
 from donna.protocol.modes import mode
 
@@ -16,30 +16,71 @@ class EnvironmentError(core_errors.EnvironmentError):
 
 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."]
+    message: str = (
+        "View directive requires exactly one positional argument: artifact_id_pattern (got {error.provided_count})."
+    )
+    ways_to_fix: list[str] = ["Provide exactly one argument: artifact_id_pattern."]
     provided_count: int
 
 
+class ViewInvalidKeyword(EnvironmentError):
+    code: str = "donna.directives.view.invalid_keyword"
+    message: str = "View directive accepts only the `tags` keyword argument (got {error.keyword})."
+    ways_to_fix: list[str] = ["Remove unsupported keyword arguments."]
+    keyword: str
+
+
+class ViewInvalidTags(EnvironmentError):
+    code: str = "donna.directives.view.invalid_tags"
+    message: str = "View directive `tags` must be a list of strings."
+    ways_to_fix: list[str] = ["Provide tags as a list of strings, e.g. tags=['tag1', 'tag2']."]
+
+
 class View(Directive):
-    def _prepare_arguments(
+    def _prepare_arguments(  # noqa: CCR001
         self,
         context: Context,
         *argv: Any,
+        **kwargs: 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()
+        for keyword in kwargs:
+            if keyword != "tags":
+                return Err([ViewInvalidKeyword(keyword=keyword)])
+
+        artifact_pattern_result = FullArtifactIdPattern.parse(str(argv[0]))
+        errors = artifact_pattern_result.err()
         if errors is not None:
             return Err(errors)
 
-        artifact_id = artifact_id_result.ok()
-        assert artifact_id is not None
+        artifact_pattern = artifact_pattern_result.ok()
+        assert artifact_pattern is not None
+
+        tags = kwargs.get("tags")
+        if tags is None:
+            tags_list: list[str] = []
+        elif isinstance(tags, (list, tuple, set)):
+            tags_list = [str(tag) for tag in tags]
+        else:
+            return Err([ViewInvalidTags()])
 
-        return Ok((artifact_id,))
+        return Ok((artifact_pattern, tags_list))
 
-    def render_view(self, context: Context, specification_id: FullArtifactId) -> Result[Any, ErrorsList]:
+    def render_view(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
         protocol = mode().value
-        return Ok(f"donna -p {protocol} artifacts view '{specification_id}'")
+        tags_args = " ".join(f"--tag '{tag}'" for tag in tags)
+        tag_suffix = f" {tags_args}" if tags_args else ""
+        return Ok(f"{artifact_pattern} (donna -p {protocol} artifacts view '{artifact_pattern}'{tag_suffix})")
+
+    def render_analyze(
+        self, context: Context, artifact_pattern: FullArtifactIdPattern, tags: list[str]
+    ) -> Result[Any, ErrorsList]:
+        if not tags:
+            return Ok(f"$$donna {self.analyze_id} {artifact_pattern} donna$$")
+
+        tags_marker = ",".join(tags)
+        return Ok(f"$$donna {self.analyze_id} {artifact_pattern} tags={tags_marker} donna$$")

donna/primitives/operations/finish_workflow.py

@@ -5,8 +5,10 @@ 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
+from donna.protocol.cells import Cell
+from donna.protocol.utils import instant_output
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change
@@ -21,6 +23,15 @@ class FinishWorkflow(MarkdownSectionMixin, OperationKind):
     def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
         from donna.machine.changes import ChangeFinishTask
 
+        output_text = operation.description
+
+        output_cell = Cell.build_markdown(
+            kind="operation_output",
+            content=output_text,
+            operation_id=str(unit.operation_id),
+        )
+        instant_output([output_cell])
+
         yield ChangeFinishTask(task_id=task.id)
 
     config_class: ClassVar[type[FinishWorkflowConfig]] = FinishWorkflowConfig

donna/primitives/operations/output.py

@@ -0,0 +1,87 @@
+from typing import TYPE_CHECKING, ClassVar, Iterator, cast
+
+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.protocol.cells import Cell
+from donna.protocol.utils import instant_output
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
+
+if TYPE_CHECKING:
+    from donna.machine.changes import Change
+    from donna.machine.tasks import Task, WorkUnit
+
+
+class OutputMissingNextOperation(ArtifactValidationError):
+    code: str = "donna.workflows.output_missing_next_operation_id"
+    message: str = "Output operation `{error.section_id}` must define `next_operation_id`."
+    ways_to_fix: list[str] = [
+        'Add `next_operation_id = "<next_operation_id>"` to the operation config block.',
+    ]
+
+
+class OutputConfig(OperationConfig):
+    next_operation_id: ArtifactSectionId | None = None
+
+
+class OutputMeta(OperationMeta):
+    next_operation_id: ArtifactSectionId | None = None
+
+
+class Output(MarkdownSectionMixin, OperationKind):
+    config_class: ClassVar[type[OutputConfig]] = OutputConfig
+
+    def markdown_construct_meta(
+        self,
+        artifact_id: "FullArtifactId",
+        source: markdown.SectionSource,
+        section_config: ArtifactSectionConfig,
+        description: str,
+        primary: bool = False,
+    ) -> Result[ArtifactSectionMeta, ErrorsList]:
+        output_config = cast(OutputConfig, section_config)
+
+        allowed_transitions: set[ArtifactSectionId] = set()
+        if output_config.next_operation_id is not None:
+            allowed_transitions.add(output_config.next_operation_id)
+
+        return Ok(
+            OutputMeta(
+                fsm_mode=output_config.fsm_mode,
+                allowed_transtions=allowed_transitions,
+                next_operation_id=output_config.next_operation_id,
+            )
+        )
+
+    def execute_section(self, task: "Task", unit: "WorkUnit", operation: ArtifactSection) -> Iterator["Change"]:
+        from donna.machine.changes import ChangeAddWorkUnit
+
+        meta = cast(OutputMeta, operation.meta)
+
+        output_text = operation.description
+
+        output_cell = Cell.build_markdown(
+            kind="operation_output",
+            content=output_text,
+            operation_id=str(unit.operation_id),
+        )
+        instant_output([output_cell])
+
+        next_operation_id = meta.next_operation_id
+        assert next_operation_id is not None
+        full_operation_id = unit.operation_id.full_artifact_id.to_full_local(next_operation_id)
+
+        yield ChangeAddWorkUnit(task_id=task.id, operation_id=full_operation_id)
+
+    def validate_section(self, artifact: Artifact, section_id: ArtifactSectionId) -> Result[None, ErrorsList]:
+        section = artifact.get_section(section_id).unwrap()
+        meta = cast(OutputMeta, section.meta)
+
+        if meta.next_operation_id is None:
+            return Err([OutputMissingNextOperation(artifact_id=artifact.id, section_id=section_id)])
+
+        return Ok(None)

donna/primitives/operations/request_action.py

@@ -10,8 +10,8 @@ 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
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change
@@ -74,13 +74,7 @@ class RequestAction(MarkdownSectionMixin, OperationKind):
     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)
+        request_text = operation.description
 
         full_operation_id = unit.operation_id
 

donna/primitives/operations/run_script.py

@@ -12,8 +12,8 @@ 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
+from donna.workspaces import markdown
+from donna.workspaces.sources.markdown import MarkdownSectionMixin
 
 if TYPE_CHECKING:
     from donna.machine.changes import Change

donna/protocol/utils.py

@@ -0,0 +1,22 @@
+import sys
+
+from donna.protocol.cells import Cell
+from donna.protocol.modes import get_cell_formatter
+
+
+def instant_output(cells: list[Cell]) -> None:
+    if not cells:
+        return
+
+    formatter = get_cell_formatter()
+
+    formatted_cells: list[bytes] = []
+    for cell in cells:
+        # TODO: we should refactor that hardcoded check somehow
+        if cell.kind == "donna_log":
+            formatted_cells.append(formatter.format_log(cell, single_mode=True))
+        else:
+            formatted_cells.append(formatter.format_cell(cell, single_mode=False))
+
+    sys.stdout.buffer.write(b"\n\n".join(formatted_cells) + b"\n\n")
+    sys.stdout.buffer.flush()