mindmesh 0.1.0__tar.gz

mindmesh-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.3
+Name: mindmesh
+Version: 0.1.0
+Summary: Actor system for asyncio environments
+Keywords: asyncio,actors,distributed,mesh,concurrency
+Author: Marcin Glinski
+Author-email: Marcin Glinski <undefinedlamb@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# mindmesh
+
+A minimal, dependency-free actor system for asyncio.
+
+- asyncio-native, zero external dependencies
+- fire-and-forget (tell) and request/response (ask) messaging
+- automatic message dispatch by message type
+- actor lifecycle hooks and background task support
+- actor linking and supervision (restart on death, stop propagation)
+
+
+## Installation
+
+    pip install mindmesh
+
+
+Or with uv:
+
+    uv add mindmesh
+
+
+## Quick Start
+
+```python
+import asyncio
+from dataclasses import dataclass
+from mindmesh import ActorHive, BaseActor, Request
+
+@dataclass
+class Greet(Request[str]):
+    name: str
+
+class GreeterActor(BaseActor):
+    def on_greet(self, msg: Greet) -> str:
+        return f"Hello, {msg.name}!"
+
+async def main():
+    hive = ActorHive()
+    greeter = hive.start_actor(GreeterActor)
+    await greeter.wait_for_start()
+
+    reply = await greeter.ask(Greet(name="world"))
+    print(reply)  # Hello, world!
+
+    await hive.shutdown()
+
+asyncio.run(main())
+```
+
+## Core Concepts
+
+### BaseActor
+
+Subclass `BaseActor` to define an actor. Each actor owns a private asyncio
+queue (its mailbox) and processes one message at a time - no parallelism
+within a single actor.
+
+```python
+class MyActor(BaseActor):
+    def __init__(self, hive: ActorHive, id: str, extra_arg: int):
+        super().__init__(hive, id)
+        self._extra = extra_arg
+```
+
+`hive` and `id` are always the first two constructor parameters; any additional
+arguments are passed by the caller via `hive.start_actor()`.
+
+### ActorHive
+
+`ActorHive` is the registry and lifecycle manager. It creates, starts, and
+stops actors.
+
+```python
+hive = ActorHive()
+addr = hive.start_actor(MyActor, extra_arg)   # returns ActorAddr
+await hive.shutdown()                         # stops all actors
+```
+
+### ActorAddr
+
+`ActorAddr` is an opaque handle to an actor. It is the only way to interact
+with an actor from outside. Never hold a direct reference to an actor instance.
+
+```python
+addr = hive.start_actor(MyActor)
+addr.tell(SomeMessage())
+result = await addr.ask(SomeRequest())
+addr.stop()
+```
+
+## Messaging
+
+### tell
+
+Enqueues any object as a fire-and-forget message. Returns immediately.
+
+```python
+addr.tell(SomeMessage(payload=42))
+```
+
+### ask
+
+Enqueues a `Request` subclass and returns an awaitable that resolves to the
+handler's return value. Exceptions raised in the handler are re-raised in the
+caller.
+
+```python
+@dataclass
+class AddRequest(Request[int]):
+    a: int
+    b: int
+
+result = await addr.ask(AddRequest(a=1, b=2))  # -> int
+```
+
+### Message dispatch
+
+`BaseActor.on_message()` routes incoming messages automatically. For a message
+of class `FooBar`, it calls `self.on_foo_bar(msg)`. You only need to define
+handler methods -- no manual dispatch boilerplate. This is default (optional) behavior,
+feel free to reimplement `BaseActor.on_message()` for your liking.
+
+```python
+class MyActor(BaseActor):
+    def on_foo_bar(self, msg: FooBar) -> None: ...
+    def on_add_request(self, msg: AddRequest) -> int: ...
+```
+
+Handler methods may be plain or async.
+
+
+## Lifecycle Hooks
+
+Override any of these on your actor class:
+
+    on_start()
+        Called before the mailbox loop begins.
+        Use it to initialize resources or start child actors.
+
+    on_stop()
+        Called after the mailbox loop exits, regardless of the stop reason.
+        Use it to clean up resources.
+
+    on_task_create()
+        Return a coroutine to run as a background task alongside the mailbox
+        loop. If the background task raises an unhandled exception, the actor
+        stops.
+
+    on_link_death(actor_id: str, reason: StopReasonType) -> LinkAction
+        Called when a monitored actor stops. Return LinkAction.Stop (default)
+        to stop this actor too, or LinkAction.Continue to keep running.
+
+All hooks may be async.
+
+
+## Supervision and Linking
+
+Actors can monitor each other. When a monitored actor stops, the monitoring
+actor's `on_link_death()` hook is called.
+
+```python
+# source stops -> monitor.on_link_death() is called
+hive.link_actors(source_addr, monitor_addr)
+
+# bidirectional: each monitors the other
+hive.link_actors_both(addr_a, addr_b)
+
+# monitor from within an actor (self monitors another)
+self.as_ref().monitor(other_addr)
+```
+
+### Stop reasons
+
+`on_link_death` receives one of:
+
+    StopReason.Stop       -- actor stopped normally
+    StopReason.Shutdown   -- hive-wide shutdown
+    StopReason.LinkDeath  -- a linked actor died and propagated the stop
+    <exception instance>  -- actor crashed with an unhandled exception
+
+### Restarting crashed actors
+
+To restart a worker that crashes, return `LinkAction.Continue` from
+`on_link_death` and start a replacement:
+
+```python
+async def on_link_death(self, actor_id: str, reason: StopReasonType) -> LinkAction:
+    replacement = self.hive.start_actor(WorkerActor)
+    self.as_ref().monitor(replacement)
+    return LinkAction.Continue
+```
+
+## Examples
+
+**examples/calculator.py**: A calculator actor that handles arithmetic requests
+via `ask()` and receives periodic random values via `tell()` from a background
+task.
+
+**examples/supervisor.py**: A supervisor that manages a pool of workers, round-robins
+jobs to them, and automatically restarts any worker that crashes.
+
+Run an example:
+
+    uv run examples/calculator.py
+    uv run examples/supervisor.py
+
+
+## Development
+
+Run tests:
+
+    uv run pytest
+
+Lint and type check:
+
+    uv run ruff check --fix
+    uv run pyright
+
+
+## License
+
+MIT - see LICENSE file.
+
+
+## Use of LLMs
+
+This project has been made by the use of LLMs in following areas:
+
+- Code review
+- Preparing test cases for discovered issues
+- Preparing and verifying documentation

