ohra

Apache Pekko Typed actors on asyncio, for Python 3.12+. No dependencies. Ohra is Finnish for barley, the crop of Pekko, the Finnish god of barley and brewing.

ohra is an independent project, built on the design of Apache Pekko and, before it, Akka, with thanks to both communities. It follows their semantics and names closely, but it is not part of the Apache Software Foundation.

An actor is a function from a message to the next behavior. Typed refs make wrong messages a type error under pyright strict. Everything runs on one event loop, so a handler can await without losing the guarantee that an actor handles one message at a time. numpy work goes to threads and comes back as a message.

import asyncio
from dataclasses import dataclass
from ohra import ActorRef, ActorSystem, Behavior, Behaviors


@dataclass(frozen=True)
class Increment:
    by: int


@dataclass(frozen=True)
class GetTotal:
    reply_to: ActorRef[int]


type Command = Increment | GetTotal


def counter(total: int = 0) -> Behavior[Command]:
    @Behaviors.receive_message
    def on_message(msg: Command) -> Behavior[Command]:
        match msg:
            case Increment(by):
                return counter(total + by)  # state is the next behavior
            case GetTotal(reply_to):
                reply_to.tell(total)
                return Behaviors.same

    return on_message


async def main() -> None:
    async with ActorSystem(counter(), "demo") as system:
        system.tell(Increment(5))
        print(await system.ask(GetTotal, timeout=1))  # 5


asyncio.run(main())

If you know Apache Pekko or Akka Typed, the names are the same in snake_case, and the semantics are checked against the Apache Pekko source. If you don't, the book explains everything from the first actor to a sharded web app on Kubernetes.

Install

pip install -e .            # the library
pip install -e '.[numpy]'   # plus numpy, for the examples that use it
pip install -e '.[web]'     # plus FastAPI and uvicorn, for ohra.ext.fastapi and the fastapi_* examples
pip install -e '.[postgres]' # plus psycopg, for ohra.ext.postgres, the durable state store for clusters
pip install -e '.[torch]'   # plus PyTorch, for the purchase predictor example
pip install -e '.[dev]'     # plus pytest, pytest-asyncio, pyright, httpx

The book

How ohra works is the guide and the reference, one chapter per layer, with diagrams:

1. Actors: behaviors, ask, children and DeathWatch, supervision, timers and stash, routers, the runtime model
2. The actor system: guardians, extensions, the receptionist, coordinated shutdown
3. Persistence: write, then install, then reply; recovery in one read
4. Remoting: addresses, @remotable messages, connections
5. Cluster membership: gossip, the member lifecycle, failure detection, the split-brain resolver
6. Cluster singleton: one actor on the oldest member, and the hand-over
7. Sharding: regions, shards and the coordinator, in one process and across nodes
8. Management and Kubernetes: health checks, bootstrap, discovery, running on Docker Desktop
9. FastAPI: the actor system owned by the app, routes that ask actors
10. numpy and shared memory: blocking work in a thread, large arrays to another process without a copy
11. Putting it together: one cart request through every layer

Appendices: Apache Pekko names, known deviations from Apache Pekko, performance, and a glossary.

Examples

The last four need numpy: uv run --extra numpy python examples/bandit.py. The fastapi_* examples need the web extra and run under uvicorn: uv run --extra web uvicorn examples.fastapi_carts:app --port 8000.

Development

Layout follows Apache Pekko's modules: ohra is the actor core, ohra.remote the transport and serialization, ohra.cluster membership and the singleton, ohra.cluster.sharding the Shard, region and coordinator, ohra.ext the FastAPI, Postgres and shared-memory integrations. Every public name is importable from ohra and from its own subpackage.

pytest      # every test fails if any asyncio task outlives it
pyright     # strict; tests/typing_check.py asserts type errors that must occur

See CONTRIBUTING.md for setup, the runtime invariants and how to port from Apache Pekko. Report vulnerabilities as described in SECURITY.md.

License

Apache-2.0, the same as Apache Pekko. The chat room and interaction-pattern examples are derived from the Apache Pekko documentation; see NOTICE.

ohra is an independent project, not affiliated with or endorsed by the Apache Software Foundation or the Apache Pekko project. Apache Pekko is a trademark of the Apache Software Foundation.