Deep Research Agent

Semantic Expansion, Economic Modeling, and Concept Synthesis · POST /v1/agent/research/scan

Category: Knowledge Generation · Execution Model: Probabilistic (LLM), Validated, Chunked

Purpose

The Deep Research Agent transforms raw demand signals into launch-ready, economically validated experiential concepts. It performs large-context semantic reasoning over recent market signals, applies strict business and margin constraints, and emits structured, schema-validated JSON chunks that represent concrete, executable session candidates. This agent is the system’s primary bridge between abstract demand detection and concrete experience creation.

Expected Inputs

resourceSignals object
Optional resource availability signals used to size how many concepts are generated during this research cycle. If omitted, the agent defaults to a fixed exploratory output size.

Outputs

HTTP Response

{
  "message": "string",
  "chunksForwarded": "number",
  "responses": "Array<{ chunkIndex: number, status: number }>"
}

Side Effect
```
Reads from IngestedData collection
```
Side Effect
```
Invokes external LLM provider
```

Side Effect

Writes sanitized research output to Whook ingestion pipeline

Responsibilities

Aggregate recent multi-source trend signals into a research context
Perform deep semantic expansion using an LLM reasoning core
Generate novel, one-off experiential class concepts
Apply margin, pricing, and cost constraints at generation time
Dynamically size output volume based on resource availability
Emit strictly valid, chunked JSON for downstream ingestion
Forward validated research output into the Whook ingestion pipeline

Lifecycle

Fetch most recent ingested demand signals
Construct a constrained, resource-aware research prompt
Invoke LLM via abstraction layer (model-agnostic)
Parse raw text output into candidate JSON chunks
Sanitize, normalize, and validate each chunk
Forward validated chunks to Whook ingestion endpoint
Return execution summary to caller

Downstream Dependencies

Whook Ingestion Pipeline
Category Trends Agent
Ontology Agent
Template Builder Agent

Guarantees

No invalid JSON is ingested downstream
Each emitted concept includes validated margin math
Chunk boundaries are deterministic and schema-compliant
Generation volume is resource-aware when signals are provided

Failure Model

If no ingested data is available, the agent aborts with a 400 error. If the LLM fails, execution terminates with a 500 error. Invalid or malformed JSON chunks are skipped but do not abort the run. Only sanitized, schema-valid chunks are forwarded downstream.

Internal State

{
  "dependencies": [
    "IngestedData",
    "LLM Adapter",
    "Sanitizer Service"
  ],
  "constraints": [
    "Strict JSON-only output",
    "Maximum 5 items per chunk",
    "Margin validation enforced before ingestion",
    "Lowest viable credit tier always selected"
  ]
}

Sample cURL


curl -X POST https://api.whook.ai/v1/agent/research/scan \
  -H "Content-Type: application/json" \
  -d '{
    "resourceSignals": {
      "cashAvailableForPilot": 6000,
      "targetUtilizationPercent": 0.7,
      "coachHoursAvailable": 60,
      "siteManagerHoursAvailable": 40,
      "maxConcurrentPilots": 6
    }
  }'