Configuration

casty.CastyConfig dataclass

Top-level configuration container for a Casty actor system.

Holds system-wide defaults, cluster settings, and per-actor overrides. Typically created via load_config() but can be constructed manually.

Parameters:

Name	Type	Description	Default
system_name	str	Logical name of the actor system.	'casty'
cluster	ClusterConfig | None	Cluster settings (None for local-only systems).	None
transport	TransportConfig	Transport-layer tuning.	TransportConfig()
serialization	SerializationConfig	Serialization settings for inter-node communication.	SerializationConfig()
gossip	GossipConfig	Gossip protocol tuning.	GossipConfig()
heartbeat	HeartbeatConfig	Heartbeat exchange tuning.	HeartbeatConfig()
failure_detector	FailureDetectorConfig	Phi accrual failure detector tuning.	FailureDetectorConfig()
defaults_mailbox	MailboxConfig	System-wide default mailbox settings.	MailboxConfig()
defaults_supervision	SupervisionConfig	System-wide default supervision settings.	SupervisionConfig()
defaults_sharding	ShardingConfig	System-wide default sharding settings.	ShardingConfig()
defaults_replication	ReplicationConfig	System-wide default replication settings.	ReplicationConfig()
actors	tuple[ActorConfig, ...]	Per-actor overrides matched by name pattern.	()

Examples:

>>> config = CastyConfig(system_name="my-app")
>>> config.system_name
'my-app'

>>> config = load_config(Path("casty.toml"))

system_name = 'casty' class-attribute instance-attribute

cluster = None class-attribute instance-attribute

tls = None class-attribute instance-attribute

transport = field(default_factory=TransportConfig) class-attribute instance-attribute

serialization = field(default_factory=SerializationConfig) class-attribute instance-attribute

gossip = field(default_factory=GossipConfig) class-attribute instance-attribute

heartbeat = field(default_factory=HeartbeatConfig) class-attribute instance-attribute

failure_detector = field(default_factory=FailureDetectorConfig) class-attribute instance-attribute

defaults_mailbox = field(default_factory=MailboxConfig) class-attribute instance-attribute

defaults_supervision = field(default_factory=SupervisionConfig) class-attribute instance-attribute

defaults_sharding = field(default_factory=ShardingConfig) class-attribute instance-attribute

defaults_replication = field(default_factory=ReplicationConfig) class-attribute instance-attribute

suppress_dead_letters_on_shutdown = False class-attribute instance-attribute

actors = () class-attribute instance-attribute

resolve_actor(name)

Resolve the effective configuration for an actor by name.

Merges the first matching ActorConfig override (if any) on top of the system defaults.

Parameters:

Name	Type	Description	Default
name	str	Actor name to resolve.	required

Returns:

Type	Description
ResolvedActorConfig

Examples:

>>> cfg = CastyConfig()
>>> resolved = cfg.resolve_actor("my-actor")
>>> resolved.supervision.strategy
'restart'

__init__(system_name='casty', cluster=None, tls=None, transport=TransportConfig(), serialization=SerializationConfig(), gossip=GossipConfig(), heartbeat=HeartbeatConfig(), failure_detector=FailureDetectorConfig(), defaults_mailbox=MailboxConfig(), defaults_supervision=SupervisionConfig(), defaults_sharding=ShardingConfig(), defaults_replication=ReplicationConfig(), suppress_dead_letters_on_shutdown=False, actors=())

casty.load_config(path=None)

Load a CastyConfig from a TOML file.

If path is None, auto-discovers casty.toml by walking up from the current working directory. Returns default config if no file is found.

Parameters:

Name	Type	Description	Default
path	Path | None	Explicit path to a TOML config file.	None

Returns:

Type	Description
CastyConfig

Raises:

Type	Description
FileNotFoundError	If an explicit path is given but does not exist.

Examples:

>>> config = load_config()
>>> config = load_config(Path("casty.toml"))
>>> config.system_name
'casty'

casty.discover_config(start=None)

Walk up from start (default: cwd) looking for casty.toml.

Parameters:

Name	Type	Description	Default
start	Path | None	Directory to start searching from.	None

Returns:

