Upload 21 files

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /app/requirements.txt
+RUN pip install -r requirements.txt
+
+COPY . /app
+
+EXPOSE 7860
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

main.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Literal
+
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from pydantic import BaseModel, Field
+
+from services.config import settings
+from services.dataset import SubstitutionDatabase
+from services.recipe_service import RecipeAdapterService
+from services.semantic import WordVectorFallback
+
+app = FastAPI(title="BiteWise API", version="1.1.0")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+class AdaptRequest(BaseModel):
+    recipe_text: str = Field(min_length=5)
+    diet: Literal["vegan", "keto", "both"] = "vegan"
+
+
+_db = None
+_semantic = None
+_service = None
+
+
+def get_service() -> RecipeAdapterService:
+    global _db, _semantic, _service
+    if _service is not None:
+        return _service
+
+    _db = SubstitutionDatabase(settings.dataset_path)
+    _semantic = WordVectorFallback(
+        model_name=settings.w2v_model_name,
+        model_path=settings.w2v_model_path,
+        enable_download=settings.enable_w2v_download,
+    )
+    _service = RecipeAdapterService(db=_db, semantic=_semantic)
+    return _service
+
+
+@app.get("/")
+def root():
+    index = Path("static/index.html")
+    if index.exists():
+        return FileResponse(index)
+    return JSONResponse(
+        {
+            "name": "BiteWise API",
+            "status": "running",
+            "hint": "POST /api/adapt with {recipe_text, diet}",
+        }
+    )
+
+
+@app.get("/health")
+def health():
+    return {"ok": True}
+
+
+@app.get("/api/meta")
+def meta():
+    service = get_service()
+    return {
+        "ner_model": settings.ner_model_name,
+        "qa_model": settings.qa_model_name,
+        "word2vec_available": service.semantic.available,
+        "word2vec_mode": service.semantic._kind,
+        "dataset_path": str(settings.dataset_path),
+    }
+
+
+@app.post("/api/adapt")
+def adapt(req: AdaptRequest) -> Dict[str, Any]:
+    try:
+        service = get_service()
+        return service.adapt(req.recipe_text, req.diet)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Unexpected error: {e}")

requirements.txt

@@ -0,0 +1,10 @@
+fastapi>=0.110
+uvicorn[standard]>=0.27
+pydantic>=2.6
+pandas>=2.1
+numpy>=1.26
+transformers>=4.41
+torch>=2.2
+gensim>=4.3
+inflect>=7.2
+python-multipart>=0.0.9

services/classify.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Literal
+
+import torch
+from transformers import AutoModelForQuestionAnswering, AutoTokenizer, pipeline
+
+from .config import settings
+from .text_utils import normalize_text
+
+RecipeType = Literal["baked", "cooked"]
+
+BAKE_KEYWORDS = [
+    "bake", "baking", "oven", "preheat", "flour", "dough", "batter",
+    "cake", "cookie", "muffin", "bread", "pastry", "brownie", "tart",
+    "pie", "scone", "loaf", "whisk", "fold in", "sift", "knead",
+    "leavening", "baking soda", "baking powder", "yeast",
+]
+COOK_KEYWORDS = [
+    "saute", "sauté", "fry", "boil", "simmer", "stir", "grill",
+    "roast", "steam", "poach", "braise", "sear", "stove", "skillet",
+    "pan", "wok", "sauce", "soup", "stew", "marinate",
+]
+
+
+@lru_cache(maxsize=1)
+def get_qa_pipeline():
+    tokenizer = AutoTokenizer.from_pretrained(settings.qa_model_name)
+    model = AutoModelForQuestionAnswering.from_pretrained(settings.qa_model_name)
+    device = 0 if torch.cuda.is_available() else -1
+    return pipeline(
+        "question-answering",
+        model=model,
+        tokenizer=tokenizer,
+        device=device,
+    )
+
+
+def classify_recipe(recipe_text: str) -> RecipeType:
+    text = normalize_text(recipe_text)
+
+    bake_score = sum(1 for kw in BAKE_KEYWORDS if kw in text)
+    cook_score = sum(1 for kw in COOK_KEYWORDS if kw in text)
+
+    answer = ""
+    try:
+        qa = get_qa_pipeline()
+        result = qa(question="Is this recipe for baking or cooking?", context=recipe_text)
+        answer = normalize_text(str(result.get("answer", "")))
+    except Exception:
+        pass
+
+    if any(sig in answer for sig in ("bak", "oven", "pastry", "dough")):
+        return "baked"
+    if any(sig in answer for sig in ("cook", "fry", "boil", "saut", "grill", "stir")):
+        return "cooked"
+
+    if bake_score > cook_score:
+        return "baked"
+    if cook_score > bake_score:
+        return "cooked"
+
+    return "cooked"

