Initial release: Epicure Explorer Gradio demo. Paper arxiv 2605.22391.

LICENSE

@@ -0,0 +1,21 @@
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+Copyright (c) 2026 Jakub Radzikowski and Josef Chen (KAIKAKU.AI)
+
+You are free to:
+  Share -- copy and redistribute the material in any medium or format
+  Adapt -- remix, transform, and build upon the material for any purpose, even commercially
+
+Under the following terms:
+  Attribution -- You must give appropriate credit, provide a link to the license,
+  and indicate if changes were made. You may do so in any reasonable manner, but
+  not in any way that suggests the licensor endorses you or your use.
+
+  No additional restrictions -- You may not apply legal terms or technological
+  measures that legally restrict others from doing anything the license permits.
+
+Full text: https://creativecommons.org/licenses/by/4.0/legalcode
+
+Citation:
+  Radzikowski, J. and Chen, J. (2026). Epicure: Navigating the Emergent Geometry
+  of Food Ingredient Embeddings. arXiv:2605.22391.

README.md

@@ -1,13 +1,37 @@
 ---
 title: Epicure Explorer
-emoji: 🔥
-colorFrom: yellow
-colorTo: indigo
+emoji: "🌶"
+colorFrom: green
+colorTo: red
 sdk: gradio
-sdk_version: 6.15.0
-python_version: '3.13'
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
+license: cc-by-4.0
+short_description: Operators over the three Epicure ingredient embeddings
+models:
+  - Kaikaku/epicure-cooc
+  - Kaikaku/epicure-core
+  - Kaikaku/epicure-chem
+datasets:
+  - Kaikaku/epicure-corpus-resources
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Epicure Explorer
+
+Interactive chef-facing demo of the three Epicure sibling ingredient embeddings (Cooc, Core, Chem). Three operator tabs:
+
+1. **Pairings**: top-K cosine neighbours plus the closest emergent mode for any of 1,790 ingredients.
+2. **Supervised SLERP**: rotate a seed toward a supervised direction (cuisine macro-region, food group, NOVA level, sensory category, USDA macro) by a continuous angle.
+3. **Emergent SLERP**: rotate a seed toward an unsupervised factor-mode pole discovered via multi-seed-stable FastICA + GMM.
+
+Paper: [Epicure: Navigating the Emergent Geometry of Food Ingredient Embeddings](https://arxiv.org/abs/2605.22391).
+
+## Try
+
+- Pairings, `chicken`, Cooc -> garlic, onion, black_pepper, turkey, carrot (recipe companions).
+- Pairings, `chicken`, Chem -> beef, pork, cream_of_chicken_soup, buffalo_wing_sauce, peanut (chemistry peers).
+- Supervised SLERP, `rice` + `cuisine:South_Asian`, 30 deg, Core -> turmeric, mustard_seed, fenugreek_seed, coriander, cumin.
+- Supervised SLERP, `corn` + `cuisine:Latin_American`, 30 deg, Chem -> poblano_pepper, corn_tortilla, salsa, queso_fresco, chipotle_pepper.
+
+Citation: Radzikowski and Chen, 2026.

app.py

@@ -0,0 +1,199 @@
+"""Epicure Explorer: a chef-facing interactive demo of the three sibling embeddings.
+
+Three tabs:
+  - Pairings: top-K cosine neighbours + closest emergent mode for a chosen ingredient.
+  - Supervised SLERP: rotate a seed toward a supervised pole (cuisine, food group,
+    NOVA, sensory, USDA macros) by a chosen angle.
+  - Emergent SLERP: rotate a seed toward an emergent factor-mode pole.
+
+Loads all three siblings on startup from their HF model repos.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import gradio as gr
+
+# epicure.py is loaded from the cooc repo's snapshot at runtime; alternatively
+# copy it into this Space's root for offline development.
+try:
+    from epicure import Epicure  # noqa: F401
+except ImportError:
+    from huggingface_hub import hf_hub_download
+    epicure_py = hf_hub_download("Kaikaku/epicure-cooc", "epicure.py")
+    sys.path.insert(0, os.path.dirname(epicure_py))
+    from epicure import Epicure  # noqa: F401
+
+MODELS = {
+    "cooc": Epicure.from_pretrained("Kaikaku/epicure-cooc"),
+    "core": Epicure.from_pretrained("Kaikaku/epicure-core"),
+    "chem": Epicure.from_pretrained("Kaikaku/epicure-chem"),
+}
+
+ALL_INGREDIENTS = sorted(MODELS["cooc"].vocab.keys())
+
+
+def _supervised_choices(sibling: str) -> list[str]:
+    return sorted(MODELS[sibling].supervised_poles.keys())
+
+
+def _factor_modes(sibling: str) -> list[tuple[str, str]]:
+    return [
+        (f"{m.mode_id} - {m.label}", m.mode_id)
+        for m in MODELS[sibling].modes
+        if m.kind == "factor"
+    ]
+
+
+def pairings(sibling: str, ingredient: str, k: int):
+    if not ingredient or ingredient not in MODELS[sibling].vocab:
+        return [], []
+    m = MODELS[sibling]
+    nb = m.neighbors(ingredient, k=k)
+    cm = m.closest_mode(ingredient, kind=None, k=k)
+    return (
+        [[name, f"{sim:.4f}"] for name, sim in nb],
+        [[mid, label, f"{sim:.4f}"] for mid, label, sim in cm],
+    )
+
+
+def supervised_slerp(sibling: str, seed: str, direction: str, theta: float, k: int):
+    if not seed or seed not in MODELS[sibling].vocab:
+        return []
+    if direction not in MODELS[sibling].supervised_poles:
+        return []
+    r = MODELS[sibling].slerp(seed, direction, theta_deg=theta, k=k)
+    return [[name, f"{sim:.4f}"] for name, sim in r]
+
+
+def emergent_slerp(sibling: str, seed: str, factor_mode_id: str, theta: float, k: int):
+    if not seed or seed not in MODELS[sibling].vocab:
+        return []
+    m = MODELS[sibling]
+    pole = None
+    for mode in m.modes:
+        if mode.mode_id == factor_mode_id:
+            pole = mode.pole
+            break
+    if pole is None:
+        return []
+    r = m.slerp(seed, pole, theta_deg=theta, k=k)
+    return [[name, f"{sim:.4f}"] for name, sim in r]
+
+
+with gr.Blocks(title="Epicure Explorer") as demo:
+    gr.Markdown(
+        """# Epicure Explorer
+
+Interactive chef-facing operators over the three Epicure sibling embeddings (Cooc, Core, Chem),
+from the paper [Epicure: Navigating the Emergent Geometry of Food Ingredient Embeddings](https://arxiv.org/abs/2605.22391).
+
+Each sibling sits at a different point on the chemistry-vs-recipe-context spectrum:
+- **Cooc** walks recipe co-occurrence only. Neighbours are recipe companions.
+- **Core** blends typed FlavorDB compound walks with injected ingredient-ingredient walks. Concentrated geometry, tightest modes.
+- **Chem** walks typed FlavorDB compound metapaths only. Strongest supervised-direction recovery; neighbours are flavour-profile peers.
+"""
+    )
+
+    sibling = gr.Radio(
+        choices=["cooc", "core", "chem"],
+        value="chem",
+        label="Sibling embedding",
+    )
+
+    with gr.Tab("Pairings"):
+        ingredient = gr.Dropdown(
+            choices=ALL_INGREDIENTS, value="chicken", label="Ingredient", allow_custom_value=False
+        )
+        k_pair = gr.Slider(1, 10, value=5, step=1, label="K")
+        pair_btn = gr.Button("Find pairings", variant="primary")
+        with gr.Row():
+            nb_table = gr.Dataframe(
+                headers=["Neighbour", "Cosine"], label="Top-K nearest neighbours", interactive=False
+            )
+            mode_table = gr.Dataframe(
+                headers=["Mode id", "Label", "Cosine"], label="Closest modes", interactive=False
+            )
+        pair_btn.click(
+            pairings, inputs=[sibling, ingredient, k_pair], outputs=[nb_table, mode_table]
+        )
+
+    with gr.Tab("Supervised SLERP"):
+        sup_seed = gr.Dropdown(
+            choices=ALL_INGREDIENTS, value="rice", label="Seed ingredient"
+        )
+        sup_dir = gr.Dropdown(
+            choices=_supervised_choices("chem"),
+            value="cuisine:South_Asian",
+            label="Supervised direction",
+        )
+        sup_theta = gr.Slider(0, 90, value=30, step=5, label="Rotation angle (deg)")
+        sup_k = gr.Slider(1, 10, value=5, step=1, label="K")
+        sup_btn = gr.Button("Rotate", variant="primary")
+        sup_table = gr.Dataframe(
+            headers=["Ingredient", "Cosine"], label="Top-K rotated-query neighbours"
+        )
+        sup_btn.click(
+            supervised_slerp,
+            inputs=[sibling, sup_seed, sup_dir, sup_theta, sup_k],
+            outputs=sup_table,
+        )
+        sibling.change(
+            lambda s: gr.Dropdown(choices=_supervised_choices(s), value=None),
+            inputs=sibling,
+            outputs=sup_dir,
+        )
+
+    with gr.Tab("Emergent SLERP"):
+        em_seed = gr.Dropdown(
+            choices=ALL_INGREDIENTS, value="chocolate", label="Seed ingredient"
+        )
+        factor_options = _factor_modes("chem")
+        em_mode = gr.Dropdown(
+            choices=[label for label, _ in factor_options],
+            value=factor_options[0][0] if factor_options else None,
+            label="Emergent factor mode (label - mode_id)",
+        )
+        em_theta = gr.Slider(0, 90, value=30, step=5, label="Rotation angle (deg)")
+        em_k = gr.Slider(1, 10, value=5, step=1, label="K")
+        em_btn = gr.Button("Rotate", variant="primary")
+        em_table = gr.Dataframe(
+            headers=["Ingredient", "Cosine"], label="Top-K rotated-query neighbours"
+        )
+
+        def _resolve_factor(sib, label, seed, theta, k):
+            options = _factor_modes(sib)
+            mode_id = None
+            for lab, mid in options:
+                if lab == label:
+                    mode_id = mid
+                    break
+            if mode_id is None and options:
+                mode_id = options[0][1]
+            if mode_id is None:
+                return []
+            return emergent_slerp(sib, seed, mode_id, theta, k)
+
+        em_btn.click(
+            _resolve_factor,
+            inputs=[sibling, em_mode, em_seed, em_theta, em_k],
+            outputs=em_table,
+        )
+        sibling.change(
+            lambda s: gr.Dropdown(choices=[label for label, _ in _factor_modes(s)], value=None),
+            inputs=sibling,
+            outputs=em_mode,
+        )
+
+    gr.Markdown(
+        """---
+**Cite:** Radzikowski and Chen 2026, *Epicure: Navigating the Emergent Geometry of Food Ingredient Embeddings*, arXiv:2605.22391.
+
+Models: [epicure-cooc](https://huggingface.co/Kaikaku/epicure-cooc), [epicure-core](https://huggingface.co/Kaikaku/epicure-core), [epicure-chem](https://huggingface.co/Kaikaku/epicure-chem).
+Dataset: [epicure-corpus-resources](https://huggingface.co/datasets/Kaikaku/epicure-corpus-resources).
+"""
+    )
+
+if __name__ == "__main__":
+    demo.launch()

epicure.py

@@ -0,0 +1,208 @@
+"""
+Epicure: minimal loader for the three sibling ingredient embeddings.
+
+Usage
+-----
+    from epicure import Epicure
+    m = Epicure.from_pretrained("Kaikaku/epicure-cooc")
+    m.neighbors("chicken", k=5)
+    m.slerp("rice", "cuisine:South_Asian/South Asian", theta_deg=30, k=5)
+    m.closest_mode("miso", kind="factor", k=3)
+
+The three repos (epicure-cooc, epicure-core, epicure-chem) ship the same loader.
+Paper: https://arxiv.org/abs/2605.22391
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Iterable
+
+import numpy as np
+
+
+def _try_hf_download(repo_id: str, filename: str, revision: str | None = None) -> str:
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError as exc:
+        raise ImportError(
+            "huggingface_hub is required for from_pretrained(). "
+            "Install with: pip install huggingface_hub safetensors numpy"
+        ) from exc
+    return hf_hub_download(repo_id=repo_id, filename=filename, revision=revision)
+
+
+def _load_safetensors(path: str) -> np.ndarray:
+    try:
+        from safetensors.numpy import load_file
+    except ImportError as exc:
+        raise ImportError("safetensors required. pip install safetensors") from exc
+    return load_file(path)["embeddings"]
+
+
+def _unit(v: np.ndarray, axis: int = -1, eps: float = 1e-9) -> np.ndarray:
+    n = np.linalg.norm(v, axis=axis, keepdims=True)
+    return v / np.maximum(n, eps)
+
+
+@dataclass
+class ModeEntry:
+    mode_id: str
+    kind: str
+    property: str
+    label: str
+    n_members: int
+    members: list[str]
+    pole: np.ndarray  # (d_model,) unit-normalised
+
+
+class Epicure:
+    """Lookup-table embedding with neighbour, SLERP, and closest-mode operators."""
+
+    def __init__(
+        self,
+        E: np.ndarray,
+        vocab: dict[str, int],
+        modes: list[ModeEntry],
+        supervised_poles: dict[str, np.ndarray],
+        config: dict,
+    ):
+        self.E_raw = E.astype(np.float32)
+        self.E = _unit(self.E_raw)
+        self.vocab = vocab
+        self.itos = {i: n for n, i in vocab.items()}
+        self.modes = modes
+        self.supervised_poles = supervised_poles
+        self.config = config
+
+    # ----- constructors -----
+
+    @classmethod
+    def from_pretrained(cls, repo_id_or_path: str, revision: str | None = None) -> "Epicure":
+        if os.path.isdir(repo_id_or_path):
+            base = repo_id_or_path
+            getp = lambda fn: os.path.join(base, fn)
+        else:
+            getp = lambda fn: _try_hf_download(repo_id_or_path, fn, revision=revision)
+        E = _load_safetensors(getp("embeddings.safetensors"))
+        with open(getp("vocab.json")) as f:
+            vocab = json.load(f)
+        with open(getp("modes.json")) as f:
+            modes_raw = json.load(f)
+        with open(getp("supervised_poles.json")) as f:
+            sup_raw = json.load(f)
+        with open(getp("config.json")) as f:
+            config = json.load(f)
+        modes = [
+            ModeEntry(
+                mode_id=m["mode_id"],
+                kind=m["kind"],
+                property=m["property"],
+                label=m["label"],
+                n_members=m["n_members"],
+                members=m["members"],
+                pole=np.array(m["pole"], dtype=np.float32),
+            )
+            for m in modes_raw
+        ]
+        supervised_poles = {k: np.array(v, dtype=np.float32) for k, v in sup_raw.items()}
+        return cls(E, vocab, modes, supervised_poles, config)
+
+    # ----- core operators -----
+
+    def vec(self, name: str, normalised: bool = True) -> np.ndarray:
+        i = self.vocab[name]
+        return self.E[i] if normalised else self.E_raw[i]
+
+    def neighbors(self, name: str, k: int = 5, exclude_self: bool = True) -> list[tuple[str, float]]:
+        v = self.vec(name)
+        sims = self.E @ v
+        order = np.argsort(-sims)
+        start = 1 if exclude_self else 0
+        return [(self.itos[int(i)], float(sims[i])) for i in order[start:start + k]]
+
+    def slerp(
+        self,
+        seed: str,
+        direction: str | np.ndarray,
+        theta_deg: float,
+        k: int = 5,
+        exclude_seed: bool = True,
+    ) -> list[tuple[str, float]]:
+        """Rotate the seed vector toward a unit direction by angle theta on the unit sphere.
+
+        ``direction`` is either a supervised pole key (e.g.
+        ``"cuisine:South_Asian"``) or a raw (d_model,) np.ndarray.
+        At theta=0 the query is the seed. At theta=60deg cosine to seed = 0.5.
+        With ``exclude_seed=True`` (default) the seed ingredient is removed from results
+        (the paper's reported tables also exclude it).
+        """
+        seed_idx = self.vocab[seed]
+        v = self.E[seed_idx]
+        d = self.supervised_poles[direction] if isinstance(direction, str) else direction
+        d = np.asarray(d, dtype=np.float32)
+        d = _unit(d)
+        # Gram-Schmidt: orthogonal component of d relative to v
+        d_perp = d - (d @ v) * v
+        n_perp = np.linalg.norm(d_perp)
+        if n_perp < 1e-9:
+            # d is colinear with v: rotation has no defined plane; return seed neighbours
+            return self.neighbors(seed, k=k)
+        d_perp = d_perp / n_perp
+        theta = np.deg2rad(float(theta_deg))
+        q = np.cos(theta) * v + np.sin(theta) * d_perp
+        q = _unit(q)
+        sims = self.E @ q
+        if exclude_seed:
+            sims[seed_idx] = -np.inf
+        order = np.argsort(-sims)
+        return [(self.itos[int(i)], float(sims[i])) for i in order[:k]]
+
+    def closest_mode(
+        self,
+        name: str,
+        kind: str | None = None,
+        k: int = 3,
+    ) -> list[tuple[str, str, float]]:
+        """Return the top-k closest modes to the named ingredient.
+
+        ``kind`` filters by mode kind: 'factor', 'cuisine', 'food_group',
+        'nova_level', 'cf_sensory', 'usda_nutrient' or None for all.
+        """
+        v = self.vec(name)
+        scored = []
+        for m in self.modes:
+            if kind is not None and m.kind != kind:
+                continue
+            scored.append((m.mode_id, m.label, float(_unit(m.pole) @ v)))
+        scored.sort(key=lambda x: -x[2])
+        return scored[:k]
+
+    def mode_members(self, mode_id: str, k: int | None = None) -> list[str]:
+        for m in self.modes:
+            if m.mode_id == mode_id:
+                return m.members[:k] if k is not None else m.members
+        raise KeyError(mode_id)
+
+    # ----- introspection -----
+
+    def list_supervised_poles(self, prefix: str | None = None) -> list[str]:
+        if prefix is None:
+            return list(self.supervised_poles.keys())
+        return [k for k in self.supervised_poles if k.startswith(prefix)]
+
+    def list_modes(self, kind: str | None = None) -> list[tuple[str, str]]:
+        if kind is None:
+            return [(m.mode_id, m.label) for m in self.modes]
+        return [(m.mode_id, m.label) for m in self.modes if m.kind == kind]
+
+    def __repr__(self) -> str:
+        return (
+            f"Epicure(schema={self.config.get('schema')!r}, "
+            f"d_model={self.config.get('d_model')}, "
+            f"vocab_size={self.config.get('vocab_size')}, "
+            f"modes={len(self.modes)}, "
+            f"supervised_poles={len(self.supervised_poles)})"
+        )

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=4.40.0
+huggingface_hub>=0.24.0
+safetensors>=0.4.0
+numpy>=1.24