agent architecture
Deep Dive
This deeper dive reframes the original Eagle AI overview as a Delectable AI platform view: model routing, function-calling orchestration, commerce tools, graph intelligence, ML personalization, retail media, governance, safety, search, research, orchestration, and the data services needed for enterprise-grade agentic commerce.
Chat, mobile, PDP, search, cart, checkout, creator content, operator console.
Tenant profile, loyalty card to mParticle resolution, session state, tool enablement.
SSE product cards, meal plan data, structured templates, analytics events.
Gemini chat session, FunctionDeclaration registry, model routing, guardrails, parallel tool calls, ranking context, result slimming.
Dietary annotation, purchase-history boost, graph affinity, session dedupe, relevance filtering.
Ingredient parsing, unit conversion, pantry deduction, package sizing, cart-ready SKU matching.
BigQuery product enrichment, recipes, purchase events, profile tables, promos, analytics.
Memgraph and BigQuery property graph for households, products, recipes, ingredients, allergens, communities.
Governance, safety policy, search abstraction, research signals, orchestration, DB, retail media, and social services.
The current implementation combines generative planning with deterministic grocery math and retrieval-backed product truth. The LLM is used for intent interpretation, planning, and response synthesis; tools own product search, profile lookup, graph traversal, cart operations, pricing, promotions, pantry, and analytics.
Gemini chat sessions receive a retailer-specific system prompt and a filtered function registry. The loop repeats until no function calls remain or the iteration guard is reached.
Ingredient consolidation, shopping-list optimization, cart management, promo checks, and SKU matching sit outside the LLM so the final commerce output is auditable.
Session propensity deltas, recommender selection, graph communities, evaluation scores, and analytics events create a feedback loop for improved ranking and planning.
The agent-facing code is only the visible execution layer. The system also depends on cross-platform modules that own durable workflows, data abstraction, search routing, safety evidence, governance evaluation, and continuous research signals.
Policy registry, runtime checks, framework registry, incidents, evaluations, and append-only evidence ledger for guardrail enforcement and compliance dashboards.
GovernanceOS provides assessment instruments, cohort scoring, NIST gap analysis, audit trail, RACI, decisions, and human review workflows.
Multi-engine search abstraction over OpenSearch, Elasticsearch, and Meilisearch, with keyword, vector, hybrid, autocomplete, taxonomy, and tenant routing.
Shared framework for LangGraph agents, durable Temporal workflows, job lifecycle management, resource optimization, rate limits, MLflow, and registry services.
Unified database abstraction across PostgreSQL, BigQuery, DuckDB, Memgraph, Cosmos DB, vector stores, schemas, retail domain models, and event loaders.
Continuous signals agent for academic feeds, regulatory updates, supplier streams, public APIs, novelty scoring, parsing, and knowledge-graph updates.
The main loop resolves identity, prefetches context in parallel, routes to the fast or deep model, executes tools, slims tool results for the LLM, retains full data for UI cards, and logs a trace for evaluation.
Tenant, retailer, model override, search backend, dietary enforcement, session ID, loyalty ID, and mParticle ID are collected before the tool loop starts.
ThreadPoolExecutor runs shopper profile, purchase history, virtual pantry, and graph prefetch together so the LLM starts with personalized context.
Product search can use the fast model. Meal planning, multi-day plans, budget constraints, family context, and complex requests route to the deeper model with more iterations.
Function calls are executed in parallel when possible. Product results pass through post-search ranking, dietary annotation, purchase matching, graph affinity, and dedupe logic.
Bulky fields are removed before results re-enter the model. Full product records and meal-plan structures still stream to the UI through SSE and structured templates.
Retrieval guardrails force catalog search when needed. The response is parsed into canonical render hints, logged to analytics, and available for LLM-as-judge evaluation.
The current code already uses intent classification and tool gating. This section turns the architecture into explicit commerce playbooks that can become runtime policy.
Best for "show me oat milk", "healthy cereal", "gluten-free pasta", and "what can I use instead of butter?" The system uses query cleaning, category anchoring, semantic search, relevance filtering, dietary annotations, and purchase-history boost.
Best for multi-day plans, family meals, recipe ideas, dietary constraints, and shopping-list generation. The agent should search recipes before synthesis, then use deterministic consolidation and optional product retrieval only when the shopper wants a shoppable plan.
Best for "build my cart", recipe-to-cart, replenishment, and budget-aware basket assembly. Deterministic cart services match ingredients to retail packages, then ranking and pricing services personalize final SKU choices.
Best for sponsored search, contextual social content, CPG-funded swaps, and creator-led discovery. These should be ranked as commerce content, with clear labels, attribution events, and incrementality measurement.
The agent exposes core and optional tools with tenant-level enablement. The most important next engineering move is to treat the tool registry as a formal product surface: versioned schemas, SLAs, auth scopes, evaluation cases, and telemetry by tool family.
| Tool family | Representative tools | Architecture role |
|---|---|---|
| Shopper context | get_user_profile get_recent_purchases save_user_preference |
Fetch and persist the declared plus inferred profile. Preference fusion follows a declared-wins rule, with inferred propensities filling gaps. |
| Catalog discovery | search_products get_product_details get_product_alternatives |
Ground answers in real products, SKUs, nutrition, allergens, and substitutions instead of model memory. |
| Recipes and plans | search_recipes create_recipe create_meal_plan modify_meal_plan |
Separate recipe retrieval from generative planning, then emit structured plan payloads for the UI. |
| Cart and lists | optimize_shopping_list build_shopping_cart manage_cart manage_shopping_list |
Perform deterministic grocery math, SKU mapping, package rounding, and session-backed commerce actions. |
| Graph reasoning | query_household_personas query_allergy_exclusions get_graph_recommendations get_ingredient_substitutes |
Use graph structure for households, communities, recipe-to-cart paths, product authority, cross-category bridges, and substitutions. |
| Monetization | get_promos_and_offers select_recommenders get_sponsored_products get_social_content |
Unify discovery, promotions, sponsored placements, and social proof without letting ads bypass relevance or safety policy. |
The platform already contains the core building blocks: batch propensity profiles, real-time session deltas, recommender orchestration, virtual pantry logic, food-science enrichment, analytics backends, and LLM-based evaluation.
Current session interactions are decayed, capped, and merged with batch propensities so search ranking can react immediately without overwriting long-term shopper truth.
A model registry selects the right carousel mix for each surface by filtering requirements, scoring relevance, and applying operator or sponsor overrides.
Product search answers "what matches this text?" Graph intelligence answers "what does this mean inside a household, recipe, basket, category, community, promotion, and safety context?"
Multi-hop traversal finds patterns such as parent, athlete, health-conscious, entertainer, and time-constrained personas inside one shared loyalty account.
User to allergen to product and ingredient paths can precompute exclusions for meal plans and explain why a recipe or SKU is unsafe.
Recipe to ingredient to product edges produce cart-ready SKUs and let propensities rerank each ingredient's product candidates.
MAGE-powered PageRank and community detection can identify shoppers with similar behavior and products with authority in a category.
Graph paths reveal products that connect categories, enabling "complete the meal", "add the missing staple", and bundle recommendations.
Vector and co-occurrence graph search support context-aware substitutions for recipe edits, dietary needs, and out-of-stock recovery.
The existing implementation already contains several reliability patterns. The next step is to make them first-class, measurable controls across tenants and surfaces.
Dietary propensity is not always a hard purchase constraint because shoppers often buy for household members, guests, parties, or gifts. The right default is rank compliant products first, annotate conflicts clearly, and only hard-filter when the user explicitly requests it or a declared allergy policy requires it.
When the model answers a catalog-grounded request without calling product or recipe search, the agent can force retrieval and ask the model to rewrite using only the returned products and recipes.
Large product and meal-plan outputs are slimmed before re-entering the LLM context. The UI still receives complete structured payloads, keeping token cost down without losing render quality.
Debug traces capture model, prompts, tool calls, durations, backends, products, and outcomes. Separate evaluator modules score per-turn and per-session quality across response quality, relevance, helpfulness, safety, and journey completion.
Policy shape to formalize:
intent + user_request + declared_constraints + inferred_profile + household_context
-> tool allowlist
-> retrieval requirement
-> ranking policy
-> annotation policy
-> evaluation rubric
-> audit eventThese recommendations build on the current codebase. I would prioritize capabilities that make the agent more reliable, measurable, and commercially useful before adding more generative surface area.
Give every grocery-agent, search, db, safety, governance, research, and orchestration contract a version, schema owner, SLA, policy class, and golden test set.
Build on the existing OR-Tools ILP / cart-optimizer path with richer MILP or CP-SAT constraint families for budgets, macros, prep time, leftovers, package sizes, pantry state, promos, inventory, and household rules.
Move session propensity, social velocity, cart events, ad events, and search interactions onto a single event stream with a feature-store contract.
Create adversarial scenarios for allergies, pregnancy, baby food, medications, alcohol, substitutions, and "shopping for someone else" ambiguity.
Inject store inventory, pick confidence, substitution likelihood, cold-chain constraints, and delivery window fit into product and cart ranking.
Go beyond last-click attribution with holdouts, uplift models, bid relevance penalties, and incrementality by mission, household, category, and creator content.
Expose compact graph paths and supporting evidence to the model and UI: household persona, allergy edge, recipe-product path, authority score, and substitute rationale.
Upgrade virtual pantry from purchase recency to household-size, product-size, consumption velocity, meal-plan usage, repeat purchase, and confidence bands.
Use OCR, image embeddings, video transcripts, and shelf-label parsing to enrich products, recipes, creator videos, and in-store discovery.
Run synthetic shoppers through thousands of policy combinations before rollout, scoring utility, safety, margin, ad load, and shopper trust.
The page content is grounded in the current grocery-agent, ML, knowledge graph, analytics, and legacy VIA ML modules. These are the highest-signal files used to shape the architecture narrative.