01

Propensity and signal routing

The chat-service fast signal router is already a useful production pattern: rules fire in the foreground, deep signal detection runs asynchronously, and downstream services receive standardized user.signal.detected events.

chat-serviceKafkaprofile

Current evidenceFast rule engine classifies product_search, cart, preferences, recipe, general_chat, and unknown.chat-service/app/services/signal_router.py

Runtime behaviorForeground route_signal emits events; deep signal detection can run via background LLM stream.chat-service/app/api/action_selector_stream.py

Next capabilityMove from regex-only categories to a feature-store-backed session propensity vector with online decay.

GuardrailSeparate declared dietary hard rules from inferred preferences and log every override reason.

02

Householding and graph de-averaging

The graph story should emphasize household conflict resolution: one loyalty card can encode multiple people, missions, and dietary intents.

GNNgraphpersonas

Current evidenceGraph explorer and client demos already show product, shopper, event, and recommendation graph patterns.knowledge-graph/ · demo/public-giant-eagle/

Runtime behaviorUse co-purchase, recipe, cart, and dietary signals to infer separable clusters behind one account.

Next capabilityAdd persona confidence and "shopping for others" detection to ranking and annotations.

GuardrailNever hard-filter ambiguous household purchases unless the shopper or policy declares a hard safety rule.

03

Recommender orchestration

The platform should formalize the "model-of-models" as a contract: candidate generator, ranker, policy filter, business objective, and evidence block.

rankersurfacemission

Current evidenceCommerce docs describe direct domain functions and one shared library consumed by grocery-agent, chat-service, and console.commerce/docs/TECHNICAL.md

Runtime behaviorSpecialized models should compete by context: mission, surface, shopper state, inventory, promotion, and policy.

Next capabilityAdd a typed recommendation envelope with model id, evidence, objective weights, suppression reasons, and replay id.

GuardrailKeep paid placement, retailer strategy, and shopper utility separate in the scoring trace.

04

Food intelligence data plane

The food layer is not just catalog enrichment. It is a multi-source scientific feature store that normalizes nutrients, dietary flags, ingredients, health scores, embeddings, recipe bridges, and Vertex-ready product attributes. Direct BigQuery metadata confirms the production scale.

BigQueryVertex AIfood science

SKU feature store70,472 Giant Eagle SKUs flow through a 102-field enriched table and a 70-field cleaned table with nutrients, per-100g fallbacks, Food Compass, NOVA, Nutri-Score, dietary flags, nutrient density, and internal health rank.giant_eagle_enriched · cleaned_food_intelligence

Vertex ingestionvertex_ingestion_ready holds 4.7M GTIN/UPC enrichment rows with ingredients, dietary claims, allergens, scientific profile, health tier, Nutri-Score, NOVA, and Food Compass score.food_intelligence.vertex_ingestion_ready

Semantic bridge2.1M recipes produce 223,062 normalized ingredients and embeddings, then 595,878 ingredient-product bridge rows for top-SKU matching with cosine similarity and confidence tiers.recipe_ingredients_normalized · ingredient_product_bridge

Embedding modelThe deployed BigQuery remote model is text_embedding_005, backed by Vertex AI text-embedding-005 in us-central1. Repo DDL still references the older text_embedding_model name, so the docs should note this drift.food_intelligence.text_embedding_005

Food science corpusThe molecular/science layer is real in BigQuery: 4.3M Open Food Facts rows, 454K USDA branded foods, 70K chemical compounds, 5.1M food-compound content rows, and FooDB/CIQUAL reference tables.open_food_facts · chemical_compounds · food_compound_content

Graph projectionFood intelligence syncs to the knowledge graph as SKU, Brand, Department, DietaryLabel, and Ingredient nodes with nutrition, scoring, and ingredient relationships.knowledge-graph/src/knowledge_graph/sync/food_intel.py

05

Retail analytics and behavioral intelligence

The retail layer supplies the agent with behavior, session telemetry, purchase history, mission clustering, propensity, pantry, co-purchase, promotion, and performance signals that make recommendations measurable and personalized.

retail_analyticsbehaviormeasurement

Event spinege_shopping_events holds 6.5M events with MPID, session, store, action type, basket total, SKU, quantity, price, brand, and four department levels. This is the raw behavior substrate.retail_analytics.ge_shopping_events

Mission modelge_mission_clusters is a BigQuery ML K-means model with six clusters and 25 features across time, basket size/value, department diversity, and department mix. It trained in five iterations.retail_analytics.ge_mission_clusters

Cluster outputsge_session_missions contains 193,119 session feature vectors; ge_session_clusters contains 196,671 scored sessions with mission_cluster and cluster_distance. ML.EVALUATE returns mean squared distance 19.75 and Davies-Bouldin 2.26.ge_session_missions · ge_session_clusters

Shopper profilege_user_propensity_profiles has 9,366 shopper profiles with primary mission, mission mix, preferred day/hour, stores, basket stats, dietary purchase shares, likely restriction flags, health score, top products, and recency JSON.grocery-agent/grocery/tools/bq.py

Behavioral assetsThe same retail plane includes 344,781 virtual pantry rows, 1.3M co-purchase affinity edges, 69,902 department-affinity rows, and 22,853 promotion rows for contextual offers.ge_virtual_pantry · ge_co_purchase_affinity · ge_promotions

