π‘ Why Annolux?
Current web search APIs for AI agents suffer from three fatal flaws:
- Garbage in, garbage out: Commercial search engines index millions of SEO farms, scraped spam, and auto-generated noise that pollute LLM context windows.
- Missing time-provenance: LLMs hallucinate current state because search APIs omit the exact snapshot timestamp (
fetched_at).
- Predatory billing: Paying full price for failed requests, empty outputs, or rate-limited retries.
Annolux solves this with an agent-first curated approach:
- π‘οΈ Curated Bilingual Technical Index: High-signal English & Chinese corpus (Rust, Go, Python, AI/ML, Official Docs, RFCs, GitHub, arXiv).
- π Explicit
fetched_at Timestamp: Every ranked hit reveals the exact second it was ingestedβenabling grounded citations and temporal reasoning.
- π― Predictable Ledger Billing: Exactly 1 credit per successful 2xx response. Errors, timeouts (504), rate limits (429), and bad requests cost 0 credits.
- 𧩠Native Model Context Protocol (MCP): Zero setup across Claude Code, Cursor, Windsurf, Cline, Zed, and Claude Desktop.
- π 1,000 Free Credits Every Month: Sign in with GitHub or Google at annolux.com and start querying in 30 seconds.
π₯ Comparison: Annolux vs. Generic Search APIs
| Feature / Metric | Annolux | Exa (Metaphor) | Tavily | Serper / Google |
|---|
| Index Quality | Curated Tech & Knowledge (EN/ZH) | Web-wide neural | Web-wide aggregator | Entire Web (noisy SEO) |
| Chinese (ZH) Tech Corpus | First-class native bilingual FTS | Moderate | Weak / Translated | Mixed with content farms |
| Explicit Snapshot Timestamp | β
fetched_at on every result | β Inconsistent | β Omitted | β Snippet approximate only |
| Billing Guarantee | β
1 credit only on 2xx success | Request-based | Request-based | Request-based |
| Failed / Timeout Queries | π 0 Credits charged | β Billed | β Billed | β Billed |
| MCP Tool Surface | Single lean search_web (Minimal token waste) | Multiple bulky tools | Multi-step tools | Needs custom bridge |
| Domain Restriction | β
Exact hostname filtering (domains) | β
Supported | β
Supported | Limited site: query |
| Free Starter Tier | 1,000 credits / month | Limited trial | 1,000 / mo | 2,500 one-time |
π¦ Quick Installation
Node.js 18+ is the only prerequisite. Start in the zero-config sandboxβno account or API key is required:
For the full monthly allowance, create a free key at annolux.com and pass it through the process environment:
ANNOLUX_API_KEY=ann_live_YOUR_API_KEY npx -y annolux-mcp
π MCP Integration
Annolux implements the official Model Context Protocol (MCP) specification with a single, high-efficiency tool: search_web.
β‘ 1-Click Installation (Cursor & Smithery)
- Cursor: Click
to install natively via deep link.
- Smithery CLI:
npx -y @smithery/cli install annolux-mcp --client claude
npx -y @smithery/cli install annolux-mcp --client cursor
- Glama Online Playground: Test queries instantly without local setup on Glama.ai.
1. Claude Code
claude mcp add annolux -- npx -y annolux-mcp
This starts in sandbox mode. To use an account key, add it with -e ANNOLUX_API_KEY=ann_live_YOUR_API_KEY before --.
2. Cursor / Windsurf
Add to your project .cursor/mcp.json or global configuration:
{
"mcpServers": {
"annolux": {
"command": "npx",
"args": ["-y", "annolux-mcp"],
"env": {
"ANNOLUX_API_KEY": "ann_live_YOUR_API_KEY"
}
}
}
}
3. Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"annolux": {
"command": "npx",
"args": ["-y", "annolux-mcp"],
"env": {
"ANNOLUX_API_URL": "https://api.annolux.com",
"ANNOLUX_API_KEY": "ann_live_YOUR_API_KEY"
}
}
}
}
π HTTP API Quickstart
Standard Search Endpoint
POST https://api.annolux.com/api/v1/search
Authorization: Bearer ann_live_YOUR_API_KEY
Content-Type: application/json
{
"query": "tokio async runtime memory model",
"domains": ["tokio.rs", "docs.rs", "github.com"],
"deduplicate": true,
"limit": 5,
"timeout": 10,
"ranking": "default"
}
Python
import os
import requests
response = requests.post(
"https://api.annolux.com/api/v1/search",
headers={"Authorization": f"Bearer {os.environ.get('ANNOLUX_API_KEY')}"},
json={
"query": "DeepSeek R1 architecture reinforcement learning",
"limit": 5,
"deduplicate": True
},
timeout=15
)
data = response.json()
for result in data.get("results", []):
print(f"[{result['fetched_at']}] {result['title']} -> {result['url']}")
TypeScript / Node.js
const res = await fetch("https://api.annolux.com/api/v1/search", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.ANNOLUX_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
query: "vLLM PagedAttention implementation details",
limit: 5,
deduplicate: true
})
});
const data = await res.json();
console.log(`Credits Remaining: ${res.headers.get("X-Annolux-Credits-Remaining")}`);
console.log(data.results);
cURL
curl -s -X POST https://api.annolux.com/api/v1/search \
-H "Authorization: Bearer ann_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Go sync.Pool benchmark best practices",
"limit": 3
}' | jq .
ποΈ Architecture & Mechanics
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AI Agent / RAG Application β
β (Claude Code / Cursor / LangChain / Custom LLM) β
ββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β
Stdio MCP / HTTPS REST Request
β
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Annolux Gateway API Engine β
β βββββββββββββββββββββββββββ βββββββββββββββββββββββββ β
β β 1. Account & Rate Limit β βββΊ β Reserve 1 Credit β β
β β (5 RPS, Burst 10) β β in /data/accounts.db β β
β βββββββββββββββββββββββββββ βββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β 2. Bilingual FTS Ranker (/data/index.db) β β
β β β’ Curated English & Chinese Corpus β β
β β β’ SimHash Content-Deduplication Engine β β
β β β’ Domain Filter & Exact Substring Match β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β β
β βΌ β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β 3. Atomic Response & Ledger Settlement β β
β β β’ 2xx Success βββΊ Commit 1 Credit & Attach Timing β β
β β β’ 4xx/5xx Err βββΊ Release Reservation (0 Cost) β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β
JSON with exact `fetched_at` & verified URL
β
βΌ
[ Grounded LLM Response ]
π Search Quality & Frozen Benchmarks
Annolux evaluates search retrieval performance against an immutable, frozen blind set of 40 complex bilingual queries. The ranking weights are never tuned on the test set.
| Metric | First Gate Baseline | Prelaunch Verification Gate |
|---|
| Hit@1 | 72.5% | 72.5% |
| Hit@3 | 82.5% | 82.5% |
| Hit@10 | 85.0% | 85.0% |
| MRR@10 | 0.78125 | 0.78125 |
| P95 Latency | 532 ms | 356 ms |
| 5xx Error Rate | 0.00% | 0.00% |
All benchmarks are evaluated client-side under full concurrency load.
π³ Transparent Pricing
| Plan | Price | Credits | Rate Limits | Billing Rules |
|---|
| Free | $0 | 1,000 / month | 5 RPS / Burst 10 | Free forever, no credit card required |
| Pro | $29 / mo | 20,000 / mo | 5 RPS / Burst 10 | 1 success = 1 credit, no rollover |
| Scale | $99 / mo | 100,000 / mo | 5 RPS / Burst 10 | 1 success = 1 credit, no rollover |
- No overage charges.
- Errors, rate-limits, and timeouts are 100% free (0 credit charged).
- Up to 3 active API keys per account.
π Examples & Recipes
Check the examples/ directory for production-ready starters:
π License
Annolux is open-source software licensed under the Apache License, Version 2.0.
