nimble-web-search

# Nimble Web Search

Real-time web intelligence using Nimble Search API with specialized focus modes and AI-powered result synthesis.

## Prerequisites

**Nimble API Key Required** - Get your key at https://www.nimbleway.com/

### Configuration

Set the `NIMBLE_API_KEY` environment variable using your platform's method:

**Claude Code:**
```json
// ~/.claude/settings.json
{
  "env": {
    "NIMBLE_API_KEY": "your-api-key-here"
  }
}
```

**VS Code/GitHub Copilot:**
- Add to `.github/skills/` directory in your repository
- Or use GitHub Actions secrets for the copilot environment

**Shell/Terminal:**
```bash
export NIMBLE_API_KEY="your-api-key-here"
```

**Any Platform:**
The skill checks for the `NIMBLE_API_KEY` environment variable regardless of how you set it.

### API Key Validation

**IMPORTANT: Before making any search request, verify the API key is configured:**

```bash
# Check if API key is set
if [ -z "$NIMBLE_API_KEY" ]; then
  echo "❌ Error: NIMBLE_API_KEY not configured"
  echo ""
  echo "Get your API key: https://www.nimbleway.com/"
  echo ""
  echo "Configure using your platform's method:"
  echo "- Claude Code: Add to ~/.claude/settings.json"
  echo "- GitHub Copilot: Use GitHub Actions secrets"
  echo "- Shell: export NIMBLE_API_KEY=\"your-key\""
  echo ""
  echo "Do NOT fall back to other search tools - guide the user to configure first."
  exit 1
fi
```

## Overview

Nimble Search provides real-time web intelligence with 8 specialized focus modes optimized for different types of queries. Get instant access to current web data with AI-powered answer generation, deep content extraction, URL discovery, and smart filtering by domain and date.

**IMPORTANT: Always Specify These Parameters**

When using this skill, **always explicitly set** the following parameters in your requests:

- `deep_search`: **Default to `false`** for 5-10x faster responses
  - **Use `false` (FAST MODE - 1-3 seconds):** For 95% of use cases - URL discovery, research, comparisons, answer generation
  - **Use `true` (DEEP MODE - 5-15 seconds):** Only when you specifically need full page content extracted for archiving or detailed analysis

- `focus`: **Default to `"general"`** for broad searches
  - Change to specific mode (`coding`, `news`, `academic`, `shopping`, `social`, `geo`, `location`) for targeted results

- `max_results`: **Default to `10`** - Balanced speed and coverage

**Performance Awareness:** By explicitly setting `deep_search: false`, you're choosing fast mode and should expect results in 1-3 seconds. If you set `deep_search: true`, expect 5-15 seconds response time.

### Quick Start

Use the wrapper script for the simplest experience:

```bash
# ALWAYS specify deep_search explicitly
./scripts/search.sh '{
  "query": "React hooks",
  "deep_search": false
}'
```

The script automatically handles authentication, tracking headers, and output formatting.

### When to Use Each Mode

**Use `deep_search: false` (FAST MODE - 1-3 seconds) - Default for 95% of cases:**
- ✅ Finding URLs and discovering resources
- ✅ Research and topic exploration
- ✅ Answer generation and summaries
- ✅ Product comparisons
- ✅ News monitoring
- ✅ Any time you DON'T need full article text

**Use `deep_search: true` (DEEP MODE - 5-15 seconds) - Only when specifically needed:**
- 📄 Archiving full article content
- 📄 Extracting complete documentation
- 📄 Building text datasets
- 📄 Processing full page content for analysis

**Decision Rule:** If you're not sure, use `deep_search: false`. You can always re-run with `true` if needed.

## Core Capabilities

### Focus Modes

Choose the appropriate focus mode based on your query type:

1. **general** - Default mode for broad web searches
2. **coding** - Real-time access to technical documentation, code examples, programming resources
3. **news** - Real-time news articles, current events, breaking stories
4. **academic** - Research papers, scholarly articles, academic resources
5. **shopping** - Real-time product searches, e-commerce results, price comparisons
6. **social** - Real-time social media posts, discussions, trending community content
7. **geo** - Location-based searches, geographic information
8. **location** - Local business searches, place-specific queries

### Search Features

**LLM Answer Generation**
- Request AI-generated answers synthesized from search results
- Powered by Claude for high-quality summaries
- Include citations to source URLs
- Best for: Research questions, topic overviews, comparative analysis

**URL Discovery**
- Extract 1-20 most relevant URLs for a query
- Useful for building reading lists and reference collections
- Returns URLs with titles and descriptions
- Best for: Resource gathering, link building, research preparation

