@soulcraft/kits 1.0.0

package/kits/gather-and-grill/skills/venue-data-model/SKILL.md

@@ -0,0 +1,336 @@
+---
+id: venue-data-model
+name: Venue Data Model
+description: Teaches the AI assistant the complete Venue platform data architecture, Brainy entity types, relationship model, and all available query APIs for building analytics and data-driven responses.
+type: background
+version: 1.0.0
+requiresVision: false
+requiresData: false
+---
+
+# Venue Data Model
+
+You are operating within the **Venue platform**, powered by **@soulcraft/brainy** — a graph-based entity store with vector search, aggregate analytics, neural clustering, and streaming APIs. This document is your complete reference for data architecture and query patterns.
+
+## Core Concepts
+
+Every piece of data is a **Brainy entity** with:
+- A `type` (the NounType — the broad category)
+- A `metadata` object (filterable, indexed fields — queryable via `where`)
+- A `data` object (full-text/vector searchable content)
+- An `id` (UUID string)
+- Relationships to other entities (directed, typed edges)
+
+**Key invariant**: Amounts are always stored in cents (integer). $75.00 = `7500`. Divide by 100 for display.
+
+**Key invariant**: Every entity scoped to a franchise location carries `metadata.locationId`. Always include this filter when querying per-location data.
+
+**Key invariant**: `Event`, `Person`, `Document`, `Measurement`, and `Thing` are the five NounTypes. Sub-entity kinds are distinguished by `metadata.entityType`. Always include the `metadata.entityType` filter when querying a specific sub-kind within a NounType.
+
+---
+
+## Entity Types Reference
+
+| NounType | `metadata.entityType` | Purpose | Key Metadata Fields |
+|---|---|---|---|
+| `Location` | `location` | Franchise kitchen studio location | `address`, `hours`, `timezone`, `stripeAccountId`, `locationId` |
+| `Product` | `experience` | Experience type / class offering | `slug`, `name`, `priceInCents`, `durationMinutes`, `minGuests`, `maxGuests`, `locationId` |
+| `Event` | `booking` | Guest reservation | `status`, `experienceSlug`, `guestCount`, `totalInCents`, `locationId`, `date`, `bookingNumber`, `checkedIn` |
+| `Event` | `time-slot` | Capacity block on the schedule | `date`, `hour`, `experienceSlug`, `capacity`, `reservedCount`, `locationId` |
+| `Event` | `audit-event` | Append-only operation log | `action`, `actorId`, `actorName`, `entityId`, `entityType`, `locationId` |
+| `Event` | `experience-memory` | Shareable post-visit cooking storybook | `bookingId`, `token`, `published`, `locationId` |
+| `Person` | `customer` | Guest profile | `email`, `displayName`, `totalBookings`, `totalSpentInCents`, `loyaltyTier`, `locationId` |
+| `Person` | `staff` | Employee record | `email`, `role`, `permissions`, `locationId` |
+| `Person` | `loyalty-account` | Points and tier balance | `customerId`, `pointsBalance`, `tier`, `locationId` |
+| `Document` | `content-page` | CMS-managed website section | `pageSlug`, `section`, `locationId` |
+| `Document` | `blog-post` | Blog article | `slug`, `title`, `status`, `tags`, `authorId`, `locationId` |
+| `Thing` | `inventory-item` | Physical supply / stock | `name`, `category`, `quantity`, `reorderThreshold`, `costInCents`, `locationId` |
+| `Thing` | `gift-card` | Digital or physical gift card | `code`, `balanceInCents`, `originalAmountInCents`, `locationId` |
+| `Measurement` | `transaction` | Revenue, expense, or refund record | `type`, `amountInCents`, `experienceSlug`, `category`, `date`, `locationId` |
+| `Measurement` | `loyalty-transaction` | Points earned, redeemed, or expired | `customerId`, `points`, `reason`, `locationId` |
+
+### Booking `status` values
+`pending` | `confirmed` | `completed` | `cancelled`
+
+### Transaction `type` values
+`revenue` | `expense` | `refund`
+
+### Booking session attributes (`data.sessionAttributes`)
+
+Each booking may carry per-session attributes set by staff. For Gather & Grill, the key attributes are:
+
+| Key | Class Types | Purpose |
+|---|---|---|
+| `dishName` | All | The dish or menu being cooked in this session |
+| `cuisineType` | Chef's Table, Quick Bites, Private Party, Date Night | Cuisine category |
+| `difficultyLevel` | Chef's Table | Beginner / Intermediate / Advanced |
+| `dietaryNotes` | Quick Bites, Private Party | Flagged dietary accommodations for this session |
+| `ageRange` | Kids Cooking Camp | Age group for the session |
+| `partyTheme` | Private Party | Client-specified theme or occasion |
+
+---
+
+## Relationships Reference
+
+Brainy relationships are directed edges with a typed verb. Query via `brain.related()` or use `brain.find()` with relationship traversal.
+
+| From Entity | Verb | To Entity | Purpose |
+|---|---|---|---|
+| `Location` | Contains | `Experience`, `TimeSlot` | What a location offers |
+| `Experience` | OccursAt | `TimeSlot` | Schedule mapping |
+| `Booking` | ParticipatesIn | `TimeSlot` | Seat reservation |
+| `Customer` | Creates | `Booking` | Ownership |
+| `Booking` | Contains | `Experience` | Line items |
+| `Transaction` | References | `Booking` | Revenue attribution |
+| `Experience` | Consumes | `InventoryItem` | COGS / supply tracking |
+| `Location` | Owns | `Transaction` | Multi-location P&L |
+| `Staff` | MemberOf | `Location` | Staff assignment |
+| `Memory` | References | `Booking` | Visit → memory link |
+
+---
+
+## Aggregate API
+
+Use `brain.defineAggregate()` to register a named aggregate, then `brain.find()` with the `aggregate` key to query it. Results are materialized and cached.
+
+### Full example — revenue by experience and month
+
+```typescript
+brain.defineAggregate('revenueByExperienceMonth', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.type', value: 'revenue' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.experienceSlug' },
+    { field: 'metadata.date', window: 'month' }
+  ],
+  metrics: {
+    totalRevenue:    { op: 'SUM',      field: 'metadata.amountInCents' },
+    bookingCount:    { op: 'COUNT' },
+    avgTicket:       { op: 'AVG',      field: 'metadata.amountInCents' },
+    maxTicket:       { op: 'MAX',      field: 'metadata.amountInCents' },
+    minTicket:       { op: 'MIN',      field: 'metadata.amountInCents' },
+    revenueStdDev:   { op: 'STDDEV',   field: 'metadata.amountInCents' },
+    revenueVariance: { op: 'VARIANCE', field: 'metadata.amountInCents' }
+  }
+});
+
+const results = await brain.find({
+  aggregate: 'revenueByExperienceMonth',
+  where: [{ field: 'metadata.locationId', value: 'loc-abc' }],
+  orderBy: 'totalRevenue',
+  order: 'desc',
+  limit: 100
+});
+```
+
+### Available aggregation operators
+
+| Operator | Description |
+|---|---|
+| `SUM` | Total of all values in the group |
+| `COUNT` | Number of entities in the group |
+| `AVG` | Arithmetic mean |
+| `MIN` | Minimum value |
+| `MAX` | Maximum value |
+| `STDDEV` | Population standard deviation |
+| `VARIANCE` | Population variance |
+
+### Available time windows for `groupBy`
+
+`hour` | `day` | `week` | `month` | `quarter` | `year`
+
+### Example — expenses by category and month
+
+```typescript
+brain.defineAggregate('expensesByCategory', {
+  source: {
+    type: 'Measurement',
+    where: [
+      { field: 'metadata.entityType', value: 'transaction' },
+      { field: 'metadata.type', value: 'expense' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.category' },
+    { field: 'metadata.date', window: 'month' }
+  ],
+  metrics: {
+    totalExpense: { op: 'SUM',   field: 'metadata.amountInCents' },
+    entryCount:   { op: 'COUNT' },
+    avgExpense:   { op: 'AVG',   field: 'metadata.amountInCents' }
+  }
+});
+```
+
+### Example — bookings by experience and day of week
+
+```typescript
+brain.defineAggregate('bookingsByExperienceDayHour', {
+  source: {
+    type: 'Event',
+    where: [
+      { field: 'metadata.entityType', value: 'booking' },
+      { field: 'metadata.status', value: 'confirmed' }
+    ]
+  },
+  groupBy: [
+    { field: 'metadata.experienceSlug' },
+    { field: 'metadata.date', window: 'day' }
+  ],
+  metrics: {
+    bookingCount: { op: 'COUNT' },
+    totalGuests:  { op: 'SUM', field: 'metadata.guestCount' },
+    avgGuests:    { op: 'AVG', field: 'metadata.guestCount' }
+  }
+});
+```
+
+---
+
+## Counts API
+
+For fast total counts without full aggregation:
+
+```typescript
+// Count all entities by NounType
+const totals = await brain.counts.byType();
+// Returns: { Location: 2, Product: 5, Event: 890, Person: 634, ... }
+
+// Count with specific criteria
+const todayBookings = await brain.counts.byCriteria({
+  type: 'Event',
+  criteria: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.date',       value: '2026-02-19' }
+  ]
+});
+// Returns: { count: 8 }
+
+// Global database statistics
+const stats = await brain.getStats();
+// Returns: { totalEntities, totalRelationships, indexedAt, storeSizeBytes, ... }
+```
+
+---
+
+## Neural API
+
+Brainy exposes ML-style operations over entity embeddings without an external model:
+
+```typescript
+// Cluster customers into behavioral segments
+const segments = await brain.neural().clusters({
+  numClusters: 5,
+  entityType: 'Person'
+});
+// Returns array of clusters, each with centroid, memberIds[], and summary stats
+
+// Detect statistical outliers (VIPs, anomalies, churn risks)
+const outliers = await brain.neural().outliers({
+  threshold: 2.5,     // Z-score threshold
+  method: 'zscore',   // 'zscore' | 'iqr'
+  entityType: 'Measurement'
+});
+
+// Find semantically similar entities
+const similar = await brain.neural().similar('entity-id-uuid', {
+  limit: 10
+});
+// Returns entities with similarity scores, ordered descending
+```
+
+---
+
+## Streaming API
+
+For large result sets or real-time feeds, use async generators:
+
+```typescript
+// Stream all entities of a NounType
+for await (const entity of brain.streaming.entities({ type: 'Event' })) {
+  // Process one entity at a time — memory-efficient for large sets
+}
+
+// Stream search results
+for await (const result of brain.streaming.search('cacio e pepe italian intermediate', { type: 'Event' })) {
+  // result.entity, result.score
+}
+```
+
+---
+
+## Tabular Export API
+
+Export entity data as CSV or OData for spreadsheet and BI tool consumption:
+
+```typescript
+import { TabularExporter } from '@soulcraft/brainy';
+
+const exporter = new TabularExporter(brain);
+
+// Export to CSV buffer
+const csv = await exporter.exportCsv({
+  type: 'Measurement',
+  where: [{ field: 'metadata.entityType', value: 'transaction' }]
+});
+
+// Export as OData JSON (compatible with Power BI, Excel)
+const odata = await exporter.exportOData({
+  type: 'Measurement',
+  where: [{ field: 'metadata.entityType', value: 'transaction' }]
+});
+```
+
+---
+
+## Standard Query Patterns
+
+### Find all bookings for a location on a date
+```typescript
+await brain.find({
+  type: 'Event',
+  where: [
+    { field: 'metadata.entityType', value: 'booking' },
+    { field: 'metadata.locationId', value: locationId },
+    { field: 'metadata.date',       value: '2026-02-19' }
+  ],
+  orderBy: 'metadata.hour',
+  order: 'asc'
+});
+```
+
+### Find inventory items below reorder threshold
+```typescript
+await brain.find({
+  type: 'Thing',
+  where: [
+    { field: 'metadata.entityType', value: 'inventory-item' },
+    { field: 'metadata.locationId', value: locationId }
+  ]
+  // Filter client-side: items where quantity <= reorderThreshold
+});
+```
+
+### Full-text + vector search
+```typescript
+await brain.search('italian pasta intermediate technique', {
+  type: 'Event',
+  limit: 20
+});
+```
+
+---
+
+## Rules Summary
+
+1. **Amounts in cents** — `7500` = $75.00. Always divide by 100 before displaying.
+2. **Always filter `metadata.locationId`** when the user's question is about a specific studio location.
+3. **Always include `metadata.entityType`** when querying Event, Person, Document, Thing, or Measurement sub-kinds.
+4. **Use aggregates for analytics** — don't load all entities and sum client-side.
+5. **Use `brain.neural().clusters()`** for customer segmentation, never hard-code segments.
+6. **Never write files directly to brainy-data/** — all data mutations go through `brain.add()`, `brain.update()`, `brain.relate()`.