Supply Scraper Agent

Category: Supply Discovery · Execution Model: Deterministic, I/O-Bound, Append-Only

Purpose

The Supply Scraper Agent discovers and ingests real-world supply signals by scanning public event platforms for existing classes, venues, and instructor-led experiences. It establishes empirical visibility into where supply already exists, what formats are being offered, how they are priced, and which venues and instructors are active in a given region. This agent grounds downstream scheduling, vetting, and feasibility logic in observed supply rather than hypothetical availability.

Expected Inputs

query string — default: fitness
The category or activity to search for existing supply. Examples: "yoga", "HIIT", "boxing", "pilates".
region string — default: Los Angeles County, CA
Geographic region used to scope supply discovery and venue inference.

Outputs

HTTP Response

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

Side Effect
```
Writes RawEvent documents
```
Side Effect
```
Writes RawDemandSignal documents
```

Side Effect

Triggers Sanitizer Agent with generated supply chunk

Responsibilities

Accept a category or activity query and target region
Scrape public event platforms for existing classes and experiences
Extract venue, instructor, pricing, and scheduling signals
Persist raw supply events for audit and refinement
Persist associated demand signals inferred from supply density
Trigger sanitizers of scraped events into Whook-compatible chunks

Lifecycle

Receive query and region parameters
Scrape or simulate supply events from public platforms
Persist raw events into RawEvent collection
Persist inferred demand signals into RawDemandSignal collection
Transform raw events into preliminary Whook-style session items
Auto-trigger Sanitizer Agent for validation and normalization
Return ingestion summary to caller

Downstream Dependencies

Sanitizer Agent
Venue Intelligence Agent
Instructor Vetting Agent
Scheduler Agent

Guarantees

All raw supply data is preserved for audit and reprocessing
Scraped events are timestamped at ingestion time
Sanitizer receives only internally constructed supply chunks

Failure Model

If scraping or persistence fails, the request returns a 500 error. Partial ingestion is possible (e.g., some events saved before failure), but sanitizer triggering is skipped if chunk generation fails. No downstream agents are invoked directly beyond the Sanitizer.

Internal State

{
  "persistence": [
    "RawEvent",
    "RawDemandSignal"
  ],
  "derivedArtifacts": [
    "Preliminary Whook-style session chunks"
  ],
  "constraints": [
    "Append-only ingestion",
    "No mutation of raw scraped records",
    "Sanitizer is authoritative for downstream validity"
  ]
}

Sample cURL


curl -X POST https://api.whook.ai/v1/agent/supply-scraper/run \
  -H "Content-Type: application/json" \
  -d '{
    "query": "yoga",
    "region": "Los Angeles County, CA"
  }'