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

# Code search

> Score which files and folders a coding agent needs for a query.

Nimble code search helps a code search tool decide what to show a coding agent. You send a query and a list of items, where each item is a piece of a file or a folder. For each item, Nimble returns the probability that the agent needs it for the query.

Send the request to `POST /v1/systemone` with one of the code search models. The request uses the System One format with `noul` questions, so clients that already send System One requests can use it.

## Make a request

Question `q0` is about item `n0`, question `q1` is about item `n1`, and so on.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.bespokelabs.ai/v1/systemone \
    -H "Authorization: Bearer $BESPOKE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "nimble-codegrep",
      "state": {
        "query": "Uploads retry forever after a 413 response.",
        "items": [
          {
            "id": "n0",
            "path": "src/upload/retry.py",
            "kind": "file",
            "filePreview": {"text": "def backoff(attempt):\n    while True:\n        retry()"}
          },
          {
            "id": "n1",
            "path": "src/upload",
            "kind": "directory",
            "childPreview": {"entries": [{"name": "retry.py", "kind": "file"}]}
          }
        ]
      },
      "questions": {
        "q0": {"type": "noul", "instructions": "Does the file src/upload/retry.py contain code needed for this query?"},
        "q1": {"type": "noul", "instructions": "Is the directory src/upload worth exploring for this query?"}
      }
    }'
  ```

  ```python Python theme={null}
  from bespokelabs import BespokeLabs

  client = BespokeLabs()  # reads BESPOKE_API_KEY

  response = client.nimble.system_one(
      model="nimble-codegrep",
      state={
          "query": "Uploads retry forever after a 413 response.",
          "items": [
              {
                  "id": "n0",
                  "path": "src/upload/retry.py",
                  "kind": "file",
                  "filePreview": {"text": "def backoff(attempt):\n    while True:\n        retry()"},
              },
              {
                  "id": "n1",
                  "path": "src/upload",
                  "kind": "directory",
                  "childPreview": {"entries": [{"name": "retry.py", "kind": "file"}]},
              },
          ],
      },
      questions={
          "q0": {"type": "noul", "instructions": "Does the file src/upload/retry.py contain code needed for this query?"},
          "q1": {"type": "noul", "instructions": "Is the directory src/upload worth exploring for this query?"},
      },
  )
  keep = [qid for qid, answer in response.answers.items() if answer.noul > 0.5]
  print(keep)
  ```
</CodeGroup>

## Read the answer

```json theme={null}
{
  "model": "nimble-codegrep",
  "effort": "medium",
  "answers": {
    "q0": { "type": "noul", "noul": 0.99 },
    "q1": { "type": "noul", "noul": 0.99 }
  },
  "details": {
    "q0": { "raw": 0.85, "overflow": false, "escalated": false, "scores": { "nimble-codegrep-4b": 0.85 } },
    "q1": { "raw": 0.82, "overflow": false, "escalated": false, "scores": { "nimble-codegrep-4b": 0.82 } }
  },
  "usage": { "input_tokens": 472, "output_tokens": 2 },
  "request_id": "0789d4c7-399f-4e70-9721-9f21bab043bc",
  "escalation_skipped": false
}
```

* Keep the items whose `noul` is above 0.5. Nimble sets the scores so that this keeps about 95% of the items that an agent needs.
* `details.raw` is the model's own probability before that adjustment.
* `details.escalated` says whether a larger model scored the item.
* An item whose prompt is longer than 8,192 tokens is not scored. Its `noul` is 1.0, so you keep it, and `overflow` is `true`.

With the Python SDK, the extra fields are attributes of the response, e.g., `response.details`.

## Models

| Model | How it answers |
| - | - |
| `nimble-codegrep-lite` | A 4B model scores every item. This is the fastest and the cheapest. |
| `nimble-codegrep` | The 4B model scores every item. Then a 27B model scores again the items that the 4B model is unsure about. |
| `nimble-codegrep-max` | The 27B model scores every item. This is the most accurate. |

The 27B model is running on weekdays from 07:30 to 19:00 Pacific time. At other times, it must start before it can answer. Until it is ready, a `nimble-codegrep-max` request gets `503` with a `Retry-After` header. So does a `nimble-codegrep` request with an item that the 4B model is unsure about. Starting takes a few minutes. You are not charged for a `503`.

## Limits

| Limit | Value |
| - | - |
| Questions in a request | 1 to 128 |
| Characters in the state | 2,000,000 |
| Request body | 1 MiB |
| Prompt tokens for one item | 8,192 |

Use `noul` questions. Code search also accepts `boolean` questions, and it answers them the same way, with a `noul` answer.

Send the state as an object with a `query` and `items`. Every item needs an `id`, a `path` and a `kind`. Question `q<i>` is about item `n<i>`, and a question ID with no matching item gets `422`. Code search also accepts a string state and uses it whole for every question, but the models were not trained on that.