beefcot 1.0.4__tar.gz → 1.1.0__tar.gz

{beefcot-1.0.4 → beefcot-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beefcot
-Version: 1.0.4
+Version: 1.1.0
 Summary: Carcass yield models and cutting plans: one YAML in, one delivered model out
 Requires-Python: >=3.13
 Requires-Dist: fastapi>=0.115

{beefcot-1.0.4 → beefcot-1.1.0}/src/beefcot/__init__.py

@@ -24,7 +24,7 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any
 
-__version__ = "1.0.4"  # the one place it is written; CHANGELOG.md records each version
+__version__ = "1.1.0"  # the one place it is written; CHANGELOG.md records each version
 
 __all__ = ["__version__", "fit", "predict", "plan", "check", "decompose", "run", "load_model"]
 

{beefcot-1.0.4 → beefcot-1.1.0}/src/beefcot/checks/figures.py

@@ -79,7 +79,7 @@ def plot_config(
         "DataSet": [{"name": "animals", "path": "../animals.csv", "type": "csv"},
                     {"name": "cells", "path": "../cells.csv", "type": "csv"}],
         "Figures": figures,
-        "output": {"dir": ".", "formats": ["png"]},
+        "output": {"dir": ".", "formats": ["svg", "png"]},
     }
 
 

{beefcot-1.0.4 → beefcot-1.1.0}/src/beefcot/cutting_plan/economics.py

@@ -6,13 +6,14 @@ built from three things, and only the first is ours:
 
     product yield   what each carcass gives for each product  <- Model.predict_table
     prices          what each product sells for               <- scenario
-    pattern costs   labour rate and processing speed, capacity <- scenario
+    pattern costs   labor rate, processing speed and packaging <- scenario
 
 This module builds those matrices and stops there. The mixed-integer solve is a separate
 concern: ``solve`` hands the matrices to HiGHS (``plan/solver.py``).
 
 Units, as the reference optimizer defines them: ``process_speed`` is carcasses per **minute**
-and ``hourly_labor_cost`` is money per hour, so labour per carcass is hourly cost / speed / 60.
+and ``hourly_labor_cost`` is money per hour, so labor per carcass is hourly cost / speed / 60.
+The optional ``packaging_cost_per_head`` is already a per-carcass cost.
 
 Coverage is explicit. The delivered tree predicts the 16 measured cuts (and their totals);
 a pattern may name products it does not cover, and pretending otherwise is how a plan ends
@@ -31,16 +32,40 @@ enough of it for the level to mean something.
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+import math
 from typing import Any, Mapping, Sequence
 
 import numpy as np
 import pandas as pd
 
 from beefcot.runtime import Model
+from beefcot.cutting_plan.eligibility import Eligibility, Rule, evaluate, parse_rules
 
 UNCOVERED_POLICIES = ("error", "zero", "external")
 # Does every carcass have to be processed, or may a carcass be left out of the plan?
 ASSIGNMENT_RULES = ("exactly_one", "at_most_one")
+PURCHASE_PRICE_BASES = ("per_head", "per_kg")
+
+
+def amount(value: Any, context: str, *, positive: bool = False) -> float:
+    if isinstance(value, bool):
+        raise ValueError(f"{context}: expected a finite number")
+    try:
+        number = float(value)
+    except (TypeError, ValueError) as failure:
+        raise ValueError(f"{context}: expected a finite number") from failure
+    if not math.isfinite(number) or (number <= 0 if positive else number < 0):
+        raise ValueError(f"{context}: must be finite and {'positive' if positive else 'nonnegative'}")
+    return number
+
+
+def whole(value: Any, context: str) -> int | None:
+    if value is None:
+        return None
+    number = amount(value, context)
+    if number != math.floor(number) or number > 2**53 - 1:
+        raise ValueError(f"{context}: must be an exactly representable whole number")
+    return int(number)
 
 
 @dataclass(frozen=True)
@@ -57,6 +82,21 @@ class Pattern:
     # scenario's list. A slower, closer trim sells the same cut for more; a fast break sells
     # it for less. Products left out here are sold at the list price.
     prices: Mapping[str, float] = field(default_factory=dict)
+    eligibility: tuple[Rule, ...] = ()
+    packaging_cost_per_head: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not self.name.strip() or not self.products:
+            raise ValueError(f"pattern {self.name!r}: name and products must be nonempty")
+        amount(self.process_speed, f"pattern {self.name}: process_speed", positive=True)
+        amount(self.hourly_labor_cost, f"pattern {self.name}: hourly_labor_cost")
+        amount(self.packaging_cost_per_head, f"pattern {self.name}: packaging_cost_per_head")
+        for key in ("min_carcasses", "max_carcasses"):
+            whole(getattr(self, key), f"pattern {self.name}: {key}")
+        if self.min_carcasses is not None and self.max_carcasses is not None and self.min_carcasses > self.max_carcasses:
+            raise ValueError(f"pattern {self.name}: min_carcasses exceeds max_carcasses")
+        for product, price in self.prices.items():
+            amount(price, f"pattern {self.name}: prices.{product}")
 
     @property
     def labor_cost_per_carcass(self) -> float:
@@ -70,7 +110,7 @@ class Pattern:
         if not isinstance(payload, Mapping):
             raise TypeError("a pattern must be a mapping")
         allowed = {"name", "products", "process_speed", "hourly_labor_cost", "min_carcasses",
-                   "max_carcasses", "prices"}
+                   "max_carcasses", "prices", "eligibility", "packaging_cost_per_head"}
         unknown = sorted(set(payload) - allowed)
         if unknown:
             raise ValueError(f"pattern {payload.get('name')!r}: unknown keys={unknown}; allowed={sorted(allowed)}")
