Skip to content

About

🧩 Familiar patterns, beautiful Python types, better code. Zero runtime dependencies.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation


GOOD PATTERNS DESERVE BEAUTIFUL TYPES.

🧩 composables

Familiar patterns. Beautiful types. Better code.

The patterns you reach for every day, expressed through precise Python types.
Turn familiar ideas into clear contracts and code worth building on.

Zero runtime dependencies. Built entirely on the Python standard library.

Python 3.12 or newer Zero runtime dependencies PEP 561 typing support MIT license Early development

Explore the notions →   ·   Shape what comes next ↗   ·   Follow releases



Your best patterns deserve better types.

Configuration factories. Action streams. Interactive agents. Stateful sessions. You reach for these patterns whenever you build something new.

composables gives them names and beautiful type definitions. We call them notions: recurring patterns expressed as small, precise contracts. Use them to make intent easier to read, implementations easier to compose, and changes easier to check.

The current package contains abstract base classes and domain types. You bring the behavior; the notions give your code a shared vocabulary.

🧩 Name the pattern

Give recurring ideas a recognizable shape. Agents, policies, environments, and configuration factories become concepts your code can speak.

⇄ Let the types explain

Generic parameters make inputs, outputs, and relationships explicit. See what a component accepts and produces before reading its implementation.

⌁ Raise the quality

Implement against shared contracts. Help readers follow intent, type checkers catch mismatches, and future changes preserve the boundaries you chose.

A small vocabulary. More expressive code.

Choose the notion that fits your pattern. Give its type parameters meaning in your domain.

flowchart LR
    agent["Agent<br/>Observations ↔ Actions"] --> implementation
    policy["Policy<br/>Observation → Action stream"] --> implementation
    environment["Environment<br/>Actions → Typed transitions"] --> implementation
    configurable["Configurable<br/>Configuration → Self"] --> implementation
    implementation["Your implementation<br/>Explicit contracts"] --> code
    code["Code you can<br/>read · compose · evolve"]

    classDef notion fill:#312e81,stroke:#a5b4fc,color:#ffffff,stroke-width:2px
    classDef outcome fill:#064e3b,stroke:#6ee7b7,color:#ffffff,stroke-width:2px
    class agent,policy,environment,configurable notion
    class implementation,code outcome
Loading

The types describe what goes in, what comes out, and how the pieces relate. Each notion also defines its behavioral contract, including execution state ownership and session lifetimes where relevant.

Choose your pieces: Agent · Policy · Environment & sessions · Configurable

Find your next notion in the catalog →

Get close to the code.

Use Python 3.12+ and the uv version pinned in pyproject.toml.

git clone https://github.com/betarixm/composables.git
cd composables
uv sync --locked

Open the catalog, recognize a pattern you use, and bring its type contract into your code.

Working on the notions? Run the checks.
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
uv build --package composables --no-sources

You're early. Help define the vocabulary.

The API is still taking shape. Your use case can help define what comes next.
Bring a pattern you keep writing. Help give it the type definition it deserves.

Star the repository to follow along. Open an issue to help steer it.

☆ Follow the project   ·   Bring your use case →

Composable primitives for Python · MIT licensed


About

🧩 Familiar patterns, beautiful Python types, better code. Zero runtime dependencies.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

Generated from betarixm/boilerplate