ddgs-search

# ddgs-search

## Why This Skill?

🆓 **Completely free** — no API keys, no subscriptions, no rate limits, no billing surprises.

🔍 **8 search engines in one** — Google, Bing, DuckDuckGo, Brave, Yandex, Yahoo, Wikipedia, and Mojeek. Switch engines with a single flag. Most search skills only support one.

🎓 **Built-in arXiv research search** — search academic papers directly via arXiv's free API. Returns authors, categories, abstracts, and publication dates. Perfect for researchers, students, and AI/ML practitioners.

🔌 **Drop-in replacement** — outputs web-search-plus compatible JSON, so it works with any skill or tool that expects that format. Zero config migration.

⚡ **Lightweight** — single pip package, no browser automation, no headless Chrome. Searches complete in 1-3 seconds.

## Install

```bash
python3 scripts/install.py
```

Works on **macOS, Linux, and Windows**. Installs the `ddgs` package, verifies CLI access, and runs a quick search test.

### Manual install
```bash
pip install ddgs
```

## Web Search

### CLI wrapper (recommended)

The `ddgs-search` wrapper outputs clean JSON to stdout with no interactive prompts or abort issues:

```bash
# Google (default)
ddgs-search "your query" 5 google

# Other engines
ddgs-search "your query" 3 duckduckgo
ddgs-search "your query" 5 brave
ddgs-search "your query" 10 yandex
```

### Python script (web-search-plus compatible JSON)

```bash
# Google (default)
python3 scripts/search.py -q "your query" -m 5

# Other engines
python3 scripts/search.py -q "your query" -b duckduckgo
python3 scripts/search.py -q "your query" -b brave
python3 scripts/search.py -q "your query" -b yandex
python3 scripts/search.py -q "your query" -b yahoo
python3 scripts/search.py -q "your query" -b wikipedia
```

Output (web-search-plus compatible JSON):
```json
{
  "provider": "ddgs",
  "results": [
    {"title": "...", "url": "...", "snippet": "...", "published_date": "..."}
  ]
}
```

## arXiv Search

```bash
# Search by topic
python3...

# ddgs-search

Free multi-engine web search skill for [OpenClaw](https://github.com/camopel/openclaw) agents. No API keys required.

Supports: **Google, Bing, DuckDuckGo, Brave, Yandex, Yahoo, Wikipedia** + **arXiv API** for academic papers.

## Install

```bash
python3 scripts/install.py
```

Installs the `ddgs` Python package and verifies the CLI is accessible.

## Scripts

### `scripts/search.py` — Web search

```bash
python3 scripts/search.py -q "your query" -m 5
python3 scripts/search.py -q "AI news" -m 10 -b bing
python3 scripts/search.py -q "python tutorial" -m 5 -b google
```

**Options:**
| Flag | Description | Default |
|------|-------------|---------|
| `-q` | Search query | (required) |
| `-m` | Max results | 5 |
| `-b` | Backend: `duckduckgo`, `google`, `bing`, `brave`, `yandex`, `yahoo` | `duckduckgo` |

**Output:** JSON with `results` array of `{title, url, snippet}`.

### `scripts/arxiv_search.py` — arXiv paper search

```bash
python3 scripts/arxiv_search.py -q "transformer architecture" -m 10
python3 scripts/arxiv_search.py -q "diffusion models" -m 5 --sort-by relevance
```

**Options:**
| Flag | Description | Default |
|------|-------------|---------|
| `-q` | Search query | (required) |
| `-m` | Max results | 10 |
| `--sort-by` | `relevance` or `date` | `relevance` |

**Output:** JSON with `results` array including `arxiv_id`, `title`, `abstract`, `authors`, `published`, `pdf_url`.

## Usage in OpenClaw

The skill is registered with OpenClaw and provides two tools:

- **`web_search`** — Search the web across multiple engines
- **`arxiv_search`** — Search academic papers on arXiv

## Requirements

- Python 3.8+
- `ddgs` package (installed automatically)
- macOS or Linux (Windows: partial support)

## License

MIT