wool 0.1rc12__tar.gz → 0.1rc14__tar.gz

{wool-0.1rc12 → wool-0.1rc14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wool
-Version: 0.1rc12
+Version: 0.1rc14
 Summary: A Python framework for distributed multiprocessing.
 Author-email: Conrad Bzura <conrad@wool.io>
 Maintainer-email: maintainers@wool.io
@@ -227,9 +227,9 @@ Requires-Dist: pytest-mock; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# Wool
+![](https://raw.githubusercontent.com/wool-labs/wool/refs/heads/main/assets/woolly-transparent-bg-2048.png)
 
-Wool is a native Python package for transparently executing tasks in a horizontally scalable, distributed network of agnostic worker processes. Any picklable async function or method can be converted into a task with a simple decorator and a client connection.
+**Wool** is a native Python package for transparently executing tasks in a horizontally scalable, distributed network of agnostic worker processes. Any picklable async function or method can be converted into a task with a simple decorator and a client connection.
 
 ## Installation
 
@@ -253,19 +253,73 @@ cd wool
 
 ## Usage
 
-### CLI Commands
+### Declaring tasks
 
-Wool provides a command-line interface (CLI) for managing the worker pool.
+Wool tasks are coroutine functions that are executed in a remote `asyncio` event loop within a worker process. To declare a task, use the `@wool.task` decorator:
 
-To list the available commands:
+```python
+import wool
 
-```sh
-wool --help
+@wool.task
+async def sample_task(x, y):
+    return x + y
 ```
 
-#### Start the Worker Pool
+Tasks must be picklable, stateless, and idempotent. Avoid passing unpicklable objects as arguments or return values.
+
+### Worker pools
+
+Worker pools are responsible for executing tasks. Wool provides two types of pools:
+
+#### Ephemeral pools
+
+Ephemeral pools are created and destroyed within the scope of a context manager. Use `wool.pool` to declare an ephemeral pool:
+
+```python
+import asyncio, wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+
+async def main():
+    with wool.pool():
+        result = await sample_task(1, 2)
+        print(f"Result: {result}")
+
+asyncio.run(main())
+```
+
+#### Durable pools
+
+Durable pools are started independently and persist beyond the scope of a single application. Use the `wool` CLI to manage durable pools:
+
+```bash
+wool pool up --port 5050 --authkey deadbeef --module tasks
+```
+
+Connect to a durable pool using `wool.session`:
+
+```python
+import asyncio, wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+
+async def main():
+    with wool.session(port=5050, authkey=b"deadbeef"):
+        result = await sample_task(1, 2)
+        print(f"Result: {result}")
+
+asyncio.run(main())
+```
 
-To start the worker pool, use the `up` command:
+### CLI commands
+
+Wool provides a command-line interface (CLI) for managing worker pools.
+
+#### Start the worker pool
 
 ```sh
 wool pool up --host <host> --port <port> --authkey <authkey> --breadth <breadth> --module <module>
@@ -275,11 +329,9 @@ wool pool up --host <host> --port <port> --authkey <authkey> --breadth <breadth>
 - `--port`: The port number (default: `0`).
 - `--authkey`: The authentication key (default: `b""`).
 - `--breadth`: The number of worker processes (default: number of CPU cores).
-- `--module`: Python module containing Wool task definitions to be executed by this pool (optional, can be specified multiple times).
-
-#### Stop the Worker Pool
+- `--module`: Python module containing Wool task definitions (optional, can be specified multiple times).
 
-To stop the worker pool, use the `down` command:
+#### Stop the worker pool
 
 ```sh
 wool pool down --host <host> --port <port> --authkey <authkey> --wait
@@ -290,9 +342,7 @@ wool pool down --host <host> --port <port> --authkey <authkey> --wait
 - `--authkey`: The authentication key (default: `b""`).
 - `--wait`: Wait for in-flight tasks to complete before shutting down.
 
-#### Ping the Worker Pool
-
-To ping the worker pool, use the `ping` command:
+#### Ping the worker pool
 
 ```sh
 wool ping --host <host> --port <port> --authkey <authkey>
@@ -302,46 +352,108 @@ wool ping --host <host> --port <port> --authkey <authkey>
 - `--port`: The port number (required).
 - `--authkey`: The authentication key (default: `b""`).
 
-### Sample Python Application
+### Advanced usage
+
+#### Nested pools and sessions
 
-Below is an example of how to create a Wool client connection, decorate an async function using the `task` decorator, and execute the function remotely:
+Wool supports nesting pools and sessions to achieve complex workflows. Tasks can be dispatched to specific pools by nesting contexts:
 
-Module defining remote tasks:
-`tasks.py`
 ```python
 import asyncio, wool
 
-# Decorate an async function using the `task` decorator
 @wool.task
-async def sample_task(x, y):
+async def task_a():
     await asyncio.sleep(1)
-    return x + y
+
+@wool.task
+async def task_b():
+    with wool.pool(port=5051):
+        await task_a()
+
+async def main():
+    with wool.pool(port=5050):
+        await task_a()
+        await task_b()
+
+asyncio.run(main())
 ```
 
-Module executing remote workflow:
-`main.py`
+In this example, `task_a` is executed by two different pools, while `task_b` is executed by the pool on port 5050.
+
+### Best practices
+
+#### Sizing worker pools
+
+When configuring worker pools, it is important to balance the number of processes with the available system resources:
+
+- **CPU-bound tasks**: Size the worker pool to match the number of CPU cores. This is the default behavior when spawning a pool.
+- **I/O-bound tasks**: For workloads involving significant I/O, consider oversizing the pool slightly to maximize the system's I/O capacity utilization.
+- **Mixed workloads**: Monitor memory usage and system load to avoid oversubscription, especially for memory-intensive tasks. Use profiling tools to determine the optimal pool size.
+
+#### Defining tasks
+
+Wool tasks are coroutine functions that execute asynchronously in a remote `asyncio` event loop. To ensure smooth execution and scalability, prioritize:
+
+- **Picklability**: Ensure all task arguments and return values are picklable. Avoid passing unpicklable objects such as open file handles, database connections, or lambda functions.
+- **Statelessness and idempotency**: Design tasks to be stateless and idempotent. Avoid relying on global variables or shared mutable state. This ensures predictable behavior and safe retries.
+- **Non-blocking operations**: To achieve higher concurrency, avoid blocking calls within tasks. Use `asyncio`-compatible libraries for I/O operations.
+- **Inter-process synchronization**: Use Wool's synchronization primitives (e.g., `wool.locking`) for inter-worker and inter-pool coordination. Standard `asyncio` primitives will not behave as expected in a multi-process environment.
+
+#### Debugging and logging
+
+- Enable detailed logging during development to trace task execution and worker pool behavior:
+  ```python
+  import logging
+  logging.basicConfig(level=logging.DEBUG)
+  ```
+- Use Wool's built-in logging configuration to capture worker-specific logs.
+
+#### Nested pools and sessions
+
+Wool supports nesting pools and sessions to achieve complex workflows. Tasks can be dispatched to specific pools by nesting contexts. This is useful for workflows requiring task segregation or resource isolation.
+
+Example:
 ```python
 import asyncio, wool
-from tasks import sample_task
 
-# Execute the decorated function in an external worker pool
+@wool.task
+async def task_a():
+    await asyncio.sleep(1)
+
+@wool.task
+async def task_b():
+    with wool.pool(port=5051):
+        await task_a()
+
 async def main():
-    with wool.PoolSession(port=5050, authkey=b"deadbeef"):
-        result = await sample_task(1, 2)
-        print(f"Result: {result}")
+    with wool.pool(port=5050):
+        await task_a()
+        await task_b()
 
-asyncio.new_event_loop().run_until_complete(main())
+asyncio.run(main())
 ```
 
-To run the demo, first start a worker pool specifying the module defining the tasks to be executed:
-```bash
-wool pool up --port 5050 --authkey deadbeef --breadth 1 --module tasks
-```
+#### Performance optimization
 
-Next, in a separate terminal, execute the application defined in `main.py` and, finally, stop the worker pool:
-```bash
-python main.py
-wool pool down --port 5050 --authkey deadbeef
+- Minimize the size of arguments and return values to reduce serialization overhead.
+- For large datasets, consider using shared memory or passing references (e.g., file paths) instead of transferring the entire data.
+- Profile tasks to identify and optimize performance bottlenecks.
+
+#### Task cancellation
+
+- Handle task cancellations gracefully by cleaning up resources and rolling back partial changes.
+- Use `asyncio.CancelledError` to detect and respond to cancellations.
+
+#### Error propagation
+
+- Wool propagates exceptions raised within tasks to the caller. Use this feature to handle errors centrally in your application.
+
+Example:
+```python
+try:
+    result = await some_task()
+except Exception as e:
+    print(f"Task failed with error: {e}")
 ```
 
 ## License

wool-0.1rc14/README.md

@@ -0,0 +1,232 @@
+![](https://raw.githubusercontent.com/wool-labs/wool/refs/heads/main/assets/woolly-transparent-bg-2048.png)
+
+**Wool** is a native Python package for transparently executing tasks in a horizontally scalable, distributed network of agnostic worker processes. Any picklable async function or method can be converted into a task with a simple decorator and a client connection.
+
+## Installation
+
+### Using pip
+
+To install the package using pip, run the following command:
+
+```sh
+[uv] pip install --pre wool
+```
+
+### Cloning from GitHub
+
+To install the package by cloning from GitHub, run the following commands:
+
+```sh
+git clone https://github.com/wool-labs/wool.git
+cd wool
+[uv] pip install ./wool
+```
+
+## Usage
+
+### Declaring tasks
+
+Wool tasks are coroutine functions that are executed in a remote `asyncio` event loop within a worker process. To declare a task, use the `@wool.task` decorator:
+
+```python
+import wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+```
+
+Tasks must be picklable, stateless, and idempotent. Avoid passing unpicklable objects as arguments or return values.
+
+### Worker pools
+
+Worker pools are responsible for executing tasks. Wool provides two types of pools:
+
+#### Ephemeral pools
+
+Ephemeral pools are created and destroyed within the scope of a context manager. Use `wool.pool` to declare an ephemeral pool:
+
+```python
+import asyncio, wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+
+async def main():
+    with wool.pool():
+        result = await sample_task(1, 2)
+        print(f"Result: {result}")
+
+asyncio.run(main())
+```
+
+#### Durable pools
+
+Durable pools are started independently and persist beyond the scope of a single application. Use the `wool` CLI to manage durable pools:
+
+```bash
+wool pool up --port 5050 --authkey deadbeef --module tasks
+```
+
+Connect to a durable pool using `wool.session`:
+
+```python
+import asyncio, wool
+
+@wool.task
+async def sample_task(x, y):
+    return x + y
+
+async def main():
+    with wool.session(port=5050, authkey=b"deadbeef"):
+        result = await sample_task(1, 2)
+        print(f"Result: {result}")
+
+asyncio.run(main())
+```
+
+### CLI commands
+
+Wool provides a command-line interface (CLI) for managing worker pools.
+
+#### Start the worker pool
+
+```sh
+wool pool up --host <host> --port <port> --authkey <authkey> --breadth <breadth> --module <module>
+```
+
+- `--host`: The host address (default: `localhost`).
+- `--port`: The port number (default: `0`).
+- `--authkey`: The authentication key (default: `b""`).
+- `--breadth`: The number of worker processes (default: number of CPU cores).
+- `--module`: Python module containing Wool task definitions (optional, can be specified multiple times).
+
+#### Stop the worker pool
+
+```sh
+wool pool down --host <host> --port <port> --authkey <authkey> --wait
+```
+
+- `--host`: The host address (default: `localhost`).
+- `--port`: The port number (required).
+- `--authkey`: The authentication key (default: `b""`).
+- `--wait`: Wait for in-flight tasks to complete before shutting down.
+
+#### Ping the worker pool
+
+```sh
+wool ping --host <host> --port <port> --authkey <authkey>
+```
+
+- `--host`: The host address (default: `localhost`).
+- `--port`: The port number (required).
+- `--authkey`: The authentication key (default: `b""`).
+
+### Advanced usage
+
+#### Nested pools and sessions
+
+Wool supports nesting pools and sessions to achieve complex workflows. Tasks can be dispatched to specific pools by nesting contexts:
+
+```python
+import asyncio, wool
+
+@wool.task
+async def task_a():
+    await asyncio.sleep(1)
+
+@wool.task
+async def task_b():
+    with wool.pool(port=5051):
+        await task_a()
+
+async def main():
+    with wool.pool(port=5050):
+        await task_a()
+        await task_b()
+
+asyncio.run(main())
+```
+
+In this example, `task_a` is executed by two different pools, while `task_b` is executed by the pool on port 5050.
+
+### Best practices
+
+#### Sizing worker pools
+
+When configuring worker pools, it is important to balance the number of processes with the available system resources:
+
+- **CPU-bound tasks**: Size the worker pool to match the number of CPU cores. This is the default behavior when spawning a pool.
+- **I/O-bound tasks**: For workloads involving significant I/O, consider oversizing the pool slightly to maximize the system's I/O capacity utilization.
+- **Mixed workloads**: Monitor memory usage and system load to avoid oversubscription, especially for memory-intensive tasks. Use profiling tools to determine the optimal pool size.
+
+#### Defining tasks
+
+Wool tasks are coroutine functions that execute asynchronously in a remote `asyncio` event loop. To ensure smooth execution and scalability, prioritize:
+
+- **Picklability**: Ensure all task arguments and return values are picklable. Avoid passing unpicklable objects such as open file handles, database connections, or lambda functions.
+- **Statelessness and idempotency**: Design tasks to be stateless and idempotent. Avoid relying on global variables or shared mutable state. This ensures predictable behavior and safe retries.
+- **Non-blocking operations**: To achieve higher concurrency, avoid blocking calls within tasks. Use `asyncio`-compatible libraries for I/O operations.
+- **Inter-process synchronization**: Use Wool's synchronization primitives (e.g., `wool.locking`) for inter-worker and inter-pool coordination. Standard `asyncio` primitives will not behave as expected in a multi-process environment.
+
+#### Debugging and logging
+
+- Enable detailed logging during development to trace task execution and worker pool behavior:
+  ```python
+  import logging
+  logging.basicConfig(level=logging.DEBUG)
+  ```
+- Use Wool's built-in logging configuration to capture worker-specific logs.
+
+#### Nested pools and sessions
+
+Wool supports nesting pools and sessions to achieve complex workflows. Tasks can be dispatched to specific pools by nesting contexts. This is useful for workflows requiring task segregation or resource isolation.
+
+Example:
+```python
+import asyncio, wool
+
+@wool.task
+async def task_a():
+    await asyncio.sleep(1)
+
+@wool.task
+async def task_b():
+    with wool.pool(port=5051):
+        await task_a()
+
+async def main():
+    with wool.pool(port=5050):
+        await task_a()
+        await task_b()
+
+asyncio.run(main())
+```
+
+#### Performance optimization
+
+- Minimize the size of arguments and return values to reduce serialization overhead.
+- For large datasets, consider using shared memory or passing references (e.g., file paths) instead of transferring the entire data.
+- Profile tasks to identify and optimize performance bottlenecks.
+
+#### Task cancellation
+
+- Handle task cancellations gracefully by cleaning up resources and rolling back partial changes.
+- Use `asyncio.CancelledError` to detect and respond to cancellations.
+
+#### Error propagation
+
+- Wool propagates exceptions raised within tasks to the caller. Use this feature to handle errors centrally in your application.
+
+Example:
+```python
+try:
+    result = await some_task()
+except Exception as e:
+    print(f"Task failed with error: {e}")
+```
+
+## License
+
+This project is licensed under the Apache License Version 2.0.

{wool-0.1rc12 → wool-0.1rc14}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [
     "debugpy",
     "hatchling",
     "packaging",
-    "GitPython",
+    "gitpython",
     "toml",
     "typing-extensions",
 ]

{wool-0.1rc12 → wool-0.1rc14}/wool/__init__.py

@@ -54,9 +54,7 @@ try:
 except PackageNotFoundError:
     __version__ = "unknown"
 
-__proxy__: Final[ContextVar[WorkerProxy | None]] = ContextVar(
-    "__proxy__", default=None
-)
+__proxy__: Final[ContextVar[WorkerProxy | None]] = ContextVar("__proxy__", default=None)
 
 __proxy_pool__: Final[ContextVar[ResourcePool[WorkerProxy] | None]] = ContextVar(
     "__proxy_pool__", default=None

{wool-0.1rc12 → wool-0.1rc14}/wool/_worker.py

@@ -43,7 +43,7 @@ if TYPE_CHECKING:
 
 
 @contextmanager
-def _signal_handlers(service: "WorkerService"):
+def _signal_handlers(service: WorkerService):
     """Context manager for setting up signal handlers for graceful shutdown.
 
     Installs SIGTERM and SIGINT handlers that gracefully shut down the worker

{wool-0.1rc12 → wool-0.1rc14}/wool/_worker_discovery.py

@@ -991,46 +991,28 @@ class LocalRegistrar(Registrar):
 
     _shared_memory: multiprocessing.shared_memory.SharedMemory | None = None
     _uri: str
-    _created_shared_memory: bool = False
 
     def __init__(self, uri: str):
         super().__init__()
         self._uri = uri
-        self._created_shared_memory = False
 
     async def _start(self) -> None:
         """Initialize shared memory for worker registration."""
         if self._shared_memory is None:
             # Try to connect to existing shared memory first, create if it doesn't exist
             shared_memory_name = hashlib.sha256(self._uri.encode()).hexdigest()[:12]
-            try:
-                self._shared_memory = multiprocessing.shared_memory.SharedMemory(
-                    name=shared_memory_name
-                )
-            except FileNotFoundError:
-                # Create new shared memory if it doesn't exist
-                self._shared_memory = multiprocessing.shared_memory.SharedMemory(
-                    name=shared_memory_name,
-                    create=True,
-                    size=1024,  # 1024 bytes = 256 worker slots (4 bytes per port)
-                )
-                self._created_shared_memory = True
-                # Initialize all slots to 0 (empty)
-                for i in range(len(self._shared_memory.buf)):
-                    self._shared_memory.buf[i] = 0
+            self._shared_memory = multiprocessing.shared_memory.SharedMemory(
+                name=shared_memory_name
+            )
 
     async def _stop(self) -> None:
         """Clean up shared memory resources."""
         if self._shared_memory:
             try:
                 self._shared_memory.close()
-                # Unlink the shared memory if this registrar created it
-                if self._created_shared_memory:
-                    self._shared_memory.unlink()
             except Exception:
                 pass
             self._shared_memory = None
-            self._created_shared_memory = False
 
     async def _register(self, worker_info: WorkerInfo) -> None:
         """Register a worker by writing its port to shared memory.
@@ -1138,7 +1120,6 @@ class LocalDiscovery(Discovery):
     async def _start(self) -> None:
         """Starts monitoring shared memory for worker registrations."""
         if self._shared_memory is None:
-            # Try to connect to existing shared memory first
             self._shared_memory = multiprocessing.shared_memory.SharedMemory(
                 name=hashlib.sha256(self._uri.encode()).hexdigest()[:12]
             )
@@ -1172,7 +1153,9 @@ class LocalDiscovery(Discovery):
                 # Read current state from shared memory
                 if self._shared_memory:
                     for i in range(0, len(self._shared_memory.buf), 4):
-                        port = struct.unpack("I", self._shared_memory.buf[i : i + 4])[0]
+                        port = struct.unpack(
+                            "I", bytes(self._shared_memory.buf[i : i + 4])
+                        )[0]
                         if port > 0:  # Active worker
                             worker_info = WorkerInfo(
                                 uid=f"worker-{port}",

{wool-0.1rc12 → wool-0.1rc14}/wool/_worker_pool.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 import asyncio
+import atexit
 import hashlib
 import os
 import uuid
+from contextlib import asynccontextmanager
 from multiprocessing.shared_memory import SharedMemory
 from typing import Final
 from typing import overload
@@ -172,7 +174,6 @@ class WorkerPool:
     """
 
     _workers: Final[list[Worker]]
-    _shared_memory = None
 
     @overload
     def __init__(
@@ -226,19 +227,27 @@ class WorkerPool:
 
                 uri = f"pool-{uuid.uuid4().hex}"
 
+                @asynccontextmanager
                 async def create_proxy():
-                    self._shared_memory = SharedMemory(
+                    shared_memory_size = (size + 1) * 4
+                    shared_memory = SharedMemory(
                         name=hashlib.sha256(uri.encode()).hexdigest()[:12],
                         create=True,
-                        size=1024,
-                    )
-                    for i in range(1024):
-                        self._shared_memory.buf[i] = 0
-                    await self._spawn_workers(uri, *tags, size=size, factory=worker)
-                    return WorkerProxy(
-                        discovery=LocalDiscovery(uri),
-                        loadbalancer=loadbalancer,
+                        size=shared_memory_size,
                     )
+                    cleanup = atexit.register(lambda: shared_memory.unlink())
+                    try:
+                        for i in range(shared_memory_size):
+                            shared_memory.buf[i] = 0
+                        await self._spawn_workers(uri, *tags, size=size, factory=worker)
+                        async with WorkerProxy(
+                            discovery=LocalDiscovery(uri),
+                            loadbalancer=loadbalancer,
+                        ):
+                            yield
+                    finally:
+                        shared_memory.unlink()
+                        atexit.unregister(cleanup)
 
             case (size, None) if size is not None:
                 if size == 0:
@@ -251,27 +260,37 @@ class WorkerPool:
 
                 uri = f"pool-{uuid.uuid4().hex}"
 
+                @asynccontextmanager
                 async def create_proxy():
-                    self._shared_memory = SharedMemory(
+                    shared_memory_size = (size + 1) * 4
+                    shared_memory = SharedMemory(
                         name=hashlib.sha256(uri.encode()).hexdigest()[:12],
                         create=True,
-                        size=1024,
-                    )
-                    for i in range(1024):
-                        self._shared_memory.buf[i] = 0
-                    await self._spawn_workers(uri, *tags, size=size, factory=worker)
-                    return WorkerProxy(
-                        discovery=LocalDiscovery(uri),
-                        loadbalancer=loadbalancer,
+                        size=shared_memory_size,
                     )
+                    cleanup = atexit.register(lambda: shared_memory.unlink())
+                    try:
+                        for i in range(shared_memory_size):
+                            shared_memory.buf[i] = 0
+                        await self._spawn_workers(uri, *tags, size=size, factory=worker)
+                        async with WorkerProxy(
+                            discovery=LocalDiscovery(uri),
+                            loadbalancer=loadbalancer,
+                        ):
+                            yield
+                    finally:
+                        shared_memory.unlink()
+                        atexit.unregister(cleanup)
 
             case (None, discovery) if discovery is not None:
 
+                @asynccontextmanager
                 async def create_proxy():
-                    return WorkerProxy(
+                    async with WorkerProxy(
                         discovery=discovery,
                         loadbalancer=loadbalancer,
-                    )
+                    ):
+                        yield
 
             case _:
                 raise RuntimeError
@@ -287,18 +306,14 @@ class WorkerPool:
         :returns:
             The :py:class:`WorkerPool` instance itself for method chaining.
         """
-        self._proxy = await self._proxy_factory()
-        await self._proxy.__aenter__()
+        self._proxy_context = self._proxy_factory()
+        await self._proxy_context.__aenter__()
         return self
 
     async def __aexit__(self, *args):
         """Stops all workers and tears down the pool and its services."""
-        try:
-            await self._stop_workers()
-            await self._proxy.__aexit__(*args)
-        finally:
-            if self._shared_memory is not None:
-                self._shared_memory.unlink()
+        await self._stop_workers()
+        await self._proxy_context.__aexit__(*args)
 
     async def _spawn_workers(
         self, uri, *tags: str, size: int, factory: WorkerFactory | None

wool-0.1rc12/README.md

@@ -1,120 +0,0 @@
-# Wool
-
-Wool is a native Python package for transparently executing tasks in a horizontally scalable, distributed network of agnostic worker processes. Any picklable async function or method can be converted into a task with a simple decorator and a client connection.
-
-## Installation
-
-### Using pip
-
-To install the package using pip, run the following command:
-
-```sh
-[uv] pip install --pre wool
-```
-
-### Cloning from GitHub
-
-To install the package by cloning from GitHub, run the following commands:
-
-```sh
-git clone https://github.com/wool-labs/wool.git
-cd wool
-[uv] pip install ./wool
-```
-
-## Usage
-
-### CLI Commands
-
-Wool provides a command-line interface (CLI) for managing the worker pool.
-
-To list the available commands:
-
-```sh
-wool --help
-```
-
-#### Start the Worker Pool
-
-To start the worker pool, use the `up` command:
-
-```sh
-wool pool up --host <host> --port <port> --authkey <authkey> --breadth <breadth> --module <module>
-```
-
-- `--host`: The host address (default: `localhost`).
-- `--port`: The port number (default: `0`).
-- `--authkey`: The authentication key (default: `b""`).
-- `--breadth`: The number of worker processes (default: number of CPU cores).
-- `--module`: Python module containing Wool task definitions to be executed by this pool (optional, can be specified multiple times).
-
-#### Stop the Worker Pool
-
-To stop the worker pool, use the `down` command:
-
-```sh
-wool pool down --host <host> --port <port> --authkey <authkey> --wait
-```
-
-- `--host`: The host address (default: `localhost`).
-- `--port`: The port number (required).
-- `--authkey`: The authentication key (default: `b""`).
-- `--wait`: Wait for in-flight tasks to complete before shutting down.
-
-#### Ping the Worker Pool
-
-To ping the worker pool, use the `ping` command:
-
-```sh
-wool ping --host <host> --port <port> --authkey <authkey>
-```
-
-- `--host`: The host address (default: `localhost`).
-- `--port`: The port number (required).
-- `--authkey`: The authentication key (default: `b""`).
-
-### Sample Python Application
-
-Below is an example of how to create a Wool client connection, decorate an async function using the `task` decorator, and execute the function remotely:
-
-Module defining remote tasks:
-`tasks.py`
-```python
-import asyncio, wool
-
-# Decorate an async function using the `task` decorator
-@wool.task
-async def sample_task(x, y):
-    await asyncio.sleep(1)
-    return x + y
-```
-
-Module executing remote workflow:
-`main.py`
-```python
-import asyncio, wool
-from tasks import sample_task
-
-# Execute the decorated function in an external worker pool
-async def main():
-    with wool.PoolSession(port=5050, authkey=b"deadbeef"):
-        result = await sample_task(1, 2)
-        print(f"Result: {result}")
-
-asyncio.new_event_loop().run_until_complete(main())
-```
-
-To run the demo, first start a worker pool specifying the module defining the tasks to be executed:
-```bash
-wool pool up --port 5050 --authkey deadbeef --breadth 1 --module tasks
-```
-
-Next, in a separate terminal, execute the application defined in `main.py` and, finally, stop the worker pool:
-```bash
-python main.py
-wool pool down --port 5050 --authkey deadbeef
-```
-
-## License
-
-This project is licensed under the Apache License Version 2.0.