wright-core 0.1.0__py3-none-any.whl

wright/__init__.py

@@ -0,0 +1,234 @@
+"""wright — Pure library for recipe modeling, cost calculation, and planning.
+
+Data-source agnostic.  Populate models from YAML, JSON, a database, or pure Python.
+Subclass to add domain-specific metadata (pricing, translations, etc.).
+"""
+
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("wright-core")
+except Exception:
+    __version__ = "0.0.0"
+
+from wright.allergens import (
+    DEFAULT_DAIRY_KEYS,
+    DEFAULT_GLUTEN_KEYS,
+    DEFAULT_NON_VEGAN_KEYS,
+    detect_allergens,
+    detect_allergens_from_names,
+    detect_dietary_properties,
+)
+from wright.costing import (
+    calculate_ingredient_cost,
+    calculate_ingredient_cost_range,
+    calculate_recipe_cost,
+    convert_ingredient_to_grams,
+    convert_with_density,
+    get_top_cost_drivers,
+)
+from wright.errors import (
+    IngredientNotFoundError,
+    PurchaseLoadError,
+    RecipeCoreError,
+    RecipeCostErrors,
+    RecipeLoadError,
+    UnitConversionError,
+)
+from wright.loader import (
+    list_recipe_files,
+    load_base_recipe,
+    load_density_data,
+    load_nutrition_registry,
+    load_purchases,
+    load_supplies,
+    load_yaml_file,
+)
+from wright.macros import calculate_recipe_macros
+from wright.matching import (
+    ItemMatcher,
+    ItemPicker,
+    PinnedPurchases,
+    chain,
+    cheapest_picker,
+    compatible_unit_recent_picker,
+    find_matching_purchases,
+    first_picker,
+    match_all_ingredients,
+    pinned_picker,
+    recent_picker,
+)
+from wright.models import (
+    DEFAULT_CATEGORY_RULES,
+    Assembly,
+    BaseIngredient,
+    BaseRecipe,
+    CategoryRule,
+    Component,
+    DensityData,
+    FoodRecord,
+    Ingredient,
+    IngredientCost,
+    MacroPerServing,
+    Material,
+    NutritionInfo,
+    NutritionRegistry,
+    PriceRange,
+    Purchase,
+    PurchasedItem,
+    Recipe,
+    RecipeComponent,
+    RecipeCost,
+    RecipeMacros,
+    ServingRange,
+    Servings,
+    VolumeWeightConversions,
+    categorize_item,
+)
+from wright.planning import (
+    IngredientGroup,
+    MenuAnalysis,
+    ShoppingItemWithCost,
+    ShoppingList,
+    analyze_menu,
+    calculate_item_costs,
+    calculate_shopping_list_cost,
+    estimate_total_items,
+    format_quantity,
+    generate_shopping_list,
+    group_shopping_items,
+    normalize_metric,
+    normalize_volume_to_ml,
+    normalize_volume_us,
+)
+from wright.pricing import (
+    margin_price,
+    multiplier_price,
+    per_serving_price,
+)
+from wright.session import (
+    ProductionItem,
+    ProductionRun,
+    convert_name_to_filename,
+)
+from wright.supply import (
+    Stock,
+    SupplyItem,
+)
+from wright.units import (
+    DISCRETE_UNITS,
+    PINCH_UNITS,
+    VOLUME_UNITS,
+    WEIGHT_UNITS,
+    are_compatible,
+    parse_quantity,
+    ureg,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Models
+    "Assembly",
+    "BaseIngredient",
+    "BaseRecipe",
+    "CategoryRule",
+    "Component",
+    "DEFAULT_CATEGORY_RULES",
+    "DensityData",
+    "FoodRecord",
+    "Ingredient",
+    "IngredientCost",
+    "MacroPerServing",
+    "Material",
+    "NutritionInfo",
+    "NutritionRegistry",
+    "PriceRange",
+    "Purchase",
+    "PurchasedItem",
+    "Recipe",
+    "RecipeComponent",
+    "RecipeCost",
+    "RecipeMacros",
+    "ServingRange",
+    "Servings",
+    "VolumeWeightConversions",
+    "categorize_item",
+    # Errors
+    "IngredientNotFoundError",
+    "PurchaseLoadError",
+    "RecipeCoreError",
+    "RecipeCostErrors",
+    "RecipeLoadError",
+    "UnitConversionError",
+    # Units
+    "DISCRETE_UNITS",
+    "PINCH_UNITS",
+    "VOLUME_UNITS",
+    "WEIGHT_UNITS",
+    "are_compatible",
+    "parse_quantity",
+    "ureg",
+    # Matching
+    "chain",
+    "cheapest_picker",
+    "compatible_unit_recent_picker",
+    "find_matching_purchases",
+    "first_picker",
+    "ItemMatcher",
+    "ItemPicker",
+    "match_all_ingredients",
+    "pinned_picker",
+    "PinnedPurchases",
+    "recent_picker",
+    # Costing
+    "calculate_ingredient_cost",
+    "calculate_ingredient_cost_range",
+    "calculate_recipe_cost",
+    "convert_ingredient_to_grams",
+    "convert_with_density",
+    "get_top_cost_drivers",
+    # Pricing
+    "margin_price",
+    "multiplier_price",
+    "per_serving_price",
+    # Nutrition & Macros
+    "calculate_recipe_macros",
+    # Allergens
+    "DEFAULT_DAIRY_KEYS",
+    "DEFAULT_GLUTEN_KEYS",
+    "DEFAULT_NON_VEGAN_KEYS",
+    "detect_allergens",
+    "detect_allergens_from_names",
+    "detect_dietary_properties",
+    # Session
+    "ProductionItem",
+    "ProductionRun",
+    "convert_name_to_filename",
+    # Planning
+    "analyze_menu",
+    "calculate_item_costs",
+    "calculate_shopping_list_cost",
+    "estimate_total_items",
+    "format_quantity",
+    "generate_shopping_list",
+    "group_shopping_items",
+    "IngredientGroup",
+    "MenuAnalysis",
+    "ShoppingItemWithCost",
+    "ShoppingList",
+    "normalize_metric",
+    "normalize_volume_to_ml",
+    "normalize_volume_us",
+    # Loader
+    "list_recipe_files",
+    "load_base_recipe",
+    "load_density_data",
+    "load_nutrition_registry",
+    "load_purchases",
+    "load_supplies",
+    "load_yaml_file",
+    # Supply
+    "Stock",
+    "SupplyItem",
+]

