Skip to content

contract

agentic_ml.core.contract

The contract every agent-written model.py must satisfy.

A trial is a directory containing a model.py module that defines a class named Model. This module describes that interface, documents it for the agent prompt, and provides helpers to dynamically import and validate a generated module.

TrialModel

Bases: Protocol

Structural type describing a fitted trial model.

ContractError

Bases: Exception

Raised when a generated model.py does not satisfy the contract.

validate_model_class 

validate_model_class(cls: type) -> None

Validate that cls exposes the required methods.

Source code in src/agentic_ml/core/contract.py 
80
81
82
83
84
85
86
87
def validate_model_class(cls: type) -> None:
    """Validate that ``cls`` exposes the required methods."""
    required = ["fit", "predict", "save", "load"]
    missing = [name for name in required if not callable(getattr(cls, name, None))]
    if missing:
        raise ContractError(
            f"class '{MODEL_CLASS_NAME}' is missing required method(s): {', '.join(missing)}"
        )

load_model_class 

load_model_class(directory: str | Path) -> type

Import directory/model.py and return its validated Model class.

helpers.py (if present) is loaded first under the name helpers so that model.py can import it. This executes the generated code and is a trust boundary.

Source code in src/agentic_ml/core/contract.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def load_model_class(directory: str | Path) -> type:
    """Import ``directory/model.py`` and return its validated ``Model`` class.

    ``helpers.py`` (if present) is loaded first under the name ``helpers`` so that
    ``model.py`` can import it. This executes the generated code and is a trust boundary.
    """
    directory = Path(directory)
    model_file = directory / "model.py"
    if not model_file.exists():
        raise ContractError(f"no model.py found in {directory}")

    added_to_path = False
    if str(directory) not in sys.path:
        sys.path.insert(0, str(directory))
        added_to_path = True
    try:
        helpers_file = directory / "helpers.py"
        if helpers_file.exists():
            helpers_spec = importlib.util.spec_from_file_location("helpers", helpers_file)
            assert helpers_spec is not None and helpers_spec.loader is not None
            helpers_module = importlib.util.module_from_spec(helpers_spec)
            sys.modules["helpers"] = helpers_module
            helpers_spec.loader.exec_module(helpers_module)

        module_name = f"agentic_ml_trial_{uuid.uuid4().hex}"
        spec = importlib.util.spec_from_file_location(module_name, model_file)
        assert spec is not None and spec.loader is not None
        module = importlib.util.module_from_spec(spec)
        sys.modules[module_name] = module
        spec.loader.exec_module(module)
    finally:
        if added_to_path:
            try:
                sys.path.remove(str(directory))
            except ValueError:
                pass

    cls = getattr(module, MODEL_CLASS_NAME, None)
    if cls is None:
        raise ContractError(f"model.py must define a class named '{MODEL_CLASS_NAME}'")
    validate_model_class(cls)
    return cls