tavily_fastmcp.models

Typed models for Tavily FastMCP.

Purpose:

Define canonical request, response, catalog, and profile models.

Design:

• Request models are strict and reject unknown fields.

• Response models allow extra fields because upstream Tavily payloads may evolve.

• Profile and catalog models are shared between direct Python helpers, packaged resources, and MCP prompts.

Examples

>>> SearchRequest(query="FastMCP docs").max_results
5
>>> ProfileSummary(slug="router", title="Router", summary="x").slug
'router'

Attributes

JsonObject

Classes

SearchRequest	Canonical request model for Tavily search.
ExtractRequest	Canonical request model for Tavily extract.
MapRequest	Canonical request model for Tavily map.
CrawlRequest	Canonical request model for Tavily crawl.
ResearchRequest	Canonical request model for Tavily research.
GetResearchRequest	Canonical request model for retrieving a Tavily research task.
SearchHit	Normalized Tavily search hit.
SearchResponse	Normalized Tavily search response.
ExtractHit	Normalized Tavily extract result item.
ExtractResponse	Normalized Tavily extract response.
MapResponse	Normalized Tavily map response.
CrawlHit	Normalized Tavily crawl result item.
CrawlResponse	Normalized Tavily crawl response.
ResearchSource	Source used by a Tavily research task.
ResearchResponse	Normalized Tavily research response.
ProfileSummary	Summary metadata for a packaged prompt profile.
PromptProfile	Structured packaged profile with markdown prompt content.
ServerCatalog	Catalog of server metadata exposed through resources and tools.
HealthResponse	Simple health payload.

Module Contents

type tavily_fastmcp.models.JsonObject = dict[str, Any]

class tavily_fastmcp.models.SearchRequest(/, **data: Any)

Bases: pydantic.BaseModel

Canonical request model for Tavily search.

Parameters:

• query – Natural-language search query.

• max_results – Maximum number of results.

• topic – Tavily topic mode.

• include_answer – Whether to include Tavily’s answer field.

• include_raw_content – Whether to return cleaned page content.

• include_images – Whether to include image URLs.

• include_image_descriptions – Whether to include image descriptions.

• search_depth – Tavily search depth.

• time_range – Relative time filter.

• start_date – Inclusive start bound in YYYY-MM-DD format.

• end_date – Inclusive end bound in YYYY-MM-DD format.

• include_domains – Domains to include.

• exclude_domains – Domains to exclude.

• include_usage – Whether to return usage metadata.

Returns:

A validated request object.

Raises:

ValueError – If a field is invalid.

Examples

>>> SearchRequest(query="FastMCP resources", max_results=3).max_results
3

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

query: str

max_results: int = None

topic: Literal['general', 'news', 'finance'] = 'general'

include_answer: bool = False

include_raw_content: bool = False

include_images: bool = False

include_image_descriptions: bool = False

search_depth: Literal['basic', 'advanced'] = 'basic'

time_range: Literal['day', 'week', 'month', 'year'] | None = None

start_date: str | None = None

end_date: str | None = None

include_domains: list[str] | None = None

exclude_domains: list[str] | None = None

include_usage: bool = False

class tavily_fastmcp.models.ExtractRequest(/, **data: Any)

Bases: pydantic.BaseModel

Canonical request model for Tavily extract.

Parameters:

• urls – URLs to extract.

• extract_depth – Extraction depth.

• include_images – Whether to include images.

Returns:

A validated request object.

Raises:

ValueError – If a field is invalid.

Examples

>>> ExtractRequest(urls=["https://example.com"]).extract_depth
'basic'

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

urls: list[pydantic.AnyUrl] = None

extract_depth: Literal['basic', 'advanced'] = 'basic'

include_images: bool = False

class tavily_fastmcp.models.MapRequest(/, **data: Any)

Bases: pydantic.BaseModel

Canonical request model for Tavily map.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: pydantic.AnyUrl

instructions: str | None = None

class tavily_fastmcp.models.CrawlRequest(/, **data: Any)

Bases: pydantic.BaseModel

Canonical request model for Tavily crawl.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: pydantic.AnyUrl

instructions: str | None = None

class tavily_fastmcp.models.ResearchRequest(/, **data: Any)

Bases: pydantic.BaseModel

Canonical request model for Tavily research.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

input: str

model: Literal['mini', 'pro', 'auto'] = 'auto'

output_schema: JsonObject | None = None

stream: bool = False

citation_format: Literal['numbered', 'mla', 'apa', 'chicago'] = 'numbered'

