goldilocks-ml 0.1.0__tar.gz

goldilocks_ml-0.1.0/.agents/skills/catchup/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: catchup
+description: Orient yourself at the start of work in goldilocks-ml by checking git state, PRs, issues, milestones, artifacts, and recent progress. Use at session start or when resuming after a break.
+---
+
+# Catch up
+
+Do not start overlapping work until local and remote state agree.
+
+## 1. Local state
+
+```bash
+git status -sb
+git remote -v
+git branch -vv
+git log --oneline --decorate --graph --all -20
+git diff --stat
+```
+
+Preserve all existing changes. Distinguish real content edits from generated
+files, permission-only changes, experiment output, and large artifacts.
+
+## 2. Remote state
+
+Use the `github-cli` skill.
+
+```bash
+gh pr list --repo stfc/goldilocks-ml --state open --limit 20
+gh issue list --repo stfc/goldilocks-ml --state open --limit 20
+gh issue list --repo stfc/goldilocks-ml --state all --limit 10 \
+  --search "sort:updated-desc"
+gh api repos/stfc/goldilocks-ml/milestones
+```
+
+Read the relevant issue bodies and recent comments. Check whether each open PR
+closes an issue and whether CI exists and passes.
+
+## 3. ML-specific state
+
+For active model work, identify without exposing secrets:
+
+- dataset snapshot/hash and whether it is locally available;
+- model/checkpoint files and whether they are tracked, cached, or missing;
+- the config, seed, split, feature schema, and target contract in use;
+- the last evaluation report and its baseline;
+- external blockers such as PSDI credentials, staging review, or Core contract
+  changes.
+
+Do not load an untrusted pickle to inspect it. Do not print tokens.
+
+## 4. Report
+
+Summarize:
+
+- current branch and working-tree state;
+- open PRs and active issues;
+- milestones and stale/placeholder candidates;
+- artifact and dataset readiness;
+- discrepancies and the safest next action.
+
+If work exists locally but not remotely, preserve and integrate it before
+reimplementing it.

goldilocks_ml-0.1.0/.agents/skills/github-cli/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: github-cli
+description: Use the gh CLI for GitHub issues, PRs, comments, checks, Actions, and milestones in stfc/goldilocks-ml. Use whenever reading or writing GitHub state from an agent session.
+---
+
+# GitHub CLI
+
+Repository: `stfc/goldilocks-ml`.
+
+Use structured `gh` commands with `--json` and `--jq`. Do not scrape GitHub web
+pages. Use `--body-file` for multiline text.
+
+## Rules
+
+- Never push or merge directly to `main`.
+- PR descriptions are human-authored. An agent never writes or drafts one.
+- Never edit or delete GitHub text authored by someone else; add a comment.
+- Agent-authored issues, comments, and reviews must end with:
+
+```text
+Written by an agent on behalf of <user>.
+```
+
+## Inspect
+
+```bash
+gh issue list --repo stfc/goldilocks-ml --state open --limit 20 \
+  --json number,title,milestone,updatedAt
+gh pr list --repo stfc/goldilocks-ml --state open --limit 20 \
+  --json number,title,headRefName,baseRefName,reviewDecision,statusCheckRollup
+gh pr view <N> --repo stfc/goldilocks-ml \
+  --json state,mergeStateStatus,isDraft,reviewDecision,baseRefName,headRefName
+gh pr checks <N> --repo stfc/goldilocks-ml
+gh run list --repo stfc/goldilocks-ml --branch <branch>
+```
+
+Use `gh api` for fields not exposed by high-level commands:
+
+```bash
+gh api repos/stfc/goldilocks-ml/issues/<N>
+gh api repos/stfc/goldilocks-ml/milestones
+```
+
+## Write safely
+
+Fetch existing text before editing text the agent owns. Prefer a new issue
+comment for progress, decisions, verification, and handoff history.
+
+```bash
+gh issue comment <N> --repo stfc/goldilocks-ml --body-file /tmp/comment.md
+gh issue create --repo stfc/goldilocks-ml --title "..." --body-file /tmp/issue.md
+```
+
+An agent does not run `gh pr create` unless the human supplies the complete PR
+body file. Before any PR operation, verify the current branch and base.
+
+## Milestones and sub-issues
+
+Every issue needs a milestone. REST milestone updates use the milestone number:
+
+```bash
+gh api repos/stfc/goldilocks-ml/issues/<N> --method PATCH -F milestone=<number>
+```
+
+Sub-issue operations require database IDs, not issue numbers:
+
+```bash
+CHILD_ID=$(gh api repos/stfc/goldilocks-ml/issues/<child> --jq .id)
+gh api repos/stfc/goldilocks-ml/issues/<parent>/sub_issues \
+  --method POST -F sub_issue_id="$CHILD_ID"
+```
+
+## Gotchas
+
+- `--body-file` replaces or posts exactly what is in the file; inspect it first.
+- A passing check is not proof that the correct dataset, split, or model artifact
+  was used; inspect scientific evidence separately.
+- If no CI is configured, state that plainly and rely on documented local
+  verification.

