adaptcompile 0.1.0__tar.gz

adaptcompile-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable public changes to this project are documented here.
+
+## 0.1.0 - 2026-09-05
+
+### Added
+
+- Declarative model and base-state contexts.
+- Learning episodes with non-serialized dataset references.
+- Conceptual program families and concrete program specifications.
+- Arbitrary-dimensional adaptation geometry and before/after adaptation results.
+- Controlled adaptation studies with ranking and Pareto analysis.
+- Multi-model, multi-episode adaptation datasets with replicate-preserving grouping.
+- JSON-safe serialization and stable conceptual/executable fingerprints.
+- Optional pandas DataFrame exports.

adaptcompile-0.1.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use adaptcompile in your research, please cite this software."
+title: "adaptcompile"
+type: software
+version: 0.1.0
+date-released: 2026-09-05
+license: MIT
+authors:
+  - name: "Rebecca Ramnauth"
+repository-code: "https://github.com/rramnauth2220/adaptcompile"

adaptcompile-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Install the project and development tools in an isolated environment:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Run the local checks before opening a pull request:
+
+```bash
+python -m pytest
+python -m ruff check .
+python -m ruff format --check .
+python -m mypy src
+```
+
+The core runtime must remain independent of ML frameworks: do not add mandatory
+PyTorch, Transformers, PEFT, TRL, model-download, network, or GPU requirements.
+Arbitrary dataset objects referenced by `LearningEpisode` must not be serialized.
+Public API additions should be deliberate and accompanied by tests and documentation.
+Tests must run without network access, GPUs, or model downloads.

adaptcompile-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rebecca Ramnauth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adaptcompile-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include CHANGELOG.md
+include CITATION.cff
+include CONTRIBUTING.md
+include LICENSE
+include README.md
+include RELEASING.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude *.py[cod]
+global-exclude __pycache__