mindmesh-0.1.0/README.md

@@ -0,0 +1,231 @@
+# mindmesh
+
+A minimal, dependency-free actor system for asyncio.
+
+- asyncio-native, zero external dependencies
+- fire-and-forget (tell) and request/response (ask) messaging
+- automatic message dispatch by message type
+- actor lifecycle hooks and background task support
+- actor linking and supervision (restart on death, stop propagation)
+
+
+## Installation
+
+    pip install mindmesh
+
+
+Or with uv:
+
+    uv add mindmesh
+
+
+## Quick Start
+
+```python
+import asyncio
+from dataclasses import dataclass
+from mindmesh import ActorHive, BaseActor, Request
+
+@dataclass
+class Greet(Request[str]):
+    name: str
+
+class GreeterActor(BaseActor):
+    def on_greet(self, msg: Greet) -> str:
+        return f"Hello, {msg.name}!"
+
+async def main():
+    hive = ActorHive()
+    greeter = hive.start_actor(GreeterActor)
+    await greeter.wait_for_start()
+
+    reply = await greeter.ask(Greet(name="world"))
+    print(reply)  # Hello, world!
+
+    await hive.shutdown()
+
+asyncio.run(main())
+```
+
+## Core Concepts
+
+### BaseActor
+
+Subclass `BaseActor` to define an actor. Each actor owns a private asyncio
+queue (its mailbox) and processes one message at a time - no parallelism
+within a single actor.
+
+```python
+class MyActor(BaseActor):
+    def __init__(self, hive: ActorHive, id: str, extra_arg: int):
+        super().__init__(hive, id)
+        self._extra = extra_arg
+```
+
+`hive` and `id` are always the first two constructor parameters; any additional
+arguments are passed by the caller via `hive.start_actor()`.
+
+### ActorHive
+
+`ActorHive` is the registry and lifecycle manager. It creates, starts, and
+stops actors.
+
+```python
+hive = ActorHive()
+addr = hive.start_actor(MyActor, extra_arg)   # returns ActorAddr
+await hive.shutdown()                         # stops all actors
+```
+
+### ActorAddr
+
+`ActorAddr` is an opaque handle to an actor. It is the only way to interact
+with an actor from outside. Never hold a direct reference to an actor instance.
+
+```python
+addr = hive.start_actor(MyActor)
+addr.tell(SomeMessage())
+result = await addr.ask(SomeRequest())
+addr.stop()
+```
+
+## Messaging
+
+### tell
+
+Enqueues any object as a fire-and-forget message. Returns immediately.
+
+```python
+addr.tell(SomeMessage(payload=42))
+```
+
+### ask
+
+Enqueues a `Request` subclass and returns an awaitable that resolves to the
+handler's return value. Exceptions raised in the handler are re-raised in the
+caller.
+
+```python
+@dataclass
+class AddRequest(Request[int]):
+    a: int
+    b: int
+
+result = await addr.ask(AddRequest(a=1, b=2))  # -> int
+```
+
+### Message dispatch
+
+`BaseActor.on_message()` routes incoming messages automatically. For a message
+of class `FooBar`, it calls `self.on_foo_bar(msg)`. You only need to define
+handler methods -- no manual dispatch boilerplate. This is default (optional) behavior,
+feel free to reimplement `BaseActor.on_message()` for your liking.
+
+```python
+class MyActor(BaseActor):
+    def on_foo_bar(self, msg: FooBar) -> None: ...
+    def on_add_request(self, msg: AddRequest) -> int: ...
+```
+
+Handler methods may be plain or async.
+
+
+## Lifecycle Hooks
+
+Override any of these on your actor class:
+
+    on_start()
+        Called before the mailbox loop begins.
+        Use it to initialize resources or start child actors.
+
+    on_stop()
+        Called after the mailbox loop exits, regardless of the stop reason.
+        Use it to clean up resources.
+
+    on_task_create()
+        Return a coroutine to run as a background task alongside the mailbox
+        loop. If the background task raises an unhandled exception, the actor
+        stops.
+
+    on_link_death(actor_id: str, reason: StopReasonType) -> LinkAction
+        Called when a monitored actor stops. Return LinkAction.Stop (default)
+        to stop this actor too, or LinkAction.Continue to keep running.
+
+All hooks may be async.
+
+
+## Supervision and Linking
+
+Actors can monitor each other. When a monitored actor stops, the monitoring
+actor's `on_link_death()` hook is called.
+
+```python
+# source stops -> monitor.on_link_death() is called
+hive.link_actors(source_addr, monitor_addr)
+
+# bidirectional: each monitors the other
+hive.link_actors_both(addr_a, addr_b)
+
+# monitor from within an actor (self monitors another)
+self.as_ref().monitor(other_addr)
+```
+
+### Stop reasons
+
+`on_link_death` receives one of:
+
+    StopReason.Stop       -- actor stopped normally
+    StopReason.Shutdown   -- hive-wide shutdown
+    StopReason.LinkDeath  -- a linked actor died and propagated the stop
+    <exception instance>  -- actor crashed with an unhandled exception
+
+### Restarting crashed actors
+
+To restart a worker that crashes, return `LinkAction.Continue` from
+`on_link_death` and start a replacement:
+
+```python
+async def on_link_death(self, actor_id: str, reason: StopReasonType) -> LinkAction:
+    replacement = self.hive.start_actor(WorkerActor)
+    self.as_ref().monitor(replacement)
+    return LinkAction.Continue
+```
+
+## Examples
+
+**examples/calculator.py**: A calculator actor that handles arithmetic requests
+via `ask()` and receives periodic random values via `tell()` from a background
+task.
+
+**examples/supervisor.py**: A supervisor that manages a pool of workers, round-robins
+jobs to them, and automatically restarts any worker that crashes.
+
+Run an example:
+
+    uv run examples/calculator.py
+    uv run examples/supervisor.py
+
+
+## Development
+
+Run tests:
+
+    uv run pytest
+
+Lint and type check:
+
+    uv run ruff check --fix
+    uv run pyright
+
+
+## License
+
+MIT - see LICENSE file.
+
+
+## Use of LLMs
+
+This project has been made by the use of LLMs in following areas:
+
+- Code review
+- Preparing test cases for discovered issues
+- Preparing and verifying documentation