Type	Description
Path | None	Path to the discovered config file, or None if not found.

Examples:

>>> discover_config(Path("/my/project"))
PosixPath('/my/project/casty.toml')

casty.ActorConfig dataclass

Per-actor configuration override matched by name pattern.

When CastyConfig.resolve_actor(name) is called, the first ActorConfig whose pattern matches name supplies overrides for mailbox, supervision, sharding, and replication settings.

Parameters:

Name	Type	Description	Default
pattern	Pattern[str]	Regex matched against actor names via fullmatch.	required
mailbox_overrides	dict[str, Any]	Fields to override in MailboxConfig.	required
supervision_overrides	dict[str, Any]	Fields to override in SupervisionConfig.	required
sharding_overrides	dict[str, Any]	Fields to override in ShardingConfig.	required
replication_overrides	dict[str, Any]	Fields to override in ReplicationConfig.	required

Examples:

>>> ActorConfig(
...     pattern=re.compile("worker-.*"),
...     mailbox_overrides={"capacity": 5000},
...     supervision_overrides={},
...     sharding_overrides={},
...     replication_overrides={},
... )
ActorConfig(pattern=..., ...)

pattern instance-attribute

mailbox_overrides instance-attribute

supervision_overrides instance-attribute

sharding_overrides instance-attribute

replication_overrides instance-attribute

__init__(pattern, mailbox_overrides, supervision_overrides, sharding_overrides, replication_overrides)

casty.CompressionAlgorithm = Literal['zlib', 'gzip', 'bz2', 'lzma', 'lz4']

casty.CompressionConfig dataclass

Compression settings for serialized messages.

Parameters:

Name	Type	Description	Default
algorithm	CompressionAlgorithm	Compression algorithm: "zlib", "gzip", "bz2", or "lzma".	'zlib'
level	int	Compression level (0-9 for zlib/gzip/bz2, 0-9 for lzma preset).	6

Examples:

>>> CompressionConfig(algorithm="gzip", level=9)
CompressionConfig(algorithm='gzip', level=9)

algorithm = 'zlib' class-attribute instance-attribute

level = 6 class-attribute instance-attribute

__init__(algorithm='zlib', level=6)

casty.MailboxConfig dataclass

Default mailbox settings applied to every actor unless overridden.

Parameters:

Name	Type	Description	Default
capacity	int | None	Maximum number of messages in the mailbox. None for unbounded.	None
strategy	MailboxStrategy	Overflow strategy: "drop_new", "drop_oldest", or "reject".	'drop_new'

Examples:

>>> MailboxConfig(capacity=500, strategy="drop_oldest")
MailboxConfig(capacity=500, strategy='drop_oldest')

capacity = None class-attribute instance-attribute

strategy = 'drop_new' class-attribute instance-attribute

__init__(capacity=None, strategy='drop_new')

casty.SerializationConfig dataclass

Serialization settings for inter-node communication.

Parameters:

Name	Type	Description	Default
serializer	SerializerKind	Serializer implementation: "pickle" or "json".	'pickle'
compression	CompressionConfig | None	Compression settings. None means no compression (opt-in).	None

Examples:

>>> SerializationConfig(serializer="pickle", compression=CompressionConfig())
SerializationConfig(serializer='pickle', compression=CompressionConfig(...))

serializer = 'pickle' class-attribute instance-attribute

compression = None class-attribute instance-attribute

__init__(serializer='pickle', compression=None)

casty.SerializerKind = Literal['pickle', 'json', 'msgpack', 'cloudpickle']

casty.SupervisionConfig dataclass

Default supervision settings for child actors.

Parameters:

Name	Type	Description	Default
strategy	str	One of "restart", "stop", or "escalate".	'restart'
max_restarts	int	Maximum restarts allowed within the time window.	3
within_seconds	float	Rolling window (seconds) for restart counting.	60.0

Examples:

>>> SupervisionConfig(strategy="stop")
SupervisionConfig(strategy='stop', max_restarts=3, within_seconds=60.0)

strategy = 'restart' class-attribute instance-attribute

max_restarts = 3 class-attribute instance-attribute