services/config.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import os
+
+
+@dataclass(frozen=True)
+class Settings:
+    dataset_path: Path = Path(os.getenv("BITEWISE_DATASET_PATH", "data/united_master_database_corrected.csv"))
+    ner_model_name: str = os.getenv("BITEWISE_NER_MODEL", "Dizex/InstaFoodRoBERTa-NER")
+    qa_model_name: str = os.getenv("BITEWISE_QA_MODEL", "bert-large-uncased-whole-word-masking-finetuned-squad")
+    w2v_model_path: str = os.getenv("BITEWISE_W2V_PATH", "")
+    w2v_model_name: str = os.getenv("BITEWISE_W2V_MODEL", "glove-wiki-gigaword-50")
+    enable_w2v_download: bool = os.getenv("BITEWISE_ENABLE_W2V_DOWNLOAD", "0") == "1"
+    max_ingredients: int = int(os.getenv("BITEWISE_MAX_INGREDIENTS", "48"))
+    similarity_threshold: float = float(os.getenv("BITEWISE_SIM_THRESHOLD", "0.55"))
+
+
+settings = Settings()

services/dataset.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional
+import re
+
+import pandas as pd
+
+from .text_utils import as_aliases, ingredient_variants, normalize_text
+
+REQUIRED_COLUMNS = [
+    "Ingredient",
+    "Context",
+    "Aliases",
+    "Category",
+    "Is_Keto_Friendly",
+    "Is_Vegan_Friendly",
+    "Keto_Substitution",
+    "Keto_Instruction",
+    "Vegan_Substitution",
+    "Vegan_Instruction",
+    "Vegan_Keto_Substitution",
+    "Vegan_Keto_Instruction",
+]
+
+BAKE_CONTEXTS = {
+    "Baking & Desserts",
+    "Baking (Binder)",
+    "Baking (Leavening)",
+    "Pastries",
+    "Bagels",
+    "Puddings",
+    "Tiramisu",
+}
+
+COOK_CONTEXTS = {
+    "Main Course & Heavy Cooking",
+    "Sauces, Dips & Dressings",
+    "Soups & Savory Liquids",
+    "Cold Prep & Light Meals",
+    "Pasta",
+    "Lasagna",
+    "Roast",
+    "Stir-Fry",
+    "Appetizer",
+    "Indian",
+    "Beverages",
+    "Cheese Making",
+    "Processed",
+    "Technical & Additives",
+}
+
+
+@dataclass(frozen=True)
+class IngredientRow:
+    ingredient: str
+    context: str
+    aliases: List[str]
+    category: str
+    is_keto_friendly: bool
+    is_vegan_friendly: bool
+    keto_substitution: Optional[str]
+    keto_instruction: Optional[str]
+    vegan_substitution: Optional[str]
+    vegan_instruction: Optional[str]
+    vegan_keto_substitution: Optional[str]
+    vegan_keto_instruction: Optional[str]
+
+    @property
+    def lookup_terms(self) -> List[str]:
+        return [self.ingredient, *self.aliases]
+
+
+class SubstitutionDatabase:
+    def __init__(self, csv_path: str | Path):
+        self.csv_path = Path(csv_path)
+        self.df = self._load()
+        self.rows = [self._row_from_series(row) for _, row in self.df.iterrows()]
+        self._preferred_rows_cache: Dict[str, List[IngredientRow]] = {}
+
+    def _load(self) -> pd.DataFrame:
+        if not self.csv_path.exists():
+            raise FileNotFoundError(
+                f"Could not find substitution database at {self.csv_path}. "
+                "Place united_master_database_corrected.csv in data/ or set BITEWISE_DATASET_PATH."
+            )
+
+        df = pd.read_csv(self.csv_path)
+        missing = [c for c in REQUIRED_COLUMNS if c not in df.columns]
+        if missing:
+            raise ValueError(f"Dataset missing required columns: {missing}")
+
+        df = df.copy()
+        df = df.dropna(subset=["Ingredient", "Context"])
+        df["_ingredient_norm"] = df["Ingredient"].astype(str).map(normalize_text)
+        df["_aliases_norm"] = df["Aliases"].apply(as_aliases)
+        return df.reset_index(drop=True)
+
+    def _row_from_series(self, row: pd.Series) -> IngredientRow:
+        return IngredientRow(
+            ingredient=str(row["Ingredient"]),
+            context=str(row["Context"]),
+            aliases=as_aliases(row.get("Aliases")),
+            category=str(row.get("Category", "")),
+            is_keto_friendly=bool(row.get("Is_Keto_Friendly", False)),
+            is_vegan_friendly=bool(row.get("Is_Vegan_Friendly", False)),
+            keto_substitution=None if pd.isna(row.get("Keto_Substitution")) else str(row.get("Keto_Substitution")),
+            keto_instruction=None if pd.isna(row.get("Keto_Instruction")) else str(row.get("Keto_Instruction")),
+            vegan_substitution=None if pd.isna(row.get("Vegan_Substitution")) else str(row.get("Vegan_Substitution")),
+            vegan_instruction=None if pd.isna(row.get("Vegan_Instruction")) else str(row.get("Vegan_Instruction")),
+            vegan_keto_substitution=None if pd.isna(row.get("Vegan_Keto_Substitution")) else str(row.get("Vegan_Keto_Substitution")),
+            vegan_keto_instruction=None if pd.isna(row.get("Vegan_Keto_Instruction")) else str(row.get("Vegan_Keto_Instruction")),
+        )
+
+    def contexts_for_recipe_type(self, recipe_type: str) -> set[str]:
+        return BAKE_CONTEXTS if recipe_type == "baked" else COOK_CONTEXTS
+
+    def preferred_rows(self, recipe_type: str) -> List[IngredientRow]:
+        if recipe_type not in self._preferred_rows_cache:
+            contexts = self.contexts_for_recipe_type(recipe_type)
+            self._preferred_rows_cache[recipe_type] = [row for row in self.rows if row.context in contexts]
+        return self._preferred_rows_cache[recipe_type]
+
+    def _normalize_terms(self, row: IngredientRow) -> List[str]:
+        return [normalize_text(term) for term in row.lookup_terms if normalize_text(term)]
+
+    def _match_exact(self, rows: List[IngredientRow], query: str) -> List[IngredientRow]:
+        query = normalize_text(query)
+        exact_rows = []
+        for row in rows:
+            terms = self._normalize_terms(row)
+            if not terms:
+                continue
+            if normalize_text(row.ingredient) == query:
+                exact_rows.append(row)
+                continue
+            if query in terms:
+                exact_rows.append(row)
+        return exact_rows
+
+    def _match_partial(self, rows: List[IngredientRow], query: str) -> List[IngredientRow]:
+        query = normalize_text(query)
+        if len(query) < 4:
+            return []
+        pattern = re.compile(rf"(?<!\w){re.escape(query)}(?!\w)")
+        partial_rows = []
+        for row in rows:
+            candidates = [normalize_text(row.ingredient), *self._normalize_terms(row)]
+            if any(pattern.search(candidate) for candidate in candidates):
+                partial_rows.append(row)
+        return partial_rows
+
+    def _rank_rows(self, rows: List[IngredientRow], query: str) -> List[IngredientRow]:
+        """Prefer exact ingredient matches over aliases, then longer ingredient names."""
+        q = normalize_text(query)
+
+        def score(row: IngredientRow) -> tuple[int, int, int]:
+            ingredient_norm = normalize_text(row.ingredient)
+            alias_norms = [normalize_text(a) for a in row.aliases]
+            exact_ingredient = int(ingredient_norm == q)
+            exact_alias = int(q in alias_norms)
+            # longer exact ingredient names are usually more specific and safer
+            length = len(ingredient_norm)
+            return (exact_ingredient, exact_alias, length)
+
+        return sorted(rows, key=score, reverse=True)
+
+    def find_rows(self, query: str, recipe_type: str) -> List[IngredientRow]:
+        query = normalize_text(query)
+        if not query:
+            return []
+
+        preferred = self.preferred_rows(recipe_type)
+        exact_preferred = self._match_exact(preferred, query)
+        if exact_preferred:
+            return self._rank_rows(exact_preferred, query)
+
+        exact_all = self._match_exact(self.rows, query)
+        if exact_all:
+            return self._rank_rows(exact_all, query)
+
+        partial_preferred = self._match_partial(preferred, query)
+        if partial_preferred:
+            return self._rank_rows(partial_preferred, query)
+
+        partial_all = self._match_partial(self.rows, query)
+        if partial_all:
+            return self._rank_rows(partial_all, query)
+
+        return []
+
+    def pick_substitution(self, row: IngredientRow, diet: str) -> tuple[str, str, bool]:
+        if diet == "vegan":
+            sub = row.vegan_substitution
+            instr = row.vegan_instruction
+            compatible = row.is_vegan_friendly
+        elif diet == "keto":
+            sub = row.keto_substitution
+            instr = row.keto_instruction
+            compatible = row.is_keto_friendly
+        else:
+            sub = row.vegan_keto_substitution
+            instr = row.vegan_keto_instruction
+            compatible = row.is_vegan_friendly and row.is_keto_friendly
+
+        if compatible or not sub or str(sub).strip().lower() in {"nan", "none"}:
+            return row.ingredient, "Already compatible — no substitution needed.", True
+
+        return str(sub), (str(instr) if instr and str(instr).lower() != "nan" else ""), False

