tools¶

tools ¶

Tool registry — schemas, dispatch, and handlers.

search_news ¶

search_news(query: str, api_key: str | None = None) -> str

Call Tavily API, save markdown, return compact summary.

Searches the web using Tavily's advanced search with configurable depth and result count. Saves the full results as a markdown file in searches/ for future reference and RAG indexing.

Parameters:

Name	Type	Description	Default
`query`	`str`	The search query string (Greek or English).	required
`api_key`	`str \| None`	Optional override for the Tavily API key. If None, uses the system key from config.	`None`

Returns:

Type	Description
`str`	A compact summary string with result titles, URLs, and
`str`	content snippets. Returns an error message if the API key
`str`	is not configured.

load_search ¶

load_search(search_id: str) -> str

Load a previously saved search result by its ID.

Reads the markdown file from the searches/ directory. Supports partial ID matching — searches for any file starting with the given ID prefix.

Parameters:

Name	Type	Description	Default
`search_id`	`str`	The search ID (filename stem without .md extension).	required

Returns:

Type	Description
`str`	The full markdown content of the saved search. Returns an
`str`	error message listing available searches if no match is found.

scrape_url ¶

scrape_url(url: str, api_key: str | None = None) -> str

Fetch a web page via ScrapingAnt API, return markdown content.

Uses ScrapingAnt's headless browser to render JavaScript-heavy pages, bypass paywalls, and extract text content. HTML entities are decoded and the result is truncated to the configured max message length.

Parameters:

Name	Type	Description	Default
`url`	`str`	The full URL to scrape (including https://).	required
`api_key`	`str \| None`	Optional override for the ScrapingAnt API key.	`None`

Returns:

Type	Description
`str`	The page's text content truncated to a reasonable length.
`str`	Returns an error message if the API key is not configured
`str`	or the page returns empty content.

execute_tool ¶

execute_tool(
    name: str,
    args: dict,
    keys: dict[str, str | None] | None = None,
) -> str

Dispatch a tool call to the appropriate handler with per-user keys.

Parameters:

Name	Type	Description	Default
`name`	`str`	Tool function name (e.g., "search_news", "write_file").	required
`args`	`dict`	Dictionary of keyword arguments for the tool function.	required
`keys`	`dict[str, str \| None] \| None`	Optional dict of per-user API keys with 'deepseek', 'tavily', 'scrapingant'.	`None`

Returns:

Type	Description
`str`	String result from the tool handler.