avtomatika-worker 1.0b1__tar.gz → 1.0b2__tar.gz

{avtomatika_worker-1.0b1 → avtomatika_worker-1.0b2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: avtomatika-worker
-Version: 1.0b1
+Version: 1.0b2
 Summary: Worker SDK for the Avtomatika orchestrator.
-Project-URL: Homepage, https://github.com/avtomatila-ai/avtomatika-worker
-Project-URL: Bug Tracker, https://github.com/avtomatila-ai/avtomatika-worker/issues
+Project-URL: Homepage, https://github.com/avtomatika-ai/avtomatika-worker
+Project-URL: Bug Tracker, https://github.com/avtomatika-ai/avtomatika-worker/issues
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
@@ -13,15 +13,14 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp~=3.13.2
 Requires-Dist: python-json-logger~=4.0.0
-Requires-Dist: aioboto3~=13.0.0
+Requires-Dist: aioboto3~=15.5.0
+Requires-Dist: aiofiles~=25.1.0
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
 Requires-Dist: aioresponses; extra == "test"
 Requires-Dist: pytest-mock; extra == "test"
 Requires-Dist: pydantic; extra == "test"
-Requires-Dist: moto[server]; extra == "test"
-Requires-Dist: aiofiles; extra == "test"
 Provides-Extra: pydantic
 Requires-Dist: pydantic; extra == "pydantic"
 Dynamic: license-file
@@ -434,18 +433,92 @@ The `ORCHESTRATORS_CONFIG` variable must contain a JSON string. Each object in t
 
 
 
-### 5. Handling Large Files (S3 Payload Offloading)
+
+
+### 5. File System Helper (TaskFiles)
+
+To simplify working with temporary files and paths, the SDK provides a `TaskFiles` helper class. It automatically manages directory creation within the isolated task folder and provides an asynchronous interface for file operations. Just add an argument typed as `TaskFiles` to your handler:
+
+```python
+from avtomatika_worker import Worker, TaskFiles
+
+@worker.task("generate_report")
+async def generate_report(params: dict, files: TaskFiles, **kwargs):
+    # 1. Easy read/write
+    await files.write("data.json", '{"status": "ok"}')
+    content = await files.read("data.json")
+    
+    # 2. Get path (directory is created automatically)
+    output_path = await files.path_to("report.pdf")
+    
+    # 3. Check and list files
+    if await files.exists("input.jpg"):
+        file_list = await files.list()
+    
+    return {"data": {"report": output_path}}
+```
+
+**Available Methods (all asynchronous):**
+- `await path_to(name)` — returns the full path to a file (ensures the task directory exists).
+- `await read(name, mode='r')` — reads the entire file.
+- `await write(name, data, mode='w')` — writes data to a file.
+- `await list()` — lists filenames in the task directory.
+- `await exists(name)` — checks if a file exists.
+- `async with open(name, mode)` — async context manager for advanced usage.
+
+> **Note: Automatic Cleanup**
+>
+> The SDK automatically deletes the entire task directory (including everything created via `TaskFiles`) immediately after the task completes and the result is sent.
+
+### 6. Handling Large Files (S3 Payload Offloading)
 
 The SDK supports working with large files "out of the box" via S3-compatible storage.
 
--   **Automatic Download**: If a value in `params` is a URI of the form `s3://...`, the SDK will automatically download the file to the local disk and replace the URI in `params` with the local path.
--   **Automatic Upload**: If your handler returns a local file path in `data` (located within the `WORKER_PAYLOAD_DIR` directory), the SDK will automatically upload this file to S3 and replace the path with an `s3://` URI in the final result.
+-   **Automatic Download**: If a value in `params` is a URI of the form `s3://...`, the SDK will automatically download the file to the local disk and replace the URI in `params` with the local path. **If the URI ends with `/` (e.g., `s3://bucket/data/`), the SDK treats it as a folder prefix and recursively downloads all matching objects into a local directory.**
+-   **Automatic Upload**: If your handler returns a local file path in `data` (located within the `TASK_FILES_DIR` directory), the SDK will automatically upload this file to S3 and replace the path with an `s3://` URI in the final result. **If the path is a directory, the SDK recursively uploads all files within it.**
+
+This functionality is transparent to your code.
+
+#### S3 Example
+
+Suppose the orchestrator sends a task with `{"input_image": "s3://my-bucket/photo.jpg"}`:
+
+```python
+import os
+from avtomatika_worker import Worker, TaskFiles
+
+worker = Worker(worker_type="image-worker")
+
+@worker.task("process_image")
+async def handle_image(params: dict, files: TaskFiles, **kwargs):
+    # SDK has already downloaded the file.
+    # 'input_image' now contains a local path like '/tmp/payloads/task-id/photo.jpg'
+    local_input = params["input_image"]
+    local_output = await files.path_to("processed.png")
+
+    # Your logic here (using local files)
+    # ... image processing ...
+
+    # Return the local path of the result.
+    # The SDK will upload it back to S3 automatically.
+    return {
+        "status": "success",
+        "data": {
+            "output_image": local_output
+        }
+    }
+```
 
-This functionality is transparent to your code and only requires configuring environment variables for S3 access.
+This only requires configuring environment variables for S3 access (see Full Configuration Reference).
 
-### 6. WebSocket Support
+> **Important: S3 Consistency**
+>
+> The SDK **does not validate** that the Worker and Orchestrator share the same storage backend. You must ensure that:
+> 1. The Worker can reach the `S3_ENDPOINT_URL` used by the Orchestrator.
+> 2. The Worker's credentials allow reading from the buckets referenced in the incoming `s3://` URIs.
+> 3. The Worker's credentials allow writing to the `S3_DEFAULT_BUCKET`.
 
-If enabled, the SDK establishes a persistent WebSocket connection with the orchestrator to receive real-time commands, such as canceling an ongoing task.
+### 7. WebSocket Support
 
 ## Advanced Features
 
@@ -522,7 +595,7 @@ The worker is fully configured via environment variables.
 | `TASK_POLL_TIMEOUT`           | The timeout in seconds for polling for new tasks.                                                       | `30`                                   |
 | `TASK_POLL_ERROR_DELAY`       | The delay in seconds before retrying after a polling error.                                             | `5.0`                                  |
 | `IDLE_POLL_DELAY`             | The delay in seconds between polls when the worker is idle.                                             | `0.01`                                 |
-| `WORKER_PAYLOAD_DIR`          | The directory for temporarily storing files when working with S3.                                       | `/tmp/payloads`                        |
+| `TASK_FILES_DIR`          | The directory for temporarily storing files when working with S3.                                       | `/tmp/payloads`                        |
 | `S3_ENDPOINT_URL`             | The URL of the S3-compatible storage.                                                                   | -                                      |
 | `S3_ACCESS_KEY`               | The access key for S3.                                                                                  | -                                      |
 | `S3_SECRET_KEY`               | The secret key for S3.                                                                                  | -                                      |

avtomatika_worker-1.0b1/src/avtomatika_worker.egg-info/PKG-INFO → avtomatika_worker-1.0b2/README.md

@@ -1,31 +1,3 @@
-Metadata-Version: 2.4
-Name: avtomatika-worker
-Version: 1.0b1
-Summary: Worker SDK for the Avtomatika orchestrator.
-Project-URL: Homepage, https://github.com/avtomatila-ai/avtomatika-worker
-Project-URL: Bug Tracker, https://github.com/avtomatila-ai/avtomatika-worker/issues
-Classifier: Development Status :: 4 - Beta
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiohttp~=3.13.2
-Requires-Dist: python-json-logger~=4.0.0
-Requires-Dist: aioboto3~=13.0.0
-Provides-Extra: test
-Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-asyncio; extra == "test"
-Requires-Dist: aioresponses; extra == "test"
-Requires-Dist: pytest-mock; extra == "test"
-Requires-Dist: pydantic; extra == "test"
-Requires-Dist: moto[server]; extra == "test"
-Requires-Dist: aiofiles; extra == "test"
-Provides-Extra: pydantic
-Requires-Dist: pydantic; extra == "pydantic"
-Dynamic: license-file
-
 # Avtomatika Worker SDK
 
 This is an SDK for creating workers compatible with the **Avtomatika** orchestrator. The SDK handles all the complexity of interacting with the orchestrator, allowing you to focus on writing your business logic.
@@ -434,18 +406,92 @@ The `ORCHESTRATORS_CONFIG` variable must contain a JSON string. Each object in t
 
 
 
-### 5. Handling Large Files (S3 Payload Offloading)
+
+
+### 5. File System Helper (TaskFiles)
+
+To simplify working with temporary files and paths, the SDK provides a `TaskFiles` helper class. It automatically manages directory creation within the isolated task folder and provides an asynchronous interface for file operations. Just add an argument typed as `TaskFiles` to your handler:
+
+```python
+from avtomatika_worker import Worker, TaskFiles
+
+@worker.task("generate_report")
+async def generate_report(params: dict, files: TaskFiles, **kwargs):
+    # 1. Easy read/write
+    await files.write("data.json", '{"status": "ok"}')
+    content = await files.read("data.json")
+    
+    # 2. Get path (directory is created automatically)
+    output_path = await files.path_to("report.pdf")
+    
+    # 3. Check and list files
+    if await files.exists("input.jpg"):
+        file_list = await files.list()
+    
+    return {"data": {"report": output_path}}
+```
+
+**Available Methods (all asynchronous):**
+- `await path_to(name)` — returns the full path to a file (ensures the task directory exists).
+- `await read(name, mode='r')` — reads the entire file.
+- `await write(name, data, mode='w')` — writes data to a file.
+- `await list()` — lists filenames in the task directory.
+- `await exists(name)` — checks if a file exists.
+- `async with open(name, mode)` — async context manager for advanced usage.
+
+> **Note: Automatic Cleanup**
+>
+> The SDK automatically deletes the entire task directory (including everything created via `TaskFiles`) immediately after the task completes and the result is sent.
+
+### 6. Handling Large Files (S3 Payload Offloading)
 
 The SDK supports working with large files "out of the box" via S3-compatible storage.
 
--   **Automatic Download**: If a value in `params` is a URI of the form `s3://...`, the SDK will automatically download the file to the local disk and replace the URI in `params` with the local path.
--   **Automatic Upload**: If your handler returns a local file path in `data` (located within the `WORKER_PAYLOAD_DIR` directory), the SDK will automatically upload this file to S3 and replace the path with an `s3://` URI in the final result.
+-   **Automatic Download**: If a value in `params` is a URI of the form `s3://...`, the SDK will automatically download the file to the local disk and replace the URI in `params` with the local path. **If the URI ends with `/` (e.g., `s3://bucket/data/`), the SDK treats it as a folder prefix and recursively downloads all matching objects into a local directory.**
+-   **Automatic Upload**: If your handler returns a local file path in `data` (located within the `TASK_FILES_DIR` directory), the SDK will automatically upload this file to S3 and replace the path with an `s3://` URI in the final result. **If the path is a directory, the SDK recursively uploads all files within it.**
+
+This functionality is transparent to your code.
+
+#### S3 Example
+
+Suppose the orchestrator sends a task with `{"input_image": "s3://my-bucket/photo.jpg"}`:
+
+```python
+import os
+from avtomatika_worker import Worker, TaskFiles
+
+worker = Worker(worker_type="image-worker")
+
+@worker.task("process_image")
+async def handle_image(params: dict, files: TaskFiles, **kwargs):
+    # SDK has already downloaded the file.
+    # 'input_image' now contains a local path like '/tmp/payloads/task-id/photo.jpg'
+    local_input = params["input_image"]
+    local_output = await files.path_to("processed.png")
+
+    # Your logic here (using local files)
+    # ... image processing ...
+
+    # Return the local path of the result.
+    # The SDK will upload it back to S3 automatically.
+    return {
+        "status": "success",
+        "data": {
+            "output_image": local_output
+        }
+    }
+```
 
-This functionality is transparent to your code and only requires configuring environment variables for S3 access.
+This only requires configuring environment variables for S3 access (see Full Configuration Reference).
 
-### 6. WebSocket Support
+> **Important: S3 Consistency**
+>
+> The SDK **does not validate** that the Worker and Orchestrator share the same storage backend. You must ensure that:
+> 1. The Worker can reach the `S3_ENDPOINT_URL` used by the Orchestrator.
+> 2. The Worker's credentials allow reading from the buckets referenced in the incoming `s3://` URIs.
+> 3. The Worker's credentials allow writing to the `S3_DEFAULT_BUCKET`.
 
-If enabled, the SDK establishes a persistent WebSocket connection with the orchestrator to receive real-time commands, such as canceling an ongoing task.
+### 7. WebSocket Support
 
 ## Advanced Features
 
@@ -522,7 +568,7 @@ The worker is fully configured via environment variables.
 | `TASK_POLL_TIMEOUT`           | The timeout in seconds for polling for new tasks.                                                       | `30`                                   |
 | `TASK_POLL_ERROR_DELAY`       | The delay in seconds before retrying after a polling error.                                             | `5.0`                                  |
 | `IDLE_POLL_DELAY`             | The delay in seconds between polls when the worker is idle.                                             | `0.01`                                 |
-| `WORKER_PAYLOAD_DIR`          | The directory for temporarily storing files when working with S3.                                       | `/tmp/payloads`                        |
+| `TASK_FILES_DIR`          | The directory for temporarily storing files when working with S3.                                       | `/tmp/payloads`                        |
 | `S3_ENDPOINT_URL`             | The URL of the S3-compatible storage.                                                                   | -                                      |
 | `S3_ACCESS_KEY`               | The access key for S3.                                                                                  | -                                      |
 | `S3_SECRET_KEY`               | The secret key for S3.                                                                                  | -                                      |

{avtomatika_worker-1.0b1 → avtomatika_worker-1.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "avtomatika-worker"
-version = "1.0.b1"
+version = "1.0.b2"
 description = "Worker SDK for the Avtomatika orchestrator."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,7 +17,8 @@ classifiers = [
 dependencies = [
     "aiohttp~=3.13.2",
     "python-json-logger~=4.0.0",
-    "aioboto3~=13.0.0",
+    "aioboto3~=15.5.0",
+    "aiofiles~=25.1.0",
 ]
 
 [project.optional-dependencies]
@@ -27,14 +28,12 @@ test = [
     "aioresponses",
     "pytest-mock",
     "pydantic",
-    "moto[server]",
-    "aiofiles",
 ]
 pydantic = ["pydantic"]
 
 [project.urls]
-"Homepage" = "https://github.com/avtomatila-ai/avtomatika-worker"
-"Bug Tracker" = "https://github.com/avtomatila-ai/avtomatika-worker/issues"
+"Homepage" = "https://github.com/avtomatika-ai/avtomatika-worker"
+"Bug Tracker" = "https://github.com/avtomatika-ai/avtomatika-worker/issues"
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -47,7 +46,7 @@ pythonpath = "src"
 filterwarnings = [
     "ignore:'asyncio.iscoroutinefunction' is deprecated:DeprecationWarning",
     "ignore:coroutine 'AsyncMockMixin._execute_mock_call' was never awaited:RuntimeWarning",
-    "ignore:datetime.datetime.utcnow() is deprecated and scheduled for removal in a future version.:DeprecationWarning",
+    "ignore::pytest.PytestUnraisableExceptionWarning"
 ]
 
 [tool.ruff]

{avtomatika_worker-1.0b1 → avtomatika_worker-1.0b2}/src/avtomatika_worker/__init__.py

@@ -2,9 +2,10 @@
 
 from importlib.metadata import PackageNotFoundError, version
 
+from .task_files import TaskFiles
 from .worker import Worker
 
-__all__ = ["Worker"]
+__all__ = ["Worker", "TaskFiles"]
 
 try:
     __version__ = version("avtomatika-worker")

{avtomatika_worker-1.0b1 → avtomatika_worker-1.0b2}/src/avtomatika_worker/config.py

@@ -49,7 +49,7 @@ class WorkerConfig:
         )
 
         # --- S3 Settings for payload offloading ---
-        self.WORKER_PAYLOAD_DIR: str = getenv("WORKER_PAYLOAD_DIR", "/tmp/payloads")
+        self.TASK_FILES_DIR: str = getenv("TASK_FILES_DIR", "/tmp/payloads")
         self.S3_ENDPOINT_URL: str | None = getenv("S3_ENDPOINT_URL")
         self.S3_ACCESS_KEY: str | None = getenv("S3_ACCESS_KEY")
         self.S3_SECRET_KEY: str | None = getenv("S3_SECRET_KEY")
@@ -75,8 +75,7 @@ class WorkerConfig:
         Loads orchestrator configuration from the ORCHESTRATORS_CONFIG environment variable.
         For backward compatibility, if it is not set, it uses ORCHESTRATOR_URL.
         """
-        orchestrators_json = getenv("ORCHESTRATORS_CONFIG")
-        if orchestrators_json:
+        if orchestrators_json := getenv("ORCHESTRATORS_CONFIG"):
             try:
                 orchestrators = loads(orchestrators_json)
                 if getenv("ORCHESTRATOR_URL"):
@@ -94,23 +93,23 @@ class WorkerConfig:
         orchestrator_url = getenv("ORCHESTRATOR_URL", "http://localhost:8080")
         return [{"url": orchestrator_url, "priority": 1, "weight": 1}]
 
-    def _get_gpu_info(self) -> dict[str, Any] | None:
+    @staticmethod
+    def _get_gpu_info() -> dict[str, Any] | None:
         """Collects GPU information from environment variables.
         Returns None if GPU is not configured.
         """
-        gpu_model = getenv("GPU_MODEL")
-        if not gpu_model:
+        if gpu_model := getenv("GPU_MODEL"):
+            return {
+                "model": gpu_model,
+                "vram_gb": int(getenv("GPU_VRAM_GB", "0")),
+            }
+        else:
             return None
 
-        return {
-            "model": gpu_model,
-            "vram_gb": int(getenv("GPU_VRAM_GB", "0")),
-        }
-
-    def _load_json_from_env(self, key: str, default: Any) -> Any:
+    @staticmethod
+    def _load_json_from_env(key: str, default: Any) -> Any:
         """Safely loads a JSON string from an environment variable."""
-        value = getenv(key)
-        if value:
+        if value := getenv(key):
             try:
                 return loads(value)
             except JSONDecodeError:

avtomatika_worker-1.0b2/src/avtomatika_worker/s3.py

@@ -0,0 +1,141 @@
+from asyncio import gather, to_thread
+from os import walk
+from os.path import basename, dirname, join, relpath
+from shutil import rmtree
+from typing import Any
+from urllib.parse import urlparse
+
+from aioboto3 import Session
+from aiofiles.os import makedirs
+from aiofiles.ospath import exists, isdir
+from botocore.client import Config
+
+from .config import WorkerConfig
+
+
+class S3Manager:
+    """Handles S3 payload offloading."""
+
+    def __init__(self, config: WorkerConfig):
+        self._config = config
+        self._session = Session()
+
+    def _get_client_args(self) -> dict[str, Any]:
+        """Returns standard arguments for S3 client creation."""
+        return {
+            "service_name": "s3",
+            "endpoint_url": self._config.S3_ENDPOINT_URL,
+            "aws_access_key_id": self._config.S3_ACCESS_KEY,
+            "aws_secret_access_key": self._config.S3_SECRET_KEY,
+            "config": Config(signature_version="s3v4"),
+        }
+
+    async def cleanup(self, task_id: str):
+        """Removes the task-specific payload directory."""
+        task_dir = join(self._config.TASK_FILES_DIR, task_id)
+        if await exists(task_dir):
+            await to_thread(lambda: rmtree(task_dir, ignore_errors=True))
+
+    async def _process_s3_uri(self, uri: str, task_id: str) -> str:
+        """Downloads a file or a folder (if uri ends with /) from S3 and returns the local path."""
+        parsed_url = urlparse(uri)
+        bucket_name = parsed_url.netloc
+        object_key = parsed_url.path.lstrip("/")
+
+        # Use task-specific directory for isolation
+        local_dir_root = join(self._config.TASK_FILES_DIR, task_id)
+        await makedirs(local_dir_root, exist_ok=True)
+
+        async with self._session.client(**self._get_client_args()) as s3:
+            # Handle folder download (prefix)
+            if uri.endswith("/"):
+                folder_name = object_key.rstrip("/").split("/")[-1]
+                local_folder_path = join(local_dir_root, folder_name)
+
+                paginator = s3.get_paginator("list_objects_v2")
+                tasks = []
+                async for page in paginator.paginate(Bucket=bucket_name, Prefix=object_key):
+                    for obj in page.get("Contents", []):
+                        key = obj["Key"]
+                        if key.endswith("/"):
+                            continue
+
+                        # Calculate relative path inside the folder
+                        rel_path = key[len(object_key) :]
+                        local_file_path = join(local_folder_path, rel_path)
+
+                        await makedirs(dirname(local_file_path), exist_ok=True)
+                        tasks.append(s3.download_file(bucket_name, key, local_file_path))
+
+                if tasks:
+                    await gather(*tasks)
+                return local_folder_path
+
+            # Handle single file download
+            local_path = join(local_dir_root, basename(object_key))
+            await s3.download_file(bucket_name, object_key, local_path)
+            return local_path
+
+    async def _upload_to_s3(self, local_path: str) -> str:
+        """Uploads a file or a folder to S3 and returns the S3 URI."""
+        bucket_name = self._config.S3_DEFAULT_BUCKET
+
+        async with self._session.client(**self._get_client_args()) as s3:
+            # Handle folder upload
+            if await isdir(local_path):
+                folder_name = basename(local_path.rstrip("/"))
+                s3_prefix = f"{folder_name}/"
+                tasks = []
+
+                # Use to_thread to avoid blocking event loop during file walk
+                def _get_files_to_upload():
+                    files_to_upload = []
+                    for root, _, files in walk(local_path):
+                        for file in files:
+                            f_path = join(root, file)
+                            rel = relpath(f_path, local_path)
+                            files_to_upload.append((f_path, f"{s3_prefix}{rel}"))
+                    return files_to_upload
+
+                files_list = await to_thread(_get_files_to_upload)
+
+                for full_path, key in files_list:
+                    tasks.append(s3.upload_file(full_path, bucket_name, key))
+
+                if tasks:
+                    await gather(*tasks)
+
+                return f"s3://{bucket_name}/{s3_prefix}"
+
+            # Handle single file upload
+            object_key = basename(local_path)
+            await s3.upload_file(local_path, bucket_name, object_key)
+            return f"s3://{bucket_name}/{object_key}"
+
+    async def process_params(self, params: dict[str, Any], task_id: str) -> dict[str, Any]:
+        """Recursively searches for S3 URIs in params and downloads the files."""
+        if not self._config.S3_ENDPOINT_URL:
+            return params
+
+        async def _process(item: Any) -> Any:
+            if isinstance(item, str) and item.startswith("s3://"):
+                return await self._process_s3_uri(item, task_id)
+            if isinstance(item, dict):
+                return {k: await _process(v) for k, v in item.items()}
+            return [await _process(i) for i in item] if isinstance(item, list) else item
+
+        return await _process(params)
+
+    async def process_result(self, result: dict[str, Any]) -> dict[str, Any]:
+        """Recursively searches for local file paths in the result and uploads them to S3."""
+        if not self._config.S3_ENDPOINT_URL:
+            return result
+
+        async def _process(item: Any) -> Any:
+            if isinstance(item, str) and item.startswith(self._config.TASK_FILES_DIR):
+                return await self._upload_to_s3(item) if await exists(item) else item
+            if isinstance(item, dict):
+                return {k: await _process(v) for k, v in item.items()}
+            return [await _process(i) for i in item] if isinstance(item, list) else item
+
+        return await _process(result)

avtomatika_worker-1.0b2/src/avtomatika_worker/task_files.py

@@ -0,0 +1,97 @@
+from contextlib import asynccontextmanager
+from os.path import dirname, join
+from typing import AsyncGenerator
+
+from aiofiles import open as aiopen
+from aiofiles.os import listdir, makedirs
+from aiofiles.ospath import exists as aio_exists
+
+
+class TaskFiles:
+    """
+    A helper class for managing task-specific files.
+    Provides asynchronous lazy directory creation and high-level file operations
+    within an isolated workspace for each task.
+    """
+
+    def __init__(self, task_dir: str):
+        """
+        Initializes TaskFiles with a specific task directory.
+        The directory is not created until needed.
+        """
+        self._task_dir = task_dir
+
+    async def get_root(self) -> str:
+        """
+        Asynchronously returns the root directory for the task.
+        Creates the directory on disk if it doesn't exist.
+        """
+        await makedirs(self._task_dir, exist_ok=True)
+        return self._task_dir
+
+    async def path_to(self, filename: str) -> str:
+        """
+        Asynchronously returns an absolute path for a file within the task directory.
+        Guarantees that the task root directory exists.
+        """
+        root = await self.get_root()
+        return join(root, filename)
+
+    @asynccontextmanager
+    async def open(self, filename: str, mode: str = "r") -> AsyncGenerator:
+        """
+        An asynchronous context manager to open a file within the task directory.
+        Automatically creates the task root and any necessary subdirectories.
+
+        Args:
+            filename: Name or relative path of the file.
+            mode: File opening mode (e.g., 'r', 'w', 'a', 'rb', 'wb').
+        """
+        path = await self.path_to(filename)
+        # Ensure directory for the file itself exists if filename contains subdirectories
+        file_dir = dirname(path)
+        if file_dir != self._task_dir:
+            await makedirs(file_dir, exist_ok=True)
+
+        async with aiopen(path, mode) as f:
+            yield f
+
+    async def read(self, filename: str, mode: str = "r") -> str | bytes:
+        """
+        Asynchronously reads the entire content of a file.
+
+        Args:
+            filename: Name of the file to read.
+            mode: Mode to open the file in (defaults to 'r').
+        """
+        async with self.open(filename, mode) as f:
+            return await f.read()
+
+    async def write(self, filename: str, data: str | bytes, mode: str = "w") -> None:
+        """
+        Asynchronously writes data to a file. Creates or overwrites the file by default.
+
+        Args:
+            filename: Name of the file to write.
+            data: Content to write (string or bytes).
+            mode: Mode to open the file in (defaults to 'w').
+        """
+        async with self.open(filename, mode) as f:
+            await f.write(data)
+
+    async def list(self) -> list[str]:
+        """
+        Asynchronously lists all file and directory names within the task root.
+        """
+        root = await self.get_root()
+        return await listdir(root)
+
+    async def exists(self, filename: str) -> bool:
+        """
+        Asynchronously checks if a specific file or directory exists in the task root.
+        """
+        path = join(self._task_dir, filename)
+        return await aio_exists(path)
+
+    def __repr__(self):
+        return f"<TaskFiles root='{self._task_dir}'>"