exa-research

# Exa Research Neural web search via BlockRun. Understands meaning, not keywords. Four distinct actions for different research modes. ## How to Call from MCP As of v0.14.1 the `blockrun_exa` tool is path-based. Pass the endpoint name as `path` and the request as `body`: ```ts blockrun_exa({ path: "search", body: { query: "AI agent frameworks 2026", numResults: 10 } }) blockrun_exa({ path: "answer", body: { query: "What is speculative decoding?" } }) blockrun_exa({ path: "contents", body: { urls: ["https://example.com/a", "https://example.com/b"] } }) blockrun_exa({ path: "find-similar", body: { url: "https://arxiv.org/abs/2401.12345", numResults: 5 } }) ``` ## Quick Decision Table Costs below are what you are actually CHARGED — the $0.001 transaction fee is already included (it applies once per call, not per result). | User wants... | Path | Body | Cost | |--------------|------|------|------| | Relevant URLs on a topic | `search` | `{ query, numResults?, category? }` | $0.0110/call | | Cited answer to a question | `answer` | `{ query }` | $0.0110/call | | Full text of URLs | `contents` | `{ urls: [...] }` | $0.002/URL + $0.001 → 1 URL $0.0030, 3 URLs $0.0070 | | Pages like a given URL | `find-similar` | `{ url, numResults? }` | $0.0110/call | | Recent news | `search` + `category: "news"` | – | $0.0110/call | | Academic papers | `search` + `category: "research paper"` | – | $0.0110/call | | Company info | `search` + `category: "company"` | – | $0.0110/call | `contents` bills per URL, so batching URLs into ONE call is markedly cheaper than one call each: 3 URLs together cost $0.0070, but three separate calls cost $0.0090 — you pay the flat fee three times instead of once. Valid `category` values for `search`: `"news"`, `"research paper"`, `"company"`, `"tweet"`, `"github"`, `"pdf"`. ## Python SDK Instructions ### 1. Initialize (Python SDK) ```python from blockrun_llm import setup_agent_wallet chain = open(os.path.expanduser("~/.blockrun/.chain")).read().strip() if os.path.exists(os.path.expanduser("~/.blockrun/.chain")) else "base" if chain == "solana": from blockrun_llm import setup_agent_solana_wallet client = setup_agent_solana_wallet() else: from blockrun_llm import setup_agent_wallet client = setup_agent_wallet() ``` ### 2. Search — Find Relevant URLs ```python # Basic search result = client._request_with_payment_raw("/v1/exa/search", { "query": "AI agent frameworks 2025", "numResults": 10, }) for r in result.get("results", []): print(f"{r['title']} — {r['url']}") # Filter by category result = client._request_with_payment_raw("/v1/exa/search", { "query": "transformer architecture improvements", "numResults": 10, "category": "research paper", }) # Restrict to specific domains result = client._request_with_payment_raw("/v1/exa/search", { "query": "prediction market regulation", "numResults": 10, "includeDomains": ["reuters.com", "bloomberg.com", "wsj.com"], }) ``` **Categories:** `"news"`, `"research paper"`, `"company"`, `"tweet"`, `"github"`, `"pdf"` ### 3. Answer — Cited, Grounded Response Use when the user asks a factual question and needs reliable sources (not Claude's training data). ```python result = client._request_with_payment_raw("/v1/exa/answer", { "query": "What is the current market cap of Polymarket?", }) print(result.get("answer", "")) for c in result.get("citations", []): print(f" [{c.get('title')}] {c.get('url')}") ``` ### 4. Contents — Fetch URL Text Use when you have URLs and need their full text for LLM context (scraping without a browser). ```python urls = [ "https://example.com/article-1", "https://example.com/article-2", ] result = client._request_with_payment_raw("/v1/exa/contents", { "urls": urls, }) for item in result.get("results", []): print(f"=== {item['url']} ===") print(item.get("text", "")[:500]) ``` Up to 100 URLs per call. Returns Markdown-ready text. ### 5. Similar — Find Related Pages Use to discover competitors, related research, or sites with similar content. ```python result = client._request_with_payment_raw("/v1/exa/find-similar", { "url": "https://polymarket.com", "numResults": 10, }) for r in result.get("results", []): print(f"{r['title']} — {r['url']}") ``` ## Common Research Workflows **Competitor discovery:** ```python # 1. Find similar companies similar = client._request_with_payment_raw("/v1/exa/find-similar", {"url": "https://target-company.com", "numResults": 15}) urls = [r["url"] for r in similar.get("results", [])] # 2. Fetch their about pages contents = client._request_with_payment_raw("/v1/exa/contents", {"urls": urls[:10]}) ``` **Research synthesis:** ```python # 1. Find papers papers = client._request_with_payment_raw("/v1/exa/search", { "query": "your topic", "category": "research paper", "numResults": 20, }) # 2. Get answer with citations answer = client._request_with_payment_raw("/v1/exa/answer", { "query": "What are the key findings on your topic?", }) ``` ## When to Use Exa vs `client.search()` | Use `blockrun_exa` / `_request_with_payment_raw` | Use `client.search()` | |---------------------------------------------------|----------------------| | Finding specific URLs and fetching content | Getting a summarized answer with citations | | Semantic similarity search | Web + news combined | | Academic paper discovery | Cheaper per call for simple lookups | | Domain-filtered research | Already returns a SearchResult object | ## Requirements - BlockRun SDK: `pip install blockrun-llm` - USDC wallet funded (see `client.get_balance()`) - `_request_with_payment_raw` is the Python SDK entry point for Exa (no dedicated method yet)