mindmesh-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "mindmesh"
+version = "0.1.0"
+description = "Actor system for asyncio environments"
+readme = "README.md"
+authors = [{ name = "Marcin Glinski", email = "undefinedlamb@gmail.com" }]
+requires-python = ">=3.11"
+license = { text = "MIT" }
+keywords = ["asyncio", "actors", "distributed", "mesh", "concurrency"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.2",
+    "pyright>=1.1.408",
+    "pre-commit>=4.5.1",
+]
+
+[tool.uv]
+managed = true
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "ASYNC"]
+ignore = ["B027"]
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+reportMissingTypeStubs = true
+pythonVersion = "3.11"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mindmesh-0.1.0/src/mindmesh/__init__.py

@@ -0,0 +1,15 @@
+from .actor import BaseActor, LinkAction
+from .core import Request, StopReason, StopReasonType, T_Response
+from .hive import ActorHive
+from .proxy import ActorAddr
+
+__all__ = [
+    "BaseActor",
+    "ActorHive",
+    "Request",
+    "T_Response",
+    "ActorAddr",
+    "LinkAction",
+    "StopReason",
+    "StopReasonType",
+]

mindmesh-0.1.0/src/mindmesh/actor.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+from .core import Envelope, StopReason
+from .proxy import ActorAddr
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine, Generator
+
+    from .core import Request, StopReasonType, T_Response
+    from .hive import ActorHive
+
+
+logger = logging.getLogger(__package__)
+
+
+class LinkAction(Enum):
+    """Return value of :meth:`BaseActor.on_link_death` controlling what happens next."""
+
+    Continue = 0
+    """Keep this actor running after a monitored actor dies."""
+    Stop = 1
+    """Stop this actor when a monitored actor dies."""
+
+
+class BaseActor:
+    """Base class for all actors. Subclass this to implement actor behaviour.
+
+    Messages are dispatched by :meth:`on_message` to methods named
+    ``on_<snake_case_type>`` - e.g. a ``MyRequest`` message calls
+    ``on_my_request(msg)``.
+
+    Lifecycle::
+
+        on_start() -> [message loop] -> on_stop()
+    """
+
+    def __init__(self, hive: ActorHive, actor_id: str):
+        self._hive = hive
+        self._id = actor_id
+        self._mailbox: asyncio.Queue[Envelope] = asyncio.Queue()
+        self._startup_future: asyncio.Future[bool] = asyncio.Future()
+        self._running = False
+        self._event_loop: asyncio.Task[None] | None = None
+        self._bg_task: asyncio.Task[None] | None = None
+        self._stop_event: asyncio.Event = asyncio.Event()
+        self._stop_reason: StopReasonType | None = None
+        self._ref: ActorAddr = ActorAddr(hive, actor_id)
+
+    @property
+    def hive(self) -> ActorHive:
+        """The hive this actor belongs to."""
+        return self._hive
+
+    @property
+    def id(self) -> str:
+        """Unique ID of this actor."""
+        return self._id
+
+    def as_ref(self) -> ActorAddr:
+        """Return an :class:`ActorAddr` pointing to this actor."""
+        return self._ref
+
+    def start(self) -> None:
+        """Start the actor's event loop.
+
+        Called by the hive; use :meth:`ActorAddr.start` instead.
+        """
+        if self._event_loop:
+            logger.warning(f"Actor {self.id} already running")
+        else:
+            self._event_loop = asyncio.create_task(self._loop())
+
+    def stop(self, reason: StopReasonType = StopReason.Stop) -> None:
+        """Cancel the actor's event loop with the given reason."""
+        if not self._event_loop:
+            raise RuntimeError(f"Actor {self.id} not started")
+        if self._stop_reason is not None:
+            return
+        self._stop_reason = reason
+        self._event_loop.cancel()
+
+    def stop_self(self) -> None:
+        """Schedule this actor to stop itself.
+
+        Safe to call from within a message handler.
+        """
+
+        async def stop_deffered(hive: ActorHive, actor_id: str):
+            hive.request_actor_stop(actor_id, StopReason.Stop)
+
+        asyncio.create_task(stop_deffered(self._hive, self.id))
+
+    def ask(self, request: Request[T_Response]) -> asyncio.Future[T_Response]:
+        """Enqueue a request and return a future for the response.
+
+        Must not be called from within the actor's own message loop.
+        Use :meth:`ActorAddr.ask` from outside instead.
+        """
+        if self._is_called_from_self():
+            raise RuntimeError("ask() called from the actor's message loop")
+        future = asyncio.get_running_loop().create_future()
+        self._mailbox.put_nowait(Envelope(payload=request, reply_to=future))
+        return future
+
+    def tell(self, event: Any) -> None:
+        """Enqueue a fire-and-forget message with no reply."""
+        self._mailbox.put_nowait(Envelope(payload=event, reply_to=None))
+
+    async def wait_for_startup(self) -> None:
+        """Block until this actor has completed :meth:`on_start`."""
+        await self._startup_future
+
+    async def wait_for_stop(self) -> None:
+        """Block until this actor has fully stopped."""
+        await self._stop_event.wait()
+
+    # --------------------- Lifecycle callbacks ----------------------------- #
+
+    async def on_link_death(self, actor_id: str, reason: StopReasonType) -> LinkAction:
+        """Called when a monitored actor stops.
+
+        Default behaviour: stop self. Override to handle the event differently
+        and return :attr:`LinkAction.Continue` to keep running.
+        """
+        logger.warning(f"Link '{actor_id}' died: {reason} - stopping {self.id}")
+        return LinkAction.Stop
+
+    async def on_message(self, message: Any) -> Any:
+        """Dispatch an incoming message to the appropriate handler method.
+
+        Resolves the handler as ``on_<snake_case_type_name>`` and
+        calls it. Override to implement custom dispatch logic.
+        """
+        type_name = type(message).__name__
+        method_name = f"on_{snake_case(type_name)}"
+        if (method := getattr(self, method_name, None)) is None:
+            raise NotImplementedError(
+                f"{type(self).__name__} does not implement {method_name}"
+            )
+        if not callable(method):
+            raise TypeError(f"{type_name}.{method_name} must be callable")
+        result = method(message)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    async def on_start(self) -> None:
+        """Called once before the message loop begins.
+
+        Override for initialisation logic.
+        """
+        logger.debug(f"Actor {self.id} is starting")
+
+    async def on_stop(self) -> None:
+        """Called once after the message loop ends.
+
+        Override for cleanup logic.
+        """
+        logger.debug(f"Actor {self.id} is stopping")
+
+    def on_task_create(self) -> Coroutine[Any, Any, None] | None:
+        """Return a coroutine to run as a background task alongside the message loop.
+
+        The task is cancelled when the actor stops. Return ``None`` (default) for
+        no background task.
+        """
+        return None
+
+    # --------------------- Internals --------------------------------------- #
+
+    async def _loop(self) -> None:
+        """Main event loop."""
+        try:
+            # Handle start lifecycle event
+            await self.on_start()
+        except Exception as e:
+            logger.error(f"Actor {self.id} not started", exc_info=e)
+            self._startup_future.set_exception(e)
+            return
+
+        if task := self.on_task_create():
+            logger.debug(f"Starting background task {task}")
+            self._bg_task = asyncio.create_task(task)
+            self._bg_task.add_done_callback(self._on_bg_task_done)
+
+        # Notify we started
+        self._startup_future.set_result(True)
+        self._running = True
+
+        reason: StopReasonType = StopReason.Stop
+        try:
+            # Start the main loop
+            while self._running:
+                envelope = await self._mailbox.get()
+                if envelope.payload is None and envelope.reply_to is None:
+                    # Skip dummy envelopes
+                    continue
+                exception_to_set = None
+                result_to_set = None
+                try:
+                    # Handle message lifecycle event
+                    result_to_set = await self.on_message(envelope.payload)
+                except Exception as e:
+                    exception_to_set = e
+                finally:
+                    if envelope.reply_to and not envelope.reply_to.done():
+                        if exception_to_set:
+                            envelope.reply_to.set_exception(exception_to_set)
+                        else:
+                            envelope.reply_to.set_result(result_to_set)
+                    self._mailbox.task_done()
+
+        except asyncio.CancelledError:
+            if self._stop_reason:
+                reason = self._stop_reason
+
+        except Exception as e:
+            logger.error("Unhandled exception in main loop!", exc_info=e)
+            reason = e
+
+        finally:
+            if self._bg_task:
+                logger.debug("Cancelling background task")
+                self._bg_task.cancel()
+
+            self._drain_mailbox()
+
+            # Handle stop lifecycle event
+            try:
+                await self.on_stop()
+            except Exception as e:
+                logger.error(f"on_stop() raised in actor {self.id}", exc_info=e)
+
+            try:
+                await self.hive.on_actor_stopped(self.id, reason)
+            except Exception as e:
+                logger.error(
+                    f"on_actor_stopped() raised for actor {self.id}",
+                    exc_info=e,
+                )
+
+            self._stop_event.set()
+
+    def _drain_mailbox(self) -> None:
+        while not self._mailbox.empty():
+            try:
+                envelope = self._mailbox.get_nowait()
+                if envelope.reply_to and not envelope.reply_to.done():
+                    envelope.reply_to.set_exception(
+                        RuntimeError(
+                            f"Actor {self.id} stopped while request was pending"
+                        )
+                    )
+            except asyncio.QueueEmpty:
+                break
+
+    def _on_bg_task_done(self, task: asyncio.Task[None]) -> None:
+        if task.cancelled():
+            return
+        if exc := task.exception():
+            logger.error(f"Background task failed for actor {self.id}", exc_info=exc)
+            self.stop(exc)
+
+    def _is_called_from_self(self) -> bool:
+        current_task = asyncio.current_task()
+        return current_task is not None and current_task is self._event_loop
+
+
+def snake_case(name: str) -> str:
+    """Convert a CamelCase name to snake_case."""
+
+    def sliding_window(x: str) -> Generator[tuple[str, str, str], Any, Any]:
+        x = "_" + x + "_"
+        for i in range(1, len(x) - 1):
+            yield (x[i - 1], x[i], x[i + 1])
+
+    def convert(prev: str, cur: str, nxt: str) -> str:
+        if cur == "_" or cur.isdigit():
+            return cur
+        if cur.islower() and not prev.isdigit():
+            return cur
+        if cur.isupper() and prev.isupper() and not nxt.islower():
+            return cur.lower()
+        return "_" + cur.lower()
+
+    return "".join(
+        convert(prev, cur, nxt) for prev, cur, nxt in sliding_window(name)
+    ).lstrip("_")

