Experimental Program API¶

mixle.experimental.program contains a move-based optimization-program API. It is kept for research workflows that do not fit the stable declarative surfaces yet. It is not the recommended first path for ordinary neural, probabilistic, or task modeling.

For new code, prefer:

mixle.stats and mixle.inference for explicit probabilistic models;
mixle.ppl for symbolic model expressions;
mixle.models for incubating neural leaves and applied model helpers;
mixle.task for task replacement, distillation, cascades, tool calling, and planning.

The compatibility module mixle.program re-exports the experimental program API so older imports continue to work.

When to Use It¶

Use the program surface when the optimization procedure is the object being studied: alternating objectives, replay buffers, continual-learning penalties, or adaptation routines that do not yet have a stable Mixle estimator or task abstraction.

Do not use it merely because a model has trainable parameters. If the goal is ordinary fitting, scoring, calibration, serving, or artifact management, the stable estimator, PPL, model, and task APIs provide clearer contracts and better documentation.

Core Idea¶

The program API describes optimization as a set of moves:

minimize(objective, over=params): Minimize a closure over parameters.
maximize(objective, over=params): Maximize a closure over parameters.
em(estimator, data, init): Treat EM as a move.
alternate(move_a, move_b, ...): Alternate between moves.
weighted([(loss_a, weight_a), ...], over=params): Combine weighted objectives.
constrain(g, bound=0.0, kind="<="): Add a constraint to an optimization move.
reinforce(sample_and_reward): Construct a policy-gradient style objective.
fit(program, ...): Execute a move or program.

The surface can express useful research patterns, but it depends heavily on closures. That is why stable Mixle workflows favor declarative estimators, PPL expressions, and task solvers when possible.

The closure-oriented design also means reproducibility is the caller’s responsibility. Record the data iterator, optimizer settings, random seeds, parameter selection policy, and any external module state needed to rerun the program.

Parameter Helpers¶

The module includes helpers for selecting and adapting trainable parameters:

trainable(module): Return trainable parameters from a module-like object.
freeze(module): Freeze a module’s parameters.
subset(module, *name_substrings): Select parameter subsets by name.
lora(module, rank=8, alpha=16.0): Add low-rank adaptation parameters to compatible linear modules.

These helpers are useful when experimenting with neural leaves or adaptation methods that are not yet expressed as stable Mixle model objects.

Check parameter selections before training. Substring-based selection is convenient for experiments, but a renamed layer can silently change what is updated. For release-like work, print or persist the selected parameter names with the experiment record.

Examples¶

Minimize a Torch loss:

from mixle.experimental.program import fit, minimize, trainable

move = minimize(lambda: loss_fn(batch), over=trainable(net), lr=1.0e-3)
fit(move, steps=200)

Alternate EM with a neural move:

from mixle.experimental.program import alternate, em, fit, minimize, trainable

program = alternate(
    em(estimator, rows, init=model0),
    minimize(lambda: neural_loss(rows), over=trainable(net)),
)

fit(program, steps=20)

Adapt a module with LoRA-style parameters:

from mixle.experimental.program import fit, lora, minimize

params = lora(module, rank=4)
fit(minimize(lambda: adaptation_loss(batch), over=params), steps=100)

Advanced Moves¶

The module also contains experimental support for:

Stream and ReplayBuffer: Streaming data and replay workflows.
snapshot / replay / distill / ewc / fisher_diagonal: Continual-learning and distillation-style objectives.
bilevel: Bilevel optimization experiments.
pareto: Multi-objective optimization with Pareto-style moves.
streaming_em: EM over a stream abstraction.
gail and maxent_irl: Imitation-learning and inverse-reinforcement-learning experiments.

Operational Cautions¶

Program-based workflows can be powerful, but they have fewer structural guarantees than estimator-based workflows. Before depending on a program result:

run a deterministic smoke test with a fixed seed;
record optimizer settings and parameter selections;
evaluate on data that was not used to tune the move schedule;
compare against the closest stable Mixle workflow when one exists;
keep program artifacts separate from production artifacts unless a promotion review accepts the experimental dependency.

Status and Stability¶

This API is explicitly experimental:

names and call signatures may change;
behavior may move into mixle.ppl, mixle.task, or a more mature mixle.models surface;
examples should be treated as exploratory workflows, not deployment guidance;
production artifacts should prefer stable estimator and inference interfaces whenever possible.

Use this surface when the optimization problem is genuinely program-shaped. Use the stable APIs when the goal is to fit, score, calibrate, explain, or operate a model.