PluginDataWebsearch Model

PluginDataWebsearch model for storing the configuration of a WebsearchPlugin.

Note

Experimental. The WebsearchPlugin was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will be documented.

class smarter.apps.llmtool.models.plugin_data_websearch.PluginDataWebsearch(*args, **kwargs)[source]

Bases: PluginDataBase

Stores the configuration of a WebsearchPlugin, which searches the open web and reads web pages.

A WebsearchPlugin performs two operations, each of which is optional:

search, via a web search API (search_provider), authenticated with an api key stored in a Smarter Secret (search_api_key).
fetch, reading a web page by URL (fetch_enabled).

Both operations are subject to the plugin’s domain policy (allowed_domains and blocked_domains), its request timeout, and its cache_ttl.

See also

PluginDataBase
smarter.apps.llmtool.plugin.websearch.WebsearchPlugin

Parameters:

id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at
description (Unknown) – Description. A brief description of what this plugin returns. Be verbose, but not too verbose.
parameters (Unknown) – Parameters. A JSON dict containing parameter names and data types. Example: {‘required’: [], ‘properties’: {‘max_cost’: {‘type’: ‘float’, ‘description’: ‘the maximum cost that a student is willing to pay for a course.’}, ‘description’: {‘enum’: [‘AI’, ‘mobile’, ‘web’, ‘database’, ‘network’, ‘neural networks’], ‘type’: ‘string’, ‘description’: ‘areas of specialization for courses in the catalogue.’}}}
test_values (Unknown) – Test values. A JSON dict containing test values for each parameter. Example: {‘city’: ‘San Francisco’}
search_provider (Unknown) – Search provider. The web search API. Null if web search is disabled.
search_max_results (Unknown) – Search max results. The maximum number of results per search.
search_safe_search (Unknown) – Search safe search. Adult content filtering of search results.
search_country (Unknown) – Search country. An ISO 3166-1 alpha-2 country code, to localize results.
search_language (Unknown) – Search language. An ISO 639-1 language code, to localize results.
search_freshness (Unknown) – Search freshness. By default, restrict results to those published within the last day, week, month or year.
fetch_enabled (Unknown) – Fetch enabled. Whether the plugin can read web pages by URL.
fetch_max_characters (Unknown) – Fetch max characters. The maximum number of characters of a web page to return.
fetch_respect_robots_txt (Unknown) – Fetch respect robots txt. Whether to obey websites’ robots.txt files.
allowed_domains (Unknown) – Allowed domains. If not empty, only these domains, and their subdomains, may be searched and read.
blocked_domains (Unknown) – Blocked domains. These domains, and their subdomains, are never searched nor read.
timeout (Unknown) – Timeout. Seconds to wait for each web request.
cache_ttl (Unknown) – Cache ttl. Seconds to cache search results and web pages. 0 disables caching.

Relationship fields:

Parameters:

plugin (Unknown) – Plugin (related name: plugin_data_base_plugin)
plugindatabase_ptr (Unknown) – Primary key: Plugindatabase ptr (related name: plugindatawebsearch)
search_api_key (Unknown) – Search api key. The Secret that contains the web search API’s api key. (related name: plugin_data_websearch_api_key)

exception DoesNotExist: Bases: DoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

exception NotUpdated: Bases: NotUpdated

allowed_domains

JSONField

Allowed domains. If not empty, only these domains, and their subdomains, may be searched and read.

Type:: Type

api_key()[source]

Return the web search API’s api key.

The Secret is read from the database, rather than from this instance, which may be a cached copy that predates the Secret’s deletion.

Return type:: str | None
Returns:: The api key, or None if web search is disabled or the Secret is unavailable.

blocked_domains

JSONField

Blocked domains. These domains, and their subdomains, are never searched nor read.

Type:: Type

cache_ttl

PositiveIntegerField

Cache ttl. Seconds to cache search results and web pages. 0 disables caching.

Type:: Type

data(params=None)[source]

Return the configuration of the plugin, without the api key.

Parameters:: params (dict[str, Any] | None) – Optional parameters for future extensibility (currently unused).
Return type:: dict[str, Any]
Returns:: The configuration.

property domain_policy: DomainPolicy: The plugin’s domain policy.

fetch_enabled

BooleanField