mindmesh-0.1.0/src/mindmesh/core.py

@@ -0,0 +1,50 @@
+import asyncio
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Generic, TypeVar
+
+
+class StopReason(Enum):
+    """Reason an actor was stopped normally (non-exception path)."""
+
+    Stop = "stop"
+    """Explicit stop requested via :meth:`ActorAddr.stop` or
+    :meth:`BaseActor.stop_self`.
+    """
+
+    Shutdown = "shutdown"
+    """Hive-wide shutdown triggered by :meth:`ActorHive.shutdown`."""
+
+    LinkDeath = "link_death"
+    """A monitored actor stopped, propagating its death to this actor."""
+
+
+StopReasonType = StopReason | BaseException
+"""Either a :class:`StopReason` value or an unhandled exception that caused
+the actor to die.
+"""
+
+
+@dataclass
+class Envelope:
+    """Internal message wrapper used by the actor mailbox.
+
+    Not part of the public API.
+    """
+
+    payload: Any
+    reply_to: asyncio.Future[Any] | None
+
+
+T_Response = TypeVar("T_Response")
+"""Type variable for the response type of a :class:`Request`."""
+
+
+class Request(Generic[T_Response]):
+    """Base class for request messages sent via :meth:`ActorAddr.ask`.
+
+    Subclass this to define a typed request/response pair::
+
+        class GetCount(Request[int]):
+            pass
+    """

