Installation

git clone git@github.com:BasisResearch/effectful.git
cd effectful
git checkout master
pip install -e .[pyro]

pip install effectful[torch]

pip install effectful[pyro]

pip install effectful[jax]

pip install effectful[numpyro]

Getting Started

Here’s an example demonstrating how effectful can be used to implement a simple DSL that performs arithmetic on terms with free variables.

import functools

from effectful.ops.types import Term
from effectful.ops.syntax import defdata, defop
from effectful.ops.semantics import handler, evaluate, coproduct, fwd

add = defdata.dispatch(int).__add__

def beta_add(x: int, y: int) -> int:
    match x, y:
        case int(), int():
            return x + y
        case _:
            return fwd()

def commute_add(x: int, y: int) -> int:
    match x, y:
        case Term(), int():
            return y + x
        case _:
            return fwd()

def assoc_add(x: int, y: int) -> int:
    match x, y:
        case _, Term(op, (a, b)) if op == add:
            return (x + a) + b
        case _:
            return fwd()

beta_rules = {add: beta_add}
commute_rules = {add: commute_add}
assoc_rules = {add: assoc_add}

eager_mixed = functools.reduce(coproduct, (beta_rules, commute_rules, assoc_rules))

We can represent free variables as operations with no arguments, generated using defop:

>>> x = defop(int, name="x")
>>> y = defop(int, name="y")

If we evaluate an expression containing free variables, we get a term:

>>> e = 1 + 1 + (x() + 1) + (5 + y())
>>> print(e)
add(2, add(add(x(), 1), add(5, y())))

We can make the evaluation strategy smarter by taking advantage of the commutativity and associativity of addition, as expressed by the commute_add and assoc_add handlers.

>>> with handler(eager_mixed):
>>>     print(evaluate(e))
add(8, add(x(), y()))

Using with AI Agents

A standalone Markdown reference for building effectful LLM applications is published with each documentation build. Point your AI coding agent (e.g. Claude Code, Cursor, Copilot) to:

https://basisresearch.github.io/effectful/llm.md

This file is auto-generated from the LLM tutorial notebook and contains complete API usage examples for templates, tool calling, structured output, retries, and more.

Learn More

More examples and API documentation can be found in the docs.