Telemetry substrateThe reusable analytics package defines analytics_* searches, selections, conversations, sessions, and traces; the grocery agent keeps eagle_ai_* equivalents for agent-specific observability and governance joins.analytics/src/analytics/events/tables.py · grocery/analytics/analytics_logger.py

06

Perfect cart, ILP, and package optimization

The existing cart optimizer is a moat because it turns recipe quantities into retail package decisions using math instead of model prose.

OR-ToolsILPcart

Current evidencesolve_optimal_packages imports OR-Tools, minimizes effective package cost, and accounts for private label, history, brand affinity, and bulk efficiency.grocery-agent/grocery/tools/shopping_optimizer.py

Runtime behaviorOptimize-cart consolidates ingredients, searches Vertex Commerce, reranks non-ILP ingredients, and skips LLM reranking for ILP items.grocery-agent/grocery/tools/OPTIMIZE-CART-API.md

Next capabilityAdd solver profiles for weekly meal plan feasibility, multi-store constraints, B2B pack/case ordering, and promo bundle arbitration.

GuardrailExpose solver status, infeasible constraints, objective weights, and fallback choices in the A2UI trace.

07

Commerce domain library and protocols

Commerce is the right place for shared business semantics: profile, pantry, cart, pricing, inventory, orders, fulfillment, payment, and protocols.

A2AMCPA2UIUCP

Current evidenceA2A exposes build_cart, search_products, profile, pantry, inventory, pricing, alternatives, meal plans, promotions, and social commerce.commerce/src/commerce/protocols/a2a.py

Runtime behaviorMCP tools register optimize_cart, profile, pantry, product search, and promotions for model/tool clients.commerce/src/commerce/protocols/mcp.py

Next capabilityVersion every protocol response, bind it to JSON Schema, and add golden fixtures for agent regression tests.

GuardrailSeparate tenant/customer data boundaries, especially for UCP gateways deployed inside customer projects.

08

Chat streaming and A2UI eventing

The chat-service platform already has the service split for real-time response delivery: cloud API, log consumer, stream service, orchestrator, admin UI, SDK, and consumer UI.

SSEKafkaA2UI

Current evidencePlatform README names chat-cloud-service, chat-cloud-logger-service, chat-stream-service, chat-orchestrator-service, SDK, and UI.chat-service/platform/README.md

Runtime behaviorStreaming endpoints schedule background actions, emit stream completion, and can trigger product search streams when signals are detected.

Next capabilityStandardize A2UI events for solver progress, retrieval trace, evaluation status, and user-visible confidence labels.

GuardrailPersist streaming completion and action traces so partial failures are auditable, not just visible in logs.

09

Safety, governance, and evaluation

The internal story should tie governance and safety to action release, not just prompt policies. The agent should carry policy class, evidence, and evaluator result with every sensitive action.

safetygovernanceeval

Current evidenceSupport repos named by the platform include governance, safety, research, orchestration, DB, and search.governance/ · safety/ · orchestration/ · db/

Runtime behaviorHard rules should catch allergens, PII, medical-adjacent claims, alcohol, child safety, and policy violations before LLM judge stages.

Next capabilityAdd a domain red-team suite for allergies, pregnancy, medication conflicts, baby food, alcohol, and shopper-for-others ambiguity.

GuardrailGate model upgrades on eval packs and require signoff for safety-sensitive prompt/tool contract changes.

10

Recipe-to-cart and deterministic parsing

This path is where agent credibility is won or lost: ingredient parsing, canonicalization, product matching, sizing, pantry deductions, and alternatives must be deterministic and explainable.

recipeparserSKU

Current evidenceOptimize-cart docs cover consolidation, SKU matching, LLM reranking for non-ILP items, ILP optimization, and personalization.grocery-agent/grocery/tools/OPTIMIZE-CART-API.md

Runtime behaviorStructured quantity/unit inputs work directly; older embedded quantity text is parsed for backward compatibility.

Next capabilityAdd a learned ingredient NER fallback, but keep the final cart math and sizing deterministic.

GuardrailPreserve raw ingredient text, source recipe, sizing method, and matched SKU explanation for every line.

11

Legacy VIA agent framework

The legacy framework still has relevant structure: BaseAgent capability registration, AgentMessage format, LLM provider abstraction, global routing, hub registration, and grocery intent routing.

via/agentsroutinghubs

Current evidenceBaseAgent defines capabilities, message history, provider selection, tool execution, and LLM call abstraction.via/agents/base_agent.py

Runtime behaviorGlobalAgent routes by keyword/patterns to hubs including grocery, governance, product, analytics, data operations, and infrastructure.via/agents/global_agent.py

Next capabilityPort only the useful abstractions into commerce protocols and current runtime; avoid reviving legacy routing as-is.

GuardrailKeep one source of truth for capability manifests so A2A, MCP, API docs, and UI traces do not drift.

12

Search, research, and knowledge graph support plane

The agent depends on non-agent support services for high-quality answers: search abstraction, DB access, research signals, graph context, orchestration, governance, and safety.

searchresearchgraph

Current evidenceSupport repos are already named as part of the agent foundation and should be first-class in the architecture view.search/ · research/ · knowledge-graph/ · db/

Runtime behaviorSearch and graph produce grounded candidates; research and DB feeds bring fresh external and internal signals.

Next capabilityCreate a shared evidence object so every search, graph, DB, and research hit can be replayed and evaluated.

GuardrailMark freshness, source class, tenant boundary, and confidence on every piece of evidence.