| name | novada-search |
| version | 1.0.8 |
| author | Novada Labs |
| description | AI Agent search platform with 9 engines, Google 13 sub-types, vertical scene search, and intelligent auto/multi/extract modes. Designed for LLM and AI agent consumption. |
| requiredEnv | {"NOVADA_API_KEY":{"description":"Novada Scraper API key (required for search/extract calls)"}} |
| permissions | {"filesystem":["./novada_search.py","./SKILL.md","./samples/*","./tests/*","./skill.json","./_meta.json"],"network":["https://scraperapi.novada.com"]} |
Novada Search v2.0
Multi-engine AI search — 9 engines, 13 Google types, 9 vertical scenes, smart agent modes.
Powered by Novada Scraper API.
Get started in 30 seconds:
- Get your free API key → novada.com
- Set the key via environment or CLI:
export NOVADA_API_KEY="your_key" (or pass --api-key $NOVADA_API_KEY)
- Search:
python3 {baseDir}/novada_search.py --query "coffee Berlin" --scene local
Agent-first + Human-friendly (Intelligent Distance)
This skill is optimized for agents first, then rendered for humans:
Recommended default contract for agent handoff:
python3 {baseDir}/novada_search.py --query "..." --scene news --format agent-json
If a human drags this skill to an agent, the agent should be able to clearly answer:
- what this tool can do,
- which mode to call (
auto | multi | extract), and
- which output format to consume (
agent-json for logic).
SDK, MCP & Integrations (v1.0.8)
Python SDK
from novada_search import NovadaSearch
client = NovadaSearch(api_key="your_key")
result = client.search("coffee Berlin", scene="local")
result = client.search("buy shoes", mode="auto")
result = client.search("AI news", mode="multi", engines=["google", "bing"])
content = client.extract("https://example.com/article")
All SDK methods raise NovadaSearchError subclasses (not SystemExit), so agents can catch and recover.
MCP Server
python3 {baseDir}/novada_mcp_server.py
Tools: novada_search, novada_extract. Config example: mcp.json.
LangChain
from integrations.langchain_tool import NovadaSearchTool
tool = NovadaSearchTool(api_key="your_key")
Install via pip
pip install novada-search
agent-json enhanced fields
response_time_mssearch_metadata- per-result
domain
- per-result
freshness
What’s New (P0) — Best-Answer First for Agents
- Unified Best Answer:
agent-json now includes unified_results (top merged results across engines).
- Dedup that Agents Love: aggressive URL normalization + multi-engine merging; exposes
duplicates_removed.
- Explainable Scoring: each unified result has
score + agreement_count + domain + a short rationale.
- Regression Guardrail: added
tests/ fixtures so ranking changes don’t silently degrade.
Troubleshooting (Read This)
- Novada may return HTTP 200 even on failure: the real error is in JSON
data.code / data.msg. This CLI hard-checks it and will exit on non-success codes.
- Cloud/Vercel IPs may be blocked (402): validate from your production egress IP before shipping; request server-to-server allowlisting if needed.
- Local/Shopping default to
fetch_mode=dynamic: slower, but higher hit rate for Maps/e-commerce pages.
- Debugging: add
--verbose to see engine/type selection and execution path.
API Keys & Permissions
- NOVADA_API_KEY is required. Either export it (recommended for deployments) or pass
--api-key per run.
- The CLI no longer scans home directories for secrets; it only checks CLI flag,
NOVADA_API_KEY, or a local .env in the working folder.
- Declared permissions: filesystem (
./*.py, ./*.md, ./samples/*) and network access to https://scraperapi.novada.com.
Real-World Example
Query: --query "dessert Düsseldorf" --scene local
Output:
🍰 Düsseldorf TOP 5 Dessert Shops
Click any shop name to open in Google Maps. This is the default enhanced output — actionable links, no extra flags needed.
Architecture
Layer 3 │ AI Agent │ auto · multi · extract
Layer 2 │ Scenes │ shopping · local · jobs · academic · video · news · travel · finance · images
Layer 1 │ Engines │ google · bing · yahoo · duckduckgo · yandex · youtube · ebay · walmart · yelp
│ │ + Google: shopping · local · news · scholar · jobs · flights · finance · patents · videos · images · play · lens
Layer 1 — Engines
9 Engines
| Engine | Strength | Example |
|---|
google | General + 13 sub-types | --engine google |
bing | Web, news | --engine bing |
yahoo | Finance | --engine yahoo |
duckduckgo | Privacy | --engine duckduckgo |
yandex | Russian web | --engine yandex |
youtube | Video | --engine youtube |
ebay | E-commerce | --engine ebay |
walmart | US retail | --engine walmart |
yelp | Local reviews | --engine yelp |
13 Google Sub-Types
Use --engine google --google-type <type>:
| Type | What it searches | Type | What it searches |
|---|
search | Web (default) | shopping | Products & prices |
local | Google Maps | news | Latest headlines |
scholar | Academic papers | jobs | Job listings |
flights | Airlines | finance | Stocks & markets |
videos | Video content | images | Pictures |
patents | IP / patents | play | Android apps |
lens | Visual search | | |
python3 {baseDir}/novada_search.py --query "MacBook Pro M4" --engine google --google-type shopping
python3 {baseDir}/novada_search.py --query "transformer attention" --engine google --google-type scholar
python3 {baseDir}/novada_search.py --query "python developer remote" --engine google --google-type jobs
python3 {baseDir}/novada_search.py --query "SFO to NRT" --engine google --google-type flights
python3 {baseDir}/novada_search.py --query "NVIDIA" --engine google --google-type finance
Layer 2 — Scenes
Scenes auto-combine the best engines for each use case. Use --scene <name>:
| Scene | Engines combined | Use case | Status |
|---|
📰 news | Google News + Bing | Multi-source news aggregation | ✅ Available |
🎓 academic | Google Scholar | Research papers & citations | ✅ Available |
💼 jobs | Google Jobs | Structured job listings | ✅ Available |
🎬 video | YouTube + Google Videos | Video tutorials & reviews | ✅ Available |
🖼️ images | Google Images | Image search | ✅ Available |
🛒 shopping | Google Shopping + eBay + Walmart | Cross-platform price comparison | 🔜 Coming in v1.1 |
📍 local | Google Local + Yelp | Local business with ratings & maps | 🔜 Coming in v1.1 |
✈️ travel | Google Flights | Flight search & pricing | 🔜 Coming in v1.1 |
💰 finance | Google Finance + Yahoo | Stock data & market info | 🔜 Coming in v1.1 |
python3 {baseDir}/novada_search.py --query "MacBook Pro" --scene shopping
python3 {baseDir}/novada_search.py --query "ramen Tokyo" --scene local
python3 {baseDir}/novada_search.py --query "react hooks tutorial" --scene video
python3 {baseDir}/novada_search.py --query "AI startup funding" --scene news
Scene Output Example — Shopping
Query: --query "AirPods Pro" --scene shopping --format agent-json
{
"query": "AirPods Pro",
"scene": "shopping",
"engines_used": ["google:shopping", "ebay", "walmart"],
"result_counts": { "shopping": 15, "organic": 6 },
"shopping_results": [
{ "title": "Apple AirPods Pro 2nd Gen", "price": "$189.99", "seller": "Walmart", "rating": 4.8 },
{ "title": "Apple AirPods Pro 2 - New", "price": "$179.00", "seller": "eBay", "rating": 4.9 },
{ "title": "AirPods Pro (2nd generation)", "price": "$249.00", "seller": "Apple", "rating": 4.7 }
]
}
Shopping Scene Enhanced Output (Coming in v1.1)
⚠️ Shopping price comparison requires engine-specific data parsing that is being finalized.
The price_comparison, lowest_price, and price_range fields will be available in v1.1
when Walmart and eBay result parsing is complete.
Local Scene Enhanced Output (Coming in v1.1)
⚠️ Local business enrichment (phone, hours, open_now) depends on Google Maps and Yelp
data parsing that is being finalized for v1.1.
Layer 3 — Agent Modes
Use --mode <auto|multi|extract>:
Auto — Smart intent detection
Analyzes your query and auto-selects the best scene:
python3 {baseDir}/novada_search.py --query "buy Nike Air Max" --mode auto
python3 {baseDir}/novada_search.py --query "best pizza near me" --mode auto
python3 {baseDir}/novada_search.py --query "latest AI news" --mode auto
Intent keywords (EN/DE/ZH): buy/kaufen, near me/in der nähe, job/stelle, paper/forschung, video/tutorial, news/nachrichten, flight/flug, stock/aktie, image/bild
Multi — Parallel engines + dedup
Search multiple engines simultaneously, deduplicate by URL:
python3 {baseDir}/novada_search.py --query "web scraping tools" --mode multi --engines google,bing,duckduckgo
python3 {baseDir}/novada_search.py --query "coffee maker" --mode multi --engines ebay,walmart,google:shopping
Extract — URL content for LLM
Pull clean text from any URL:
python3 {baseDir}/novada_search.py --url "https://example.com/article" --mode extract
Research — Search + Extract + Merge (Coming in v1.1)
⚠️ Research mode depends on the extract API which requires dynamic fetch mode.
This feature will be fully available in v1.1.
python3 {baseDir}/novada_search.py --query "AI agent trends 2026" --mode research
SDK:
result = client.research("AI agent trends 2026", max_sources=5)
Optional: AI Analysis (Bring Your Own LLM)
This tool focuses on search + structured results. If you want additional reasoning, use your own LLM API:
- Run with structured output:
python3 {baseDir}/novada_search.py --query "..." --scene news --format agent-json > results.json
- Feed
results.json into your own LLM prompt (OpenAI/Claude/etc.) for summarization, ranking, or extraction.
This keeps Novada Search read-only and avoids bundling external AI keys into the skill.
Output Formats
Default is enhanced (clickable links). Override with --format <name>:
| Format | Output type | Best for |
|---|
enhanced (default) | Markdown + clickable Maps/website links | Daily use |
ranked | Readable markdown with ratings | Quick overview |
agent-json | Structured JSON for AI agents | LLM integration |
table | Side-by-side comparison table | Comparing options |
action-links | Shell open commands | Automation |
raw | Full API response | Debugging |
See samples/agent-json-example.json for a ready-to-copy agent-json payload with source_engine + confidence fields.
Full Command Reference
python3 {baseDir}/novada_search.py
--query "search terms" # required (unless extract mode)
--engine google|bing|yahoo|duckduckgo|yandex|youtube|ebay|walmart|yelp
--google-type search|shopping|local|news|scholar|jobs|flights|finance|videos|images|patents|play|lens
--scene shopping|local|jobs|academic|video|news|travel|finance|images
--mode auto|multi|extract
--engines google,bing,ebay # for multi mode (colon syntax: google:shopping)
--url "https://..." # for extract mode
--format enhanced|ranked|agent-json|table|action-links|raw
--max-results 1-20 # default: 10
--fetch-mode static|dynamic # static = fast, dynamic = JS pages
Priority: --mode auto overrides everything. --scene overrides --engine. Direct --engine is the fallback.
vs Tavily
| Feature | Novada Search | Tavily |
|---|
| Search engines | 9 | 1 |
| Google sub-types | 13 | 0 |
| Vertical scenes | 9 | 0 |
| Shopping (eBay+Walmart+Google) | v1.1 | No |
| Local (Maps+Yelp) | v1.1 | No |
| Video (YouTube) | Yes | No |
| Jobs / Academic / Travel | Yes | No |
| Multi-engine parallel | Yes | No |
| Auto intent detection | Yes | No |
| Content extraction | Yes | Yes |
| Agent JSON output | Yes | Yes |
Get your API key → · GitHub · Powered by Novada Scraper API v2.0
中文版｜Novada Search v2.0
更新亮点（P0）— 面向 Agent 的“最佳答案优先”
- 统一最佳答案：
agent-json 新增 unified_results（多引擎合并后的 Top 结果）。
- 强力去重：URL 归一 + 多引擎聚合；并输出
duplicates_removed。
- 可解释评分：每条 unified 结果带
score + agreement_count + domain + rationale（为什么排前）。
- 回归测试：新增
tests/ 固件，保证排序逻辑稳定不退化。
多引擎 AI 搜索平台——一次调用叠加 9 套主引擎、13 种 Google 类型、9 个垂直场景，并内置 auto / multi / extract 三层 Agent 模式。
快速上手
- 在 novada.com 申请 NOVADA_API_KEY。
- 用
export NOVADA_API_KEY="..." 或运行时 --api-key $NOVADA_API_KEY 注入（推荐显式传参，脚本不会再扫描个人目录）。
- 运行示例：
python3 {baseDir}/novada_search.py --query "coffee Berlin" --scene local。
常见问题｜踩坑
- Novada HTTP 常年 200，真实错误在 JSON
data.code / data.msg，脚本已内建校验。
- 云服务器 / Vercel IP 可能被封（402），上线前先在目标 IP 做 Step 1.6 验证。
- local / shopping 场景默认
fetch_mode=dynamic，命中率更高但更慢。
--verbose 可查看 engine/type 选择与节点评估。
真实案例
--query "dessert Düsseldorf" --scene local 会输出带点击链接的 Top 5 甜品店表格，可直接跳转 Google Maps。
架构分层
- Layer 1 引擎层：google / bing / yahoo / duckduckgo / yandex / youtube / ebay / walmart / yelp，Google 额外 13 个子类型（shopping/local/news/...）。
- Layer 2 场景层：shopping、local、jobs、academic、video、news、travel、finance、images，根据场景组合多引擎并定义合并策略。
- Layer 3 Agent 模式：
auto（意图识别 → 场景）、multi（自选引擎并行去重）、extract（URL 正文抽取）。
指令参考
python3 {baseDir}/novada_search.py \
--query "search" --scene news --format agent-json
python3 {baseDir}/novada_search.py \
--mode multi --engines google:shopping,ebay,walmart --format table
python3 {baseDir}/novada_search.py \
--mode extract --url "https://example.com/article"
输出格式
enhanced：默认 Markdown，附地图/官网快速操作。ranked：排名 + 摘要。table：商品/本地商家对照表。agent-json / brave：结构化 JSON 供 LLM 食用（示例见 samples/agent-json-example.json）。action-links：生成 open "URL" 命令，方便自动化。raw：原始 API 回包。
vs Tavily 对比（精简版）
| 功能 | Novada | Tavily |
|---|
| 搜索引擎数量 | 9 | 1 |
| Google 子类型 | 13 | 0 |
| 垂直场景 | 9 | 0 |
| Shopping（eBay+Walmart+Google） | ✅ | ❌ |
| Local（Maps+Yelp） | ✅ | ❌ |
| 多引擎并行 | ✅ | ❌ |
| Auto intent | ✅ | ❌ |
| Extract API | ✅ | ✅ |
实用建议
- 需要稳定输出 → 显式指定
--scene 或 --mode multi，避免 auto 误判。
- 需要被别的 Agent 调用 → 优先
--format agent-json，字段与 Tavily 兼容。
- 线上引用时建议直接传
--api-key 或在进程环境里 export（CLI 现仅读取 --api-key / NOVADA_API_KEY / 当前目录 .env）。
- 发布时请确保 registry metadata 与本包的
requiredEnv.NOVADA_API_KEY、permissions 保持一致（避免扫描器判定 metadata mismatch）。
