🧩 composables

Familiar patterns. Beautiful types. Better code.

Your next abstraction might already have a name.

Zero runtime dependencies. Every notion uses only the Python standard library.

A growing catalog of notions: recurring patterns expressed through precise Python types. Give your code a shared vocabulary that makes intent easier to read, implementations easier to compose, and changes easier to check.

Agent

Give every interaction a clear contract.

Agent[State, Action] names both sides of an interaction. Yield actions, receive new observations through asend, and let the types describe the exchange before anyone reads the implementation.

interact(observation: State) → AsyncGenerator[Action, State]

The agent holds static configuration. Each call owns its interaction state and actions; concurrent calls on the same agent must remain independent.

Explore the Agent notion →

Policy

Turn an intention into a typed stream of actions.

Policy[State, Action] gives action generation a reusable shape. Start with an observation and produce an asynchronous action stream, with the input and output types visible at the boundary.

run(observation: State) → AsyncIterator[Action]

The policy holds static configuration. Each run owns its execution state and actions; concurrent runs on the same policy must remain independent.

Explore the Policy notion →

Environment

Make the world your code acts on explicit.

Environment[State, Action, Reward, Context] pairs a reusable factory with EnvironmentSession[State, Action, Reward, Context]. The types name what an action changes, what it earns, and what comes back with the result.

await session() → EnvironmentSession[State, Action, Reward, Context]
await __aenter__() → State
await step(action: Action) → tuple[State, Reward, Terminated, Truncated, Context]

The environment is stateless. Await environment.session() to create a session. Each session owns its interaction state and uses async with to scope resource acquisition and cleanup through its asynchronous __aenter__ and __aexit__ methods. Entering a session returns its initial state. Keep the session object to call session.step(action) and await its transition result.

session = await environment.session()
async with session as initial_state:
    transition = await session.step(action)

Two distinct boolean types give episode endings their own meaning:

Explore the Environment notion → · Episode types

Configurable

Give construction the same clarity as behavior.

Configurable[Configuration] binds a component to a configuration type you choose. Its factory accepts that type and returns Self, preserving the concrete subclass in the type contract.

from_configuration(configuration: Configuration) → Self

A shared construction pattern makes configuration requirements visible across implementations.

Explore the Configurable notion →