wright/allergens.py

@@ -0,0 +1,342 @@
+"""Allergen and dietary badge detection — pure functions, no I/O."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from wright.models import Ingredient, Recipe
+
+# ---------------------------------------------------------------------------
+# Badge configuration
+# ---------------------------------------------------------------------------
+
+BADGE_DISPLAY: dict[str, str] = {
+    "vegan": "VEGAN",
+    "gluten-free": "GLUTEN-FREE",
+    "dairy-free": "DAIRY-FREE",
+    "nut-free": "NUT-FREE",
+    "soy-free": "SOY-FREE",
+    "organic": "ORGANIC",
+    "local": "LOCAL",
+    "no-refined-sugar": "NO REFINED SUGAR",
+}
+
+BADGE_IMPLIES: dict[str, set[str]] = {
+    "vegan": {"dairy-free"},
+}
+
+
+# ── Default dietary keyword sets (English food vocabulary) ──────────────────
+
+DEFAULT_NON_VEGAN_KEYS: frozenset[str] = frozenset({
+    "egg",
+    "honey",
+    "gelatin",
+    "lard",
+    "meat",
+    "chicken",
+    "beef",
+    "pork",
+    "fish",
+    "shrimp",
+    "anchovy",
+    "milk",
+    "cream",
+    "butter",
+    "cheese",
+    "yogurt",
+    "sour cream",
+    "cream cheese",
+    "whey",
+    "casein",
+})
+"""Default ingredient-name keywords that disqualify vegan."""
+
+DEFAULT_DAIRY_KEYS: frozenset[str] = frozenset({
+    "milk",
+    "cream",
+    "butter",
+    "cheese",
+    "yogurt",
+    "sour cream",
+    "cream cheese",
+    "whey",
+    "casein",
+})
+"""Default ingredient-name keywords that disqualify dairy-free."""
+
+DEFAULT_GLUTEN_KEYS: frozenset[str] = frozenset({
+    "flour",
+    "wheat",
+    "barley",
+    "rye",
+    "spelt",
+    "semolina",
+})
+"""Default ingredient-name keywords that disqualify gluten-free."""
+
+_WHEAT_ALLERGEN_KEYS: frozenset[str] = frozenset({"flour", "wheat"})
+"""Allergen-map keys suppressed for gluten-free ingredients."""
+
+
+# ---------------------------------------------------------------------------
+# Allergen detection
+# ---------------------------------------------------------------------------
+
+
+def detect_allergens(
+    recipe: Recipe,
+    allergy_map: dict[str, str],
+    *,
+    ingredient_properties: Callable[[Ingredient], frozenset[str]] | None = None,
+) -> list[str]:
+    """Detect allergens present in a recipe's ingredients.
+
+    Consult the *ingredient_properties* callback (if provided) per
+    ingredient to suppress wheat/dairy keyword matches when the
+    ingredient is known to be gluten-free or vegan.
+
+    Args:
+        recipe: The recipe to scan.
+        allergy_map: Mapping of lowercase keyword → display name
+            (e.g. ``{"milk": "Milk", "wheat": "Wheat"}``).
+        ingredient_properties: Optional callback
+            ``(ingredient) -> frozenset[str]`` for authoritative dietary
+            properties (e.g. ``{"vegan", "gluten-free"}``).
+
+    Returns:
+        Sorted list of allergen display names.
+    """
+    found: set[str] = set()
+
+    for ingredient in recipe.all_ingredients:
+        if ingredient.byproduct:
+            continue
+
+        name_lower = ingredient.name.lower()
+
+        props: frozenset[str] = frozenset()
+        if ingredient_properties is not None:
+            props = ingredient_properties(ingredient)
+
+        gf = "gluten-free" in props
+        vegan = "vegan" in props
+
+        for key, allergy in allergy_map.items():
+            if allergy in found:
+                continue
+
+            if key in _WHEAT_ALLERGEN_KEYS and gf and key != "wheat":
+                continue
+            if key == "wheat" and gf and "wheat" not in name_lower:
+                continue
+
+            if key in DEFAULT_DAIRY_KEYS and vegan:
+                continue
+
+            if key == "cream" and "cream of tartar" in name_lower:
+                continue
+
+            if key in name_lower:
+                found.add(allergy)
+
+    return sorted(found)
+
+
+def detect_allergens_from_names(
+    ingredient_names: list[str],
+    allergy_map: dict[str, str],
+    *,
+    ingredient_properties_for_name: Callable[[str], frozenset[str]] | None = None,
+) -> list[str]:
+    """Detect allergens from a plain list of ingredient name strings.
+
+    Useful when working with flat ingredient lists rather than structured
+    ``Recipe`` objects.
+
+    Args:
+        ingredient_names: List of ingredient name strings.
+        allergy_map: Mapping of lowercase keyword → display name.
+        ingredient_properties_for_name: Optional callback
+            ``(name) -> frozenset[str]`` for authoritative dietary properties.
+
+    Returns:
+        Sorted list of allergen display names.
+    """
+    found: set[str] = set()
+
+    for name in ingredient_names:
+        name_lower = name.lower()
+
+        props: frozenset[str] = frozenset()
+        if ingredient_properties_for_name is not None:
+            props = ingredient_properties_for_name(name)
+
+        gf = "gluten-free" in props
+        vegan = "vegan" in props
+
+        for key, allergy in allergy_map.items():
+            if allergy in found:
+                continue
+
+            if key in _WHEAT_ALLERGEN_KEYS and gf and key != "wheat":
+                continue
+            if key == "wheat" and gf and "wheat" not in name_lower:
+                continue
+
+            if key in DEFAULT_DAIRY_KEYS and vegan:
+                continue
+
+            if key == "cream" and "cream of tartar" in name_lower:
+                continue
+
+            if key in name_lower:
+                found.add(allergy)
+
+    return sorted(found)
+
+
+# ---------------------------------------------------------------------------
+# Badge detection
+# ---------------------------------------------------------------------------
+
+
+def _resolve_badges(
+    raw_badges: list[str],
+    badge_display: dict[str, str] | None = None,
+    badge_implies: dict[str, set[str]] | None = None,
+) -> list[str]:
+    """Normalize badge slugs, suppress redundant ones, return display labels."""
+    _display = badge_display or BADGE_DISPLAY
+    _implies = badge_implies or BADGE_IMPLIES
+    normalized = [b.lower().strip() for b in raw_badges]
+    suppressed: set[str] = set()
+    for badge in normalized:
+        for redundant in _implies.get(badge, set()):
+            suppressed.add(redundant)
+
+    result: list[str] = []
+    for badge in normalized:
+        if badge not in suppressed:
+            result.append(_display.get(badge, badge.upper()))
+    return result
+
+
+def detect_dietary_properties(
+    recipe: Recipe,
+    *,
+    ingredient_properties: Callable[[Ingredient], frozenset[str]] | None = None,
+    non_vegan_keys: frozenset[str] | None = None,
+    dairy_keys: frozenset[str] | None = None,
+    gluten_keys: frozenset[str] | None = None,
+    badge_display: dict[str, str] | None = None,
+    badge_implies: dict[str, set[str]] | None = None,
+) -> list[str]:
+    """Derive dietary/quality display badges from a recipe's ingredients.
+
+    A badge is awarded only when ALL non-byproduct ingredients qualify.
+
+    Supported built-in badges (in display order):
+        - ``VEGAN`` -- no animal products detected.
+        - ``DAIRY-FREE`` -- no dairy detected (suppressed when VEGAN present).
+        - ``GLUTEN-FREE`` -- no gluten/wheat detected.
+
+    Additional badges (e.g. ``keto``, ``paleo``) are supported via the
+    *ingredient_properties* callback -- any property key returned by the
+    callback is tracked the same way.
+
+    **Detection priority per ingredient**:
+
+    1. If *ingredient_properties* returns a frozenset containing the property
+       name, that is authoritative (``True``).
+    2. If *ingredient_properties* returns a non-empty frozenset without the
+       property, the ingredient is skipped for that property.
+    3. If *ingredient_properties* returns ``frozenset()`` (or the callback
+       is ``None``), keyword disqualification is used: any ingredient name
+       matching *non_vegan_keys* / *dairy_keys* / *gluten_keys* disqualifies
+       the corresponding badge.
+
+    Args:
+        recipe: The recipe to scan.
+        ingredient_properties: Optional callback ``(ingredient) -> frozenset[str]``
+            that returns dietary properties for an ingredient from an
+            external data source (e.g. purchase tags, brand database).
+        non_vegan_keys: Ingredient-name keywords that disqualify vegan.
+            Defaults to the built-in English food vocabulary.
+        dairy_keys: Ingredient-name keywords that disqualify dairy-free.
+            Defaults to the built-in set.
+        gluten_keys: Ingredient-name keywords that disqualify gluten-free.
+            Defaults to the built-in set.
+        badge_display: Mapping of badge slug → display label.
+            Defaults to :data:`BADGE_DISPLAY`.
+        badge_implies: Mapping of badge slug → set of redundant badges.
+            Defaults to :data:`BADGE_IMPLIES`.
+
+    Returns:
+        List of display strings (e.g. ``["VEGAN", "GLUTEN-FREE"]``).
+    """
+    _non_vegan = non_vegan_keys or DEFAULT_NON_VEGAN_KEYS
+    _dairy = dairy_keys or DEFAULT_DAIRY_KEYS
+    _gluten = gluten_keys or DEFAULT_GLUTEN_KEYS
+    _badge_display = badge_display or BADGE_DISPLAY
+    _badge_implies = badge_implies or BADGE_IMPLIES
+
+    all_callback_keys: set[str] = set()
+
+    props: dict[str, bool] = {"vegan": True, "dairy-free": True, "gluten-free": True}
+
+    for ing in recipe.all_ingredients:
+        if ing.byproduct:
+            continue
+        name_lower = ing.name.lower()
+
+        cb_props: frozenset[str] = frozenset()
+        if ingredient_properties is not None:
+            cb_props = ingredient_properties(ing)
+            all_callback_keys.update(cb_props)
+
+        # Vegan
+        if cb_props:
+            pass
+        else:
+            for key in _non_vegan:
+                if key in name_lower:
+                    props["vegan"] = False
+                    break
+
+        # Dairy-free
+        if cb_props:
+            pass
+        else:
+            for key in _dairy:
+                if key in name_lower:
+                    props["dairy-free"] = False
+                    break
+
+        # Gluten-free
+        if cb_props:
+            pass
+        else:
+            for key in _gluten:
+                if key in name_lower:
+                    props["gluten-free"] = False
+                    break
+
+        # Additional properties from callback only (no keyword fallback)
+        for extra_key in all_callback_keys - {"vegan", "dairy-free", "gluten-free"}:
+            if extra_key not in props:
+                props[extra_key] = True
+            if not (cb_props and extra_key in cb_props):
+                props[extra_key] = False
+
+    raw_badges: list[str] = []
+    for prop_name in [
+        "vegan",
+        "dairy-free",
+        "gluten-free",
+        *sorted(all_callback_keys - {"vegan", "dairy-free", "gluten-free"}),
+    ]:
+        if props.get(prop_name, False):
+            raw_badges.append(prop_name)
+
+    return _resolve_badges(raw_badges, _badge_display, _badge_implies)