services/ner.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import List
+
+import torch
+from transformers import AutoModelForTokenClassification, AutoTokenizer, pipeline
+
+from .config import settings
+from .text_utils import dedupe_preserve_order, strip_amounts_and_preps, tokenize_recipe_segments
+
+
+@lru_cache(maxsize=1)
+def get_ner_pipeline():
+    tokenizer = AutoTokenizer.from_pretrained(settings.ner_model_name)
+    model = AutoModelForTokenClassification.from_pretrained(settings.ner_model_name)
+    device = 0 if torch.cuda.is_available() else -1
+    return pipeline(
+        "token-classification",
+        model=model,
+        tokenizer=tokenizer,
+        aggregation_strategy="simple",
+        device=device,
+    )
+
+
+def _merge_adjacent_entities(entities: List[dict]) -> List[dict]:
+    merged: List[dict] = []
+    for ent in entities:
+        start = int(ent.get("start", 0))
+        end = int(ent.get("end", 0))
+        label = str(ent.get("entity_group", ""))
+        if not label or end <= start:
+            continue
+
+        if merged and merged[-1]["label"] == label and -1 <= start - merged[-1]["end"] <= 1:
+            merged[-1]["end"] = end
+            continue
+
+        merged.append({"start": start, "end": end, "label": label})
+    return merged
+
+
+def _extract_spans(text: str) -> List[str]:
+    try:
+        ner = get_ner_pipeline()
+        entities = ner(text)
+    except Exception:
+        return []
+
+    merged = _merge_adjacent_entities(entities)
+    spans: List[str] = []
+    for ent in merged:
+        span = text[ent["start"]:ent["end"]].strip(" ,.;:\n\t")
+        span = strip_amounts_and_preps(span)
+        if len(span) >= 3:
+            spans.append(span)
+    return dedupe_preserve_order(spans)
+
+
+def extract_ingredients(text: str, max_items: int = 48) -> List[str]:
+    """Extract ingredient-like tokens from a recipe.
+
+    We keep the MVP behaviour simple: split the recipe into comma-separated
+    chunks, run RoBERTa NER per chunk, and fall back to the cleaned chunk when
+    the model misses it.
+    """
+    chunks = tokenize_recipe_segments(text)
+    if not chunks:
+        chunks = [strip_amounts_and_preps(text)]
+
+    extracted: List[str] = []
+    for chunk in chunks:
+        if not chunk:
+            continue
+
+        spans = _extract_spans(chunk)
+        if spans:
+            extracted.extend(spans)
+        else:
+            cleaned = strip_amounts_and_preps(chunk)
+            if cleaned and len(cleaned) >= 2:
+                extracted.append(cleaned)
+
+    # Keep only meaningful spans; short fragments tend to be false positives.
+    cleaned = []
+    for item in dedupe_preserve_order(extracted):
+        if len(item) < 3:
+            continue
+        if item in {"and", "or", "the", "a", "an"}:
+            continue
+        cleaned.append(item)
+
+    return cleaned[:max_items]

