casty 0.7.0

A minimalist, type-safe actor framework for Python 3.12+ inspired by Akka Typed

Minimalist, type-safe actor framework for Python 3.12+

Documentation · Getting Started · PyPI

---

Casty is an actor framework inspired by Akka Typed that brings the behavior-driven, functional actor model to Python. Instead of threads, locks, and shared mutable state, you model your system as independent actors that communicate exclusively through messages.

Quick Start

pip install casty

import asyncio
from dataclasses import dataclass
from casty import ActorContext, ActorSystem, Behavior, Behaviors

@dataclass(frozen=True)
class Greet:
    name: str

def greeter() -> Behavior[Greet]:
    async def receive(ctx: ActorContext[Greet], msg: Greet) -> Behavior[Greet]:
        print(f"Hello, {msg.name}!")
        return Behaviors.same()

    return Behaviors.receive(receive)

async def main() -> None:
    async with ActorSystem() as system:
        ref = system.spawn(greeter(), "greeter")
        ref.tell(Greet("Alice"))
        ref.tell(Greet("Bob"))
        await asyncio.sleep(0.1)

asyncio.run(main())
# Hello, Alice!
# Hello, Bob!

Features

• Behaviors as values, not classes — No Actor base class. Behaviors are frozen dataclasses composed through factory functions.
• State via closures — Actor state is captured in closures. State transitions happen by returning a new behavior with new closed-over values. No mutable fields, no nonlocal.
• Immutability by default — All messages, behaviors, events, and configurations are frozen dataclasses.
• Type-safe end-to-end — ActorRef[M], Behavior[M], and PEP 695 type aliases ensure message type mismatches are caught at development time.
• Zero external dependencies — Pure Python, stdlib only.
• Supervision — "Let it crash" philosophy with configurable restart strategies, inspired by Erlang/OTP.
• Event sourcing — Persist actor state as a sequence of events with automatic recovery on restart.
• Cluster sharding — Distribute actors across nodes with gossip-based membership, phi accrual failure detection, and automatic shard rebalancing.
• Shard replication — Passive replicas with automatic promotion on node failure.
• Cluster broadcast — Fan-out messages to all nodes with typesafe aggregated responses.
• Distributed data structures — Counter, Dict, Set, Queue, Lock, Semaphore, and Barrier built on sharded actors.
• TOML configuration — Optional casty.toml for environment-specific tuning with per-actor overrides.

Documentation

Full documentation is available at gabfssilva.github.io/casty.

Section	Description
Getting Started	Installation and first steps
Concepts	Actors, behaviors, state, request-reply, hierarchies, supervision, state machines
Persistence	Event sourcing with journals and snapshots
Clustering	Sharding, broadcast, replication, distributed data structures
Configuration	TOML-based configuration with per-actor overrides
API Reference	Complete API documentation

Contributing

git clone https://github.com/gabfssilva/casty
cd casty
uv sync
uv run pytest                    # run tests
uv run pyright src/casty/        # type checking (strict mode)
uv run ruff check src/ tests/    # lint
uv run ruff format src/ tests/   # format

License

MIT — see LICENSE for details.