agent-folder-workspace 0.1.0__py3-none-any.whl

agent_folder_workspace/__init__.py

@@ -0,0 +1,42 @@
+"""Lazy, offline folder exploration for agents."""
+
+from __future__ import annotations
+
+from agent_folder_workspace.config import BackendPolicy, WorkspaceConfig
+from agent_folder_workspace.errors import (
+    FolderWorkspaceError,
+    InputValidationError,
+    NodeNotFoundError,
+    ResourceLimitError,
+    StaleCursorError,
+)
+from agent_folder_workspace.ids import stable_node_id
+from agent_folder_workspace.models import (
+    CapabilityReportV1,
+    ContentPageV1,
+    DiagnosticV1,
+    NodePageV1,
+    NodeV1,
+    SearchPageV1,
+)
+from agent_folder_workspace.workspace import FolderWorkspace
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BackendPolicy",
+    "CapabilityReportV1",
+    "ContentPageV1",
+    "DiagnosticV1",
+    "FolderWorkspace",
+    "FolderWorkspaceError",
+    "InputValidationError",
+    "NodeNotFoundError",
+    "NodePageV1",
+    "NodeV1",
+    "ResourceLimitError",
+    "SearchPageV1",
+    "StaleCursorError",
+    "WorkspaceConfig",
+    "stable_node_id",
+]

agent_folder_workspace/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m agent_folder_workspace`` on every supported platform."""
+
+from agent_folder_workspace.cli import app
+
+if __name__ == "__main__":
+    app()

agent_folder_workspace/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Built-in lazy file adapters."""
+
+from agent_folder_workspace.adapters.manager import AdapterManager
+
+__all__ = ["AdapterManager"]

agent_folder_workspace/adapters/base.py

@@ -0,0 +1,93 @@
+"""Shared adapter contracts."""
+
+from __future__ import annotations
+
+import mmap
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+from agent_folder_workspace.config import WorkspaceConfig
+from agent_folder_workspace.models import ContentStatus, DiagnosticV1, NodeKind, NodeV1
+
+
+@dataclass(frozen=True, slots=True)
+class VirtualNodeSpec:
+    name: str
+    kind: NodeKind
+    logical_path: str
+    child_count: int | None = None
+    size: int | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    source_part: str | None = None
+    source_offset: int | None = None
+    source_length: int | None = None
+    adapter: str | None = None
+    content_status: ContentStatus = ContentStatus.READY
+    diagnostics: list[DiagnosticV1] = field(default_factory=list)
+
+
+@dataclass(frozen=True, slots=True)
+class ReadResult:
+    items: list[Any]
+    total: int
+    text: str | None = None
+    diagnostics: list[DiagnosticV1] = field(default_factory=list)
+
+
+class Adapter(Protocol):
+    def children(
+        self, node: NodeV1, source: Path, config: WorkspaceConfig
+    ) -> list[VirtualNodeSpec]: ...
+
+    def read(
+        self,
+        node: NodeV1,
+        source: Path,
+        offset: int,
+        limit: int,
+        config: WorkspaceConfig,
+    ) -> ReadResult: ...
+
+    def read_binary_part(
+        self,
+        node: NodeV1,
+        source: Path,
+        offset: int,
+        length: int,
+        config: WorkspaceConfig,
+    ) -> tuple[bytes, int]: ...
+
+
+class BaseAdapter:
+    def children(
+        self, node: NodeV1, source: Path, config: WorkspaceConfig
+    ) -> list[VirtualNodeSpec]:
+        return []
+
+    def read(
+        self,
+        node: NodeV1,
+        source: Path,
+        offset: int,
+        limit: int,
+        config: WorkspaceConfig,
+    ) -> ReadResult:
+        return ReadResult(items=[], total=0)
+
+    def read_binary_part(
+        self,
+        node: NodeV1,
+        source: Path,
+        offset: int,
+        length: int,
+        config: WorkspaceConfig,
+    ) -> tuple[bytes, int]:
+        total = source.stat().st_size
+        if total == 0 or offset >= total:
+            return b"", total
+        with (
+            source.open("rb") as handle,
+            mmap.mmap(handle.fileno(), length=0, access=mmap.ACCESS_READ) as mapped,
+        ):
+            return bytes(mapped[offset : offset + length]), total