@@ -78,14 +118,19 @@ class Pattern:
         missing = [key for key in required if key not in payload]
         if missing:
             raise ValueError(f"pattern {payload.get('name', '?')!r}: missing keys={missing}")
+        if not isinstance(payload["products"], (list, tuple)):
+            raise ValueError(f"pattern {payload['name']}: products must be a list")
         return cls(
             name=str(payload["name"]),
             products=tuple(str(item) for item in payload["products"]),
-            process_speed=float(payload["process_speed"]),
-            hourly_labor_cost=float(payload["hourly_labor_cost"]),
-            min_carcasses=None if payload.get("min_carcasses") is None else int(payload["min_carcasses"]),
-            max_carcasses=None if payload.get("max_carcasses") is None else int(payload["max_carcasses"]),
-            prices={str(key): float(value) for key, value in dict(payload.get("prices") or {}).items()},
+            process_speed=amount(payload["process_speed"], f"pattern {payload['name']}: process_speed", positive=True),
+            hourly_labor_cost=amount(payload["hourly_labor_cost"], f"pattern {payload['name']}: hourly_labor_cost"),
+            packaging_cost_per_head=amount(payload.get("packaging_cost_per_head", 0),
+                                           f"pattern {payload['name']}: packaging_cost_per_head"),
+            min_carcasses=whole(payload.get("min_carcasses"), f"pattern {payload['name']}: min_carcasses"),
+            max_carcasses=whole(payload.get("max_carcasses"), f"pattern {payload['name']}: max_carcasses"),
+            eligibility=parse_rules(payload.get("eligibility", []), f"pattern {payload['name']} eligibility"),
+            prices={str(key): amount(value, f"pattern {payload['name']}: prices.{key}") for key, value in dict(payload.get("prices") or {}).items()},
         )
 
     def to_dict(self) -> dict[str, Any]:
@@ -94,9 +139,11 @@ class Pattern:
             "products": list(self.products),
             "process_speed": self.process_speed,
             "hourly_labor_cost": self.hourly_labor_cost,
