{
  "schemaKind": "protocol",
  "protocolVersion": "1.0",
  "meta": {
    "archetype": "ml_train",
    "eligibility": "eligible",
    "repo": {
      "owner": "trevin-creator",
      "name": "autoresearch-mlx",
      "defaultBranch": "main",
      "cloneUrl": "https://github.com/trevin-creator/autoresearch-mlx"
    },
    "purposeStatement": "Improve the final validation bits-per-byte (val_bpb) achieved by a fixed 5-minute MLX training run on the same Apple Silicon machine.",
    "createdAt": "2026-05-09T08:00:09Z",
    "updatedAt": "2026-05-09T08:00:09Z",
    "protocolBundleId": "autoresearch-mlx-main-ba6ebf6-20260509"
  },
  "environment": {
    "osHints": [
      "darwin-arm64",
      "Apple Silicon"
    ],
    "packageManagers": [
      "uv"
    ],
    "setupCommands": [
      "uv sync",
      "uv run prepare.py"
    ],
    "assetPrep": [
      "One-time data and tokenizer preparation writes to ~/.cache/autoresearch.",
      "prepare.py downloads public Hugging Face shards when the local cache is missing.",
      "Measured baselines and downstream trials should run against an already populated ~/.cache/autoresearch snapshot rather than requiring network during the experiment loop.",
      "Training/eval should reuse the same local cache snapshot across trials on the same machine."
    ],
    "constraints": {
      "noNewDependencies": true,
      "networkPolicy": "offline"
    }
  },
  "mutableSurface": {
    "allowedGlobs": [
      "train.py"
    ],
    "forbiddenGlobs": [
      "prepare.py",
      "README.md",
      "program.md",
      "results.tsv",
      "uv.lock",
      "LICENSE"
    ],
    "allowedKinds": [
      "code_edit"
    ]
  },
  "immutableHarness": {
    "paths": [
      "prepare.py"
    ],
    "rationale": "prepare.py defines the fixed data prep, tokenizer training, dataloader, time budget, and evaluate_bpb metric implementation that must remain stable across trials."
  },
  "execution": {
    "command": "uv run train.py",
    "cwd": ".",
    "stopCondition": {
      "type": "wall_clock",
      "trainingSecondsBudget": 300,
      "excludeCompilationFromBudget": true,
      "notes": "The training loop accumulates 300 seconds of post-startup training time, then runs a final evaluation pass."
    },
    "hardTimeoutSeconds": 900,
    "determinism": {
      "seedPolicy": "optional",
      "notes": "The public repo does not expose a strict fixed-seed contract; compare runs on the same hardware and cache snapshot."
    }
  },
  "measurement": {
    "primaryMetric": {
      "name": "val_bpb",
      "direction": "minimize",
      "extract": {
        "kind": "regex",
        "pattern": "^val_bpb:\\s+([0-9]+(?:\\.[0-9]+)?)$",
        "exampleStdout": "---\nval_bpb:          2.534000\ntraining_seconds: 312.4\ntotal_seconds:    405.7\npeak_vram_mb:     27528.9\nmfu_percent:      0.00\ntotal_tokens_M:   39.8\nnum_steps:        46\nnum_params_M:     50.3\ndepth:            8",
        "notes": "Use the summary block printed at the end of train.py. The first regex capture group is the scalar benchmark value."
      }
    },
    "secondaryMetrics": [
      {
        "name": "peak_vram_mb",
        "direction": "minimize",
        "extract": {
          "kind": "regex",
          "pattern": "^peak_vram_mb:\\s+([0-9]+(?:\\.[0-9]+)?)$",
          "exampleStdout": "---\nval_bpb:          2.534000\ntraining_seconds: 312.4\ntotal_seconds:    405.7\npeak_vram_mb:     27528.9\nmfu_percent:      0.00\ntotal_tokens_M:   39.8\nnum_steps:        46\nnum_params_M:     50.3\ndepth:            8"
        }
      },
      {
        "name": "training_seconds",
        "direction": "minimize",
        "extract": {
          "kind": "regex",
          "pattern": "^training_seconds:\\s+([0-9]+(?:\\.[0-9]+)?)$",
          "exampleStdout": "---\nval_bpb:          2.534000\ntraining_seconds: 312.4\ntotal_seconds:    405.7\npeak_vram_mb:     27528.9\nmfu_percent:      0.00\ntotal_tokens_M:   39.8\nnum_steps:        46\nnum_params_M:     50.3\ndepth:            8",
          "notes": "Support metric only. The main optimization target remains val_bpb."
        }
      }
    ],
    "baselinePolicy": {
      "establishOnHardware": true,
      "sameDataSnapshot": true,
      "baselineNotes": "Do not reuse baseline values from other machines. Establish a fresh local baseline on the same Apple Silicon hardware and with the same ~/.cache/autoresearch data/tokenizer snapshot."
    }
  },
  "provenance": {
    "resultsLog": {
      "format": "tsv",
      "path": "results.tsv",
      "columns": [
        "commit",
        "val_bpb",
        "memory_gb",
        "status",
        "description"
      ]
    },
    "gitWorkflow": {
      "branchPattern": "autoresearch/<tag>",
      "commitScope": "One experimental change per commit on a dedicated autoresearch branch.",
      "stagingExample": "git add train.py && git commit -m \"experiment: <description>\""
    }
  },
  "safety": {
    "oomPolicy": "reduce_batch",
    "crashStatus": "crash"
  },
  "agentRules": {
    "simplicityCriterion": true,
    "autonomy": {
      "noAskHumanToContinue": true
    },
    "experimentTimeoutNotes": "Typical runs are about 5 minutes of training plus compile/eval overhead. Kill runs that exceed 15 minutes wall clock.",
    "logRedirectExample": "uv run train.py > run.log 2>&1"
  },
  "archetypeExtensions": {
    "ml_train": {
      "dataSnapshot": "~/.cache/autoresearch/data with pinned validation shard shard_06542.parquet and tokenizer artifacts under ~/.cache/autoresearch/tokenizer",
      "evalTokens": 1572864,
      "hardwareNotes": "Absolute val_bpb differs by Apple Silicon hardware class. Compare only against baselines and trials from the same machine."
    }
  }
}