**Deep Content Extraction**
- **Default (Recommended):** `deep_search=false` - Fastest response, returns titles, descriptions, and URLs
- **Optional:** `deep_search=true` - Slower, extracts full page content
- **Important:** Most use cases work perfectly with `deep_search=false` (the default)
- Available formats when deep_search=true: markdown, plain_text, simplified_html
- Only enable deep search for: Detailed content analysis, archiving, or comprehensive text extraction needs

**Domain Filtering**
- Include specific domains (e.g., github.com, stackoverflow.com)
- Exclude domains to remove unwanted sources
- Combine multiple domains for focused searches
- Best for: Targeted research, brand monitoring, competitive analysis

**Time Filtering**
- **Recommended:** Use `time_range` for real-time recency filtering (hour, day, week, month, year)
- **Alternative:** Use `start_date`/`end_date` for precise date ranges (YYYY-MM-DD)
- Note: `time_range` and date filters are mutually exclusive
- Best for: Real-time news monitoring, recent developments, temporal analysis

## Usage Patterns

All examples below use the `./scripts/search.sh` wrapper for simplicity. For raw API usage, see the [API Integration](#api-integration) section.

### Basic Search

Quick search in fast mode (ALWAYS specify deep_search explicitly):

```bash
./scripts/search.sh '{
  "query": "React Server Components tutorial",
  "deep_search": false
}'
```

For technical content, specify coding focus (still fast mode):

```bash
./scripts/search.sh '{
  "query": "React Server Components tutorial",
  "focus": "coding",
  "deep_search": false
}'
```

### Research with AI Summary

Get synthesized insights from multiple sources (fast mode works great with answer generation):

```bash
./scripts/search.sh '{
  "query": "impact of AI on software development 2026",
  "deep_search": false,
  "include_answer": true
}'
```

### Domain-Specific Search

Target specific authoritative sources (fast mode):

```bash
./scripts/search.sh '{
  "query": "async await patterns",
  "focus": "coding",
  "deep_search": false,
  "include_domains": ["github.com", "stackoverflow.com", "dev.to"],
  "max_results": 8
}'
```

### Real-Time News Monitoring

Track current events and breaking news as they happen (fast mode):

```bash
./scripts/search.sh '{
  "query": "latest developments in quantum computing",
  "focus": "news",
  "deep_search": false,
  "time_range": "week",
  "max_results": 15,
  "include_answer": true
}'
```

### Academic Research - Fast Mode (Recommended)

Find and synthesize scholarly content using fast mode:

```bash
./scripts/search.sh '{
  "query": "machine learning interpretability methods",
  "focus": "academic",
  "deep_search": false,
  "max_results": 20,
  "include_answer": true
}'
```

**When to use deep mode:** Only use `"deep_search": true` if you need full paper content extracted for archiving:

```bash
./scripts/search.sh '{
  "query": "machine learning interpretability methods",
  "focus": "academic",
  "deep_search": true,
  "max_results": 5,
  "output_format": "markdown"
}'
```
**Note:** Deep mode is 5-15x slower. Use only when specifically needed.

### Real-Time Shopping Research

Compare products and current prices (fast mode):

```bash
./scripts/search.sh '{
  "query": "best mechanical keyboards for programming",
  "focus": "shopping",
  "deep_search": false,
  "max_results": 10,
  "include_answer": true
}'
```

## Parallel Search Strategies

### When to Use Parallel Searches

Run multiple real-time searches in parallel when:
- **Comparing perspectives**: Search the same topic across different focus modes
- **Multi-faceted research**: Investigate different aspects of a topic simultaneously
- **Competitive analysis**: Search multiple domains or competitors at once
- **Real-time monitoring**: Track multiple topics or keywords concurrently
- **Cross-validation**: Verify information across different source types in real-time

### Implementation Methods

**Method 1: Background Processes (Recommended)**

Run multiple searches concurrently using the wrapper script:

```bash
# Start multiple searches in parallel
./scripts/search.sh '{"query": "React", "focus": "coding"}' > react_coding.json &
./scripts/search.sh '{"query": "React", "focus": "news"}' > react_news.json &
./scripts/search.sh '{"query": "React", "focus": "academic"}' > react_academic.json &

# Wait for all to complete
wait

# Combine results
jq -s '.' react_*.json > combined_results.json
```

**Method 2: Loop with xargs (Controlled Parallelism)**

Process multiple queries with rate limiting:

```bash
# Create queries file
cat > queries.txt <<EOF
{"query": "AI frameworks", "focus": "coding"}
{"query": "AI regulation", "focus": "news"}
{"query": "AI research", "focus": "academic"}
EOF

# Run with max 3 parallel processes
cat queries.txt | xargs -n1 -P3 -I{} ./scripts/search.sh '{}'
```

**Method 3: Focus Mode Comparison**

Search the same query across different focus modes:

```bash
QUERY="artificial intelligence trends"

for focus in "general" "coding" "news" "academic"; do
  (
    ./scripts/search.sh "{\"query\": \"$QUERY\", \"focus\": \"$focus\"}" \
      > "${focus}_results.json"
  ) &
done

wait
echo "All searches complete!"
```

### Best Practices for Parallel Execution

1. **Rate Limiting**: Limit parallel requests to 3-5 to avoid overwhelming the API
   - Use `xargs -P3` to set maximum concurrent requests
   - Check your API tier limits before increasing parallelism

2. **Error Handling**: Capture and handle failures gracefully
   ```bash
   ./scripts/search.sh '{"query": "test"}' || echo "Search failed" >> errors.log
   ```

3. **Result Aggregation**: Combine results after all searches complete
   ```bash
   # Wait for all searches
   wait

   # Merge JSON results
   jq -s 'map(.results) | flatten' result*.json > combined.json
   ```

4. **Progress Tracking**: Monitor completion status
   ```bash
   echo "Running 5 parallel searches..."

   for i in {1..5}; do
     ./scripts/search.sh "{\"query\": \"query$i\"}" > "result$i.json" &
   done

   wait
   echo "All searches complete!"
   ```

### Example: Multi-Perspective Research

```bash
#!/bin/bash
# Research a topic across multiple focus modes simultaneously

QUERY="artificial intelligence code generation"
OUTPUT_DIR="./search_results"
mkdir -p "$OUTPUT_DIR"

# Run searches in parallel across different focus modes
for focus in "general" "coding" "news" "academic"; do
  (
    ./scripts/search.sh "{
      \"query\": \"$QUERY\",
      \"focus\": \"$focus\",
      \"max_results\": 10
    }" > "$OUTPUT_DIR/${focus}_results.json"
  ) &
done

# Wait for all searches to complete
wait

# Aggregate and analyze results
jq -s '{
  general: .[0].results,
  coding: .[1].results,
  news: .[2].results,
  academic: .[3].results
}' "$OUTPUT_DIR"/*.json > "$OUTPUT_DIR/combined_analysis.json"

echo "✓ Multi-perspective search complete"
```

### Performance Considerations

- **Optimal Parallelism**: 3-5 concurrent requests balances speed and API limits
- **Memory Usage**: Each parallel request consumes memory; monitor for large result sets
- **Network Bandwidth**: Parallel requests can saturate bandwidth on slow connections
- **API Costs**: More parallel requests = faster API quota consumption

### When NOT to Use Parallel Searches

- Single, focused query with one clear answer
- Sequential research where each search informs the next
- API quota is limited or expensive
- Results need to be processed before next search
- Simple URL collection that doesn't require multiple perspectives

## API Integration

**Note:** For most use cases, use the `./scripts/search.sh` wrapper script shown in [Usage Patterns](#usage-patterns). The raw API examples below are for advanced users who need direct API access or custom integration.

### Required Configuration

**Before making any API request, always validate the API key is configured:**

```bash
# Validate API key is set
if [ -z "$NIMBLE_API_KEY" ]; then
  echo "❌ Nimble API key not configured."
  echo "Get your key at https://www.nimbleway.com/"
  echo ""
  echo "Set NIMBLE_API_KEY environment variable using your platform's method."
  exit 1
fi
```

The skill requires the `NIMBLE_API_KEY` environment variable. See [Prerequisites](#prerequisites) for platform-specific setup instructions.

Get your API key at: https://www.nimbleway.com/

### API Endpoint

```
POST https://nimble-retriever.webit.live/search
```

### Request Format

```json
{
  "query": "search query string",  // REQUIRED
  "focus": "general",  // OPTIONAL: default "general" | coding|news|academic|shopping|social|geo|location
  "max_results": 10,  // OPTIONAL: default 10 (range: 1-100)
  "include_answer": false,  // OPTIONAL: default false
  "deep_search": false,  // OPTIONAL: default false (RECOMMENDED: keep false for speed)
  "output_format": "markdown",  // OPTIONAL: default "markdown" | plain_text|simplified_html
  "include_domains": ["domain1.com"],  // OPTIONAL: default [] (no filter)
  "exclude_domains": ["domain3.com"],  // OPTIONAL: default [] (no filter)
  "time_range": "week",  // OPTIONAL: hour|day|week|month|year
  "start_date": "2026-01-01",  // OPTIONAL: Use time_range OR start_date/end_date (not both)
  "end_date": "2026-12-31"  // OPTIONAL
}
```

**Key Defaults:**
- `focus`: `"general"` - Change to specific mode for targeted results
- `deep_search`: `false` - Keep false unless you need full page content
- `max_results`: `10` - Balanced speed and coverage

### Response Format

```json
{
  "results": [
    {
      "url": "https://example.com/page",
      "title": "Page Title",
      "description": "Page description",
      "content": "Full page content (if deep_search=true)",
      "published_date": "2026-01-15"
    }
  ],
  "include_answer": "AI-generated summary (if include_answer=true)",
  "urls": ["url1", "url2", "url3"],
  "total_results": 10
}
```

## Best Practices

### Focus Mode Selection

**Use `coding` for:**
- Programming questions
- Technical documentation
- Code examples and tutorials
- API references
- Framework guides

**Use `news` for:**
- Real-time current events
- Breaking stories as they happen
- Recent announcements
- Trending topics
- Time-sensitive information

**Use `academic` for:**
- Research papers
- Scholarly articles
- Scientific studies
- Academic journals
- Citations and references

**Use `shopping` for:**
- Product searches
- Price comparisons
- E-commerce research
- Product reviews
- Buying guides

**Use `social` for:**
- Real-time social media monitoring
- Live community discussions
- Current user-generated content
- Trending hashtags and topics
- Real-time public sentiment

**Use `geo` for:**
- Geographic information
- Regional data
- Maps and locations
- Area-specific queries

**Use `location` for:**
- Local business searches
- Place-specific information
- Nearby services
- Regional recommendations

### Result Limits

- **Quick searches**: 5-10 results for fast overview
- **Comprehensive research**: 15-20 results for depth
- **Answer generation**: 10-15 results for balanced synthesis
- **URL collection**: 20 results for comprehensive resource list

### When to Use LLM Answers

✅ **Use LLM answers when:**
- You need a synthesized overview of a topic
- Comparing multiple sources or approaches
- Summarizing recent developments
- Answering specific questions
- Creating research summaries

❌ **Skip LLM answers when:**
- You just need a list of URLs
- Building a reference collection
- Speed is critical
- You want to analyze sources manually
- Original source text is needed

### Content Extraction

**Default (Recommended): `deep_search=false`**

The default setting works for 95% of use cases:
- ✅ Fastest response times
- ✅ Returns titles, descriptions, URLs
- ✅ Works perfectly with `include_answer=true`
- ✅ Sufficient for research, comparisons, and URL discovery

**Only use `deep_search=true` when you specifically need:**
- Full page content extraction
- Archiving complete articles
- Processing full text for analysis
- Building comprehensive datasets

**Performance impact:**
- `deep_search=false`: ~1-3 seconds
- `deep_search=true`: ~5-15 seconds (significantly slower)

## Error Handling

### Common Issues

**Authentication Failed**
- Verify NIMBLE_API_KEY is set correctly
- Check API key is active at nimbleway.com
- Ensure key has search API access

**Rate Limiting**
- Reduce max_results
- Add delays between requests
- Check your plan limits
- Consider upgrading API tier

**No Results**
- Try different focus mode
- Broaden search query
- Remove domain filters
- Adjust date filters

**Timeout Errors**
- Reduce max_results
- Disable deep content extraction
- Simplify query
- Try again after brief delay

## Performance Tips

1. **Use Defaults**: Keep `deep_search=false` (default) for 5-10x faster responses
2. **Start Simple**: Begin with just `{"query": "..."}` - defaults work great
3. **Choose Right Focus**: Proper focus mode dramatically improves relevance (default: "general")
4. **Optimize Result Count**: Default of 10 results balances speed and coverage
5. **Domain Filtering**: Pre-filter sources for faster, more relevant results
6. **Avoid Deep Search**: Only enable `deep_search=true` when you truly need full content
7. **Batch Queries**: Group related searches to minimize API calls
8. **Cache Results**: Store results locally when appropriate

## Integration Examples

See the `examples/` directory for detailed integration patterns:
- `basic-search.md` - Simple search implementation
- `deep-research.md` - Multi-step research workflow
- `competitive-analysis.md` - Domain-specific research pattern

See `references/` directory for detailed documentation:
- `focus-modes.md` - Complete focus mode guide
- `search-strategies.md` - Advanced search patterns
- `api-reference.md` - Full API documentation

## Scripts

### search.sh - Main Search Wrapper

The recommended way to use the Nimble Search API:

```bash
./scripts/search.sh '{"query": "your search", "focus": "coding"}'
```

**Features:**
- Automatic authentication with `$NIMBLE_API_KEY`
- Platform detection (claude-code, github-copilot, vscode, cli)
- Request tracking headers for analytics
- JSON validation and error handling
- Formatted output with `jq`

**Usage:**
```bash
# Basic search
./scripts/search.sh '{"query": "React hooks"}'

# With all options
./scripts/search.sh '{
  "query": "AI frameworks",
  "focus": "coding",
  "max_results": 15,
  "include_answer": true,
  "include_domains": ["github.com"]
}'
```

### validate-query.sh - API Configuration Test

Test your API configuration and connectivity:

```bash
./scripts/validate-query.sh "test query" general
```

This verifies:
- API key is configured
- Endpoint is accessible
- Response format is correct
- Focus mode is supported