mindmesh-0.1.0/src/mindmesh/hive.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from .actor import BaseActor, LinkAction
+from .core import StopReason
+from .registry import ActorRegistry
+
+if TYPE_CHECKING:
+    from .core import Request, StopReasonType, T_Response
+    from .proxy import ActorAddr
+    from .registry import ActorContext
+
+logger = logging.getLogger(__package__)
+T = TypeVar("T", bound=BaseActor)
+
+
+class ActorFactory:
+    """Responsible for instantiating actors.
+
+    Override to customise actor creation.
+    """
+
+    def create(
+        self,
+        hive: ActorHive,
+        actor_class: type[T],
+        actor_id: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> T:
+        return actor_class(hive, actor_id, *args, **kwargs)
+
+
+class ActorHive:
+    """Central runtime that owns and coordinates all actors.
+
+    Typical usage:
+
+        hive = ActorHive()
+        addr = hive.start_actor(MyActor)
+        await addr.ask(MyRequest())
+        await hive.shutdown()
+
+    Args:
+        factory: Optional custom :class:`ActorFactory` for actor instantiation.
+        registry: Optional custom :class:`ActorRegistry`.
+    """
+
+    def __init__(
+        self, factory: ActorFactory | None = None, registry: ActorRegistry | None = None
+    ) -> None:
+        self._next_id = 0
+        self._actor_factory = factory if factory else ActorFactory()
+        self._registry = registry if registry else ActorRegistry()
+
+    # ------------------------------- Public API ---------------------------------------
+
+    @property
+    def actor_ids(self) -> list[str]:
+        """IDs of all currently registered actors."""
+        return self._registry.actor_ids
+
+    async def ask_actor(
+        self,
+        actor_id: str,
+        request: Request[T_Response],
+    ) -> T_Response:
+        """Send a request to an actor by ID and await its typed response."""
+        if actor := self._registry.get_actor(actor_id):
+            return await actor.ask(request)
+        raise ValueError(f"Actor {actor_id} not found")
+
+    def create_actor(
+        self, actor_class: type[T], *args: Any, **kwargs: Any
+    ) -> ActorAddr:
+        """Instantiate and register an actor without starting it.
+
+        Returns proxy object.
+        """
+        actor_id = f"{actor_class.__name__}-{self._next_id}"
+        self._next_id += 1
+        actor = self._actor_factory.create(self, actor_class, actor_id, *args, **kwargs)
+        return self._registry.register(actor_id, actor).actor_ref
+
+    def create_named_actor(
+        self, name: str, actor_class: type[T], *args: Any, **kwargs: Any
+    ) -> ActorAddr:
+        """Instantiate and register an actor under a given name without starting it.
+
+        Returns proxy object.
+        """
+        actor_id = f"{actor_class.__name__}-{self._next_id}"
+        self._next_id += 1
+        actor = self._actor_factory.create(self, actor_class, actor_id, *args, **kwargs)
+        return self._registry.register(actor_id, actor, name=name).actor_ref
+
+    def link_actors(self, source_id: str, monitor_id: str) -> None:
+        """Make *monitor_id* watch *source_id*
+
+        When *source_id* stops, *monitor_id* is notified."""
+        self._registry.add_monitor(source_id, monitor_id)
+
+    def link_actors_both(self, actor1: str, actor2: str) -> None:
+        """Bidirectional link: each actor monitors the other."""
+        self._registry.add_monitor(actor1, actor2, both=True)
+
+    def lookup(self, actor_name: str) -> ActorAddr | None:
+        """Return the address of a named actor, or ``None`` if not found."""
+        if context := self._registry.get_by_name(actor_name):
+            return context.actor_ref
+        return None
+
+    def register(self, actor_name: str, addr: ActorAddr) -> None:
+        """Associate *name* with an existing actor address for later :meth:`lookup`."""
+        self._registry.register_name(actor_name, addr.id())
+
+    def request_actor_start(self, actor_id: str) -> None:
+        """Trigger the start sequence of an already-registered actor."""
+        if not (actor := self._registry.get_actor(actor_id)):
+            raise ValueError(f"Actor {actor_id} not found")
+        try:
+            actor.start()
+        except Exception as e:
+            logger.error(
+                f"Unhandled exception while starting actor {actor_id}", exc_info=e
+            )
+            raise
+
+    def request_actor_stop(self, actor_id: str, reason: StopReasonType) -> None:
+        """Request an actor to stop with the given reason.
+
+        No-op if already stopped.
+        """
+        if not (actor := self._registry.get_actor(actor_id)):
+            return  # Actor already stopped and removed
+        actor.stop(reason)
+
+    async def shutdown(self) -> None:
+        """Stop all actors and wait for them to finish.
+
+        Call this to cleanly tear down the hive.
+        """
+        logger.debug("Shutting down the hive")
+        for actor_id in self._registry.actor_ids:
+            try:
+                self.request_actor_stop(actor_id, StopReason.Shutdown)
+            except RuntimeError:
+                self._registry.unregister(actor_id)
+        await asyncio.gather(
+            *(
+                self.wait_for_actor_stop(actor_id)
+                for actor_id in self._registry.actor_ids
+            )
+        )
+
+    def start_actor(self, actor_class: type[T], *args: Any, **kwargs: Any) -> ActorAddr:
+        """Create and immediately start an actor.
+
+        Equivalent to :meth:`create_actor` + :meth:`request_actor_start`.
+        """
+        actor_ref = self.create_actor(actor_class, *args, **kwargs)
+        self.request_actor_start(actor_ref.id())
+        return actor_ref
+
+    def start_named_actor(
+        self, name: str, actor_class: type[T], *args: Any, **kwargs: Any
+    ) -> ActorAddr:
+        """Create and immediately start an actor.
+
+        Actor is registered under the name for later :meth:`lookup`.
+
+        Like :meth:`start_actor` but also registers the actor under *name*.
+        """
+        actor_ref = self.create_named_actor(name, actor_class, *args, **kwargs)
+        self.request_actor_start(actor_ref.id())
+        return actor_ref
+
+    def tell(self, actor_id: str, event: Any) -> None:
+        """Send a fire-and-forget message to an actor by ID."""
+        if actor := self._registry.get_actor(actor_id):
+            actor.tell(event)
+        else:
+            raise ValueError(f"Tell: actor {actor_id} not found")
+
+    async def wait_for_actor_start(self, actor_id: str) -> None:
+        """Block until the actor has finished its startup sequence."""
+        if actor := self._registry.get_actor(actor_id):
+            await actor.wait_for_startup()
+
+    async def wait_for_actor_stop(self, actor_id: str) -> None:
+        """Block until the actor has fully stopped."""
+        if actor := self._registry.get_actor(actor_id):
+            await actor.wait_for_stop()
+
+    # ------------------------------- Callbacks ----------------------------------------
+
+    async def on_actor_stopped(self, actor_id: str, reason: StopReasonType) -> None:
+        """Called by the framework when an actor stops.
+
+        Notifies monitors and cleans up the registry.
+        """
+        logger.debug(f"on_actor_stopped: {actor_id}: {reason}")
+        try:
+            actors_to_stop: list[ActorContext] = []
+            monitor_reason = (
+                reason if reason != StopReason.Stop else StopReason.LinkDeath
+            )
+
+            for monitor_context in self._registry.monitors(actor_id):
+                try:
+                    action = await monitor_context.actor.on_link_death(
+                        actor_id, monitor_reason
+                    )
+                    if action == LinkAction.Stop:
+                        actors_to_stop.append(monitor_context)
+                except ValueError:
+                    logger.error(
+                        f"Monitor {monitor_context.actor.id} of source {actor_id}"
+                        " - not found"
+                    )
+                    pass
+
+            for actor_context in actors_to_stop:
+                actor_context.actor_ref.stop()
+
+            self._registry.unregister(actor_id)
+
+        except ValueError:
+            logger.error(f"on_actor_stopped: actor {actor_id} no longer exists")
+            pass

mindmesh-0.1.0/src/mindmesh/proxy.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .core import StopReason
+
+if TYPE_CHECKING:
+    from .core import Request, T_Response
+    from .hive import ActorHive
+
+
+class ActorAddr:
+    """A reference to an actor.
+
+    Use this to interact with actors without holding a direct reference.
+
+    Obtain an ``ActorAddr`` with:
+    - :meth:`ActorHive.create_actor`
+    - :meth:`ActorHive.start_actor`,
+    - :meth:`BaseActor.as_ref`.
+    """
+
+    def __init__(self, hive: ActorHive, actor_id: str):
+        self._hive = hive
+        self._id = actor_id
+
+    def id(self) -> str:
+        """Return the unique ID of the referenced actor."""
+        return self._id
+
+    async def ask(self, request: Request[T_Response]) -> T_Response:
+        """Send a request and await a typed response."""
+        return await self._hive.ask_actor(self._id, request)
+
+    def monitor(self, actor_ref: ActorAddr) -> None:
+        """Monitor *actor_ref* from this actor.
+
+        Death of *actor_ref* triggers ``on_link_death``.
+        """
+        self._hive.link_actors(actor_ref.id(), self.id())
+
+    def start(self) -> None:
+        """Schedule the actor to start."""
+        self._hive.request_actor_start(self._id)
+
+    def stop(self) -> None:
+        """Schedule the actor to stop."""
+        self._hive.request_actor_stop(self._id, StopReason.Stop)
+
+    def tell(self, message: Any) -> None:
+        """Send a fire-and-forget message."""
+        self._hive.tell(self._id, message)
+
+    async def wait_for_start(self) -> None:
+        """Block until the actor has finished starting up."""
+        await self._hive.wait_for_actor_start(self._id)
+
+    async def wait_for_stop(self) -> None:
+        """Block until the actor has fully stopped."""
+        await self._hive.wait_for_actor_stop(self._id)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, ActorAddr) and self._id == other._id
+
+    def __hash__(self) -> int:
+        return hash(self._id)
+
+    def __repr__(self) -> str:
+        return f"ActorAddr{{id={self._id}}}"

