calute.tools.duckduckgo_engine

calute.tools.duckduckgo_engine#

DuckDuckGo search engine integration for Calute agents.

This module provides a comprehensive DuckDuckGo search tool for Calute agents, enabling web searches with advanced filtering and customization options. It includes: - Text, image, video, news, and map searches - Domain and keyword filtering - Safe search and time range filtering - Multi-source search across different content types - Search suggestions and query translation - Lazy loading of dependencies to avoid import errors

The search tool is implemented as an AgentBaseFn subclass for seamless integration with Calute agents. It depends on the ddgs package, which is included in Calute’s core runtime dependencies.

Example

>>> from calute.tools.duckduckgo_engine import DuckDuckGoSearch
>>> results = DuckDuckGoSearch.static_call("Python programming", n_results=5)
>>> news = DuckDuckGoSearch.static_call("AI news", search_type="news")
class calute.tools.duckduckgo_engine.DuckDuckGoSearch(name, bases, namespace, /, **kwargs)[source]#

Bases: AgentBaseFn

DuckDuckGo search tool for web, image, video, news, and map searches.

Provides comprehensive search capabilities through the DuckDuckGo API with support for filtering, safe search, time limits, and domain restrictions. Implements lazy loading of the ddgs package.

SearchType#

Literal type for search categories (text, images, videos, news, maps).

TimeFilter#

Literal type for time range filtering (day, week, month, year, None).

SafeSearch#

Literal type for safe search levels (strict, moderate, off).

static_call()[source]#

Perform a search with full filtering options.

search_multiple_sources()[source]#

Search across multiple content types.

get_suggestions()[source]#

Get search query suggestions.

translate_query()[source]#

Translate a query to another language.

Example

>>> results = DuckDuckGoSearch.static_call(
...     query="machine learning",
...     search_type="text",
...     n_results=10,
...     timelimit="month"
... )
SafeSearch#

alias of Literal[‘strict’, ‘moderate’, ‘off’]

SearchType#

alias of Literal[‘text’, ‘images’, ‘videos’, ‘news’, ‘maps’]

TimeFilter#

alias of Literal[‘day’, ‘week’, ‘month’, ‘year’, None]

static get_suggestions(query: str, region: str = 'us-en', **context_variables) → list[str][source]#

Get search query suggestions (autocomplete) for a partial query.

Retrieves search suggestions from DuckDuckGo’s suggestion API, useful for expanding or refining queries before performing a full search.

Parameters

  • query – Partial or full search query to get suggestions for.

  • region – Region code for localized suggestions (e.g., “us-en”, “uk-en”, “de-de”). Defaults to “us-en”.

  • **context_variables – Runtime context from the agent (unused).

Returns

A list of suggested search query strings. Returns an empty list if no suggestions are available or if the request fails.

Example

>>> suggestions = DuckDuckGoSearch.get_suggestions("python prog")
>>> print(suggestions)
['python programming', 'python programming language', ...]
static search_multiple_sources(query: str, sources: list[Literal['text', 'images', 'videos', 'news', 'maps']] | None = None, n_results_per_source: int = 3, **kwargs) → dict[str, list[dict]][source]#

Search across multiple source types and return categorized results.

Performs separate searches for each specified source type and aggregates the results into a single dictionary keyed by source. Errors for individual sources are captured without failing the entire operation.

Parameters

  • query – The search query string to use across all sources.

  • sources – List of search types to query. Each must be one of “text”, “images”, “videos”, “news”, “maps”. Defaults to [“text”, “news”] if None.

  • n_results_per_source – Maximum number of results to return per source type. Defaults to 3.

  • **kwargs – Additional keyword arguments forwarded to static_call (e.g., region, safesearch, timelimit).

Returns

A dictionary mapping source type names to their respective result lists. If a source fails, its value is a dict with an “error” key describing the failure.

Example

>>> results = DuckDuckGoSearch.search_multiple_sources(
...     "Python programming",
...     sources=["text", "news"],
...     n_results_per_source=3
... )
>>> print(len(results["text"]))
3
static static_call(query: str, search_type: Literal['text', 'images', 'videos', 'news', 'maps'] = 'text', n_results: int | None = 5, title_length_limit: int | None = 200, snippet_length_limit: int | None = 1000, region: str = 'us-en', safesearch: Literal['strict', 'moderate', 'off'] = 'moderate', timelimit: Literal['day', 'week', 'month', 'year', None] = None, allowed_domains: list[str] | None = None, excluded_domains: list[str] | None = None, must_include_keywords: list[str] | None = None, exclude_keywords: list[str] | None = None, file_type: str | None = None, return_metadata: bool = False, **context_variables) → list[dict] | dict[source]#

Perform an enhanced DuckDuckGo search with multiple options and filters.

Use this tool when the model needs fresh public-web information rather than local workspace context. It supports regular text search plus images, videos, news, and maps. The tool normalizes provider output into compact result dictionaries so a model can scan titles, snippets, URLs, and metadata without scraping a page first.

Parameters

  • query (str) – Search keywords. The query can be plain language or can include search-style qualifiers. If file_type or domain filters are provided, they are merged into the outgoing query automatically.

  • search_type (SearchType) – Search vertical to use: "text", "images", "videos", "news", or "maps".

  • n_results (int, optional) – Number of results to return. Must be between 1 and 30.

  • title_length_limit (int | None) – Maximum number of characters kept from the result title. Set to None to keep titles in full.

  • snippet_length_limit (int | None) – Maximum number of characters kept from result body text or summary fields. Set to None to keep snippets in full.

  • region (str) – Region code such as "us-en", "uk-en", or "fr-fr".

  • safesearch (SafeSearch) – Safe-search level: "strict", "moderate", or "off".

  • timelimit (TimeFilter) – Optional recency filter such as "day", "week", "month", or "year". This is especially useful for news and fast-moving topics.

  • allowed_domains (list[str] | None) – Restrict results to these domains. This is implemented both by expanding the query and by filtering the returned URLs.

  • excluded_domains (list[str] | None) – Remove results from these domains.

  • must_include_keywords (list[str] | None) – Keep only results whose title or snippet contains at least one of the provided keywords.

  • exclude_keywords (list[str] | None) – Remove results whose title or snippet contains any of the provided keywords.

  • file_type (str | None) – Add a file-type constraint such as "pdf" or "doc" to the search query.

  • return_metadata (bool) – When True, return a dictionary with results and additional metadata such as the final query string, timestamp, and filters applied. When False, return only the results list.

Returns

Either a list of result dictionaries or a metadata wrapper containing results and search context. Result items typically include keys such as title, snippet, url, and type-specific fields like image source or publication date.

Return type

Union[list[dict], dict]

static translate_query(query: str, to_language: str = 'en', **context_variables) → str[source]#

Translate a search query to another language using DuckDuckGo.

Uses DuckDuckGo’s translation service to convert a query from its detected language to the specified target language. Falls back to returning the original query if translation fails.

Parameters

  • query – The original search query to translate.

  • to_language – Target language code (e.g., “en” for English, “es” for Spanish, “fr” for French, “de” for German). Defaults to “en”.

  • **context_variables – Runtime context from the agent (unused).

Returns

The translated query string. If translation fails, returns the original query unchanged.

Example

>>> translated = DuckDuckGoSearch.translate_query("hola mundo", to_language="en")
>>> print(translated)
'hello world'
Contents