Category Trends Agent

Category: Knowledge Aggregation · Execution Model: Deterministic, Batch-Oriented, Append-Only

Purpose

The Category Trends Agent aggregates normalized experiential events into weekly, city-level category trend metrics. It transforms individual session-level signals into macro indicators of category momentum, pricing behavior, attendance density, and growth rate. These aggregated signals serve as a core input for downstream learning, geospatial heat mapping, demand pooling, and strategic expansion decisions.

Expected Inputs

weekOverride ISODate
Optional override for the aggregation window. If omitted, the agent aggregates events for the current calendar week.

Outputs

HTTP Response

{
  "success": "boolean",
  "message": "string",
  "inserted": "number"
}

Side Effect
```
Reads from events_normalized collection
```

Side Effect

Writes CategoryTrend documents to category_trends collection

Responsibilities

Aggregate normalized events by category and city
Compute weekly category-level demand metrics
Calculate average price and attendance per category
Estimate week-over-week growth rates
Persist immutable category trend snapshots
Provide structured trend signals for learning and scoring agents

Lifecycle

Determine current weekly aggregation window
Fetch normalized events created during the week
Group events by (category + city)
Compute aggregate metrics and averages
Compare results against prior week trends
Persist category trend documents
Return aggregation summary to caller

Downstream Dependencies

GeoHeat Agent
Demand Pool Agent
Trend Fusion Agent
Learning Agent
Market Scouter Agent

Guarantees

Each aggregation run writes immutable weekly snapshots
No historical trend documents are mutated
Growth rates are computed deterministically
Category and city labels are preserved exactly as ingested

Failure Model

If no normalized events are found for the aggregation window, the agent exits successfully without writing any records. If database access fails or aggregation errors occur, the agent returns a 500 response and no partial trend documents are persisted.

Internal State

{
  "persistence": [
    "events_normalized",
    "category_trends"
  ],
  "aggregationRules": [
    "Weekly window (startOfWeek → endOfWeek)",
    "Grouping key = category + city",
    "Append-only trend records"
  ]
}

Sample cURL


curl -X POST https://api.whook.ai/v1/agent/trends/run \
  -H "Content-Type: application/json"