Image Search Plugin Model

Smarter API ImageSearchPlugin Manifest Constants.

Note

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

smarter.apps.plugin.manifest.models.image_search_plugin.const.BRAVE_IMAGE_SEARCH_URL = 'https://api.search.brave.com/res/v1/images/search'

The Brave Image Search API endpoint.

https://api-dashboard.search.brave.com/app/documentation/image-search/get-started

smarter.apps.plugin.manifest.models.image_search_plugin.const.CREDENTIALS_HELP = "An ImageSearchPlugin requires a Brave Search API key, stored in a Smarter Secret. 1) Sign up at https://api-dashboard.search.brave.com, subscribe to a plan that includes image search, and create an api key at https://api-dashboard.search.brave.com/app/keys. 2) Set SMARTER_BRAVE_SEARCH_API_KEY in .env, and run 'python manage.py initialize_providers', or apply a Secret manifest named brave_search_api_key. See https://api-dashboard.search.brave.com/app/documentation/image-search/get-started": Instructions for creating the Brave Search API key, logged when it is missing.

smarter.apps.plugin.manifest.models.image_search_plugin.const.DEFAULT_API_KEY_SECRET_NAME = 'brave_search_api_key'

The default name of the Smarter Secret that contains the Brave Search API key.

The WebsearchPlugin’s Brave samples use the same Secret.

smarter.apps.plugin.manifest.models.image_search_plugin.const.MAX_COUNT = 20

The maximum number of images per search.

The Brave Image Search API returns up to 200, but each url is validated with a request of its own.

smarter.apps.plugin.manifest.models.image_search_plugin.const.MAX_DIMENSION = 10000: The maximum value of minWidth and minHeight, in pixels.

smarter.apps.plugin.manifest.models.image_search_plugin.const.MAX_QUERY_LENGTH = 400: The maximum length of a search query, in characters, which is also the Brave Search API’s limit.

Enumeration classes for the ImageSearchPlugin manifest models.

Note

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

smarter.apps.plugin.manifest.models.image_search_plugin.enum.FILE_TYPE_CONTENT_TYPES: dict[str, str] = {'image/avif': 'avif', 'image/bmp': 'bmp', 'image/gif': 'gif', 'image/jpeg': 'jpg', 'image/jpg': 'jpg', 'image/png': 'png', 'image/svg+xml': 'svg', 'image/vnd.microsoft.icon': 'ico', 'image/webp': 'webp', 'image/x-icon': 'ico'}

Response Content-Types, and their file types.

{
    'image/avif': 'avif',
    'image/bmp': 'bmp',
    'image/gif': 'gif',
    'image/jpeg': 'jpg',
    'image/jpg': 'jpg',
    'image/png': 'png',
    'image/svg+xml': 'svg',
    'image/vnd.microsoft.icon': 'ico',
    'image/webp': 'webp',
    'image/x-icon': 'ico',
}

smarter.apps.plugin.manifest.models.image_search_plugin.enum.FILE_TYPE_EXTENSIONS: dict[str, str] = {'avif': 'avif', 'bmp': 'bmp', 'gif': 'gif', 'ico': 'ico', 'jpeg': 'jpg', 'jpg': 'jpg', 'png': 'png', 'svg': 'svg', 'webp': 'webp'}

Image url file extensions, and their file types.

{
    'avif': 'avif',
    'bmp': 'bmp',
    'gif': 'gif',
    'ico': 'ico',
    'jpeg': 'jpg',
    'jpg': 'jpg',
    'png': 'png',
    'svg': 'svg',
    'webp': 'webp',
}

class smarter.apps.plugin.manifest.models.image_search_plugin.enum.ImageSearchFileType(*values)[source]

Bases: SmarterEnumAbstract

Image file types, for the fileType filter.

The Brave Image Search API cannot filter by file type, so Smarter filters its results, by the extension of each image url, or else by the Content-Type of its response.

AVIF = 'avif'

