Agent System Architecture (Restaurant Monitoring & Anomaly Detection)

This repository will contain an LLM-driven monitoring system that helps restaurants detect ad-hoc operational and financial anomalies (POS, KDS, inventory, etc.) from manager-written prompts.

Key constraints / principles:

• Non-technical authoring: managers describe what they want to monitor in natural language.
• Ad-hoc detection: the system should detect issues that were not explicitly “pre-modeled”.
• Per-store baselines (for now): anomalies are judged relative to the store’s own history.
• Two processes:
• Authoring: a manager iterates with AI to create/approve a MonitorSpec.
• Runtime: a scheduler executes the approved MonitorSpec and emits alerts.
• Knowledgebase-driven feasibility: each restaurant can have different available data; the system should identify missing data and suggest what’s needed.
• Alert output contract (tool call payload): Name, Summary, Content (Markdown), Severity (High | Medium | Low).

Core artifacts (contracts)

• MonitorSpec: versioned, executable “monitor definition” created during authoring and consumed at runtime.
• Capabilities Manifest: per-restaurant structured catalog of available entities/tables/joins/units/freshness.
• KPI Catalog: KPI definitions and targets extracted from restaurant manuals/SOPs.
• Doc Index (RAG): searchable text passages (vendor docs, manuals) used only as supporting context.
• Run History / Dedupe Memory: records of executions + emitted alerts to reduce noise.

Agents (responsibilities)

• Orchestrator: coordinates other agents; persists and loads MonitorSpec; aggregates final decisions.
• Spec Builder (LLM): manager-facing; converts vague prompts into a MonitorSpec and iterates until approved.
• KB / Semantic Agent: answers “what data exists?”, “what does this mean?”, “how do I join these?”, “what KPIs apply?” using the knowledgebase artifacts.
• Data Access Agent (MCP/tools): executes read-only queries; returns feature panels (aggregates/distributions/cohorts) and “data missing” diagnostics.
• Runtime Detector (LLM): executes the MonitorSpec as an adaptive runbook (broad scan → drilldowns → hypothesis checks).
• Critic / Verifier (LLM): challenges conclusions; blocks alerts without sufficient evidence (baseline validity, sample sizes, missing-data checks, etc.).
• Alert Emitter: performs dedupe and calls the external alert tool with the required payload.

Full system flow (authoring + runtime + KB generation)

flowchart TD
  %% Shared stores/sources
  W["Warehouse DB(s)"]:::store
  SPEC["MonitorSpec Store (versioned)"]:::store
  CM["Capabilities Manifest (per restaurant)"]:::store
  KPI["KPI Catalog (from manuals)"]:::store
  DOC["Doc Index (RAG)"]:::store
  MEM["Run History + Dedupe Memory"]:::store

  classDef store fill:#f6f8fa,stroke:#9aa4b2,color:#111;

  subgraph KBGEN["KB Generation (one-time + ongoing updates)"]
    INP1["DB schemas + vendor docs"] --> KBI["KB Ingestion/Profiler"]
    INP2["Restaurant manual / SOP"] --> KBI
    KBI --> CM
    KBI --> KPI
    KBI --> DOC
  end

  subgraph AUTHOR["1) Manager authoring / iteration"]
    M["Manager"] <--> SB["Spec Builder (LLM)"]
    SB <--> ORCH_A["Orchestrator"]
    ORCH_A <--> SEM_A["KB/Semantic Agent"]
    SEM_A --> CM
    SEM_A --> KPI
    SEM_A --> DOC
    ORCH_A <--> DA_A["Data Access Agent (MCP/tools)"]
    DA_A --> W
    ORCH_A --> SPEC
    SB <--> SPEC
    M -->|"Approve + enable"| SPEC
  end

  subgraph RUNTIME["2) Scheduled execution + alerting"]
    SCH["Scheduler"] --> ORCH_R["Run Orchestrator"]
    ORCH_R -->|"Load spec"| SPEC
    ORCH_R --> DET["Runtime Detector (LLM)"]
    DET <--> SEM_R["KB/Semantic Agent"]
    SEM_R --> CM
    SEM_R --> KPI
    SEM_R --> DOC
    DET <--> DA_R["Data Access Agent (MCP/tools)"]
    DA_R --> W
    DET --> CRIT["Critic/Verifier (LLM)"]
    CRIT -->|"Needs more evidence"| DET
    CRIT -->|"Alert approved"| EMIT["Alert Emitter"]
    EMIT --> TOOL["Alert Tool Call<br/>Name • Summary • Content(MD) • Severity"]
    TOOL --> NOTIF["External notification system"]
    ORCH_R --> MEM
    EMIT --> MEM
  end

Flow documents

• KB generation
• Monitor authoring (manager iteration)
• Scheduled runtime execution (detection + alerting)

Technology choices

• Technologies & knowledgebase storage