Fetch enabled. Whether the plugin can read web pages by URL.

Type:: Type

fetch_max_characters

PositiveIntegerField

Fetch max characters. The maximum number of characters of a web page to return.

Type:: Type

fetch_respect_robots_txt

BooleanField

Fetch respect robots txt. Whether to obey websites’ robots.txt files.

Type:: Type

classmethod get_cached_data_by_plugin(plugin, invalidate=False)[source]

Return a single instance of PluginDataWebsearch by plugin, with caching.

Parameters:

plugin (PluginMeta) – The plugin whose data should be retrieved.
invalidate (bool) – If True, invalidate the cache before retrieving.

Return type:

PluginDataWebsearch | None

Returns:

The PluginDataWebsearch instance.

Raises:

PluginDataWebsearch.DoesNotExist – If the plugin has no websearch data.

classmethod get_cached_object(*args, invalidate=False, pk=None, plugin=None, **kwargs)[source]

Retrieve a model instance by primary key or by plugin, with caching.

Parameters:

invalidate (bool | None) – If True, invalidate the cache for this query before retrieving the object.
pk (int | None) – The primary key of the model instance to retrieve.
plugin (PluginMeta | None) – The PluginMeta instance associated with the data to retrieve.

Return type:

PluginDataBase | None

Returns:

The model instance.

Raises:

PluginDataWebsearch.DoesNotExist – If the plugin has no websearch data.

get_search_freshness_display(*, field=<django.db.models.CharField: search_freshness>): Shows the label of the search_freshness. See get_FOO_display() for more information.

get_search_provider_display(*, field=<django.db.models.CharField: search_provider>): Shows the label of the search_provider. See get_FOO_display() for more information.

get_search_safe_search_display(*, field=<django.db.models.CharField: search_safe_search>): Shows the label of the search_safe_search. See get_FOO_display() for more information.

manifest_data()[source]

Return the spec.websearchData section of the plugin manifest.

The api key is rendered as the name of its Secret, never its value.

Return type:: dict[str, Any]
Returns:: The manifest section, in camelCase.

property operations: list[str]: The operations that the plugin performs.

plugindatabase_ptr

OneToOneField to PluginDataBase

Primary key: Plugindatabase ptr (related name: plugindatawebsearch)

Type:: Type

plugindatabase_ptr_id: Internal field, use plugindatabase_ptr instead.

property return_data_keys: list[str]: The operations that the plugin performs.

sanitized_return_data(params=None)[source]

Return the configuration of the plugin, without the api key.

The results of web searches and web page fetches are returned by smarter.apps.llmtool.plugin.websearch.WebsearchPlugin.tool_call_fetch_plugin_response().

Return type:: dict[str, Any]

save(*args, **kwargs)[source]: Normalize the domain lists, validate, and save.

search_api_key

ForeignKey to Secret

Search api key. The Secret that contains the web search API’s api key. (related name: plugin_data_websearch_api_key)

Type:: Type

search_api_key_id: Internal field, use search_api_key instead.

search_country

CharField

Search country. An ISO 3166-1 alpha-2 country code, to localize results.

Type:: Type

property search_enabled: bool: Whether the plugin can search the web.

search_freshness

CharField

Search freshness. By default, restrict results to those published within the last day, week, month or year.

Choices:

day
week
month
year

Type:: Type

search_language

CharField

Search language. An ISO 639-1 language code, to localize results.

Type:: Type

search_max_results

PositiveSmallIntegerField

Search max results. The maximum number of results per search.

Type:: Type

search_provider

CharField

Search provider. The web search API. Null if web search is disabled.

Choices:

brave
tavily

Type:: Type

search_safe_search

CharField

Search safe search. Adult content filtering of search results.

Choices:

off
moderate
strict

Type:: Type

timeout

PositiveSmallIntegerField

Timeout. Seconds to wait for each web request.

Type:: Type

validate()[source]

Validate the configuration.

Raises:: SmarterValueError – If neither operation is enabled, a value is out of range, web search is enabled without an api key, or a domain is invalid.
Return type:: bool

smarter.apps.llmtool.models.plugin_data_websearch.choices(enum)[source]

Return Django model field choices for a SmarterEnumAbstract.

Return type:: list[tuple[str, str]]