donna 0.2.0__py3-none-any.whl

donna/world/templates.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import enum
+import importlib
+import importlib.util
+from typing import TYPE_CHECKING
+
+import jinja2
+
+from donna.core import errors as core_errors
+from donna.core.errors import EnvironmentErrorsProxy, ErrorsList
+from donna.core.result import Err, Ok, Result
+from donna.domain.ids import FullArtifactId
+from donna.machine.templates import Directive
+from donna.world import errors as world_errors
+
+if TYPE_CHECKING:
+    from donna.world.artifacts import ArtifactRenderContext
+
+
+class RenderMode(enum.Enum):
+    """Modes for rendering artifacts.
+
+    Donna could render artifacts for different purposes, for example:
+
+    - to be displayed to the agent when Donna is used via CLI
+    - TODO: to be displayed to the agent when Donna is used as an agent tool
+    - TODO: to be displayed to the agent when Donna is used as an MCP server
+    - to be used for analysis by Donna itself
+
+    In each mode Donna can produce different outputs.
+
+    For example, it can output CLI commands in view/execute mode, tool specifications in tool mode,
+    special markup in analyze mode, etc.
+    """
+
+    view = "view"
+    execute = "execute"
+    analysis = "analysis"
+
+
+_ENVIRONMENT = None
+
+
+def _is_importable_module(name: str) -> bool:
+    return importlib.util.find_spec(name) is not None
+
+
+class DirectivePathBuilder:
+    def __init__(self, parts: tuple[str, ...]) -> None:
+        self._parts = parts
+
+    def __getattr__(self, name: str) -> "DirectivePathBuilder":
+        return DirectivePathBuilder(self._parts + (name,))
+
+    def __getitem__(self, name: str) -> "DirectivePathBuilder":
+        return DirectivePathBuilder(self._parts + (name,))
+
+    @jinja2.pass_context
+    def __call__(self, context: jinja2.runtime.Context, *argv: object) -> object:  # noqa: CCR001
+        artifact_id = context.get("artifact_id")
+        directive_path = ".".join(self._parts)
+        if len(self._parts) < 2:
+            raise EnvironmentErrorsProxy(
+                [world_errors.DirectivePathIncomplete(path=directive_path, artifact_id=artifact_id)]
+            )
+
+        module_path = ".".join(self._parts[:-1])
+        directive_name = self._parts[-1]
+
+        try:
+            module = importlib.import_module(module_path)
+        except ModuleNotFoundError as exc:
+            raise EnvironmentErrorsProxy(
+                [world_errors.DirectiveModuleNotImportable(module_path=module_path, artifact_id=artifact_id)]
+            ) from exc
+        except core_errors.InternalError:
+            raise
+        except Exception as exc:
+            raise EnvironmentErrorsProxy(
+                [
+                    world_errors.DirectiveUnexpectedError(
+                        directive_path=directive_path,
+                        details=str(exc),
+                        artifact_id=artifact_id,
+                    )
+                ]
+            ) from exc
+
+        try:
+            directive = getattr(module, directive_name)
+        except AttributeError as exc:
+            raise EnvironmentErrorsProxy(
+                [
+                    world_errors.DirectiveNotAvailable(
+                        module_path=module_path,
+                        directive_name=directive_name,
+                        artifact_id=artifact_id,
+                    )
+                ]
+            ) from exc
+
+        if not isinstance(directive, Directive):
+            raise EnvironmentErrorsProxy(
+                [
+                    world_errors.DirectiveNotDirective(
+                        module_path=module_path,
+                        directive_name=directive_name,
+                        artifact_id=artifact_id,
+                    )
+                ]
+            )
+
+        try:
+            result = directive.apply_directive(context, *argv)
+        except EnvironmentErrorsProxy:
+            raise
+        except core_errors.InternalError:
+            raise
+        except Exception as exc:
+            raise EnvironmentErrorsProxy(
+                [
+                    world_errors.DirectiveUnexpectedError(
+                        directive_path=directive_path,
+                        details=str(exc),
+                        artifact_id=artifact_id,
+                    )
+                ]
+            ) from exc
+
+        if result.is_err():
+            raise EnvironmentErrorsProxy(result.unwrap_err())
+
+        return result.unwrap()
+
+
+class DirectivePathUndefined(jinja2.Undefined):
+    def __getattr__(self, name: str) -> object:
+        if not self._undefined_name or not _is_importable_module(self._undefined_name):
+            return jinja2.Undefined(name=f"{self._undefined_name}.{name}")
+
+        return DirectivePathBuilder((self._undefined_name, name))
+
+
+def env() -> jinja2.Environment:
+    global _ENVIRONMENT
+
+    if _ENVIRONMENT is not None:
+        return _ENVIRONMENT
+
+    _ENVIRONMENT = jinja2.Environment(
+        loader=None,
+        # we render into markdown, not into HTML
+        # i.e. before (possible) displaying in the browser,
+        # the result of the jinja2 render will be rendered by markdown renderer
+        # markdown renderer should take care of escaping
+        autoescape=jinja2.select_autoescape(default=False, default_for_string=False),
+        auto_reload=False,
+        extensions=["jinja2.ext.do", "jinja2.ext.loopcontrols", "jinja2.ext.debug"],
+        undefined=DirectivePathUndefined,
+    )
+
+    return _ENVIRONMENT
+
+
+def render(
+    artifact_id: FullArtifactId, template: str, render_context: "ArtifactRenderContext"
+) -> Result[str, ErrorsList]:
+    context = {"render_mode": render_context.primary_mode, "artifact_id": artifact_id}
+
+    if render_context.current_task is not None:
+        context["current_task"] = render_context.current_task
+
+    if render_context.current_work_unit is not None:
+        context["current_work_unit"] = render_context.current_work_unit
+
+    try:
+        template_obj = env().from_string(template)
+        return Ok(template_obj.render(**context))
+    except EnvironmentErrorsProxy as exc:
+        return Err(exc.arguments["errors"])

