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

# Natural-Language Search

> Ask Roboticks questions in plain English - "failing tests on main from last week", "uncovered requirements for IEC 61508". The platform parses your intent, runs the query, and links to the answer.

# Natural-language search

The global search bar at the top of every page accepts plain-English queries. Behind the scenes a Haiku-tier AI call parses the intent, picks the target entity (test runs, requirements, logs, evidence packs, standards), extracts filters, and returns a structured answer with deterministic click-through URLs.

## What it can answer

Examples that work today:

| You type                                     | What it does                                                                                                                                            |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "failing tests on main from last week"       | Targets `test_runs` with `branch=main`, `status=failed`, time range `7d`. Links you to `/{org}/{project}/test-runs?branch=main&status=failed&since=7d`. |
| "uncovered requirements for IEC 61508 SIL 2" | Targets `requirements` with `standard=iec-61508`, `sil=2`, `coverage=uncovered`.                                                                        |
| "what does REQ-014 confirm"                  | Targets `requirements` with `id=REQ-014`.                                                                                                               |
| "evidence packs for release v2.4.0"          | Targets `evidence_packs` with `release_tag=v2.4.0`.                                                                                                     |
| "logs mentioning ros2\_control timeout"      | Targets `logs` with full-text `ros2_control timeout`.                                                                                                   |

The LLM picks the target entity and the filter values. The platform builds the URL itself — the LLM never invents a link. If the platform can't be confident, it falls back to traditional text search and surfaces the AI-suggested URLs as secondary options.

## What you get back

```json theme={null}
{
  "query": "failing tests on main from last week",
  "is_ai_query": true,
  "ai_result": {
    "answer": "Targets failed test runs on the main branch in the last 7 days.",
    "confidence": 0.92,
    "sources": [],
    "suggested_actions": [
      {"label": "View failed runs on main", "url": "/.../test-runs?branch=main&status=failed&since=7d"}
    ],
    "follow_up_questions": [
      "Just the runs whose failures touched safety-tagged tests?",
      "Group by test name to find flaky cases?"
    ]
  },
  "tokens_used": 42,
  "processing_time_ms": 410
}
```

The `follow_up_questions` are one-click — clicking them re-runs `q` with the new phrasing.

## Endpoint

```http theme={null}
GET /api/v1/organizations/{org}/projects/{project}/search/ai?q=<query>
```

Returns 402 if the org is out of `ai_tokens`. Returns 200 + `is_ai_query: false` for queries the platform decided to handle with traditional search (short queries, exact-ID lookups).

## Plan gating

Costs 1 ai-token per parse call (`SEARCH_QUERY_PARSE` task type — Haiku at 2k input). Free plan's 100k grant is plenty.

## What it does NOT do

* It does **not** answer the question itself. It parses intent into a filter and links you to the structured view. The answer comes from the actual matrix / list page the link opens.
* It does **not** read your repo source or your private logs to "answer questions" about them. It only uses the parsed query intent.
* It does **not** invent IDs. If you ask "show me REQ-9999" and REQ-9999 doesn't exist, the structured page will render empty — the AI doesn't hallucinate rows into existence.

## Next

<CardGroup cols={2}>
  <Card title="AI overview" icon="brain" href="/ai/overview">
    Every AI surface on the platform and what they cost.
  </Card>

  <Card title="Traceability matrix" icon="table-cells" href="/traceability/matrix">
    Where most of these queries actually land.
  </Card>
</CardGroup>