autoform is an extensible framework for program transformations over user-defined types and operations. Rules describe how each operation behaves under a transform. The framework combines those rules to produce a new program, which can be executed or transformed again.

Programs can combine text, numbers, and user-defined structures. Extensions define the spaces used to represent values, changes, and feedback, together with the rules for operations on those values. This makes the same program available to different computations, including program optimization.

Installation

autoform requires Python 3.12 or later.

pip install git+https://github.com/ASEM000/autoform.git

A First Example

In this first example, a language model grades text based on a rubric. A points adjustment then raises or lowers the grade: an adjustment of 1 adds one point to every grade. The program has two parameters, the text rubric and the numerical adjustment.

The forward grading program A language model scores an example using a text rubric. A numerical adjustment adds or subtracts points from the score to produce a prediction. Blue arrows carry numbers; purple arrows carry text. 
import autoform as af


def forward(rubric, adjustment, x):
    # a slot that fill asks the lm to supply, constrained to 0 through 10
    score = af.lm.Float(min=0, max=10, desc="grading instructions")
    content = dict(rubric=rubric, example=x, score=score)
    # choose a litellm model, e.g. "openai/gpt-5.6"
    result = af.lm.fill(content, model="model-name")
    return result["score"] + adjustment

The predicted grade may not match the reference grade, so the loss program calculates the squared error between the two. The goal is to reduce this loss by updating the rubric and points adjustment while keeping the example and reference fixed.

Squared error measures the prediction error The loss program compares the adjusted language model score with a fixed target using squared error. Blue arrows carry numbers; purple arrows carry text. 
def loss_func(rubric, adjustment, x, y):
    x, y = af.stop_gradient((x, y))
    error = forward(rubric, adjustment, x) - y
    return error * error

Applying pullback to the loss program produces a program that returns the loss and feedback for its inputs. The rubric receives text feedback, while the points adjustment receives a numerical gradient. The example and reference grade have feedback blocked by stop_gradient. An update method can use the two remaining signals to propose a new rubric and adjustment.

Pullback adds reverse feedback to the grading program Pullback transforms the original program into a feedback program. Solid arrows carry forward values, and dashed arrows return feedback. Blue arrows carry numerical gradients; purple arrows carry text feedback for the rubric. The reference example and target are fixed. 
# set the text and numerical parameters
rubric = "rubric instructions"
adjustment = 0.0

# trace the grading program with one example
sample_inputs = (rubric, adjustment, "example text", 8.0)
program = af.trace(loss_func)(*sample_inputs)

# add text feedback for the rubric and gradients for the adjustment
feedback_program = af.pullback(program)

batch applies this feedback program across several examples. The rubric, points adjustment, and loss seed are shared, while the example text and reference grade vary together. The returned losses and feedback remain separate for each example, so an update method can decide how to combine them.

Batch runs the feedback program for each example Batch transforms the feedback program into one batched IR. Stacked program rectangles represent the batch dimension. The rubric, points adjustment, and loss seed are shared; each example and target vary. Each batch item returns its own loss and feedback. 
# choose examples and illustrative reference scores
examples = ["example text 1", "example text 2"]
targets = [8.0, 6.0]

# `False` axis means share the parameter, while True means batch it over
# programs. the tuple axesshape matches the shape of the arguments input
batch_axes = ((False, False, True, True), False)
batched_feedback = af.batch(feedback_program, in_axes=batch_axes)

# run the feedback program for all examples
batch_inputs = (rubric, adjustment, examples, targets)
losses, feedback = batched_feedback.call(batch_inputs, 1.0)

# keep rubric feedback and adjustment gradients
rubric_feedback, adjustment_grad, _, _ = feedback
print(losses, rubric_feedback, adjustment_grad)

This example composes transformations on a mixed-type program with a language model call. The transforms guide also covers:

  • pushforward: propagates input changes forward.

  • sched: groups independent operations for parallel execution.

  • weight: multiplies weights along the execution path.

  • dce: removes computations unused by the selected outputs.

More

The concepts guide explains tracing, types, spaces, and transformation rules.

The recipes cover tool use, tool ranking, human review, and array extensions.

Citation

The citation below identifies autoform in research that uses the framework:

@software{autoform,
  author       = {Asem, Mahmoud},
  title        = {AutoForm: Extensible Framework for Program Transformations over User-Defined Types},
  year         = {2026},
  url          = {https://github.com/ASEM000/autoform},
  doi          = {10.5281/zenodo.18071950},
  publisher    = {Zenodo},
  license      = {Apache-2.0}
}

Warning

autoform is in early development. API changes may require updates to existing code.

A First Program

A complete example of tracing, executing, and transforming a language model program.

A First Program
Concepts

The program representation, types and spaces, primitive rules, transforms, and execution behavior.

Concepts
Recipes

Examples that combine concepts for tool use, tool ranking, human review, and array extensions.

Recipes
API Reference

Public signatures, parameters, return values, and interfaces for extending the framework.

API Reference