BMP = 'bmp'

GIF = 'gif'

ICO = 'ico'

JPG = 'jpg'

PNG = 'png'

SVG = 'svg'

WEBP = 'webp'

class smarter.apps.plugin.manifest.models.image_search_plugin.enum.ImageSearchSafeSearch(*values)[source]

Bases: SmarterEnumAbstract

Brave Image Search filtering of adult content, for the safesearch search parameter.

OFF = 'off': No filtering, except for illegal content.

STRICT = 'strict'

Drops all adult content.

Brave’s default.

Smarter API Manifest - ImageSearchPlugin.spec.

An ImageSearchPlugin gives the LLM an image search, powered by the Brave Image Search API. Its tool returns a JSON list of strings: the https urls of the images that it found.

The LLM supplies the search query, e.g. formula 1 race cars, in each tool call. spec.imageSearchData.queryTerms, if set, are appended to it, e.g. black and white photograph, so that Brave searches for formula 1 race cars black and white photograph. spec.imageSearchData.searchParams map 1:1 to the Brave Image Search API’s other query parameters. spec.imageSearchData.filters are applied by Smarter to Brave’s results, for what the API itself cannot filter: file type, minimum size, and the websites that images come from.

imageSearchData:
  apiKey: brave_search_api_key   # the name of a Smarter Secret
  queryTerms: null               # terms appended to every query that the LLM sends
  llmSearchParams: false         # whether the LLM may set every search parameter in each call
  searchParams:
    count: 10                    # 1 to 20
    country: us                  # a two letter country code, or all
    searchLang: en               # a language code, e.g. en, pt-br
    safesearch: strict           # strict or off
    spellcheck: true
  filters:
    fileType: jpg|png            # any of jpg, png, gif, svg, webp, avif, bmp, ico
    minWidth: 800                # pixels. Images of unknown width are skipped
    minHeight: null
    allowedDomains: []           # if not empty, only images from web pages on these domains
    blockedDomains: []           # never images on, or from web pages on, these domains
  validateUrls: true             # only return urls that respond with HTTP 200
  timeout: 10
  cacheTtl: 604800

Note

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

class smarter.apps.plugin.manifest.models.image_search_plugin.spec.ImageSearchData(*, apiKey: str = 'brave_search_api_key', queryTerms: Annotated[str | None, ~annotated_types.MaxLen(max_length=400)] = None, llmSearchParams: bool = False, searchParams: ImageSearchParams = <factory>, filters: ImageSearchFilters = <factory>, validateUrls: bool = True, timeout: Annotated[int, ~annotated_types.Ge(ge=1), ~annotated_types.Le(le=60)] = 10, cacheTtl: Annotated[int, ~annotated_types.Ge(ge=0), ~annotated_types.Le(le=<PluginCacheTtl.IMAGE_SEARCH: 604800>)] = PluginCacheTtl.IMAGE_SEARCH)[source]

Bases: SmarterBasePydanticModel

Smarter API - ImageSearchPlugin.spec.imageSearchData.

apiKey: str

cacheTtl: int

class_identifier: ClassVar[str] = 'ImageSearchPlugin.spec'

filters: ImageSearchFilters

llmSearchParams: bool

model_config = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

queryTerms: str | None

searchParams: ImageSearchParams

timeout: int

validateUrls: bool

classmethod validate_api_key(v)[source]

Validate that the api key is the name of a Secret, not empty.

Return type:: str

classmethod validate_query_terms(v)[source]

Normalize the query terms.

Return type:: str | None

class smarter.apps.plugin.manifest.models.image_search_plugin.spec.ImageSearchFilters(*, fileType: str | None = None, minWidth: Annotated[int | None, Ge(ge=1), Le(le=10000)] = None, minHeight: Annotated[int | None, Ge(ge=1), Le(le=10000)] = None, allowedDomains: list[str] | None = None, blockedDomains: list[str] | None = None)[source]

Bases: SmarterBasePydanticModel