adaptcompile-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: adaptcompile
+Version: 0.1.0
+Summary: Represent, measure, and compare the behavioral effects of model adaptation.
+Author: Rebecca Ramnauth
+License-Expression: MIT
+Project-URL: Repository, https://github.com/rramnauth2220/adaptcompile
+Keywords: machine-learning,model-adaptation,evaluation,research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dataframe
+Requires-Dist: pandas>=1.5; extra == "dataframe"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: pandas-stubs>=1.5; extra == "dev"
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# adaptcompile
+
+`adaptcompile` is a model-agnostic Python library for representing and comparing
+observed model-adaptation experiments.
+
+`adaptcompile` treats model adaptation as a behavioral transformation that can be
+represented, measured, and compared independently of the training framework used to
+produce it. It provides the representation and analysis foundation on which future
+adaptation-compilation functionality can be built.
+
+See the [architecture overview](https://github.com/rramnauth2220/adaptcompile/blob/main/docs/architecture.md) for how the objects fit
+together.
+
+## Installation
+
+```bash
+pip install adaptcompile
+```
+
+DataFrame exports are optional:
+
+```bash
+pip install "adaptcompile[dataframe]"
+```
+
+For contributor setup:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Minimal example
+
+```python
+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](https://github.com/rramnauth2220/adaptcompile/tree/main/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.
+
+## What adaptcompile does not do
+
+- It does not train or load models.
+- It does not implement LoRA or replace PEFT, TRL, or another training framework.
+- It does not currently predict outcomes or select adaptation programs.
+- It does not require PyTorch, Transformers, pandas, or any other ML framework.
+
+## Status
+
+`0.1.0` is the first public release. The API is usable but may evolve during the
+`0.x` series. Compiler functionality may be added in future releases without adding
+ML-framework dependencies to the representation layer.

adaptcompile-0.1.0/README.md

@@ -0,0 +1,98 @@
+# adaptcompile
+
+`adaptcompile` is a model-agnostic Python library for representing and comparing
+observed model-adaptation experiments.
+
+`adaptcompile` treats model adaptation as a behavioral transformation that can be
+represented, measured, and compared independently of the training framework used to
+produce it. It provides the representation and analysis foundation on which future
+adaptation-compilation functionality can be built.
+
+See the [architecture overview](https://github.com/rramnauth2220/adaptcompile/blob/main/docs/architecture.md) for how the objects fit
+together.
+
+## Installation
+
+```bash
+pip install adaptcompile
+```
+
+DataFrame exports are optional:
+
+```bash
+pip install "adaptcompile[dataframe]"
+```
+
+For contributor setup:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Minimal example
+
+```python
+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](https://github.com/rramnauth2220/adaptcompile/tree/main/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.
+
+## What adaptcompile does not do
+
+- It does not train or load models.
+- It does not implement LoRA or replace PEFT, TRL, or another training framework.
+- It does not currently predict outcomes or select adaptation programs.
+- It does not require PyTorch, Transformers, pandas, or any other ML framework.
+
+## Status
+
+`0.1.0` is the first public release. The API is usable but may evolve during the
+`0.x` series. Compiler functionality may be added in future releases without adding
+ML-framework dependencies to the representation layer.

adaptcompile-0.1.0/docs/architecture.md

@@ -0,0 +1,32 @@
+# Architecture
+
+`adaptcompile` separates experiment identity, executable declarations, measurements,
+and collections. It does not execute adaptations.
+
+```text
+ModelContext + LearningEpisode + ProgramSpec
+                                |
+                                v
+                        AdaptationResult
+                         /             \
+                        v               v
+               AdaptationStudy   AdaptationDataset
+```
+
+- `ModelContext` identifies the pre-adaptation model, revision, and base state.
+- `LearningEpisode` identifies a learning problem and references its training and
+  evaluation datasets without serializing those datasets.
+- `ProgramFamily` describes a conceptual adaptation family independently of a
+  model-specific realization.
+- `ProgramSpec` describes a concrete, backend-independent executable declaration and
+  may reference a `ProgramFamily`.
+- `AdaptationGeometry` is an immutable mapping of behavioral metric names to values.
+- `AdaptationResult` records before and after geometry for one observed combination
+  of model context, episode, and program.
+- `AdaptationStudy` compares programs while holding model context and episode fixed.
+- `AdaptationDataset` stores a corpus whose models, episodes, programs, metric
+  dimensions, and replicate provenance may vary.
+
+Names and metadata remain descriptive annotations. Stable identity is explicit:
+model studies use `(model_id, revision, base_state_id)`, episodes may supply an
+`episode_id`, and program/family fingerprints derive from their semantic parameters.

adaptcompile-0.1.0/examples/basic_comparison.py

@@ -0,0 +1,69 @@
+"""Compare two fake adaptation programs without a model or ML dependencies."""
+
+from adaptcompile import (
+    AdaptationResult,
+    AdaptationStudy,
+    LearningEpisode,
+    ModelContext,
+    ProgramSpec,
+)
+
+model_context = ModelContext(
+    model_id="example/model",
+    revision="synthetic-revision-1",
+    base_state_id="synthetic-base-state-1",
+)
+episode = LearningEpisode(
+    name="toy-task",
+    episode_id="toy-task-v1",
+    train=["example"],
+    evaluations={
+        "acquisition": ["a"],
+        "transfer": ["b"],
+        "preservation": ["c"],
+    },
+    metadata={"learning_family": "toy", "synthetic": True},
+)
+
+programs = [
+    ProgramSpec(
+        name="early",
+        method="localized_lora",
+        parameters={"layers": [2, 3, 4], "rank": 16},
+    ),
+    ProgramSpec(
+        name="middle",
+        method="localized_lora",
+        parameters={"layers": [12, 13, 14], "rank": 16},
+    ),
+]
+
+results = [
+    AdaptationResult(
+        model_context=model_context,
+        episode=episode,
+        program=programs[0],
+        before={"acquisition": 0.10, "transfer": 0.10, "preservation": 0.98},
+        after={"acquisition": 0.81, "transfer": 0.77, "preservation": 0.99},
+    ),
+    AdaptationResult(
+        model_context=model_context,
+        episode=episode,
+        program=programs[1],
+        before={"acquisition": 0.10, "transfer": 0.10, "preservation": 0.98},
+        after={"acquisition": 0.93, "transfer": 0.84, "preservation": 0.95},
+    ),
+]
+
+study = AdaptationStudy(results)
+print("\nBest transfer:", study.best("transfer").program.name)
+print("Best transfer delta:", study.best("transfer").delta.to_dict())
+print(
+    "Pareto front:",
+    [
+        result.program.name
+        for result in study.pareto_front(
+            maximize=["acquisition", "transfer", "preservation"]
+        )
+    ],
+)

adaptcompile-0.1.0/examples/from_experiment_results.py

@@ -0,0 +1,162 @@
+"""Adapt already-computed synthetic experiment records into adaptcompile.
+
+The values below are plausible test data, not published experimental results. This
+example performs no training, model loading, downloads, or backend execution.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+from adaptcompile import (
+    AdaptationResult,
+    AdaptationStudy,
+    LearningEpisode,
+    ModelContext,
+    ProgramSpec,
+)
+
+METRICS = ("acquisition", "transfer", "boundedness", "preservation")
+MODEL_CONTEXT = {
+    "model": "synthetic-research/base-model-8b",
+    "model_revision": "synthetic-revision-001",
+    "base_state_id": "synthetic-pre-adaptation-state-v1",
+}
+PROGRAMS = {
+    "early": {
+        "name": "early",
+        "method": "localized_lora",
+        "parameters": {
+            "layers": [2, 3, 4, 5],
+            "rank": 16,
+            "learning_rate": 2e-4,
+        },
+    },
+    "middle": {
+        "name": "middle",
+        "method": "localized_lora",
+        "parameters": {
+            "layers": [12, 13, 14, 15],
+            "rank": 16,
+            "learning_rate": 2e-4,
+        },
+    },
+    "late": {
+        "name": "late",
+        "method": "localized_lora",
+        "parameters": {
+            "layers": [24, 25, 26, 27],
+            "rank": 16,
+            "learning_rate": 2e-4,
+        },
+    },
+}
+SYNTHETIC_OUTPUTS = {
+    "relation-001": {
+        "early": (0.78, 0.66, 0.94, 0.97),
+        "middle": (0.93, 0.85, 0.92, 0.95),
+        "late": (0.87, 0.74, 0.97, 0.97),
+    },
+    "relation-002": {
+        "early": (0.74, 0.62, 0.95, 0.98),
+        "middle": (0.89, 0.80, 0.93, 0.96),
+        "late": (0.84, 0.70, 0.97, 0.98),
+    },
+}
+
+
+def scores(values: tuple[float, float, float, float]) -> dict[str, float]:
+    return dict(zip(METRICS, values, strict=True))
+
+
+def external_records() -> Iterator[dict[str, Any]]:
+    """Stand in for records emitted by an external research pipeline."""
+    for episode_index, (episode_id, outputs) in enumerate(
+        SYNTHETIC_OUTPUTS.items(), start=1
+    ):
+        for program_name, after in outputs.items():
+            yield {
+                "episode_id": episode_id,
+                "episode_name": f"synthetic relation episode {episode_index}",
+                "learning_family": "synthetic-relational-learning",
+                "program": PROGRAMS[program_name],
+                "before": scores((0.08, 0.06, 0.98, 0.98)),
+                "after": scores(after),
+                **MODEL_CONTEXT,
+                "experiment_id": "synthetic-adapter-example",
+                "seed": 100 + episode_index,
+                "synthetic": True,
+            }
+
+
+def adapt_record(record: Mapping[str, Any]) -> AdaptationResult:
+    """Convert one external result record without adding a core adapter API."""
+    before = record["before"]
+    after = record["after"]
+    program_data = record["program"]
+    if not isinstance(before, Mapping) or not isinstance(after, Mapping):
+        raise TypeError("external before/after values must be mappings")
+    if not isinstance(program_data, Mapping):
+        raise TypeError("external program value must be a mapping")
+
+    episode = LearningEpisode(
+        name=record["episode_name"],
+        episode_id=record["episode_id"],
+        train={"dataset_ref": f"memory://{record['episode_id']}/train"},
+        evaluations={
+            metric: {"dataset_ref": f"memory://{record['episode_id']}/{metric}"}
+            for metric in before
+        },
+        metadata={
+            "learning_family": record["learning_family"],
+            "synthetic": record["synthetic"],
+        },
+    )
+    program = ProgramSpec(
+        name=program_data["name"],
+        method=program_data["method"],
+        parameters=program_data["parameters"],
+    )
+    model_context = ModelContext(
+        model_id=record["model"],
+        revision=record["model_revision"],
+        base_state_id=record["base_state_id"],
+    )
+    return AdaptationResult(
+        model_context=model_context,
+        episode=episode,
+        program=program,
+        before=before,
+        after=after,
+        metadata={
+            "experiment_id": record["experiment_id"],
+            "seed": record["seed"],
+            "synthetic": record["synthetic"],
+        },
+    )
+
+
+results = [adapt_record(record) for record in external_records()]
+grouped: dict[str, list[AdaptationResult]] = defaultdict(list)
+for result in results:
+    episode_id = result.episode.episode_id
+    if episode_id is None:
+        raise RuntimeError("experiment records require stable episode IDs")
+    grouped[episode_id].append(result)
+
+studies = {
+    episode_id: AdaptationStudy(episode_results)
+    for episode_id, episode_results in grouped.items()
+}
+
+print(f"Converted {len(results)} synthetic records into {len(studies)} studies.")
+for episode_id, study in studies.items():
+    ranking = [result.program.name for result in study.rank("acquisition")]
+    best_transfer = study.best("transfer").program.name
+    pareto = [result.program.name for result in study.pareto_front(maximize=METRICS)]
+    print(
+        f"{episode_id}: acquisition={ranking}, "
+        f"best_transfer={best_transfer}, pareto={pareto}"
+    )

adaptcompile-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adaptcompile"
+version = "0.1.0"
+description = "Represent, measure, and compare the behavioral effects of model adaptation."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Rebecca Ramnauth" }]
+keywords = ["machine-learning", "model-adaptation", "evaluation", "research"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dataframe = ["pandas>=1.5"]
+dev = [
+    "build>=1.2",
+    "mypy>=1.8",
+    "pandas>=1.5",
+    "pandas-stubs>=1.5",
+    "pytest>=7",
+    "ruff>=0.4",
+    "twine>=5",
+]
+
+[project.urls]
+Repository = "https://github.com/rramnauth2220/adaptcompile"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+adaptcompile = ["py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["adaptcompile"]

adaptcompile-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adaptcompile-0.1.0/src/adaptcompile/__init__.py

@@ -0,0 +1,30 @@
+"""Public API for adaptcompile."""
+
+from importlib.metadata import version as _distribution_version
+
+from .dataset import AdaptationDataset
+from .episode import LearningEpisode
+from .errors import AdaptCompileError, SerializationError, ValidationError
+from .family import ProgramFamily
+from .geometry import AdaptationGeometry
+from .model import ModelContext
+from .program import ProgramSpec
+from .result import AdaptationResult
+from .study import AdaptationStudy
+
+__version__ = _distribution_version("adaptcompile")
+
+__all__ = [
+    "AdaptCompileError",
+    "AdaptationDataset",
+    "AdaptationGeometry",
+    "AdaptationResult",
+    "AdaptationStudy",
+    "LearningEpisode",
+    "ModelContext",
+    "ProgramFamily",
+    "ProgramSpec",
+    "SerializationError",
+    "ValidationError",
+    "__version__",
+]