goldilocks_ml-0.1.0/.agents/skills/make-a-pr/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: make-a-pr
+description: Prepare tested goldilocks-ml changes for a human to open as a pull request. Use after implementation, evaluation, tests, and self-review are complete.
+---
+
+# Make a PR
+
+The agent creates a feature branch, commits, pushes, and hands facts to the
+human. The human opens the PR and writes its body.
+
+## Preconditions
+
+- Work is on `feat/...`, `fix/...`, `docs/...`, `test/...`, or `chore/...`, not
+  `main`.
+- One concrete issue exists, has a milestone, and the PR will close it.
+- Code checks pass.
+- Scientific claims have reproducible evidence: dataset hash, split, seed,
+  configuration, baseline, metrics, and relevant slices.
+- Released artifacts have manifests, checksums, compatibility versions, and a
+  model card where applicable.
+
+## Self-review
+
+```bash
+git status -sb
+git diff main...HEAD
+git log main..HEAD --oneline
+```
+
+Check for secrets, large files, private paths, generated experiment state,
+notebooks with outputs, accidental formatting, and unexplained metric changes.
+
+Run the checks that exist in the current branch, normally:
+
+```bash
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run pytest
+uv build
+```
+
+## Commit and push
+
+Use conventional, imperative commit messages and one logical change per commit.
+
+```bash
+git push -u origin <branch>
+```
+
+Do not force-push reviewed history unless asked.
+
+## Human handoff
+
+Provide only:
+
+- branch name;
+- `git log main..HEAD --oneline`;
+- `git diff main...HEAD --stat`;
+- checks/evaluations run and their outcomes;
+- artifact/dataset identifiers where relevant;
+- `Closes #N` for the human-authored PR body.
+
+Do not draft the PR description and do not run `gh pr create` unless the human
+provides the complete body file.

goldilocks_ml-0.1.0/.agents/skills/plan/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: plan
+description: Turn a concrete goldilocks-ml feature, model experiment, refactor, or release task into an implementation plan recorded as a GitHub issue. Use before multi-step work or when the user asks for a plan.
+argument-hint: [topic]
+---
+
+# Plan work as an issue
+
+Use the `github-cli` skill. Search open and recently closed issues before
+creating anything.
+
+## Gate
+
+Create an issue only when it describes one shippable PR or model release and
+contains:
+
+- a concrete problem;
+- evidence/current state;
+- a proposed approach;
+- explicit scope and non-goals;
+- verifiable acceptance criteria;
+- a milestone.
+
+Do not create roadmap mirrors, placeholders, decision-only issues, or one issue
+per phase. Put phases and decisions inside the feature issue.
+
+For model work, settle or explicitly gate:
+
+- dataset snapshot and target/label contract;
+- feature schema and Core compatibility boundary;
+- leakage-resistant split strategy;
+- baseline, primary metrics, and reporting slices;
+- reproducibility inputs (seed, config, dependency versions);
+- artifact bundle, manifest, model card, checksums, and publication target.
+
+## Structure
+
+```markdown
+## Problem
+
+## Evidence and current state
+
+## Proposed approach
+
+## Scientific and data contract
+
+## Scope
+
+## Non-goals
+
+## Implementation plan
+
+## Verification
+
+## Acceptance criteria
+
+---
+Written by an agent on behalf of <user>.
+```
+
+Write the body to a temporary file, inspect it, then create the issue with
+`--repo stfc/goldilocks-ml --body-file`. Report the new issue URL and any open
+decision that genuinely blocks implementation.

goldilocks_ml-0.1.0/.agents/skills/report/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: report
+description: Record goldilocks-ml progress as a GitHub issue comment. Use at session end, after a milestone, when an experiment completes, or when work is blocked and needs a durable handoff.
+argument-hint: [issue number]
+---
+
+# Report progress
+
+Use the `github-cli` skill. Add history as a comment; do not rewrite another
+author's issue body.
+
+## Collect evidence
+
+```bash
+git status -sb
+git log main..HEAD --oneline 2>/dev/null
+git diff main...HEAD --stat 2>/dev/null
+```
+
+For model or data work, also capture:
+
+- dataset snapshot/hash;
+- target and feature contract versions;
+- split strategy and seed;
+- config and git commit;
+- baseline and evaluation metrics/slices;
+- artifact paths, SHA-256 digests, and publication state;
+- commands actually run and whether they passed.
+
+Never report an uncommitted local path as if it were a durable artifact. Never
+include credentials or private URLs.
+
+## Comment format
+
+```markdown
+## Progress
+
+### Completed
+
+### Evidence
+
+### Decisions
+
+### Remaining work
+
+### Blockers
+
+### Git state
+
+---
+Written by an agent on behalf of <user>.
+```
+
+Post with a body file to the relevant issue in `stfc/goldilocks-ml`. If no issue
+exists, create one only if the work passes the `plan` skill's issue gate.