+            **({"packaging_cost_per_head": self.packaging_cost_per_head} if self.packaging_cost_per_head else {}),
             "min_carcasses": self.min_carcasses,
             "max_carcasses": self.max_carcasses,
             "prices": dict(self.prices),
+            **({"eligibility": [rule.to_dict() for rule in self.eligibility]} if self.eligibility else {}),
         }
 
 
@@ -109,14 +156,50 @@ class ScenarioSpec:
     pieces_per_carcass: float = 2.0  # both sides; the tree predicts one side
     purchase_price_column: str | None = "grid_price"
     weight_column: str | None = None  # the carcass weight the purchase price is per kg of
-    purchase_price: float | None = None  # a flat price per kg when the carcasses carry none
+    purchase_price: float | None = None  # scalar fallback when the source column is absent
     available_column: str | None = "num_available"
     uncovered_products: str = "error"
     assignment: str = "exactly_one"  # exactly_one | at_most_one
+    units: Mapping[str, str | None] = field(default_factory=dict)
+    purchase_price_basis: str = "per_kg"
+    purchase_price_column_basis: str = "per_kg"
+
+    @property
+    def yield_factor(self) -> float:
+        return 1.0 if self.units.get("yield") == "kg/carcass" else self.pieces_per_carcass
+
+    @property
+    def purchase_weight_factor(self) -> float:
+        return 1.0 if self.units.get("purchase_weight") == "kg/carcass" else self.pieces_per_carcass
+
+    def purchase_input(self, columns) -> tuple[str | None, str | None]:
+        if self.purchase_price_column and self.purchase_price_column in columns:
+            return self.purchase_price_column, self.purchase_price_column_basis
+        if self.purchase_price is not None:
+            return None, self.purchase_price_basis
+        return None, None
 
     def __post_init__(self) -> None:
+        for key in ("purchase_price_basis", "purchase_price_column_basis"):
+            if getattr(self, key) not in PURCHASE_PRICE_BASES:
+                raise ValueError(f"scenario.{key}: expected per_head or per_kg")
         if not self.patterns:
             raise ValueError("a scenario needs at least one pattern")
+        if len({pattern.name for pattern in self.patterns}) != len(self.patterns):
+            raise ValueError("scenario: pattern names must be unique")
+        amount(self.pieces_per_carcass, "scenario.pieces_per_carcass", positive=True)
+        for product, price in self.prices.items():
+            amount(price, f"scenario.prices.{product}")
+        if self.purchase_price is not None:
+            amount(self.purchase_price, "scenario.purchase_price")
+        if not isinstance(self.units, Mapping) or set(self.units) - {"yield", "purchase_weight", "currency"}:
+            raise ValueError("scenario.units: allowed keys are yield, purchase_weight, currency")
+        for key in ("yield", "purchase_weight"):
+            if self.units.get(key, "kg/side") not in {"kg/side", "kg/carcass"}:
+                raise ValueError(f"scenario.units.{key}: expected kg/side or kg/carcass")
+        currency = self.units.get("currency")
+        if currency is not None and (not isinstance(currency, str) or len(currency) != 3 or not currency.isascii() or not currency.isupper() or not currency.isalpha()):
+            raise ValueError("scenario.units.currency: expected a three-letter uppercase currency code")
         if self.assignment not in ASSIGNMENT_RULES:
             raise ValueError(f"assignment={self.assignment!r}; allowed={list(ASSIGNMENT_RULES)}")
         if self.uncovered_products not in UNCOVERED_POLICIES:
@@ -140,6 +223,9 @@ class ScenarioSpec:
         for pattern in self.patterns:
             for product in pattern.products:
                 seen.setdefault(product, None)
+            for rule in pattern.eligibility:
+                if rule.kind == "product":
+                    seen.setdefault(rule.name, None)
         return tuple(seen)
 
     @classmethod