donna/world/tmp.py

@@ -0,0 +1,33 @@
+import pathlib
+import shutil
+import time
+
+from donna.cli.types import FullArtifactIdArgument
+from donna.world.config import config, config_dir
+
+
+def dir() -> pathlib.Path:
+    cfg = config()
+    tmp_path = cfg.tmp_dir
+
+    if not cfg.tmp_dir.is_absolute():
+        tmp_path = config_dir() / tmp_path
+
+    tmp_path.mkdir(parents=True, exist_ok=True)
+
+    return tmp_path
+
+
+def file_for_artifact(artifact_id: FullArtifactIdArgument, extention: str) -> pathlib.Path:
+    directory = dir()
+
+    directory.mkdir(parents=True, exist_ok=True)
+
+    normalized_extension = extention.lstrip(".")
+    artifact_file_name = f"{str(artifact_id).replace('/', '.')}.{int(time.time() * 1000)}.{normalized_extension}"
+
+    return directory / artifact_file_name
+
+
+def clear() -> None:
+    shutil.rmtree(dir())

donna/world/worlds/base.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from donna.core.entities import BaseEntity
+from donna.core.errors import ErrorsList
+from donna.core.result import Result
+from donna.domain.ids import ArtifactId, FullArtifactIdPattern, WorldId
+from donna.machine.artifacts import Artifact
+from donna.machine.primitives import Primitive
+
+if TYPE_CHECKING:
+    from donna.world.artifacts import ArtifactRenderContext
+    from donna.world.config import WorldConfig
+
+
+class World(BaseEntity, ABC):
+    id: WorldId
+    readonly: bool = True
+    session: bool = False
+
+    @abstractmethod
+    def has(self, artifact_id: ArtifactId) -> bool: ...  # noqa: E704
+
+    @abstractmethod
+    def fetch(  # noqa: E704
+        self, artifact_id: ArtifactId, render_context: "ArtifactRenderContext"
+    ) -> Result[Artifact, ErrorsList]: ...
+
+    @abstractmethod
+    def fetch_source(self, artifact_id: ArtifactId) -> Result[bytes, ErrorsList]: ...  # noqa: E704
+
+    @abstractmethod
+    def update(  # noqa: E704
+        self, artifact_id: ArtifactId, content: bytes, extension: str
+    ) -> Result[None, ErrorsList]: ...  # noqa: E704
+
+    @abstractmethod
+    def file_extension_for(self, artifact_id: ArtifactId) -> Result[str, ErrorsList]: ...  # noqa: E704
+
+    @abstractmethod
+    def list_artifacts(self, pattern: FullArtifactIdPattern) -> list[ArtifactId]: ...  # noqa: E704
+
+    # These two methods are intended for storing world state (e.g., session data)
+    # It is an open question if the world state is an artifact itself or something else
+    # For the artifact: uniform API for storing/loading data
+    # Against the artifact:
+    # - session data MUST be accessible only by Donna => no one should be able to read/write/list it
+    # - session data will require an additonal kind(s) of artifact(s) just for that purpose
+    # - session data may change more frequently than regular artifacts
+
+    @abstractmethod
+    def read_state(self, name: str) -> Result[bytes | None, ErrorsList]: ...  # noqa: E704
+
+    @abstractmethod
+    def write_state(self, name: str, content: bytes) -> Result[None, ErrorsList]: ...  # noqa: E704
+
+    def initialize(self, reset: bool = False) -> None:
+        pass
+
+    @abstractmethod
+    def is_initialized(self) -> bool: ...  # noqa: E704
+
+
+class WorldConstructor(Primitive, ABC):
+    @abstractmethod
+    def construct_world(self, config: WorldConfig) -> World: ...  # noqa: E704