mindmesh-0.1.0/src/mindmesh/registry.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from .actor import BaseActor
+
+if TYPE_CHECKING:
+    from .proxy import ActorAddr
+
+logger = logging.getLogger(__package__)
+
+
+@dataclass
+class ActorContext:
+    actor: BaseActor
+    actor_ref: ActorAddr
+    monitors: set[str] = field(default_factory=set[str])
+    monitored_by: set[str] = field(default_factory=set[str])
+    name: str | None = None
+
+
+class ActorRegistry:
+    def __init__(self):
+        self._contexts: dict[str, ActorContext] = {}
+        self._names: dict[str, ActorContext] = {}
+
+    @property
+    def actor_ids(self) -> list[str]:
+        return list(self._contexts.keys())
+
+    def add_monitor(self, source_id: str, monitor_id: str, both: bool = False) -> None:
+        if source_id == monitor_id:
+            logger.warning(
+                f"Source {source_id} and Monitor {monitor_id} are the same actors"
+            )
+            return
+        if not (source := self.get(source_id)):
+            logger.debug(f"Source actor {source_id} not found")
+            return
+        if not (monitor := self.get(monitor_id)):
+            logger.debug(f"Monitor actor {monitor_id} not found")
+            return
+        source.monitored_by.add(monitor_id)
+        monitor.monitors.add(source_id)
+        if both:
+            monitor.monitored_by.add(source_id)
+            source.monitors.add(monitor_id)
+
+    def drop_monitor(self, monitor_id: str) -> None:
+        if not (monitor := self.get(monitor_id)):
+            return
+        for source_id in monitor.monitors:
+            if source := self.get(source_id):
+                source.monitored_by.discard(monitor_id)
+        monitor.monitors.clear()
+
+    def get(self, actor_id: str) -> ActorContext | None:
+        return self._contexts.get(actor_id)
+
+    def get_actor(self, actor_id: str) -> BaseActor | None:
+        if context := self.get(actor_id):
+            return context.actor
+        return None
+
+    def get_by_name(self, actor_name: str) -> ActorContext | None:
+        return self._names.get(actor_name)
+
+    def monitors(self, source_id: str) -> Generator[ActorContext, None, None]:
+        if not (source := self.get(source_id)):
+            logger.debug(f"Source {source_id} not found")
+            return
+        for monitor_id in list(source.monitored_by):
+            if monitor := self.get(monitor_id):
+                yield monitor
+            else:
+                logging.debug(f"Monitor {monitor_id} of source {source_id} not found")
+
+    def register(
+        self, actor_id: str, actor: BaseActor, name: str | None = None
+    ) -> ActorContext:
+        if actor_id in self._contexts:
+            raise ValueError(f"Actor {actor_id} already in the registry")
+        context = ActorContext(actor=actor, actor_ref=actor.as_ref())
+        self._contexts[actor_id] = context
+        if name:
+            try:
+                self.register_name(name, actor_id)
+            except ValueError:
+                self.unregister(actor_id)
+                raise
+        return context
+
+    def register_name(self, name: str, actor_id: str) -> None:
+        if not (context := self.get(actor_id)):
+            raise ValueError(f"Actor {actor_id} not found")
+        if context.name:
+            raise ValueError(
+                f"Actor {actor_id} previously registered as {context.name}"
+            )
+        if name in self._names:
+            other = self._names[name]
+            raise ValueError(
+                f"Actor {actor_id} could not be registered under name "
+                f"{name} - Actor {other.actor.id} was first."
+            )
+        context.name = name
+        self._names[name] = context
+
+    def unregister(self, actor_id: str) -> None:
+        self.drop_monitor(actor_id)
+        if actor := self.get(actor_id):
+            if actor.name and actor.name in self._names:
+                del self._names[actor.name]
+            del self._contexts[actor_id]
+        else:
+            logger.warning(f"Actor {actor_id} not registered")