class tavily_fastmcp.models.GetResearchRequest(/, **data: Any)

Bases: pydantic.BaseModel

Canonical request model for retrieving a Tavily research task.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

request_id: str

class tavily_fastmcp.models.SearchHit(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily search hit.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str

title: str | None = None

content: str | None = None

raw_content: str | None = None

score: float | None = None

published_date: str | None = None

class tavily_fastmcp.models.SearchResponse(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily search response.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

query: str | None = None

answer: str | None = None

results: list[SearchHit] = None

images: list[str] = None

response_time: float | None = None

request_id: str | None = None

follow_up_questions: list[str] = None

usage: JsonObject | None = None

class tavily_fastmcp.models.ExtractHit(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily extract result item.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str

raw_content: str | None = None

images: list[str] = None

class tavily_fastmcp.models.ExtractResponse(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily extract response.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

results: list[ExtractHit] = None

failed_results: list[JsonObject] = None

response_time: float | None = None

class tavily_fastmcp.models.MapResponse(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily map response.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

base_url: str | None = None

results: list[str] = None

request_id: str | None = None

response_time: float | None = None

class tavily_fastmcp.models.CrawlHit(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily crawl result item.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str

raw_content: str | None = None

class tavily_fastmcp.models.CrawlResponse(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily crawl response.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

base_url: str | None = None

results: list[CrawlHit] = None

request_id: str | None = None

response_time: float | None = None

class tavily_fastmcp.models.ResearchSource(/, **data: Any)

Bases: pydantic.BaseModel

Source used by a Tavily research task.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

title: str | None = None

url: str | None = None

favicon: str | None = None

class tavily_fastmcp.models.ResearchResponse(/, **data: Any)

Bases: pydantic.BaseModel

Normalized Tavily research response.

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

request_id: str | None = None

created_at: str | None = None

completed_at: str | None = None

status: str | None = None

input: str | None = None

model: str | None = None

content: str | JsonObject | None = None

sources: list[ResearchSource] = None

response_time: float | None = None

class tavily_fastmcp.models.ProfileSummary(/, **data: Any)

Bases: pydantic.BaseModel

Summary metadata for a packaged prompt profile.

Parameters:

• slug – Stable profile slug.

• title – Human-readable title.

• summary – One-sentence profile summary.

• tags – Tags for filtering and discovery.

• recommended_tools – Ordered preferred tool names.

• prompt_resource_uri – Resource URI for the prompt text.

• profile_resource_uri – Resource URI for structured profile metadata.

Returns:

A reusable profile summary object.

Raises:

ValueError – If a field is invalid.

Examples

>>> ProfileSummary(
...     slug="router",
...     title="Router",
...     summary="Route tasks",
...     prompt_resource_uri="resource://x",
...     profile_resource_uri="resource://y",
... ).slug
'router'

slug: str

title: str

summary: str

tags: list[str] = None

recommended_tools: list[str] = None

prompt_resource_uri: str

profile_resource_uri: str

class tavily_fastmcp.models.PromptProfile(/, **data: Any)

Bases: pydantic.BaseModel

Structured packaged profile with markdown prompt content.

Parameters:

• slug – Stable profile slug.

• title – Human-readable title.

• summary – Short description.

• use_when – List of ideal use cases.

• avoid_when – List of anti-patterns.

• recommended_tools – Preferred tool sequence.

• tags – Discovery tags.

• meta – Arbitrary profile metadata.

• prompt_markdown – Full markdown prompt body.

Returns:

A rich profile object.

Raises:

ValueError – If a field is invalid.

Examples

>>> profile = PromptProfile(
...     slug="router",
...     title="Router",
...     summary="Route tasks",
...     prompt_markdown="# Router",
... )
>>> profile.title
'Router'

slug: str

title: str

summary: str

use_when: list[str] = None

avoid_when: list[str] = None

recommended_tools: list[str] = None

tags: list[str] = None

meta: JsonObject = None

prompt_markdown: str

class tavily_fastmcp.models.ServerCatalog(/, **data: Any)

Bases: pydantic.BaseModel

Catalog of server metadata exposed through resources and tools.

name: str

version: str

package_name: str

prompt_names: list[str] = None

profile_slugs: list[str] = None

tool_names: list[str] = None

resource_uris: list[str] = None

example_resource_uris: list[str] = None

meta: JsonObject = None

class tavily_fastmcp.models.HealthResponse(/, **data: Any)

Bases: pydantic.BaseModel

Simple health payload.

status: Literal['ok']

server_name: str

version: str