donna/world/worlds/filesystem.py

@@ -0,0 +1,189 @@
+import pathlib
+import shutil
+from typing import TYPE_CHECKING, cast
+
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.domain.ids import ArtifactId, FullArtifactId, FullArtifactIdPattern
+from donna.machine.artifacts import Artifact
+from donna.world import errors as world_errors
+from donna.world.artifacts import ArtifactRenderContext
+from donna.world.artifacts_discovery import ArtifactListingNode, list_artifacts_by_pattern
+from donna.world.worlds.base import World as BaseWorld
+from donna.world.worlds.base import WorldConstructor
+
+if TYPE_CHECKING:
+    from donna.world.config import SourceConfigValue, WorldConfig
+
+
+class World(BaseWorld):
+    path: pathlib.Path
+
+    def _artifact_listing_root(self) -> ArtifactListingNode | None:
+        if not self.path.exists():
+            return None
+
+        return cast(ArtifactListingNode, self.path)
+
+    def _artifact_path(self, artifact_id: ArtifactId, extension: str) -> pathlib.Path:
+        return self.path / f"{artifact_id.replace(':', '/')}{extension}"
+
+    def _resolve_artifact_file(self, artifact_id: ArtifactId) -> Result[pathlib.Path | None, ErrorsList]:
+        artifact_path = self.path / artifact_id.replace(":", "/")
+        parent = artifact_path.parent
+
+        if not parent.exists():
+            return Ok(None)
+
+        from donna.world.config import config
+
+        supported_extensions = config().supported_extensions()
+        matches = [
+            path
+            for path in parent.glob(f"{artifact_path.name}.*")
+            if path.is_file() and path.suffix.lower() in supported_extensions
+        ]
+
+        if not matches:
+            return Ok(None)
+
+        if len(matches) > 1:
+            return Err([world_errors.ArtifactMultipleFiles(artifact_id=artifact_id, world_id=self.id)])
+
+        return Ok(matches[0])
+
+    def _get_source_by_filename(
+        self, artifact_id: ArtifactId, filename: str
+    ) -> Result["SourceConfigValue", ErrorsList]:
+        from donna.world.config import config
+
+        extension = pathlib.Path(filename).suffix
+        source_config = config().find_source_for_extension(extension)
+        if source_config is None:
+            return Err(
+                [
+                    world_errors.UnsupportedArtifactSourceExtension(
+                        artifact_id=artifact_id,
+                        world_id=self.id,
+                        extension=extension,
+                    )
+                ]
+            )
+
+        return Ok(source_config)
+
+    def has(self, artifact_id: ArtifactId) -> bool:
+        resolve_result = self._resolve_artifact_file(artifact_id)
+        if resolve_result.is_err():
+            return True
+
+        return resolve_result.unwrap() is not None
+
+    @unwrap_to_error
+    def fetch(self, artifact_id: ArtifactId, render_context: ArtifactRenderContext) -> Result[Artifact, ErrorsList]:
+        path = self._resolve_artifact_file(artifact_id).unwrap()
+        if path is None:
+            return Err([world_errors.ArtifactNotFound(artifact_id=artifact_id, world_id=self.id)])
+
+        content_bytes = path.read_bytes()
+        full_id = FullArtifactId((self.id, artifact_id))
+
+        extension = pathlib.Path(path.name).suffix
+        from donna.world.config import config
+
+        source_config = config().find_source_for_extension(extension)
+        if source_config is None:
+            return Err(
+                [
+                    world_errors.UnsupportedArtifactSourceExtension(
+                        artifact_id=artifact_id,
+                        world_id=self.id,
+                        extension=extension,
+                    )
+                ]
+            )
+
+        return Ok(source_config.construct_artifact_from_bytes(full_id, content_bytes, render_context).unwrap())
+
+    @unwrap_to_error
+    def fetch_source(self, artifact_id: ArtifactId) -> Result[bytes, ErrorsList]:
+        path = self._resolve_artifact_file(artifact_id).unwrap()
+        if path is None:
+            return Err([world_errors.ArtifactNotFound(artifact_id=artifact_id, world_id=self.id)])
+
+        return Ok(path.read_bytes())
+
+    def update(self, artifact_id: ArtifactId, content: bytes, extension: str) -> Result[None, ErrorsList]:
+        if self.readonly:
+            return Err([world_errors.WorldReadonly(world_id=self.id)])
+
+        path = self._artifact_path(artifact_id, extension)
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(content)
+        return Ok(None)
+
+    @unwrap_to_error
+    def file_extension_for(self, artifact_id: ArtifactId) -> Result[str, ErrorsList]:
+        path = self._resolve_artifact_file(artifact_id).unwrap()
+        if path is None:
+            return Err([world_errors.ArtifactNotFound(artifact_id=artifact_id, world_id=self.id)])
+
+        return Ok(path.suffix)
+
+    def read_state(self, name: str) -> Result[bytes | None, ErrorsList]:
+        if not self.session:
+            return Err([world_errors.WorldStateStorageUnsupported(world_id=self.id)])
+
+        path = self.path / name
+
+        if not path.exists():
+            return Ok(None)
+
+        return Ok(path.read_bytes())
+
+    def write_state(self, name: str, content: bytes) -> Result[None, ErrorsList]:
+        if self.readonly:
+            return Err([world_errors.WorldReadonly(world_id=self.id)])
+
+        if not self.session:
+            return Err([world_errors.WorldStateStorageUnsupported(world_id=self.id)])
+
+        path = self.path / name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(content)
+        return Ok(None)
+
+    def list_artifacts(self, pattern: FullArtifactIdPattern) -> list[ArtifactId]:  # noqa: CCR001
+        return list_artifacts_by_pattern(
+            world_id=self.id,
+            root=self._artifact_listing_root(),
+            pattern=pattern,
+        )
+
+    def initialize(self, reset: bool = False) -> None:
+        if self.readonly:
+            return
+
+        if self.path.exists() and reset:
+            shutil.rmtree(self.path)
+
+        self.path.mkdir(parents=True, exist_ok=True)
+
+    def is_initialized(self) -> bool:
+        return self.path.exists()
+
+
+class FilesystemWorldConstructor(WorldConstructor):
+    def construct_world(self, config: "WorldConfig") -> World:
+        path_value = getattr(config, "path", None)
+
+        if path_value is None:
+            raise ValueError(f"World config '{config.id}' does not define a filesystem path")
+
+        return World(
+            id=config.id,
+            path=pathlib.Path(path_value),
+            readonly=config.readonly,
+            session=config.session,
+        )