goldilocks_ml-0.1.0/.agents/skills/triage/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: triage
+description: Triage the stfc/goldilocks-ml issue board by closing placeholders, folding duplicates, assigning milestones, and keeping one concrete issue per PR or model release. Use when catchup finds board drift.
+argument-hint: [optional scope]
+---
+
+# Triage issues
+
+Use the `github-cli` skill. Inspect before mutating; propose changes to the user
+before closing or restructuring text written by others.
+
+## Inventory
+
+```bash
+gh issue list --repo stfc/goldilocks-ml --state open --limit 200 \
+  --json number,title,body,labels,milestone,updatedAt
+gh issue list --repo stfc/goldilocks-ml --state closed --limit 100 \
+  --json number,title,closedAt
+gh api repos/stfc/goldilocks-ml/milestones
+```
+
+Cross-check open issues against branches, PRs, recent merges, sibling-repository
+dependencies, and the current release milestone.
+
+## Classify
+
+- **Keep:** concrete, shippable, current, correctly scoped, and assigned.
+- **Expand:** valid feature but missing evidence, approach, scientific contract,
+  verification, or acceptance criteria.
+- **Fold:** duplicate, decision, experiment phase, or sub-step of another issue.
+- **Close:** stale placeholder, roadmap mirror, superseded design, completed work,
+  or work outside this repository's boundary.
+
+For ML issues, distinguish a research question from a release issue. An open
+ended experiment needs a decision rule and bounded deliverable before it is a
+shippable issue. A model release issue must name its dataset/target contract,
+evaluation bar, and artifact output.
+
+## Execute safely
+
+- Comment before closing so the reason and destination are durable.
+- Do not edit or delete text authored by someone else.
+- Every agent-authored comment ends with the required attribution.
+- Assign a milestone to every surviving issue.
+- Do not burst-file replacements; consolidate first.
+
+Finish with a table of kept, expanded, folded, and closed issues plus any
+remaining dependency or milestone mismatch.