@@ -149,6 +235,7 @@ class ScenarioSpec:
         allowed = {
             "patterns", "prices", "pieces_per_carcass", "purchase_price_column", "purchase_price",
             "weight_column", "available_column", "uncovered_products", "assignment",
+            "units", "purchase_price_basis", "purchase_price_column_basis",
         }
         unknown = sorted(set(payload) - allowed)
         if unknown:
@@ -158,14 +245,17 @@ class ScenarioSpec:
             raise ValueError(f"scenario: missing keys={missing}")
         return cls(
             patterns=tuple(Pattern.from_dict(item) for item in payload["patterns"]),
-            prices={str(key): float(value) for key, value in dict(payload["prices"]).items()},
-            pieces_per_carcass=float(payload.get("pieces_per_carcass", 2.0)),
+            prices={str(key): amount(value, f"scenario.prices.{key}") for key, value in dict(payload["prices"]).items()},
+            pieces_per_carcass=amount(payload.get("pieces_per_carcass", 2.0), "scenario.pieces_per_carcass", positive=True),
             purchase_price_column=payload.get("purchase_price_column", "grid_price"),
             weight_column=None if payload.get("weight_column") is None else str(payload["weight_column"]),
-            purchase_price=None if payload.get("purchase_price") is None else float(payload["purchase_price"]),
+            purchase_price=None if payload.get("purchase_price") is None else amount(payload["purchase_price"], "scenario.purchase_price"),
             available_column=payload.get("available_column", "num_available"),
             uncovered_products=str(payload.get("uncovered_products", "error")),
             assignment=str(payload.get("assignment", "exactly_one")),
+            units=payload.get("units", {}),
+            purchase_price_basis=payload.get("purchase_price_basis", "per_kg"),
+            purchase_price_column_basis=payload.get("purchase_price_column_basis", "per_kg"),
         )
 
     def to_dict(self) -> dict[str, Any]:
@@ -179,6 +269,9 @@ class ScenarioSpec:
             "available_column": self.available_column,
             "uncovered_products": self.uncovered_products,
             "assignment": self.assignment,
+            "units": dict(self.units),
+            **{key: getattr(self, key) for key in ("purchase_price_basis", "purchase_price_column_basis")
+               if getattr(self, key) != "per_kg"},
         }
 
 
@@ -200,6 +293,8 @@ class CuttingPlanInputs:
     # pattern -> the measured cuts it sells once its totals are counted as their cuts; two
     # patterns are a like-for-like choice only when these are the same
     pattern_cuts: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    eligibility: Eligibility | None = None
+    animal_ids: tuple[str, ...] = ()
 
 
 @dataclass
@@ -212,6 +307,12 @@ class PlanResult:
     per_pattern_count: dict[str, int]
     solver: str
     seconds: float | None = None
+    outcome: str = "error"
+    bound: float | None = None  # upper bound, in the maximisation problem's sign
+    gap: float | None = None
+    termination: str | None = None
+    verification: dict[str, Any] = field(default_factory=dict)
+    constraint_rows: list[dict[str, Any]] = field(default_factory=list)
 
 
 # The one solver: HiGHS through SciPy (plan/solver.py). A plan YAML may name it, nothing else.
