Source code for rigconductor.models
# ╔══════════════════════════════════════════════════════════════════╗
# ║ Rig Conductor — models ║
# ║ « which AI models exist » ║
# ╠══════════════════════════════════════════════════════════════════╣
# ║ Model registry: one YAML per organism on Aoraki, cached here. ║
# ╚══════════════════════════════════════════════════════════════════╝
"""Model registry: one YAML per organism on the cluster, cached locally.
Entry example::
- id: flies13_lab_v1
organism: drosophila
kind: sleap-topdown # sleap-topdown | dlc | tadpose-assign
run: flies13_lab_v1 # what the SLURM script takes (models/<run>.centroid …)
env: sleap
trained: 2026-11-20
validation: {frames: 150, mAP: 0.82}
notes: fine-tuned from flies13 on 150 October frames
"""
from __future__ import annotations
import shlex
import subprocess
from dataclasses import dataclass, field
from pathlib import Path
import yaml
from rigconductor import ConductorError
[docs]
@dataclass
class Model:
id: str
organism: str
kind: str
run: str
env: str = "sleap"
trained: str | None = None
validation: dict = field(default_factory=dict)
notes: str = ""
deprecated: bool = False
expects: dict = field(default_factory=dict) # training-data description, see compat.py
grayscale_input: bool = False # the model's config converts any input to gray
default: bool = False # promoted: pre-selected for its organism (last one wins)
@property
def label(self) -> str:
"""Dropdown text: id, date and the headline validation number."""
bits = [self.id]
if self.trained:
bits.append(str(self.trained))
for k in ("mAP", "f1", "silhouette", "frames"):
if k in self.validation:
bits.append(f"{k} {self.validation[k]}")
break
if self.deprecated:
bits.append("(deprecated)")
return " · ".join(bits)
def parse_registry(text: str) -> list[Model]:
data = yaml.safe_load(text) or []
if isinstance(data, dict):
data = data.get("models", [])
out = []
for i, d in enumerate(data):
for k in ("id", "organism", "kind"):
if k not in d:
raise ConductorError(f"registry entry {i} lacks '{k}'")
d = dict(d)
d.setdefault("run", d["id"])
d["validation"] = d.get("validation") or {}
d["expects"] = d.get("expects") or {}
out.append(Model(**{k: v for k, v in d.items() if k in Model.__dataclass_fields__}))
return out
def load_cached(cache: Path) -> list[Model]:
if not Path(cache).is_file():
return []
return parse_registry(Path(cache).read_text(encoding="utf-8"))
def refresh(ssh_host: str, remote_path: str, cache: Path, run=subprocess.run) -> list[Model]:
r = run(
["ssh", "-o", "BatchMode=yes", ssh_host, f"cat {shlex.quote(remote_path)}"],
capture_output=True,
text=True,
timeout=60,
)
if r.returncode != 0:
raise ConductorError(
f"could not read the model registry {ssh_host}:{remote_path}: {r.stderr.strip()[-300:]}"
)
models = parse_registry(r.stdout) # validate before caching
Path(cache).parent.mkdir(parents=True, exist_ok=True)
Path(cache).write_text(r.stdout, encoding="utf-8")
return models
def models_for(models: list[Model], organism: str, include_deprecated: bool = False) -> list[Model]:
return [
m for m in models if m.organism == organism and (include_deprecated or not m.deprecated)
]
def by_id(models: list[Model], model_id: str) -> Model:
for m in models:
if m.id == model_id:
return m
raise ConductorError(f"model '{model_id}' is not in the registry; press 'Refresh models'")
[docs]
def default_for(models: list[Model], organism: str) -> str | None:
"""Id of the promoted model for ``organism`` (the last one marked default)."""
marked = [m for m in models_for(models, organism) if m.default]
return marked[-1].id if marked else None