Metadata-Version: 2.4
Name: llama-index-tools-blopus
Version: 0.3.0
Summary: llama-index tools blopus integration
Author: Blopus
License: MIT
Project-URL: Homepage, https://blopus.ai
Project-URL: Documentation, https://blopus.ai/docs/
Project-URL: Source, https://github.com/blopus-ai/llama-index-tools-blopus
Keywords: blopus,llama-index,search,web-search,agents,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: blopus>=0.5.0
Requires-Dist: llama-index-core>=0.11
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# LlamaIndex Tools Integration: Blopus

[Blopus](https://blopus.ai) 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.

```bash
pip install llama-index-tools-blopus
```

Create a key at [blopus.ai/app](https://blopus.ai/app):

```bash
export BLOPUS_API_KEY="blp_live_..."
```


### Images

```python
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

```python
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:

```python
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:

```python
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
