{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/antfly/json-schema/antfly-retrieval-agent-result-schema.json",
  "title": "RetrievalAgentResult",
  "description": "Result from the retrieval agent",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/antfly-query-operations-api-openapi.yml#/components/schemas/RetrievalAgentResult",
  "type": "object",
  "required": [
    "hits",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique response ID for logging and tracing"
    },
    "model": {
      "type": "string",
      "description": "LLM model used for generation"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp (seconds) when the response was created"
    },
    "status": {
      "$ref": "#/$defs/AgentStatus",
      "description": "Current status of the bounded agent execution"
    },
    "incomplete_details": {
      "$ref": "#/$defs/IncompleteDetails",
      "description": "Present when status is \"incomplete\" — explains why"
    },
    "usage": {
      "$ref": "#/$defs/RetrievalAgentUsage",
      "description": "Token usage and resource statistics from this execution"
    },
    "hits": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/QueryHit"
      },
      "description": "Retrieved query hits"
    },
    "steps": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentStep"
      },
      "description": "Shared bounded-agent execution trace for this retrieval run."
    },
    "strategy_used": {
      "$ref": "#/$defs/RetrievalStrategy",
      "description": "Primary strategy that was used (optional in agentic mode)"
    },
    "session_id": {
      "type": "string",
      "description": "Correlation identifier for client-carried continuation."
    },
    "iteration": {
      "type": "integer",
      "description": "Current internal iteration count for this bounded session."
    },
    "clarification_count": {
      "type": "integer",
      "description": "Number of user clarification turns already consumed in this session."
    },
    "remaining_internal_iterations": {
      "type": "integer",
      "description": "Remaining internal reasoning/tool-use iterations for this session."
    },
    "remaining_user_clarifications": {
      "type": "integer",
      "description": "Remaining clarification turns allowed for this session."
    },
    "questions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentQuestion"
      },
      "description": "Clarification questions exposed in the shared bounded-agent envelope."
    },
    "applied_filters": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FilterSpec"
      },
      "description": "Filters that were applied during retrieval"
    },
    "tool_calls_made": {
      "type": "integer",
      "description": "Total number of tool calls made during retrieval"
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChatMessage"
      },
      "description": "Optional conversational context including tool calls and responses.\nDecisions remain the authoritative continuation input for bounded agent interactions.\n"
    },
    "classification": {
      "$ref": "#/$defs/ClassificationTransformationResult",
      "description": "Query classification and transformation result. Present when\nsteps.classification was configured. Includes strategy, semantic_query,\nsub_questions (decompose), step_back_query, and reasoning.\n"
    },
    "generation": {
      "type": "string",
      "description": "Generated response in markdown format. Present when steps.generation\nwas configured.\n"
    },
    "generation_confidence": {
      "type": "number",
      "format": "float",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Confidence in the generated response (requires steps.confidence)"
    },
    "context_relevance": {
      "type": "number",
      "format": "float",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Relevance of retrieved documents to the query (requires steps.confidence)"
    },
    "followup_questions": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Suggested follow-up questions (requires steps.followup)"
    },
    "eval_result": {
      "$ref": "#/$defs/EvalResult",
      "description": "Evaluation results when steps.eval was configured"
    }
  },
  "$defs": {
    "AgentQuestion": {
      "type": "object",
      "required": [
        "id",
        "kind",
        "question"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable question identifier for client-carried continuation"
        },
        "kind": {
          "$ref": "#/$defs/AgentQuestionKind"
        },
        "question": {
          "type": "string",
          "description": "The clarifying question to ask the user"
        },
        "reason": {
          "type": "string",
          "description": "Why clarification is needed"
        },
        "options": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optional list of choices for the user"
        },
        "default_answer": {
          "type": "string",
          "description": "Suggested default answer when the server has a preferred choice"
        },
        "affects": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "High-level result areas affected by this decision"
        }
      }
    },
    "AgentQuestionKind": {
      "type": "string",
      "enum": [
        "confirm",
        "single_choice",
        "multi_choice",
        "free_text",
        "field_policy"
      ],
      "description": "UI rendering/answer handling hint for a bounded agent question"
    },
    "AgentStatus": {
      "type": "string",
      "enum": [
        "clarification_required",
        "completed",
        "in_progress",
        "incomplete",
        "failed"
      ],
      "description": "Shared bounded-agent execution status"
    },
    "AgentStep": {
      "type": "object",
      "description": "A step in the shared bounded-agent execution trace",
      "required": [
        "name",
        "action"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique step ID for correlation and tracing"
        },
        "kind": {
          "$ref": "#/$defs/AgentStepKind"
        },
        "name": {
          "type": "string",
          "description": "Stable step name used for correlation across JSON and SSE surfaces"
        },
        "action": {
          "type": "string",
          "description": "What action was taken"
        },
        "status": {
          "$ref": "#/$defs/AgentStepStatus"
        },
        "error_message": {
          "type": "string",
          "description": "Error details when status is \"error\""
        },
        "duration_ms": {
          "type": "integer",
          "description": "Server-side execution time in milliseconds"
        },
        "details": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional details about the step"
        }
      }
    },
    "AgentStepKind": {
      "type": "string",
      "enum": [
        "tool_call",
        "planning",
        "classification",
        "generation",
        "validation",
        "clarification"
      ],
      "description": "Shared bounded-agent step category"
    },
    "AgentStepStatus": {
      "type": "string",
      "enum": [
        "success",
        "error",
        "skipped"
      ],
      "description": "Outcome of a shared agent step"
    },
    "ChatMessage": {
      "type": "object",
      "description": "OpenAI-compatible message in a generation/chat conversation.",
      "required": [
        "role"
      ],
      "properties": {
        "extra_content": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque provider message metadata. Preserve unchanged when replaying assistant messages; native Anthropic content retains signed thinking blocks."
        },
        "role": {
          "$ref": "#/$defs/ChatMessageRole"
        },
        "content": {
          "$ref": "#/$defs/ChatMessageContent"
        },
        "tool_calls": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ToolCall"
          },
          "description": "Tool calls made by the assistant (only for role=assistant)."
        },
        "tool_call_id": {
          "type": "string",
          "description": "ID of the tool call this message responds to (only for role=tool)."
        },
        "name": {
          "type": "string",
          "description": "Optional tool name for tool messages when model templates need it."
        }
      }
    },
    "ChatMessageContent": {
      "x-go-type": "stdjson.RawMessage",
      "x-go-type-import": {
        "path": "encoding/json",
        "name": "stdjson"
      },
      "description": "Message content. Supports two formats:\n- Simple string: \"Hello, how are you?\"\n- Array of content parts: [{\"type\": \"text\", \"text\": \"Hello\"}]\n",
      "oneOf": [
        {
          "type": "string",
          "description": "Simple text content."
        },
        {
          "type": "array",
          "description": "Array of multimodal content parts.",
          "items": {
            "$ref": "#/$defs/ContentPart"
          }
        }
      ]
    },
    "ChatMessageRole": {
      "type": "string",
      "enum": [
        "user",
        "assistant",
        "system",
        "tool"
      ],
      "description": "Role of the message sender in a generation/chat conversation"
    },
    "ClassificationTransformationResult": {
      "type": "object",
      "description": "Query classification and transformation result combining all query enhancements including strategy selection and semantic optimization",
      "required": [
        "route_type",
        "improved_query",
        "semantic_query",
        "semantic_mode",
        "strategy",
        "confidence"
      ],
      "properties": {
        "route_type": {
          "x-go-type-skip-optional-pointer": true,
          "$ref": "#/$defs/RouteType"
        },
        "strategy": {
          "x-go-type-skip-optional-pointer": true,
          "$ref": "#/$defs/QueryStrategy"
        },
        "semantic_mode": {
          "x-go-type-skip-optional-pointer": true,
          "$ref": "#/$defs/SemanticQueryMode"
        },
        "improved_query": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Clarified query with added context for answer generation (human-readable)"
        },
        "semantic_query": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Optimized query for vector/semantic search. Content style depends on semantic_mode: keywords for 'rewrite', hypothetical answer for 'hypothetical'"
        },
        "step_back_query": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Broader background query for context (only present when strategy is 'step_back')"
        },
        "sub_questions": {
          "x-go-type-skip-optional-pointer": true,
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Decomposed sub-questions (only present when strategy is 'decompose')"
        },
        "multi_phrases": {
          "x-go-type-skip-optional-pointer": true,
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Alternative phrasings of the query for expanded retrieval coverage"
        },
        "reasoning": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "description": "Pre-retrieval reasoning explaining query analysis and strategy selection (only present when with_classification_reasoning is enabled)"
        },
        "confidence": {
          "x-go-type-skip-optional-pointer": true,
          "type": "number",
          "format": "float",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Classification confidence (0.0 to 1.0)"
        }
      }
    },
    "ContentPart": {
      "description": "A content part for multimodal input (text, image URL, or inline media).",
      "oneOf": [
        {
          "$ref": "#/$defs/TextContentPart"
        },
        {
          "$ref": "#/$defs/ImageURLContentPart"
        },
        {
          "$ref": "#/$defs/MediaContentPart"
        }
      ]
    },
    "EvalResult": {
      "type": "object",
      "description": "Complete evaluation result",
      "properties": {
        "scores": {
          "$ref": "#/$defs/EvalScores",
          "description": "Scores organized by category"
        },
        "summary": {
          "$ref": "#/$defs/EvalSummary",
          "description": "Aggregate statistics"
        },
        "duration_ms": {
          "type": "integer",
          "description": "Total evaluation duration in milliseconds"
        }
      }
    },
    "EvalScores": {
      "type": "object",
      "description": "Scores organized by category",
      "properties": {
        "retrieval": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/EvaluatorScore"
          },
          "description": "Retrieval metric scores (recall, precision, ndcg, etc.)"
        },
        "generation": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/EvaluatorScore"
          },
          "description": "Generation quality scores (faithfulness, relevance, etc.)"
        }
      }
    },
    "EvalSummary": {
      "type": "object",
      "description": "Aggregate statistics across all evaluators",
      "properties": {
        "average_score": {
          "type": "number",
          "format": "float",
          "description": "Average score across all evaluators"
        },
        "passed": {
          "type": "integer",
          "description": "Number of evaluators that passed"
        },
        "failed": {
          "type": "integer",
          "description": "Number of evaluators that failed"
        },
        "total": {
          "type": "integer",
          "description": "Total number of evaluators run"
        }
      }
    },
    "EvaluatorScore": {
      "type": "object",
      "description": "Result from a single evaluator",
      "properties": {
        "score": {
          "type": "number",
          "format": "float",
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Numeric score (0-1)"
        },
        "pass": {
          "type": "boolean",
          "description": "Whether the evaluation passed the threshold"
        },
        "reason": {
          "type": "string",
          "description": "Human-readable explanation of the result"
        },
        "metadata": {
          "type": "object",
          "additionalProperties": true,
          "description": "Additional evaluator-specific data"
        }
      }
    },
    "FilterSpec": {
      "type": "object",
      "description": "A filter specification to apply to search queries",
      "required": [
        "field",
        "operator",
        "value"
      ],
      "properties": {
        "field": {
          "type": "string",
          "description": "Field name to filter on"
        },
        "operator": {
          "type": "string",
          "enum": [
            "eq",
            "ne",
            "gt",
            "gte",
            "lt",
            "lte",
            "contains",
            "prefix",
            "range",
            "in"
          ],
          "description": "Filter operator:\n- eq: Equals\n- ne: Not equals\n- gt/gte: Greater than (or equal)\n- lt/lte: Less than (or equal)\n- contains: Contains substring\n- prefix: Starts with\n- range: Between two values (value should be array [min, max])\n- in: Value in list (value should be array)\n"
        },
        "value": {
          "description": "Filter value (string, number, boolean, or array for range/in operators)"
        }
      }
    },
    "GraphMetricRerankScoreDetails": {
      "type": "object",
      "required": [
        "index_name",
        "metric_name",
        "base_score",
        "base_weight",
        "metric_score_used",
        "metric_weight",
        "missing_score_used",
        "final_score",
        "published_generation"
      ],
      "properties": {
        "index_name": {
          "type": "string",
          "description": "Graph index that provided the metric score."
        },
        "metric_name": {
          "type": "string",
          "description": "Graph metric used as a score feature."
        },
        "base_score": {
          "type": "number",
          "format": "double",
          "description": "Hit score before graph metric rerank composition."
        },
        "base_weight": {
          "type": "number",
          "format": "double",
          "description": "Weight applied to the base score."
        },
        "metric_score": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "description": "Published metric score for this hit, or null when the hit was missing from the metric generation."
        },
        "metric_score_used": {
          "type": "number",
          "format": "double",
          "description": "Metric feature value used in the formula after applying missing_score fallback if needed."
        },
        "metric_weight": {
          "type": "number",
          "format": "double",
          "description": "Weight applied to the metric score feature."
        },
        "missing_score_used": {
          "type": "boolean",
          "description": "True when metric_score was missing and the request's missing_score fallback was used."
        },
        "final_score": {
          "type": "number",
          "format": "double",
          "description": "Final hit score after graph metric rerank composition."
        },
        "published_generation": {
          "type": "integer",
          "format": "int64",
          "description": "Published graph metric score generation used for this hit."
        }
      }
    },
    "HierarchyAncestor": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "id": {
          "type": "string"
        },
        "document": {
          "type": "object",
          "additionalProperties": true
        },
        "key": {
          "type": "string"
        },
        "artifact_name": {
          "type": "string"
        },
        "source_field": {
          "type": "string"
        },
        "provenance": {}
      }
    },
    "HierarchyArtifact": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "kind"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "chunk",
            "asset",
            "embedding"
          ]
        },
        "chunk_id": {
          "type": "integer",
          "format": "uint32",
          "x-go-type-skip-optional-pointer": false
        },
        "window_index": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Independent media output sub-window within the parent chunk; omitted for an unsplit vector.",
          "x-go-type-skip-optional-pointer": false
        },
        "unit_id": {
          "type": "string"
        },
        "source": {
          "$ref": "#/$defs/HierarchyArtifactSource"
        }
      }
    },
    "HierarchyArtifactSource": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "kind"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "kind": {
          "type": "string",
          "enum": [
            "chunk",
            "asset",
            "embedding"
          ]
        },
        "chunk_id": {
          "type": "integer",
          "format": "uint32",
          "x-go-type-skip-optional-pointer": false
        },
        "window_index": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Independent media output sub-window within the parent chunk; omitted for an unsplit vector.",
          "x-go-type-skip-optional-pointer": false
        },
        "unit_id": {
          "type": "string"
        }
      }
    },
    "HierarchyEvidence": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "local_id": {
          "type": "string"
        },
        "decision": {
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-type-skip-optional-pointer": false
        },
        "source_artifact": {
          "type": "string"
        },
        "source_artifact_key": {
          "type": "string"
        },
        "resolution_artifact": {
          "type": "string"
        },
        "resolution_artifact_key": {
          "type": "string"
        },
        "resolver": {
          "type": "string"
        },
        "resolver_table": {
          "type": "string"
        },
        "mention": {
          "type": "object",
          "additionalProperties": true
        },
        "canonical": {
          "type": "object",
          "additionalProperties": true
        }
      }
    },
    "HierarchyMatchContext": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "level": {
          "$ref": "#/$defs/QueryHitHierarchyLevel"
        },
        "parent_doc_key": {
          "type": "string"
        },
        "parent_unit_id": {
          "type": "string"
        },
        "artifact": {
          "$ref": "#/$defs/HierarchyArtifact"
        },
        "ancestors": {
          "$ref": "#/$defs/QueryHitHierarchyAncestors"
        }
      }
    },
    "HierarchyMatchHit": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "_id",
        "_score"
      ],
      "properties": {
        "_id": {
          "type": "string",
          "x-go-name": "ID"
        },
        "_score": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-name": "score",
          "description": "Relevance score, normalized so higher values always rank first."
        },
        "_distance": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-name": "distance",
          "x-go-type-skip-optional-pointer": false,
          "description": "Raw vector distance when this hit came directly from a dense-vector search; lower values are better."
        },
        "_source": {
          "type": "object",
          "additionalProperties": true,
          "x-go-name": "source"
        },
        "hierarchy": {
          "$ref": "#/$defs/HierarchyMatchContext"
        }
      }
    },
    "HighlightFragment": {
      "type": "object",
      "required": [
        "text",
        "offset",
        "spans"
      ],
      "properties": {
        "text": {
          "type": "string",
          "description": "The fragment of the stored field value."
        },
        "offset": {
          "type": "integer",
          "description": "Byte offset of the fragment within the field value."
        },
        "item": {
          "type": "integer",
          "description": "Array index for one array; flattened value ordinal for paths through multiple arrays."
        },
        "spans": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/HighlightSpan"
          }
        }
      }
    },
    "HighlightSpan": {
      "type": "object",
      "required": [
        "start",
        "end"
      ],
      "description": "Half-open byte range within the fragment text.",
      "properties": {
        "start": {
          "type": "integer"
        },
        "end": {
          "type": "integer"
        }
      }
    },
    "ImageURL": {
      "type": "object",
      "description": "Image URL or data URI.",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "type": "string",
          "description": "URL or data URI (data:image/png;base64,...)."
        }
      }
    },
    "ImageURLContentPart": {
      "type": "object",
      "description": "Image content in OpenAI-compatible format.",
      "required": [
        "type",
        "image_url"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "image_url"
          ]
        },
        "image_url": {
          "$ref": "#/$defs/ImageURL"
        }
      }
    },
    "IncompleteDetails": {
      "type": "object",
      "description": "Explains why the agent stopped before completion. Present when status is \"incomplete\".",
      "required": [
        "reason"
      ],
      "properties": {
        "reason": {
          "type": "string",
          "enum": [
            "max_internal_iterations",
            "max_tokens",
            "no_tools",
            "clarification_required"
          ],
          "description": "Why the agent stopped:\n- max_internal_iterations: Hit the configured max_internal_iterations limit\n- max_tokens: LLM output was truncated\n- no_tools: No tools were available for agentic mode\n- clarification_required: The agent needs a user decision before it can continue\n"
        }
      }
    },
    "MediaContentPart": {
      "type": "object",
      "description": "Inline binary media content (audio, image, etc.).",
      "required": [
        "type",
        "data",
        "mime_type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "media"
          ]
        },
        "data": {
          "type": "string",
          "format": "byte",
          "description": "Base64-encoded binary data."
        },
        "mime_type": {
          "type": "string",
          "description": "MIME type (audio/wav, image/gif, image/png, etc.)."
        },
        "sampling": {
          "$ref": "#/$defs/VideoSamplingPolicy"
        }
      }
    },
    "PruneStats": {
      "type": "object",
      "description": "Statistics from token-based document pruning",
      "properties": {
        "resources_kept": {
          "type": "integer",
          "description": "Number of resources kept after pruning"
        },
        "resources_pruned": {
          "type": "integer",
          "description": "Number of resources pruned to fit token budget"
        },
        "tokens_kept": {
          "type": "integer",
          "description": "Estimated tokens in kept resources"
        },
        "tokens_pruned": {
          "type": "integer",
          "description": "Estimated tokens in pruned resources"
        }
      }
    },
    "QueryHit": {
      "type": "object",
      "description": "A single query result hit",
      "required": [
        "_id",
        "_score"
      ],
      "properties": {
        "_table": {
          "type": "string",
          "description": "Source table provenance for composed query hits; equal IDs from union inputs remain distinct."
        },
        "_computed": {
          "type": "object",
          "x-zig-type": "raw_json_object",
          "additionalProperties": true,
          "description": "Named query-time computed values, separate from stored source."
        },
        "_id": {
          "type": "string",
          "description": "ID of the record.",
          "x-go-name": "ID"
        },
        "_score": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "description": "Relevance score of the hit, normalized so higher values always rank first.",
          "x-go-name": "score"
        },
        "_distance": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-name": "distance",
          "x-go-type-skip-optional-pointer": false,
          "description": "Raw vector distance for direct dense-vector hits; lower values are better.\nFor a source group ranked by dense descendants, this is the distance of\nthe best matching descendant that supplied the group score. Omitted for\nnon-dense and fused results.\n"
        },
        "_index_scores": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "format": "double"
          },
          "description": "Scores partitioned by index when using RRF search.",
          "x-go-name": "indexScores"
        },
        "_score_details": {
          "$ref": "#/$defs/QueryScoreDetails",
          "description": "Optional score provenance for ranking features applied to this hit.",
          "x-go-name": "scoreDetails"
        },
        "_source": {
          "type": "object",
          "additionalProperties": true,
          "x-go-name": "source"
        },
        "hierarchy": {
          "$ref": "#/$defs/QueryHitHierarchy",
          "description": "Stable ancestry envelope for derived document hierarchy hits. Present when\nthe hit is a derived unit/chunk/embedding artifact or when a source-level\ngroup includes nested matches. Standard fields include `level`,\n`parent_doc_key`, optional `parent_unit_id`, `artifact` or `matched_artifact`, `matches`, and\n`ancestors` with response-local or requested DB-backed source/unit context when available.\nV0.2-compatible implicit rollup requests continue to use the deprecated\n`chunks` field instead of `matches`.\n"
        },
        "_sort": {
          "type": "array",
          "items": {},
          "description": "Sort key values for this hit. Pass as search_after or search_before\nto paginate to the next/previous page. Values preserve their JSON\ntypes. Present for ordered result pages, including cursor-only\nrequests whose effective order is `_id` ascending.\n",
          "x-go-name": "sort"
        },
        "_highlights": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "$ref": "#/$defs/HighlightFragment"
            }
          },
          "description": "Highlighted fragments keyed by source field, present when the request\nset `highlight` and the stored document has the field. Highlights are\ncomputed from the unprojected document, so a `fields` projection that\nomits a highlighted field does not suppress its highlights. Each\nfragment is a window of the stored field value with byte-offset spans\nmarking the text the full-text query matched.\n",
          "x-go-name": "highlights"
        }
      }
    },
    "QueryHitHierarchy": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "level": {
          "$ref": "#/$defs/QueryHitHierarchyLevel",
          "description": "Hierarchy level represented by this hit."
        },
        "parent_doc_key": {
          "type": "string",
          "description": "Source document key that owns this derived hit."
        },
        "parent_unit_id": {
          "type": "string",
          "description": "Unit identifier when the hit is attached to a document unit."
        },
        "artifact": {
          "$ref": "#/$defs/HierarchyArtifact"
        },
        "matched_artifact": {
          "$ref": "#/$defs/HierarchyArtifact",
          "description": "Artifact member that supplied the score for a source-level grouped hit."
        },
        "ancestors": {
          "$ref": "#/$defs/QueryHitHierarchyAncestors"
        },
        "evidence": {
          "$ref": "#/$defs/HierarchyEvidence"
        },
        "matches": {
          "type": "array",
          "description": "Matching descendant hits attached by the canonical hierarchy.group_by request.",
          "items": {
            "$ref": "#/$defs/HierarchyMatchHit"
          }
        },
        "position": {
          "type": "string",
          "description": "Opaque format-neutral position used for sequential hierarchy traversal."
        },
        "revision": {
          "type": "string",
          "description": "Composite source hierarchy revision to which the position and cursor are bound."
        },
        "chunks": {
          "type": "array",
          "deprecated": true,
          "description": "Deprecated child chunk hits included by the v0.2-compatible implicit source rollup.",
          "items": {
            "$ref": "#/$defs/HierarchyMatchHit"
          }
        }
      }
    },
    "QueryHitHierarchyAncestors": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "source"
      ],
      "properties": {
        "source": {
          "$ref": "#/$defs/HierarchyAncestor"
        },
        "unit": {
          "$ref": "#/$defs/HierarchyAncestor"
        }
      }
    },
    "QueryHitHierarchyLevel": {
      "type": "string",
      "enum": [
        "source",
        "unit",
        "chunk",
        "mention",
        "artifact",
        "embedding"
      ]
    },
    "QueryScoreDetails": {
      "type": "object",
      "description": "Optional score provenance for ranking features that changed the final hit score.",
      "properties": {
        "graph_metric_rerank": {
          "$ref": "#/$defs/GraphMetricRerankScoreDetails",
          "description": "Score contribution from an explicit graph_metric_rerank request."
        }
      }
    },
    "QueryStrategy": {
      "type": "string",
      "enum": [
        "simple",
        "decompose",
        "step_back",
        "hyde"
      ],
      "description": "Strategy for query transformation and retrieval:\n- simple: Direct query with multi-phrase expansion. Best for straightforward factual queries.\n- decompose: Break complex queries into sub-questions, retrieve for each. Best for multi-part questions.\n- step_back: Generate broader background query first, then specific query. Best for questions needing context.\n- hyde: Generate hypothetical answer document, embed that for retrieval. Best for abstract/conceptual questions.\n"
    },
    "RetrievalAgentUsage": {
      "type": "object",
      "description": "Token usage and resource statistics from the retrieval agent execution",
      "properties": {
        "input_tokens": {
          "type": "integer",
          "description": "Total input tokens across all LLM calls"
        },
        "output_tokens": {
          "type": "integer",
          "description": "Total output tokens across all LLM calls"
        },
        "total_tokens": {
          "type": "integer",
          "description": "Sum of input + output tokens"
        },
        "cached_input_tokens": {
          "type": "integer",
          "description": "Input tokens served from cache"
        },
        "llm_calls": {
          "type": "integer",
          "description": "Number of LLM invocations made"
        },
        "resources_retrieved": {
          "type": "integer",
          "description": "Total resources found across all search queries"
        },
        "prune_stats": {
          "$ref": "#/$defs/PruneStats",
          "description": "Token pruning statistics, present when max_context_tokens was configured"
        }
      }
    },
    "RetrievalStrategy": {
      "type": "string",
      "enum": [
        "semantic",
        "bm25",
        "metadata",
        "tree",
        "graph",
        "hybrid"
      ],
      "description": "Strategy for document retrieval:\n- semantic: Vector similarity search using embeddings\n- bm25: Full-text search using BM25 scoring\n- metadata: Structured query on document fields\n- tree: Iterative tree navigation with summarization\n- graph: Relationship-based traversal\n- hybrid: Combine multiple strategies with RRF or rerank\n"
    },
    "RouteType": {
      "type": "string",
      "enum": [
        "question",
        "search"
      ],
      "description": "Classification of query type: question (specific factual query) or search (exploratory query)"
    },
    "SemanticQueryMode": {
      "type": "string",
      "enum": [
        "rewrite",
        "hypothetical"
      ],
      "description": "Mode for semantic query generation:\n- rewrite: Transform query into expanded keywords/concepts optimized for vector search (Level 2 optimization)\n- hypothetical: Generate a hypothetical answer that would appear in relevant documents (HyDE - Level 3 optimization)\n"
    },
    "TextContentPart": {
      "type": "object",
      "description": "Text content for multimodal input.",
      "required": [
        "type",
        "text"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "text"
          ]
        },
        "text": {
          "type": "string",
          "description": "Text content."
        }
      }
    },
    "ToolCall": {
      "type": "object",
      "description": "OpenAI-compatible assistant tool call.",
      "required": [
        "id",
        "type",
        "function"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Tool call identifier."
        },
        "type": {
          "type": "string",
          "enum": [
            "function"
          ]
        },
        "function": {
          "$ref": "#/$defs/ToolCallFunction"
        },
        "extra_content": {
          "type": "object",
          "additionalProperties": true,
          "description": "Opaque provider tool metadata, including Google thought signatures. Preserve it unchanged when replaying assistant tool calls."
        }
      }
    },
    "ToolCallFunction": {
      "type": "object",
      "description": "The function called by a model tool call.",
      "required": [
        "name",
        "arguments"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Function name."
        },
        "arguments": {
          "type": "string",
          "description": "JSON string of function arguments."
        }
      }
    },
    "VideoSamplingPolicy": {
      "type": "object",
      "description": "Explicit EmbeddingGemma 2 video-group sampling. Timestamp windows are half-open and relative to the first presentation picture.",
      "required": [
        "policy"
      ],
      "properties": {
        "policy": {
          "type": "string",
          "enum": [
            "reference",
            "timestamps"
          ]
        },
        "start_ns": {
          "type": "integer",
          "format": "int64",
          "minimum": 0
        },
        "end_ns": {
          "type": "integer",
          "format": "int64",
          "minimum": 1
        },
        "step_ns": {
          "type": "integer",
          "format": "int64",
          "minimum": 1
        },
        "max_frames": {
          "type": "integer",
          "minimum": 1,
          "maximum": 32
        },
        "overflow": {
          "type": "string",
          "enum": [
            "uniform",
            "truncate"
          ]
        },
        "hold": {
          "type": "boolean",
          "description": "Sample the displayed picture, including VFR holds, rather than the next picture at or after the target."
        }
      }
    }
  }
}