LlamaIndex Tools Integration: Blopus

Blopus is a web search and fetch API for LLMs and agents, running on its own crawler and index rather than reselling another search engine.

This tool spec gives an agent two functions: blopus_search for ranked results with snippets, and blopus_fetch for the full cleaned text of the pages worth reading.

pip install llama-index-tools-blopus

Create a key at blopus.ai/app:

export BLOPUS_API_KEY="blp_live_..."

Images

from llama_index.tools.blopus import BlopusToolSpec

spec = BlopusToolSpec(include_images=True)
out = spec.blopus_search("tesla factory")
for r in out["results"]:
    if r.get("image"):     # absent is normal - coverage is partial
        print(r["title"], r["image"])

Image support is in BETA. Every result also carries word_count.

Usage

from llama_index.tools.blopus import BlopusToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

tool_spec = BlopusToolSpec()

agent = FunctionAgent(
    tools=tool_spec.to_tool_list(),
    llm=OpenAI(model="gpt-4.1"),
)

print(await agent.run("What changed in postgres logical replication this month?"))

Calling the functions directly:

tool_spec.blopus_search("postgres logical replication", freshness="pw")
tool_spec.blopus_fetch(["https://example.com/article"])

Configuration

Defaults can be set once on the spec and overridden per call:

BlopusToolSpec(
    count=20,              # results per search; billed in blocks of 10, so this rounds up
    freshness="pm",        # pd, pw, pm, p3m, p1y, all
    news_only=True,        # newsroom sources only; faster, not slower
    include_content=True,  # cleaned page text inline, avoiding a second fetch
)

Per-search filters: include_domains, exclude_domains, language.

Notes

One topic per search. A query joining several subjects ("economy, sports, Iran") matches nothing, because no single document is about all of them. Issue one search per topic. The tool description tells the model this, and the API returns a note when it detects the mistake, which this package passes straight through.

Billing is in blocks of ten. One search returns up to 10 results for 1 credit. If your remaining quota cannot cover a request, the API serves a partial page rather than refusing and sets quota_clamped, so an agent can tell "my quota cut this short" apart from "that is all that exists".

Fetch is batched. Pass up to 50 URLs in one call. URLs that were not found come back in failed_urls rather than raising, so one bad URL does not lose the rest of the batch.

License

MIT