ResearchJobRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/scale-ai/json-schema/scale-ai-research-job-request-schema.json",
  "title": "ResearchJobRequest",
  "description": "Kickoff body for ``POST /v1/projects/{project_id}/research``.\n\nUse ``tools`` for per-tool enablement and configuration (same map shape as\n:class:`~dex_core.models.extraction.ExtractionParameters.agentic_tools` on extract jobs).",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/scale-ai-document-understanding-openapi.yml#/components/schemas/ResearchJobRequest",
  "properties": {
    "inputs": {
      "$ref": "#/$defs/ResearchInputs",
      "description": "Explicit scope. Empty lists: the API resolves to the project's **sole** vector store when exactly one exists; otherwise set vector_stores or parse_results explicitly."
    },
    "task": {
      "$ref": "#/$defs/ResearchTask"
    },
    "tools": {
      "additionalProperties": {
        "$ref": "#/$defs/ResearchToolConfigEntry"
      },
      "type": "object",
      "title": "Tools",
      "description": "Map tool name → enablement + config"
    },
    "model": {
      "type": "string",
      "title": "Model",
      "description": "Default model for all agent steps unless overridden in advanced"
    },
    "advanced": {
      "anyOf": [
        {
          "$ref": "#/$defs/ResearchAdvanced"
        },
        {
          "type": "null"
        }
      ],
      "description": "Per-stage model/prompt/temperature/reasoning overrides"
    },
    "execute_dependent_subtask_tool_hints": {
      "type": "boolean",
      "title": "Execute Dependent Subtask Tool Hints",
      "description": "When True, DECOMPOSE tool hints for dependent subtasks are executed as warm-start searches (same semantics as extract ``execute_dependent_subtask_tool_hints``). Default False (intent-only hints for dependents).",
      "default": false
    },
    "enable_subtable_citations": {
      "type": "boolean",
      "title": "Enable Subtable Citations",
      "description": "When True, the agent may cite specific table cells/rows/ranges (block_ref#loc), resolved to sub-bboxes when the table was parsed with substructure recognition. Default False — whole-table citations only (previous behavior).",
      "default": false
    },
    "include_file_tree_in_prompt": {
      "type": "string",
      "enum": [
        "auto",
        "all",
        "folders",
        "none"
      ],
      "title": "Include File Tree In Prompt",
      "description": "Whether the document file tree is embedded in the extraction prompt. 'auto' (default) keeps existing behavior: omitted when a file-system index is configured (index tools browse the tree instead), else the full tree ('all'). 'all' = every file path; 'folders' = folder structure only; 'none' = omit the tree entirely. Set 'none' to avoid spending tokens on hundreds of unhelpful file names.",
      "default": "auto"
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "task",
    "model"
  ],
  "$defs": {
    "ResearchAdvanced": {
      "properties": {
        "decomposition": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchDecompositionAdvanced"
            },
            {
              "type": "null"
            }
          ],
          "description": "Decomposition step overrides (model, prompt, rules, temperature, reasoning)"
        },
        "subtasks": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchSubtaskAdvancedSettings"
            },
            {
              "type": "null"
            }
          ],
          "description": "Subtask / ReAct step overrides including max_cycles"
        },
        "aggregation": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchAdvancedStep"
            },
            {
              "type": "null"
            }
          ],
          "description": "Aggregation step overrides (model, prompt, temperature, reasoning)"
        },
        "output_validation": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchOutputValidationAdvanced"
            },
            {
              "type": "null"
            }
          ],
          "description": "Output validation / schema-fix loop overrides including max_cycles"
        },
        "spreadsheet": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchSpreadsheetAdvanced"
            },
            {
              "type": "null"
            }
          ],
          "description": "Spreadsheet (Excel) sub-agent overrides (model, rules, max_hops)"
        }
      },
      "type": "object",
      "title": "ResearchAdvanced",
      "description": "Optional per-stage overrides (``advanced`` object)."
    },
    "ResearchAdvancedStep": {
      "properties": {
        "prompt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt",
          "description": "Override prompt for this step"
        },
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model",
          "description": "Model id for this step"
        },
        "temperature": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Temperature",
          "description": "Sampling temperature for this step"
        },
        "reasoning": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchReasoningBlock"
            },
            {
              "type": "null"
            }
          ],
          "description": "Reasoning-effort block (e.g. o-series)"
        }
      },
      "type": "object",
      "title": "ResearchAdvancedStep",
      "description": "Shared knobs for decomposition, subtasks, aggregation, validation."
    },
    "ResearchDecompositionAdvanced": {
      "properties": {
        "prompt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt",
          "description": "Override prompt for this step"
        },
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model",
          "description": "Model id for this step"
        },
        "temperature": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Temperature",
          "description": "Sampling temperature for this step"
        },
        "reasoning": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchReasoningBlock"
            },
            {
              "type": "null"
            }
          ],
          "description": "Reasoning-effort block (e.g. o-series)"
        },
        "rules": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rules",
          "description": "Extra rules appended to the decompose prompt (e.g. domain-specific subtask guidance)."
        }
      },
      "type": "object",
      "title": "ResearchDecompositionAdvanced",
      "description": "Decomposition step overrides (``advanced.decomposition``)."
    },
    "ResearchInputs": {
      "properties": {
        "files": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Files",
          "description": "Uploaded file IDs (e.g. file_…) — not yet supported."
        },
        "parse_results": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Parse Results",
          "description": "Parse result IDs (e.g. pres_…)"
        },
        "vector_stores": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Vector Stores",
          "description": "Vector store IDs to search"
        },
        "indexes": {
          "items": {
            "type": "string"
          },
          "type": "array",
          "title": "Indexes",
          "description": "Index IDs (at most one). Enables index-based search/navigation tools."
        }
      },
      "type": "object",
      "title": "ResearchInputs",
      "description": "Scoped inputs for a research job. If all are empty, the API resolves to the project's sole vector store."
    },
    "ResearchOutputValidationAdvanced": {
      "properties": {
        "prompt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt",
          "description": "Override prompt for this step"
        },
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model",
          "description": "Model id for this step"
        },
        "temperature": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Temperature",
          "description": "Sampling temperature for this step"
        },
        "reasoning": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchReasoningBlock"
            },
            {
              "type": "null"
            }
          ],
          "description": "Reasoning-effort block (e.g. o-series)"
        },
        "max_cycles": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Cycles",
          "description": "Max validation–fix cycles (default 3)"
        }
      },
      "type": "object",
      "title": "ResearchOutputValidationAdvanced",
      "description": "Schema validation / fix loop (``advanced.output_validation``)."
    },
    "ResearchReasoningBlock": {
      "properties": {
        "effort": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "high",
                "medium",
                "low",
                "none"
              ]
            },
            {
              "type": "null"
            }
          ],
          "title": "Effort",
          "description": "Model reasoning effort where applicable"
        }
      },
      "type": "object",
      "title": "ResearchReasoningBlock",
      "description": "Nested reasoning / effort block for ``advanced.*.reasoning``."
    },
    "ResearchSpreadsheetAdvanced": {
      "properties": {
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model",
          "description": "Model for the spreadsheet (Excel) sub-agent; defaults to the subtask/acting model."
        },
        "rules": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Rules",
          "description": "Extra rules appended to the spreadsheet sub-agent's system prompt (e.g. summarise large sheets)."
        },
        "max_hops": {
          "anyOf": [
            {
              "type": "integer",
              "maximum": 50.0,
              "minimum": 1.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Hops",
          "description": "Max ReAct iterations inside the spreadsheet sub-agent (default 20); distinct from subtasks.max_cycles."
        }
      },
      "type": "object",
      "title": "ResearchSpreadsheetAdvanced",
      "description": "Excel / spreadsheet sub-agent overrides (``advanced.spreadsheet``)."
    },
    "ResearchSubtaskAdvancedSettings": {
      "properties": {
        "prompt": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Prompt",
          "description": "Override prompt for this step"
        },
        "model": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Model",
          "description": "Model id for this step"
        },
        "temperature": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ],
          "title": "Temperature",
          "description": "Sampling temperature for this step"
        },
        "reasoning": {
          "anyOf": [
            {
              "$ref": "#/$defs/ResearchReasoningBlock"
            },
            {
              "type": "null"
            }
          ],
          "description": "Reasoning-effort block (e.g. o-series)"
        },
        "max_cycles": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1.0
            },
            {
              "type": "null"
            }
          ],
          "title": "Max Cycles",
          "description": "Max ReAct iterations per subtask (default 5)"
        },
        "search_rules": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Search Rules",
          "description": "Extra rules appended to the reasoning step search action (e.g. search strategy hints)."
        },
        "extraction_rules": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Extraction Rules",
          "description": "Extra rules appended to the reasoning step extract action (e.g. unit/sign conventions)."
        }
      },
      "type": "object",
      "title": "ResearchSubtaskAdvancedSettings",
      "description": "ReAct / subtask loop settings (``advanced.subtasks``)."
    },
    "ResearchTask": {
      "properties": {
        "description": {
          "type": "string",
          "title": "Description",
          "description": "Goal of the research / extraction task"
        },
        "plan": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Plan",
          "description": "Unstructured plan or guidance for the agent"
        },
        "output_schema": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "title": "Output Schema",
          "description": "JSON Schema for structured output"
        },
        "report_schema": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Report Schema",
          "description": "Unstructured template (e.g. markdown) for report-style output"
        }
      },
      "type": "object",
      "required": [
        "description"
      ],
      "title": "ResearchTask",
      "description": "User task: goal, optional plan, and structured or report-shaped output."
    },
    "ResearchToolConfigEntry": {
      "properties": {
        "enabled": {
          "type": "boolean",
          "title": "Enabled",
          "description": "When False, the tool is not offered to the agent",
          "default": true
        },
        "config": {
          "additionalProperties": true,
          "type": "object",
          "title": "Config",
          "description": "Tool-specific configuration (e.g. top_k, filters, rerank_config)"
        }
      },
      "type": "object",
      "title": "ResearchToolConfigEntry",
      "description": "Per-tool enablement and opaque config (e.g. search_config for similarity_search)."
    }
  }
}