{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/metricduck-com/json-schema/metricduck-com-signal-screen-request-schema.json",
  "title": "SignalScreenRequest",
  "description": "Request for cross-company filing intelligence signal screening.",
  "x-generated": "2026-11-18",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/metricduck-com-openapi.json#/components/schemas/SignalScreenRequest",
  "properties": {
    "signals": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Signals",
      "description": "Signal filters to match. Pass any signal_id present in the signals.signals catalog. The api is id-agnostic — no allowlist enforced here; mcp-worker SCREENING_SIGNALS (mcp-worker/src/tools/signal-catalog.ts) is the SSOT for client-facing valid IDs."
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Ticker",
      "description": "Filter to a single ticker (e.g. 'NVDA'). Per-ticker cross-source signal inventory. Combines with sectors as AND."
    },
    "sectors": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sectors",
      "description": "Sector codes to filter by (e.g., ['TECH', 'FIN'])"
    },
    "recency_days": {
      "type": "integer",
      "maximum": 365.0,
      "minimum": 1.0,
      "title": "Recency Days",
      "description": "Only filings from last N days",
      "default": 90
    },
    "limit": {
      "type": "integer",
      "maximum": 50.0,
      "minimum": 1.0,
      "title": "Limit",
      "description": "Max results to return",
      "default": 20
    },
    "match_mode": {
      "type": "string",
      "enum": [
        "all",
        "any"
      ],
      "title": "Match Mode",
      "description": "Signal-list match semantics within each source type. 'all' (default, backwards-compat): row qualifies only if every requested signal_id fires on the same source row. 'any': row qualifies if any requested signal_id fires. Use 'any' for broadcast-discovery; 'all' for targeted screening.",
      "default": "all"
    },
    "order_by": {
      "type": "string",
      "enum": [
        "recency",
        "market_cap"
      ],
      "title": "Order By",
      "description": "Result ordering. 'recency' (default): event_date / filing_date DESC. 'market_cap': company market cap DESC NULLS LAST, recency as tiebreaker. Use 'market_cap' for broadcast-digest discovery so high-impact filings aren't pushed past the limit by fresher small-cap noise.",
      "default": "recency"
    },
    "since_date": {
      "anyOf": [
        {
          "type": "string",
          "format": "date"
        },
        {
          "type": "null"
        }
      ],
      "title": "Since Date",
      "description": "Time-travel lower bound (inclusive) on event_date / filing_date. When provided alongside until_date, defines an explicit date range — overrides recency_days. Format: YYYY-MM-DD. Use for backfilling past digests or anchoring research to specific historical windows."
    },
    "until_date": {
      "anyOf": [
        {
          "type": "string",
          "format": "date"
        },
        {
          "type": "null"
        }
      ],
      "title": "Until Date",
      "description": "Time-travel upper bound (inclusive) on event_date / filing_date. When provided alongside since_date, defines an explicit date range — overrides recency_days. Defaults to today (UTC) when only since_date is set. Format: YYYY-MM-DD."
    },
    "agreement_type_filter": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Agreement Type Filter",
      "description": "Discriminator filter for ir_partnership signals — restricts results to a specific agreement_type (e.g., 'm_and_a_announcement', 'partnership_strategic'). Values mirror services/sec-8k-material-agreement/extraction/schemas.py AgreementType. Only applied to ir_press_release source rows; ignored for other sources."
    }
  },
  "type": "object",
  "required": [
    "signals"
  ]
}