within_seconds = 60.0 class-attribute instance-attribute

__init__(strategy='restart', max_restarts=3, within_seconds=60.0)

casty.ShardingConfig dataclass

Default sharding settings.

Parameters:

Name	Type	Description	Default
num_shards	int	Number of virtual shards to distribute across the cluster.	256

Examples:

>>> ShardingConfig(num_shards=512)
ShardingConfig(num_shards=512)

num_shards = 256 class-attribute instance-attribute

__init__(num_shards=256)

casty.FailureDetectorConfig dataclass

Phi accrual failure detector tuning (Hayashibara et al.).

Parameters:

Name	Type	Description	Default
threshold	float	Phi value above which a node is considered unreachable.	8.0
max_sample_size	int	Maximum heartbeat interval samples to retain.	200
min_std_deviation_ms	float	Floor for the standard deviation estimate (ms).	100.0
acceptable_heartbeat_pause_ms	float	Grace period added to the heartbeat interval estimate (ms).	0.0
first_heartbeat_estimate_ms	float	Initial heartbeat interval estimate before real samples arrive (ms).	1000.0

Examples:

>>> FailureDetectorConfig(threshold=12.0, max_sample_size=500)
FailureDetectorConfig(threshold=12.0, max_sample_size=500, ...)

threshold = 8.0 class-attribute instance-attribute

max_sample_size = 200 class-attribute instance-attribute

min_std_deviation_ms = 100.0 class-attribute instance-attribute

acceptable_heartbeat_pause_ms = 0.0 class-attribute instance-attribute

first_heartbeat_estimate_ms = 1000.0 class-attribute instance-attribute

__init__(threshold=8.0, max_sample_size=200, min_std_deviation_ms=100.0, acceptable_heartbeat_pause_ms=0.0, first_heartbeat_estimate_ms=1000.0)

casty.GossipConfig dataclass

Gossip protocol tuning.

Parameters:

Name	Type	Description	Default
interval	float	Seconds between gossip rounds.	1.0
fanout	int	Number of peers contacted per gossip round.	3

Examples:

>>> GossipConfig(interval=0.5, fanout=5)
GossipConfig(interval=0.5, fanout=5)

interval = 1.0 class-attribute instance-attribute

fanout = 3 class-attribute instance-attribute

__init__(interval=1.0, fanout=3)

casty.HeartbeatConfig dataclass

Heartbeat exchange tuning.

Parameters:

Name	Type	Description	Default
interval	float	Seconds between heartbeat sends to each monitored peer.	0.5
availability_check_interval	float	Seconds between phi-accrual availability checks.	2.0

Examples:

>>> HeartbeatConfig(interval=1.0, availability_check_interval=5.0)
HeartbeatConfig(interval=1.0, availability_check_interval=5.0)

interval = 0.5 class-attribute instance-attribute

availability_check_interval = 2.0 class-attribute instance-attribute

__init__(interval=0.5, availability_check_interval=2.0)

casty.ResolvedActorConfig dataclass

Fully resolved configuration for a single actor.

Produced by CastyConfig.resolve_actor(name) by merging per-actor overrides on top of the system defaults.

Parameters:

Name	Type	Description	Default
mailbox	MailboxConfig	Resolved mailbox settings.	required
supervision	SupervisionConfig	Resolved supervision settings.	required
sharding	ShardingConfig	Resolved sharding settings.	required
replication	ReplicationConfig	Resolved replication settings.	required

Examples:

>>> cfg = CastyConfig()
>>> resolved = cfg.resolve_actor("my-actor")
>>> resolved.mailbox.capacity
1000

mailbox instance-attribute

supervision instance-attribute

sharding instance-attribute

replication instance-attribute

__init__(mailbox, supervision, sharding, replication)

casty.TransportConfig dataclass

Transport-layer tuning.

Parameters:

Name	Type	Description	Default
max_pending_per_path	int	Maximum queued outbound messages per remote actor path.	64

Examples:

>>> TransportConfig(max_pending_per_path=128)
TransportConfig(max_pending_per_path=128)

max_pending_per_path = 64 class-attribute instance-attribute

__init__(max_pending_per_path=64)