Metadata-Version: 2.5
Name: llama-index-tools-webz
Version: 0.1.0
Summary: Python tools for Webz.io News Search - global news in natural language with semantic ranking and rich filters
Project-URL: Homepage, https://news-search-mcp.webz.io
Project-URL: Documentation, https://docs.webz.io/docs/webz/news-search-api-mcp
Project-URL: Repository, https://github.com/Webhose/webz-news-search
Project-URL: Issues, https://github.com/Webhose/webz-news-search/issues
Author-email: "Webz.io" <support@webz.io>
License-Expression: MIT
License-File: LICENSE
Keywords: llama-index,llamaindex,mcp,news,search,webz
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: llama-index-core<0.15,>=0.13.0
Requires-Dist: llama-index-tools-mcp>=0.4.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: examples
Requires-Dist: llama-index-llms-openai-like>=0.4.0; extra == 'examples'
Description-Content-Type: text/markdown

# llama-index-tools-webz

**Search global news with [Webz.io](https://webz.io) from Python - in natural language, with the most relevant articles first.**

[Webz.io News Search](https://docs.webz.io/docs/webz/news-search-api-mcp) covers news and current events from sources worldwide. Ask a question in plain language, narrow results with filters (language, country, date, sentiment, domain, ticker, and more), and get back focused article excerpts with titles, URLs, and metadata.

Use this package on its own, or plug it into LlamaIndex agents.

## What you get

- **Natural-language search** - no keyword hacking. Example: `"EU AI Act enforcement updates"` or `"How is Tesla stock reacting to earnings?"`
- **Worldwide coverage** - semantic search over Webz.io's global news index.
- **Rich filters** - language, country, days, sentiment, domain, ticker, person, organization, topic, and more. See the [MCP tool reference](https://docs.webz.io/docs/webz/news-search-api-mcp#tool-reference).
- **Live schema** - filters are loaded from the hosted MCP server (`tools/list`). New Webz filters appear automatically, without republishing this package.

## Install

```bash
pip install llama-index-tools-webz
export WEBZ_API_TOKEN="your-webz-api-token"
```

Get a token from your [Webz.io dashboard](https://webz.io) (same token as the News Search API).

Full setup and client options: [MCP Server docs](https://docs.webz.io/docs/webz/news-search-api-mcp).

## Direct search (no agent required)

```python
from llama_index.tools.webz import WebzNewsSearch, flatten_tool_result

tool = WebzNewsSearch()  # reads WEBZ_API_TOKEN from the environment
# tool = WebzNewsSearch(api_token="your-webz-api-token")

result = tool.call(
    query="recent developments on EU AI regulation",
    k=10,
    days=30,
)
print(flatten_tool_result(result))
```

To see every filter your connection supports:

```python
print(sorted(WebzNewsSearch().metadata.fn_schema.model_fields))
```

## With a LlamaIndex agent

The agent discovers the live tool schema and picks filters itself. Any tool-calling LLM works (Llama, GPT, Claude, and others). The snippet uses Llama via OpenRouter.

```python
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai_like import OpenAILike
from llama_index.tools.webz import get_webz_tools

tools = get_webz_tools()
# OpenAI-compatible client; any tool-calling LLM works (Llama shown here)
llm = OpenAILike(
    model="meta-llama/llama-3.3-70b-instruct",
    api_key="your-openrouter-key",
    api_base="https://openrouter.ai/api/v1",
    is_chat_model=True,
    is_function_calling_model=True,
)
agent = FunctionAgent(
    tools=tools,
    llm=llm,
    system_prompt="You are a helpful assistant that searches global news with Webz.",
)
response = await agent.run(
    "Search Webz news for renewable energy investments "
    "from the past 30 days and summarize with sources."
)
print(str(response))
```

Async helpers (when you already run inside an event loop):

```python
from llama_index.tools.webz import aget_webz_tools, awebz_news_search

tools = await aget_webz_tools()
tool = await awebz_news_search()
```

## How it works

This package connects to the hosted Webz News Search MCP server at `https://news-search-mcp.webz.io/mcp` using [`llama-index-tools-mcp`](https://pypi.org/project/llama-index-tools-mcp/). Each call runs a regular News Search API request with your token (same credits and rate limits). It does not hardcode filter fields - the tool schema comes from the live server.

## Configuration

| Name | Default | Purpose |
| --- | --- | --- |
| `WEBZ_API_TOKEN` | required | Webz API token from the dashboard |
| `WEBZ_MCP_URL` | `https://news-search-mcp.webz.io/mcp` | Override for local MCP testing |

You can also pass `api_token=` and `mcp_url=` to the helpers.

## Links

- [Webz.io](https://webz.io)
- [News Search MCP documentation](https://docs.webz.io/docs/webz/news-search-api-mcp)
- [MCP server landing page](https://news-search-mcp.webz.io)
- [News Search API filters](https://docs.webz.io/docs/webz/news-search-api-filters)
- [LlamaIndex MCP tools](https://developers.llamaindex.ai/python/framework/module_guides/mcp/llamaindex_mcp/)
- [GitHub](https://github.com/Webhose/webz-news-search)
