The
libs/hestia/area: fourteen Nx libraries that implement Hestia, the culinary-intelligence platform — from a shared domain core through ingredient science, nutrition, recipes, an Epicure-style embedding engine, and the kitchen/social/education surfaces built on top.
What this area is#
Hestia (named for the Greek goddess of the hearth) is Oshun's culinary domain,
and libs/hestia/ is where its logic lives — not as one package but as
fourteen separate Nx libraries, each tagged scope:hestia, layer:domain,
type:lib. Every project is a @nx/js:tsc-built TypeScript library with its
own src/index.ts barrel, its own vitest.config.ts, and a co-located
*.spec.ts beside every module. These are substantial, fully-implemented
libraries (the larger ones — ai-ml, education, social, professional,
sustainability — run to 22–25k lines of source-plus-tests each); none of the
fourteen is an empty scaffold.
The area is layered. @hestia/core sits at the bottom as the shared foundation:
measurement/temperature conversions (types.ts, volume anchored on ml, weight
on grams), the pure-TypeScript domain schemas and validators (schemas.ts, no
Zod runtime), a Drizzle ORM PostgreSQL schema of ~20 tables (db-schema.ts), a
domain-event system with an EventStore/EventBus/projections/upcasters
(events.ts), and the authorization model (auth.ts). The other thirteen
libraries import their domain types from @hestia/core — for example
@hestia/recipes imports Recipe/RecipeIngredient, @hestia/nutrition
imports NutritionInfo/MineralProfile, and @hestia/pantry imports
IngredientCategory.
On top of that core sit two tiers: a data-and-intelligence tier
(ingredients, nutrition, recipes, ai-ml) that owns the heavy domain
modelling, and a experience tier (cooking, meal-planning, pantry,
smart-kitchen, professional, social, education, heritage,
sustainability) that builds user- and operator-facing features on top of the
data tier. The standout node is @hestia/ai-ml, which implements an
Epicure-style ingredient-embedding pipeline (typed heterograph → metapath2vec
random walks → skip-gram with negative sampling → orthogonal-Procrustes
alignment to sensory axes → WEAT bias tests) in pure TypeScript.
How it fits the wider system#
The dependency edges inside the area are deliberately one-directional and mostly
flow through @hestia/core. Where a cross-library dependency would otherwise be
heavy — notably between @hestia/ingredients and @hestia/ai-ml — the code
uses a structural (duck-typed) interface instead of a package import:
@hestia/ingredients/src/pairing.ts declares a VectorSimilarityLookup
interface that ai-ml's EmbeddingStore happens to satisfy, so pairing.ts
and substitution.ts can consume trained embeddings without ingredients/
taking a hard dependency on ai-ml/. That keeps the intelligence engine
optional: the pairing and substitution engines work from curated rules alone and
gain embedding-powered recall only when a trained model is injected.
Consumers outside the area import the public barrel of whichever capability they
need — @hestia/recipes for recipe modelling and scaling, @hestia/nutrition
for analysis and allergen handling, @hestia/professional for
commercial-kitchen HACCP/menu-costing, and so on. Walk the "used by" edges on
any node below to see exactly who depends on it.
Entity catalog (14)#
The 14 tracked Nx projects in hestia, each a code-linked entity node — package, type, source path, declared targets, and its internal dependency graph (depends-on / used-by, resolved from the package manifests, §6/§8), read from the project graph. Grouped by architectural layer; walk the dependency links to travel the system. 14 of these carry an authored deep-dive (what / why / how it fits); the rest are generated scaffolds awaiting one.
domain (14)#
The machine-learning engine and the most algorithm-dense node in the area
(libs/hestia/ai-ml/src). Alongside recipe-generation, flavor-pairing,
image-recognition, recommendations, nlp, and predictive-analytics, it
implements a full Epicure-style ingredient-embedding pipeline in pure
TypeScript: rng (deterministic seeded RNG), embeddings (vectors +
cosine/similarity primitives), heterograph (a typed graph with CHEM / CHEM_CAT
/ COOC metapaths), metapath2vec (typed random walks feeding skip-gram with
negative sampling), procrustes (closed-form orthogonal-Procrustes alignment of
the embedding space to sensory axes via Jacobi-rotation SVD), bias-evaluation
(WEAT effect size plus a non-parametric permutation-test p-value), and
epicure, which orchestrates these into a trained model holding three lenses —
Chem, Cooc, and Core — supporting similarity, nearest-neighbor, bridge
discovery, and Mikolov-style 3CosAdd analogy. The module comments tie each piece
back to the Epicure paper's method and ablation tables.
The active-cooking surface (libs/hestia/cooking/src): guided-cooking
(step-by-step sessions), timers, a voice interface (command parsing for
next/previous/repeat/timer/quantity/substitute intents, TTS formatting, and
eight-language support — en/es/fr/de/it/ja/zh/ko), doneness guides
(temperature ranges, visual cues, and touch tests across
meat/bread/egg/vegetable/sauce/ caramel/dough/emulsion categories),
techniques, and a session-log.
The shared foundation every other Hestia library builds on
(libs/hestia/core/src). It bundles five modules behind one barrel:
schemas.ts (pure-TypeScript domain interfaces, enums like MeasurementUnit,
and validation functions — deliberately no Zod runtime dependency), types.ts
(the measurement and temperature conversion system, anchored on millilitres for
volume and grams for weight, plus equipment/user/household types),
db-schema.ts (Drizzle ORM PostgreSQL definitions — roughly 20 pgTables with
enums, indexes, and relations), events.ts (a DomainEvent base with an
EventStore, EventBus, projections, versioned upcasters, and notifications),
and auth.ts (RecipeVisibility, roles, permissions, household sharing, and
API-key scopes). Most other libraries in the area import their domain types from
here.
The culinary-education platform (libs/hestia/education/src): a techniques
library, a gamified progression system (skill trees, XP, badges with rarity
tiers, challenges with weighted criteria, assessments, and personalized learning
paths across the novice→apprentice→journeyman→expert→master skill levels), a
food-science curriculum (courses on the Maillard reaction, caramelization,
protein denaturation, starch gelatinization, emulsions, gluten, fermentation,
etc., with diagrams and temperature-curve data), world-cuisine deep-dives,
certifications, and interactive learning features.
The cultural-heritage preservation library (libs/hestia/heritage/src):
family-recipes digitization, an oral-history module (audio/video recording
configs, transcription engines including whisper, guided interviews,
story-to-recipe linking, timeline visualization, geographic-origin and migration
tracking, language preservation, and cross-generation sharing), a
regional-archive, food-history research, and a community contribution
surface.
The ingredient-intelligence library (libs/hestia/ingredients/src). Its modules
cover a master-database, per-ingredient nutrition, a flavor-compounds
database that models Maillard products, fermentation products, and compound
interactions (synergy/suppression/enhancement) with detection thresholds in ppm,
a pairing engine scoring from traditional cuisine pairings plus
flavor-compound overlap, a substitution engine
(allergen/dietary/budget/functional subs), seasonality, and a multilingual
lexicon with a deterministic canonicalization pipeline modelled on Epicure's
LLM-assisted normalization. Both pairing.ts and substitution.ts accept an
optional VectorSimilarityLookup (duck-typed to @hestia/ai-ml's
EmbeddingStore) to add embedding-based similarity, k-NN, and bridge-ingredient
discovery without a hard dependency on the ML library.
Meal-planning and household coordination (libs/hestia/meal-planning/src):
calendar, household, recipe suggestions, a budget optimizer (cost
estimation, spending tracking, bulk-buying, coupon management, budget-friendly
substitutions, and budgeted-vs-actual comparison), batch-cooking, and an
events module. It imports Recipe from @hestia/core.
Nutrition analysis and dietary management (libs/hestia/nutrition/src), built
on @hestia/core's NutritionInfo/MineralProfile/VitaminProfile types. It
exposes analysis, a bioavailability model (absorption factors with
enhancers/inhibitors, cooking-retention factors, nutrient–nutrient interactions,
and personalized adjustments by age/sex/condition), dietary management, an
allergen system (detection, hidden-allergen flagging, cross-contamination
warnings, severity from mild to anaphylactic, multi-person tracking),
medical-diet support, and personalized goals.
Pantry and inventory management (libs/hestia/pantry/src): inventory,
barcode/receipt scanning, expiration management (tiered alerts
info→warning→urgent→expired, FIFO ordering, waste tracking by reason, and recipe
suggestions for expiring items), shopping, grocery-store integration, and
equipment. It imports IngredientCategory from @hestia/core.
The commercial-kitchen / foodservice library (libs/hestia/professional/src):
menu-costing (ingredient cost database with price history, recipe costing,
food cost %, pricing suggestions, margin analysis, supplier comparison, and menu
engineering), kitchen-workflow, inventory-management, a food-safety module
implementing HACCP (plan builder, critical-control-point tracking, temperature
logging, corrective actions, sanitization verification, audit trails, and health
inspector reports), catering-events, and recipe-development.
Recipe management (libs/hestia/recipes/src), built on the Recipe/
RecipeIngredient/Instruction types from @hestia/core. Modules: a
recipe-model, a parsing engine (ingredient-line parsing with a large
unit-alias normalization map, plus quantity/prep/instruction/time/temperature/
equipment extraction), import-export, a scaling engine with category-aware
rules (linear for most ingredients, sublinear factor^0.7 power-law for spices,
factor^0.8 for leavening, plus cooking-time/temperature and pan-size
adjustments), versioning, search, and collections.
The IoT / connected-appliance layer (libs/hestia/smart-kitchen/src): a generic
devices model, cooking-devices, sensors, smart-appliances, automation
workflows, and an orchestration module that schedules a multi-device cooking
plan (building an ExecutionPlan of timed per-device steps, tracking
CookingProgress, and powering a kitchen dashboard).
The culinary social network (libs/hestia/social/src): recipe-sharing,
profiles-following, ratings-reviews (1–5 ratings with optional sub-scores
for taste/difficulty/presentation/value/accuracy, photo reviews, helpful votes,
moderation, review responses, aggregation, and verification),
cook-alongs-events, family-cookbook, and community-challenges.
The environmental-impact library (libs/hestia/sustainability/src): a
carbon-footprint calculator (a FoodCategory enum from meat through processed
foods, a TransportMode enum, and supply-chain modelling), food-waste
tracking, ethical-sourcing, seasonal-local guidance, and composting.