services/recipe_service.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Literal, Optional
+
+from .classify import classify_recipe
+from .config import settings
+from .dataset import SubstitutionDatabase
+from .ner import extract_ingredients
+from .semantic import WordVectorFallback
+from .text_utils import normalize_text
+
+Diet = Literal["vegan", "keto", "both"]
+
+
+@dataclass
+class IngredientResult:
+    original: str
+    normalized: str
+    compliant: bool
+    substitute: str
+    instructions: str
+    source: str
+    matched_ingredient: Optional[str] = None
+    confidence: float = 1.0
+    notes: Optional[str] = None
+
+    def as_dict(self) -> Dict[str, Any]:
+        payload = {
+            "original": self.original,
+            "normalized": self.normalized,
+            "compliant": self.compliant,
+            "substitute": self.substitute,
+            "instructions": self.instructions,
+            "source": self.source,
+            "matched_ingredient": self.matched_ingredient,
+            "confidence": round(float(self.confidence), 3),
+        }
+        if self.notes:
+            payload["notes"] = self.notes
+        return payload
+
+
+class RecipeAdapterService:
+    def __init__(self, db: SubstitutionDatabase, semantic: WordVectorFallback):
+        self.db = db
+        self.semantic = semantic
+
+    def _row_to_result(self, ingredient: str, row, diet: Diet) -> IngredientResult:
+        substitute, instructions, compliant = self.db.pick_substitution(row, diet)
+        normalized = normalize_text(ingredient)
+
+        if compliant:
+            return IngredientResult(
+                original=ingredient,
+                normalized=normalized,
+                compliant=True,
+                substitute=ingredient,
+                instructions="Already compatible — no substitution needed.",
+                source="database match",
+                matched_ingredient=row.ingredient,
+                confidence=1.0,
+            )
+
+        return IngredientResult(
+            original=ingredient,
+            normalized=normalized,
+            compliant=False,
+            substitute=substitute,
+            instructions=instructions,
+            source="database match",
+            matched_ingredient=row.ingredient,
+            confidence=0.96,
+        )
+
+    def _semantic_fallback(self, ingredient: str, diet: Diet, recipe_type: str) -> Optional[IngredientResult]:
+        candidates = list(dict.fromkeys(row.ingredient for row in self.db.rows))
+        if not candidates:
+            return None
+
+        hits = self.semantic.nearest(ingredient, candidates, top_k=5)
+        if not hits:
+            return None
+
+        for hit in hits:
+            matched_rows = self.db.find_rows(hit.term, recipe_type)
+            if not matched_rows:
+                continue
+            row = matched_rows[0]
+            result = self._row_to_result(ingredient, row, diet)
+            result.source = f"word2vec semantic match ({hit.term}, score={hit.score:.2f})"
+            result.confidence = max(0.5, min(0.95, hit.score))
+            return result
+
+        return None
+
+    def adapt(self, recipe_text: str, diet: Diet) -> Dict[str, Any]:
+        if diet not in {"vegan", "keto", "both"}:
+            raise ValueError("diet must be one of: vegan, keto, both")
+
+        recipe_text = (recipe_text or "").strip()
+        if len(recipe_text) < 5:
+            raise ValueError("recipe_text is too short")
+
+        recipe_type = classify_recipe(recipe_text)
+        ingredients = extract_ingredients(recipe_text, max_items=settings.max_ingredients)
+
+        results: List[IngredientResult] = []
+        substitutions = 0
+
+        for ingredient in ingredients:
+            matches = self.db.find_rows(ingredient, recipe_type)
+            if matches:
+                result = self._row_to_result(ingredient, matches[0], diet)
+            else:
+                result = self._semantic_fallback(ingredient, diet, recipe_type)
+                if result is None:
+                    result = IngredientResult(
+                        original=ingredient,
+                        normalized=normalize_text(ingredient),
+                        compliant=True,
+                        substitute=ingredient,
+                        instructions="No substitution needed.",
+                        source="not in database — assumed compatible",
+                        matched_ingredient=None,
+                        confidence=0.4,
+                        notes="No reliable database or semantic match found.",
+                    )
+
+            if not result.compliant:
+                substitutions += 1
+            results.append(result)
+
+        return {
+            "diet": diet,
+            "recipe_type": recipe_type,
+            "ingredients": [r.as_dict() for r in results],
+            "ingredients_found": len(results),
+            "substitution_count": substitutions,
+            "model_metadata": {
+                "ner_model": settings.ner_model_name,
+                "qa_model": settings.qa_model_name,
+                "word2vec_available": self.semantic.available,
+                "word2vec_mode": self.semantic._kind,
+                "dataset_path": str(self.db.csv_path),
+            },
+            "disclaimer": (
+                "This is an assistive recipe tool, not nutritional or allergen medical advice. "
+                "Verify substitutions before cooking."
+            ),
+        }

