{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/antfly/json-schema/antfly-retrieval-agent-request-schema.json",
  "title": "RetrievalAgentRequest",
  "description": "Request for the retrieval agent. Queries define which tables and indexes\nto search, each as an ordinary QueryRequest. Optional tree or graph exploration\nis configured by steps.retrieval.navigation, targeting one query by index.\n\n**Pipeline mode** (default, max_internal_iterations=0): Queries are executed\ndirectly without an LLM tool-calling loop.\n\n**Agentic mode** (max_internal_iterations > 0): The LLM decides which tools to\ncall, using the queries to determine available tables and indexes. A query\nmay contain only a table scope and caller constraints: build_query delegates\nto the query-builder agent, then search executes its validated QueryRequest.\nRefinements use the same canonical full-DSL validator, not keyword substitution.\n\nAuthenticated row filters are enforced on every initial and generated\noperation in both modes, including scans, aggregates, and graph/tree\ntraversal. They cannot be replaced or weakened by model tool arguments.\n",
  "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/RetrievalAgentRequest",
  "type": "object",
  "required": [
    "query",
    "queries"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "User's natural language query"
    },
    "queries": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/QueryRequest"
      },
      "description": "Queries to execute. Each query carries its own table via the\nQueryRequest table field.\n\nIn pipeline mode (max_internal_iterations=0), these are executed directly.\nIn agentic mode, these declare which table and indexes are available.\n\n`filter_query` and `exclusion_query` are mandatory table predicates\nfor retrieval-agent execution. Predicates declared by any query for\na table are conjoined (or unioned for exclusions) and applied to\nevery initial query, generated refinement, probe, aggregation,\ngraph/tree traversal, root scan, and follow-up for that table.\nThey cannot be weakened by generated operations.\n"
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChatMessage"
      },
      "description": "Optional conversational context for the current turn. Decisions remain the authoritative continuation input for bounded agent interactions."
    },
    "agent_knowledge": {
      "type": "string",
      "description": "Domain-specific knowledge to include in the agent's system prompt.\nUseful for providing context about the document collection.\n"
    },
    "accumulated_filters": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FilterSpec"
      },
      "description": "Mandatory filters from prior interactions. These are converted to\nstructured Antfly predicates and applied to every table and every\nsearch tool invocation, including generated follow-ups, graph/tree\ntraversal, aggregations, and root scans.\n"
    },
    "session_id": {
      "type": "string",
      "description": "Correlation identifier for a bounded agent interaction. This is echoed back to the client and does not imply server-side session persistence."
    },
    "decisions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentDecision"
      },
      "description": "Structured answers provided by the user as part of client-carried continuation."
    },
    "interactive": {
      "type": "boolean",
      "default": true,
      "description": "If true, the agent may return clarification questions when needed."
    },
    "max_internal_iterations": {
      "type": "integer",
      "minimum": 0,
      "maximum": 20,
      "default": 0,
      "description": "Maximum number of model-generation rounds across retrieval and any\ndelegated query-builder calls. All calls share the request deadline\nand cancellation. Tool calls are additionally capped at 20 overall.\n\n- 0: Pipeline mode — execute provided queries directly, no LLM loop\n- 1+: Agentic mode — LLM decides which tools to call\n"
    },
    "max_user_clarifications": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10,
      "description": "Maximum number of clarification turns the agent may request from the user."
    },
    "require_decision_after": {
      "type": "integer",
      "minimum": 0,
      "maximum": 20,
      "description": "Force a user-facing decision after this many unresolved internal passes."
    },
    "max_context_tokens": {
      "type": "integer",
      "description": "Maximum tokens for document context in tool responses. Documents\nexceeding this limit are pruned to fit.\n"
    },
    "reserve_tokens": {
      "type": "integer",
      "description": "Tokens to reserve for system prompt, answer generation, and other overhead.\nSubtracted from max_context_tokens to determine available context budget.\nDefaults to 4000 if max_context_tokens is set.\n",
      "default": 4000,
      "minimum": 0
    },
    "stream": {
      "type": "boolean",
      "default": true,
      "description": "Enable SSE streaming vs JSON response"
    },
    "generator": {
      "$ref": "#/$defs/GeneratorConfig",
      "description": "Generator for the retrieval agent's LLM calls"
    },
    "chain": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChainLink"
      },
      "description": "Chain of generators"
    },
    "tools": {
      "$ref": "#/$defs/ChatToolsConfig",
      "description": "Default tool policy for this agent run. Step-specific tool policies\nnarrow this default for their step; retrieval currently uses\nsteps.retrieval.tools.\n"
    },
    "steps": {
      "$ref": "#/$defs/RetrievalAgentSteps",
      "description": "Step configuration"
    },
    "document_renderer": {
      "type": "string",
      "description": "Handlebars template that renders each retrieved document in the\ngeneration prompt. Requires steps.generation to be set.\n\nThe template is rendered once per hit against `{id, score, fields}`,\nwhere `fields` is the hit's source. When omitted, each document's\nfields are encoded as TOON (Token-Oriented Object Notation), which\ncarries the same structure as JSON in fewer tokens.\n\nHelpers: `encodeToon` (options `indent`, 1 to 16, default 2; and\n`delimiter`: `comma`, `tab`, or `pipe`), `scrubHtml`, `eq`, and\n`media`. Values in `{{...}}` are HTML-escaped; use `{{{...}}}` for\nraw text.\n\nExamples:\n- `{{encodeToon this.fields}}`\n- `{{encodeToon this.fields delimiter=\"tab\"}}`\n- `Title: {{{this.fields.title}}}`\n"
    }
  },
  "$defs": {
    "AgentDecision": {
      "type": "object",
      "required": [
        "question_id"
      ],
      "properties": {
        "question_id": {
          "type": "string",
          "description": "The question being answered"
        },
        "answer": {
          "description": "User answer, scalar or structured depending on the question kind"
        },
        "approved": {
          "type": "boolean",
          "description": "Used for confirm/review steps where the draft may be accepted as-is"
        }
      }
    },
    "AggregationDateRange": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the date range bucket"
        },
        "from": {
          "type": "string",
          "x-go-type-skip-optional-pointer": false,
          "description": "Start date (ISO 8601 or relative like \"now-7d\")"
        },
        "to": {
          "type": "string",
          "x-go-type-skip-optional-pointer": false,
          "description": "End date (ISO 8601 or relative like \"now\")"
        }
      }
    },
    "AggregationRange": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the range bucket"
        },
        "from": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-type-skip-optional-pointer": false,
          "description": "Lower bound (inclusive)"
        },
        "to": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-type-skip-optional-pointer": false,
          "description": "Upper bound (exclusive)"
        }
      }
    },
    "AggregationRequest": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "$ref": "#/$defs/AggregationType"
        },
        "field": {
          "type": "string",
          "description": "Field to aggregate on. Required unless `fields` is supplied for a multi-field terms aggregation."
        },
        "mode": {
          "x-go-type-skip-optional-pointer": false,
          "allOf": [
            {
              "$ref": "#/$defs/CardinalityMode"
            }
          ],
          "description": "Selection mode for a cardinality aggregation. `auto` (default) uses a materialized HyperLogLog sketch when one applies and is current, else falls back to an exact distinct scan. `exact` always scans. `approximate` requires a sketch and errors if none applies. Ignored for other types."
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Ordered field list for multi-field terms aggregations. Each bucket key is a JSON string containing the serialized value array in the same order; clients should parse bucket.key as JSON."
        },
        "size": {
          "type": "integer",
          "x-go-type-skip-optional-pointer": false,
          "description": "Maximum number of buckets to return (for bucketing aggregations)"
        },
        "ranges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AggregationRange"
          },
          "description": "Ranges for range aggregations"
        },
        "date_ranges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AggregationDateRange"
          },
          "description": "Date ranges for date_range aggregations"
        },
        "interval": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-type-skip-optional-pointer": false,
          "description": "Fixed interval for histogram aggregations"
        },
        "calendar_interval": {
          "x-go-type-skip-optional-pointer": false,
          "allOf": [
            {
              "$ref": "#/$defs/CalendarInterval"
            }
          ],
          "description": "Calendar-aware interval for date_histogram aggregations"
        },
        "origin": {
          "type": "string",
          "x-go-type-skip-optional-pointer": false,
          "description": "Origin for geohash_grid aggregation (format: \"lat,lon\")\nExample: \"37.7749,-122.4194\"\n"
        },
        "precision": {
          "type": "integer",
          "x-go-type-skip-optional-pointer": false,
          "description": "Geohash precision (1-12) for geohash_grid aggregations"
        },
        "distance_ranges": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DistanceRange"
          },
          "description": "Distance ranges for geo_distance aggregations"
        },
        "unit": {
          "x-go-type-skip-optional-pointer": false,
          "allOf": [
            {
              "$ref": "#/$defs/DistanceUnit"
            }
          ],
          "description": "Distance unit for geo_distance aggregations"
        },
        "min_doc_count": {
          "type": "integer",
          "x-go-type-skip-optional-pointer": false,
          "description": "Minimum document count for a bucket to be included"
        },
        "background_filter": {
          "$ref": "#/$defs/RawQuery",
          "description": "Background filter for significant_terms aggregations"
        },
        "algorithm": {
          "x-go-type-skip-optional-pointer": false,
          "allOf": [
            {
              "$ref": "#/$defs/SignificanceAlgorithm"
            }
          ],
          "description": "Significance algorithm for significant_terms aggregations"
        },
        "algebraic_join": {
          "$ref": "#/$defs/AlgebraicAggregationJoin",
          "description": "Algebraic join descriptor for bounded cross-table aggregation planning"
        },
        "sub_aggregations": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/AggregationRequest"
          },
          "description": "Nested sub-aggregations"
        }
      }
    },
    "AggregationType": {
      "type": "string",
      "enum": [
        "sum",
        "avg",
        "min",
        "max",
        "count",
        "sumsquares",
        "stats",
        "cardinality",
        "terms",
        "range",
        "date_range",
        "histogram",
        "date_histogram",
        "geohash_grid",
        "geo_distance",
        "significant_terms"
      ],
      "description": "Type of aggregation to compute:\n- Metrics: sum, avg, min, max, count, sumsquares, stats, cardinality\n- Bucketing: terms, range, date_range, histogram, date_histogram\n- Geo: geohash_grid, geo_distance\n- Analytics: significant_terms\n"
    },
    "AlgebraicAggregationJoin": {
      "type": "object",
      "required": [
        "name",
        "group_side",
        "measure_side"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Algebraic join materialization or capability name"
        },
        "kind": {
          "type": "string",
          "enum": [
            "none",
            "bucket",
            "window",
            "bucket_window"
          ],
          "x-go-type-skip-optional-pointer": false,
          "description": "Temporal join mode for the algebraic materialization"
        },
        "group_side": {
          "type": "string",
          "description": "Join side that supplies grouping bucket values"
        },
        "measure_side": {
          "type": "string",
          "description": "Join side that supplies metric values"
        }
      }
    },
    "Analyses": {
      "x-go-type-skip-optional-pointer": false,
      "type": "object",
      "properties": {
        "pca": {
          "type": "boolean"
        },
        "tsne": {
          "type": "boolean"
        }
      }
    },
    "AntflyGeneratorConfig": {
      "type": "object",
      "description": "Configuration for the Antfly inference generative AI provider.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "antfly"
          ]
        },
        "model": {
          "type": "string",
          "description": "The name of the generator model."
        },
        "api_url": {
          "type": "string",
          "format": "uri",
          "description": "The URL of the Inference API endpoint. Can also be set via ANTFLY_INFERENCE_URL environment variable."
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-2.0).",
          "minimum": 0.0,
          "maximum": 2.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter.",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "top_k": {
          "type": "integer",
          "description": "Top-k sampling parameter."
        },
        "timeout": {
          "type": "integer",
          "description": "HTTP response timeout in seconds for Inference API calls.",
          "minimum": 1
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "AntflyRerankerConfig": {
      "type": "object",
      "description": "Configuration for the Antfly inference reranking provider.",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "antfly"
          ]
        },
        "api_key": {
          "type": "string",
          "description": "Optional bearer API key for remote Antfly inference. Supports secret references and defaults to ANTFLY_INFERENCE_API_KEY. Embedded inference does not resolve or use outbound credentials."
        },
        "model": {
          "type": "string",
          "description": "Optional reranking model name. When omitted, Antfly inference selects a model from its reranker model directory. Set this explicitly when more than one local reranker is installed."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The URL of the Inference API endpoint. Can also be set via ANTFLY_INFERENCE_URL environment variable."
        }
      },
      "required": [
        "provider"
      ]
    },
    "AnthropicGeneratorConfig": {
      "type": "object",
      "description": "Configuration for the Anthropic generative AI provider.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "anthropic"
          ]
        },
        "workspace_id": {
          "type": "string",
          "description": "Anthropic workspace for keys not scoped to a workspace. Defaults to ANTHROPIC_WORKSPACE_ID."
        },
        "model": {
          "type": "string",
          "description": "The full model ID of the Anthropic model to use.",
          "default": "claude-sonnet-4-5-20250929"
        },
        "api_key": {
          "type": "string",
          "writeOnly": true,
          "description": "Anthropic API key or secret reference. Defaults to ANTHROPIC_API_KEY."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Messages API base URL. Defaults to https://api.anthropic.com/v1."
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-1.0).",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate in the response."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter (0.0-1.0).",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "top_k": {
          "type": "integer",
          "description": "Top-k sampling parameter."
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "AppleGeneratorConfig": {
      "type": "object",
      "description": "On-device Apple Foundation Models generation. Requires a macOS Apple provider build, Apple Intelligence enabled, and its system model ready. Supports text conversations; tool calling and media attachments are not supported.",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "apple"
          ]
        },
        "max_tokens": {
          "type": "integer",
          "minimum": 1,
          "default": 256
        },
        "temperature": {
          "type": "number",
          "minimum": 0,
          "maximum": 2
        }
      }
    },
    "AutocompleteQuery": {
      "type": "object",
      "additionalProperties": false,
      "description": "Analyzed bool-prefix search on a logical field. The planner selects\ndeclared search-as-you-type root, shingle and prefix representations.\nRequires a compatible representation; never silently becomes raw prefix search.\n",
      "required": [
        "autocomplete",
        "field"
      ],
      "properties": {
        "autocomplete": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "minLength": 1
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "BedrockGeneratorConfig": {
      "type": "object",
      "description": "AWS Bedrock Converse generation, including image inputs and tools for\nmodels that support them. Uses the AWS default credential chain unless\nan explicit Bedrock API key is configured. Image capability is declared\nper target through inference_capabilities; model IDs are not allowlisted.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "bedrock"
          ]
        },
        "url": {
          "type": "string",
          "description": "Optional Bedrock Runtime endpoint override. Defaults to the regional AWS endpoint."
        },
        "api_key": {
          "type": "string",
          "description": "Optional Bedrock bearer API key or secret reference. Omit to use signed AWS requests and the default credential chain."
        },
        "model": {
          "type": "string",
          "description": "The Bedrock model ID to use."
        },
        "region": {
          "type": "string",
          "description": "AWS region. Defaults to AWS_REGION, then AWS_DEFAULT_REGION, then us-east-1."
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-1.0).",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter.",
          "minimum": 0.0,
          "maximum": 1.0
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "BoolFieldQuery": {
      "type": "object",
      "properties": {
        "bool": {
          "type": "boolean"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "bool"
      ]
    },
    "BoolQuery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bool"
      ],
      "description": "Canonical Boolean wrapper. Must clauses score; filter clauses constrain without scoring.",
      "properties": {
        "bool": {
          "$ref": "#/$defs/BoolQueryBody"
        }
      }
    },
    "BoolQueryBody": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "must": {
          "$ref": "#/$defs/BoolQueryClause"
        },
        "should": {
          "$ref": "#/$defs/BoolQueryClause"
        },
        "must_not": {
          "$ref": "#/$defs/BoolQueryClause"
        },
        "filter": {
          "$ref": "#/$defs/BoolQueryClause"
        },
        "minimum_should_match": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "description": "Minimum optional clauses required; omission follows the runtime's required-clause defaults."
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "BoolQueryClause": {
      "oneOf": [
        {
          "$ref": "#/$defs/Query"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Query"
          }
        }
      ]
    },
    "BooleanQuery": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "must": {
          "$ref": "#/$defs/ConjunctionQuery"
        },
        "should": {
          "$ref": "#/$defs/DisjunctionQuery"
        },
        "must_not": {
          "$ref": "#/$defs/DisjunctionQuery"
        },
        "filter": {
          "$ref": "#/$defs/Query"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "Boost": {
      "type": [
        "number",
        "null"
      ],
      "format": "double",
      "description": "A floating-point number used to decrease or increase the relevance scores of a query.",
      "default": 1.0
    },
    "BraveSearchConfig": {
      "type": "object",
      "description": "Configuration for Brave Search API.\n\nBrave Search provides privacy-focused search with its own independent index.\n\n**Setup:**\n1. Sign up at https://brave.com/search/api/\n2. Get API key from dashboard\n\n**Docs:** https://api.search.brave.com/app/documentation\n",
      "allOf": [
        {
          "$ref": "#/$defs/WebSearchConfig"
        },
        {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "brave"
              ]
            },
            "api_key": {
              "type": "string",
              "description": "Brave Search API key (or set BRAVE_API_KEY env var)"
            },
            "freshness": {
              "type": "string",
              "enum": [
                "pd",
                "pw",
                "pm",
                "py"
              ],
              "description": "Freshness filter: pd=day, pw=week, pm=month, py=year"
            },
            "text_decorations": {
              "type": "boolean",
              "description": "Include text decorations (bold, italic markers)"
            },
            "spellcheck": {
              "type": "boolean",
              "description": "Enable spellcheck suggestions"
            }
          }
        }
      ]
    },
    "CalendarInterval": {
      "type": "string",
      "enum": [
        "minute",
        "hour",
        "day",
        "week",
        "month",
        "quarter",
        "year"
      ],
      "description": "Calendar-aware interval for date_histogram aggregations"
    },
    "CardinalityMode": {
      "type": "string",
      "enum": [
        "auto",
        "exact",
        "approximate"
      ],
      "description": "Exact-vs-approximate selection for a cardinality aggregation:\n- auto: use a materialized HyperLogLog sketch when one applies and is\n  current, else an exact distinct scan (default).\n- exact: always compute an exact distinct count.\n- approximate: require a matching sketch; error if none applies.\n"
    },
    "CatalogTableTarget": {
      "type": "object",
      "description": "An explicit native table target. Components are literal names; dots do not qualify a string table name.",
      "properties": {
        "database": {
          "type": "string",
          "default": "default"
        },
        "namespace": {
          "type": "string",
          "default": "public"
        },
        "table": {
          "type": "string"
        }
      },
      "required": [
        "table"
      ],
      "additionalProperties": false
    },
    "ChainCondition": {
      "type": "string",
      "enum": [
        "always",
        "on_error",
        "on_timeout",
        "on_rate_limit"
      ],
      "default": "on_error",
      "description": "Condition for trying the next generator in chain:\n- always: Always try next regardless of outcome\n- on_error: Try next on any error (default)\n- on_timeout: Try next only on timeout errors\n- on_rate_limit: Try next only on rate limit errors\n"
    },
    "ChainLink": {
      "type": "object",
      "description": "A single link in a generator chain with optional retry and condition",
      "required": [
        "generator"
      ],
      "properties": {
        "generator": {
          "$ref": "#/$defs/GeneratorConfig"
        },
        "retry": {
          "$ref": "#/$defs/RetryConfig",
          "description": "Retry configuration for this generator"
        },
        "condition": {
          "$ref": "#/$defs/ChainCondition",
          "description": "When to try the next generator in chain"
        }
      }
    },
    "ChatGPTGeneratorConfig": {
      "type": "object",
      "description": "Personal ChatGPT plan for interactive generation. Credentials stay in the local runtime.",
      "required": [
        "provider",
        "model",
        "connection_id"
      ],
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "chatgpt"
          ]
        },
        "reasoning_effort": {
          "$ref": "#/$defs/OpenAIReasoningEffort"
        },
        "model": {
          "type": "string"
        },
        "connection_id": {
          "type": "string",
          "description": "Opaque personal registration owned by the authenticated caller."
        }
      }
    },
    "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"
    },
    "ChatToolName": {
      "type": "string",
      "description": "Available tool names for retrieval agents.\n- add_filter: Add search filters (field constraints)\n- ask_clarification: Ask user for clarification\n- web_search: Search the web (requires web_search_connection or web_search_config)\n- fetch: Fetch URL content (subject to security controls)\n- semantic_search: Execute semantic/vector search against an index\n- full_text_search: Execute full-text BM25 search against an index\n- tree_search: Execute tree search with beam search navigation\n- graph_search: Execute graph traversal search\n- aggregate: Execute aggregations against an index\n",
      "enum": [
        "add_filter",
        "ask_clarification",
        "web_search",
        "fetch",
        "semantic_search",
        "full_text_search",
        "tree_search",
        "graph_search",
        "aggregate"
      ]
    },
    "ChatToolsConfig": {
      "type": "object",
      "description": "Configuration for retrieval agent tools.\n\nIf `enabled_tools` is empty/omitted, retrieval agents default to all retrieval tools\navailable for the request. Explicit retrieval policies should use semantic_search\nfor vector retrieval.\n\nFor models that don't support native tool calling (e.g., Ollama),\na prompt-based fallback is used with structured output parsing.\n",
      "properties": {
        "enabled_tools": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChatToolName"
          },
          "description": "List of tools to enable. If empty, retrieval agents default to all retrieval\ntools available for the request.\n"
        },
        "web_search_config": {
          "$ref": "#/$defs/WebSearchProviderConfig",
          "description": "Inline web search provider configuration. Prefer web_search_connection for\nconfigured production agents; inline config remains useful for CLI/dev\nrequests. See specs/openapi/antfly/websearch.yaml for provider-specific\noptions.\n"
        },
        "web_search_connection": {
          "type": "string",
          "description": "Name of a configured connections.<id> resource with kind web_search.\nRequest-level tool options may reduce scope, but cannot expand the\nconnection's configured capabilities or policy.\n"
        },
        "fetch_config": {
          "$ref": "#/$defs/FetchConfig",
          "description": "URL fetching configuration. See specs/openapi/antfly/websearch.yaml\nfor available options and security controls.\n"
        },
        "max_tool_iterations": {
          "type": "integer",
          "default": 5,
          "minimum": 1,
          "maximum": 20,
          "description": "Maximum number of tool call iterations per turn.\nPrevents infinite loops in tool execution.\n"
        }
      }
    },
    "ClassificationStepConfig": {
      "type": "object",
      "description": "Configuration for the classification step. This step analyzes the query,\nselects the optimal retrieval strategy, and generates semantic transformations.\n",
      "properties": {
        "enabled": {
          "type": "boolean",
          "deprecated": true,
          "description": "Compatibility switch. The step is enabled when this object is present; omit the step to disable it."
        },
        "with_reasoning": {
          "type": "boolean",
          "default": false,
          "description": "Include pre-retrieval reasoning explaining query analysis and strategy selection"
        },
        "force_strategy": {
          "$ref": "#/$defs/QueryStrategy",
          "description": "Override LLM strategy selection. If not set, the LLM chooses optimal strategy."
        },
        "force_semantic_mode": {
          "$ref": "#/$defs/SemanticQueryMode",
          "description": "Override semantic query mode selection."
        }
      }
    },
    "CloudflareGeneratorConfig": {
      "type": "object",
      "description": "Cloudflare Workers AI generation. Uses CLOUDFLARE_API_TOKEN or an Antfly secret reference.",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "cloudflare"
          ]
        },
        "account_id": {
          "type": "string",
          "minLength": 1
        },
        "gateway_id": {
          "type": "string",
          "minLength": 1,
          "description": "Optional AI Gateway ID, sent through cf-aig-gateway-id."
        },
        "model": {
          "type": "string",
          "default": "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
        },
        "api_key": {
          "type": "string",
          "writeOnly": true
        },
        "url": {
          "type": "string",
          "description": "Optional deployment-owned endpoint override."
        },
        "max_tokens": {
          "type": "integer",
          "minimum": 1
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "minimum": 0,
          "maximum": 2
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "minimum": 0,
          "maximum": 1
        },
        "frequency_penalty": {
          "type": "number",
          "format": "float",
          "minimum": -2,
          "maximum": 2
        },
        "presence_penalty": {
          "type": "number",
          "format": "float",
          "minimum": -2,
          "maximum": 2
        }
      },
      "required": [
        "provider",
        "account_id",
        "model"
      ]
    },
    "CloudflareRerankerConfig": {
      "type": "object",
      "description": "Cloudflare Workers AI reranking. Uses CLOUDFLARE_API_TOKEN or an Antfly secret reference.",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "cloudflare"
          ]
        },
        "account_id": {
          "type": "string",
          "minLength": 1
        },
        "gateway_id": {
          "type": "string",
          "minLength": 1,
          "description": "Optional AI Gateway ID, sent through cf-aig-gateway-id."
        },
        "model": {
          "type": "string",
          "default": "@cf/baai/bge-reranker-base"
        },
        "api_key": {
          "type": "string",
          "writeOnly": true
        },
        "url": {
          "type": "string",
          "description": "Optional deployment-owned endpoint override."
        }
      },
      "required": [
        "provider",
        "account_id",
        "model"
      ]
    },
    "CohereRerankerConfig": {
      "type": "object",
      "description": "Configuration for the Cohere reranking provider.\n\nAPI key via `api_key` field or `COHERE_API_KEY` environment variable.\n\n**Example Models:** rerank-english-v3.0 (default), rerank-multilingual-v3.0\n\n**Docs:** https://docs.cohere.com/reference/rerank",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "cohere"
          ]
        },
        "model": {
          "type": "string",
          "description": "The name of the Cohere reranking model to use.",
          "default": "rerank-english-v3.0"
        },
        "api_key": {
          "type": "string",
          "description": "The Cohere API key. Can also be set via COHERE_API_KEY environment variable."
        }
      },
      "required": [
        "provider"
      ]
    },
    "ConfidenceStepConfig": {
      "type": "object",
      "description": "Configuration for confidence assessment. Evaluates answer quality and\nresource relevance. Can use a model calibrated for scoring tasks.\n",
      "properties": {
        "enabled": {
          "type": "boolean",
          "deprecated": true,
          "description": "Compatibility switch. The step is enabled when this object is present; omit the step to disable it."
        }
      }
    },
    "ConjunctionQuery": {
      "type": "object",
      "properties": {
        "conjuncts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Query"
          }
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "conjuncts"
      ]
    },
    "ContainsQuery": {
      "type": "object",
      "additionalProperties": false,
      "description": "Contiguous substring search on the original logical field value, including whitespace and punctuation.\nNo normalization is applied. Case-sensitive by default; case_sensitive=false\nuses Unicode simple case folding, not locale-specific or multi-character folding.\nMissing, null, and non-string values do not match. Arrays use any-element\nsemantics; a match never spans array elements. Indexes select conservative\ncandidates and original values are verified before counting and pagination.\n",
      "required": [
        "contains",
        "field"
      ],
      "properties": {
        "contains": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "minLength": 1,
          "description": "Logical source field path, not a companion index name."
        },
        "case_sensitive": {
          "type": "boolean",
          "default": true,
          "x-go-type-skip-optional-pointer": false
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "ContentPart": {
      "description": "A content part for multimodal input (text, image URL, or inline media).",
      "oneOf": [
        {
          "$ref": "#/$defs/TextContentPart"
        },
        {
          "$ref": "#/$defs/ImageURLContentPart"
        },
        {
          "$ref": "#/$defs/MediaContentPart"
        }
      ]
    },
    "Credentials": {
      "type": "object",
      "properties": {
        "endpoint": {
          "type": "string",
          "description": "S3-compatible endpoint (e.g., 's3.amazonaws.com' or 'localhost:9000' for MinIO)",
          "minLength": 1
        },
        "use_ssl": {
          "type": "boolean",
          "description": "Enable SSL/TLS for S3 connections (default: true for AWS, false for local MinIO)",
          "default": true
        },
        "access_key_id": {
          "type": "string",
          "description": "AWS access key ID. Supports secret-store references. Falls back to AWS_ACCESS_KEY_ID when not set."
        },
        "secret_access_key": {
          "type": "string",
          "description": "AWS secret access key. Supports secret-store references. Falls back to AWS_SECRET_ACCESS_KEY when not set."
        },
        "session_token": {
          "type": "string",
          "description": "Optional AWS session token for temporary credentials. Supports secret-store references."
        }
      }
    },
    "DateRangeStringQuery": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "start": {
          "type": "string",
          "format": "date-time",
          "x-go-type-skip-optional-pointer": false
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_start": {
          "type": [
            "boolean",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_end": {
          "type": [
            "boolean",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        },
        "datetime_parser": {
          "type": "string"
        }
      }
    },
    "DisjunctionQuery": {
      "type": "object",
      "properties": {
        "disjuncts": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Query"
          }
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        },
        "min": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "x-go-type-skip-optional-pointer": false,
          "description": "Minimum number of disjuncts that must match. Omit for conventional disjunction semantics; set to 0 to make a pure disjunction optional."
        }
      },
      "required": [
        "disjuncts"
      ]
    },
    "DistanceRange": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Name of the distance range bucket"
        },
        "from": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-type-skip-optional-pointer": false,
          "description": "Minimum distance (inclusive)"
        },
        "to": {
          "type": "number",
          "format": "float",
          "x-go-type": "float64",
          "x-go-type-skip-optional-pointer": false,
          "description": "Maximum distance (exclusive)"
        }
      }
    },
    "DistanceUnit": {
      "type": "string",
      "enum": [
        "m",
        "km",
        "mi",
        "ft",
        "yd"
      ],
      "description": "Distance unit for geo aggregations:\n- m: meters\n- km: kilometers\n- mi: miles\n- ft: feet\n- yd: yards\n"
    },
    "DocIdQuery": {
      "type": "object",
      "properties": {
        "ids": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "ids"
      ]
    },
    "EdgeDirection": {
      "x-go-type-skip-optional-pointer": true,
      "type": "string",
      "enum": [
        "out",
        "in",
        "both"
      ],
      "default": "out",
      "description": "Direction of edges to query:\n- out: Outgoing edges from the node\n- in: Incoming edges to the node\n- both: Both outgoing and incoming edges\n"
    },
    "Embedding": {
      "oneOf": [
        {
          "type": "array",
          "items": {
            "type": "number",
            "format": "float"
          },
          "description": "Dense embedding as an array of floats, e.g. `[0.1, 0.2, 0.3]`"
        },
        {
          "type": "object",
          "required": [
            "indices",
            "values"
          ],
          "properties": {
            "indices": {
              "type": "array",
              "items": {
                "type": "integer",
                "x-go-type": "uint32"
              }
            },
            "values": {
              "type": "array",
              "items": {
                "type": "number",
                "format": "float"
              }
            }
          },
          "description": "Sparse embedding with `indices` and `values` arrays"
        },
        {
          "type": "string",
          "format": "byte",
          "description": "Packed dense embedding as a base64-encoded string of raw little-endian float32 bytes.\nThis is ~4x more compact than the JSON array format. For example, a 3-dimensional\nvector `[1.0, 2.0, 3.0]` is encoded as base64(12 bytes of little-endian float32s).\n"
        },
        {
          "type": "object",
          "required": [
            "packed_indices",
            "packed_values"
          ],
          "properties": {
            "packed_indices": {
              "type": "string",
              "format": "byte",
              "description": "Base64-encoded little-endian uint32 bytes for sparse indices"
            },
            "packed_values": {
              "type": "string",
              "format": "byte",
              "description": "Base64-encoded little-endian float32 bytes for sparse values"
            }
          },
          "description": "Packed sparse embedding with base64-encoded indices and values.\nSame semantics as the sparse object format but more compact on the wire.\n"
        }
      ]
    },
    "EqualsQuery": {
      "type": "object",
      "additionalProperties": false,
      "description": "Whole string equality on the original logical field value.\nNo normalization is applied. Case-sensitive by default; case_sensitive=false\nuses Unicode simple case folding, not locale-specific or multi-character folding.\nMissing, null, and non-string values do not match. Arrays use any-element\nsemantics; a match never spans array elements. Indexes select conservative\ncandidates and original values are verified before counting and pagination.\n",
      "required": [
        "equals",
        "field"
      ],
      "properties": {
        "equals": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "minLength": 1,
          "description": "Logical source field path, not a companion index name."
        },
        "case_sensitive": {
          "type": "boolean",
          "default": true,
          "x-go-type-skip-optional-pointer": false
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "EvalConfig": {
      "type": "object",
      "x-go-type-skip-optional-pointer": true,
      "description": "Configuration for inline evaluation of query results.\nAdd to RetrievalAgentRequest, QueryRequest, or other evaluation-capable request schemas.\n",
      "properties": {
        "evaluators": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EvaluatorName"
          },
          "description": "List of evaluators to run"
        },
        "judge": {
          "$ref": "#/$defs/GeneratorConfig",
          "description": "LLM configuration for judge-based evaluators.\nFalls back to default if not specified.\n"
        },
        "ground_truth": {
          "$ref": "#/$defs/GroundTruth",
          "description": "Ground truth data for retrieval metrics"
        },
        "options": {
          "$ref": "#/$defs/EvalOptions",
          "description": "Evaluation options (k, thresholds, etc.)"
        }
      }
    },
    "EvalOptions": {
      "type": "object",
      "description": "Options for evaluation behavior",
      "properties": {
        "k": {
          "type": "integer",
          "default": 10,
          "minimum": 1,
          "maximum": 100,
          "description": "K value for @K metrics (precision@k, recall@k, ndcg@k)"
        },
        "pass_threshold": {
          "type": "number",
          "format": "float",
          "default": 0.5,
          "minimum": 0.0,
          "maximum": 1.0,
          "description": "Score threshold for pass/fail determination"
        },
        "timeout_seconds": {
          "type": "integer",
          "default": 30,
          "minimum": 1,
          "maximum": 300,
          "description": "Timeout for evaluation in seconds"
        }
      }
    },
    "EvaluatorName": {
      "type": "string",
      "enum": [
        "recall",
        "precision",
        "ndcg",
        "mrr",
        "map",
        "relevance",
        "faithfulness",
        "completeness",
        "coherence",
        "safety",
        "helpfulness",
        "correctness",
        "citation_quality"
      ],
      "description": "Available evaluator types:\n\n**Retrieval metrics** (require ground_truth.relevant_ids):\n- recall: Recall@k - fraction of relevant docs retrieved\n- precision: Precision@k - fraction of retrieved docs that are relevant\n- ndcg: Normalized Discounted Cumulative Gain\n- mrr: Mean Reciprocal Rank\n- map: Mean Average Precision\n\n**LLM-as-judge metrics** (require judge config):\n- relevance: Is output relevant to query? (works on retrieval-only too)\n- faithfulness: Is output grounded in context?\n- completeness: Does output fully address query?\n- coherence: Is output well-structured?\n- safety: Is output safe/appropriate?\n- helpfulness: Is output useful?\n- correctness: Is output factually correct? (uses expectations)\n- citation_quality: Are citations accurate?\n"
    },
    "ExaSearchConfig": {
      "type": "object",
      "description": "Configuration for Exa neural/semantic web search.\n\nExa is optimized for semantic web search, highlights, and retrieved page\ncontents for RAG and agent workflows.\n\n**Setup:**\n1. Sign up at https://exa.ai\n2. Get API key from dashboard\n\n**Docs:** https://docs.exa.ai\n",
      "allOf": [
        {
          "$ref": "#/$defs/WebSearchConfig"
        },
        {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "exa"
              ]
            },
            "api_key": {
              "type": "string",
              "description": "Exa API key (or set EXA_API_KEY env var)"
            },
            "search_type": {
              "type": "string",
              "enum": [
                "auto",
                "neural",
                "keyword"
              ],
              "description": "Search mode to request from Exa"
            },
            "num_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "description": "Provider-specific result count override"
            },
            "start_published_date": {
              "type": "string",
              "description": "ISO date/time lower bound for published date filtering"
            },
            "end_published_date": {
              "type": "string",
              "description": "ISO date/time upper bound for published date filtering"
            },
            "include_domains": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Only include results from these domains"
            },
            "exclude_domains": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Exclude results from these domains"
            }
          }
        }
      ]
    },
    "FetchConfig": {
      "type": "object",
      "description": "Configuration for URL content fetching.\n\nUses Antfly's content fetcher for downloading and processing. Supports:\n- HTTP/HTTPS URLs with security validation\n- HTML pages (extracts readable text via go-readability)\n- PDF files (extracts text)\n- Images (returns as data URIs)\n- Plain text files\n- S3 URLs (requires s3_credentials)\n\nSecurity features include:\n- Allowed host whitelist\n- Private IP blocking (SSRF prevention)\n- Download size limits\n- Timeout controls\n",
      "properties": {
        "s3_credentials": {
          "description": "S3 credentials for fetching S3 URLs. If not set, uses package-level defaults.",
          "$ref": "#/$defs/Credentials"
        },
        "max_content_length": {
          "type": "integer",
          "default": 50000,
          "description": "Maximum content length in characters (truncated if exceeded)"
        },
        "allowed_hosts": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Whitelist of allowed hostnames for fetching.\nIf empty, all hosts are allowed (except private IPs).\nExample: [\"docs.example.com\", \"api.example.com\"]\n"
        },
        "block_private_ips": {
          "x-go-type-skip-optional-pointer": false,
          "type": "boolean",
          "default": true,
          "description": "Block requests to private IP ranges (SSRF prevention).\nBlocked: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16\n"
        },
        "max_download_size_bytes": {
          "type": "integer",
          "default": 104857600,
          "description": "Maximum download size in bytes (default: 100MB)"
        },
        "timeout_seconds": {
          "type": "integer",
          "default": 30,
          "description": "Download timeout in seconds"
        }
      }
    },
    "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)"
        }
      }
    },
    "FollowupStepConfig": {
      "type": "object",
      "description": "Configuration for deterministic follow-up suggestions derived from the\noriginal query and the standard Antfly follow-up templates.\n",
      "properties": {
        "enabled": {
          "type": "boolean",
          "deprecated": true,
          "description": "Compatibility switch. The step is enabled when this object is present; omit the step to disable it."
        },
        "count": {
          "type": "integer",
          "default": 3,
          "minimum": 1,
          "maximum": 4,
          "description": "Number of follow-up questions to generate"
        }
      }
    },
    "ForeignColumn": {
      "type": "object",
      "required": [
        "name",
        "type"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Column name in the foreign table."
        },
        "type": {
          "type": "string",
          "description": "Column data type. Used for filter validation and type coercion.\nCommon types: text, integer, bigint, float, boolean, timestamp, uuid, jsonb.\n"
        },
        "nullable": {
          "type": "boolean",
          "description": "Whether the column allows NULL values.",
          "default": false
        }
      }
    },
    "ForeignSource": {
      "type": "object",
      "required": [
        "type",
        "dsn",
        "postgres_table"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of the foreign data source. Currently only \"postgres\" is supported.\n",
          "enum": [
            "postgres"
          ]
        },
        "dsn": {
          "type": "string",
          "description": "Data source name (connection string) for the foreign database.\nSupports `${secret:key_name}` references that resolve from the Antfly secret store\nor environment variables.\n"
        },
        "postgres_table": {
          "type": "string",
          "description": "Name of the table or view in the foreign PostgreSQL database to query.\n"
        },
        "columns": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ForeignColumn"
          },
          "description": "Optional column definitions for the foreign table. If omitted, columns are\nauto-discovered from `information_schema.columns` on first query.\n"
        }
      }
    },
    "Fuzziness": {
      "description": "The fuzziness of the query. Can be an integer or \"auto\".",
      "anyOf": [
        {
          "type": "integer",
          "format": "int32",
          "minimum": 0,
          "maximum": 2
        },
        {
          "type": "string",
          "enum": [
            "auto"
          ]
        }
      ]
    },
    "FuzzyQuery": {
      "type": "object",
      "properties": {
        "term": {
          "type": "string"
        },
        "prefix_length": {
          "type": "integer",
          "format": "int32",
          "minimum": 0,
          "maximum": 255
        },
        "fuzziness": {
          "$ref": "#/$defs/Fuzziness"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "term"
      ]
    },
    "GenerationStepConfig": {
      "type": "object",
      "description": "Configuration for the generation step. This step generates the final\nresponse from retrieved documents using the reasoning as context.\n",
      "properties": {
        "enabled": {
          "type": "boolean",
          "deprecated": true,
          "description": "Compatibility switch. The step is enabled when this object is present; omit the step to disable it."
        },
        "generator": {
          "$ref": "#/$defs/GeneratorConfig",
          "description": "Canonical generator configuration for this step. When omitted, the top-level request generator is used."
        },
        "chain": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ChainLink"
          },
          "description": "Chain of generators to try in order. Mutually exclusive with 'generator'."
        },
        "system_prompt": {
          "type": "string",
          "description": "Custom system prompt for answer generation"
        },
        "generation_context": {
          "type": "string",
          "description": "Custom guidance for generation tone, detail level, and style"
        }
      }
    },
    "GeneratorConfig": {
      "description": "A unified configuration for a generative AI provider.\n",
      "allOf": [
        {
          "oneOf": [
            {
              "$ref": "#/$defs/CloudflareGeneratorConfig"
            },
            {
              "$ref": "#/$defs/GoogleGeneratorConfig"
            },
            {
              "$ref": "#/$defs/VertexGeneratorConfig"
            },
            {
              "$ref": "#/$defs/BedrockGeneratorConfig"
            },
            {
              "$ref": "#/$defs/AnthropicGeneratorConfig"
            },
            {
              "$ref": "#/$defs/OllamaGeneratorConfig"
            },
            {
              "$ref": "#/$defs/AntflyGeneratorConfig"
            },
            {
              "$ref": "#/$defs/ChatGPTGeneratorConfig"
            },
            {
              "$ref": "#/$defs/OpenAIGeneratorConfig"
            },
            {
              "$ref": "#/$defs/OpenRouterGeneratorConfig"
            },
            {
              "$ref": "#/$defs/AppleGeneratorConfig"
            }
          ]
        },
        {
          "properties": {
            "max_image_input_tokens": {
              "x-go-type-skip-optional-pointer": false,
              "type": "integer",
              "format": "int64",
              "minimum": 1,
              "description": "Conservative input-token ceiling per image. Required for image calls when tokens_per_minute is configured; choose a bound valid for the model and image policy."
            },
            "rate_limit": {
              "x-go-type-skip-optional-pointer": false,
              "$ref": "#/$defs/RateLimitConfig"
            },
            "provider": {
              "$ref": "#/$defs/GeneratorProvider"
            }
          },
          "required": [
            "provider"
          ]
        }
      ]
    },
    "GeneratorProvider": {
      "type": "string",
      "enum": [
        "cloudflare",
        "gemini",
        "vertex",
        "bedrock",
        "anthropic",
        "ollama",
        "openai",
        "chatgpt",
        "openrouter",
        "antfly",
        "apple"
      ],
      "description": "Generator providers implemented by Antfly's generation runtime."
    },
    "GeoBoundingBoxQuery": {
      "type": "object",
      "description": "Geographic bounding box filter. The public query shape uses scalar latitude and longitude bounds to match structured filter_query.geo_bbox. Longitude ranges may cross the antimeridian by specifying a western/min longitude that is greater than the eastern/max longitude; for example, min_lon 179.5 and max_lon -179.5 matches points near +/-180 degrees longitude. Latitude bounds must be ordered with min_lat <= max_lat.\n",
      "properties": {
        "field": {
          "type": "string",
          "description": "Field or path containing geo_point values."
        },
        "min_lat": {
          "type": "number",
          "format": "double",
          "minimum": -90,
          "maximum": 90,
          "description": "Southern latitude bound."
        },
        "min_lon": {
          "type": "number",
          "format": "double",
          "minimum": -180,
          "maximum": 180,
          "description": "Western longitude bound. If greater than max_lon, the box crosses the antimeridian."
        },
        "max_lat": {
          "type": "number",
          "format": "double",
          "minimum": -90,
          "maximum": 90,
          "description": "Northern latitude bound. Must be greater than or equal to min_lat."
        },
        "max_lon": {
          "type": "number",
          "format": "double",
          "minimum": -180,
          "maximum": 180,
          "description": "Eastern longitude bound. May be less than min_lon for antimeridian-wrapped boxes."
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "field",
        "min_lat",
        "min_lon",
        "max_lat",
        "max_lon"
      ]
    },
    "GeoBoundingPolygonQuery": {
      "type": "object",
      "properties": {
        "polygon_points": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/GeoPoint"
          }
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "polygon_points"
      ]
    },
    "GeoDistanceQuery": {
      "type": "object",
      "properties": {
        "location": {
          "type": "array",
          "items": {
            "type": "number",
            "format": "double"
          },
          "minItems": 2,
          "maxItems": 2,
          "description": "[lon, lat]"
        },
        "distance": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "location",
        "distance"
      ]
    },
    "GeoPoint": {
      "type": "object",
      "properties": {
        "lon": {
          "type": "number",
          "format": "double"
        },
        "lat": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "GeoShape": {
      "type": "object",
      "description": "A GeoJSON shape object. This is a simplified representation.",
      "properties": {
        "type": {
          "type": "string"
        },
        "coordinates": {
          "type": "array",
          "items": {}
        }
      },
      "required": [
        "type",
        "coordinates"
      ]
    },
    "GeoShapeGeometry": {
      "type": "object",
      "properties": {
        "shape": {
          "$ref": "#/$defs/GeoShape"
        },
        "relation": {
          "type": "string",
          "enum": [
            "intersects",
            "contains",
            "within"
          ]
        }
      },
      "required": [
        "shape",
        "relation"
      ]
    },
    "GeoShapeQuery": {
      "type": "object",
      "properties": {
        "geometry": {
          "$ref": "#/$defs/GeoShapeGeometry"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "geometry"
      ]
    },
    "GoogleGeneratorConfig": {
      "type": "object",
      "description": "Configuration for the Google generative AI provider (Gemini).\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "gemini"
          ]
        },
        "project_id": {
          "type": "string",
          "description": "The Google Cloud project ID."
        },
        "location": {
          "type": "string",
          "description": "The Google Cloud location (e.g., 'us-central1')."
        },
        "model": {
          "type": "string",
          "description": "The name of the generative model to use.",
          "default": "gemini-2.5-flash"
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-2.0).",
          "minimum": 0.0,
          "maximum": 2.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter.",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "top_k": {
          "type": "integer",
          "description": "Top-k sampling parameter."
        },
        "api_key": {
          "type": "string",
          "writeOnly": true,
          "description": "The Google API key."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The URL of the Google API endpoint."
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "GraphAggregatesReturn": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "aggregates"
      ],
      "properties": {
        "aggregates": {
          "type": "object",
          "minProperties": 1,
          "maxProperties": 64,
          "additionalProperties": {
            "$ref": "#/$defs/GraphCountAggregate"
          },
          "x-antfly-property-name-schema": {
            "$ref": "#/$defs/GraphIdentifier"
          },
          "description": "Keys are GraphIdentifiers naming aggregate results."
        }
      }
    },
    "GraphAliasCountAggregate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "count"
      ],
      "properties": {
        "count": {
          "$ref": "#/$defs/GraphIdentifier",
          "description": "Count bindings in which this alias is non-null. An unmatched optional alias does not increment the count."
        },
        "distinct": {
          "type": "boolean",
          "default": false,
          "description": "Count exact table-qualified identities. Exact distinct sets share a request resource budget and fail with `graph_distinct_budget_exceeded` instead of returning a partial count."
        }
      }
    },
    "GraphAliasOperand": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "alias"
      ],
      "properties": {
        "alias": {
          "$ref": "#/$defs/GraphIdentifier"
        }
      }
    },
    "GraphBindingsReturn": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bindings"
      ],
      "properties": {
        "bindings": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphIdentifier"
          }
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "default": 100
        },
        "include_documents": {
          "type": "boolean",
          "default": false,
          "description": "Hydrate documents for projected non-null bindings when they exist at the pinned snapshot. A dangling graph identity omits document. When false, document is always omitted. The product of `limit` and the number of projected bindings may not exceed 10,000. Table-qualified bindings are hydrated by coordinator-backed deployments; runtimes with only a source-table snapshot reject such requests instead of silently omitting an available document."
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Document fields to hydrate. Requires include_documents=true; omit to include all fields."
        }
      }
    },
    "GraphCountAggregate": {
      "oneOf": [
        {
          "$ref": "#/$defs/GraphRowCountAggregate"
        },
        {
          "$ref": "#/$defs/GraphAliasCountAggregate"
        }
      ],
      "description": "Exact count(*) or count(alias). The distinct option exists only for alias counts, making distinct count(*) invalid by schema and at runtime. count(*) includes null-extended optional rows; count(alias) counts only bindings where that alias is non-null."
    },
    "GraphDocumentBoolFieldBody": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "path",
        "value"
      ],
      "properties": {
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        },
        "value": {
          "type": "boolean"
        }
      }
    },
    "GraphDocumentBoolFieldFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bool_field"
      ],
      "properties": {
        "bool_field": {
          "$ref": "#/$defs/GraphDocumentBoolFieldBody"
        }
      }
    },
    "GraphDocumentDateRangeBody": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "path"
      ],
      "not": {
        "allOf": [
          {
            "not": {
              "required": [
                "start"
              ]
            }
          },
          {
            "not": {
              "required": [
                "end"
              ]
            }
          }
        ]
      },
      "description": "At least one of start or end is required and enforced by every Antfly execution boundary. Bounds are RFC 3339 instants in Antfly's unsigned Unix-nanosecond domain, from 1970-01-01T00:00:00Z through 2554-07-21T23:34:33.709551615Z inclusive. When both are present, start must not exceed end after offset normalization.",
      "properties": {
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        },
        "start": {
          "type": "string",
          "format": "date-time",
          "x-go-type-skip-optional-pointer": false
        },
        "end": {
          "type": "string",
          "format": "date-time",
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_start": {
          "type": "boolean",
          "default": true,
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_end": {
          "type": "boolean",
          "default": false,
          "x-go-type-skip-optional-pointer": false
        }
      }
    },
    "GraphDocumentDateRangeFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "date_range"
      ],
      "properties": {
        "date_range": {
          "$ref": "#/$defs/GraphDocumentDateRangeBody"
        }
      }
    },
    "GraphDocumentFilter": {
      "oneOf": [
        {
          "$ref": "#/$defs/GraphDocumentFuzzyFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentTermFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentPrefixFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentRegexpFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentWildcardFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentNumericRangeFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentTermRangeFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentDateRangeFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentMatchAllFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentMatchNoneFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentIdsFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentBoolFieldFilter"
        },
        {
          "$ref": "#/$defs/GraphDocumentFilterBoolean"
        },
        {
          "$ref": "#/$defs/GraphDocumentFilterConjunction"
        },
        {
          "$ref": "#/$defs/GraphDocumentFilterDisjunction"
        }
      ],
      "description": "A non-scoring stored-document predicate embedded at a graph node. It uses structurally distinct stored-field predicates and deliberately excludes analyzer-backed full-text clauses such as match, phrase, multi_match, and query_string. Fuzzy predicates require an explicit fuzziness. Range predicates use numeric_range, term_range, or date_range wrappers, and every stored value is addressed by an RFC 6901 JSON Pointer in `path`. Alias-to-alias predicates belong in GraphMatch.where."
    },
    "GraphDocumentFilterBoolean": {
      "type": "object",
      "additionalProperties": false,
      "minProperties": 1,
      "description": "Stored-document boolean predicate. `must` and `filter` are required clauses; `should` uses its disjunction threshold; and `must_not` negates its thresholded disjunction as one group. Thus a `must_not.min` of N excludes a document only when at least N of that group's clauses match.",
      "properties": {
        "must": {
          "$ref": "#/$defs/GraphDocumentFilterConjunction"
        },
        "should": {
          "$ref": "#/$defs/GraphDocumentFilterDisjunction"
        },
        "must_not": {
          "$ref": "#/$defs/GraphDocumentFilterDisjunction"
        },
        "filter": {
          "$ref": "#/$defs/GraphDocumentFilter"
        }
      }
    },
    "GraphDocumentFilterConjunction": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "conjuncts"
      ],
      "properties": {
        "conjuncts": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphDocumentFilter"
          }
        }
      }
    },
    "GraphDocumentFilterDisjunction": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "disjuncts"
      ],
      "properties": {
        "disjuncts": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphDocumentFilter"
          }
        },
        "min": {
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "maximum": 64,
          "x-go-type-skip-optional-pointer": false,
          "description": "Minimum number of disjuncts that must match. Omit for conventional context-sensitive disjunction semantics; set to 0 to impose no matching-clause requirement. Under `must_not`, the complete thresholded disjunction is negated as one group."
        }
      }
    },
    "GraphDocumentFuzzyFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "term",
        "path",
        "fuzziness"
      ],
      "properties": {
        "term": {
          "type": "string"
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        },
        "fuzziness": {
          "$ref": "#/$defs/Fuzziness",
          "description": "Required so fuzzy and exact term predicates remain structurally distinct."
        },
        "prefix_length": {
          "type": "integer",
          "format": "int32",
          "minimum": 0,
          "maximum": 255
        }
      }
    },
    "GraphDocumentIdsFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "ids"
      ],
      "properties": {
        "ids": {
          "type": "array",
          "minItems": 1,
          "maxItems": 10000,
          "uniqueItems": true,
          "items": {
            "type": "string"
          }
        }
      }
    },
    "GraphDocumentMatchAllFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "match_all"
      ],
      "properties": {
        "match_all": {
          "type": "object",
          "additionalProperties": false
        }
      }
    },
    "GraphDocumentMatchNoneFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "match_none"
      ],
      "properties": {
        "match_none": {
          "type": "object",
          "additionalProperties": false
        }
      }
    },
    "GraphDocumentNumericRangeBody": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "path"
      ],
      "not": {
        "allOf": [
          {
            "not": {
              "required": [
                "min"
              ]
            }
          },
          {
            "not": {
              "required": [
                "max"
              ]
            }
          }
        ]
      },
      "description": "At least one of min or max is required and enforced by every Antfly execution boundary. When both are present, min must not exceed max.",
      "properties": {
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        },
        "min": {
          "type": "number",
          "format": "double",
          "x-go-type-skip-optional-pointer": false
        },
        "max": {
          "type": "number",
          "format": "double",
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_min": {
          "type": "boolean",
          "default": true,
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_max": {
          "type": "boolean",
          "default": false,
          "x-go-type-skip-optional-pointer": false
        }
      }
    },
    "GraphDocumentNumericRangeFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "numeric_range"
      ],
      "properties": {
        "numeric_range": {
          "$ref": "#/$defs/GraphDocumentNumericRangeBody"
        }
      }
    },
    "GraphDocumentPrefixFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "prefix",
        "path"
      ],
      "properties": {
        "prefix": {
          "type": "string"
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        }
      }
    },
    "GraphDocumentRegexpFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "regexp",
        "path"
      ],
      "properties": {
        "regexp": {
          "type": "string"
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        }
      }
    },
    "GraphDocumentTermFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "term",
        "path"
      ],
      "properties": {
        "term": {
          "type": "string"
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        }
      }
    },
    "GraphDocumentTermRangeBody": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "path"
      ],
      "not": {
        "allOf": [
          {
            "not": {
              "required": [
                "min"
              ]
            }
          },
          {
            "not": {
              "required": [
                "max"
              ]
            }
          }
        ]
      },
      "description": "At least one of min or max is required and enforced by every Antfly execution boundary.",
      "properties": {
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        },
        "min": {
          "type": "string",
          "x-go-type-skip-optional-pointer": false
        },
        "max": {
          "type": "string",
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_min": {
          "type": "boolean",
          "default": true,
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_max": {
          "type": "boolean",
          "default": false,
          "x-go-type-skip-optional-pointer": false
        }
      }
    },
    "GraphDocumentTermRangeFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "term_range"
      ],
      "properties": {
        "term_range": {
          "$ref": "#/$defs/GraphDocumentTermRangeBody"
        }
      }
    },
    "GraphDocumentWildcardFilter": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "wildcard",
        "path"
      ],
      "properties": {
        "wildcard": {
          "type": "string"
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "pattern": "^/",
          "description": "RFC 6901 JSON Pointer to the stored-document value."
        }
      }
    },
    "GraphEdgeType": {
      "type": "string",
      "minLength": 1,
      "maxLength": 65536,
      "x-antfly-max-utf8-bytes": 65536,
      "description": "Durable graph edge type. Values must be valid UTF-8 and encode to at most 64 KiB; `maxLength` is the standard-schema code-point ceiling and `x-antfly-max-utf8-bytes` carries the exact wire-byte limit."
    },
    "GraphEdgeWeightRange": {
      "type": "object",
      "additionalProperties": false,
      "minProperties": 1,
      "description": "Inclusive per-edge weight filter. At least one bound is required. Bounds must be finite and non-negative; when both are present, min must not exceed max. This filters individual stored edges and does not constrain the aggregate path objective.",
      "properties": {
        "min": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "x-go-type-skip-optional-pointer": false
        },
        "max": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "x-go-type-skip-optional-pointer": false
        }
      }
    },
    "GraphIdentifier": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "not": {
        "enum": [
          "*"
        ]
      },
      "description": "User-visible graph alias or named result under Antfly graph identifier policy v1 (Unicode 15.0.0). Identifiers are exact UTF-8 strings and are not normalized. Ordinary internal ASCII spaces are allowed. The value must not equal `*`, begin with `$`, have leading or trailing spaces, contain non-ASCII Unicode White_Space, or contain Unicode Cc control or Cf format code points. UTF-8 encoding is limited to 512 bytes.",
      "x-antfly-identifier-policy": {
        "version": 1,
        "unicodeVersion": "15.0.0",
        "maxUtf8Bytes": 512,
        "reservedExact": [
          "*"
        ],
        "reservedPrefixes": [
          "$"
        ],
        "disallowedCodePointRanges": [
          [
            "0000",
            "001F"
          ],
          [
            "007F",
            "00A0"
          ],
          [
            "00AD",
            "00AD"
          ],
          [
            "0600",
            "0605"
          ],
          [
            "061C",
            "061C"
          ],
          [
            "06DD",
            "06DD"
          ],
          [
            "070F",
            "070F"
          ],
          [
            "0890",
            "0891"
          ],
          [
            "08E2",
            "08E2"
          ],
          [
            "1680",
            "1680"
          ],
          [
            "180E",
            "180E"
          ],
          [
            "2000",
            "200F"
          ],
          [
            "2028",
            "202F"
          ],
          [
            "205F",
            "2064"
          ],
          [
            "2066",
            "206F"
          ],
          [
            "3000",
            "3000"
          ],
          [
            "D800",
            "DFFF"
          ],
          [
            "FEFF",
            "FEFF"
          ],
          [
            "FFF9",
            "FFFB"
          ],
          [
            "110BD",
            "110BD"
          ],
          [
            "110CD",
            "110CD"
          ],
          [
            "13430",
            "1343F"
          ],
          [
            "1BCA0",
            "1BCA3"
          ],
          [
            "1D173",
            "1D17A"
          ],
          [
            "E0001",
            "E0001"
          ],
          [
            "E0020",
            "E007F"
          ]
        ]
      }
    },
    "GraphIdentityNodeSelector": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "identities"
      ],
      "properties": {
        "identities": {
          "type": "array",
          "minItems": 1,
          "maxItems": 10000,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphPathEndpoint"
          },
          "description": "Exact node identities. Omitted table means the query table."
        }
      }
    },
    "GraphKShortestPaths": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "from",
        "to",
        "k"
      ],
      "description": "Find up to `k` loopless paths from `from` to `to` in the requested stored-edge direction. Results are unique by ordered table-qualified node identities plus stored-edge direction, type, edge ID and fact owner, and are ordered best-first by the selected objective.",
      "properties": {
        "edge_filter": {
          "$ref": "#/$defs/GraphRelationshipFilter"
        },
        "from": {
          "$ref": "#/$defs/GraphPathEndpoint"
        },
        "to": {
          "$ref": "#/$defs/GraphPathEndpoint"
        },
        "direction": {
          "$ref": "#/$defs/EdgeDirection",
          "description": "Stored-edge direction relative to each expanded path node; defaults to `out`."
        },
        "k": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100
        },
        "edge_types": {
          "type": "array",
          "maxItems": 64,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphEdgeType"
          },
          "description": "At most 64 unique edge types totaling at most 64 KiB."
        },
        "max_depth": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64,
          "default": 10
        },
        "edge_weight": {
          "x-go-type-skip-optional-pointer": false,
          "$ref": "#/$defs/GraphEdgeWeightRange"
        },
        "objective": {
          "$ref": "#/$defs/GraphPathObjective",
          "default": "min_hops"
        },
        "filter": {
          "$ref": "#/$defs/GraphDocumentFilter",
          "description": "Non-scoring structured stored-document predicate for path nodes."
        },
        "include_documents": {
          "type": "boolean",
          "default": false,
          "description": "Attach each terminal stored document as paths[].document when it exists at the pinned snapshot. A dangling terminal identity omits document. When false, document is always omitted."
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Requires include_documents=true. Omit to include all document fields."
        }
      }
    },
    "GraphKShortestPathsQuery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "index",
        "k_shortest_paths"
      ],
      "properties": {
        "index": {
          "type": "string",
          "minLength": 1,
          "pattern": ".*\\S.*"
        },
        "k_shortest_paths": {
          "$ref": "#/$defs/GraphKShortestPaths"
        }
      }
    },
    "GraphKeyNodeSelector": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "keys"
      ],
      "properties": {
        "keys": {
          "type": "array",
          "minItems": 1,
          "maxItems": 10000,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Exact keys in the table being queried."
        }
      }
    },
    "GraphMatch": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "anchor",
        "nodes",
        "edges"
      ],
      "description": "`anchor` names the alias enumerated from the query table as the source relation. Every other alias is reached through graph edges and may resolve to a table-qualified target identity. An `ids` filter, or a disjunction made only of `ids` filters, uses the table's primary identity access path and needs no secondary index. Stored-field predicates and row-level authorization filters on the anchor must have native index coverage so Antfly can enumerate the complete relation in `_id` order; otherwise the request fails with `graph_anchor_filter_requires_index`.",
      "properties": {
        "anchor": {
          "$ref": "#/$defs/GraphIdentifier"
        },
        "nodes": {
          "type": "object",
          "minProperties": 1,
          "maxProperties": 64,
          "additionalProperties": {
            "$ref": "#/$defs/GraphMatchNode"
          },
          "x-antfly-property-name-schema": {
            "$ref": "#/$defs/GraphIdentifier"
          },
          "description": "Keys are GraphIdentifiers naming aliases in the required match."
        },
        "edges": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphMatchEdge"
          }
        },
        "where": {
          "$ref": "#/$defs/GraphWhereExpression"
        },
        "optional": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphOptionalMatch"
          },
          "description": "Ordered correlated left-outer patterns. Aliases introduced by an earlier item are visible to later items, including as null."
        }
      }
    },
    "GraphMatchEdge": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "from",
        "to"
      ],
      "description": "Structural edge expansion from the `from` alias to the `to` alias. Direction defaults to `out`; use `in` to reverse the stored edge or `both` to match an undirected relationship without duplicating stored edges. A fixed single-hop relationship preserves physical self-loops and may bind two distinct aliases to the same node identity. Variable-length expansion uses node-simple paths: a (table, key) identity is visited at most once within one expanded edge path, except when closing onto an already bound target alias for an explicit cycle. Exact distributed and serverless execution rejects planner-required reverse variable expansion when the source tables of unnamed intermediate nodes cannot be proven. Express cross-table multi-hop patterns as explicit single-hop edges with a table-qualified alias at each table boundary.",
      "properties": {
        "edge_filter": {
          "$ref": "#/$defs/GraphRelationshipFilter"
        },
        "from": {
          "$ref": "#/$defs/GraphIdentifier"
        },
        "to": {
          "$ref": "#/$defs/GraphIdentifier"
        },
        "direction": {
          "$ref": "#/$defs/EdgeDirection",
          "description": "Stored-edge direction relative to `from`; defaults to `out`."
        },
        "types": {
          "type": "array",
          "maxItems": 64,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphEdgeType"
          },
          "description": "Empty or omitted matches every edge type; otherwise at most 64 unique types totaling at most 64 KiB."
        },
        "min_hops": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64,
          "default": 1
        },
        "max_hops": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64,
          "default": 1
        },
        "edge_weight": {
          "x-go-type-skip-optional-pointer": false,
          "$ref": "#/$defs/GraphEdgeWeightRange"
        }
      }
    },
    "GraphMatchNode": {
      "type": "object",
      "additionalProperties": false,
      "description": "Declared under an alias of at most 128 Unicode code points. Omit table for the queried table. Declare it for a cross-table alias that may be used as the source of a relationship, including planner-selected reverse expansion of a branched pattern.",
      "properties": {
        "table": {
          "type": "string",
          "minLength": 1,
          "pattern": "[^ \\t\\r\\n]",
          "description": "Owning table for this alias. Omit for the queried table."
        },
        "filter": {
          "$ref": "#/$defs/GraphDocumentFilter",
          "description": "Non-scoring structured stored-document predicate evaluated for this alias. Serverless execution rejects document filters on aliases qualified with a different table because its published snapshot contains only the queried table. Explicitly qualifying an alias with the queried table is equivalent to omitting `table`."
        }
      }
    },
    "GraphMatchQuery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "index",
        "match",
        "return"
      ],
      "description": "Conjunctive graph match over the complete authorized source universe. Top-level retrieval queries and filters do not scope that universe; put source constraints on the node named by match.anchor. Results are exact or the request fails; execution never labels a partial aggregate exact. Source anchors are streamed in stable snapshot-pinned pages and charged to the request-wide `scanned_anchors` work dimension; transient expansion state remains bounded, and execution observes request deadlines, cancellation, and server resource admission. Exact distinct identity sets are also bounded and fail closed when their request-scoped memory budget is exhausted.",
      "properties": {
        "index": {
          "type": "string",
          "minLength": 1,
          "pattern": ".*\\S.*"
        },
        "match": {
          "$ref": "#/$defs/GraphMatch"
        },
        "return": {
          "$ref": "#/$defs/GraphReturn"
        }
      }
    },
    "GraphMetricFilter": {
      "type": "object",
      "required": [
        "metric",
        "op",
        "value"
      ],
      "properties": {
        "metric": {
          "type": "string",
          "minLength": 1
        },
        "op": {
          "type": "string",
          "description": "Semantic comparison operator. Named values keep generated SDK enums portable and readable.",
          "enum": [
            "gt",
            "gte",
            "lt",
            "lte",
            "eq",
            "neq"
          ]
        },
        "value": {
          "type": "number",
          "format": "double"
        }
      }
    },
    "GraphMetricOrder": {
      "type": "object",
      "required": [
        "metric"
      ],
      "properties": {
        "metric": {
          "type": "string",
          "minLength": 1
        },
        "direction": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "nulls": {
          "type": "string",
          "enum": [
            "first",
            "last",
            "nulls_first",
            "nulls_last"
          ]
        }
      }
    },
    "GraphMetricQuery": {
      "type": "object",
      "description": "Reads a published graph metric. Score-bearing graph metric queries on multi-shard tables require a globally coordinated metric snapshot and otherwise return graph_metric_global_materialization_required instead of merging mathematically incompatible shard-local scores.",
      "required": [
        "index",
        "metric"
      ],
      "properties": {
        "direction": {
          "$ref": "#/$defs/EdgeDirection",
          "description": "Direction of query-time personalized PageRank; defaults to out. Requires seed_nodes and metric_freshness=fresh. Both treats every selected relationship as undirected, allowing entity seeds to reach documents through incoming mention edges."
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "Optional result key. Defaults to the metric name."
        },
        "index": {
          "type": "string",
          "minLength": 1,
          "description": "Graph index that owns the published metric."
        },
        "metric": {
          "type": "string",
          "minLength": 1,
          "description": "Graph metric to read."
        },
        "top_k": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 10000,
          "default": 10,
          "description": "Maximum ranked metric scores to return. Multi-shard tables require a globally coordinated metric snapshot."
        },
        "metric_freshness": {
          "type": "string",
          "enum": [
            "published",
            "fresh"
          ],
          "default": "published",
          "description": "Whether the latest published generation may be stale or must match the graph edge generation."
        },
        "seed_nodes": {
          "type": "array",
          "maxItems": 128,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Node keys receiving all teleport mass for query-seeded personalized PageRank (HippoRAG-style retrieval). Only valid for pagerank metrics and requires metric_freshness=fresh: personalized scores are computed at query time from the current edge snapshot, while published generations are global-only, so seeded reads against published freshness are rejected. Seed keys absent from the graph are skipped; if none resolve, ranking degenerates to global PageRank."
        },
        "damping": {
          "type": "number",
          "format": "double",
          "description": "Damping override for query-seeded personalized PageRank (typical HippoRAG-style retrieval uses 0.9). Only valid together with seed_nodes; omitted reads keep the metric's configured damping.",
          "exclusiveMinimum": 0,
          "exclusiveMaximum": 1
        }
      }
    },
    "GraphMetricRerank": {
      "type": "object",
      "description": "Blends a published graph metric into hit scores. Multi-shard tables require a globally coordinated metric snapshot and otherwise return graph_metric_global_materialization_required.",
      "required": [
        "index",
        "metric"
      ],
      "properties": {
        "direction": {
          "$ref": "#/$defs/EdgeDirection",
          "description": "Direction of query-time personalized PageRank; defaults to out. Requires seed_nodes and metric_freshness=fresh. Both treats every selected relationship as undirected, allowing entity seeds to reach documents through incoming mention edges."
        },
        "index": {
          "type": "string",
          "description": "Graph index that owns the published metric."
        },
        "metric": {
          "type": "string",
          "description": "Graph metric name to blend into the search hit score."
        },
        "candidate_count": {
          "type": "integer",
          "format": "int32",
          "minimum": 1,
          "maximum": 10000,
          "description": "Bounded retrieval window scored by the graph metric before offset and limit are applied. When omitted, Antfly uses an adaptive four-times page window, capped at 10,000 candidates. An explicit value must cover offset plus limit. Larger windows improve promotion recall at predictable linear score-read cost."
        },
        "base_weight": {
          "type": "number",
          "format": "double",
          "default": 1.0,
          "description": "Multiplier applied to the existing hit score before adding the graph metric feature."
        },
        "weight": {
          "type": "number",
          "format": "double",
          "default": 1.0,
          "description": "Multiplier applied to the graph metric score before it is added to the existing hit score."
        },
        "missing_score": {
          "type": "number",
          "format": "double",
          "default": 0.0,
          "description": "Metric feature value to use for hits that do not have a score in the published metric generation."
        },
        "metric_freshness": {
          "type": "string",
          "enum": [
            "published",
            "fresh"
          ],
          "default": "published",
          "description": "Whether stale published generations are acceptable or the metric must be fresh."
        },
        "seed_nodes": {
          "type": "array",
          "maxItems": 128,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Node keys receiving all teleport mass for a query-seeded personalized PageRank blend (HippoRAG-style retrieval). Only valid for pagerank metrics and requires metric_freshness=fresh: the blended feature scores are computed at query time from the current edge snapshot, while published generations are global-only, so seeded blends against published freshness are rejected. Seed keys absent from the graph are skipped; if none resolve, the blend degenerates to global PageRank."
        },
        "damping": {
          "type": "number",
          "format": "double",
          "description": "Damping override for the query-seeded personalized PageRank blend. Only valid together with seed_nodes; omitted blends keep the metric's configured damping.",
          "exclusiveMinimum": 0,
          "exclusiveMaximum": 1
        },
        "auto_seed": {
          "type": "boolean",
          "default": false,
          "description": "Seed the personalized PageRank blend from the query's literal graph-search start keys; only valid for pagerank metrics with metric_freshness=fresh. Honored by retrieval-agent queries: caller-supplied seed_nodes always take precedence and are never overwritten, and queries without literal graph-search start keys keep their unseeded (global) blend."
        }
      }
    },
    "GraphNodeSelector": {
      "oneOf": [
        {
          "$ref": "#/$defs/GraphKeyNodeSelector"
        },
        {
          "$ref": "#/$defs/GraphIdentityNodeSelector"
        },
        {
          "$ref": "#/$defs/GraphResultRefNodeSelector"
        }
      ],
      "description": "Select graph nodes using exactly one explicit, exact selector form."
    },
    "GraphNotEqualPredicate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "left",
        "right"
      ],
      "properties": {
        "left": {
          "$ref": "#/$defs/GraphAliasOperand"
        },
        "right": {
          "$ref": "#/$defs/GraphAliasOperand"
        }
      }
    },
    "GraphNotExistsPattern": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "edges"
      ],
      "properties": {
        "edges": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphMatchEdge"
          }
        }
      },
      "description": "Correlated negative-edge predicate over aliases already visible at this point in the MATCH. It does not introduce new aliases."
    },
    "GraphOptionalMatch": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "edges"
      ],
      "description": "One correlated left-outer graph pattern. Optional groups are evaluated in array order and must connect to an alias visible from the required MATCH or an earlier optional group. Each input binding is extended by every matching optional binding; when none match, exactly one binding is retained with every alias introduced by this group set to null.",
      "properties": {
        "nodes": {
          "type": "object",
          "maxProperties": 64,
          "additionalProperties": {
            "$ref": "#/$defs/GraphMatchNode"
          },
          "x-antfly-property-name-schema": {
            "$ref": "#/$defs/GraphIdentifier"
          },
          "description": "Keys are GraphIdentifiers naming aliases introduced by this optional match."
        },
        "edges": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphMatchEdge"
          }
        },
        "where": {
          "$ref": "#/$defs/GraphWhereExpression"
        }
      }
    },
    "GraphPathEndpoint": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key"
      ],
      "properties": {
        "key": {
          "type": "string",
          "minLength": 1
        },
        "table": {
          "x-go-type-skip-optional-pointer": false,
          "type": "string",
          "minLength": 1,
          "pattern": "[^ \\t\\r\\n]",
          "description": "Optional table qualifier for an exact cross-table node identity. Omit for the query table."
        }
      }
    },
    "GraphPathObjective": {
      "type": "string",
      "enum": [
        "min_hops",
        "min_weight_sum",
        "max_weight_product"
      ],
      "description": "Objective used to rank graph paths:\n- min_hops: Minimize the number of edges.\n- min_weight_sum: Minimize the sum of finite non-negative edge weights.\n- max_weight_product: Maximize the product of edge weights, requiring every traversed weight to be in [0,1].\n"
    },
    "GraphQueries": {
      "type": "object",
      "minProperties": 1,
      "maxProperties": 64,
      "additionalProperties": {
        "$ref": "#/$defs/GraphQuery"
      },
      "x-antfly-property-name-schema": {
        "$ref": "#/$defs/GraphIdentifier"
      },
      "description": "Named canonical graph operations. When graph_queries is present it must contain at least one operation. A request may contain at most 64 operations, of which at most eight may be MATCH operations. Keys use the versioned GraphIdentifier policy."
    },
    "GraphQuery": {
      "oneOf": [
        {
          "$ref": "#/$defs/GraphMatchQuery"
        },
        {
          "$ref": "#/$defs/GraphTraverseQuery"
        },
        {
          "$ref": "#/$defs/GraphShortestPathQuery"
        },
        {
          "$ref": "#/$defs/GraphKShortestPathsQuery"
        }
      ]
    },
    "GraphRelationshipFilter": {
      "type": "object",
      "additionalProperties": false,
      "description": "AND predicates applied to every relationship before neighbor admission, path ranking, and match counting. Missing or null properties fail comparisons, including ne; use explicit null operators. Maximum 64 predicates and 64 KiB of predicate fields and values. Time intervals have inclusive lower and exclusive upper bounds. Missing/null valid-time bounds are open; known_at requires a created_at value. Invalid timestamp properties never match.",
      "properties": {
        "properties": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphRelationshipPropertyPredicate"
          }
        },
        "valid_at": {
          "type": "string",
          "format": "date-time",
          "description": "Require metadata.valid_at <= instant < metadata.invalid_at."
        },
        "known_at": {
          "type": "string",
          "format": "date-time",
          "description": "Require metadata.created_at <= instant < metadata.expired_at."
        }
      }
    },
    "GraphRelationshipPropertyPredicate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "field",
        "op"
      ],
      "properties": {
        "field": {
          "type": "string",
          "description": "JSON pointer to /metadata/... or /edge_id, /owner_document, /source, /target, /type, /weight, /created_at, /updated_at."
        },
        "op": {
          "type": "string",
          "enum": [
            "eq",
            "ne",
            "lt",
            "lte",
            "gt",
            "gte",
            "is_null",
            "is_not_null"
          ]
        },
        "value": {
          "description": "Non-null scalar comparison value. Omit for is_null and is_not_null."
        },
        "value_type": {
          "type": "string",
          "enum": [
            "scalar",
            "datetime"
          ],
          "default": "scalar",
          "description": "Datetime compares RFC3339 instants rather than string ordering."
        }
      }
    },
    "GraphResultRefNodeSelector": {
      "description": "Select nodes from a prior graph result. `binding` is valid only when `result_ref` names a prior MATCH result; traversal and path results select their returned or endpoint nodes and prohibit `binding`.",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "result_ref"
      ],
      "properties": {
        "result_ref": {
          "type": "string",
          "x-antfly-graph-result-name-schema": {
            "$ref": "#/$defs/GraphIdentifier"
          },
          "description": "`$query_results` selects the final ranked query results. `$graph_results.<query-name>` selects a prior graph query result. Prior MATCH results require `binding`; traversal and path results prohibit it. A path result selects the endpoint node of each returned path."
        },
        "binding": {
          "$ref": "#/$defs/GraphIdentifier"
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "description": "Maximum referenced results to use. Omit only when the referenced result is complete."
        }
      }
    },
    "GraphReturn": {
      "oneOf": [
        {
          "$ref": "#/$defs/GraphBindingsReturn"
        },
        {
          "$ref": "#/$defs/GraphAggregatesReturn"
        }
      ],
      "description": "Return bindings or exact aggregates. Bindings and aggregates are mutually exclusive."
    },
    "GraphRowCountAggregate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "count"
      ],
      "properties": {
        "count": {
          "$ref": "#/$defs/GraphRowCountTarget"
        }
      }
    },
    "GraphRowCountTarget": {
      "type": "string",
      "enum": [
        "*"
      ],
      "description": "Count every complete graph binding, including a binding retained by an unmatched optional group through null extension."
    },
    "GraphShortestPath": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "from",
        "to"
      ],
      "description": "Find the best path from `from` to `to` in the requested stored-edge direction.",
      "properties": {
        "edge_filter": {
          "$ref": "#/$defs/GraphRelationshipFilter"
        },
        "from": {
          "$ref": "#/$defs/GraphPathEndpoint"
        },
        "to": {
          "$ref": "#/$defs/GraphPathEndpoint"
        },
        "direction": {
          "$ref": "#/$defs/EdgeDirection",
          "description": "Stored-edge direction relative to each expanded path node; defaults to `out`."
        },
        "edge_types": {
          "type": "array",
          "maxItems": 64,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphEdgeType"
          },
          "description": "At most 64 unique edge types totaling at most 64 KiB."
        },
        "max_depth": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64,
          "default": 10
        },
        "edge_weight": {
          "x-go-type-skip-optional-pointer": false,
          "$ref": "#/$defs/GraphEdgeWeightRange"
        },
        "objective": {
          "$ref": "#/$defs/GraphPathObjective",
          "default": "min_hops"
        },
        "filter": {
          "$ref": "#/$defs/GraphDocumentFilter",
          "description": "Non-scoring structured stored-document predicate for path nodes."
        },
        "include_documents": {
          "type": "boolean",
          "default": false,
          "description": "Attach the terminal stored document as paths[].document when it exists at the pinned snapshot. A dangling terminal identity omits document. When false, document is always omitted."
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Requires include_documents=true. Omit to include all document fields."
        }
      }
    },
    "GraphShortestPathQuery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "index",
        "shortest_path"
      ],
      "properties": {
        "index": {
          "type": "string",
          "minLength": 1,
          "pattern": ".*\\S.*"
        },
        "shortest_path": {
          "$ref": "#/$defs/GraphShortestPath"
        }
      }
    },
    "GraphTraversal": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "start"
      ],
      "description": "Breadth-first traversal with request-wide deduplication by exact table-qualified node identity. Direction defaults to `out`; use `both` to traverse a relationship as undirected without storing a reciprocal edge.",
      "properties": {
        "edge_filter": {
          "$ref": "#/$defs/GraphRelationshipFilter"
        },
        "start": {
          "$ref": "#/$defs/GraphNodeSelector"
        },
        "direction": {
          "$ref": "#/$defs/EdgeDirection",
          "description": "Stored-edge direction relative to each expanded node; defaults to `out`."
        },
        "edge_types": {
          "type": "array",
          "maxItems": 64,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphEdgeType"
          },
          "description": "At most 64 unique edge types totaling at most 64 KiB."
        },
        "max_depth": {
          "type": "integer",
          "minimum": 1,
          "maximum": 64,
          "default": 1,
          "description": "Maximum traversal depth. Defaults to one hop to keep fan-out explicit."
        },
        "edge_weight": {
          "x-go-type-skip-optional-pointer": false,
          "$ref": "#/$defs/GraphEdgeWeightRange"
        },
        "limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000,
          "default": 100
        },
        "deduplicate_nodes": {
          "x-go-type-skip-optional-pointer": false,
          "type": "boolean",
          "default": true,
          "description": "Return each node once across all starts. Set false with include_paths to return each reaching path, including its start node. Depth, result, and work limits still bound path enumeration."
        },
        "include_paths": {
          "type": "boolean",
          "default": false
        },
        "include_documents": {
          "type": "boolean",
          "default": false,
          "description": "Include each result node's stored document when it exists at the pinned snapshot. A dangling graph identity omits document. When false, document is always omitted."
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Requires include_documents=true. Omit to include all document fields."
        },
        "metrics": {
          "type": "array",
          "maxItems": 16,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "Graph metric names to project onto returned traversal nodes."
        },
        "order_by": {
          "type": "array",
          "maxItems": 8,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphMetricOrder"
          },
          "description": "Sort traversal candidates by graph metric score before applying limit."
        },
        "where_metric": {
          "type": "array",
          "maxItems": 32,
          "items": {
            "$ref": "#/$defs/GraphMetricFilter"
          },
          "description": "Filter traversal candidates by graph metric score before applying limit."
        },
        "metric_freshness": {
          "type": "string",
          "enum": [
            "published",
            "fresh"
          ],
          "default": "published",
          "description": "Freshness required for projected, ordered, and filtered graph metrics."
        },
        "include_metric_status": {
          "type": "boolean",
          "default": false,
          "description": "Include graph metric status metadata in the traversal profile."
        },
        "filter": {
          "$ref": "#/$defs/GraphDocumentFilter",
          "description": "Non-scoring structured stored-document predicate for reached nodes."
        }
      }
    },
    "GraphTraverseQuery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "index",
        "traverse"
      ],
      "properties": {
        "index": {
          "type": "string",
          "minLength": 1,
          "pattern": ".*\\S.*"
        },
        "traverse": {
          "$ref": "#/$defs/GraphTraversal"
        }
      }
    },
    "GraphWhereAnd": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "and"
      ],
      "properties": {
        "and": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/GraphWhereExpression"
          }
        }
      }
    },
    "GraphWhereExpression": {
      "oneOf": [
        {
          "$ref": "#/$defs/GraphWhereAnd"
        },
        {
          "$ref": "#/$defs/GraphWhereNotEqual"
        },
        {
          "$ref": "#/$defs/GraphWhereNotExists"
        }
      ]
    },
    "GraphWhereNotEqual": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "not_equal"
      ],
      "properties": {
        "not_equal": {
          "$ref": "#/$defs/GraphNotEqualPredicate"
        }
      }
    },
    "GraphWhereNotExists": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "not_exists"
      ],
      "properties": {
        "not_exists": {
          "$ref": "#/$defs/GraphNotExistsPattern"
        }
      }
    },
    "GroundTruth": {
      "type": "object",
      "description": "Ground truth data for evaluation",
      "properties": {
        "relevant_ids": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Document IDs known to be relevant (for retrieval metrics)"
        },
        "expectations": {
          "type": "string",
          "description": "Context for evaluators about what to expect in the response.\nProvides guidance for LLM judges (e.g., \"Should mention pricing tiers\").\n"
        }
      }
    },
    "HierarchyAncestors": {
      "type": "object",
      "additionalProperties": false,
      "minProperties": 1,
      "properties": {
        "source": {
          "$ref": "#/$defs/HierarchyProjection",
          "x-go-type-skip-optional-pointer": false
        },
        "unit": {
          "$ref": "#/$defs/HierarchyProjection",
          "x-go-type-skip-optional-pointer": false
        }
      }
    },
    "HierarchyChildParent": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "level",
        "id"
      ],
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "source"
          ]
        },
        "id": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "HierarchyChildren": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "parent",
        "level"
      ],
      "properties": {
        "parent": {
          "$ref": "#/$defs/HierarchyChildParent"
        },
        "level": {
          "type": "string",
          "enum": [
            "unit"
          ],
          "description": "Child level to enumerate. Unit traversal reads the versioned extraction\nhierarchy rather than a relevance index, so empty and failed units are included.\n"
        }
      }
    },
    "HierarchyChildrenOrderBy": {
      "type": "array",
      "minItems": 1,
      "maxItems": 1,
      "description": "The required public order for sequential hierarchy traversal. Specify\n`_hierarchy.position` ascending; Antfly appends `_id` ascending as the\ndeterministic tie-breaker and returns both values in each hit's `_sort`.\n",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "field"
        ],
        "properties": {
          "field": {
            "type": "string",
            "enum": [
              "_hierarchy.position"
            ]
          },
          "desc": {
            "type": "boolean",
            "enum": [
              false
            ],
            "default": false
          }
        }
      }
    },
    "HierarchyChildrenSearchAfter": {
      "type": "array",
      "minItems": 2,
      "maxItems": 2,
      "description": "Opaque position and unit-id tuple returned in the preceding hit's `_sort`.",
      "items": {
        "type": "string"
      }
    },
    "HierarchyGroupBy": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "level"
      ],
      "properties": {
        "level": {
          "type": "string",
          "enum": [
            "source",
            "unit"
          ],
          "description": "Hierarchy level used to group the records matched by the targeted index.\nUnit groups are relevance-ranked and do not accept `order_by`, `search_after`,\nor `search_before`; use `hierarchy.children` for sequential, cursor-paginated\nunit traversal.\n"
        },
        "matches": {
          "$ref": "#/$defs/HierarchyMatches",
          "x-go-type-skip-optional-pointer": false
        }
      }
    },
    "HierarchyMatches": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "fields"
      ],
      "properties": {
        "limit": {
          "type": "integer",
          "format": "uint32",
          "minimum": 1,
          "maximum": 100,
          "default": 3,
          "description": "Maximum matching descendant hits attached to each group, independent of\nthe top-level query limit. Matches follow the effective query order, and\nthe group score is the score of its best matching descendant. The maximum\nbounds nested response growth. Group selection uses an adaptive candidate\nwindow, then each returned group is expanded with a separately bounded query,\nso a group with fewer matches never forces a global exhaustive scan. To bound\nexecution as well as response growth, grouped queries accept at most 100\ntop-level groups and 1,000 requested matches across the complete result page.\n"
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Fields to include in each nested match. This projection is required because\ngrouped and matching records commonly have different schemas. Use an empty\narray to return match identity and hierarchy metadata without stored fields.\n"
        }
      }
    },
    "HierarchyProjection": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "fields"
      ],
      "properties": {
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Fields to include from the hydrated hierarchy document. This projection is\nrequired whenever the ancestor is requested so hierarchy hydration cannot\naccidentally return an unbounded document. Use an empty array to return\nhierarchy identity without stored document fields.\n"
        }
      }
    },
    "IPRangeQuery": {
      "type": "object",
      "properties": {
        "cidr": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "cidr"
      ]
    },
    "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"
        }
      }
    },
    "JoinClause": {
      "type": "object",
      "description": "Configuration for joining data from another table.\nSupports inner, left, and right joins with automatic strategy selection.\n",
      "required": [
        "on"
      ],
      "properties": {
        "right_target": {
          "$ref": "#/$defs/CatalogTableTarget"
        },
        "right_table": {
          "type": "string",
          "description": "Literal native table name or declared foreign-source alias. Specify exactly one of right_table or right_target."
        },
        "join_type": {
          "$ref": "#/$defs/JoinType",
          "description": "Type of join to perform. Defaults to \"inner\"."
        },
        "on": {
          "$ref": "#/$defs/JoinCondition",
          "description": "Join condition specifying which fields to match."
        },
        "right_filters": {
          "$ref": "#/$defs/JoinFilters",
          "description": "Optional filters to apply to the right table before joining.\nUse to reduce the amount of data being joined.\n"
        },
        "right_fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Fields to include from the right table in the result.\nIf not specified, all fields from the right table are included.\nFields are prefixed with the right table name in the result.\n"
        },
        "strategy_hint": {
          "$ref": "#/$defs/JoinStrategy",
          "description": "Optional hint for which join strategy to use.\nIf not specified, the planner automatically selects based on table statistics.\n"
        },
        "nested_join": {
          "type": [
            "object",
            "null"
          ],
          "allOf": [
            {
              "$ref": "#/$defs/JoinClause"
            }
          ],
          "x-go-type-skip-optional-pointer": false,
          "description": "Optional nested join for multi-way joins.\nThe nested join operates on the result of the current join.\n"
        }
      }
    },
    "JoinCondition": {
      "type": "object",
      "description": "Condition for matching rows between tables.",
      "required": [
        "left_field",
        "right_field"
      ],
      "properties": {
        "left_field": {
          "type": "string",
          "description": "Field from the left (primary) table to match on."
        },
        "right_field": {
          "type": "string",
          "description": "Field from the right (joined) table to match on."
        },
        "operator": {
          "$ref": "#/$defs/JoinOperator",
          "description": "Comparison operator. Defaults to \"eq\" (equality)."
        }
      }
    },
    "JoinFilters": {
      "type": "object",
      "description": "Filters to apply to a table before joining.",
      "properties": {
        "filter_query": {
          "$ref": "#/$defs/RawQuery",
          "description": "Antfly query to filter rows before joining."
        },
        "filter_prefix": {
          "type": "string",
          "format": "byte",
          "description": "Key prefix filter for the table."
        },
        "limit": {
          "type": "integer",
          "description": "Maximum number of rows to include from this table."
        }
      }
    },
    "JoinOperator": {
      "type": "string",
      "enum": [
        "eq",
        "neq",
        "lt",
        "lte",
        "gt",
        "gte"
      ],
      "default": "eq",
      "description": "Comparison operator for join condition:\n- `eq`: Equal (default)\n- `neq`: Not equal\n- `lt`: Less than\n- `lte`: Less than or equal\n- `gt`: Greater than\n- `gte`: Greater than or equal\n"
    },
    "JoinStrategy": {
      "type": "string",
      "enum": [
        "broadcast",
        "index_lookup",
        "shuffle"
      ],
      "description": "Strategy for executing the join:\n- `broadcast`: Broadcast small table to all shards of large table.\n  Best for dimension tables < 10MB. O(small_table) memory per shard.\n- `index_lookup`: Use batch key lookups via indexes.\n  Best for selective joins with indexed join keys. Low memory overhead.\n- `shuffle`: Hash-partition both tables by join key.\n  Best for large-large table joins. Requires data movement.\n"
    },
    "JoinType": {
      "type": "string",
      "enum": [
        "inner",
        "left",
        "right"
      ],
      "default": "inner",
      "description": "Type of join to perform:\n- `inner`: Only return rows with matches in both tables\n- `left`: Return all rows from left table, NULL for non-matching right rows\n- `right`: Return all rows from right table, NULL for non-matching left rows\n"
    },
    "LinkupSearchConfig": {
      "type": "object",
      "description": "Configuration for Linkup Search API.\n\nLinkup is useful for web search, source retrieval, and structured\nresearch workflows.\n\n**Setup:**\n1. Sign up at https://linkup.so\n2. Get API key from dashboard\n\n**Docs:** https://docs.linkup.so\n",
      "allOf": [
        {
          "$ref": "#/$defs/WebSearchConfig"
        },
        {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "linkup"
              ]
            },
            "api_key": {
              "type": "string",
              "description": "Linkup API key (or set LINKUP_API_KEY env var)"
            },
            "depth": {
              "type": "string",
              "enum": [
                "standard",
                "deep"
              ],
              "description": "Search depth to request from Linkup"
            },
            "output_type": {
              "type": "string",
              "enum": [
                "searchResults",
                "sourcedAnswer"
              ],
              "description": "Linkup response shape to request"
            }
          }
        }
      ]
    },
    "MatchAllQuery": {
      "type": "object",
      "properties": {
        "match_all": {
          "type": "object"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "match_all"
      ]
    },
    "MatchNoneQuery": {
      "type": "object",
      "properties": {
        "match_none": {
          "type": "object"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "match_none"
      ]
    },
    "MatchPhraseQuery": {
      "type": "object",
      "description": "Match a phrase using the field's analyzer. On a `substring` companion,\none or two words match contained text across token separators. Three\nor more words are rejected because the suffix index cannot verify\ntheir word boundaries; lookups over 32 bytes are also rejected.\nNonzero or automatic fuzziness is rejected on substring fields; use a standalone fuzzy query instead.\n",
      "properties": {
        "match_phrase": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "analyzer": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        },
        "fuzziness": {
          "$ref": "#/$defs/Fuzziness"
        }
      },
      "required": [
        "match_phrase"
      ]
    },
    "MatchQuery": {
      "type": "object",
      "description": "Analyze the text with the field's analyzer and match any of the\nresulting terms. On a `substring` companion field (`fieldName._substring`)\nthe text is lowercased and matched as a contained substring instead:\n`{\"match\": \"g3we\", \"field\": \"sku._substring\"}` finds `RAG3-WEAVER`.\nSubstring lookups require at least two bytes and reject a token or\nadjacent token pair longer than 32 bytes.\n",
      "properties": {
        "match": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "analyzer": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "match"
      ]
    },
    "MatchesQuery": {
      "type": "object",
      "additionalProperties": false,
      "description": "Unanchored native Unicode regular expression search on the original logical field value. Anchors refer to each complete value; indexed-term regexp semantics are unchanged.\nNo normalization is applied. Case-sensitive by default; case_sensitive=false\nuses Unicode simple case folding, not locale-specific or multi-character folding.\nMissing, null, and non-string values do not match. Arrays use any-element\nsemantics; a match never spans array elements. Indexes select conservative\ncandidates and original values are verified before counting and pagination.\n",
      "required": [
        "matches",
        "field"
      ],
      "properties": {
        "matches": {
          "type": "string"
        },
        "field": {
          "type": "string",
          "minLength": 1,
          "description": "Logical source field path, not a companion index name."
        },
        "case_sensitive": {
          "type": "boolean",
          "default": true,
          "x-go-type-skip-optional-pointer": false
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "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"
        }
      }
    },
    "MergeConfig": {
      "type": "object",
      "description": "Configuration for result fusion when combining multiple search indexes.",
      "properties": {
        "strategy": {
          "$ref": "#/$defs/MergeStrategy"
        },
        "weights": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "format": "double"
          },
          "description": "Named weights keyed by index name. `full_text` for the full-text search index;\nembedding index names for vector indexes.\nUnspecified indexes default to 1.0. Applied in both RRF and RSF.\n"
        },
        "window_size": {
          "x-go-type-skip-optional-pointer": true,
          "type": "integer",
          "minimum": 1,
          "description": "RSF normalization window size. Defaults to `limit`."
        },
        "rank_constant": {
          "x-go-type-skip-optional-pointer": true,
          "type": "number",
          "format": "double",
          "description": "RRF k constant (1/(k+rank)). Defaults to 60.0."
        }
      }
    },
    "MergeStrategy": {
      "type": "string",
      "enum": [
        "rrf",
        "rsf"
      ],
      "default": "rrf",
      "description": "Merge strategy for combining results from the semantic_search and full_text_search.\nrrf: Reciprocal Rank Fusion - combines scores using reciprocal rank formula\nrsf: Relative Score Fusion - normalizes scores by min/max within a window and combines weighted scores\n"
    },
    "MultiMatchBody": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 1
        },
        "type": {
          "type": "string",
          "enum": [
            "bool_prefix"
          ]
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "query",
        "fields",
        "type"
      ]
    },
    "MultiMatchQuery": {
      "type": "object",
      "properties": {
        "multi_match": {
          "$ref": "#/$defs/MultiMatchBody"
        }
      },
      "required": [
        "multi_match"
      ]
    },
    "MultiPhraseQuery": {
      "type": "object",
      "properties": {
        "terms": {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        },
        "fuzziness": {
          "$ref": "#/$defs/Fuzziness"
        }
      },
      "required": [
        "terms"
      ]
    },
    "NumericRangeQuery": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "min": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "x-go-type-skip-optional-pointer": false
        },
        "max": {
          "type": [
            "number",
            "null"
          ],
          "format": "double",
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_min": {
          "type": [
            "boolean",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_max": {
          "type": [
            "boolean",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "OllamaGeneratorConfig": {
      "type": "object",
      "description": "Configuration for the Ollama generative AI provider.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "ollama"
          ]
        },
        "model": {
          "type": "string",
          "description": "The name of the Ollama model to use."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The URL of the Ollama API endpoint."
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-2.0).",
          "minimum": 0.0,
          "maximum": 2.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter.",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "top_k": {
          "type": "integer",
          "description": "Top-k sampling parameter."
        },
        "timeout": {
          "type": "integer",
          "description": "HTTP response timeout in seconds for Ollama API calls.",
          "minimum": 1
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "OpenAIGeneratorConfig": {
      "type": "object",
      "description": "Configuration for the OpenAI generative AI provider.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "openai"
          ]
        },
        "model": {
          "type": "string",
          "description": "The name of the OpenAI model to use.",
          "default": "gpt-4.1"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The URL of the OpenAI API endpoint."
        },
        "api_key": {
          "type": "string",
          "writeOnly": true,
          "description": "The OpenAI API key."
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-2.0).",
          "minimum": 0.0,
          "maximum": 2.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate."
        },
        "max_completion_tokens": {
          "type": "integer",
          "minimum": 1,
          "description": "OpenAI completion budget, including visible output and reasoning tokens.\nUse for reasoning models instead of max_tokens; the two are mutually exclusive.\n"
        },
        "reasoning_effort": {
          "$ref": "#/$defs/OpenAIReasoningEffort",
          "description": "Optional reasoning effort. Supported values depend on the selected OpenAI model."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter.",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "frequency_penalty": {
          "type": "number",
          "format": "float",
          "description": "Penalty for token frequency (-2.0 to 2.0).",
          "minimum": -2.0,
          "maximum": 2.0
        },
        "presence_penalty": {
          "type": "number",
          "format": "float",
          "description": "Penalty for token presence (-2.0 to 2.0).",
          "minimum": -2.0,
          "maximum": 2.0
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "OpenAIReasoningEffort": {
      "type": "string",
      "enum": [
        "none",
        "minimal",
        "low",
        "medium",
        "high",
        "xhigh",
        "max"
      ],
      "description": "OpenAI reasoning effort; model support varies. Omit to use the model default."
    },
    "OpenRouterGeneratorConfig": {
      "type": "object",
      "description": "Configuration for the OpenRouter generative AI provider.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "openrouter"
          ]
        },
        "model": {
          "type": "string",
          "description": "The OpenRouter model identifier to use."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The URL of the OpenRouter API endpoint.",
          "default": "https://openrouter.ai/api/v1"
        },
        "api_key": {
          "type": "string",
          "writeOnly": true,
          "description": "The OpenRouter API key."
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-2.0).",
          "minimum": 0.0,
          "maximum": 2.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate in the response."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter (0.0-1.0).",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "frequency_penalty": {
          "type": "number",
          "format": "float",
          "description": "Penalty for token frequency (-2.0 to 2.0).",
          "minimum": -2.0,
          "maximum": 2.0
        },
        "presence_penalty": {
          "type": "number",
          "format": "float",
          "description": "Penalty for token presence (-2.0 to 2.0).",
          "minimum": -2.0,
          "maximum": 2.0
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "PhraseQuery": {
      "type": "object",
      "properties": {
        "terms": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        },
        "fuzziness": {
          "$ref": "#/$defs/Fuzziness"
        }
      },
      "required": [
        "terms"
      ]
    },
    "PrefixQuery": {
      "type": "object",
      "description": "Match terms that start with the given bytes. On a `substring`\ncompanion field the prefix is lowercased and matched as a contained\nsubstring, exactly like `match` on that field.\n",
      "properties": {
        "case_insensitive": {
          "type": "boolean",
          "default": false,
          "description": "Fold ASCII letter case when matching indexed terms, without stemming the pattern."
        },
        "prefix": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "prefix"
      ]
    },
    "ProjectionExpression": {
      "type": "object",
      "x-zig-type": "std.json.Value",
      "x-go-type-skip-optional-pointer": false,
      "additionalProperties": false,
      "description": "Exactly one expression node: literal, field, ref, param, call with args,\ncase with optional else, cast, or a binary operator. Pure expressions\nlower to the same typed scalar IR as SQL SELECT and CASE. AI/provider\ncalls remain in evaluate, never execute implicitly in select.\nvalue_identity(field) returns an opaque identity for a present logical\nvalue (including JSON null); missing has no identity. is_missing(field)\ndistinguishes missing from present null. Identity reads require the same\nauthorization and retained source revision as value reads. Metadata may\naccelerate them; unsupported/old metadata falls back to ordinary reads.\nUntaken CASE branches do not load fields or evaluate erroring calls.\nSupported binary nodes include eq, neq, lt, lte, gt, gte, is_distinct_from,\nis_not_distinct_from, and, or, add, subtract, multiply, divide and concat.\nExpressions are limited to depth 64 including referenced aliases, and\n8192 nodes per request. Alias dependencies are acyclic; each alias is a\nrequested output and is evaluated once per row.\n",
      "properties": {
        "literal": {
          "x-go-type": "json.RawMessage"
        },
        "field": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024,
          "description": "Logical source path. Dots traverse objects; numeric array components select an original index (items.1.name), and named components traverse arrays collecting present values (items.name). Nested user keys such as metadata._type are allowed. Internal root fields are reserved except _id."
        },
        "ref": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024
        },
        "param": {
          "type": "string",
          "minLength": 1,
          "maxLength": 1024
        },
        "call": {
          "type": "string",
          "description": "Public pure SQL scalar function name, including value_identity and is_missing. Internal and provider-backed functions are forbidden."
        },
        "args": {
          "type": "array",
          "maxItems": 64,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "case": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "when",
              "then"
            ],
            "properties": {
              "when": {
                "$ref": "#/$defs/ProjectionExpression"
              },
              "then": {
                "$ref": "#/$defs/ProjectionExpression"
              }
            }
          }
        },
        "else": {
          "$ref": "#/$defs/ProjectionExpression",
          "x-go-type-skip-optional-pointer": false
        },
        "cast": {
          "type": "object",
          "x-go-type-skip-optional-pointer": false,
          "additionalProperties": false,
          "required": [
            "type",
            "expression"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "string",
                "integer",
                "number",
                "boolean",
                "json",
                "datetime"
              ]
            },
            "expression": {
              "$ref": "#/$defs/ProjectionExpression"
            }
          }
        },
        "eq": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "neq": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "lt": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "lte": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "gt": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "gte": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "is_distinct_from": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "is_not_distinct_from": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "and": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "or": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "add": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "subtract": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "multiply": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "divide": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        },
        "concat": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "$ref": "#/$defs/ProjectionExpression"
          }
        }
      }
    },
    "Pruner": {
      "type": "object",
      "description": "Configuration for pruning search results based on score quality.\nHelps filter out low-relevance results in RAG pipelines by detecting\nscore gaps or deviations from top results. Pruning runs once on the\nglobally merged score domain, after reranking when a reranker is\nconfigured and before offset/limit paging.\n",
      "properties": {
        "min_score_ratio": {
          "x-go-type-skip-optional-pointer": true,
          "type": "number",
          "format": "double",
          "description": "Keep only results with score >= max_score * min_score_ratio.\nFor example, 0.5 keeps results scoring at least half of the top result.\nApplied to final scores after global fusion and optional reranking.\n"
        },
        "max_score_gap_percent": {
          "x-go-type-skip-optional-pointer": true,
          "type": "number",
          "format": "double",
          "description": "Stop returning results when the gap between consecutive scores\nexceeds this percentage of the total score range (max - min).\nDetects \"elbows\" in score distributions regardless of score scale.\nFor example, 30.0 stops when a gap spans 30% of the score range.\n"
        },
        "min_absolute_score": {
          "x-go-type-skip-optional-pointer": true,
          "type": "number",
          "format": "double",
          "description": "Hard minimum score threshold. Results with scores below this value\nare excluded regardless of other pruning settings.\n"
        },
        "require_multi_index": {
          "x-go-type-skip-optional-pointer": true,
          "type": "boolean",
          "description": "Only keep results that appear in multiple indexes (both full-text\nand vector search). Useful for increasing precision by requiring\nagreement between different retrieval methods.\n",
          "default": false
        },
        "std_dev_threshold": {
          "x-go-type-skip-optional-pointer": true,
          "type": "number",
          "format": "double",
          "description": "Keep results within N standard deviations below the mean score.\nFor example, 1.0 keeps results with score >= mean - 1*stddev.\nUseful for statistical outlier detection in result sets.\n"
        }
      }
    },
    "Query": {
      "oneOf": [
        {
          "$ref": "#/$defs/EqualsQuery"
        },
        {
          "$ref": "#/$defs/ContainsQuery"
        },
        {
          "$ref": "#/$defs/MatchesQuery"
        },
        {
          "$ref": "#/$defs/AutocompleteQuery"
        },
        {
          "$ref": "#/$defs/TermQuery"
        },
        {
          "$ref": "#/$defs/MatchQuery"
        },
        {
          "$ref": "#/$defs/MultiMatchQuery"
        },
        {
          "$ref": "#/$defs/MatchPhraseQuery"
        },
        {
          "$ref": "#/$defs/PhraseQuery"
        },
        {
          "$ref": "#/$defs/MultiPhraseQuery"
        },
        {
          "$ref": "#/$defs/FuzzyQuery"
        },
        {
          "$ref": "#/$defs/PrefixQuery"
        },
        {
          "$ref": "#/$defs/RegexpQuery"
        },
        {
          "$ref": "#/$defs/WildcardQuery"
        },
        {
          "$ref": "#/$defs/QueryStringQuery"
        },
        {
          "$ref": "#/$defs/NumericRangeQuery"
        },
        {
          "$ref": "#/$defs/TermRangeQuery"
        },
        {
          "$ref": "#/$defs/DateRangeStringQuery"
        },
        {
          "$ref": "#/$defs/BoolQuery"
        },
        {
          "$ref": "#/$defs/BooleanQuery"
        },
        {
          "$ref": "#/$defs/ConjunctionQuery"
        },
        {
          "$ref": "#/$defs/DisjunctionQuery"
        },
        {
          "$ref": "#/$defs/MatchAllQuery"
        },
        {
          "$ref": "#/$defs/MatchNoneQuery"
        },
        {
          "$ref": "#/$defs/DocIdQuery"
        },
        {
          "$ref": "#/$defs/BoolFieldQuery"
        },
        {
          "$ref": "#/$defs/IPRangeQuery"
        },
        {
          "$ref": "#/$defs/GeoBoundingBoxQuery"
        },
        {
          "$ref": "#/$defs/GeoDistanceQuery"
        },
        {
          "$ref": "#/$defs/GeoBoundingPolygonQuery"
        },
        {
          "$ref": "#/$defs/GeoShapeQuery"
        }
      ]
    },
    "QueryEvaluation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "scope",
        "compute"
      ],
      "description": "Evaluate expressions after global retrieval merging, before final\noffset/limit. Candidates require candidate_count; matches require\nmax_rows and fail if the full qualifying population exceeds that budget.\nCursor pagination, reranking, pruning, and ordinary aggregations cannot\nbe combined with evaluation. NULL inputs skip inference; errors fail.\n",
      "properties": {
        "graph_query": {
          "type": "string",
          "description": "Evaluate completed bindings of this named graph MATCH instead of retrieval hits. Fields use alias.document.path or alias.key. Existing graph aggregates cannot be combined with this stage."
        },
        "scope": {
          "type": "string",
          "enum": [
            "candidates",
            "matches"
          ]
        },
        "candidate_count": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000
        },
        "max_rows": {
          "type": "integer",
          "minimum": 1,
          "maximum": 10000
        },
        "compute": {
          "type": "object",
          "minProperties": 1,
          "maxProperties": 64,
          "additionalProperties": {
            "$ref": "#/$defs/QueryExpression"
          }
        },
        "where": {
          "type": "object",
          "description": "Exactly one of eq, neq, lt, lte, gt, gte (two expressions), is_null (expression), not (predicate), and, or (predicate arrays). Comparisons propagate NULL.",
          "additionalProperties": true
        },
        "order_by": {
          "type": "array",
          "maxItems": 16,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "expression"
            ],
            "properties": {
              "expression": {
                "$ref": "#/$defs/QueryExpression"
              },
              "descending": {
                "type": "boolean"
              }
            }
          }
        },
        "aggregations": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "type",
              "expression"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "terms",
                  "avg",
                  "sum",
                  "count"
                ]
              },
              "expression": {
                "$ref": "#/$defs/QueryExpression"
              }
            }
          }
        }
      }
    },
    "QueryExecution": {
      "type": "object",
      "additionalProperties": false,
      "description": "Execution controls; these affect admitted work, never predicate meaning or read freshness.",
      "properties": {
        "value_verification": {
          "$ref": "#/$defs/ValueVerification"
        }
      }
    },
    "QueryExpression": {
      "x-zig-type": "std.json.Value",
      "x-go-type-skip-optional-pointer": false,
      "type": "object",
      "additionalProperties": false,
      "description": "Exactly one of literal, field, ref, or call. A call requires input and\ndecider. ai_decide requires questions; ai_probability requires statement;\nai_choice and ai_score require instructions and criteria. Named refs may\nselect nested JSON members with dotted paths. Binding cycles are invalid.\n",
      "properties": {
        "literal": {
          "x-go-type": "json.RawMessage"
        },
        "field": {
          "type": "string",
          "minLength": 1
        },
        "ref": {
          "type": "string",
          "minLength": 1
        },
        "call": {
          "type": "string",
          "enum": [
            "ai_decide",
            "ai_choice",
            "ai_score",
            "ai_probability"
          ]
        },
        "input": {
          "$ref": "#/$defs/QueryExpression",
          "x-go-type-skip-optional-pointer": false
        },
        "decider": {
          "type": "string",
          "minLength": 1
        },
        "questions": {
          "type": "array",
          "minItems": 1,
          "maxItems": 64,
          "description": "Named decision question array using choice choices, score levels, or predicate instructions.",
          "items": {
            "type": "object",
            "additionalProperties": true
          }
        },
        "statement": {
          "type": "string",
          "minLength": 1
        },
        "instructions": {
          "type": "string",
          "minLength": 1
        },
        "criteria": {
          "description": "Choice ID map or ordered score level array.",
          "oneOf": [
            {
              "type": "object",
              "additionalProperties": {
                "type": "string"
              }
            },
            {
              "type": "array",
              "minItems": 2,
              "maxItems": 64,
              "items": {
                "type": "string"
              }
            }
          ]
        }
      }
    },
    "QueryHierarchy": {
      "type": "object",
      "additionalProperties": false,
      "description": "Returns direct index matches with optional projected ancestor context, or groups\nthose matches at a hierarchy level through `group_by`. A group's nested `matches`\nprojection is independently bounded and defaults to three hits while the top-level\n`limit` continues to control the number of groups.\n\n`children` is a separate sequential-browsing operation. It enumerates every unit\nin the selected source revision, including units with no searchable chunk, and uses\nthe top-level `_sort`/`search_after` cursor contract.\n\nAncestor and nested-match field projections are always explicit to keep response\nsize predictable. The presence of this object selects the canonical contract:\nwithout `group_by` or `children`, including when the object is empty, direct index\nmatches are returned. `ancestors` only controls projected context and never changes result\ncardinality. Omit `hierarchy` entirely to retain the v0.2-compatible implicit\nsource-grouped result shape.\n",
      "allOf": [
        {
          "not": {
            "description": "Relevance grouping and sequential child traversal are separate operations.",
            "required": [
              "group_by",
              "children"
            ]
          }
        },
        {
          "not": {
            "description": "Sequential child traversal cannot request per-hit ancestor hydration.",
            "required": [
              "children",
              "ancestors"
            ]
          }
        },
        {
          "not": {
            "description": "A source group already carries its projected source document.",
            "required": [
              "group_by",
              "ancestors"
            ],
            "properties": {
              "group_by": {
                "required": [
                  "level"
                ],
                "properties": {
                  "level": {
                    "type": "string",
                    "enum": [
                      "source"
                    ]
                  }
                }
              },
              "ancestors": {
                "required": [
                  "source"
                ]
              }
            }
          }
        }
      ],
      "properties": {
        "group_by": {
          "$ref": "#/$defs/HierarchyGroupBy",
          "x-go-type-skip-optional-pointer": false
        },
        "ancestors": {
          "$ref": "#/$defs/HierarchyAncestors",
          "x-go-type-skip-optional-pointer": false
        },
        "children": {
          "$ref": "#/$defs/HierarchyChildren",
          "x-go-type-skip-optional-pointer": false
        }
      }
    },
    "QueryHighlight": {
      "type": "object",
      "description": "Ask for highlighted fragments of the stored fields matched by\n`full_text_search` and by named full-text queries. Matches are located\nby re-analyzing the stored value with the field's analyzer, so stemmed\nand stop-word-filtered terms highlight the surface form. `prefix`,\n`wildcard`, `regexp`, and `fuzzy` clauses mark whole tokens; `match`,\n`match_phrase`, or `prefix` on a `substring` companion\n(`field._substring`) marks the exact contained bytes, including\nmatches that span two adjacent words.\n",
      "properties": {
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Source fields to highlight. Defaults to every field the full-text\nquery references (companion suffixes such as `._substring` and\n`.keyword` resolve to their root field).\n"
        },
        "fragment_size": {
          "type": "integer",
          "minimum": 16,
          "maximum": 4096,
          "default": 150,
          "description": "Fragment window size in bytes."
        },
        "max_fragments": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "default": 3,
          "description": "Maximum fragments returned per field."
        }
      }
    },
    "QueryRequest": {
      "type": "object",
      "not": {
        "anyOf": [
          {
            "required": [
              "lake_read"
            ]
          },
          {
            "required": [
              "lake_visibility"
            ]
          },
          {
            "required": [
              "value_search_execution"
            ]
          },
          {
            "description": "Hierarchy grouping requires an explicit top-level field projection.",
            "allOf": [
              {
                "required": [
                  "hierarchy"
                ],
                "properties": {
                  "hierarchy": {
                    "required": [
                      "group_by"
                    ]
                  }
                }
              },
              {
                "not": {
                  "required": [
                    "fields"
                  ]
                }
              }
            ]
          },
          {
            "description": "Hierarchy child traversal requires an explicit top-level field projection.",
            "allOf": [
              {
                "required": [
                  "hierarchy"
                ],
                "properties": {
                  "hierarchy": {
                    "required": [
                      "children"
                    ]
                  }
                }
              },
              {
                "not": {
                  "required": [
                    "fields"
                  ]
                }
              }
            ]
          },
          {
            "description": "Hierarchy child traversal requires its revision-bound ascending position order.",
            "allOf": [
              {
                "required": [
                  "hierarchy"
                ],
                "properties": {
                  "hierarchy": {
                    "required": [
                      "children"
                    ]
                  }
                }
              },
              {
                "not": {
                  "required": [
                    "order_by"
                  ]
                }
              }
            ]
          },
          {
            "description": "Hierarchy child traversal accepts only `_hierarchy.position` ascending.",
            "required": [
              "hierarchy",
              "order_by"
            ],
            "properties": {
              "hierarchy": {
                "required": [
                  "children"
                ]
              },
              "order_by": {
                "not": {
                  "$ref": "#/$defs/HierarchyChildrenOrderBy"
                }
              }
            }
          },
          {
            "description": "Hierarchy child traversal pages contain between one and 100 units.",
            "required": [
              "hierarchy",
              "limit"
            ],
            "properties": {
              "hierarchy": {
                "required": [
                  "children"
                ]
              },
              "limit": {
                "type": "integer",
                "anyOf": [
                  {
                    "maximum": 0
                  },
                  {
                    "minimum": 101
                  }
                ]
              }
            }
          },
          {
            "description": "Hierarchy child traversal cursors are exact two-string `_sort` tuples.",
            "required": [
              "hierarchy",
              "search_after"
            ],
            "properties": {
              "hierarchy": {
                "required": [
                  "children"
                ]
              },
              "search_after": {
                "not": {
                  "$ref": "#/$defs/HierarchyChildrenSearchAfter"
                }
              }
            }
          },
          {
            "description": "Relevance-ranked unit grouping does not expose exact sort tuples or cursors.",
            "allOf": [
              {
                "required": [
                  "hierarchy"
                ],
                "properties": {
                  "hierarchy": {
                    "required": [
                      "group_by"
                    ],
                    "properties": {
                      "group_by": {
                        "required": [
                          "level"
                        ],
                        "properties": {
                          "level": {
                            "type": "string",
                            "enum": [
                              "unit"
                            ]
                          }
                        }
                      }
                    }
                  }
                }
              },
              {
                "anyOf": [
                  {
                    "required": [
                      "order_by"
                    ]
                  },
                  {
                    "required": [
                      "search_after"
                    ]
                  },
                  {
                    "required": [
                      "search_before"
                    ]
                  }
                ]
              }
            ]
          },
          {
            "description": "Relevance, filtering, backward/offset pagination, and result transforms do not apply to sequential child traversal.",
            "allOf": [
              {
                "required": [
                  "hierarchy"
                ],
                "properties": {
                  "hierarchy": {
                    "required": [
                      "children"
                    ]
                  }
                }
              },
              {
                "anyOf": [
                  {
                    "required": [
                      "query"
                    ]
                  },
                  {
                    "required": [
                      "full_text_search"
                    ]
                  },
                  {
                    "required": [
                      "full_text_index"
                    ]
                  },
                  {
                    "required": [
                      "filter_query"
                    ]
                  },
                  {
                    "required": [
                      "exclusion_query"
                    ]
                  },
                  {
                    "required": [
                      "semantic_search"
                    ]
                  },
                  {
                    "required": [
                      "embedding_template"
                    ]
                  },
                  {
                    "required": [
                      "indexes"
                    ]
                  },
                  {
                    "required": [
                      "embeddings"
                    ]
                  },
                  {
                    "required": [
                      "offset"
                    ]
                  },
                  {
                    "required": [
                      "search_before"
                    ]
                  },
                  {
                    "required": [
                      "filter_prefix"
                    ]
                  },
                  {
                    "required": [
                      "distance_under"
                    ]
                  },
                  {
                    "required": [
                      "distance_over"
                    ]
                  },
                  {
                    "required": [
                      "search_effort"
                    ]
                  },
                  {
                    "required": [
                      "merge_config"
                    ]
                  },
                  {
                    "required": [
                      "count"
                    ]
                  },
                  {
                    "required": [
                      "profile"
                    ]
                  },
                  {
                    "required": [
                      "reranker"
                    ]
                  },
                  {
                    "required": [
                      "graph_metric"
                    ]
                  },
                  {
                    "required": [
                      "graph_metric_rerank"
                    ]
                  },
                  {
                    "required": [
                      "analyses"
                    ]
                  },
                  {
                    "required": [
                      "highlight"
                    ]
                  },
                  {
                    "required": [
                      "aggregations"
                    ]
                  },
                  {
                    "required": [
                      "graph_queries"
                    ]
                  },
                  {
                    "required": [
                      "document_renderer"
                    ]
                  },
                  {
                    "required": [
                      "pruner"
                    ]
                  },
                  {
                    "required": [
                      "evaluate"
                    ]
                  },
                  {
                    "required": [
                      "join"
                    ]
                  },
                  {
                    "required": [
                      "foreign_sources"
                    ]
                  },
                  {
                    "required": [
                      "execution"
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      "properties": {
        "execution": {
          "$ref": "#/$defs/QueryExecution"
        },
        "read_requirements": {
          "$ref": "#/$defs/ReadRequirements"
        },
        "remote_snapshot": {
          "type": "string",
          "description": "Opaque retained snapshot token returned by an ordered native or external-table query. Echo with search_after or search_before. Native and lake cuts expire within the configured retention period (default five minutes; maximum one hour); missing, expired or incompatible generations return 409. Also supported when resuming hierarchy.children; its revision-bound ascending position cursor remains required."
        },
        "evaluate": {
          "$ref": "#/$defs/QueryEvaluation"
        },
        "table_target": {
          "$ref": "#/$defs/CatalogTableTarget"
        },
        "table": {
          "type": "string",
          "description": "Literal table name in default.public. Global queries require exactly one of table or table_target."
        },
        "query": {
          "x-go-type": "json.RawMessage",
          "x-zig-type": "std.json.Value",
          "type": "object",
          "additionalProperties": true,
          "description": "Canonical public query AST. Prefer this field for new clients.\n\nBoolean clauses are normalized before planning:\n- `bool.must` is scoring query input.\n- `bool.filter` is non-scoring query input.\n- `bool.must_not` is non-scoring exclusion query input.\n\nFilter branches accept the same query variants as `filter_query` and\n`exclusion_query`. Structured clauses use the native document-value\npath; text clauses are resolved through the text index before scoring.\n"
        },
        "full_text_search": {
          "$ref": "#/$defs/RawQuery",
          "description": "Antfly query for full-text search. Supports all Antfly query types.\n\nSee specs/openapi/antfly/query.yaml for complete type definitions.\n\nExamples:\n- Simple: `{\"query\": \"computer\"}`\n- Field-specific: `{\"query\": \"body:computer\"}`\n- Boolean: `{\"query\": \"+artificial +intelligence\"}`\n- Range: `{\"query\": \"year:>2020\"}`\n- Phrase: `{\"query\": \"\\\"exact phrase\\\"\"}`\n"
        },
        "full_text_index": {
          "x-go-type-skip-optional-pointer": true,
          "type": "string",
          "minLength": 1,
          "maxLength": 256,
          "x-antfly-runtime-validation": "Requires full_text_search or at least one scoring text clause after normalizing the query AST; filter-only and exclusion-only query trees receive HTTP 422.",
          "description": "Full-text index used by `full_text_search` and by scoring text clauses in `query`.\nUse this to query a named document- or artifact-backed full-text index. The selected\nindex must exist and have type `full_text`. Omit this field to use the table's active\nschema full-text index, preserving v0.2 behavior. Structured document filters continue\nto use the active schema index even when retrieval uses a named artifact index. This\nselector is invalid without `full_text_search` or a scoring text clause in `query` and\nreceives HTTP 422. This semantic relationship is enforced after the recursive query AST\nis normalized; OpenAPI presence checks cannot accurately distinguish scoring clauses\nfrom filter-only or exclusion-only trees.\n"
        },
        "semantic_search": {
          "type": "string",
          "x-antfly-max-utf8-bytes": 1048576,
          "description": "Natural language query for vector similarity search. Results are ranked by semantic similarity\nto the query and can be combined with full_text_search using Reciprocal Rank Fusion (RRF).\n\nThe semantic_search string is automatically embedded using the configured embedding model\nfor the specified indexes. UTF-8 input is limited to 1 MiB. Use `embedding_template` for\nmultimodal queries.\n"
        },
        "embedding_template": {
          "type": "string",
          "x-antfly-max-utf8-bytes": 65536,
          "description": "Optional Handlebars template for multimodal embedding of the semantic_search query.\nThe template has access to `this` which contains the semantic_search string value.\n\nUTF-8 template input is limited to 64 KiB.\n\nUse this when you want to embed template-time multimodal content instead of\njust text. The template is rendered using dotprompt with access to remote content helpers.\n\n**Available Helpers**:\n- `remoteMedia url=<url>` - Fetches and embeds remote images/media\n- `remotePDF url=<url>` - **Deprecated.** Fetches and extracts text from born-digital PDFs\n- `remoteText url=<url>` - Fetches and includes remote text content\n\nUse a `document_extraction` asset producer when PDF pages and chunks must be persisted\nand reprocessed. `remoteMedia` and the other helpers only prepare template-time inference input.\n\n**Examples**:\n- Legacy PDF search: `{{remotePDF url=this}}`\n- Image search: `{{remoteMedia url=this}}`\n- Mixed: `Search for: {{this}} {{#if this}}{{remoteMedia url=this}}{{/if}}`\n\nWhen not specified, the semantic_search string is embedded as plain text.\n"
        },
        "indexes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Embedding index names selected for `semantic_search` or explicit `embeddings`.\nDense and sparse indexes are supported when the corresponding query representation is\nsupplied. Provisioned deployments require at least one index for `semantic_search`;\nserverless may infer its single published dense index when this field is omitted. When\n`embeddings` is supplied without this field, the embedding map keys select the indexes.\nProvisioned results from multiple indexes are merged using RRF. Serverless currently\nexecutes at most one dense and one sparse index per request; it rejects multiple\nsame-kind selectors and omitted selectors when more than one corresponding index is\npublished rather than choosing an index by catalog order.\n"
        },
        "filter_prefix": {
          "type": "string",
          "format": "byte",
          "description": "Filter results by key prefix. Only returns documents whose keys start with this string.\nApplied before scoring to improve performance.\n\nCommon use cases:\n- Multi-tenant filtering: `\"tenant:acme:\"`\n- User-specific data: `\"user:123:\"`\n- Document type filtering: `\"article:\"`\n"
        },
        "filter_query": {
          "$ref": "#/$defs/RawQuery",
          "description": "Antfly query applied as an AND condition. Documents must match both the main query\nand this filter. Applied before scoring for better performance.\n\nSee specs/openapi/antfly/query.yaml for complete type definitions.\n\nUse for:\n- Status filtering: `\"status:published\"`\n- Date ranges: `\"created_at:>2023-01-01\"`\n- Category filtering: `\"+category:technology +language:en\"`\n- Geo bounding boxes: `{\"geo_bbox\":{\"field\":\"location\",\"min_lat\":-1,\"min_lon\":179.5,\"max_lat\":1,\"max_lon\":-179.5}}`\n\nFor structured `geo_bbox`, `min_lon > max_lon` intentionally\nrepresents a bounding box that crosses the antimeridian.\n"
        },
        "exclusion_query": {
          "$ref": "#/$defs/RawQuery",
          "description": "Antfly query applied as a NOT condition. Documents matching this query are excluded\nfrom results. Applied before scoring.\n\nSee specs/openapi/antfly/query.yaml for complete type definitions.\n\nUse for:\n- Excluding drafts: `\"status:draft\"`\n- Removing deprecated content: `\"deprecated:true\"`\n- Filtering out archived items: `\"status:archived\"`\n"
        },
        "aggregations": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/AggregationRequest"
          },
          "description": "Aggregation requests for computing metrics and bucketing results.\nEach key is a user-defined name for the aggregation, and the value specifies the aggregation configuration.\n\nWhen `hierarchy.group_by` is present, aggregations operate on the complete\nset of top-level grouped source or unit records. Nested `group_by.matches` are\nbounded evidence projections and are not counted as aggregation rows.\n\nSupports metric aggregations (sum, avg, min, max, count, stats, cardinality),\nbucketing aggregations (terms, range, date_range, histogram, date_histogram),\ngeo aggregations (geohash_grid, geo_distance), and analytics (significant_terms).\n\nExample:\n```json\n{\n  \"price_stats\": {\n    \"type\": \"stats\",\n    \"field\": \"price\"\n  },\n  \"categories\": {\n    \"type\": \"terms\",\n    \"field\": \"category\",\n    \"size\": 10\n  }\n}\n```\n"
        },
        "embeddings": {
          "type": "object",
          "description": "Pre-computed embeddings to use for semantic searches instead of embedding the semantic_search string.\nThe keys are the index names. Values can be either:\n- **Dense (array)**: an array of floats, e.g. `[0.1, 0.2, 0.3]`\n- **Dense (packed)**: a base64 string of little-endian float32 bytes (~4x more compact)\n- **Sparse**: an object with `indices` (array of ints) and `values` (array of floats),\n  e.g. `{\"indices\": [1, 5, 100], \"values\": [0.3, 0.7, 0.1]}`\n- **Sparse (packed)**: an object with `packed_indices` (base64 uint32 LE) and `packed_values` (base64 float32 LE)\n\nUse when you've already generated embeddings on the client side to avoid redundant embedding calls.\n",
          "additionalProperties": {
            "$ref": "#/$defs/Embedding"
          }
        },
        "search_effort": {
          "x-go-type-skip-optional-pointer": false,
          "type": "number",
          "format": "float",
          "minimum": 0,
          "maximum": 1,
          "default": 0.5,
          "description": "Controls the vector search recall/latency tradeoff for semantic searches.\n\n- `0.0` = fastest, lowest recall\n- `0.5` = balanced default\n- `1.0` = highest recall\n\nWhen omitted, Antfly uses the balanced default effort (`0.5`) unless\nlower-level vector search overrides are provided internally.\n"
        },
        "select": {
          "type": "object",
          "minProperties": 1,
          "maxProperties": 64,
          "additionalProperties": {
            "$ref": "#/$defs/ProjectionExpression"
          },
          "x-zig-type": "std.json.Value",
          "x-go-type-skip-optional-pointer": false,
          "description": "Pure named output expressions evaluated after final filtering, ranking and pagination; returned in _computed. Compatible with fields, which selects stored _source. Uses the SQL scalar engine and lazy CASE branches. Aliases may reference other select aliases with ref; cycles and collisions with evaluate.compute are rejected. Does not change hit membership or paging."
        },
        "params": {
          "type": "object",
          "additionalProperties": true,
          "x-zig-type": "std.json.Value",
          "x-go-type-skip-optional-pointer": false,
          "description": "Request-local values bound by select expressions through param. Parameters are data, never executable expressions or read grants. The serialized parameter object is limited to 1 MiB and 1024 named parameters."
        },
        "fields": {
          "x-go-type-skip-optional-pointer": false,
          "type": "array",
          "description": "List of fields to include in the results. If not specified, all fields are returned.\nUse to reduce response size and improve performance. This field is required when\nhierarchy.group_by is present so a grouped query cannot accidentally hydrate an\nentire grouped document. Use an empty array for identity-only groups.\nThis projection is also required for hierarchy.children traversal.\n",
          "items": {
            "type": "string"
          }
        },
        "hierarchy": {
          "$ref": "#/$defs/QueryHierarchy",
          "x-go-type-skip-optional-pointer": false
        },
        "highlight": {
          "$ref": "#/$defs/QueryHighlight",
          "x-go-type-skip-optional-pointer": false
        },
        "limit": {
          "type": "integer",
          "description": "Maximum number of top-level results to return. For semantic_search, this is the topk parameter.\nThis does not limit nested matches attached through hierarchy.group_by.matches;\nuse hierarchy.group_by.matches.limit for that. Default varies by query type (typically 10).\nQueries using hierarchy.group_by.matches are limited to 100 top-level groups\nand a groups-times-matches execution budget of 1,000.\n"
        },
        "offset": {
          "type": "integer",
          "description": "Number of results to skip for pagination. Supported for text-backed,\nmatch_all, and filter-only requests. Approximate semantic requests do\nnot support offset on their own. Semantic and hybrid requests support\nit when a reranker is configured: Antfly retrieves a bounded candidate\nwindow and applies offset after coordinator-owned reranking.\n"
        },
        "timeout_ms": {
          "type": "integer",
          "minimum": 0,
          "description": "Optional query execution deadline in milliseconds. The server applies this as a\ncooperative deadline across query planning, search execution, aggregation reruns,\nsorting, and response post-processing. If the deadline expires before the query\ncompletes, the HTTP API returns 504. When omitted, semantic query embedding planning\nand provider I/O use a 30-second default deadline.\n"
        },
        "order_by": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SortField"
          },
          "description": "Sort order for results. Array of sort fields with direction.\nAntfly appends `_id` ascending as a stable tie-breaker when it is omitted.\nHierarchy child traversal requires `_hierarchy.position` ascending; its opaque,\nsortable value is bound to the complete source hierarchy revision.\nSupported for exact text-backed, match_all, and filter-only requests\nwhen each non-`_id` field is a mapped exact scalar field with sortable\nnative doc-value coverage. Sortable mapping types are keyword,\nnumeric/number/integer, boolean/bool, datetime/date/timestamp, and\nlink. Declare the field with `x-antfly-field` and `sortable: true`;\n`x-antfly-types` shorthand declarations alone are not sortable.\nAnalyzed `text` fields and `search_as_you_type`, geo, embedding,\nblob, html, object, and array fields are not directly sortable; sort\non an exact scalar mapping such as `title.keyword` instead. Requests\nthat cannot be executed through an exact native sort path return 422\nrather than falling back to stored JSON sorting. Semantic searches\nare always sorted by similarity score. Not supported when `count` is true.\n"
        },
        "search_after": {
          "type": "array",
          "items": {},
          "description": "Cursor for forward pagination. Pass the `_sort` values from the last hit\nof the previous page exactly, including the appended `_id` tie-breaker.\nValues preserve their JSON types; for example numbers remain numbers,\nbooleans remain booleans, and strings remain strings. Cursor values\nmust be replayable JSON scalars; nulls, arrays, objects, and non-finite\nnumbers are rejected.\nMutually exclusive with `offset`.\nWhen `order_by` is omitted, Antfly uses `_id` ascending as the effective\norder and the cursor tuple must contain exactly one `_id` string.\nSupported for exact text-backed, match_all, and filter-only requests;\nnot supported for semantic_search or count-only requests.\nFor hierarchy child traversal, a cursor whose source-artifact revision\nchanged returns `409 hierarchy_cursor_stale`; restart the same traversal\nwithout `search_after` rather than retrying the stale tuple.\n"
        },
        "search_before": {
          "type": "array",
          "items": {},
          "description": "Cursor for backward pagination. Pass the `_sort` values from the first hit\nof the current page exactly, including the appended `_id` tie-breaker.\nValues preserve their JSON types; for example numbers remain numbers,\nbooleans remain booleans, and strings remain strings. Cursor values\nmust be replayable JSON scalars; nulls, arrays, objects, and non-finite\nnumbers are rejected.\nMutually exclusive with `offset`.\nWhen `order_by` is omitted, Antfly uses `_id` ascending as the effective\norder and the cursor tuple must contain exactly one `_id` string.\nSupported for exact text-backed, match_all, and filter-only requests;\nnot supported for semantic_search or count-only requests.\n"
        },
        "distance_under": {
          "x-go-type-skip-optional-pointer": false,
          "type": "number",
          "format": "float",
          "description": "Maximum distance threshold for semantic similarity search. Results with distance\ngreater than this value are excluded. Lower distances indicate higher similarity.\n\nUseful for filtering out low-confidence matches.\n"
        },
        "distance_over": {
          "x-go-type-skip-optional-pointer": false,
          "type": "number",
          "format": "float",
          "description": "Minimum distance threshold for semantic similarity search. Results with distance\nless than this value are excluded.\n\nUseful for excluding near-exact duplicates or finding dissimilar documents.\n"
        },
        "merge_config": {
          "$ref": "#/$defs/MergeConfig",
          "description": "Configuration for merging full-text and semantic search results.\nOnly applies when both `full_text_search` and `semantic_search` are specified.\n"
        },
        "count": {
          "type": "boolean",
          "description": "If true, returns only the total count of matching documents without retrieving the actual documents.\nUseful for pagination and displaying result counts. Count-only requests\ndo not return an ordered result page, so `order_by`, `search_after`,\nand `search_before` are not supported when this is true.\n"
        },
        "profile": {
          "type": "boolean",
          "description": "If true, includes detailed execution profiling in the response.\nAdds a `profile` object with per-phase timing breakdowns, shard statistics,\njoin metadata, reranker stats, and merge details.\nHas minor performance overhead — not recommended for production traffic.\n"
        },
        "reranker": {
          "$ref": "#/$defs/RerankerConfig",
          "description": "Optional reranker configuration to improve result relevance.\n\nRerankers use cross-encoder models that score query-document pairs directly,\nproviding more accurate relevance scores than embedding similarity alone.\n\n**When to use:**\n- Results need high precision (e.g., RAG, question answering)\n- You have semantic or hybrid search results to refine\n- Latency trade-off is acceptable (reranking adds 100-500ms typically)\n\n**Best practice:** Set `candidate_count` to the bounded retrieval window\n(often 50-100) and use the query `limit` for the final page size. Antfly\nretrieves and globally merges that window, calls the reranker once, then\napplies pruning, offset, and limit at the coordinator.\n\nExample:\n```json\n{\n  \"provider\": \"antfly\",\n  \"model\": \"cross-encoder/ms-marco-MiniLM-L-6-v2\",\n  \"field\": \"content\"\n}\n```\n"
        },
        "graph_metric": {
          "$ref": "#/$defs/GraphMetricQuery",
          "description": "Direct top-k read from a published graph metric generation. Results are returned in graph_metric_results under the requested name or the metric name when no explicit name is supplied. Supplying seed_nodes switches a pagerank metric to query-seeded personalized PageRank computed at query time; that form requires metric_freshness=fresh because published generations are global-only."
        },
        "graph_metric_rerank": {
          "$ref": "#/$defs/GraphMetricRerank",
          "description": "Blend a published graph metric feature into ordinary search hit scores. Requests may require either any published generation or a generation that is fresh with respect to graph writes. Supplying seed_nodes switches a pagerank metric to a query-seeded personalized PageRank blend computed at query time; that form requires metric_freshness=fresh. Retrieval-agent queries may opt in to automatic seeding with auto_seed=true, which seeds the blend from the query's literal graph-search start keys; only valid for pagerank metrics with metric_freshness=fresh. Caller-supplied seed_nodes always take precedence and are never overwritten."
        },
        "analyses": {
          "$ref": "#/$defs/Analyses"
        },
        "graph_queries": {
          "$ref": "#/$defs/GraphQueries",
          "description": "Declarative graph matching, traversal, and path queries. A nested node\n`filter` is a typed, non-scoring stored-document predicate. It shares\nfamiliar scalar syntax with document queries but deliberately excludes\nanalyzer-backed and index-only clauses. A request may contain at most\n64 named graph operations, of which at most 8 may be named `match`\noperations. Each operation key is a GraphIdentifier under the\nversioned policy published in the GraphIdentifier schema.\nPut multiple counts over one pattern in the same `match` return\nobject so they share one complete anchor scan.\n"
        },
        "document_renderer": {
          "type": "string",
          "description": "Not supported on queries, which do not generate text; requests that\nset it are rejected. Set `document_renderer` on a retrieval agent\nrequest to control how documents appear in the generation prompt.\n"
        },
        "pruner": {
          "$ref": "#/$defs/Pruner",
          "description": "Optional result pruning configuration to filter low-relevance results.\n\nPruning helps detect \"elbows\" in score distributions and removes\nresults that are significantly worse than top matches. It runs once\non globally merged results, after optional reranking and before the\nfinal offset/limit page is selected.\n\n**Common patterns:**\n- RAG queries: Use `max_score_gap_percent: 30` to stop at quality drop-offs\n- Strict matching: Use `min_score_ratio: 0.7` for high-quality results only\n- Combine both for best results\n\nExample:\n```json\n{\n  \"min_score_ratio\": 0.5,\n  \"max_score_gap_percent\": 25.0,\n  \"min_absolute_score\": 0.3\n}\n```\n"
        },
        "join": {
          "$ref": "#/$defs/JoinClause",
          "description": "Cross-table join configuration for combining results from multiple tables.\n\nJoins allow you to enrich query results with data from related tables,\nsimilar to SQL JOINs but optimized for distributed execution.\n\n**Join Types:**\n- `inner`: Only return rows that have matches in both tables\n- `left`: Return all rows from the primary table, with NULL for non-matching right rows\n- `right`: Return all rows from the joined table, with NULL for non-matching left rows\n\n**Join Strategies** (auto-selected based on table sizes):\n- `broadcast`: Small table broadcast to all shards (best for dimension tables < 10MB)\n- `index_lookup`: Batch key lookups using indexes (best for selective joins)\n- `shuffle`: Hash-partition both tables (best for large-large joins)\n\n**Example - Enrich orders with customer data:**\n```json\n{\n  \"table\": \"orders\",\n  \"full_text_search\": {\"query\": \"status:pending\"},\n  \"join\": {\n    \"right_table\": \"customers\",\n    \"join_type\": \"inner\",\n    \"on\": {\n      \"left_field\": \"customer_id\",\n      \"right_field\": \"id\"\n    },\n    \"right_filters\": {\n      \"filter_query\": {\"query\": \"tier:premium\"}\n    }\n  },\n  \"fields\": [\"order_id\", \"amount\", \"customers.name\", \"customers.email\"]\n}\n```\n\n**Multi-way joins** (nested):\n```json\n{\n  \"table\": \"orders\",\n  \"join\": {\n    \"right_table\": \"customers\",\n    \"on\": {\"left_field\": \"customer_id\", \"right_field\": \"id\"},\n    \"nested_join\": {\n      \"right_table\": \"addresses\",\n      \"on\": {\"left_field\": \"customers.address_id\", \"right_field\": \"id\"}\n    }\n  }\n}\n```\n\n**Performance Tips:**\n- Filter the driving table first to reduce join input size\n- Put the smaller table on the right side for broadcast joins\n- Use indexed fields in join conditions for index_lookup strategy\n- Limit result fields to reduce data transfer\n"
        },
        "foreign_sources": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/ForeignSource"
          },
          "description": "Map of table name to foreign data source configuration for query-time federated access.\nWhen a table name referenced in this query (or in a join's `right_table`) appears as a key\nhere, the query is routed to the external database instead of Antfly shards.\n\nThis enables joining Antfly search results with structured relational data (customer records,\nproduct catalogs, etc.) without ingesting that data into Antfly.\n\n**Supported operations on foreign tables:** filter_query, field selection, limit/offset.\n**Not supported:** full_text_search, semantic_search, graph_queries, aggregations, reranker.\n\n**Example - Join Antfly products with Postgres customers:**\n```json\n{\n  \"table\": \"products\",\n  \"full_text_search\": {\"query\": \"category:electronics\"},\n  \"join\": {\n    \"right_table\": \"pg_customers\",\n    \"on\": {\"left_field\": \"customer_id\", \"right_field\": \"id\"}\n  },\n  \"foreign_sources\": {\n    \"pg_customers\": {\n      \"type\": \"postgres\",\n      \"dsn\": \"${secret:pg_dsn}\",\n      \"postgres_table\": \"customers\"\n    }\n  }\n}\n```\n"
        }
      }
    },
    "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"
    },
    "QueryStringQuery": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "query"
      ]
    },
    "RateLimitConfig": {
      "type": "object",
      "x-go-type-skip-optional-pointer": false,
      "additionalProperties": false,
      "description": "Outbound provider limits shared within one Antfly process by effective\nendpoint, operation, model, credential source, project and region/location.\nConflicting policies for an active scope are rejected. These limits do\nnot coordinate across replicas or infer the provider's account quota.\n",
      "properties": {
        "pacing": {
          "$ref": "#/$defs/RequestPacing",
          "description": "Request pacing mode. Defaults to token_bucket. Legacy flat embedder RPM with burst=1 uses completion pacing."
        },
        "requests_per_minute": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "maximum": 4294967295
        },
        "burst": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "maximum": 4294967295,
          "default": 1
        },
        "tokens_per_minute": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "description": "Conservative text budget: each HTTP attempt reserves its serialized\nUTF-8 body byte count plus the configured generation output cap.\nReservations are not refunded. A request larger than this budget\nis rejected. This is not provider billing token accounting; media\nrequests are not supported with this limit.\n"
        },
        "max_concurrency": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "maximum": 4294967295,
          "description": "Maximum in-flight HTTP attempts, held through response completion."
        }
      }
    },
    "RawQuery": {
      "oneOf": [
        {
          "$ref": "#/$defs/Query"
        }
      ],
      "x-go-type": "json.RawMessage",
      "x-zig-type": "raw_json",
      "description": "An Antfly query expression retained as syntactically validated JSON and compiled by the query engine."
    },
    "ReadReceipt": {
      "type": "object",
      "additionalProperties": false,
      "description": "Opaque write receipt returned by ingestion. Pass it back unchanged to require a read including that write; it is a minimum freshness frontier, not an exact snapshot.",
      "required": [
        "table_id",
        "object_generation",
        "wal_lsn"
      ],
      "properties": {
        "table_id": {
          "type": "integer",
          "format": "uint64"
        },
        "object_generation": {
          "type": "integer",
          "format": "uint64"
        },
        "wal_lsn": {
          "type": "integer",
          "format": "uint64"
        }
      }
    },
    "ReadRequirements": {
      "type": "object",
      "additionalProperties": false,
      "description": "Freshness requirements for writable Iceberg reads. Search supports accepted and published (default accepted); SQL supports accepted and committed (default committed). Unsupported visibility modes fail explicitly. A pinned transaction snapshot never advances to satisfy a newer receipt.",
      "properties": {
        "visibility": {
          "type": "string",
          "enum": [
            "accepted",
            "committed",
            "published"
          ],
          "description": "Accepted includes durable WAL writes; committed reads an Iceberg commit; published reads the search index generation. These are distinct visibility stages."
        },
        "after_write": {
          "$ref": "#/$defs/ReadReceipt"
        },
        "wait_ms": {
          "x-go-type-skip-optional-pointer": false,
          "type": "integer",
          "format": "uint32",
          "minimum": 0,
          "maximum": 60000,
          "description": "Readiness wait budget within the query or statement timeout. Defaults to 5000 ms when requirements are supplied; zero fails immediately if coverage is unavailable."
        }
      }
    },
    "RegexpQuery": {
      "type": "object",
      "description": "Match post-analysis indexed terms. Patterns are not stemmed; use match for analyzed natural-language input.",
      "properties": {
        "case_insensitive": {
          "type": "boolean",
          "default": false,
          "description": "Fold ASCII letter case when matching indexed terms, without stemming the pattern."
        },
        "regexp": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "regexp"
      ]
    },
    "RequestPacing": {
      "type": "string",
      "enum": [
        "token_bucket",
        "completion"
      ],
      "description": "token_bucket limits admission rate while allowing overlapping attempts.\ncompletion serializes attempts and waits one RPM interval after each\nattempt finishes, including streamed writes and transport failures.\nThis prevents delayed connection setup from compressing successful\nrequest spacing, at the cost of response latency plus one interval per\nrequest. Requires requests_per_minute and burst=1. Neither mode can\nguarantee zero upstream 429s or coordinate other processes.\n"
    },
    "RerankerConfig": {
      "x-go-type-skip-optional-pointer": false,
      "description": "A unified configuration for a reranking provider.",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "account_id": {
              "type": "string"
            },
            "gateway_id": {
              "type": "string"
            },
            "rate_limit": {
              "x-go-type-skip-optional-pointer": false,
              "$ref": "#/$defs/RateLimitConfig"
            },
            "provider": {
              "$ref": "#/$defs/RerankerProvider"
            },
            "field": {
              "type": "string",
              "description": "Field name to extract from documents for reranking."
            },
            "template": {
              "type": "string",
              "description": "Handlebars template that renders each candidate for reranking. The `media` and `remoteMedia` helpers add images, which are sent to the reranker alongside the rendered text; only an Antfly reranker whose model accepts images can score them, and any other reranker rejects the query with `400`."
            },
            "model": {
              "type": "string",
              "description": "Optional provider model name. When omitted, the selected provider's documented default is used."
            },
            "candidate_count": {
              "x-go-type-skip-optional-pointer": false,
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "description": "Maximum number of globally highest-ranked retrieval candidates to send to the reranker. In distributed deployments each shard retrieves at most this many candidates, the coordinator retains the global window, and the provider is called once. Defaults to offset plus the effective final result limit and, when supplied explicitly, must be at least that page boundary. Candidates outside this window are not returned, but hits.total continues to describe the underlying retrieval match count. The ceiling bounds retrieval fan-out, memory, provider latency, and external API cost. The effective window must be at most 1000, and providers may impose a lower ceiling; Vertex currently accepts at most 200. Antfly rejects invalid or provider-specific windows before retrieval fan-out."
            },
            "top_n": {
              "x-go-type-skip-optional-pointer": false,
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "deprecated": true,
              "description": "Deprecated compatibility override for QueryRequest.limit. When present, this is the final page size after reranking and offset is applied after scoring. Prefer QueryRequest.limit. Cannot exceed candidate_count when both are present or the selected provider's candidate ceiling; Vertex currently accepts at most 200."
            }
          },
          "required": [
            "provider"
          ]
        },
        {
          "oneOf": [
            {
              "$ref": "#/$defs/CloudflareRerankerConfig"
            },
            {
              "$ref": "#/$defs/AntflyRerankerConfig"
            },
            {
              "$ref": "#/$defs/CohereRerankerConfig"
            },
            {
              "$ref": "#/$defs/VertexRerankerConfig"
            }
          ]
        }
      ]
    },
    "RerankerProvider": {
      "type": "string",
      "enum": [
        "cloudflare",
        "antfly",
        "cohere",
        "vertex"
      ],
      "description": "The reranking provider to use."
    },
    "RetrievalAgentSteps": {
      "type": "object",
      "description": "Configuration for the retrieval agent's pipeline steps and tool-use behavior.\nEach step can have its own generator (or chain of generators) and step-specific options.\nIf a step is not configured, it is skipped (retrieval always runs).\n",
      "properties": {
        "classification": {
          "$ref": "#/$defs/ClassificationStepConfig",
          "description": "Configuration for query classification and transformation.\nWhen set, runs classification before retrieval to select the optimal\nstrategy (simple/decompose/step_back/hyde) and transform the query.\n"
        },
        "retrieval": {
          "$ref": "#/$defs/RetrievalStepConfig",
          "description": "Configuration for retrieval tool execution. Retrieval-step tools\nnarrow the top-level tools policy when both are provided.\n"
        },
        "generation": {
          "$ref": "#/$defs/GenerationStepConfig",
          "description": "Configuration for generation from retrieved documents.\nWhen set, generates a response with citations after retrieval completes.\n"
        },
        "followup": {
          "$ref": "#/$defs/FollowupStepConfig",
          "description": "Configuration for generating follow-up questions.\nRequires steps.generation to be set.\n"
        },
        "confidence": {
          "$ref": "#/$defs/ConfidenceStepConfig",
          "description": "Configuration for confidence assessment of the generated response.\nRequires steps.generation to be set.\n"
        },
        "eval": {
          "$ref": "#/$defs/EvalConfig",
          "description": "Configuration for inline evaluation. Runs evaluators on retrieved\ndocuments and/or generated response. Requires steps.generation for\ngeneration-quality evaluators (faithfulness, completeness, etc.).\n"
        }
      }
    },
    "RetrievalNavigationConfig": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "query_index",
        "strategy",
        "selection",
        "index"
      ],
      "description": "Retrieval-step navigation targeting one ordinary query. Graph navigation\nfollows one path; tree navigation explores a retained branch frontier.\nAgentic selection uses the enclosing model and budgets. Ranked selection\nis supported for trees and uses the existing deterministic tree traversal.\nAgentic selection requires agentic mode and a retrieval generator. Search\nstarts exploration; navigation selects only an offered, unvisited node.\nAll reads enforce mandatory predicates and authenticated row filters.\n",
      "properties": {
        "query_index": {
          "type": "integer",
          "minimum": 0,
          "description": "Zero-based index into the enclosing request queries."
        },
        "strategy": {
          "$ref": "#/$defs/RetrievalNavigationStrategy"
        },
        "selection": {
          "$ref": "#/$defs/RetrievalNavigationSelection",
          "description": "Ranked selection is supported only with strategy tree."
        },
        "max_depth": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "description": "Tree-only maximum depth from the start node (depth zero); defaults to 5."
        },
        "beam_width": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "description": "Tree-only maximum children offered per expansion; defaults to 3."
        },
        "index": {
          "type": "string",
          "minLength": 1,
          "pattern": ".*\\S.*",
          "description": "Graph index used for every neighbor read."
        },
        "start_nodes": {
          "type": "string",
          "minLength": 1,
          "description": "Ranked-tree-only seed selector (comma-separated keys, $roots, or a prior-result selector). Mutually exclusive with start_key."
        },
        "start_key": {
          "type": "string",
          "minLength": 1,
          "description": "Literal start document key. Agentic selection defaults to the first query hit; ranked selection defaults to seed results or prior query hits."
        },
        "direction": {
          "$ref": "#/$defs/EdgeDirection",
          "description": "Direction for every hop; defaults to out."
        },
        "edge_types": {
          "type": "array",
          "maxItems": 64,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/GraphEdgeType"
          }
        },
        "max_steps": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "description": "Graph-only maximum moves after the start node (default 8). The enclosing agent's iteration and tool limits also apply."
        },
        "neighbor_limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 256,
          "description": "Graph-only maximum candidate neighbors per node (default 8), further limited by the context budget."
        },
        "instruction": {
          "type": "string",
          "minLength": 1,
          "description": "Optional caller-supplied workflow instruction retained in agent history."
        },
        "instruction_field": {
          "type": "string",
          "minLength": 1,
          "description": "Explicitly opt in to following instructions from this top-level string\nfield of each visited document. Instructions accumulate in agent history.\nOther document fields and unvisited neighbors remain untrusted evidence.\nThe field must be included if the query uses a fields projection.\n"
        }
      }
    },
    "RetrievalNavigationSelection": {
      "type": "string",
      "enum": [
        "agentic",
        "ranked"
      ]
    },
    "RetrievalNavigationStrategy": {
      "type": "string",
      "enum": [
        "tree",
        "graph"
      ]
    },
    "RetrievalStepConfig": {
      "type": "object",
      "description": "Configuration for the retrieval step. Retrieval tools are constrained by\nthe top-level request tools policy when both are present.\n",
      "properties": {
        "navigation": {
          "$ref": "#/$defs/RetrievalNavigationConfig",
          "description": "Navigation policy for one query; incompatible with graph_queries on that query."
        },
        "tools": {
          "$ref": "#/$defs/ChatToolsConfig",
          "description": "Tool configuration for the retrieval step. When set, this narrows\nthe top-level tools policy for retrieval execution.\n"
        }
      }
    },
    "RetryConfig": {
      "type": "object",
      "description": "Retry configuration for generator calls",
      "properties": {
        "max_attempts": {
          "type": "integer",
          "default": 3,
          "minimum": 1,
          "maximum": 10,
          "description": "Maximum number of retry attempts"
        },
        "initial_backoff_ms": {
          "type": "integer",
          "default": 1000,
          "minimum": 100,
          "description": "Initial backoff delay in milliseconds"
        },
        "backoff_multiplier": {
          "type": "number",
          "format": "float",
          "default": 2.0,
          "minimum": 1.0,
          "maximum": 5.0,
          "description": "Multiplier for exponential backoff"
        },
        "max_backoff_ms": {
          "type": "integer",
          "default": 30000,
          "description": "Maximum backoff delay in milliseconds"
        }
      }
    },
    "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"
    },
    "SerperSearchConfig": {
      "type": "object",
      "description": "Configuration for Serper.dev Google Search API.\n\nSerper provides a simpler alternative to Google Custom Search with\ncompetitive pricing and easy setup.\n\n**Setup:**\n1. Sign up at https://serper.dev\n2. Get API key from dashboard\n\n**Docs:** https://serper.dev/docs\n",
      "allOf": [
        {
          "$ref": "#/$defs/WebSearchConfig"
        },
        {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "serper"
              ]
            },
            "api_key": {
              "type": "string",
              "description": "Serper API key (or set SERPER_API_KEY env var)"
            },
            "search_type": {
              "type": "string",
              "enum": [
                "search",
                "news",
                "images",
                "places",
                "shopping"
              ],
              "description": "Type of search to perform"
            },
            "time_period": {
              "type": "string",
              "enum": [
                "d",
                "w",
                "m",
                "y"
              ],
              "description": "Time period filter: d=day, w=week, m=month, y=year"
            }
          }
        }
      ]
    },
    "SignificanceAlgorithm": {
      "type": "string",
      "enum": [
        "jlh",
        "mutual_information",
        "chi_squared",
        "percentage"
      ],
      "description": "Algorithm for computing term significance:\n- jlh: JLH algorithm (default)\n- mutual_information: Mutual Information\n- chi_squared: Chi-squared test\n- percentage: Simple percentage comparison\n"
    },
    "SortField": {
      "type": "object",
      "description": "A single sort field with direction.",
      "additionalProperties": false,
      "required": [
        "field"
      ],
      "properties": {
        "field": {
          "type": "string",
          "description": "The field name to sort by."
        },
        "desc": {
          "type": "boolean",
          "default": false,
          "description": "Sort direction. true = descending, false = ascending."
        }
      }
    },
    "TavilySearchConfig": {
      "type": "object",
      "description": "Configuration for Tavily AI Search API.\n\nTavily is optimized for RAG and AI applications, providing\npre-processed results with summaries and relevance scoring.\n\n**Setup:**\n1. Sign up at https://tavily.com\n2. Get API key from dashboard\n\n**Docs:** https://docs.tavily.com\n",
      "allOf": [
        {
          "$ref": "#/$defs/WebSearchConfig"
        },
        {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "tavily"
              ]
            },
            "api_key": {
              "type": "string",
              "description": "Tavily API key (or set TAVILY_API_KEY env var)"
            },
            "search_depth": {
              "type": "string",
              "enum": [
                "basic",
                "advanced"
              ],
              "description": "Search depth:\n- basic: Fast search with standard results\n- advanced: Deeper search with more comprehensive results\n"
            },
            "include_answer": {
              "type": "boolean",
              "description": "Include AI-generated answer summary"
            },
            "include_raw_content": {
              "type": "boolean",
              "description": "Include raw HTML content of pages"
            },
            "include_domains": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Only include results from these domains"
            },
            "exclude_domains": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Exclude results from these domains"
            }
          }
        }
      ]
    },
    "TermQuery": {
      "type": "object",
      "description": "Match an indexed post-analysis term exactly. Use match for analyzed natural-language input.",
      "properties": {
        "case_insensitive": {
          "type": "boolean",
          "default": false,
          "description": "Fold ASCII letter case when matching indexed terms, without stemming the pattern."
        },
        "term": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "term"
      ]
    },
    "TermRangeQuery": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "min": {
          "type": [
            "string",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "max": {
          "type": [
            "string",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_min": {
          "type": [
            "boolean",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "inclusive_max": {
          "type": [
            "boolean",
            "null"
          ],
          "x-go-type-skip-optional-pointer": false
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      }
    },
    "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."
        }
      }
    },
    "ValueVerification": {
      "type": "object",
      "additionalProperties": false,
      "description": "Execution policy for logical string-value operations. Limits apply to\nverification work per shard request, including repeated leaf evaluations.\nExhaustion fails explicitly; it never returns a successful partial result.\n",
      "properties": {
        "allow_scan": {
          "type": "boolean",
          "default": false,
          "description": "Permit logical value verification without an indexed candidate constraint."
        },
        "max_documents": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "default": 100000
        },
        "max_bytes": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "default": 67108864
        },
        "max_regex_work": {
          "type": "integer",
          "format": "int64",
          "minimum": 1,
          "default": 100000000,
          "description": "Bound on the sum of original string bytes multiplied by compiled regex states. Charged before regex evaluation; sensitive literals bypass this work."
        }
      }
    },
    "VertexGeneratorConfig": {
      "type": "object",
      "description": "Configuration for Google Cloud Vertex AI generative models.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "vertex"
          ]
        },
        "model": {
          "type": "string",
          "description": "The name of the Vertex AI model to use.",
          "default": "gemini-2.5-flash"
        },
        "project_id": {
          "type": "string",
          "description": "Google Cloud project ID."
        },
        "location": {
          "type": "string",
          "description": "Google Cloud region for Vertex AI API.",
          "default": "us-central1"
        },
        "credentials_path": {
          "type": "string",
          "writeOnly": true,
          "description": "Path to service account JSON key file."
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "description": "Controls randomness in generation (0.0-2.0).",
          "minimum": 0.0,
          "maximum": 2.0
        },
        "max_tokens": {
          "type": "integer",
          "description": "Maximum number of tokens to generate in the response."
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "description": "Nucleus sampling parameter (0.0-1.0).",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "top_k": {
          "type": "integer",
          "description": "Top-k sampling parameter."
        }
      },
      "required": [
        "provider",
        "model"
      ]
    },
    "VertexRerankerConfig": {
      "type": "object",
      "description": "Configuration for the Google Vertex AI Ranking API.\n\nUses Application Default Credentials (ADC) or explicit credentials path.\n\n**Prerequisites:**\n- Enable Discovery Engine API: `gcloud services enable discoveryengine.googleapis.com`\n- Grant IAM role: `roles/discoveryengine.admin` (includes `discoveryengine.rankingConfigs.rank` permission)\n\n**Models:** semantic-ranker-default@latest (default), semantic-ranker-fast-004\n\n**Docs:** https://cloud.google.com/generative-ai-app-builder/docs/ranking\n\n**IAM:** https://cloud.google.com/generative-ai-app-builder/docs/access-control",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "vertex"
          ]
        },
        "model": {
          "type": "string",
          "description": "The ranking model to use.",
          "default": "semantic-ranker-default@latest"
        },
        "project_id": {
          "type": "string",
          "description": "Google Cloud project ID. Shared Vertex credential field; see vertex.yaml#/components/schemas/VertexCredentials. Falls back to GOOGLE_CLOUD_PROJECT environment variable."
        },
        "credentials_path": {
          "type": "string",
          "description": "Path to an ADC credential JSON file (service-account, authorized-user, or external-account). Shared Vertex credential field; see vertex.yaml#/components/schemas/VertexCredentials. Falls back to the default ADC chain."
        }
      },
      "required": [
        "provider"
      ]
    },
    "VertexSearchConfig": {
      "type": "object",
      "description": "Configuration for Google Cloud Agent Search / Vertex AI Search.\n\nUse this for bounded Google Cloud search over configured data stores or\nverified websites. The provider token is `vertex` to match Antfly's\nexisting Google Cloud provider convention.\n\n**Setup:**\n1. Enable Discovery Engine API in Google Cloud\n2. Create an Agent Search app/data store\n3. Grant service account access to query the serving config\n\n**Docs:** https://cloud.google.com/generative-ai-app-builder/docs\n",
      "allOf": [
        {
          "$ref": "#/$defs/WebSearchConfig"
        },
        {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "vertex"
              ]
            },
            "service": {
              "type": "string",
              "enum": [
                "agent_search"
              ],
              "description": "Google Cloud search service flavor"
            },
            "project_id": {
              "type": "string",
              "description": "Google Cloud project ID. Falls back to GOOGLE_CLOUD_PROJECT."
            },
            "location": {
              "type": "string",
              "description": "Google Cloud location. Falls back to GOOGLE_CLOUD_LOCATION."
            },
            "data_store": {
              "type": "string",
              "description": "Agent Search data store ID."
            },
            "serving_config": {
              "type": "string",
              "description": "Agent Search serving config ID."
            },
            "credentials_path": {
              "type": "string",
              "description": "Service account JSON path. Falls back to GOOGLE_APPLICATION_CREDENTIALS."
            }
          }
        }
      ]
    },
    "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."
        }
      }
    },
    "WebSearchConfig": {
      "description": "A unified configuration for web search providers.\n\nEach provider has specific configuration requirements. Use the appropriate\nprovider-specific config or set common options at the top level.\n\nOmitted options inherit the named connection when one is supplied.\nInline configurations preserve omission; clients must not materialize\ndefaults as overrides. Without a connection, the server applies provider\ndefaults (Exa: 5 results, 10000 ms timeout, safe search enabled, content\nand highlights disabled, and auto search).\n\n**Environment Variables (fallbacks):**\n- EXA_API_KEY\n- SERPER_API_KEY\n- TAVILY_API_KEY\n- BRAVE_API_KEY\n- YOU_API_KEY\n- LINKUP_API_KEY\n- GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION\n",
      "type": "object",
      "required": [
        "provider"
      ],
      "properties": {
        "provider": {
          "$ref": "#/$defs/WebSearchProvider"
        },
        "api_key": {
          "type": "string",
          "description": "Provider API key or secret reference. Prefer named web_search connections for production use."
        },
        "endpoint": {
          "type": "string",
          "description": "Provider endpoint override when applicable"
        },
        "project_id": {
          "type": "string",
          "description": "Google Cloud project ID for provider vertex. Shared Vertex credential field; see vertex.yaml#/components/schemas/VertexCredentials. Falls back to GOOGLE_CLOUD_PROJECT."
        },
        "location": {
          "type": "string",
          "description": "Google Cloud location for provider vertex. Shared Vertex credential field; see vertex.yaml#/components/schemas/VertexCredentials. Falls back to GOOGLE_CLOUD_LOCATION, then global."
        },
        "data_store": {
          "type": "string",
          "description": "Agent Search data store ID for provider vertex."
        },
        "serving_config": {
          "type": "string",
          "description": "Agent Search serving config ID for provider vertex. Defaults to default_config."
        },
        "credentials_path": {
          "type": "string",
          "description": "Service account JSON path for provider vertex. Shared Vertex credential field; see vertex.yaml#/components/schemas/VertexCredentials. Falls back to GOOGLE_APPLICATION_CREDENTIALS or ADC."
        },
        "max_results": {
          "type": "integer",
          "minimum": 1,
          "maximum": 20,
          "description": "Maximum number of search results to return"
        },
        "timeout_ms": {
          "type": "integer",
          "description": "Request timeout in milliseconds"
        },
        "safe_search": {
          "x-go-type-skip-optional-pointer": false,
          "type": "boolean",
          "description": "Enable safe search filtering"
        },
        "language": {
          "type": "string",
          "description": "Preferred language for results (e.g., 'en', 'es', 'fr')"
        },
        "region": {
          "type": "string",
          "description": "Preferred region for results (e.g., 'us', 'uk', 'de')"
        },
        "include_content": {
          "x-go-type-skip-optional-pointer": false,
          "type": "boolean",
          "description": "Ask the provider to return extracted page content when supported"
        },
        "include_highlights": {
          "x-go-type-skip-optional-pointer": false,
          "type": "boolean",
          "description": "Ask the provider to return highlighted passages when supported"
        }
      }
    },
    "WebSearchProvider": {
      "type": "string",
      "enum": [
        "exa",
        "serper",
        "tavily",
        "brave",
        "you",
        "linkup",
        "vertex"
      ],
      "description": "The web search provider to use.\n\n- **exa**: Exa neural/semantic web search API\n- **serper**: Serper.dev Google Search API (simpler setup)\n- **tavily**: Tavily AI Search API (optimized for RAG)\n- **brave**: Brave Search API\n- **you**: You.com Search API for agent and research workflows\n- **linkup**: Linkup Search API for web search and content retrieval\n- **vertex**: Google Cloud Agent Search / Vertex AI Search\n"
    },
    "WebSearchProviderConfig": {
      "description": "Provider-specific inline web search configuration.",
      "oneOf": [
        {
          "$ref": "#/$defs/ExaSearchConfig"
        },
        {
          "$ref": "#/$defs/SerperSearchConfig"
        },
        {
          "$ref": "#/$defs/TavilySearchConfig"
        },
        {
          "$ref": "#/$defs/BraveSearchConfig"
        },
        {
          "$ref": "#/$defs/YouSearchConfig"
        },
        {
          "$ref": "#/$defs/LinkupSearchConfig"
        },
        {
          "$ref": "#/$defs/VertexSearchConfig"
        }
      ]
    },
    "WildcardQuery": {
      "type": "object",
      "description": "Match post-analysis indexed terms. Patterns are not stemmed; use match for analyzed natural-language input.",
      "properties": {
        "case_insensitive": {
          "type": "boolean",
          "default": false,
          "description": "Fold ASCII letter case when matching indexed terms, without stemming the pattern."
        },
        "wildcard": {
          "type": "string"
        },
        "field": {
          "type": "string"
        },
        "boost": {
          "$ref": "#/$defs/Boost"
        }
      },
      "required": [
        "wildcard"
      ]
    },
    "YouSearchConfig": {
      "type": "object",
      "description": "Configuration for You.com Search API.\n\nYou.com is useful for agentic search and research-oriented result\nretrieval.\n\n**Setup:**\n1. Sign up for You.com API access\n2. Get API key from dashboard\n\n**Docs:** https://api.you.com\n",
      "allOf": [
        {
          "$ref": "#/$defs/WebSearchConfig"
        },
        {
          "type": "object",
          "properties": {
            "provider": {
              "type": "string",
              "enum": [
                "you"
              ]
            },
            "api_key": {
              "type": "string",
              "description": "You.com API key (or set YOU_API_KEY env var)"
            },
            "endpoint": {
              "type": "string",
              "format": "uri",
              "description": "You.com API endpoint URL"
            }
          }
        }
      ]
    }
  }
}