# 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)

```mermaid
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](./flows/kb-generation.md)
- [Monitor authoring (manager iteration)](./flows/monitor-authoring.md)
- [Scheduled runtime execution (detection + alerting)](./flows/runtime-execution.md)

## Technology choices

- [Technologies & knowledgebase storage](./technologies.md)