niche_signal_scan

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "Niche / beat description (2-200 chars). Specific is better.",
      "minLength": 2,
      "maxLength": 200
    },
    "recency": {
      "type": "string",
      "description": "Optional recency window that constrains discovery to fresh sources. One of '24h' | 'week' | 'month' | 'quarter' | 'year' (aliases: 'today'/'day'→24h, 'this week'→week, etc.). Use '24h' for 'today only / breaking'. Putting the demand in the niche string does not constrain recency; use this param. Omit to use the niche's default window."
    },
    "recency_strict": {
      "type": "boolean",
      "description": "When true, `recency` is a hard cutoff: sources outside the window are dropped before clustering, so 'nothing older than yesterday' is honored exactly. Default false: the window is a strong bias but older corroborating sources can still attach to a fresh cluster. Set true when exactness matters more than slate depth (strict can thin the slate)."
    },
    "source_quality": {
      "type": "string",
      "enum": [
        "strict",
        "balanced",
        "broad"
      ],
      "default": "balanced",
      "description": "How aggressively to filter the slate on source quality (niche-relative; never penalizes a small publication that is the authority for the niche).\n  • strict: drop uncorroborated single-source silos that aren't a primary/official or a niche authority; surfaces only well-sourced stories. Can thin the slate.\n  • balanced (default): down-weight weak sources, don't drop.\n  • broad: surface everything, including low-coverage emerging clusters, with authority as a tiebreaker only.\nUse strict for a high-trust brief, broad to scout early signal."
    },
    "density": {
      "type": "string",
      "enum": [
        "minimal",
        "balanced",
        "essay"
      ],
      "default": "balanced",
      "description": "How tightly to pack visual formats (carousels especially).\n  • minimal: split a dense argument across more, shorter slides; favors skimmability.\n  • balanced (default): the standard per-slide caps.\n  • essay: permissive; allows longer slides/sections.\nOver-cap slides auto-split on sentence boundaries (never mid-sentence); over-280 tweets split into a chain regardless."
    },
    "target_outputs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Output cells to generate (platform×content_type matrix). Each cell is a 'platform:content_type' string or a cross-platform content type. Valid cells:\n  • linkedin:text_post: short LinkedIn post (text only)\n  • linkedin:image_post: LinkedIn post plus 1.91:1 image card\n  • linkedin:carousel: multi-slide carousel\n  • linkedin:reel: LinkedIn-native vertical video\n  • x:single_tweet: standalone tweet\n  • x:thread: multi-tweet thread\n  • x:image_post: tweet plus 16:9 image card\n  • x:reel: tweet plus 9:16 video\n  • instagram:image_post: caption plus 4:5 image card\n  • instagram:carousel: multi-image swipe\n  • instagram:reel: caption plus 9:16 reel\n  • long_form_article: universal essay (Substack/blog)\n\nA bare platform name also works and maps to that platform's default cell: 'x'/'twitter'→x:single_tweet (pass 'x:thread' for a thread), 'linkedin'/'li'→linkedin:text_post, 'instagram'/'ig'→instagram:image_post, 'longform'→long_form_article. The resolved cells are echoed back as target_outputs.\nDefaults to ['linkedin:text_post']; request only the cells you need (each additional cell adds generation cost)."
    },
    "target_platforms": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional. A flat platform list (linkedin, linkedin_carousel, twitter, longform, instagram), coerced into target_outputs cells. Prefer target_outputs."
    },
    "brand_id": {
      "type": "string",
      "description": "Binds this brand's voice, colors, offer, and CTA to the piece. Omit to use your default brand; on a multi-brand account pass the slug explicitly so a post about one product is not bound to another brand's identity. niche_whoami lists your brands."
    },
    "profile_overrides": {
      "type": "object",
      "description": "Optional. Deep-merge these overrides onto the persisted profile for this run only. Use case: same brand, different register for a specific piece (e.g. a product-launch voice over an editorial one). Requires brand_id."
    },
    "thinking_budget": {
      "type": "string",
      "enum": [
        "fast",
        "balanced"
      ],
      "default": "balanced",
      "description": "Agent-side polling control. A full editorial workflow is structurally 15-20 tool calls (scan, poll, poll, poll, pick, poll, pick, poll, read). Use this to tune how many of those calls collapse into single waits.\n  • fast: scan blocks briefly (up to ~45s, under the tool-call timeout) for CP1 and returns the stories inline when they land in time. One call instead of many polls. Cheaper agent tokens, smaller cognitive surface. If CP1 isn't ready by the cap it still returns the session_id (status=discovering); poll niche_session_state from there, the run is never lost. Pick when you just want stories and the user is waiting.\n  • balanced (default): scan returns immediately with session_id; the agent polls niche_session_state (with wait plus since_status long-poll)."
    },
    "idempotency_key": {
      "type": "string",
      "description": "Optional. A stable key for this logical scan: a retry with the same key reuses the original run instead of starting (and billing) a second. Even without it, an identical scan fired while one is still running is auto-deduped."
    },
    "estimate_only": {
      "type": "boolean",
      "description": "When true, return the discovery credit cost without starting a run or holding a reservation. Use it to quote a price before committing.",
      "default": false
    }
  },
  "required": [
    "niche"
  ]
}