> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-baseline.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Modes

> Choose the right query mode, effort level, and response sections.

Use `POST https://api-beta.ai-baseline.xyz/v2/sandp_500/query` to query filing evidence. Every request includes a natural-language `query` and can optionally set `mode`, `effort`, `metadata_filters`, `include`, and `retrieval`.

The minimal request body contains only `query`:

```json theme={null}
{
  "query": "What supply chain risks did Apple disclose in its 10-K filings?"
}
```

That request defaults to `mode: "basic"` and `effort: "medium"`. It returns rendered `evidence`, `evidence_instructions`, `evidence_budget`, and `summary` by default.

## Modes

| Mode               | Use when                                                                               | Metadata filters |
| ------------------ | -------------------------------------------------------------------------------------- | ---------------- |
| `basic`            | You need the fastest retrieval path and do not need metadata filters.                  | No               |
| `research`         | You want metadata-filtered retrieval.                                                  | Yes              |
| `agentic_research` | You want the API to decompose a higher-effort or comparative question into subqueries. | Yes              |

`basic` rejects non-empty metadata filters. If you send `metadata_filters`, explicitly set `mode` to `research` or `agentic_research`.

## Effort

`effort` controls how much work the API spends on supporting evidence. The default is `medium`.

| Effort   | Typical use                                           |
| -------- | ----------------------------------------------------- |
| `low`    | Fast, focused lookups.                                |
| `medium` | Default balance of effort and latency.                |
| `high`   | Higher effort for difficult or comparative questions. |

## Include Controls

The `include` object controls optional response sections:

```json theme={null}
{
  "include": {
    "evidence": true,
    "evidence_format": "rendered",
    "evidence_instructions": true,
    "agent_context": false,
    "metadata_distribution": true,
    "metadata_dashboard": true,
    "summary": true
  }
}
```

| Field                   | Values                  | Default      |
| ----------------------- | ----------------------- | ------------ |
| `evidence`              | `true` or `false`       | `true`       |
| `evidence_format`       | `"rendered"` or `"xml"` | `"rendered"` |
| `evidence_instructions` | `true` or `false`       | `true`       |
| `agent_context`         | `true` or `false`       | `false`      |
| `metadata_distribution` | `true` or `false`       | `false`      |
| `metadata_dashboard`    | `true` or `false`       | `false`      |
| `summary`               | `true` or `false`       | `true`       |

`evidence: true` returns grounding evidence directly in top-level `evidence`. Use `evidence_format: "rendered"` for XML-like grounding with a trailing `<source_key>` quick reference. This is the recommended default when you want grounded context to pass to your own LLM. Use `evidence_format: "xml"` for the same grounding without that source-key footer.

`evidence_instructions: true` returns top-level `evidence_instructions`, a separate string containing guidance for how a downstream LLM should use the returned evidence to generate a grounded answer. These instructions are returned by default when evidence is included and are not part of the evidence content itself. Set `evidence_instructions: false` to omit them.

`agent_context: true` returns top-level `agent_context`, a derived convenience payload intended for direct handoff to another LLM or agent. It is not the canonical evidence contract. `evidence` remains the canonical grounding evidence field, and `evidence_instructions` remains the canonical downstream answer-generation guidance field.

`agent_context.content_type` is currently always `"text/markdown"`. `agent_context.text` combines the evidence-use instructions with the selected evidence format. For `agentic_research`, it also includes the task-aware `coverage` assessment. `agent_context.source_fields` lists the canonical response fields used to construct the payload.

`agent_context` honors `include.evidence_format`: with `"rendered"`, the context includes rendered evidence; with `"xml"`, it includes XML evidence with the same public XML formatting behavior as top-level `evidence`.

Clients building custom prompts or UIs should use `evidence` and `evidence_instructions` directly. Use `agent_context` when you want one ready-to-feed context block and do not need separate raw fields.

`metadata_distribution: true` returns structured metadata distribution keyed by canonical field names such as `sec_ticker` and `sec_form_type`. Each metric entry includes a readable `display_name` plus `values` for distributions, or `value` for text summaries. `metadata_dashboard: true` can return the rendered dashboard independently.

`summary` contains the selected mode, effort, `submitted_metadata_filters`, `applied_metadata_filters`, warnings, and `evidence_count`, which counts the retrieved evidence paths used to ground the response.

For `agentic_research`, `retrieval_plan.queries[].applied_metadata_filters` shows the metadata filters applied to each retrieval branch.

## Agentic Coverage

