Ingestion Agent

Category: Signal Acquisition · Execution Model: Stateless, Write-Once, Append-Only

Purpose

The Ingestion Agent serves as the primary intake layer for raw cultural, trend, and velocity signals entering the Whook ecosystem. It captures early-stage demand indicators from external sources such as search trends, social velocity, and event marketplaces, preserving them in a minimally processed form for downstream interpretation, research, and orchestration by higher-order agents.

Expected Inputs

query string (required)
Search term, cultural concept, or signal identifier being ingested. Examples include activities, experiences, or emerging cultural themes.
region string — default: Los Angeles
Geographic context used to localize trend signals. Defaults to Los Angeles if not specified.

Outputs

HTTP Response

{
  "success": "boolean",
  "record": "IngestedData"
}

Side Effect
```
Writes a new IngestedData document
```

Side Effect

Persists rawPayload for future reprocessing

Responsibilities

Accept raw trend queries and regional context
Ingest early-stage cultural and demand signals
Preserve unmodified source payloads for traceability
Store time-series ingestion records for longitudinal analysis
Provide a stable ingestion interface for external data sources

Lifecycle

Receive ingestion request with query and region
Fetch or accept raw trend indicators (mock or real sources)
Optionally map or sanitize role-specific fields
Persist ingestion record to database
Expose stored signal for downstream agents

Downstream Dependencies

Deep Research Agent
Trend Correlation Agent
Orchestrator Agent
Sanitize Agent

Guarantees

Stateless execution
No mutation of previously ingested records
Safe for replay and backfill operations

Failure Model

If ingestion fails due to validation or persistence errors, the agent returns a 500 response with error details and does not partially write state. Malformed requests lacking required fields are rejected.

Internal State

{
  "persistence": [
    "ingesteddatas"
  ],
  "guarantees": [
    "No destructive updates — ingestion is append-only",
    "Raw payloads are preserved without transformation",
    "Each ingestion is timestamped"
  ]
}

Sample cURL


curl -X POST https://api.whook.ai/api/ingest/trends \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Outdoor Yoga",
    "region": "Los Angeles County"
  }'