nimble-search-reference

What this skill does

# nimble search — reference

Real-time web search with 8 focus modes. Returns results with titles, URLs, and optionally full content and AI answers.

## Table of Contents

- [Parameters](#parameters)
- [Search depth modes](#search-depth-modes)
- [Focus modes](#focus-modes)
- [CLI](#cli)
- [Python SDK](#python-sdk)
- [Response structure](#response-structure)

---

## Parameters

| Parameter                 | Type            | Default  | Description                                                                                                       |
| ------------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `query`                   | string          | required | Search query                                                                                                      |
| `search_depth`            | string          | `deep`   | Content depth: `lite` \| `fast` \| `deep` — see depth table below                                                |
| `focus`                   | string or array | `general`| Focus mode (see table below) or array of specific agent names e.g. `["amazon_serp", "target_serp"]`               |
| `include_answer`          | bool            | `false`  | AI-synthesized answer (premium — retry without if 402/403)                                                        |
| `max_results`             | int             | `10`     | Result count (1–100)                                                                                              |
| `output_format`           | string          | —        | `plain_text` \| `markdown` \| `simplified_html`                                                                   |
| `include_domains`         | array           | —        | Restrict to these domains (max 50)                                                                                |
| `exclude_domains`         | array           | —        | Exclude these domains (max 50)                                                                                    |
| `time_range`              | string          | —        | `hour` \| `day` \| `week` \| `month` \| `year` — cannot combine with dates                                        |
| `start_date` / `end_date` | string          | —        | Date range `YYYY-MM-DD` — cannot combine with `time_range`                                                        |
| `content_type`            | string          | —        | File type filter: `pdf`, `docx`, `xlsx`, `documents`, `spreadsheets`, `presentations` — only with `general` focus |
| `max_subagents`           | int             | —        | Parallel agents for shopping/social/geo/location (1–5)                                                            |
| `country`                 | string          | —        | ISO Alpha-2 geo-targeted results (e.g. `US`)                                                                      |
| `locale`                  | string          | —        | Language code (e.g. `en`, `fr`, `de`)                                                                             |
| `deep_search`             | bool            | —        | **Deprecated** — use `search_depth` instead. `true` = `deep`, `false` = `lite`. Still works for backward compat. |

CLI uses hyphens (`--search-depth`, `--include-answer`). SDK uses underscores (`search_depth`, `include_answer`).

---

## Search depth modes

| Mode   | Content                          | Speed    | Best for                                                        |
| ------ | -------------------------------- | -------- | --------------------------------------------------------------- |
| `lite` | Metadata only (title, URL, snippet) | Fastest | High-volume pipelines, URL discovery, quick filtering           |
| `fast` | Rich cached content              | Fast     | AI agents, RAG, chatbots — quality content without scrape latency |
| `deep` | Full real-time page content      | Slowest  | Research, due diligence, tasks requiring complete source material |

**Default for AI agent use:** prefer `fast` — richest content-to-latency ratio.

---

## Focus modes

| Mode       | Best for                            | Example query                            |
| ---------- | ----------------------------------- | ---------------------------------------- |
| `general`  | Broad web (default)                 | "best practices for X"                   |
| `coding`   | Docs, code, Stack Overflow, GitHub  | "how to implement X in Python"           |
| `news`     | Current events, breaking news       | "EU AI Act enforcement 2026"             |
| `academic` | Research papers, scholarly articles | "transformer attention mechanisms paper" |
| `shopping` | Products, price comparisons         | "best wireless headphones under $200"    |
| `social`   | People, LinkedIn, X, YouTube        | "Jane Doe Head of Engineering"           |
| `geo`      | Geographic and regional data        | "tech companies in Berlin"               |
| `location` | Local businesses, restaurants       | "italian restaurants San Francisco"      |

---

## CLI

```bash
# Fast depth — rich content, low latency (best for agents)
nimble search --query "React server components" --search-depth fast

# Lite — metadata only, fastest
nimble search --query "OpenAI announcements" --focus news --search-depth lite

# Deep — full real-time page scrape
nimble search --query "EU AI Act" --focus news --search-depth deep \
  --start-date 2025-01-01 --end-date 2025-12-31

# With AI answer + domain filter
nimble search --query "Python asyncio best practices" \
  --focus coding --search-depth fast --include-answer \
  --include-domain '["docs.python.org", "realpython.com"]'

# Extract just URLs
nimble --transform "results.#.url" search --query "React tutorials" --search-depth lite
```

## Python SDK

```python
from nimble_python import Nimble
nimble = Nimble(api_key=os.environ["NIMBLE_API_KEY"])

# Fast depth — best default for AI agent use
resp = nimble.search(query="React server components", search_depth="fast")

# Lite — scan many results quickly
resp = nimble.search(
    query="OpenAI announcements",
    focus="news",
    search_depth="lite",
    time_range="week",
)

# Deep — full content for research
resp = nimble.search(
    query="EU AI Act enforcement",
    focus="news",
    search_depth="deep",
    include_answer=True,
)

# Custom focus — explicit agent array
resp = nimble.search(
    query="best wireless headphones",
    focus=["amazon_serp", "walmart_serp"],
    search_depth="fast",
    max_results=10,
)

results = resp.results       # list of result objects
answer = resp.answer         # AI summary (if include_answer=True)
```

---

## Response structure

| Field                            | Type   | Description                                                  |
| -------------------------------- | ------ | ------------------------------------------------------------ |
| `total_results`                  | int    | Total results returned                                       |
| `results`                        | array  | Search results                                               |
| `results[].title`                | string | Page title                                                   |
| `results[].description`          | string | Snippet                                                      |
| `results[].url`                  | string | Page URL                                                     |
| `results[].content`              | string | Page content — cached (`fast`) or real-time scraped (`deep`) |
| `results[].metadata.position`    | int    | Result rank                                                  |
| `results[].metadata.entity_type` | string | e.g. `OrganicResult`                                         |
| `answer`                         | string | AI summary (if `include_answer=True`)