services/semantic.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, List, Optional
+
+import numpy as np
+
+from .text_utils import normalize_text, singularize
+
+
+@dataclass
+class SemanticHit:
+    term: str
+    score: float
+
+
+class WordVectorFallback:
+    """Small semantic fallback using vector similarity when available.
+
+    It is intentionally optional so the app can still run on free hosts even if
+    no embedding model is downloaded.
+    """
+
+    def __init__(self, model_name: str = "glove-wiki-gigaword-50", model_path: str = "", enable_download: bool = False):
+        self.model = None
+        self._kind = "disabled"
+        self._load(model_name=model_name, model_path=model_path, enable_download=enable_download)
+
+    def _load(self, model_name: str, model_path: str, enable_download: bool) -> None:
+        try:
+            from gensim.models import KeyedVectors
+            import gensim.downloader as api
+        except Exception:
+            self.model = None
+            self._kind = "unavailable"
+            return
+
+        if model_path:
+            try:
+                self.model = KeyedVectors.load(model_path, mmap="r")
+                self._kind = f"local:{model_path}"
+                return
+            except Exception:
+                try:
+                    self.model = KeyedVectors.load_word2vec_format(model_path, binary=model_path.endswith(".bin"))
+                    self._kind = f"local-vec:{model_path}"
+                    return
+                except Exception:
+                    self.model = None
+
+        if enable_download:
+            try:
+                self.model = api.load(model_name)
+                self._kind = model_name
+            except Exception:
+                self.model = None
+                self._kind = "download-failed"
+        else:
+            self.model = None
+            self._kind = "disabled"
+
+    @property
+    def available(self) -> bool:
+        return self.model is not None
+
+    def vector_for(self, phrase: str) -> Optional[np.ndarray]:
+        if not self.available:
+            return None
+
+        tokens = [singularize(t) for t in normalize_text(phrase).split()]
+        vectors = []
+        for token in tokens:
+            if token in self.model:
+                vectors.append(self.model[token])
+
+        if vectors:
+            return np.mean(np.stack(vectors), axis=0)
+
+        phrase_key = normalize_text(phrase).replace(" ", "_")
+        if phrase_key in self.model:
+            return self.model[phrase_key]
+
+        return None
+
+    def nearest(self, query: str, candidates: Iterable[str], top_k: int = 3) -> List[SemanticHit]:
+        if not self.available:
+            return []
+
+        qv = self.vector_for(query)
+        if qv is None:
+            return []
+
+        scored: List[SemanticHit] = []
+        for candidate in candidates:
+            cv = self.vector_for(candidate)
+            if cv is None:
+                continue
+            score = float(np.dot(qv, cv) / (np.linalg.norm(qv) * np.linalg.norm(cv) + 1e-8))
+            scored.append(SemanticHit(term=candidate, score=score))
+
+        scored.sort(key=lambda x: x.score, reverse=True)
+        return scored[:top_k]