`agentic_research` currently decomposes a question into up to four independently required retrieval inputs. For financial comparisons and calculations, these can include every issuer, current and comparison periods, each requested metric, and source inputs such as a numerator and denominator.

The top-level `coverage` object reports whether the delivered evidence covers those planned inputs:

| Coverage status | Meaning                                                                                                                                               |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `complete`      | Every planned requirement has at least one returned evidence chain, and the plan did not omit any requirements.                                       |
| `partial`       | Some requirements are covered while others are missing, omitted by the evidence token budget, or could not fit within the requirement-planning limit. |
| `none`          | No planned requirement has returned evidence.                                                                                                         |
| `not_assessed`  | Requirement decomposition failed and retrieval fell back to the original query.                                                                       |

Each `coverage.requirements[]` item includes the requirement `id`, `label`, retrieval `query`, `retrieved_evidence_count`, `returned_evidence_count`, and one of these statuses:

* `covered`: at least one associated evidence chain was returned.
* `missing`: no associated evidence chain survived retrieval and delivery.
* `omitted_by_budget`: evidence was available for this requirement, but none of its complete chains fit within `retrieval.max_evidence_tokens`.

`coverage.limitations` can contain `planning_fallback`, `requirement_limit`, `missing_evidence`, or `token_budget`. `coverage.omitted_requirements` lists required inputs that did not fit within the decomposition limit.

Coverage is a retrieval-completeness signal. It means evidence was returned for every planned input; it does not independently certify that the evidence is factually correct or sufficient for a final calculation.

## Retrieval Controls

The public `/query` API supports evidence-count and estimated-token controls:

```json theme={null}
{
  "retrieval": {
    "max_evidence": 25,
    "max_evidence_tokens": 12000
  }
}
```

`retrieval.max_evidence` must be a positive integer. It controls the maximum number of evidence chains returned to the API consumer.

`retrieval.max_evidence_tokens` must also be a positive integer. It is a strict cap on the deterministic estimated size of the returned evidence. Selection keeps complete evidence chains, prioritizes chains that cover the most uncovered agentic requirements, and then fills the remaining budget in rerank order. The evidence and its regenerated source registry are re-estimated after each candidate, so the final estimate does not exceed the requested cap.

The estimator is `chars_div_4_v1`, calculated as `ceil(projected evidence characters / 4)`. It is deterministic and useful for payload planning, but it is not a provider-exact tokenizer. Evidence instructions, dashboards, and agent-context wrappers are excluded.

Both controls are uncapped by default. If `max_evidence` is omitted, no caller-supplied chain-count cap is added after the normal retrieval, relevance filtering, and deduplication stages. If `max_evidence_tokens` is omitted or `null`, no token cap is applied.

Whenever `evidence` or `agent_context` is requested, the response includes `evidence_budget`:

```json theme={null}
{
  "evidence_budget": {
    "requested_max_tokens": 12000,
    "estimator": "chars_div_4_v1",
    "estimated_tokens": 8460,
    "available_evidence_count": 18,
    "returned_evidence_count": 12,
    "truncated": true
  }
}
```

With no token cap, `requested_max_tokens` is `null`; the API returns all evidence that survived the earlier stages and provides estimate metadata only.

If no complete chain fits within the requested cap, `evidence` is omitted rather than cut into a malformed chain. This is not reported as `"No data found"` because retrieval did find evidence.

Other retrieval control fields are not supported on the public `/query` API and are rejected by request validation.

## Request Examples

Structured/custom integrations can use the canonical fields directly and only override the defaults they need to change:

```json theme={null}
{
  "query": "What supply chain risks did Apple disclose in its 10-K Item 1A filings?",
  "mode": "research",
  "effort": "medium",
  "metadata_filters": {
    "sec_ticker": "AAPL",
    "sec_form_type": "10-K"
  },
  "include": {
    "summary": false
  },
  "retrieval": {
    "max_evidence": 25,
    "max_evidence_tokens": 12000
  }
}
```

Direct LLM or agent handoff can request `agent_context` without duplicated raw fields:

```json theme={null}
{
  "query": "What supply chain risks did Apple disclose in its 10-K Item 1A filings?",
  "mode": "research",
  "effort": "medium",
  "metadata_filters": {
    "sec_ticker": "AAPL",
    "sec_form_type": "10-K"
  },
  "include": {
    "evidence": false,
    "evidence_instructions": false,
    "agent_context": true
  }
}
```

That request returns `agent_context` and omits top-level `evidence` and `evidence_instructions`.