beefcot 1.0.3__tar.gz

beefcot-1.0.3/.gitignore

@@ -0,0 +1,69 @@
+# Local environments and editor junk
+.venv/
+.venv-*/
+venv/
+env/
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*~
+
+# Python / test / coverage
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Runtime caches
+.cache/
+
+# Run records (written under the workspace's runs folder).
+/runs/
+/workflow-log/
+/docs/reports/
+/docs/deployment/m1-acceptance.md
+/docs/development/relocations-20261020.tsv
+
+# Retired code, tests and moved-aside material: local audit, not GitHub.
+/archive/
+
+# The model library: delivered models carry rows of the data in their self-checks.
+/models/
+
+# Data lives next to this repo under $BEEF_COT_ROOT/DataSets, never in git.
+/DataSets/
+*.xlsx
+*.xls
+*.csv
+*.tsv
+*.parquet
+*.npy
+*.npz
+*.sqlite
+*.sqlite3
+*.db
+*.zip
+*.tar.gz
+
+# Fitted blobs if someone dumps them in-tree
+*.pkl
+*.joblib
+*.pt
+*.pth
+*.ckpt
+
+# Logs / notebooks
+*.log
+.ipynb_checkpoints/
+.factorized_policy_search*.yaml

beefcot-1.0.3/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.5
+Name: beefcot
+Version: 1.0.3
+Summary: Carcass yield models and cutting plans: one YAML in, one delivered model out
+Requires-Python: >=3.13
+Requires-Dist: jarvisplot>=2.1
+Requires-Dist: numpy>=2.5
+Requires-Dist: pandas>=3.0
+Requires-Dist: pytest>=8
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn>=1.9
+Requires-Dist: scipy>=1.18
+Requires-Dist: xgboost>=3.3
+Description-Content-Type: text/markdown
+
+# beefcot
+
+Carcass yield regression models and cutting plans, defined by YAML. Python 3.13
+or newer is required.
+
+```bash
+python3 -m pip install beefcot
+beefcot --help
+beefcot validate /path/to/job.yaml
+beefcot fit /path/to/job.yaml
+```
+
+Each fit starts from a `kind: regression_tree` YAML declaring its input table,
+feature and target columns, cut-tree mapping, split and regression space.
+Available methods are profile, RF, DNN, ReRF and exhaustive search. Structural
+nodes aggregate measured products; data and fitted models are supplied by users.
+
+Delivered format-3 models can be loaded once and called through the NumPy-only
+runtime:
+
+```python
+from beefcot.runtime import load
+
+model = load("/path/to/delivered/model")
+result = model.predict_one(carcass_inputs)
+```
+
+The source distribution contains package code, required generic resources,
+runtime schemas and build metadata. It contains no animal datasets, fitted
+models, reports, machine setup records or development job configurations.
+
+Plotting delegates to the public `jplot plot.yaml` command. Keep `jplot` on the
+active environment's PATH; plotting YAML and input tables are retained beside
+the generated figures for redrawing. Supported usage is available from
+`jplot --help` and `jplot man <topic> --json`.
+
+Development configuration templates, tests and tools are maintained separately
+from the installed package. Keep your job YAML, data, outputs and delivered
+models in an independent workspace.

beefcot-1.0.3/README.pypi.md

@@ -0,0 +1,39 @@
+# beefcot
+
+Carcass yield regression models and cutting plans, defined by YAML. Python 3.13
+or newer is required.
+
+```bash
+python3 -m pip install beefcot
+beefcot --help
+beefcot validate /path/to/job.yaml
+beefcot fit /path/to/job.yaml
+```
+
+Each fit starts from a `kind: regression_tree` YAML declaring its input table,
+feature and target columns, cut-tree mapping, split and regression space.
+Available methods are profile, RF, DNN, ReRF and exhaustive search. Structural
+nodes aggregate measured products; data and fitted models are supplied by users.
+
+Delivered format-3 models can be loaded once and called through the NumPy-only
+runtime:
+
+```python
+from beefcot.runtime import load
+
+model = load("/path/to/delivered/model")
+result = model.predict_one(carcass_inputs)
+```
+
+The source distribution contains package code, required generic resources,
+runtime schemas and build metadata. It contains no animal datasets, fitted
+models, reports, machine setup records or development job configurations.
+
+Plotting delegates to the public `jplot plot.yaml` command. Keep `jplot` on the
+active environment's PATH; plotting YAML and input tables are retained beside
+the generated figures for redrawing. Supported usage is available from
+`jplot --help` and `jplot man <topic> --json`.
+
+Development configuration templates, tests and tools are maintained separately
+from the installed package. Keep your job YAML, data, outputs and delivered
+models in an independent workspace.

