MyOrder Agentic Layer

MyOrder is an AI-native restaurant ordering agentic layer designed to provide a natural language interface for digital menus. It operates as a decoupled Python Sidecar, orchestrating complex ordering workflows while ensuring strict adherence to business logic and menu availability.

The MyOrder Agentic Layer follows a Session-Aware Sidecar Pattern. It is designed to sit between a customer-facing UI or a voice agent's text input and a core business API (e.g., NestJS/MongoDB).

• FastAPI Sidecar: Serves as the entry point for both REST and WebSocket communication.
• Pydantic AI Engine: Orchestrates the LLM turns, grounding the model with real-time menu context via deterministic tools.
• Session Store: Manages conversational state, allowing the agent to remember user preferences (e.g., "no onions") across multiple turns.
• Verification Pipeline: A multi-stage guardrail system that validates agent output before it reachers the execution layer.

graph TD
    subgraph "Client Layer"
        UI["Frontend UI / Voice Agent<br/>(Text Input)"]
    end

    subgraph "MyOrder Agentic Layer (Python Sidecar)"
        FAST["FastAPI Server"]
        OA["OrderAgent<br/>(Pydantic AI)"]
        SESS["Session Store<br/>(In-Memory / Redis)"]
    end

    subgraph "Business Logic Layer (External API)"
        MC["Menu Service<br/>(MenuController)"]
        OC["Order Service<br/>(OrderAppController)"]
    end

    subgraph "Data Layer (MongoDB)"
        DB[(Core Database)]
        MENUS["'menus' collection"]
        RESTS["'restaurants' collection"]
        ORDERS["'orders' collection"]
    end

    UI <--> FAST
    FAST <--> OA
    OA <--> SESS
    OA -- "fetch menu context" --> MC
    OA -- "dry-run validation (Stage 3)" --> OC
    MC --> DB
    OC --> DB
    DB --- MENUS
    DB --- RESTS
    DB --- ORDERS

This repo contains the source code for the "MyOrder Agentic Layer". The DB and backend are external to this repo.

To ensure order accuracy and prevent hallucinations, the system implements a 3-Stage Verification Pipeline:

1. Stage 1: Schema Validation (Pydantic): Ensures the LLM output conforms to the structured OrderOutput model (types, required fields, etc.).
2. Stage 2: Python Business Guardrails: A deterministic validation layer that iterates over the suggested items to verify prices, modifier compatibility, and item IDs against the current menu.
3. Stage 3: Backend API Validation: A final "dry-run" call to the external Backend API to verify absolute consistency with the database (e.g., checking if an item just went out of stock).

• Deterministic Lookup: The agent is required to use the search_menu_item tool. If a search returns no results, the agent is constrained by the system prompt to inform the user that the item is unavailable.
• Strict Grounding: Menus are injected directly into the prompt context for small-to-medium menus, ensuring the agent only "knows" what is actually on the menu.

Unlike standard stateless REST APIs, MyOrder maintains a Session-Aware Architecture:

• Message History: Full conversation logs are persisted in the session, allowing the LLM to maintain context.
• Explicit Fact Extraction: Key preferences (allergies, dislikes) are explicitly extracted and stored in the session state using specialized tools, preventing context drift in long conversations.

The chatbot interface looks like this and shows how the agent adheres to the available options, prompts user to add add-ons. Also, the verbose on right shows how agent computed the wrong total cost but the verification subagent caught it using the guardrails mentioned above!

The internal components of the agentic layer can be found in src/ai-sidecar/app:

• agents/: Pydantic AI agent definitions and logic.
• tools/: Deterministic tools used by the agent for menu lookups.
• guardrails/: Stage 2 validation logic.
• services/: Integration logic for external API communication.