@@ -224,6 +325,8 @@ def build_inputs(
     carcasses: pd.DataFrame,
     *,
     external_yield: pd.DataFrame | None = None,
+    eligibility_source: pd.DataFrame | None = None,
+    animal_ids: tuple[str, ...] = (),
 ) -> CuttingPlanInputs:
     """Predict the carcasses, then build the income, cost and profit matrices.
 
@@ -251,21 +354,27 @@ def build_inputs(
         used.append(model)
         warnings.append((model, predicted.attrs.get("warnings", {})))
         for product in needed:
+            contract_units = {str(item['code']): item.get('unit') for item in model.contract['products']}
+            members = model.totals.get(product, (product,))
+            if any(contract_units.get(member) != "kg" for member in members):
+                raise ValueError(f"model {model.id}, product {product}: cutting plans require model output in kg")
             coverage[product] = model.id
             frames[product] = pd.Series(predicted[product].to_numpy(dtype=float), index=index)
     for product in scenario.products:
         if product in frames:
             continue
         if external_yield is not None and product in external_yield.columns:
+            if len(external_yield) != len(carcasses):
+                raise ValueError(f"external yield product {product}: expected {len(carcasses)} rows, got {len(external_yield)}")
             coverage[product] = "external"
-            frames[product] = pd.Series(external_yield[product].astype(float).to_numpy(), index=index)
+            frames[product] = pd.Series(_amounts(external_yield, product, what="external product yield"), index=index)
             continue
         uncovered.append(product)
-        if scenario.uncovered_products == "error":
+        if scenario.uncovered_products in {"error", "external"}:
             continue
         coverage[product] = "zero"
         frames[product] = pd.Series(np.zeros(len(carcasses)), index=index)
-    if uncovered and scenario.uncovered_products == "error":
+    if uncovered and scenario.uncovered_products in {"error", "external"}:
         raise ValueError(
             "no model given predicts these products and no external yield was "
             f"given: {sorted(uncovered)}. Either supply them (uncovered_products: external) "
@@ -278,39 +387,30 @@ def build_inputs(
     pattern_cuts = {pattern.name: _cuts_of(pattern, members_of) for pattern in scenario.patterns}
 
     product_yield = pd.DataFrame(frames, index=index)
+    for product in product_yield:
+        _amounts(product_yield, product, what="predicted product yield")
     income = pd.DataFrame(index=index)
     labor = pd.DataFrame(index=index)
     for pattern in scenario.patterns:
         money = pd.Series(np.zeros(len(carcasses)), index=index)
         for product in pattern.products:
             price = float(pattern.prices.get(product, scenario.prices.get(product, 0.0)))
-            money = money + product_yield[product] * price * scenario.pieces_per_carcass
+            money = money + product_yield[product] * price * scenario.yield_factor
         income[pattern.name] = money
         labor[pattern.name] = pattern.labor_cost_per_carcass
-    # An unreadable weight or price would make that carcass's profit NaN, which the solver
-    # cannot take and would report without saying which row; so every row is checked here.
-    if scenario.purchase_price_column and scenario.purchase_price_column in carcasses.columns:
-        price = _amounts(carcasses, scenario.purchase_price_column, what="the purchase price per kg")
-    elif scenario.purchase_price is not None:
-        price = np.full(len(carcasses), float(scenario.purchase_price))
-    else:
-        price = None  # nothing is paid for, so the weight is not needed either
-    if price is None:
-        purchase = pd.Series(np.zeros(len(carcasses)), index=index)
-    else:
-        if not scenario.weight_column:
-            raise ValueError("a purchase price needs scenario.weight_column: the carcass weight it is per kg of")
-        weight = _amounts(carcasses, scenario.weight_column, what="the side weight the purchase cost is priced on")
-        purchase = pd.Series(weight * price * scenario.pieces_per_carcass, index=index)
+    purchase = pd.Series(purchase_costs(carcasses, scenario), index=index)
     profit = income.subtract(labor, axis=0).subtract(purchase, axis=0)
+    for pattern in scenario.patterns:
+        if pattern.packaging_cost_per_head:
+            profit[pattern.name] -= float(pattern.packaging_cost_per_head)
     if scenario.available_column and scenario.available_column in carcasses.columns:
         raw = carcasses[scenario.available_column]
         counts = pd.to_numeric(raw, errors="coerce")
         # Silently reading an unreadable count as zero would drop that carcass from the plan
         # without a word, and a fractional one cannot be assigned at all (the solver would call
         # the plan infeasible and blame the pattern limits), so both are refused here.
-        whole = counts.notna() & (counts >= 0) & (counts == np.floor(counts))
-        bad = [int(i) for i, ok in enumerate(whole) if not ok]
+        valid_counts = counts.notna() & np.isfinite(counts) & (counts >= 0) & (counts <= 2**53 - 1) & (counts == np.floor(counts))
+        bad = [int(i) for i, ok in enumerate(valid_counts) if not ok]
         if bad:
             shown = ", ".join(f"row {i}: {_plain(raw.iloc[i])!r}" for i in bad[:5])
             raise ValueError(
@@ -346,6 +446,8 @@ def build_inputs(
             "pieces_per_carcass": scenario.pieces_per_carcass,
         },
         pattern_cuts=pattern_cuts,
+        eligibility=evaluate(scenario, carcasses if eligibility_source is None else eligibility_source, product_yield, coverage),
+        animal_ids=animal_ids,
     )
 
 
@@ -373,6 +475,22 @@ def _cuts_of(pattern: Pattern, members_of: Mapping[str, Sequence[str]]) -> tuple
     return tuple(sorted(sold))
 
 
+def purchase_costs(carcasses: pd.DataFrame, scenario: ScenarioSpec) -> np.ndarray:
+    """Charge the known quote per head, or price its declared purchase kilograms."""
+    column, basis = scenario.purchase_input(carcasses.columns)
+    if basis is None:
+        return np.zeros(len(carcasses))
+    unit = "per head" if basis == "per_head" else "per kg"
+    prices = (_amounts(carcasses, column, what=f"the purchase price {unit}") if column
+              else np.full(len(carcasses), float(scenario.purchase_price)))
+    if basis == "per_head":
+        return prices
+    if not scenario.weight_column:
+        raise ValueError("a purchase price per kg needs scenario.weight_column")
+    weight = _amounts(carcasses, scenario.weight_column, what="the weight the purchase cost is priced on")
+    return weight * prices * scenario.purchase_weight_factor
+
+
 def _amounts(carcasses: pd.DataFrame, column: str, *, what: str) -> np.ndarray:
     """A money-relevant column as numbers, refusing the rows that are not a finite amount >= 0."""
     if column not in carcasses.columns:
@@ -418,10 +536,11 @@ def random_assignment_comparison(
         for pattern in inputs.patterns
     )
     solved = assignment is not None
+    comparable = inputs.eligibility is None
     if solved:
         counts = assignment.reindex(index=profit.index, columns=patterns).fillna(0.0).astype(float)
         chosen_profit = (profit * counts).sum(axis=1)
-        advantage = chosen_profit - expected_profit
+        advantage = chosen_profit - expected_profit if comparable else pd.Series(np.nan, index=profit.index)
     else:
         chosen_profit = pd.Series(np.nan, index=profit.index)
         advantage = pd.Series(np.nan, index=profit.index)
@@ -444,17 +563,22 @@ def random_assignment_comparison(
         "expected_labor_cost": float(expected_labor.sum()),
         "expected_purchase_cost": float(expected_purchase.sum()),
         "expected_carcasses_per_pattern": total_carcasses / len(patterns),
-        "advantage_over_random": None if not solved else float(advantage.sum()),
+        "advantage_over_random": None if not solved or not comparable else float(advantage.sum()),
+        **({"respects_eligibility": False} if not comparable else {}),
     }
+    if any(pattern.packaging_cost_per_head for pattern in inputs.patterns):
+        mean_packaging = sum(float(pattern.packaging_cost_per_head) / len(patterns)
+                             for pattern in inputs.patterns)
+        report["expected_packaging_cost"] = float(mean_packaging * total_carcasses)
     return report, by_carcass
 
 
-def solve(inputs: CuttingPlanInputs) -> PlanResult:
+def solve(inputs: CuttingPlanInputs, *, options: Mapping[str, float] | None = None) -> PlanResult:
     """Assign carcasses to patterns: a mixed-integer problem (one pattern per carcass, pattern
     capacities), solved exactly by HiGHS."""
     from beefcot.cutting_plan.solver import solve_assignment
 
-    return solve_assignment(inputs)
+    return solve_assignment(inputs, options=options)
 
 
 def unusual_inputs(carcasses: pd.DataFrame, warnings) -> dict[str, dict[str, Any]]:

beefcot-1.1.0/src/beefcot/cutting_plan/eligibility.py

@@ -0,0 +1,158 @@
+"""Pattern eligibility evaluated against source rows and frozen model yields."""
+from dataclasses import dataclass
+import io
+import json
+import math
+from typing import Mapping
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class Rule:
+    kind: str
+    name: str
+    minimum: float | None = None
+    maximum: float | None = None
+    values: tuple[str, ...] = ()
+    basis: str | None = None
+
+    def to_dict(self):
+        if self.kind == 'category':
+            return {'kind': self.kind, 'column': self.name, 'values': list(self.values)}
+        target = {'product': self.name, 'basis': self.basis} if self.kind == 'product' else {'column': self.name}
+        return {'kind': self.kind, **target, 'min': self.minimum, 'max': self.maximum}
+
+    def label(self):
+        if self.kind == 'category':
+            return f'{self.name} in {json.dumps(self.values, ensure_ascii=False)}'
+        target = f'{self.name} ({self.basis})' if self.basis else self.name
+        low = '−∞' if self.minimum is None else f'{self.minimum:g}'
+        high = '+∞' if self.maximum is None else f'{self.maximum:g}'
+        return f'{target} in [{low}, {high}]'
+
+
+def parse_rules(raw, context):
+    if not isinstance(raw, (list, tuple)):
+        raise ValueError(f'{context}: expected a list of rules')
+    rules = []
+    for index, item in enumerate(raw, 1):
+        where = f'{context}, rule {index}'
+        if not isinstance(item, Mapping):
+            raise ValueError(f'{where}: expected a mapping')
+        kind = item.get('kind')
+        if kind not in ('number', 'category', 'product'):
+            raise ValueError(f'{where}: choose number, category or product')
+        target = 'product' if kind == 'product' else 'column'
+        name = item.get(target)
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError(f'{where}: choose a {target}')
+        allowed = {'kind', target, 'values'} if kind == 'category' else {'kind', target, 'min', 'max'}
+        if kind == 'product':
+            allowed.add('basis')
+        if set(item) - allowed:
+            raise ValueError(f'{where}: unexpected fields: {sorted(map(str, set(item) - allowed))}')
+        if kind == 'category':
+            values = item.get('values')
+            if not isinstance(values, list) or not values or any(not isinstance(v, str) or not v.strip() for v in values):
+                raise ValueError(f'{where}: values must be a nonempty list of category strings')
+            rules.append(Rule(kind, name, values=tuple(values)))
+            continue
+        bounds = []
+        for key in ('min', 'max'):
+            value = item.get(key)
+            if value is not None:
+                if isinstance(value, bool) or not isinstance(value, (int, float)):
+                    raise ValueError(f'{where}: {key} must be a finite number')
+                try:
+                    value = float(value)
+                except OverflowError:
+                    value = math.inf
+                if not math.isfinite(value):
+                    raise ValueError(f'{where}: {key} must be a finite number')
+                if kind == 'product' and value < 0:
+                    raise ValueError(f'{where}: product weight bounds must be nonnegative')
+            bounds.append(value)
+        low, high = bounds
+        if low is None and high is None:
+            raise ValueError(f'{where}: enter at least one bound')
+        if low is not None and high is not None and low > high:
+            raise ValueError(f'{where}: minimum exceeds maximum')
+        basis = item.get('basis')
+        if kind == 'product' and basis not in ('kg/side', 'kg/carcass'):
+            raise ValueError(f'{where}: choose kg/side or kg/carcass')
+        rules.append(Rule(kind, name, low, high, basis=basis))
+    return tuple(rules)
+
+
+def source_values(raw, count):
+    """Read exact CSV category spellings without changing the model input table."""
+    stream = io.BytesIO(raw) if isinstance(raw, bytes) else raw
+    return pd.read_csv(stream, dtype=str, keep_default_na=False, nrows=count)
+
+
+@dataclass
+class Eligibility:
+    allowed: pd.DataFrame
+    rejected: dict[tuple[int, str], list[str]]
+
+    def table(self, ids, available):
+        return pd.DataFrame([
+            {'carcass': i, 'animal_id': ids[i], 'pattern': pattern,
+             'available': int(available[i]), 'eligible': bool(self.allowed.iloc[i, p]),
+             'reasons': json.dumps(self.rejected.get((i, pattern), []), ensure_ascii=False)}
+            for i in range(len(ids)) for p, pattern in enumerate(self.allowed.columns)
+        ])
+
+    def diagnostics(self, available, patterns, ids):
+        unmatched = [
+            {'carcass': i, 'animal_id': str(ids[i]), 'head': int(available[i]),
+             'reasons': [f'{p}: {reason}' for p in self.allowed.columns
+                         for reason in self.rejected.get((i, p), [])]}
+            for i in np.flatnonzero((available > 0) & ~self.allowed.to_numpy().any(axis=1)).tolist()
+        ]
+        counts = [
+            {'pattern': pattern.name, 'eligible_head': int(available[self.allowed[pattern.name].to_numpy()].sum()),
+             'min_head': pattern.min_carcasses, 'max_head': pattern.max_carcasses}
+            for pattern in patterns
+        ]
+        return {'unmatched_rows': len(unmatched), 'unmatched_head': sum(row['head'] for row in unmatched),
+                'unmatched_examples': unmatched[:10], 'patterns': counts}
+
+
+def evaluate(scenario, source, yields, coverage):
+    if not any(pattern.eligibility for pattern in scenario.patterns):
+        return None
+    allowed = pd.DataFrame(True, index=range(len(source)), columns=[pattern.name for pattern in scenario.patterns])
+    rejected = {}
+    for pattern in scenario.patterns:
+        for rule in pattern.eligibility:
+            context = f'pattern {pattern.name!r}, eligibility {rule.label()}'
+            if rule.kind == 'product':
+                if rule.name not in yields or coverage.get(rule.name) in (None, 'zero', 'external'):
+                    raise ValueError(f'{context}: product needs a frozen model prediction')
+                original = scenario.units.get('yield', 'kg/side')
+                factor = 1 if original == rule.basis else 2 if rule.basis == 'kg/carcass' else 0.5
+                values = yields[rule.name].reset_index(drop=True) * factor
+            else:
+                if rule.name not in source:
+                    raise ValueError(f'{context}: source column is missing')
+                values = source[rule.name].reset_index(drop=True)
+            missing = values.isna() | values.astype(str).str.strip().eq('')
+            if rule.kind == 'category':
+                valid = values.astype(str).isin(rule.values) & ~missing
+                failure = 'category is not allowed'
+            else:
+                numbers = pd.to_numeric(values, errors='coerce').to_numpy(dtype=float)
+                valid = np.isfinite(numbers) & ~missing.to_numpy()
+                if rule.minimum is not None:
+                    valid &= numbers >= rule.minimum
+                if rule.maximum is not None:
+                    valid &= numbers <= rule.maximum
+                failure = 'value is outside the range or is not a finite number'
+            for row in np.flatnonzero(~np.asarray(valid)).tolist():
+                reason = 'value is missing' if missing.iloc[row] else f'{values.iloc[row]!r}: {failure}'
+                rejected.setdefault((row, pattern.name), []).append(f'{rule.label()}: {reason}')
+                allowed.at[row, pattern.name] = False
+    return Eligibility(allowed, rejected)