search-intelligence-skill

# search-intelligence-skill

Use `search-intelligence-skill` to give any AI agent the ability to search the entire internet like an expert OSINT analyst, SEO engineer, and security researcher combined. All searches flow through your SearXNG instance — zero API keys, full privacy, 90+ engines.

The skill generates optimized dork queries, selects intelligent multi-step search strategies, translates operators across engines, routes queries to the best SearXNG engines, scores results by multi-signal relevance, and learns from results to refine searches automatically.

## Setup (once)

**Install the package**
```bash
# From source (recommended)
git clone https://github.com/mouaad-ops/search-intelligence-skill.git
cd search-intelligence-skill
pip install -e .

# Or direct pip
pip install search-intelligence-skill # NOT yet working
```

**Start a SearXNG instance (if you don't have one)**
```bash
# Docker (quickest)
docker run -d \
  --name searxng \
  -p 8888:8080 \
  -e SEARXNG_SECRET=your-secret-key \
  searxng/searxng:latest

# Verify it's running
curl http://localhost:8888/healthz
```

**Enable JSON API in SearXNG settings**
```yaml
# In searxng/settings.yml — ensure search formats include json
search:
  formats:
    - html
    - json
```

**Initialize in code**
```python
from search_intelligence_skill import SearchSkill

# Default — localhost:8888
skill = SearchSkill()

# Custom instance
skill = SearchSkill(
    searxng_url="http://localhost:8888",
    timeout=30.0,
    max_retries=2,
    rate_limit=0.5,
    verify_ssl=True,
    auto_refine=True,
    max_refine_rounds=1,
)

# Verify connection
if skill.health_check():
    print("✓ SearXNG is reachable")
else:
    print("✗ Cannot reach SearXNG — check URL and port")
```

## Common Commands

**Natural language search (the main interface)**
```python
from search_intelligence_skill import SearchSkill

skill = SearchSkill(searxng_url="http://localhost:8888")

# Just describe what you want — the skill handles everything:
#...

# 🔍 search-intelligence-skill

Advanced AI-powered search skill using SearXNG as the universal search backend.

**Zero API keys. Full privacy. 90+ engines. Intelligent dork generation.**

Give any AI agent the ability to search the entire internet like an expert
OSINT analyst, SEO engineer, and security researcher combined.

## Features

| Feature | Description |
|---|---|
| **Intent Parsing** | NLP-based classification into 14 intent categories (security, OSINT, SEO, academic, code, etc.) |
| **Dork Generation** | 100+ dork templates with automatic entity extraction and template filling |
| **90+ Engines** | Routes queries to the optimal SearXNG engines per intent |
| **Multi-Step Strategies** | 8 strategy types: broad-to-narrow, OSINT chain, deep dive, temporal, file hunt, etc. |
| **Cross-Engine Translation** | Translates operators between Google, Bing, Yandex, DuckDuckGo, Brave |
| **Result Analysis** | Multi-signal relevance scoring, deduplication, credibility assessment |
| **Auto-Refinement** | Detects poor results and automatically generates improved queries |
| **LLM-Ready Output** | `.to_context()` formats results for AI agent consumption |

## Quick Start

```bash
pip install -e .
```

```python
from search_intelligence_skill import SearchSkill

skill = SearchSkill(searxng_url="http://localhost:8888")

# Natural language → intelligent multi-engine search
report = skill.search("find exposed admin panels on example.com", depth="deep")
print(report.to_context())

# Top results as structured data
for r in report.top(5):
    print(f"[{r.relevance:.1f}] {r.title} — {r.url}")
```

## Search Depths

| Depth | Queries | Strategy | Use Case |
|---|---|---|---|
| `quick` | 1-2 | Single-step | Fast lookups |
| `standard` | 3-6 | Broad-to-narrow | General searching |
| `deep` | 6-12 | Multi-angle / Deep dive | Research, security audits |
| `exhaustive` | 12+ | OSINT chain / Full sweep | Complete investigations |

## Intent Categories

The skill automatically detects:...