Smarter API - ImageSearchPlugin.spec.imageSearchData.filters.

Smarter applies these to the Brave Image Search API’s results.

allowedDomains: list[str] | None

blockedDomains: list[str] | None

class_identifier: ClassVar[str] = 'ImageSearchPlugin.spec.filters'

fileType: str | None

minHeight: int | None

minWidth: int | None

model_config = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

classmethod validate_domains(v)[source]

Validate and normalize domain names.

Return type:: list[str] | None

classmethod validate_file_type(v)[source]

Validate the file types.

Return type:: str | None

class smarter.apps.plugin.manifest.models.image_search_plugin.spec.ImageSearchParams(*, count: Annotated[int, Ge(ge=1), Le(le=20)] = 10, country: str | None = None, searchLang: str | None = None, safesearch: Literal['off', 'strict'] = 'strict', spellcheck: bool = True)[source]

Bases: SmarterBasePydanticModel

Smarter API - ImageSearchPlugin.spec.imageSearchData.searchParams.

These map 1:1 to the query parameters of the Brave Image Search API, except for q, the query itself, which the LLM supplies. See imageSearchData.queryTerms.

class_identifier: ClassVar[str] = 'ImageSearchPlugin.spec.searchParams'

count: int

country: str | None

model_config = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

safesearch: Literal['off', 'strict']

searchLang: str | None

spellcheck: bool

classmethod validate_country(v)[source]

Validate the country code.

Return type:: str | None

classmethod validate_safesearch(v)[source]

Validate the safe search level.

Return type:: str

classmethod validate_search_lang(v)[source]

Validate the language code.

Return type:: str | None

class smarter.apps.plugin.manifest.models.image_search_plugin.spec.SAMImageSearchPluginSpec(*, selector: SAMPluginCommonSpecSelector, prompt: SAMPluginCommonSpecPrompt, imageSearchData: ImageSearchData = <factory>)[source]

Bases: SAMPluginCommonSpec

Smarter API Manifest - ImageSearchPlugin.spec.

class_identifier: ClassVar[str] = 'ImageSearchPlugin.spec'

imageSearchData: ImageSearchData

model_config = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

smarter.apps.plugin.manifest.models.image_search_plugin.spec.normalize_country(value)[source]

Validate and normalize a country search parameter.

Parameters:: value (Any) – A two letter country code, or all for worldwide results.
Return type:: str | None
Returns:: The lower case value, or None if the value is empty.
Raises:: ValueError – If the value is not a two letter country code, nor all.

smarter.apps.plugin.manifest.models.image_search_plugin.spec.normalize_file_types(value)[source]

Validate and normalize a fileType filter.

Parameters:: value (Any) – File types separated by |, e.g. jpg|png. jpeg is read as jpg.
Return type:: str | None
Returns:: The normalized value, e.g. jpg|png, or None if the value is empty.
Raises:: ValueError – If a file type is not permitted.

smarter.apps.plugin.manifest.models.image_search_plugin.spec.normalize_search_lang(value)[source]

Validate and normalize a searchLang search parameter.

Parameters:: value (Any) – A language code, e.g. en or pt-br.
Return type:: str | None
Returns:: The lower case value, or None if the value is empty.
Raises:: ValueError – If the value is not a language code.

Smarter API Manifest - ImageSearchPlugin.

Note

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

class smarter.apps.plugin.manifest.models.image_search_plugin.model.SAMImageSearchPlugin(*, apiVersion: str, kind: str, metadata: SAMPluginCommonMetadata, spec: SAMImageSearchPluginSpec, status: SAMPluginCommonStatus | None = None)[source]

Bases: SAMPluginCommon

Smarter API Manifest - ImageSearchPlugin Model.

class_identifier: ClassVar[str] = 'ImageSearchPlugin'

model_config = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

self (BaseModel) – The BaseModel instance.
context (Any) – The context.

Return type:

None

spec: SAMImageSearchPluginSpec