adaptcompile

adaptcompile is a model-agnostic Python library for representing, measuring, predicting, and selecting model adaptations.

adaptcompile treats model adaptation as a behavioral transformation that can be represented, measured, predicted, and selected independently of the training framework used to produce it.

See the architecture overview for how the objects fit together.

Installation

pip install adaptcompile

DataFrame exports are optional:

pip install "adaptcompile[dataframe]"

The reference prediction implementation is also optional:

pip install "adaptcompile[predict]"

For contributor setup:

python -m pip install -e ".[dev]"

Minimal example

from adaptcompile import (
    AdaptationResult,
    AdaptationStudy,
    LearningEpisode,
    ModelContext,
    ProgramSpec,
)

model = ModelContext("example/model", revision="v1", base_state_id="base-1")
episode = LearningEpisode(
    "toy-task",
    train=["example"],
    evaluations={"accuracy": ["held-out example"]},
    episode_id="toy-task-v1",
)

results = [
    AdaptationResult(
        model_context=model,
        episode=episode,
        program=ProgramSpec(name, "adapter", {"strength": strength}),
        before={"accuracy": 0.40},
        after={"accuracy": score},
    )
    for name, strength, score in [
        ("gentle", 0.25, 0.68),
        ("strong", 0.75, 0.81),
    ]
]

study = AdaptationStudy(results)
print(study.best("accuracy").program.name)
print(study.best("accuracy").delta.to_dict())

More runnable examples are available in examples.

Core objects

• ModelContext identifies a model revision and pre-adaptation base state.
• LearningEpisode names a learning problem and references its datasets.
• ProgramFamily describes a conceptual adaptation family.
• ProgramSpec declares one concrete, backend-independent adaptation program.
• AdaptationGeometry stores arbitrary-dimensional behavioral measurements.
• AdaptationResult records before/after geometry for one observed adaptation.
• AdaptationStudy compares programs for one fixed model context and episode.
• AdaptationDataset stores observations across models, episodes, and programs.

Public records support JSON-safe serialization. Dataset-like objects attached to a LearningEpisode are intentionally held by reference and are not serialized. DataFrame export is available through the optional dataframe extra.

Compiler-ready data

adaptcompile.compiler combines an AdaptationDataset with externally supplied numeric decision-time descriptors to produce a validated supervised dataset. Feature extraction remains external. Version 0.3 can fit a predictor over the assembled numeric features.

from adaptcompile.compiler import build_compiler_dataset

compiler_data = build_compiler_dataset(
    observations,
    episode_descriptors=episode_features,
    program_descriptors=program_features,
    target="delta",
)
print(compiler_data.feature_names)

See the compiler data contract for descriptor identities, namespaces, baseline features, and validation rules.

Predicting geometry

The dependency-free GeometryPredictor protocol defines target-free prediction from compiler features and candidate identity. RidgeGeometryPredictor is one optional, deliberately simple reference implementation:

from adaptcompile.compiler.predictors import RidgeGeometryPredictor

predictor = RidgeGeometryPredictor().fit(compiler_data)
prediction = predictor.predict(
    features=compiler_data[0].features,
    model_key=compiler_data[0].model_key,
    episode_key=compiler_data[0].episode_key,
    family_fingerprint=compiler_data[0].family_fingerprint,
    program_fingerprint=compiler_data[0].program_fingerprint,
)
print(prediction.predicted_geometry)

See prediction for target semantics and delta reconstruction.

Selecting a program

Selection uses predicted post-adaptation geometry, an explicit weighted objective, and optional hard constraints:

from adaptcompile.compiler import GeometryConstraint, SelectionObjective
from adaptcompile.compiler.selectors import LinearUtilitySelector

objective = SelectionObjective(
    maximize={"gain": 1.0},
    minimize={"cost": 0.2},
    constraints=(GeometryConstraint("retention", minimum=0.8),),
)
selection = LinearUtilitySelector().select(predictions, objective)

See selection for ranking, feasibility, and tie semantics.

What adaptcompile does not do

• It does not train or load adapted models.
• It does not implement LoRA or replace PEFT, TRL, or another training framework.
• It does not infer objectives, synthesize programs, or execute adaptations.
• It has no mandatory ML-framework or numerical-stack dependencies; pandas and the scikit-learn reference predictor are optional extras.

Status

0.4.0 adds explicit selection among predicted candidate adaptations. The API is usable but may evolve during the 0.x series. The package does not infer objectives, extract features, synthesize programs, or execute adaptations.