Sanitize Agent

Category: Normalization & Validation · Execution Model: Deterministic, Stateless, Idempotent

Purpose

The Sanitize Agent is responsible for transforming raw, untrusted JSON payloads produced by LLMs and scraper agents into a normalized, economically-evaluated, and schema-safe format suitable for downstream scoring, scheduling, and launch decisions. It acts as the system’s primary integrity gate — enforcing defaults, validating structure, computing financial viability, and preventing malformed or hallucinated data from propagating through the Whook pipeline.

Expected Inputs

meta object (required)
Metadata describing the context of the chunk. Includes region, discovery assumptions, and chunk-level parameters.
items array (required)
Array of raw event or session objects generated by LLMs or supply scrapers. Each item may be incomplete or partially hallucinated prior to sanitization.

Outputs

HTTP Response

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

Side Effect

Writes NormalizedEvent documents to events_normalized collection

Side Effect

Rejects malformed chunks with 400-level validation errors

Responsibilities

Validate presence of required top-level schema fields (meta, items)
Normalize and default missing metadata values
Clean and standardize AI-generated text fields
Compute revenue, cost, and gross margin when missing or incomplete
Apply deterministic launch readiness classification
Reject malformed or structurally invalid payloads
Persist sanitized events into the normalized events collection

Lifecycle

Receive raw JSON chunk from upstream agent
Validate required schema structure
Apply metadata defaults and consistency checks
Normalize and enrich each item deterministically
Compute unit economics and gross margin
Assign launch readiness classification
Persist sanitized output for downstream agents

Downstream Dependencies

Scoring Agent
Profitability Agent
Scheduler Agent
Human Review Interfaces

Guarantees

Stateless execution — same input yields same output
Idempotent normalization logic
Economic math is always computed if missing
Launch readiness classification is deterministic

Failure Model

If required schema fields are missing or validation fails, the sanitizer returns a 400 response with explicit error messages and does not persist any data. Unexpected runtime failures return a 500 response and log errors without partially writing invalid state.

Internal State

{
  "persistence": [
    "events_normalized"
  ],
  "guarantees": [
    "All persisted events conform to normalized schema",
    "All numeric economics are deterministically computed",
    "No malformed items reach downstream agents"
  ]
}

Sample cURL


curl -X POST https://api.whook.ai/v1/agent/sanitize/run \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "region": "Los Angeles County, CA",
      "assumptions": "Supply scraper ingestion"
    },
    "items": [
      {
        "title": "Outdoor Power Yoga",
        "about": "Intense 90-minute yoga session outdoors.",
        "recommendedCreditsRequired": 2,
        "estimatedSessionCostBreakdown": {
          "instructorCost": 50,
          "venueCost": 20
        }
      }
    ]
  }'