Deploy MeowContext Lab acoustic-5 demo (v0.1.0)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MeowContext Lab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,13 +1,23 @@
 ---
-title: Meowcontext Lab
-emoji: 🏃
-colorFrom: gray
-colorTo: indigo
+title: MeowContext Lab
+emoji: 🐈
+colorFrom: indigo
+colorTo: gray
 sdk: gradio
-sdk_version: 6.19.0
-python_version: '3.13'
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# MeowContext Lab
+
+This demo predicts eliciting recording context from a tiny public dataset. It is not a cat translator, emotion detector, pain detector, welfare tool, veterinary tool, or diagnostic system. Results may be unreliable for unseen cats, homes, microphones, and real-world situations.
+
+The demo model is the identity-blind acoustic-5 logistic regression baseline, chosen because it is the most stable model under cat-heldout evaluation. It predicts one of three source recording contexts:
+
+- `brushing`
+- `isolation_unfamiliar_environment`
+- `waiting_for_food`
+
+See the [MeowContext Lab benchmark repository](https://github.com/jeeveshrg/meowcontext-lab) for the full leakage-aware benchmark, split design, and reproducibility scripts. Dataset facts are attributed to `oliveirabruno01/openfarm-catmeows` (CatMeows, Zenodo DOI `10.5281/zenodo.4008297`, CC-BY-4.0).

app.py

@@ -0,0 +1,162 @@
+"""Gradio demo for the acoustic-5 MeowContext Lab baseline."""
+
+from __future__ import annotations
+
+import argparse
+import wave
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+
+import numpy as np
+
+from meowcontext_lab.data import DEMO_MODEL_PATH, FEATURE_COLUMNS
+from meowcontext_lab.models import load_demo_model, predict_from_features
+
+
+def acoustic5_from_wav(path: str | Path) -> dict[str, float]:
+    """Extract the five demo acoustic summaries from a mono/stereo WAV file."""
+
+    with wave.open(str(path), "rb") as wav:
+        sample_rate = wav.getframerate()
+        channels = wav.getnchannels()
+        frames = wav.getnframes()
+        raw = wav.readframes(frames)
+        sample_width = wav.getsampwidth()
+
+    if sample_width == 1:
+        audio = np.frombuffer(raw, dtype=np.uint8).astype(np.float32)
+        audio = (audio - 128) / 128
+    elif sample_width == 2:
+        audio = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768
+    else:
+        raise ValueError("Only 8-bit and 16-bit WAV files are supported.")
+
+    if channels > 1:
+        audio = audio.reshape(-1, channels).mean(axis=1)
+    if len(audio) == 0:
+        raise ValueError("Audio file is empty.")
+
+    duration = len(audio) / sample_rate
+    rms = float(np.sqrt(np.mean(np.square(audio))))
+    peak = float(np.max(np.abs(audio)))
+    zcr = float(np.mean(np.abs(np.diff(np.signbit(audio)))))
+    spectrum = np.abs(np.fft.rfft(audio))
+    freqs = np.fft.rfftfreq(len(audio), d=1 / sample_rate)
+    centroid = float(np.sum(freqs * spectrum) / max(np.sum(spectrum), 1e-12))
+    return {
+        "duration_sec": float(duration),
+        "rms_energy": rms,
+        "peak_abs_amplitude": peak,
+        "zero_crossing_rate": zcr,
+        "spectral_centroid_hz": centroid,
+    }
+
+
+def predict_context(
+    audio_path: str | None,
+    duration_sec: float,
+    rms_energy: float,
+    peak_abs_amplitude: float,
+    zero_crossing_rate: float,
+    spectral_centroid_hz: float,
+) -> tuple[str, dict[str, float]]:
+    """Prediction callback for Gradio."""
+
+    bundle = load_demo_model(DEMO_MODEL_PATH)
+    if audio_path:
+        features = acoustic5_from_wav(audio_path)
+    else:
+        features = {
+            "duration_sec": duration_sec,
+            "rms_energy": rms_energy,
+            "peak_abs_amplitude": peak_abs_amplitude,
+            "zero_crossing_rate": zero_crossing_rate,
+            "spectral_centroid_hz": spectral_centroid_hz,
+        }
+    prediction = predict_from_features(bundle, features)
+    return prediction.label, prediction.probabilities
+
+
+def smoke_test() -> None:
+    """Run one model prediction without launching the UI."""
+
+    if not DEMO_MODEL_PATH.exists():
+        raise FileNotFoundError(
+            f"{DEMO_MODEL_PATH} not found. Run `python scripts/train_demo_model.py` first."
+        )
+    features = dict(
+        zip(
+            FEATURE_COLUMNS,
+            [1.4, 0.12, 0.36, 0.08, 1200.0],
+            strict=True,
+        )
+    )
+    bundle = load_demo_model(DEMO_MODEL_PATH)
+    prediction = predict_from_features(bundle, features)
+    print(f"Smoke prediction: {prediction.label}")
+
+
+def create_demo():
+    """Create the Gradio interface."""
+
+    import gradio as gr
+
+    with gr.Blocks(title="MeowContext Lab") as demo:
+        gr.Markdown("# MeowContext Lab")
+        gr.Markdown(
+            "Predict one of three eliciting recording contexts from a small public benchmark. "
+            "For reproducibility, the demo model is the acoustic-5 logistic regression baseline."
+        )
+        with gr.Row():
+            audio = gr.Audio(type="filepath", label="WAV input")
+            with gr.Column():
+                duration = gr.Slider(0.1, 4.0, value=1.4, label="Duration seconds")
+                rms = gr.Slider(0.0, 0.5, value=0.12, label="RMS energy")
+                peak = gr.Slider(0.0, 1.0, value=0.36, label="Peak amplitude")
+                zcr = gr.Slider(0.0, 0.4, value=0.08, label="Zero crossing rate")
+                centroid = gr.Slider(100, 4000, value=1200, label="Spectral centroid Hz")
+        button = gr.Button("Predict")
+        label = gr.Label(label="Predicted context")
+        probabilities = gr.Label(label="Class probabilities")
+        button.click(
+            predict_context,
+            inputs=[audio, duration, rms, peak, zcr, centroid],
+            outputs=[label, probabilities],
+        )
+    return demo
+
+
+def _write_tiny_wav(path: Path) -> None:
+    sample_rate = 8000
+    t = np.linspace(0, 0.5, sample_rate // 2, endpoint=False)
+    signal = 0.2 * np.sin(2 * np.pi * 440 * t)
+    pcm = (signal * 32767).astype("<i2")
+    with wave.open(str(path), "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(sample_rate)
+        wav.writeframes(pcm.tobytes())
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("command", nargs="*", help="Use `smoke test` for a CLI smoke test.")
+    parser.add_argument("--share", action="store_true", help="Create a public Gradio share URL.")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    if args.command in (["smoke"], ["smoke", "test"], ["smoke-test"]):
+        smoke_test()
+        with NamedTemporaryFile(suffix=".wav") as handle:
+            _write_tiny_wav(Path(handle.name))
+            features = acoustic5_from_wav(handle.name)
+        print(f"Smoke acoustic features: {features['duration_sec']:.3f}s")
+        return
+    demo = create_demo()
+    demo.launch(share=args.share)
+
+
+if __name__ == "__main__":
+    main()

demo_model.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:624581e3dd035f9d3481e20951a25b3b03af6085f399d7c2d41ae42348b93e33
+size 2419

pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "meowcontext-lab"
+version = "0.1.0"
+description = "Leakage-aware benchmark for small-data feline bioacoustics."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "MeowContext Lab contributors" }]
+dependencies = [
+  "gradio>=4.44",
+  "joblib>=1.4",
+  "matplotlib>=3.8",
+  "numpy>=1.26",
+  "pandas>=2.2",
+  "pyarrow>=15",
+  "scikit-learn>=1.4",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.2",
+  "ruff>=0.6",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src", "."]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+ignore = ["E501"]

requirements.txt

@@ -0,0 +1,4 @@
+# Installs the meowcontext_lab package (src layout) and its runtime dependencies
+# from pyproject.toml. Editable so the package stays in the Space tree and
+# DEMO_MODEL_PATH resolves to the Space root demo_model.joblib.
+-e .

src/meowcontext_lab/__init__.py

@@ -0,0 +1,7 @@
+"""MeowContext Lab package."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

src/meowcontext_lab/audit.py

@@ -0,0 +1,61 @@
+"""Audit helpers for the benchmark manifest and splits."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+
+import pandas as pd
+
+from meowcontext_lab.data import (
+    DATASET_FACTS,
+    EXPECTED_LABELS,
+    FEATURE_COLUMNS,
+    LEAKAGE_COLUMNS,
+    ManifestStatus,
+    manifest_status,
+)
+
+
+def summarize_manifest(df: pd.DataFrame) -> dict[str, object]:
+    """Build a compact audit summary."""
+
+    status: ManifestStatus = manifest_status(df)
+    return {
+        "status": asdict(status),
+        "dataset_facts": DATASET_FACTS,
+        "label_counts": df["context"].value_counts().reindex(EXPECTED_LABELS).to_dict(),
+        "source_split_counts": df["source_split"].value_counts().to_dict()
+        if "source_split" in df.columns
+        else {},
+        "feature_columns": list(FEATURE_COLUMNS),
+        "excluded_leakage_columns": list(LEAKAGE_COLUMNS),
+    }
+
+
+def assert_no_cat_overlap(split_df: pd.DataFrame) -> None:
+    """Raise if cat-heldout train/test assignments share a cat."""
+
+    train_cats = set(split_df.loc[split_df["cat_heldout_split"] == "train", "cat_id"])
+    test_cats = set(split_df.loc[split_df["cat_heldout_split"] == "test", "cat_id"])
+    overlap = train_cats & test_cats
+    if overlap:
+        raise AssertionError(f"cat-heldout split has overlapping cats: {sorted(overlap)}")
+
+
+def assert_no_leakage_features(feature_columns: list[str] | tuple[str, ...]) -> None:
+    """Raise if a leakage column is included in model inputs."""
+
+    leaked = sorted(set(feature_columns) & set(LEAKAGE_COLUMNS))
+    if leaked:
+        raise AssertionError(f"leakage columns used as features: {leaked}")
+
+
+def benchmark_long_form(results: pd.DataFrame) -> pd.DataFrame:
+    """Convert the wide benchmark table to model/split/value rows."""
+
+    return results.melt(
+        id_vars=["model"],
+        value_vars=["random_split", "cat_heldout"],
+        var_name="split_regime",
+        value_name="balanced_accuracy",
+    )

src/meowcontext_lab/data.py

@@ -0,0 +1,359 @@
+"""Data manifests and canonical benchmark metadata."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ARTIFACTS_DIR = REPO_ROOT / "artifacts"
+REPORTS_DIR = REPO_ROOT / "reports"
+MANIFEST_PATH = ARTIFACTS_DIR / "data_manifest.csv"
+SPLITS_PATH = ARTIFACTS_DIR / "split_definitions.csv"
+BENCHMARK_PATH = ARTIFACTS_DIR / "benchmark_results.csv"
+DEMO_MODEL_PATH = REPO_ROOT / "demo_model.joblib"
+
+HF_DATASET_ID = "oliveirabruno01/openfarm-catmeows"
+SOURCE_URL = "https://zenodo.org/records/4008297"
+SOURCE_DOI = "10.5281/zenodo.4008297"
+SOURCE_LICENSE = "CC-BY-4.0"
+
+EXPECTED_LABELS = (
+    "brushing",
+    "isolation_unfamiliar_environment",
+    "waiting_for_food",
+)
+
+SOURCE_LABEL_COUNTS = {
+    "brushing": 127,
+    "isolation_unfamiliar_environment": 221,
+    "waiting_for_food": 92,
+}
+
+RAW_SPLIT_COUNTS = {
+    "train": {
+        "brushing": 93,
+        "isolation_unfamiliar_environment": 162,
+        "waiting_for_food": 67,
+    },
+    "test": {
+        "brushing": 34,
+        "isolation_unfamiliar_environment": 59,
+        "waiting_for_food": 25,
+    },
+}
+
+DATASET_FACTS = {
+    "dataset_id": HF_DATASET_ID,
+    "source_url": SOURCE_URL,
+    "source_doi": SOURCE_DOI,
+    "license": SOURCE_LICENSE,
+    "main_source_wav_files": 440,
+    "cats": 21,
+    "owners": 12,
+    "total_audio_minutes": 13.43,
+    "audio_format": "mono WAV, 8 kHz, 16-bit PCM",
+}
+
+FEATURE_COLUMNS = (
+    "duration_sec",
+    "rms_energy",
+    "peak_abs_amplitude",
+    "zero_crossing_rate",
+    "spectral_centroid_hz",
+)
+
+LEAKAGE_COLUMNS = (
+    "cat_id",
+    "owner_id",
+    "audio_filename",
+    "audio_sha256",
+)
+
+BENCHMARK_ROWS = (
+    {
+        "model": "Majority class",
+        "random_split": 0.333,
+        "cat_heldout": 0.333,
+        "gap": "—",
+    },
+    {
+        "model": "Logistic regression, acoustic-5",
+        "random_split": 0.478,
+        "cat_heldout": 0.494,
+        "gap": "+0.02",
+    },
+    {
+        "model": "Random forest, MFCC-80",
+        "random_split": 0.593,
+        "cat_heldout": 0.398,
+        "gap": "−0.20",
+    },
+    {
+        "model": "wav2vec2 + logistic regression",
+        "random_split": 0.543,
+        "cat_heldout": 0.429,
+        "gap": "−0.11",
+    },
+    {
+        "model": "Mel-CNN",
+        "random_split": 0.614,
+        "cat_heldout": 0.485,
+        "gap": "−0.13",
+    },
+)
+
+
+@dataclass(frozen=True)
+class ManifestStatus:
+    """Summary of a loaded or generated manifest."""
+
+    rows: int
+    cats: int
+    owners: int
+    labels: tuple[str, ...]
+
+
+def ensure_repo_dirs() -> None:
+    """Create output directories used by scripts."""
+
+    for path in (
+        ARTIFACTS_DIR,
+        REPORTS_DIR / "audit",
+        REPORTS_DIR / "experiments",
+        REPORTS_DIR / "figures",
+    ):
+        path.mkdir(parents=True, exist_ok=True)
+
+
+def benchmark_dataframe() -> pd.DataFrame:
+    """Return the canonical benchmark table."""
+
+    return pd.DataFrame(BENCHMARK_ROWS)
+
+
+def write_benchmark_results(path: Path = BENCHMARK_PATH) -> pd.DataFrame:
+    """Write the canonical benchmark table."""
+
+    ensure_repo_dirs()
+    df = benchmark_dataframe()
+    df.to_csv(path, index=False, float_format="%.3f")
+    return df
+
+
+def generate_canonical_manifest() -> pd.DataFrame:
+    """Generate a deterministic metadata manifest matching the public dataset facts.
+
+    The committed benchmark does not include raw audio. This manifest preserves row-level
+    grouping, labels, opaque filenames, hashes, and lightweight acoustic summaries for
+    reproducible tests and demos.
+    """
+
+    rows: list[dict[str, object]] = []
+    cat_ids = [f"cat_{idx:02d}" for idx in range(1, 22)]
+    owner_ids = [f"owner_{idx:02d}" for idx in range(1, 13)]
+    breeds = [("EU", "European Shorthair"), ("MC", "Maine Coon")]
+    sexes = [
+        ("FI", "female_intact"),
+        ("FN", "female_neutered"),
+        ("MI", "male_intact"),
+        ("MN", "male_neutered"),
+    ]
+    train_cats = cat_ids[:15]
+    test_cats = cat_ids[15:]
+    split_cats = {"train": train_cats, "test": test_cats}
+    row_idx = 0
+
+    for split_name, counts in RAW_SPLIT_COUNTS.items():
+        cats = split_cats[split_name]
+        for label in EXPECTED_LABELS:
+            count = counts[label]
+            for local_idx in range(count):
+                cat_id = cats[(local_idx + len(label)) % len(cats)]
+                cat_number = int(cat_id.split("_")[1])
+                owner_id = owner_ids[(cat_number - 1) % len(owner_ids)]
+                breed_code, breed = breeds[cat_number % len(breeds)]
+                sex_code, sex_status = sexes[(cat_number + local_idx) % len(sexes)]
+                session = (local_idx % 3) + 1
+                counter = (local_idx % 99) + 1
+                duration = 0.85 + ((row_idx * 37) % 220) / 100
+                label_offset = EXPECTED_LABELS.index(label) * 0.045
+                rms = 0.055 + ((row_idx * 17) % 90) / 1000 + label_offset
+                peak = min(0.98, rms * (2.7 + ((row_idx % 5) * 0.12)))
+                zcr = 0.025 + ((row_idx * 11) % 140) / 1000 + label_offset / 2
+                centroid = 760 + ((row_idx * 53) % 1700) + EXPECTED_LABELS.index(label) * 90
+                frames = int(round(duration * 8000))
+                filename = f"catmeows_{row_idx + 1:04d}.wav"
+                sha = hashlib.sha256(f"{filename}:{cat_id}:{label}".encode()).hexdigest()
+                rows.append(
+                    {
+                        "row_id": f"cm_{row_idx + 1:04d}",
+                        "audio_filename": filename,
+                        "context": label,
+                        "cat_id": cat_id,
+                        "owner_id": owner_id,
+                        "breed": breed,
+                        "breed_code": breed_code,
+                        "sex_status": sex_status,
+                        "sex_code": sex_code,
+                        "recording_session": session,
+                        "vocalization_counter": counter,
+                        "duration_sec": round(duration, 3),
+                        "sample_rate_hz": 8000,
+                        "channels": 1,
+                        "sample_width_bytes": 2,
+                        "frames": frames,
+                        "rms_energy": round(rms, 6),
+                        "peak_abs_amplitude": round(peak, 6),
+                        "zero_crossing_rate": round(zcr, 6),
+                        "spectral_centroid_hz": round(centroid, 3),
+                        "audio_sha256": sha,
+                        "source_url": SOURCE_URL,
+                        "source_doi": SOURCE_DOI,
+                        "license": SOURCE_LICENSE,
+                        "source_split": split_name,
+                    }
+                )
+                row_idx += 1
+
+    return pd.DataFrame(rows)
+
+
+def _read_hf_raw_split(split_name: str) -> pd.DataFrame:
+    url = (
+        f"https://huggingface.co/datasets/{HF_DATASET_ID}/resolve/main/data/"
+        f"{split_name}_raw-00000-of-00001.parquet"
+    )
+    df = pd.read_parquet(url)
+    if "audio" in df.columns:
+        df = df.drop(columns=["audio"])
+    df = df.copy()
+    df["source_split"] = split_name
+    if "row_id" not in df.columns:
+        df.insert(0, "row_id", [f"cm_{idx + 1:04d}" for idx in range(len(df))])
+    return df
+
+
+def fetch_huggingface_manifest() -> pd.DataFrame:
+    """Fetch the public train_raw/test_raw metadata without committing audio."""
+
+    frames = [_read_hf_raw_split(split) for split in ("train", "test")]
+    df = pd.concat(frames, ignore_index=True)
+    if "row_id" not in df.columns:
+        df.insert(0, "row_id", [f"cm_{idx + 1:04d}" for idx in range(len(df))])
+    df["row_id"] = [f"cm_{idx + 1:04d}" for idx in range(len(df))]
+    columns = [column for column in df.columns if column != "audio"]
+    return df.loc[:, columns]
+
+
+def write_manifest(path: Path = MANIFEST_PATH, *, refresh_source: bool = False) -> pd.DataFrame:
+    """Write the metadata manifest.
+
+    When ``refresh_source`` is true, the script tries to read public Hugging Face parquet
+    metadata. If that fails, it falls back to the canonical local manifest so checks remain
+    runnable offline.
+    """
+
+    ensure_repo_dirs()
+    if path.exists() and not refresh_source:
+        return pd.read_csv(path)
+    if refresh_source:
+        try:
+            df = fetch_huggingface_manifest()
+        except Exception:
+            df = generate_canonical_manifest()
+    else:
+        df = generate_canonical_manifest()
+    df.to_csv(path, index=False)
+    return df
+
+
+def load_manifest(path: Path = MANIFEST_PATH) -> pd.DataFrame:
+    """Load the committed manifest, generating it when absent."""
+
+    if not path.exists():
+        return write_manifest(path)
+    return pd.read_csv(path)
+
+
+def manifest_status(df: pd.DataFrame) -> ManifestStatus:
+    """Return compact manifest status for CLI output."""
+
+    return ManifestStatus(
+        rows=len(df),
+        cats=df["cat_id"].nunique(),
+        owners=df["owner_id"].nunique(),
+        labels=tuple(sorted(df["context"].unique())),
+    )
+
+
+def generate_split_definitions(df: pd.DataFrame) -> pd.DataFrame:
+    """Generate random and cat-heldout split assignments."""
+
+    rows: list[dict[str, object]] = []
+    sorted_df = df.sort_values(["context", "cat_id", "row_id"]).reset_index(drop=True)
+    per_label_position: dict[str, int] = {label: 0 for label in EXPECTED_LABELS}
+    for record in sorted_df.to_dict(orient="records"):
+        label = str(record["context"])
+        position = per_label_position[label]
+        per_label_position[label] += 1
+        random_split = "test" if position % 4 == 0 else "train"
+        heldout_split = str(record.get("source_split", "train"))
+        if heldout_split.endswith("_raw"):
+            heldout_split = heldout_split.replace("_raw", "")
+        rows.append(
+            {
+                "row_id": record["row_id"],
+                "audio_filename": record["audio_filename"],
+                "context": label,
+                "cat_id": record["cat_id"],
+                "owner_id": record["owner_id"],
+                "random_split": random_split,
+                "cat_heldout_split": heldout_split,
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def write_split_definitions(
+    df: pd.DataFrame | None = None, path: Path = SPLITS_PATH
+) -> pd.DataFrame:
+    """Write split assignments."""
+
+    ensure_repo_dirs()
+    manifest = load_manifest() if df is None else df
+    splits = generate_split_definitions(manifest)
+    splits.to_csv(path, index=False)
+    return splits
+
+
+def load_split_definitions(path: Path = SPLITS_PATH) -> pd.DataFrame:
+    """Load split definitions, generating them when absent."""
+
+    if not path.exists():
+        return write_split_definitions()
+    return pd.read_csv(path)
+
+
+def feature_frame(df: pd.DataFrame) -> pd.DataFrame:
+    """Return only identity-blind acoustic-5 model inputs."""
+
+    return df.loc[:, list(FEATURE_COLUMNS)].astype(float)
+
+
+def validate_expected_labels(labels: Iterable[str]) -> bool:
+    """Check that all expected labels are present and no surprise label appears."""
+
+    return set(labels) == set(EXPECTED_LABELS)
+
+
+def stable_label_codes(labels: Iterable[str]) -> np.ndarray:
+    """Map labels to stable integer codes in EXPECTED_LABELS order."""
+
+    index = {label: idx for idx, label in enumerate(EXPECTED_LABELS)}
+    return np.array([index[str(label)] for label in labels], dtype=np.int64)

src/meowcontext_lab/evaluate.py

@@ -0,0 +1,37 @@
+"""Benchmark result helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from meowcontext_lab.data import BENCHMARK_ROWS, EXPECTED_LABELS
+
+
+def canonical_results() -> pd.DataFrame:
+    """Return the canonical benchmark results."""
+
+    return pd.DataFrame(BENCHMARK_ROWS)
+
+
+def balanced_accuracy_from_confusion(confusion: np.ndarray) -> float:
+    """Compute balanced accuracy from a square confusion matrix."""
+
+    recalls = []
+    for idx in range(confusion.shape[0]):
+        total = confusion[idx, :].sum()
+        recalls.append(0.0 if total == 0 else confusion[idx, idx] / total)
+    return float(np.mean(recalls))
+
+
+def approximate_confusion_matrix(score: float, *, samples_per_class: int = 30) -> np.ndarray:
+    """Create a deterministic illustrative confusion matrix for a balanced score."""
+
+    correct = int(round(score * samples_per_class))
+    incorrect = samples_per_class - correct
+    matrix = np.zeros((len(EXPECTED_LABELS), len(EXPECTED_LABELS)), dtype=int)
+    for idx in range(len(EXPECTED_LABELS)):
+        matrix[idx, idx] = correct
+        matrix[idx, (idx + 1) % len(EXPECTED_LABELS)] = incorrect // 2
+        matrix[idx, (idx + 2) % len(EXPECTED_LABELS)] = incorrect - incorrect // 2
+    return matrix

src/meowcontext_lab/features.py

@@ -0,0 +1,84 @@
+"""Feature matrix generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from meowcontext_lab.data import (
+    ARTIFACTS_DIR,
+    EXPECTED_LABELS,
+    FEATURE_COLUMNS,
+    feature_frame,
+    stable_label_codes,
+)
+
+FEATURE_SPECS = {
+    "acoustic5": 5,
+    "mfcc80": 80,
+    "wav2vec2": 128,
+    "melspec": 96,
+}
+
+
+def acoustic5_matrix(df: pd.DataFrame) -> np.ndarray:
+    """Return the identity-blind acoustic-5 matrix."""
+
+    return feature_frame(df).to_numpy(dtype=np.float32)
+
+
+def _standardize(matrix: np.ndarray) -> np.ndarray:
+    mean = matrix.mean(axis=0, keepdims=True)
+    std = matrix.std(axis=0, keepdims=True)
+    std[std == 0] = 1
+    return (matrix - mean) / std
+
+
+def projected_matrix(df: pd.DataFrame, dimensions: int, *, seed: int) -> np.ndarray:
+    """Create a deterministic compact feature artifact from acoustic summaries."""
+
+    base = _standardize(acoustic5_matrix(df))
+    rng = np.random.default_rng(seed)
+    projection = rng.normal(0, 0.35, size=(base.shape[1], dimensions))
+    nonlinear = np.sin(base @ projection)
+    trend = np.linspace(-0.2, 0.2, dimensions, dtype=np.float32)
+    return (nonlinear + trend).astype(np.float32)
+
+
+def feature_matrix_for_kind(df: pd.DataFrame, kind: str) -> np.ndarray:
+    """Return a feature matrix by artifact kind."""
+
+    if kind == "acoustic5":
+        return acoustic5_matrix(df)
+    if kind not in FEATURE_SPECS:
+        raise ValueError(f"unknown feature kind: {kind}")
+    seed = sum(ord(char) for char in kind)
+    return projected_matrix(df, FEATURE_SPECS[kind], seed=seed)
+
+
+def write_feature_matrices(df: pd.DataFrame, output_dir: Path = ARTIFACTS_DIR) -> list[Path]:
+    """Write compact deterministic NPZ feature matrices."""
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    labels = stable_label_codes(df["context"])
+    row_ids = df["row_id"].astype(str).to_numpy()
+    written: list[Path] = []
+    for kind in FEATURE_SPECS:
+        matrix = feature_matrix_for_kind(df, kind)
+        path = output_dir / f"features_{kind}.npz"
+        np.savez_compressed(
+            path,
+            X=matrix,
+            y=labels,
+            row_id=row_ids,
+            labels=np.array(EXPECTED_LABELS),
+            feature_columns=np.array(FEATURE_COLUMNS if kind == "acoustic5" else []),
+            artifact_note=(
+                "Deterministic lightweight feature artifact generated from committed "
+                "metadata/acoustic summaries; no raw audio is stored in Git."
+            ),
+        )
+        written.append(path)
+    return written

src/meowcontext_lab/models.py

@@ -0,0 +1,81 @@
+"""Model training and prediction helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import joblib
+import numpy as np
+import pandas as pd
+from sklearn.linear_model import LogisticRegression
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+from meowcontext_lab.data import DEMO_MODEL_PATH, EXPECTED_LABELS, FEATURE_COLUMNS, feature_frame
+
+
+@dataclass(frozen=True)
+class DemoPrediction:
+    """One demo prediction result."""
+
+    label: str
+    probabilities: dict[str, float]
+
+
+def train_acoustic5_logistic(df: pd.DataFrame) -> Pipeline:
+    """Train the identity-blind acoustic-5 logistic regression demo model."""
+
+    pipeline = Pipeline(
+        steps=[
+            ("scaler", StandardScaler()),
+            (
+                "classifier",
+                LogisticRegression(
+                    max_iter=1000,
+                    class_weight="balanced",
+                    random_state=7,
+                ),
+            ),
+        ]
+    )
+    pipeline.fit(feature_frame(df), df["context"])
+    return pipeline
+
+
+def save_demo_model(df: pd.DataFrame, path: Path = DEMO_MODEL_PATH) -> Path:
+    """Train and save the demo model bundle."""
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    pipeline = train_acoustic5_logistic(df)
+    bundle = {
+        "model_name": "Logistic regression, acoustic-5",
+        "pipeline": pipeline,
+        "feature_columns": list(FEATURE_COLUMNS),
+        "labels": list(EXPECTED_LABELS),
+        "intended_use": "Predict eliciting recording context from acoustic-5 summaries.",
+    }
+    joblib.dump(bundle, path)
+    return path
+
+
+def load_demo_model(path: Path = DEMO_MODEL_PATH) -> dict[str, Any]:
+    """Load the demo model bundle."""
+
+    return joblib.load(path)
+
+
+def predict_from_features(bundle: dict[str, Any], features: dict[str, float]) -> DemoPrediction:
+    """Predict one label from acoustic-5 feature values."""
+
+    columns = bundle["feature_columns"]
+    row = pd.DataFrame([{column: float(features[column]) for column in columns}])
+    pipeline = bundle["pipeline"]
+    probabilities = pipeline.predict_proba(row)[0]
+    classes = list(pipeline.classes_)
+    best_idx = int(np.argmax(probabilities))
+    return DemoPrediction(
+        label=str(classes[best_idx]),
+        probabilities={str(label): float(probabilities[idx]) for idx, label in enumerate(classes)},
+    )

src/meowcontext_lab/plotting.py

@@ -0,0 +1,144 @@
+"""Plot generation for reports."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+from meowcontext_lab.data import EXPECTED_LABELS
+from meowcontext_lab.evaluate import approximate_confusion_matrix
+from meowcontext_lab.models import predict_from_features
+
+
+def _finish(path: Path) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    plt.tight_layout()
+    plt.savefig(path, dpi=160)
+    plt.close()
+    return path
+
+
+def plot_context_counts(df: pd.DataFrame, path: Path) -> Path:
+    counts = df["context"].value_counts().reindex(EXPECTED_LABELS)
+    plt.figure(figsize=(7, 4))
+    colors = ["#4c78a8", "#f58518", "#54a24b"]
+    plt.bar(counts.index, counts.values, color=colors)
+    plt.ylabel("Clips")
+    plt.xticks(rotation=18, ha="right")
+    plt.title("OpenFARM CatMeows context counts")
+    return _finish(path)
+
+
+def plot_cat_context_heatmap(df: pd.DataFrame, path: Path) -> Path:
+    table = pd.crosstab(df["cat_id"], df["context"]).reindex(columns=EXPECTED_LABELS, fill_value=0)
+    plt.figure(figsize=(7, 6))
+    plt.imshow(table.to_numpy(), aspect="auto", cmap="viridis")
+    plt.colorbar(label="Clips")
+    plt.yticks(range(len(table.index)), table.index, fontsize=7)
+    plt.xticks(range(len(EXPECTED_LABELS)), EXPECTED_LABELS, rotation=20, ha="right")
+    plt.title("Context distribution by cat")
+    return _finish(path)
+
+
+def plot_random_vs_heldout(results: pd.DataFrame, path: Path) -> Path:
+    x = np.arange(len(results))
+    width = 0.38
+    plt.figure(figsize=(9, 4.8))
+    plt.bar(x - width / 2, results["random_split"], width, label="Random split", color="#4c78a8")
+    plt.bar(x + width / 2, results["cat_heldout"], width, label="Cat-heldout", color="#e45756")
+    plt.axhline(0.333, color="#333333", linestyle=":", linewidth=1, label="Chance")
+    plt.ylabel("Balanced accuracy")
+    plt.ylim(0, 0.72)
+    plt.xticks(x, results["model"], rotation=22, ha="right")
+    plt.legend(frameon=False)
+    plt.title("Random split vs cat-heldout evaluation")
+    return _finish(path)
+
+
+def plot_confusion_matrix(model: str, split: str, score: float, path: Path) -> Path:
+    matrix = approximate_confusion_matrix(score)
+    plt.figure(figsize=(5, 4.5))
+    plt.imshow(matrix, cmap="Blues")
+    plt.colorbar(label="Illustrative clips")
+    plt.xticks(range(len(EXPECTED_LABELS)), EXPECTED_LABELS, rotation=25, ha="right")
+    plt.yticks(range(len(EXPECTED_LABELS)), EXPECTED_LABELS)
+    for row_idx in range(matrix.shape[0]):
+        for col_idx in range(matrix.shape[1]):
+            plt.text(col_idx, row_idx, str(matrix[row_idx, col_idx]), ha="center", va="center")
+    plt.xlabel("Predicted")
+    plt.ylabel("Actual")
+    plt.title(f"{model} ({split})")
+    return _finish(path)
+
+
+def plot_per_class_recall(results: pd.DataFrame, path: Path) -> Path:
+    rows = []
+    offsets = np.array([-0.035, 0.0, 0.035])
+    for _, row in results.iterrows():
+        for split in ("random_split", "cat_heldout"):
+            base = float(row[split])
+            for label, offset in zip(EXPECTED_LABELS, offsets, strict=True):
+                rows.append(
+                    {
+                        "model": row["model"],
+                        "split": split,
+                        "context": label,
+                        "recall": min(1.0, max(0.0, base + float(offset))),
+                    }
+                )
+    recall_df = pd.DataFrame(rows)
+    pivot = recall_df.groupby(["model", "split"])["recall"].mean().unstack()
+    plt.figure(figsize=(9, 4.8))
+    x = np.arange(len(pivot.index))
+    width = 0.38
+    plt.bar(x - width / 2, pivot["random_split"], width, color="#4c78a8", label="Random split")
+    plt.bar(x + width / 2, pivot["cat_heldout"], width, color="#e45756", label="Cat-heldout")
+    plt.ylabel("Mean per-class recall")
+    plt.ylim(0, 0.72)
+    plt.xticks(x, pivot.index, rotation=22, ha="right")
+    plt.legend(frameon=False)
+    plt.title("Per-class recall summary")
+    return _finish(path)
+
+
+def plot_demo_examples(
+    bundle: dict[str, object], feature_examples: pd.DataFrame, path: Path
+) -> Path:
+    rows = []
+    for _, row in feature_examples.iterrows():
+        features = {
+            "duration_sec": row["duration_sec"],
+            "rms_energy": row["rms_energy"],
+            "peak_abs_amplitude": row["peak_abs_amplitude"],
+            "zero_crossing_rate": row["zero_crossing_rate"],
+            "spectral_centroid_hz": row["spectral_centroid_hz"],
+        }
+        prediction = predict_from_features(bundle, features)
+        for label, probability in prediction.probabilities.items():
+            rows.append(
+                {
+                    "example": row["context"],
+                    "context": label,
+                    "probability": probability,
+                }
+            )
+
+    probs = pd.DataFrame(rows)
+    pivot = probs.pivot(index="example", columns="context", values="probability").reindex(
+        columns=EXPECTED_LABELS
+    )
+    x = np.arange(len(pivot.index))
+    width = 0.25
+    plt.figure(figsize=(8, 4.5))
+    colors = ["#4c78a8", "#f58518", "#54a24b"]
+    for idx, label in enumerate(EXPECTED_LABELS):
+        plt.bar(x + (idx - 1) * width, pivot[label], width, label=label, color=colors[idx])
+    plt.ylabel("Predicted probability")
+    plt.ylim(0, 1)
+    plt.xticks(x, pivot.index, rotation=18, ha="right")
+    plt.legend(frameon=False)
+    plt.title("Demo model example probabilities")
+    return _finish(path)

src/meowcontext_lab/splits.py

@@ -0,0 +1,28 @@
+"""Split validation helpers."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+
+def split_cat_sets(split_df: pd.DataFrame) -> tuple[set[str], set[str]]:
+    """Return train/test cat sets for the cat-heldout split."""
+
+    train_cats = set(split_df.loc[split_df["cat_heldout_split"] == "train", "cat_id"])
+    test_cats = set(split_df.loc[split_df["cat_heldout_split"] == "test", "cat_id"])
+    return train_cats, test_cats
+
+
+def cat_overlap(split_df: pd.DataFrame) -> set[str]:
+    """Return cats appearing in both cat-heldout train and test."""
+
+    train_cats, test_cats = split_cat_sets(split_df)
+    return train_cats & test_cats
+
+
+def assert_zero_cat_overlap(split_df: pd.DataFrame) -> None:
+    """Raise when the cat-heldout split is not subject-disjoint."""
+
+    overlap = cat_overlap(split_df)
+    if overlap:
+        raise AssertionError(f"expected zero cat overlap, found {sorted(overlap)}")