goldilocks_ml-0.1.0/.agents/skills/use-uv/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: use-uv
+description: Use uv for all Python package management in this project. Use when installing dependencies, running Python commands, adding packages, building, or managing environments. Never use pip, venv, or pipx.
+---
+
+# Use uv
+
+Use `uv` for every Python package and environment operation.
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check src tests
+uv run ruff format --check src tests
+uv run python -c "..."
+uv add <package>
+uv add --group dev <package>
+uv build
+```
+
+- Do not activate a virtual environment manually.
+- Do not use `pip`, `pipx`, `venv`, or `virtualenv`.
+- Declare dependencies in `pyproject.toml` and commit `uv.lock` once the project
+  has one.
+- Use optional dependency groups for heavyweight or platform-specific ML
+  stacks when they are not required by every workflow.
+- If a command shown here does not yet exist in the repository, establish the
+  corresponding configuration before treating it as a required check.

goldilocks_ml-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,132 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install development dependencies
+        run: uv sync --frozen --group dev --extra models
+
+      - name: Check formatting
+        run: uv run --frozen ruff format --check .
+
+      - name: Lint
+        run: uv run --frozen ruff check .
+
+      - name: Test
+        run: uv run --frozen pytest
+
+      # A notebook is committed with its outputs, so anything the machine that
+      # ran it printed ships to the public site. A home directory is the one
+      # that gets there by accident.
+      - name: Refuse a workstation path in the documentation
+        run: |
+          if grep -rIn -e '/Users/' -e '/home/' docs/; then
+            echo "::error::a local path reached docs/; clear the cell output that carries it"
+            exit 1
+          fi
+
+  # A base install must stay light and must still train. Both halves of that
+  # promise break silently -- one stray module-level import in the CLI pulls in
+  # the scientific stack, and the unit suite would not notice because it runs
+  # with the extra installed.
+  base-install:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.12"
+
+      - name: Install the package alone
+        run: |
+          uv venv /tmp/base
+          uv pip install --python /tmp/base/bin/python .
+
+      - name: Refuse a heavy base install
+        run: |
+          /tmp/base/bin/python - <<'PY'
+          import importlib.util as util
+          heavy = [
+              name
+              for name in ("torch", "torch_geometric", "pymatgen", "matminer",
+                           "dscribe", "sklearn", "sklearn_quantile", "numpy")
+              if util.find_spec(name) is not None
+          ]
+          if heavy:
+              raise SystemExit(
+                  "the base install pulled in the model stack: " + ", ".join(heavy)
+              )
+          print("base install is clean")
+          PY
+
+      - name: Refuse a heavy import
+        run: |
+          /tmp/base/bin/python - <<'PY'
+          import sys
+          import goldilocks_ml.cli  # noqa: F401
+          import goldilocks_ml.inference  # noqa: F401
+          leaked = sorted(
+              name
+              for name in sys.modules
+              if name.split(".")[0] in {
+                  "torch", "torch_geometric", "pymatgen", "matminer",
+                  "dscribe", "sklearn", "sklearn_quantile", "numpy",
+              }
+          )
+          if leaked:
+              raise SystemExit("importing the CLI loaded: " + ", ".join(leaked))
+          print("the CLI and inference seam import nothing heavy")
+          PY
+
+      - name: Train with the built-in baselines
+        run: |
+          /tmp/base/bin/goldilocks-ml train run protocols/synthetic/regression.toml \
+            --dataset tests/fixtures/kdist --output /tmp/run/regression
+          /tmp/base/bin/goldilocks-ml train run protocols/synthetic/classification.toml \
+            --dataset tests/fixtures/metallic --output /tmp/run/classification
+          test -f /tmp/run/regression/metrics.json
+          test -f /tmp/run/classification/metrics.json
+
+      - name: Report a missing extra clearly
+        run: |
+          /tmp/base/bin/python - <<'PY'
+          from goldilocks_ml.registry import get_feature_contract, get_trainer
+
+          for lookup, name in (
+              (get_trainer, "quantile_random_forest"),
+              (get_feature_contract, "comp_struct_soap_lattice_metal.v1"),
+          ):
+              try:
+                  lookup(name)
+              except ValueError as error:
+                  if "models" not in str(error):
+                      raise SystemExit(f"{name} should name the extra: {error}")
+                  print(f"{name}: {error}")
+              else:
+                  raise SystemExit(f"{name} resolved without its dependencies")
+          PY

goldilocks_ml-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install documentation dependencies
+        run: uv sync --frozen --group docs
+
+      - name: Build documentation
+        run: uv run --frozen mkdocs build --strict
+
+      - name: Upload GitHub Pages artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

goldilocks_ml-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Publish on PyPI
+
+# Driven by a tag, so what reaches PyPI is always a commit in the history.
+# Shaped after stfc/janus-core's release workflow, so both packages are
+# released the same way.
+on:
+  push:
+    tags:
+      # After vMajor.Minor.Patch anything is allowed, except "/".
+      - v[0-9]+.[0-9]+.[0-9]+*
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # A fork that pushes a tag must not try to publish.
+    if: github.repository == 'stfc/goldilocks-ml'
+    environment:
+      # Registered as the trusted publisher's environment on PyPI. Renaming it
+      # here means editing the publisher there too, or the upload is refused.
+      name: pypi
+      url: https://pypi.org/p/goldilocks-ml
+    permissions:
+      # For PyPI's trusted publishing.
+      id-token: write
+      # For creating the GitHub release.
+      contents: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          python-version: "3.12"
+
+      # A tag that disagrees with the packaged version publishes a release
+      # nobody can find from the history.
+      - name: Check the tag matches the packaged version
+        run: |
+          packaged=$(uvx --from=toml-cli toml get --toml-path=pyproject.toml project.version)
+          tagged="${GITHUB_REF_NAME#v}"
+          if [ "$packaged" != "$tagged" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match version $packaged"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Check the artifacts are well formed
+        run: uvx twine check --strict dist/*
+
+      - name: Create the GitHub release
+        uses: ncipollo/release-action@339a81892b84b4eeb0f6e744e4574d79d0d9b8dd # v1.21.0
+        with:
+          artifacts: "dist/*"
+          token: ${{ secrets.GITHUB_TOKEN }}
+          draft: false
+          skipIfReleaseExists: true
+          generateReleaseNotes: true
+
+      - name: Publish to PyPI
+        run: uv publish

goldilocks_ml-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+site/
+*.egg-info/
+
+# Local data, model artifacts, and experiment state
+local_data/
+artifacts/
+checkpoints/
+mlruns/
+wandb/
+outputs/
+
+# Secrets and local configuration
+.env
+.env.*
+!.env.example
+*token*
+
+# Training run bundles
+local_runs/
+
+# Files a notebook downloads or writes while it runs, and the docs build cache
+docs/notebooks/goldilocks-*/
+.cache/