donna/world/worlds/python.py

@@ -0,0 +1,196 @@
+import importlib
+import importlib.resources
+import pathlib
+from typing import TYPE_CHECKING, cast
+
+from donna.core.errors import ErrorsList
+from donna.core.result import Err, Ok, Result, unwrap_to_error
+from donna.domain.ids import ArtifactId, FullArtifactId, FullArtifactIdPattern, WorldId
+from donna.machine.artifacts import Artifact
+from donna.world import errors as world_errors
+from donna.world.artifacts import ArtifactRenderContext
+from donna.world.artifacts_discovery import ArtifactListingNode, list_artifacts_by_pattern
+from donna.world.worlds.base import World as BaseWorld
+from donna.world.worlds.base import WorldConstructor
+
+if TYPE_CHECKING:
+    from donna.world.config import SourceConfigValue, WorldConfig
+
+
+class Python(BaseWorld):
+    id: WorldId
+    readonly: bool = True
+    session: bool = False
+    package: str
+    artifacts_root: str
+
+    def _resource_root(self) -> importlib.resources.abc.Traversable | None:
+        package = self.artifacts_root
+
+        try:
+            return importlib.resources.files(package)
+        except ModuleNotFoundError:
+            return None
+
+    def _artifact_listing_root(self) -> ArtifactListingNode | None:
+        root = self._resource_root()
+        if root is None:
+            return None
+
+        return cast(ArtifactListingNode, root)
+
+    def _resolve_artifact_file(
+        self, artifact_id: ArtifactId
+    ) -> Result[importlib.resources.abc.Traversable | None, ErrorsList]:
+        parts = str(artifact_id).split(":")
+        if not parts:
+            return Ok(None)
+
+        resource_root = self._resource_root()
+        if resource_root is None:
+            return Ok(None)
+
+        *dirs, file_name = parts
+        resource_dir = resource_root
+
+        for part in dirs:
+            resource_dir = resource_dir.joinpath(part)
+
+        if not resource_dir.is_dir():
+            return Ok(None)
+
+        from donna.world.config import config
+
+        supported_extensions = config().supported_extensions()
+        matches = [
+            entry
+            for entry in resource_dir.iterdir()
+            if entry.is_file()
+            and entry.name.startswith(f"{file_name}.")
+            and pathlib.Path(entry.name).suffix.lower() in supported_extensions
+        ]
+
+        if not matches:
+            return Ok(None)
+
+        if len(matches) > 1:
+            return Err([world_errors.ArtifactMultipleFiles(artifact_id=artifact_id, world_id=self.id)])
+
+        return Ok(matches[0])
+
+    def _get_source_by_filename(
+        self, artifact_id: ArtifactId, filename: str
+    ) -> Result["SourceConfigValue", ErrorsList]:
+        from donna.world.config import config
+
+        extension = pathlib.Path(filename).suffix
+        source_config = config().find_source_for_extension(extension)
+        if source_config is None:
+            return Err(
+                [
+                    world_errors.UnsupportedArtifactSourceExtension(
+                        artifact_id=artifact_id,
+                        world_id=self.id,
+                        extension=extension,
+                    )
+                ]
+            )
+
+        return Ok(source_config)
+
+    def has(self, artifact_id: ArtifactId) -> bool:
+        resolve_result = self._resolve_artifact_file(artifact_id)
+        if resolve_result.is_err():
+            return True
+
+        return resolve_result.unwrap() is not None
+
+    @unwrap_to_error
+    def fetch(self, artifact_id: ArtifactId, render_context: ArtifactRenderContext) -> Result[Artifact, ErrorsList]:
+        resource_path = self._resolve_artifact_file(artifact_id).unwrap()
+        if resource_path is None:
+            return Err([world_errors.ArtifactNotFound(artifact_id=artifact_id, world_id=self.id)])
+
+        content_bytes = resource_path.read_bytes()
+        full_id = FullArtifactId((self.id, artifact_id))
+
+        extension = pathlib.Path(resource_path.name).suffix
+        from donna.world.config import config
+
+        source_config = config().find_source_for_extension(extension)
+        if source_config is None:
+            return Err(
+                [
+                    world_errors.UnsupportedArtifactSourceExtension(
+                        artifact_id=artifact_id,
+                        world_id=self.id,
+                        extension=extension,
+                    )
+                ]
+            )
+
+        return Ok(source_config.construct_artifact_from_bytes(full_id, content_bytes, render_context).unwrap())
+
+    @unwrap_to_error
+    def fetch_source(self, artifact_id: ArtifactId) -> Result[bytes, ErrorsList]:  # noqa: CCR001
+        resource_path = self._resolve_artifact_file(artifact_id).unwrap()
+        if resource_path is None:
+            return Err([world_errors.ArtifactNotFound(artifact_id=artifact_id, world_id=self.id)])
+
+        return Ok(resource_path.read_bytes())
+
+    def update(self, artifact_id: ArtifactId, content: bytes, extension: str) -> Result[None, ErrorsList]:
+        return Err([world_errors.WorldReadonly(world_id=self.id)])
+
+    @unwrap_to_error
+    def file_extension_for(self, artifact_id: ArtifactId) -> Result[str, ErrorsList]:
+        resource_path = self._resolve_artifact_file(artifact_id).unwrap()
+        if resource_path is None:
+            return Err([world_errors.ArtifactNotFound(artifact_id=artifact_id, world_id=self.id)])
+
+        return Ok(pathlib.Path(resource_path.name).suffix)
+
+    def list_artifacts(self, pattern: FullArtifactIdPattern) -> list[ArtifactId]:  # noqa: CCR001
+        return list_artifacts_by_pattern(
+            world_id=self.id,
+            root=self._artifact_listing_root(),
+            pattern=pattern,
+        )
+
+    # TODO: How can the state be represented in the Python world?
+    def read_state(self, name: str) -> Result[bytes | None, ErrorsList]:
+        return Err([world_errors.WorldStateStorageUnsupported(world_id=self.id)])
+
+    def write_state(self, name: str, content: bytes) -> Result[None, ErrorsList]:
+        return Err([world_errors.WorldStateStorageUnsupported(world_id=self.id)])
+
+    def initialize(self, reset: bool = False) -> None:
+        pass
+
+    def is_initialized(self) -> bool:
+        return True
+
+
+class PythonWorldConstructor(WorldConstructor):
+    def construct_world(self, config: "WorldConfig") -> Python:
+        package = getattr(config, "package", None)
+
+        if package is None:
+            raise ValueError(f"World config '{config.id}' does not define a python package")
+
+        module = importlib.import_module(str(package))
+        artifacts_root = getattr(module, "donna_artifacts_root", None)
+
+        if artifacts_root is None:
+            raise ValueError(f"Package '{package}' does not define donna_artifacts_root")
+
+        if not isinstance(artifacts_root, str):
+            raise ValueError(f"Package '{package}' defines invalid donna_artifacts_root")
+
+        return Python(
+            id=config.id,
+            package=str(package),
+            artifacts_root=artifacts_root,
+            readonly=config.readonly,
+            session=config.session,
+        )