spb/modelmap Public License

1#!/usr/bin/env python32# =============================================================================3#  Project   : modelmap4#  File      : tools/new_experiment.py5#  Purpose   : Scaffold a charter-compliant experiment directory (§10 block)6#  Author    : Simon-Pierre Boucher7#  Contact   : contact@spboucher.ai8#  Website   : https://modelmap.io9#  Created   : 2026-08-1210#  Modified  : 2026-08-1211#  Platform  : macOS / Apple Silicon (arm64)12#  License   : All rights reserved (research code)13# =============================================================================14"""Scaffold an experiment directory with the seven-field scientific block.1516Usage:17    python3 tools/new_experiment.py experiments/micro/expX_name "one-line purpose"18"""1920from __future__ import annotations2122import datetime23import sys24from pathlib import Path2526ROOT = Path(__file__).resolve().parent.parent2728FRONT = """---29project: modelmap30document: {doc}31author: Simon-Pierre Boucher32contact: contact@spboucher.ai33website: https://modelmap.io34created: {date}35status: draft36---37"""3839BLOCK = """```text40Hypothesis              : (to be registered before the first run)41Falsification criterion : (explicit kill-number, registered in advance)42Method                  : (including controls)43Baseline / null         : (shuffled labels / random directions / random init)44Result                  : (pending)45Interpretation          : (pending — with explicit confidence level)46Next experiment         : (pending)47```48"""495051def main() -> int:52    if len(sys.argv) < 3:53        print(__doc__)54        return 255    rel, purpose = sys.argv[1], sys.argv[2]56    date = datetime.datetime.now(tz=datetime.UTC).date().isoformat()57    exp = ROOT / rel58    name = exp.name59    if exp.exists():60        print(f"error: {rel} already exists")61        return 162    (exp / "implementation").mkdir(parents=True)63    (exp / "results").mkdir()64    (exp / "README.md").write_text(65        FRONT.format(doc=name, date=date) + f"\n# {name}\n\n{purpose}\n"66    )67    (exp / "hypothesis.md").write_text(68        FRONT.format(doc=f"{name} — hypothesis", date=date)69        + f"\n# Hypothesis — {name}\n\n> {purpose}\n\n" + BLOCK70    )71    (exp / "analysis.md").write_text(72        FRONT.format(doc=f"{name} — analysis", date=date)73        + f"\n# Analysis — {name}\n\n*(pending — written only after results exist)*\n"74    )75    print(f"scaffolded {rel}")76    return 0777879if __name__ == "__main__":80    sys.exit(main())81