beefcot-1.0.3/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "beefcot"
+dynamic = ["version"]  # from src/beefcot/__init__.py; see CHANGELOG.md
+description = "Carcass yield models and cutting plans: one YAML in, one delivered model out"
+readme = "README.pypi.md"
+requires-python = ">=3.13"
+# Lower bounds are the versions this was built and measured on; no upper bounds, because a
+# cap only gets in the way at upgrade time. The delivered numbers are pinned by the run
+# records, not by the dependency ranges.
+dependencies = [
+    "numpy>=2.5",
+    "pandas>=3.0",
+    "scipy>=1.18",
+    "scikit-learn>=1.9",
+    "xgboost>=3.3",
+    "PyYAML>=6.0",
+    "JarvisPLOT>=2.1",
+    "pytest>=8",
+]
+
+[project.scripts]
+beefcot = "beefcot.cli:main"
+
+[tool.hatch.version]
+path = "src/beefcot/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/beefcot"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src/beefcot", "/pyproject.toml", "/README.pypi.md",
+]
+exclude = [
+    "**/__pycache__", "**/*.pyc", "**/.DS_Store",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: reproduces the recorded RF run (about 100 seconds); run with -m slow"]
+addopts = "-m 'not slow'"

beefcot-1.0.3/src/beefcot/__init__.py

@@ -0,0 +1,101 @@
+"""Carcass yield models, found from one YAML.
+
+Every job is one YAML and one verb, the same in Python as on the command line (``beefcot fit ...``):
+
+    import beefcot
+
+    beefcot.fit("config/regression/murdoch_rf.yaml")          # kind: regression_tree -> a run with a model
+    beefcot.predict("config/prediction/murdoch_rf_241.yaml")  # kind: prediction      -> one table
+    beefcot.plan("config/plan/murdoch_demo.yaml")             # kind: cutting_plan    -> a plan
+    beefcot.check("config/checks/murdoch_core3_bins.yaml")    # kind: bin_variance    -> a data check
+    beefcot.decompose("config/decomposition/murdoch_rf.yaml") # kind: error_decomposition -> noise / bias² / variance
+    beefcot.run("config/pipelines/murdoch_smoke.yaml")        # kind: pipeline        -> several, in order
+
+    model = beefcot.load_model("murdoch_rf-rf-20261003-83a160")   # a directory or a library id
+    model.predict_one({"sidewt": 155.4, "P8": 5, "Bred": "BxH"})  # one carcass -> its products
+
+Each verb takes only the kind it names and returns where it wrote (a folder, or the prediction
+table). ``beefcot.runtime`` is what loads and calls a delivered model (numpy only); everything else
+in the package is an implementation detail.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+__version__ = "1.0.3"  # the one place it is written; CHANGELOG.md records each version
+
+__all__ = ["__version__", "fit", "predict", "plan", "check", "decompose", "run", "load_model"]
+
+
+def fit(config: str | Path) -> Path:
+    """Find and deliver a regression tree (``kind: regression_tree``); returns the run folder."""
+    return _do("fit", config)
+
+
+def predict(config: str | Path, *, workspace: str | Path | None = None) -> Path:
+    """Predict every row of a CSV with a delivered model (``kind: prediction``); returns the table.
+    ``workspace`` names the model library a ``model.id`` is looked up in."""
+    return _do("predict", config, workspace)
+
+
+def plan(config: str | Path, *, workspace: str | Path | None = None) -> Path:
+    """Make a cutting plan (``kind: cutting_plan``); returns the plan folder. ``workspace`` names the
+    model library a ``model.id`` is looked up in."""
+    return _do("plan", config, workspace)
+
+
+def check(config: str | Path) -> Path:
+    """Measure data, label anomalies or analyse saved regressions; returns the
+    analysis folder. An anomaly check fits only its diagnostic detector."""
+    return _do("check", config)
+
+
+def decompose(config: str | Path) -> Path:
+    """Split a regression YAML's error into noise, bias² and estimation variance
+    (``kind: error_decomposition``); returns the analysis folder. No model is delivered."""
+    return _do("decompose", config)
+
+
+def run(config: str | Path, *, workspace: str | Path | None = None) -> Path:
+    """Run several YAMLs in order (``kind: pipeline``); returns the folder holding the chain's record."""
+    return _do("run", config, workspace)
+
+
+def _do(verb: str, config: str | Path, workspace: str | Path | None = None) -> Path:
+    """Every path the YAML names is absolute or relative to the YAML, and nothing is written over an
+    earlier output: a taken folder or file gets a ``_02``, ``_03``, ... name."""
+    from beefcot import registry
+    from beefcot.model.runtime import bootstrap_native_runtime
+    from beefcot.workspace import preferring
+
+    path = Path(config).expanduser().resolve()
+    kind = registry.kind_of(path)
+    entry = registry.kind(kind)
+    if entry.command != verb:
+        raise ValueError(f"{path} is kind={kind!r}: use `beefcot {entry.command}` (beefcot.{entry.command}), "
+                         f"not `beefcot {verb}`")
+    bootstrap_native_runtime()
+    with preferring(workspace):
+        return entry.run(path)
+
+
+def load_model(model: str | Path, *, workspace: str | Path | None = None) -> Any:
+    """Load a delivered model (format version 3), by directory or by library id.
+
+    This is ``beefcot.runtime.load`` with the workspace's model library to find an id in: every check
+    runs on the first load, and a model loaded once in a process is the same object every time after.
+    """
+    from beefcot import runtime
+
+    path = Path(model).expanduser()
+    if path.exists():
+        return runtime.load(path)
+    if path.parent != Path("."):  # it was written as a path, so say it is missing as one
+        raise FileNotFoundError(f"no model directory at {path}")
+    from beefcot.model_format.library import ModelLibrary
+    from beefcot.workspace import Workspace as _Workspace
+
+    space = None if workspace is None else _Workspace.load(workspace)
+    return ModelLibrary.from_workspace(space).load(str(model))

beefcot-1.0.3/src/beefcot/anomaly.py

@@ -0,0 +1,101 @@
+"""Versioned numeric Isolation Forest scoring, used only by YAML jobs.
+
+Scores are unusualness, not error probabilities. No source values are changed.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from importlib.metadata import version
+from math import isfinite
+
+import numpy as np
+import pandas as pd
+
+VERSION = "isolation_forest_v1"
+DEFAULT_THRESHOLD = 0.5
+LABEL_COLUMNS = ("iforest_score", "iforest_label", "iforest_rank", "iforest_reason")
+PARAMS = {"n_estimators": 256, "max_samples": "auto", "max_features": 1.0,
+          "bootstrap": False, "contamination": "auto", "n_jobs": 1}
+
+
+def threshold(value, *, context: str) -> float:
+    if (isinstance(value, bool) or not isinstance(value, (int, float))
+            or not isfinite(value) or not 0 <= value <= 1):
+        raise ValueError(f"{context}: threshold must be a finite number in [0, 1]")
+    return float(value)
+
+
+def seed(value, *, context: str) -> int:
+    if type(value) is not int or value < 0:
+        raise ValueError(f"{context}: seed must be a nonnegative integer")
+    return value
+
+
+def settings(yaml_seed: int) -> dict:
+    random_state = int(np.random.SeedSequence(yaml_seed, spawn_key=(0x49464F52,)).generate_state(1)[0])
+    return {"version": VERSION, "score": "-score_samples; higher is more unusual",
+            "threshold_rule": "score > threshold", "library": "scikit-learn",
+            "library_version": version("scikit-learn"),
+            "params": {**PARAMS, "random_state": random_state}}
+
+
+def id_hash(ids) -> str:
+    import json
+    return hashlib.sha256(json.dumps(list(map(str, ids)), ensure_ascii=False,
+                                     separators=(",", ":")).encode("utf-8")).hexdigest()
+
+
+def numeric_matrix(raw: pd.DataFrame, columns, *, source) -> np.ndarray:
+    arrays = []
+    for column in columns:
+        values = raw[column]
+        numbers = pd.to_numeric(values, errors="coerce")
+        wrong = values.notna() & numbers.isna()
+        if wrong.any():
+            raise ValueError(f"{source}: isolation_forest column {column!r} contains nonnumeric text, "
+                             f"e.g. {values[wrong].tolist()[:5]}")
+        arrays.append(numbers.to_numpy(dtype=float))
+    return np.column_stack(arrays)
+
+
+@dataclass(frozen=True)
+class Scores:
+    values: np.ndarray
+    labels: np.ndarray
+    reasons: tuple[str, ...]
+    reference_rows: np.ndarray
+    resolved: dict
+
+
+def score(matrix: np.ndarray, columns, reference_rows, *, yaml_seed: int, limit: float,
+          context: str) -> Scores:
+    """Fit on finite reference rows, score every finite row; never impute."""
+    from sklearn.ensemble import IsolationForest
+
+    matrix = np.asarray(matrix, dtype=float)
+    # sklearn consumes float32 internally; do not silently overflow finite CSV values.
+    usable = np.isfinite(matrix) & (np.abs(matrix) <= np.finfo(np.float32).max)
+    finite = usable.all(axis=1)
+    reference = np.asarray(reference_rows, dtype=np.intp)
+    reference = reference[finite[reference]]
+    if len(reference) < 2:
+        raise ValueError(f"{context}: isolation_forest needs at least 2 scoreable reference rows; "
+                         f"found {len(reference)} for columns {list(columns)}")
+    resolved = settings(yaml_seed)
+    detector = IsolationForest(**resolved["params"]).fit(matrix[reference])
+    values = np.full(len(matrix), np.nan)
+    values[finite] = -detector.score_samples(matrix[finite])
+    labels = np.full(len(matrix), "unscored", dtype=object)
+    labels[finite] = np.where(values[finite] > limit, "review", "within_threshold")
+    reasons = tuple("; ".join(
+        f"{columns[j]}:" + ("missing" if np.isnan(matrix[i, j]) else
+                            "nonfinite" if not np.isfinite(matrix[i, j]) else "float32_overflow")
+        for j in np.flatnonzero(~usable[i])) for i in range(len(matrix)))
+    return Scores(values, labels, reasons, reference, resolved)
+
+
+def labelled_columns(result: Scores) -> pd.DataFrame:
+    return pd.DataFrame({"iforest_score": result.values, "iforest_label": result.labels,
+                         "iforest_rank": pd.Series(result.values).rank(method="min", ascending=False).astype("Int64"),
+                         "iforest_reason": result.reasons})