services/text_utils.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Iterable, List
+
+import inflect
+
+_p = inflect.engine()
+
+
+def normalize_text(text: str) -> str:
+    text = (text or "").lower().strip()
+    text = re.sub(r"[\u2018\u2019\u201c\u201d]", "'", text)
+    text = re.sub(r"[^a-z0-9\s\-']+", " ", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+@lru_cache(maxsize=4096)
+def singularize(word: str) -> str:
+    word = normalize_text(word)
+    singular = _p.singular_noun(word)
+    return singular if singular else word
+
+
+def dedupe_preserve_order(items: Iterable[str]) -> List[str]:
+    seen = set()
+    out = []
+    for item in items:
+        item = normalize_text(item)
+        if item and item not in seen:
+            seen.add(item)
+            out.append(item)
+    return out
+
+
+_AMOUNT_RE = re.compile(
+    r"^(?:\d+(?:\.\d+)?|\d+/\d+|[\u00bc\u00bd\u00be\u2153\u2154\u215b\u215c\u215d\u215e])\s*"
+)
+_MEASURE_RE = re.compile(
+    r"^(?:g|kg|mg|ml|l|oz|lb|lbs|cup|cups|tbsp|tablespoon|tsp|teaspoon|clove|cloves|slice|slices|piece|pieces|can|cans|bunch|handful|pinch|large|small|medium|whole)\s+"
+)
+
+
+def strip_amounts_and_preps(text: str) -> str:
+    """Remove leading quantities and prep words from a recipe fragment."""
+    text = normalize_text(text)
+    text = _AMOUNT_RE.sub("", text)
+    text = _MEASURE_RE.sub("", text)
+    text = re.sub(r"^of\s+", "", text)
+    text = re.sub(r"\(.*?\)", "", text)
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def tokenize_recipe_segments(text: str) -> List[str]:
+    """Split a recipe into ingredient-like chunks.
+
+    The MVP demo worked best with comma-separated ingredients, so we keep that
+    behaviour first and only use a small fallback split when the recipe has no
+    commas.
+    """
+    raw = text or ""
+    parts = re.split(r",|\n|;", raw)
+    if len(parts) == 1:
+        parts = re.split(r"\s+and\s+", raw, flags=re.IGNORECASE)
+
+    cleaned = []
+    for part in parts:
+        item = strip_amounts_and_preps(part)
+        if item and len(item) > 1:
+            cleaned.append(item)
+    return dedupe_preserve_order(cleaned)
+
+
+def ingredient_variants(ingredient: str) -> List[str]:
+    ing = normalize_text(ingredient)
+    variants = [ing]
+
+    singular = singularize(ing)
+    if singular != ing:
+        variants.append(singular)
+
+    suffixes = [" cheese", " oil", " milk", " cream", " butter", " powder", " sauce", " paste", " extract"]
+    for suffix in suffixes:
+        if ing.endswith(suffix) and len(ing) > len(suffix) + 1:
+            base = ing[:-len(suffix)].strip()
+            variants.append(base)
+            base_singular = singularize(base)
+            if base_singular != base:
+                variants.append(base_singular)
+
+    words = ing.split()
+    if len(words) > 1:
+        variants.extend([
+            words[0],
+            words[-1],
+            " ".join(words[:2]),
+            " ".join(words[1:]),
+        ])
+
+    # very short fragments create false matches, so keep them only as a last resort
+    return dedupe_preserve_order(variants)
+
+
+def as_aliases(aliases: str | float | None) -> List[str]:
+    if aliases is None:
+        return []
+    if not isinstance(aliases, str):
+        return []
+    return dedupe_preserve_order(alias.strip() for alias in aliases.split("|"))