# Flow: Knowledgebase (KB) Generation

The KB generation subsystem builds and maintains **restaurant-specific knowledge** that makes monitors feasible and explainable across heterogeneous data sources.

Primary objectives:

- Discover and document **what data exists** for a restaurant.
- Create a structured **Capabilities Manifest** (entities, joins, units, freshness).
- Extract restaurant **KPIs/targets** from manuals/SOPs into a KPI catalog.
- Index documentation for retrieval (RAG) without flooding runtime context.

## Sub-diagram

```mermaid
flowchart TD
  INP1["DB schemas / metadata<br/>(DDL, information_schema)"] --> PROF["Schema Profiler"]
  INP2["Vendor docs / schema docs"] --> PROF
  INP3["Restaurant manual / SOP"] --> KPIX["KPI Extractor"]

  PROF --> MAP["Entity + Join Mapper"]
  MAP --> CM["Capabilities Manifest<br/>(per restaurant)"]

  KPIX --> KPI["KPI Catalog<br/>(metric definitions + targets)"]
  KPIX --> DOC["Doc Index (RAG)<br/>(manual passages)"]
  PROF --> DOC

  classDef store fill:#f6f8fa,stroke:#9aa4b2,color:#111;
  class CM,KPI,DOC store;
```

## Outputs (what other agents rely on)

- **Capabilities Manifest**
  - Entities available (Orders, LineItems, Stations, Purchases, etc.)
  - Verified join paths (with confidence + example joins)
  - Column semantics (units, timezones, money, durations)
  - Freshness/latency markers (watermarks, update cadence)
  - Data-quality profile (null rates, distinct counts, typical grains)
- **KPI Catalog**
  - KPI name, definition, target, exceptions (dayparts, service levels)
  - “Operational intent” phrasing that can be referenced in `MonitorSpec`
- **Doc Index (RAG)**
  - Source passages for “explain why / where this came from”
  - Used as supporting context, not as the source of truth for schema facts

## Notes / guardrails

- Prefer **structured** outputs (manifest + KPI catalog) for “facts”; use RAG for “supporting text”.
- Track versions: KB artifacts should be versioned per restaurant so monitor specs remain interpretable over time.