web-search

# Web Search

## Overview

Search the web using DuckDuckGo's API to find information across web pages, news articles, images, and videos. Returns results in multiple formats (text, markdown, JSON) with filtering options for time range, region, and safe search.

## When to Use This Skill

Use this skill when users request:
- Web searches for information or resources
- Finding current or recent information online
- Looking up news articles about specific topics
- Searching for images by description or topic
- Finding videos on specific subjects
- Research requiring current web data
- Fact-checking or verification using web sources
- Gathering URLs and resources on a topic

## Prerequisites

OpenSquilla declares the required `duckduckgo-search` Python package as a runtime dependency.
For source checkouts, run the normal project dependency sync before invoking this bundled skill.
The library provides a simple Python interface to DuckDuckGo's search API without requiring API keys or authentication.

## Core Capabilities

### 1. Basic Web Search

Search for web pages and information:

```bash
python {baseDir}/scripts/search.py "<query>"
```

**Example:**
```bash
python {baseDir}/scripts/search.py "python asyncio tutorial"
```

Returns the top 10 web results with titles, URLs, and descriptions in a clean text format.

### 2. Limiting Results

Control the number of results returned:

```bash
python {baseDir}/scripts/search.py "<query>" --max-results <N>
```

**Example:**
```bash
python {baseDir}/scripts/search.py "machine learning frameworks" --max-results 20
```

Useful for:
- Getting more comprehensive results (increase limit)
- Quick lookups with fewer results (decrease limit)
- Balancing detail vs. processing time

### 3. Time Range Filtering

Filter results by recency:

```bash
python {baseDir}/scripts/search.py "<query>" --time-range <d|w|m|y>
```

**Time range options:**
- `d` - Past day
- `w` - Past week
- `m` - Past month
- `y` - Past year

**Example:**
```bash
python {baseDir}/scripts/search.py "artificial intelligence news" --time-range w
```

Great for:
- Finding recent news or updates
- Filtering out outdated content
- Tracking recent developments

### 4. News Search

Search specifically for news articles:

```bash
python {baseDir}/scripts/search.py "<query>" --type news
```

**Example:**
```bash
python {baseDir}/scripts/search.py "climate change" --type news --time-range w --max-results 15
```

News results include:
- Article title
- Source publication
- Publication date
- URL
- Article summary/description

### 5. Image Search

Search for images:

```bash
python {baseDir}/scripts/search.py "<query>" --type images
```

**Example:**
```bash
python {baseDir}/scripts/search.py "sunset over mountains" --type images --max-results 20
```

**Image filtering options:**

Size filters:
```bash
python {baseDir}/scripts/search.py "landscape photos" --type images --image-size Large
```
Options: `Small`, `Medium`, `Large`, `Wallpaper`

Color filters:
```bash
python {baseDir}/scripts/search.py "abstract art" --type images --image-color Blue
```
Options: `color`, `Monochrome`, `Red`, `Orange`, `Yellow`, `Green`, `Blue`, `Purple`, `Pink`, `Brown`, `Black`, `Gray`, `Teal`, `White`

Type filters:
```bash
python {baseDir}/scripts/search.py "icons" --type images --image-type transparent
```
Options: `photo`, `clipart`, `gif`, `transparent`, `line`

Layout filters:
```bash
python {baseDir}/scripts/search.py "wallpapers" --type images --image-layout Wide
```
Options: `Square`, `Tall`, `Wide`

Image results include:
- Image title
- Image URL (direct link to image)
- Thumbnail URL
- Source website
- Dimensions (width x height)

### 6. Video Search

Search for videos:

```bash
python {baseDir}/scripts/search.py "<query>" --type videos
```

**Example:**
```bash
python {baseDir}/scripts/search.py "python tutorial" --type videos --max-results 15
```

**Video filtering options:**

Duration filters:
```bash
python {baseDir}/scripts/search.py "cooking recipes" --type videos --video-duration short
```
Options: `short`, `medium`, `long`

Resolution filters:
```bash
python {baseDir}/scripts/search.py "documentary" --type videos --video-resolution high
```
Options: `high`, `standard`

Video results include:
- Video title
- Publisher/channel
- Duration
- Publication date
- Video URL
- Description

### 7. Region-Specific Search

Search with region-specific results:

```bash
python {baseDir}/scripts/search.py "<query>" --region <region-code>
```

**Common region codes:**
- `us-en` - United States (English)
- `uk-en` - United Kingdom (English)
- `ca-en` - Canada (English)
- `au-en` - Australia (English)
- `de-de` - Germany (German)
- `fr-fr` - France (French)
- `wt-wt` - Worldwide (default)

**Example:**
```bash
python {baseDir}/scripts/search.py "local news" --region us-en --type news
```

### 8. Safe Search Control

Control safe search filtering:

```bash
python {baseDir}/scripts/search.py "<query>" --safe-search <on|moderate|off>
```

**Options:**
- `on` - Strict filtering
- `moderate` - Balanced filtering (default)
- `off` - No filtering

**Example:**
```bash
python {baseDir}/scripts/search.py "medical information" --safe-search on
```

### 9. Output Formats

Choose how results are formatted:

**Text format (default):**
```bash
python {baseDir}/scripts/search.py "quantum computing"
```

Clean, readable plain text with numbered results.

**Markdown format:**
```bash
python {baseDir}/scripts/search.py "quantum computing" --format markdown
```

Formatted markdown with headers, bold text, and links.

**JSON format:**
```bash
python {baseDir}/scripts/search.py "quantum computing" --format json
```

Structured JSON data for programmatic processing.

### 10. Saving Results to File

Save search results to a file:

```bash
python {baseDir}/scripts/search.py "<query>" --output <file-path>
```

**Example:**
```bash
python {baseDir}/scripts/search.py "artificial intelligence" --output ai_results.txt
python {baseDir}/scripts/sear