Skip to content

pydantic_ai.models

Logic related to making requests to an LLM.

The aim here is to make a common interface for different LLMs, so that the rest of the code can be agnostic to the specific LLM being used.

KnownModelName module-attribute 

KnownModelName = TypeAliasType(
    "KnownModelName",
    Literal[
        "anthropic:claude-3-haiku-20240307",
        "anthropic:claude-fable-5",
        "anthropic:claude-haiku-4-5",
        "anthropic:claude-haiku-4-5-20251001",
        "anthropic:claude-mythos-5",
        "anthropic:claude-mythos-preview",
        "anthropic:claude-opus-4-0",
        "anthropic:claude-opus-4-1",
        "anthropic:claude-opus-4-1-20250805",
        "anthropic:claude-opus-4-20250514",
        "anthropic:claude-opus-4-5",
        "anthropic:claude-opus-4-5-20251101",
        "anthropic:claude-opus-4-6",
        "anthropic:claude-opus-4-7",
        "anthropic:claude-opus-4-8",
        "anthropic:claude-sonnet-4-0",
        "anthropic:claude-sonnet-4-20250514",
        "anthropic:claude-sonnet-4-5",
        "anthropic:claude-sonnet-4-5-20250929",
        "anthropic:claude-sonnet-4-6",
        "bedrock:amazon.titan-text-express-v1",
        "bedrock:amazon.titan-text-lite-v1",
        "bedrock:amazon.titan-tg1-large",
        "bedrock:anthropic.claude-3-5-haiku-20241022-v1:0",
        "bedrock:anthropic.claude-3-5-sonnet-20240620-v1:0",
        "bedrock:anthropic.claude-3-5-sonnet-20241022-v2:0",
        "bedrock:anthropic.claude-3-7-sonnet-20250219-v1:0",
        "bedrock:anthropic.claude-3-haiku-20240307-v1:0",
        "bedrock:anthropic.claude-3-opus-20240229-v1:0",
        "bedrock:anthropic.claude-3-sonnet-20240229-v1:0",
        "bedrock:anthropic.claude-haiku-4-5-20251001-v1:0",
        "bedrock:anthropic.claude-instant-v1",
        "bedrock:anthropic.claude-opus-4-20250514-v1:0",
        "bedrock:anthropic.claude-sonnet-4-20250514-v1:0",
        "bedrock:anthropic.claude-sonnet-4-5-20250929-v1:0",
        "bedrock:anthropic.claude-sonnet-4-6",
        "bedrock:anthropic.claude-v2",
        "bedrock:anthropic.claude-v2:1",
        "bedrock:cohere.command-light-text-v14",
        "bedrock:cohere.command-r-plus-v1:0",
        "bedrock:cohere.command-r-v1:0",
        "bedrock:cohere.command-text-v14",
        "bedrock:eu.anthropic.claude-haiku-4-5-20251001-v1:0",
        "bedrock:eu.anthropic.claude-sonnet-4-20250514-v1:0",
        "bedrock:eu.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "bedrock:eu.anthropic.claude-sonnet-4-6",
        "bedrock:global.anthropic.claude-opus-4-5-20251101-v1:0",
        "bedrock:meta.llama3-1-405b-instruct-v1:0",
        "bedrock:meta.llama3-1-70b-instruct-v1:0",
        "bedrock:meta.llama3-1-8b-instruct-v1:0",
        "bedrock:meta.llama3-70b-instruct-v1:0",
        "bedrock:meta.llama3-8b-instruct-v1:0",
        "bedrock:mistral.mistral-7b-instruct-v0:2",
        "bedrock:mistral.mistral-large-2402-v1:0",
        "bedrock:mistral.mistral-large-2407-v1:0",
        "bedrock:mistral.mixtral-8x7b-instruct-v0:1",
        "bedrock:us.amazon.nova-2-lite-v1:0",
        "bedrock:us.amazon.nova-lite-v1:0",
        "bedrock:us.amazon.nova-micro-v1:0",
        "bedrock:us.amazon.nova-pro-v1:0",
        "bedrock:us.anthropic.claude-3-5-haiku-20241022-v1:0",
        "bedrock:us.anthropic.claude-3-5-sonnet-20240620-v1:0",
        "bedrock:us.anthropic.claude-3-5-sonnet-20241022-v2:0",
        "bedrock:us.anthropic.claude-3-7-sonnet-20250219-v1:0",
        "bedrock:us.anthropic.claude-3-haiku-20240307-v1:0",
        "bedrock:us.anthropic.claude-3-opus-20240229-v1:0",
        "bedrock:us.anthropic.claude-3-sonnet-20240229-v1:0",
        "bedrock:us.anthropic.claude-haiku-4-5-20251001-v1:0",
        "bedrock:us.anthropic.claude-opus-4-20250514-v1:0",
        "bedrock:us.anthropic.claude-sonnet-4-20250514-v1:0",
        "bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "bedrock:us.anthropic.claude-sonnet-4-6",
        "bedrock:us.meta.llama3-1-70b-instruct-v1:0",
        "bedrock:us.meta.llama3-1-8b-instruct-v1:0",
        "bedrock:us.meta.llama3-2-11b-instruct-v1:0",
        "bedrock:us.meta.llama3-2-1b-instruct-v1:0",
        "bedrock:us.meta.llama3-2-3b-instruct-v1:0",
        "bedrock:us.meta.llama3-2-90b-instruct-v1:0",
        "bedrock:us.meta.llama3-3-70b-instruct-v1:0",
        "cerebras:gpt-oss-120b",
        "cerebras:llama3.1-8b",
        "cerebras:qwen-3-235b-a22b-instruct-2507",
        "cerebras:zai-glm-4.7",
        "cohere:c4ai-aya-expanse-32b",
        "cohere:c4ai-aya-expanse-8b",
        "cohere:command-nightly",
        "cohere:command-r-08-2024",
        "cohere:command-r-plus-08-2024",
        "cohere:command-r7b-12-2024",
        "deepseek:deepseek-chat",
        "deepseek:deepseek-reasoner",
        "deepseek:deepseek-v4-flash",
        "deepseek:deepseek-v4-pro",
        "gateway/anthropic:claude-3-haiku-20240307",
        "gateway/anthropic:claude-fable-5",
        "gateway/anthropic:claude-haiku-4-5",
        "gateway/anthropic:claude-haiku-4-5-20251001",
        "gateway/anthropic:claude-mythos-5",
        "gateway/anthropic:claude-mythos-preview",
        "gateway/anthropic:claude-opus-4-0",
        "gateway/anthropic:claude-opus-4-1",
        "gateway/anthropic:claude-opus-4-1-20250805",
        "gateway/anthropic:claude-opus-4-20250514",
        "gateway/anthropic:claude-opus-4-5",
        "gateway/anthropic:claude-opus-4-5-20251101",
        "gateway/anthropic:claude-opus-4-6",
        "gateway/anthropic:claude-opus-4-7",
        "gateway/anthropic:claude-opus-4-8",
        "gateway/anthropic:claude-sonnet-4-0",
        "gateway/anthropic:claude-sonnet-4-20250514",
        "gateway/anthropic:claude-sonnet-4-5",
        "gateway/anthropic:claude-sonnet-4-5-20250929",
        "gateway/anthropic:claude-sonnet-4-6",
        "gateway/bedrock:anthropic.claude-3-5-sonnet-20240620-v1:0",
        "gateway/bedrock:anthropic.claude-3-haiku-20240307-v1:0",
        "gateway/bedrock:eu.anthropic.claude-haiku-4-5-20251001-v1:0",
        "gateway/bedrock:eu.anthropic.claude-sonnet-4-20250514-v1:0",
        "gateway/bedrock:eu.anthropic.claude-sonnet-4-5-20250929-v1:0",
        "gateway/bedrock:eu.anthropic.claude-sonnet-4-6",
        "gateway/bedrock:global.anthropic.claude-opus-4-5-20251101-v1:0",
        "gateway/google-cloud:gemini-2.5-flash",
        "gateway/google-cloud:gemini-2.5-flash-image",
        "gateway/google-cloud:gemini-2.5-flash-lite",
        "gateway/google-cloud:gemini-2.5-flash-lite-preview-09-2025",
        "gateway/google-cloud:gemini-2.5-pro",
        "gateway/google-cloud:gemini-3-flash-preview",
        "gateway/google-cloud:gemini-3-pro-image-preview",
        "gateway/google-cloud:gemini-3.1-flash-image-preview",
        "gateway/google-cloud:gemini-3.1-flash-lite-preview",
        "gateway/google-cloud:gemini-3.1-pro-preview",
        "gateway/google-cloud:gemini-3.5-flash",
        "gateway/google:gemini-2.5-flash",
        "gateway/google:gemini-2.5-flash-image",
        "gateway/google:gemini-2.5-flash-lite",
        "gateway/google:gemini-2.5-flash-lite-preview-09-2025",
        "gateway/google:gemini-2.5-pro",
        "gateway/google:gemini-3-flash-preview",
        "gateway/google:gemini-3-pro-image-preview",
        "gateway/google:gemini-3.1-flash-image-preview",
        "gateway/google:gemini-3.1-flash-lite-preview",
        "gateway/google:gemini-3.1-pro-preview",
        "gateway/google:gemini-3.5-flash",
        "gateway/groq:llama-3.1-8b-instant",
        "gateway/groq:llama-3.3-70b-versatile",
        "gateway/groq:meta-llama/llama-4-scout-17b-16e-instruct",
        "gateway/groq:moonshotai/kimi-k2-instruct-0905",
        "gateway/groq:openai/gpt-oss-120b",
        "gateway/groq:openai/gpt-oss-20b",
        "gateway/groq:openai/gpt-oss-safeguard-20b",
        "gateway/openai:gpt-3.5-turbo",
        "gateway/openai:gpt-3.5-turbo-0125",
        "gateway/openai:gpt-3.5-turbo-1106",
        "gateway/openai:gpt-3.5-turbo-16k",
        "gateway/openai:gpt-4",
        "gateway/openai:gpt-4-0613",
        "gateway/openai:gpt-4-turbo",
        "gateway/openai:gpt-4-turbo-2024-04-09",
        "gateway/openai:gpt-4.1",
        "gateway/openai:gpt-4.1-2025-04-14",
        "gateway/openai:gpt-4.1-mini",
        "gateway/openai:gpt-4.1-mini-2025-04-14",
        "gateway/openai:gpt-4.1-nano",
        "gateway/openai:gpt-4.1-nano-2025-04-14",
        "gateway/openai:gpt-4o",
        "gateway/openai:gpt-4o-2024-05-13",
        "gateway/openai:gpt-4o-2024-08-06",
        "gateway/openai:gpt-4o-2024-11-20",
        "gateway/openai:gpt-4o-mini",
        "gateway/openai:gpt-4o-mini-2024-07-18",
        "gateway/openai:gpt-4o-mini-search-preview",
        "gateway/openai:gpt-4o-mini-search-preview-2025-03-11",
        "gateway/openai:gpt-4o-search-preview",
        "gateway/openai:gpt-4o-search-preview-2025-03-11",
        "gateway/openai:gpt-5",
        "gateway/openai:gpt-5-2025-08-07",
        "gateway/openai:gpt-5-chat-latest",
        "gateway/openai:gpt-5-mini",
        "gateway/openai:gpt-5-mini-2025-08-07",
        "gateway/openai:gpt-5-nano",
        "gateway/openai:gpt-5-nano-2025-08-07",
        "gateway/openai:gpt-5.1",
        "gateway/openai:gpt-5.1-2025-11-13",
        "gateway/openai:gpt-5.1-chat-latest",
        "gateway/openai:gpt-5.2",
        "gateway/openai:gpt-5.2-2025-12-11",
        "gateway/openai:gpt-5.2-chat-latest",
        "gateway/openai:gpt-5.4",
        "gateway/openai:gpt-5.4-mini",
        "gateway/openai:gpt-5.4-mini-2026-03-17",
        "gateway/openai:gpt-5.4-nano",
        "gateway/openai:gpt-5.4-nano-2026-03-17",
        "gateway/openai:o1",
        "gateway/openai:o1-2024-12-17",
        "gateway/openai:o3",
        "gateway/openai:o3-2025-04-16",
        "gateway/openai:o3-mini",
        "gateway/openai:o3-mini-2025-01-31",
        "gateway/openai:o4-mini",
        "gateway/openai:o4-mini-2025-04-16",
        "google-cloud:gemini-2.0-flash",
        "google-cloud:gemini-2.0-flash-lite",
        "google-cloud:gemini-2.5-flash",
        "google-cloud:gemini-2.5-flash-image",
        "google-cloud:gemini-2.5-flash-lite",
        "google-cloud:gemini-2.5-flash-lite-preview-09-2025",
        "google-cloud:gemini-2.5-flash-preview-09-2025",
        "google-cloud:gemini-2.5-pro",
        "google-cloud:gemini-3-flash-preview",
        "google-cloud:gemini-3-pro-image-preview",
        "google-cloud:gemini-3-pro-preview",
        "google-cloud:gemini-3.1-flash-image-preview",
        "google-cloud:gemini-3.1-flash-lite-preview",
        "google-cloud:gemini-3.1-pro-preview",
        "google-cloud:gemini-3.5-flash",
        "google-cloud:gemini-flash-latest",
        "google-cloud:gemini-flash-lite-latest",
        "google:gemini-2.0-flash",
        "google:gemini-2.0-flash-lite",
        "google:gemini-2.5-flash",
        "google:gemini-2.5-flash-image",
        "google:gemini-2.5-flash-lite",
        "google:gemini-2.5-flash-lite-preview-09-2025",
        "google:gemini-2.5-flash-preview-09-2025",
        "google:gemini-2.5-pro",
        "google:gemini-3-flash-preview",
        "google:gemini-3-pro-image-preview",
        "google:gemini-3-pro-preview",
        "google:gemini-3.1-flash-image-preview",
        "google:gemini-3.1-flash-lite-preview",
        "google:gemini-3.1-pro-preview",
        "google:gemini-3.5-flash",
        "google:gemini-flash-latest",
        "google:gemini-flash-lite-latest",
        "groq:llama-3.1-8b-instant",
        "groq:llama-3.3-70b-versatile",
        "groq:meta-llama/llama-4-maverick-17b-128e-instruct",
        "groq:meta-llama/llama-4-scout-17b-16e-instruct",
        "groq:meta-llama/llama-guard-4-12b",
        "groq:meta-llama/llama-prompt-guard-2-22m",
        "groq:meta-llama/llama-prompt-guard-2-86m",
        "groq:moonshotai/kimi-k2-instruct-0905",
        "groq:openai/gpt-oss-120b",
        "groq:openai/gpt-oss-20b",
        "groq:openai/gpt-oss-safeguard-20b",
        "groq:playai-tts",
        "groq:playai-tts-arabic",
        "groq:qwen/qwen-3-32b",
        "groq:whisper-large-v3",
        "groq:whisper-large-v3-turbo",
        "heroku:claude-3-5-haiku",
        "heroku:claude-3-5-sonnet-latest",
        "heroku:claude-3-7-sonnet",
        "heroku:claude-3-haiku",
        "heroku:claude-4-5-haiku",
        "heroku:claude-4-5-sonnet",
        "heroku:claude-4-6-sonnet",
        "heroku:claude-4-sonnet",
        "heroku:claude-opus-4-5",
        "heroku:claude-opus-4-6",
        "heroku:deepseek-v3-2",
        "heroku:glm-4-7",
        "heroku:glm-4-7-flash",
        "heroku:gpt-oss-120b",
        "heroku:kimi-k2-5",
        "heroku:kimi-k2-thinking",
        "heroku:minimax-m2",
        "heroku:minimax-m2-1",
        "heroku:nova-2-lite",
        "heroku:nova-lite",
        "heroku:nova-pro",
        "heroku:qwen3-235b",
        "heroku:qwen3-coder-480b",
        "huggingface:Qwen/QwQ-32B",
        "huggingface:Qwen/Qwen2.5-72B-Instruct",
        "huggingface:Qwen/Qwen3-235B-A22B",
        "huggingface:Qwen/Qwen3-32B",
        "huggingface:deepseek-ai/DeepSeek-R1",
        "huggingface:meta-llama/Llama-3.3-70B-Instruct",
        "huggingface:meta-llama/Llama-4-Maverick-17B-128E-Instruct",
        "huggingface:meta-llama/Llama-4-Scout-17B-16E-Instruct",
        "mistral:codestral-latest",
        "mistral:mistral-large-latest",
        "mistral:mistral-moderation-latest",
        "mistral:mistral-small-latest",
        "moonshotai:kimi-k2-0711-preview",
        "moonshotai:kimi-latest",
        "moonshotai:kimi-thinking-preview",
        "moonshotai:moonshot-v1-128k",
        "moonshotai:moonshot-v1-128k-vision-preview",
        "moonshotai:moonshot-v1-32k",
        "moonshotai:moonshot-v1-32k-vision-preview",
        "moonshotai:moonshot-v1-8k",
        "moonshotai:moonshot-v1-8k-vision-preview",
        "openai-chat:computer-use-preview",
        "openai-chat:computer-use-preview-2025-03-11",
        "openai-chat:gpt-3.5-turbo",
        "openai-chat:gpt-3.5-turbo-0125",
        "openai-chat:gpt-3.5-turbo-0301",
        "openai-chat:gpt-3.5-turbo-0613",
        "openai-chat:gpt-3.5-turbo-1106",
        "openai-chat:gpt-3.5-turbo-16k",
        "openai-chat:gpt-3.5-turbo-16k-0613",
        "openai-chat:gpt-4",
        "openai-chat:gpt-4-0314",
        "openai-chat:gpt-4-0613",
        "openai-chat:gpt-4-turbo",
        "openai-chat:gpt-4-turbo-2024-04-09",
        "openai-chat:gpt-4.1",
        "openai-chat:gpt-4.1-2025-04-14",
        "openai-chat:gpt-4.1-mini",
        "openai-chat:gpt-4.1-mini-2025-04-14",
        "openai-chat:gpt-4.1-nano",
        "openai-chat:gpt-4.1-nano-2025-04-14",
        "openai-chat:gpt-4o",
        "openai-chat:gpt-4o-2024-05-13",
        "openai-chat:gpt-4o-2024-08-06",
        "openai-chat:gpt-4o-2024-11-20",
        "openai-chat:gpt-4o-audio-preview",
        "openai-chat:gpt-4o-audio-preview-2024-12-17",
        "openai-chat:gpt-4o-audio-preview-2025-06-03",
        "openai-chat:gpt-4o-mini",
        "openai-chat:gpt-4o-mini-2024-07-18",
        "openai-chat:gpt-4o-mini-audio-preview",
        "openai-chat:gpt-4o-mini-audio-preview-2024-12-17",
        "openai-chat:gpt-4o-mini-search-preview",
        "openai-chat:gpt-4o-mini-search-preview-2025-03-11",
        "openai-chat:gpt-4o-search-preview",
        "openai-chat:gpt-4o-search-preview-2025-03-11",
        "openai-chat:gpt-5",
        "openai-chat:gpt-5-2025-08-07",
        "openai-chat:gpt-5-chat-latest",
        "openai-chat:gpt-5-codex",
        "openai-chat:gpt-5-mini",
        "openai-chat:gpt-5-mini-2025-08-07",
        "openai-chat:gpt-5-nano",
        "openai-chat:gpt-5-nano-2025-08-07",
        "openai-chat:gpt-5-pro",
        "openai-chat:gpt-5-pro-2025-10-06",
        "openai-chat:gpt-5.1",
        "openai-chat:gpt-5.1-2025-11-13",
        "openai-chat:gpt-5.1-chat-latest",
        "openai-chat:gpt-5.1-codex",
        "openai-chat:gpt-5.1-codex-max",
        "openai-chat:gpt-5.2",
        "openai-chat:gpt-5.2-2025-12-11",
        "openai-chat:gpt-5.2-chat-latest",
        "openai-chat:gpt-5.2-pro",
        "openai-chat:gpt-5.2-pro-2025-12-11",
        "openai-chat:gpt-5.3-chat-latest",
        "openai-chat:gpt-5.4",
        "openai-chat:gpt-5.4-mini",
        "openai-chat:gpt-5.4-mini-2026-03-17",
        "openai-chat:gpt-5.4-nano",
        "openai-chat:gpt-5.4-nano-2026-03-17",
        "openai-chat:o1",
        "openai-chat:o1-2024-12-17",
        "openai-chat:o1-pro",
        "openai-chat:o1-pro-2025-03-19",
        "openai-chat:o3",
        "openai-chat:o3-2025-04-16",
        "openai-chat:o3-deep-research",
        "openai-chat:o3-deep-research-2025-06-26",
        "openai-chat:o3-mini",
        "openai-chat:o3-mini-2025-01-31",
        "openai-chat:o3-pro",
        "openai-chat:o3-pro-2025-06-10",
        "openai-chat:o4-mini",
        "openai-chat:o4-mini-2025-04-16",
        "openai-chat:o4-mini-deep-research",
        "openai-chat:o4-mini-deep-research-2025-06-26",
        "openai:computer-use-preview",
        "openai:computer-use-preview-2025-03-11",
        "openai:gpt-3.5-turbo",
        "openai:gpt-3.5-turbo-0125",
        "openai:gpt-3.5-turbo-0301",
        "openai:gpt-3.5-turbo-0613",
        "openai:gpt-3.5-turbo-1106",
        "openai:gpt-3.5-turbo-16k",
        "openai:gpt-3.5-turbo-16k-0613",
        "openai:gpt-4",
        "openai:gpt-4-0314",
        "openai:gpt-4-0613",
        "openai:gpt-4-turbo",
        "openai:gpt-4-turbo-2024-04-09",
        "openai:gpt-4.1",
        "openai:gpt-4.1-2025-04-14",
        "openai:gpt-4.1-mini",
        "openai:gpt-4.1-mini-2025-04-14",
        "openai:gpt-4.1-nano",
        "openai:gpt-4.1-nano-2025-04-14",
        "openai:gpt-4o",
        "openai:gpt-4o-2024-05-13",
        "openai:gpt-4o-2024-08-06",
        "openai:gpt-4o-2024-11-20",
        "openai:gpt-4o-audio-preview",
        "openai:gpt-4o-audio-preview-2024-12-17",
        "openai:gpt-4o-audio-preview-2025-06-03",
        "openai:gpt-4o-mini",
        "openai:gpt-4o-mini-2024-07-18",
        "openai:gpt-4o-mini-audio-preview",
        "openai:gpt-4o-mini-audio-preview-2024-12-17",
        "openai:gpt-4o-mini-search-preview",
        "openai:gpt-4o-mini-search-preview-2025-03-11",
        "openai:gpt-4o-search-preview",
        "openai:gpt-4o-search-preview-2025-03-11",
        "openai:gpt-5",
        "openai:gpt-5-2025-08-07",
        "openai:gpt-5-chat-latest",
        "openai:gpt-5-codex",
        "openai:gpt-5-mini",
        "openai:gpt-5-mini-2025-08-07",
        "openai:gpt-5-nano",
        "openai:gpt-5-nano-2025-08-07",
        "openai:gpt-5-pro",
        "openai:gpt-5-pro-2025-10-06",
        "openai:gpt-5.1",
        "openai:gpt-5.1-2025-11-13",
        "openai:gpt-5.1-chat-latest",
        "openai:gpt-5.1-codex",
        "openai:gpt-5.1-codex-max",
        "openai:gpt-5.2",
        "openai:gpt-5.2-2025-12-11",
        "openai:gpt-5.2-chat-latest",
        "openai:gpt-5.2-pro",
        "openai:gpt-5.2-pro-2025-12-11",
        "openai:gpt-5.3-chat-latest",
        "openai:gpt-5.4",
        "openai:gpt-5.4-mini",
        "openai:gpt-5.4-mini-2026-03-17",
        "openai:gpt-5.4-nano",
        "openai:gpt-5.4-nano-2026-03-17",
        "openai:o1",
        "openai:o1-2024-12-17",
        "openai:o1-pro",
        "openai:o1-pro-2025-03-19",
        "openai:o3",
        "openai:o3-2025-04-16",
        "openai:o3-deep-research",
        "openai:o3-deep-research-2025-06-26",
        "openai:o3-mini",
        "openai:o3-mini-2025-01-31",
        "openai:o3-pro",
        "openai:o3-pro-2025-06-10",
        "openai:o4-mini",
        "openai:o4-mini-2025-04-16",
        "openai:o4-mini-deep-research",
        "openai:o4-mini-deep-research-2025-06-26",
        "test",
        "xai:grok-3",
        "xai:grok-3-fast",
        "xai:grok-3-fast-latest",
        "xai:grok-3-latest",
        "xai:grok-3-mini",
        "xai:grok-3-mini-fast",
        "xai:grok-3-mini-fast-latest",
        "xai:grok-4",
        "xai:grok-4-0709",
        "xai:grok-4-1-fast",
        "xai:grok-4-1-fast-non-reasoning",
        "xai:grok-4-1-fast-non-reasoning-latest",
        "xai:grok-4-1-fast-reasoning",
        "xai:grok-4-1-fast-reasoning-latest",
        "xai:grok-4-fast",
        "xai:grok-4-fast-non-reasoning",
        "xai:grok-4-fast-non-reasoning-latest",
        "xai:grok-4-fast-reasoning",
        "xai:grok-4-fast-reasoning-latest",
        "xai:grok-4-latest",
        "xai:grok-4.20",
        "xai:grok-4.20-0309",
        "xai:grok-4.20-0309-non-reasoning",
        "xai:grok-4.20-0309-reasoning",
        "xai:grok-4.20-multi-agent",
        "xai:grok-4.20-multi-agent-0309",
        "xai:grok-4.20-multi-agent-latest",
        "xai:grok-4.20-non-reasoning",
        "xai:grok-4.20-non-reasoning-latest",
        "xai:grok-4.20-reasoning-latest",
        "xai:grok-4.3",
        "xai:grok-4.3-latest",
        "xai:grok-code-fast-1",
    ],
)

Known model names that can be used with the model parameter of Agent.

KnownModelName is provided as a concise way to specify a model.

known_model_names cached 

known_model_names() -> tuple[str, ...]

Return every model name known to KnownModelName.

This is the public, stable way to enumerate the known model ids. Prefer it over introspecting the KnownModelName type alias directly (e.g. get_args(KnownModelName.__value__)), which is not part of the public API and would break if the alias were ever recomposed.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
73
74
75
76
77
78
79
80
81
@cache
def known_model_names() -> tuple[str, ...]:
    """Return every model name known to [`KnownModelName`][pydantic_ai.models.KnownModelName].

    This is the public, stable way to enumerate the known model ids. Prefer it over introspecting
    the `KnownModelName` type alias directly (e.g. `get_args(KnownModelName.__value__)`), which is
    not part of the public API and would break if the alias were ever recomposed.
    """
    return tuple(get_literal_values(KnownModelName.__value__, unpack_type_aliases='eager'))

ModelRequestParameters dataclass

Configuration for an agent's request to a model, specifically related to tools and output handling.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
@dataclass(repr=False, kw_only=True)
class ModelRequestParameters:
    """Configuration for an agent's request to a model, specifically related to tools and output handling."""

    function_tools: list[ToolDefinition] = field(default_factory=list[ToolDefinition])
    native_tools: list[AbstractNativeTool] = field(default_factory=list[AbstractNativeTool])

    output_mode: OutputMode = 'text'
    output_object: OutputObjectDefinition | None = None
    output_tools: list[ToolDefinition] = field(default_factory=list[ToolDefinition])
    prompted_output_template: str | Literal[False] | None = None
    allow_text_output: bool = True
    allow_image_output: bool = False

    instruction_parts: list[InstructionPart] | None = None
    """Structured instruction parts with metadata about their origin (static vs dynamic).

    Static instructions (`dynamic=False`) come from literal strings passed to `Agent(instructions=...)`.
    Dynamic instructions (`dynamic=True`) come from `@agent.instructions` functions, `TemplateStr`,
    or toolset `get_instructions()` methods.

    Models that support granular caching (e.g. Anthropic, Bedrock) use this to place cache
    boundaries at the static/dynamic instruction boundary.
    """

    thinking: ThinkingLevel | None = None
    """Resolved thinking/reasoning configuration for this request.

    `None` means the model should use its default behavior. Set by the base
    `Model.prepare_request()` from the unified `thinking` field in `ModelSettings`,
    after checking that the model's profile supports thinking.
    """

    @cached_property
    def tool_defs(self) -> dict[str, ToolDefinition]:
        return {tool_def.name: tool_def for tool_def in [*self.function_tools, *self.output_tools]}

    @cached_property
    def prompted_output_instructions(self) -> str | None:
        if self.prompted_output_template and self.output_object:
            return StructuredTextOutputSchema.build_instructions(self.prompted_output_template, self.output_object)
        return None

    def with_default_output_mode(self, output_mode: StructuredOutputMode) -> ModelRequestParameters:
        """Set the default output mode if the current mode is 'auto', atomically updating allow_text_output.

        No-op if the current output_mode is not 'auto'. This ensures the two fields stay in sync —
        output_mode='tool' implies allow_text_output=False, while 'native' and 'prompted' imply
        allow_text_output=True.
        """
        if self.output_mode != 'auto':
            return self
        return replace(self, output_mode=output_mode, allow_text_output=output_mode in ('native', 'prompted'))

    __repr__ = _utils.dataclasses_no_defaults_repr

instruction_parts class-attribute instance-attribute 

instruction_parts: list[InstructionPart] | None = None

Structured instruction parts with metadata about their origin (static vs dynamic).

Static instructions (dynamic=False) come from literal strings passed to Agent(instructions=...). Dynamic instructions (dynamic=True) come from @agent.instructions functions, TemplateStr, or toolset get_instructions() methods.

Models that support granular caching (e.g. Anthropic, Bedrock) use this to place cache boundaries at the static/dynamic instruction boundary.

thinking class-attribute instance-attribute 

thinking: ThinkingLevel | None = None

Resolved thinking/reasoning configuration for this request.

None means the model should use its default behavior. Set by the base Model.prepare_request() from the unified thinking field in ModelSettings, after checking that the model's profile supports thinking.

with_default_output_mode 

with_default_output_mode(
    output_mode: StructuredOutputMode,
) -> ModelRequestParameters

Set the default output mode if the current mode is 'auto', atomically updating allow_text_output.

No-op if the current output_mode is not 'auto'. This ensures the two fields stay in sync — output_mode='tool' implies allow_text_output=False, while 'native' and 'prompted' imply allow_text_output=True.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
163
164
165
166
167
168
169
170
171
172
def with_default_output_mode(self, output_mode: StructuredOutputMode) -> ModelRequestParameters:
    """Set the default output mode if the current mode is 'auto', atomically updating allow_text_output.

    No-op if the current output_mode is not 'auto'. This ensures the two fields stay in sync —
    output_mode='tool' implies allow_text_output=False, while 'native' and 'prompted' imply
    allow_text_output=True.
    """
    if self.output_mode != 'auto':
        return self
    return replace(self, output_mode=output_mode, allow_text_output=output_mode in ('native', 'prompted'))

Model

Bases: ABC, Generic[InterfaceClient]

Abstract class for a model.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
class Model(ABC, Generic[InterfaceClient]):
    """Abstract class for a model."""

    _provider: Provider[InterfaceClient]
    _profile: ModelProfileSpec | None = None
    _settings: ModelSettings | None = None

    def __init__(
        self,
        *,
        settings: ModelSettings | None = None,
        profile: ModelProfileSpec | None = None,
    ) -> None:
        """Initialize the model with optional settings and profile.

        Args:
            settings: Model-specific settings that will be used as defaults for this model.
            profile: The model profile to use.
        """
        self._settings = settings
        self._profile = profile

    @property
    def provider(self) -> Provider[InterfaceClient] | None:
        """The provider for this model, if any."""
        return getattr(self, '_provider', None)

    async def __aenter__(self) -> Self:
        """Enter the model context, delegating to the provider to manage its HTTP client lifecycle."""
        if self.provider is not None:
            await self.provider.__aenter__()
        return self

    async def __aexit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: TracebackType | None,
    ) -> bool | None:
        """Exit the model context, closing the provider's HTTP client if it owns one."""
        if self.provider is not None:
            await self.provider.__aexit__(exc_type, exc_val, exc_tb)

    @property
    def settings(self) -> ModelSettings | None:
        """Get the model settings."""
        return self._settings

    @abstractmethod
    async def request(
        self,
        messages: list[ModelMessage],
        model_settings: ModelSettings | None,
        model_request_parameters: ModelRequestParameters,
    ) -> ModelResponse:
        """Make a request to the model.

        This is ultimately called by `pydantic_ai._agent_graph.ModelRequestNode._make_request(...)`.
        """
        raise NotImplementedError()

    async def count_tokens(
        self,
        messages: list[ModelMessage],
        model_settings: ModelSettings | None,
        model_request_parameters: ModelRequestParameters,
    ) -> RequestUsage:
        """Make a request to the model for counting tokens."""
        # This method is not required, but you need to implement it if you want to support `UsageLimits.count_tokens_before_request`.
        raise NotImplementedError(f'Token counting ahead of the request is not supported by {self.__class__.__name__}')

    async def compact_messages(
        self,
        request_context: ModelRequestContext,
        *,
        instructions: str | None = None,
    ) -> ModelResponse:
        """Compact messages to reduce conversation context size.

        This method is optional and only supported by specific providers
        (e.g. OpenAI Responses API). Providers that support compaction
        override this method with their implementation.
        """
        raise NotImplementedError(f'Message compaction is not supported by {self.__class__.__name__}')

    @asynccontextmanager
    async def request_stream(
        self,
        messages: list[ModelMessage],
        model_settings: ModelSettings | None,
        model_request_parameters: ModelRequestParameters,
        run_context: RunContext[Any] | None = None,
    ) -> AsyncGenerator[StreamedResponse]:
        """Make a request to the model and return a streaming response."""
        # This method is not required, but you need to implement it if you want to support streamed responses
        raise NotImplementedError(f'Streamed requests not supported by this {self.__class__.__name__}')
        # yield is required to make this a generator for type checking
        # noinspection PyUnreachableCode
        yield  # pragma: no cover

    def customize_request_parameters(self, model_request_parameters: ModelRequestParameters) -> ModelRequestParameters:
        """Customize the request parameters for the model.

        This method can be overridden by subclasses to modify the request parameters before sending them to the model.
        In particular, this method can be used to make modifications to the generated tool JSON schemas if necessary
        for vendor/model-specific reasons.
        """
        if transformer := self.profile.get('json_schema_transformer'):
            model_request_parameters = replace(
                model_request_parameters,
                function_tools=[_customize_tool_def(transformer, t) for t in model_request_parameters.function_tools],
                output_tools=[_customize_tool_def(transformer, t) for t in model_request_parameters.output_tools],
            )
            if output_object := model_request_parameters.output_object:
                model_request_parameters = replace(
                    model_request_parameters,
                    output_object=_customize_output_object(transformer, output_object),
                )

        return model_request_parameters

    def prepare_request(
        self,
        model_settings: ModelSettings | None,
        model_request_parameters: ModelRequestParameters,
    ) -> tuple[ModelSettings | None, ModelRequestParameters]:
        """Prepare request inputs before they are passed to the provider.

        This merges the given `model_settings` with the model's own `settings` attribute and ensures
        `customize_request_parameters` is applied to the resolved
        [`ModelRequestParameters`][pydantic_ai.models.ModelRequestParameters]. Subclasses can override this method if
        they need to customize the preparation flow further, but most implementations should simply call
        `self.prepare_request(...)` at the start of their `request` (and related) methods.
        """
        model_settings = merge_model_settings(self.settings, model_settings)

        params = self.customize_request_parameters(model_request_parameters)
        params = _prepare_return_schemas(params, self.profile)

        # Resolve unified thinking setting and strip from model_settings
        if model_settings and 'thinking' in model_settings:
            thinking_value = model_settings['thinking']
            supports_thinking = self.profile.get('supports_thinking', False)
            thinking_always_enabled = self.profile.get('thinking_always_enabled', False)
            if supports_thinking or thinking_always_enabled:
                if not (thinking_value is False and thinking_always_enabled):
                    params = replace(params, thinking=thinking_value)
            stripped = {k: v for k, v in model_settings.items() if k != 'thinking'}
            model_settings = cast(ModelSettings, stripped) if stripped else None

        if native_tools := params.native_tools:
            # Deduplicate native tools
            params = replace(
                params,
                native_tools=list({tool.unique_id: tool for tool in native_tools}.values()),
            )

        params = params.with_default_output_mode(self.profile.get('default_structured_output_mode', 'tool'))

        # Reset irrelevant fields
        if params.output_tools and params.output_mode != 'tool':
            params = replace(params, output_tools=[])
        if params.output_object and params.output_mode not in ('native', 'prompted'):
            params = replace(params, output_object=None)
        if params.prompted_output_template and params.output_mode not in ('prompted', 'native'):
            params = replace(params, prompted_output_template=None)  # pragma: no cover

        # Set default prompted output template
        if (
            params.output_mode == 'prompted'
            or (
                params.output_mode == 'native'
                and self.profile.get('native_output_requires_schema_in_instructions', False)
            )
        ) and params.prompted_output_template is None:
            params = replace(
                params,
                prompted_output_template=self.profile.get('prompted_output_template', DEFAULT_PROMPTED_OUTPUT_TEMPLATE),
            )

        # Append prompted_output_instructions to instruction_parts so models that use structured
        # instruction parts (for per-part system messages or cache placement) also get them.
        # Done here (after customize_request_parameters) so it uses the final resolved template.
        if output_instr := params.prompted_output_instructions:
            parts = [*(params.instruction_parts or []), InstructionPart(content=output_instr)]
            params = replace(params, instruction_parts=InstructionPart.sorted(parts))

        # Check if output mode is supported
        if params.output_mode == 'native' and not self.profile.get('supports_json_schema_output', False):
            raise UserError('Native structured output is not supported by this model.')
        if params.output_mode == 'tool' and not self.profile.get('supports_tools', True):
            raise UserError('Tool output is not supported by this model.')
        if params.allow_image_output and not self.profile.get('supports_image_output', False):
            raise UserError('Image output is not supported by this model.')

        # Check native tools and handle fallback swap
        if params.native_tools or any(t.unless_native or t.with_native for t in params.function_tools):
            params = self._resolve_native_tool_swap(params)

        return model_settings, params

    def prepare_messages(self, messages: list[ModelMessage]) -> list[ModelMessage]:
        """Pre-process the message history before it's handed to the adapter's message-prep step.

        Currently translates any typed `NativeToolSearch*Part` instances carried over from a
        prior native turn (e.g. Anthropic / OpenAI Responses) into the local-shape
        `ToolSearch*Part` instances when the active model's profile doesn't support
        `ToolSearchTool` — splitting the single `ModelResponse(call+return)` carrying the
        inline server-side result into `ModelResponse(call) + ModelRequest(return)` so the
        adapter sees a normal function-call exchange against `search_tools`.

        Also wraps non-leading `SystemPromptPart`s as `<system>`-tagged `UserPromptPart`s when
        the profile's `supports_inline_system_prompts` is `False`.

        Subclasses normally don't need to override this; the framework calls it on the
        agent's behalf in `_agent_graph._make_request` so per-adapter message-prep code
        sees a homogeneous shape regardless of which provider produced the prior turn.
        """
        if ToolSearchTool not in self.profile.get('supported_native_tools', SUPPORTED_NATIVE_TOOLS):
            from .._tool_search import synthesize_local_tool_search_messages

            messages = synthesize_local_tool_search_messages(messages)

        if not self.profile.get('supports_inline_system_prompts', False):
            messages = _wrap_non_leading_system_prompts(messages)

        return messages

    def _resolve_native_tool_swap(self, params: ModelRequestParameters) -> ModelRequestParameters:
        """Swap native tools and function-tool fallbacks/corpus based on profile support.

        Four rules drive the per-tool filter:

        1. `unless_native` matches a supported native tool → drop from wire.
        2. `with_native` matches a supported native tool → keep on wire; the adapter
           applies any native-tool-specific format (e.g. Anthropic / OpenAI's wire-side
           `defer_loading` flag for `ToolSearchTool`).
        3. `with_native` matches an *unsupported* native tool AND `defer_loading=True`
           → drop from wire (the corpus member is currently undiscovered, so the model has
           no way to call it on this provider).
        4. Otherwise → keep.

        On top of the four-rule filter, two narrower drops apply, kept independent:

        * `optional=True` only governs the *unsupported-on-this-model* path: an unsupported
          optional native tool is silently dropped (no error raised). It does NOT govern the
          corpus-empty drop below.
        * The corpus-empty drop is specific to the framework-managed tool-search native tool's
          corpus-management role: an *optional* `ToolSearchTool` is dropped when its
          corpus ends up empty after filtering, since sending it with no deferred tools
          to discover would waste a tool slot. A non-optional `ToolSearchTool` stays —
          the user asked explicitly. Other native tools don't have a corpus and aren't subject
          to this drop, so making `optional` a base-class field doesn't accidentally cause
          e.g. `WebSearchTool(optional=True)` to be dropped here.
        """
        supported_types = self.profile.get('supported_native_tools', SUPPORTED_NATIVE_TOOLS)

        supported_natives = [t for t in params.native_tools if isinstance(t, tuple(supported_types))]
        unsupported_natives = [t for t in params.native_tools if not isinstance(t, tuple(supported_types))]

        supported_ids = {t.unique_id for t in supported_natives}
        unsupported_ids = {t.unique_id for t in unsupported_natives}
        optional_ids = {t.unique_id for t in unsupported_natives if t.optional}
        fallback_ids = {t.unless_native for t in params.function_tools if t.unless_native}

        without_fallback = unsupported_ids - fallback_ids - optional_ids
        if without_fallback:
            unsupported_names = [type(t).__name__ for t in unsupported_natives if t.unique_id in without_fallback]
            supported_names = [t.__name__ for t in supported_types]
            raise UserError(
                f'Native tool(s) {unsupported_names} not supported by this model. '
                f'Supported: {supported_names}. '
                f'To use these tools with this model, provide a local fallback via '
                f'NativeOrLocalTool(native=..., local=...) or the `local` parameter '
                f"of the capability (e.g. WebSearch(local='duckduckgo'), WebFetch(local=True), "
                f'MCP(local=True), ImageGeneration(local=my_func)). '
                f'Some capabilities require an optional install group for the local fallback '
                f'(e.g. `pip install "pydantic-ai-slim[mcp]"` for MCP).'
            )

        tool_search_resolution = _resolve_tool_search_native_for_capability_owned_corpus(
            supported_natives, params.function_tools
        )
        supported_natives = tool_search_resolution.native_tools
        tool_search_kept_local = tool_search_resolution.keep_search_tools_local

        function_tools: list[ToolDefinition] = []
        for t in params.function_tools:
            # Rule 1: drop local fallback when the native tool is supported — except for
            # `search_tools` when tool search was kept local for capability visibility,
            # where the local function tool is the callback the client-executed native
            # surface dispatches to.
            if t.unless_native and t.unless_native in supported_ids:
                if not (tool_search_kept_local and t.unless_native == ToolSearchTool.kind):
                    continue
            # Rule 3: drop undiscovered corpus members when the native tool is unsupported.
            if t.with_native and t.with_native not in supported_ids and t.defer_loading:
                continue
            # Rules 2 + 4: keep.
            function_tools.append(t)

        # Drop optional `ToolSearchTool` whose managed corpus is empty after filtering —
        # nothing to discover, sending it would waste a tool slot. The `isinstance` check
        # confines this to ToolSearchTool specifically: other native tools don't carry a corpus,
        # so making `optional` a base-class field doesn't accidentally drop e.g.
        # `WebSearchTool(optional=True)` here on absence of dependents.
        remaining_corpus_ids = {t.with_native for t in function_tools if t.with_native}
        supported_natives = [
            t
            for t in supported_natives
            if not (isinstance(t, ToolSearchTool) and t.optional) or t.unique_id in remaining_corpus_ids
        ]
        return replace(params, native_tools=supported_natives, function_tools=function_tools)

    @property
    @abstractmethod
    def model_name(self) -> str:
        """The model name."""
        raise NotImplementedError()

    @property
    def model_id(self) -> str:
        """The fully qualified model name in `'provider:model_name'` format."""
        return f'{self.system}:{self.model_name}'

    @property
    def label(self) -> str:
        """Human-friendly display label for the model.

        Handles common patterns:
        - gpt-5 -> GPT 5
        - claude-sonnet-4-5 -> Claude Sonnet 4.5
        - gemini-2.5-pro -> Gemini 2.5 Pro
        - meta-llama/llama-3-70b -> Llama 3 70b (OpenRouter style)
        """
        label = self.model_name
        # Handle OpenRouter-style names with / (e.g., meta-llama/llama-3-70b)
        if '/' in label:
            label = label.split('/')[-1]

        parts = label.split('-')
        result: list[str] = []

        for i, part in enumerate(parts):
            if i == 0 and part.lower() == 'gpt':
                result.append(part.upper())
            elif part.replace('.', '').isdigit():
                if result and result[-1].replace('.', '').isdigit():
                    result[-1] = f'{result[-1]}.{part}'
                else:
                    result.append(part)
            else:
                result.append(part.capitalize())

        return ' '.join(result)

    @classmethod
    def supported_native_tools(cls) -> frozenset[type[AbstractNativeTool]]:
        """Return the set of native tool types this model class can handle.

        Subclasses should override this to reflect their actual capabilities.
        Default is empty set - subclasses must explicitly declare support.
        """
        return frozenset()

    @cached_property
    def profile(self) -> ModelProfile:
        """The model profile.

        Resolution order (later layers override earlier ones):
          1. `DEFAULT_PROFILE` — base values for every key in `ModelProfile`.
          2. The provider's `model_profile(model_name)` result — provider-specific defaults
             for this model.
          3. The user's `profile=` argument — partial dict merged on top, OR a callable
             `(default) -> profile` for full control.

        After resolution we compute the intersection of the profile's `supported_native_tools`
        and the model class's implemented tools, ensuring `model.profile['supported_native_tools']`
        is the single source of truth for what's actually usable.
        """
        # Step 1+2: provider default merged with base default
        provider_profile: ModelProfile = {}
        if (provider := self.provider) is not None:
            provider_profile = provider.model_profile(self.model_name) or {}
        resolved = merge_profile(DEFAULT_PROFILE, provider_profile)

        # Step 3: user override
        user = self._profile
        if user is None:
            pass
        elif callable(user):
            # New v2 form: (default profile) -> final profile
            resolved = user(resolved)
        else:
            # Partial dict — merge on top
            resolved = merge_profile(resolved, user)

        # Step 4: native tools intersection — profile's allowed tools & model's implemented tools
        model_supported = self.__class__.supported_native_tools()
        profile_supported = resolved.get('supported_native_tools', SUPPORTED_NATIVE_TOOLS)
        effective_tools = profile_supported & model_supported
        if effective_tools != profile_supported:
            resolved = merge_profile(resolved, ModelProfile(supported_native_tools=effective_tools))

        return resolved

    @property
    @abstractmethod
    def system(self) -> str:
        """The model provider, ex: openai.

        Use to populate the `gen_ai.system` OpenTelemetry semantic convention attribute,
        so should use well-known values listed in
        https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/#gen-ai-system
        when applicable.
        """
        raise NotImplementedError()

    @property
    def base_url(self) -> str | None:
        """The base URL for the provider API, if available."""
        return None

    @staticmethod
    def _get_instruction_parts(
        messages: Sequence[ModelMessage], model_request_parameters: ModelRequestParameters
    ) -> list[InstructionPart] | None:
        """Get structured instruction parts for the current request.

        Uses `model_request_parameters.instruction_parts` when set (normal agent flow).
        Falls back to synthesizing from `ModelRequest.instructions` in message history
        when `instruction_parts` is `None` (e.g. direct `model.request()` calls).
        """
        if model_request_parameters.instruction_parts is not None:
            return model_request_parameters.instruction_parts or None

        # Fallback: synthesize from message history for direct model.request() callers.
        # Mirrors the last-two-requests logic from `pydantic_ai._instrumentation.get_instructions`:
        # if the most recent request only has tool-return/retry-prompt parts (a "mock" request
        # for result tools), use the instructions from the second-to-most-recent request.
        last_two_requests: list[ModelRequest] = []
        for message in reversed(messages):
            if isinstance(message, ModelRequest):
                last_two_requests.append(message)
                if len(last_two_requests) == 2:
                    break
                if message.instructions is not None:
                    return [InstructionPart(content=message.instructions)]

        if len(last_two_requests) == 2:
            most_recent = last_two_requests[0]
            second = last_two_requests[1]
            if (
                all(p.part_kind == 'tool-return' or p.part_kind == 'retry-prompt' for p in most_recent.parts)
                and second.instructions is not None
            ):
                return [InstructionPart(content=second.instructions)]

        return None

__init__ 

__init__(
    *,
    settings: ModelSettings | None = None,
    profile: ModelProfileSpec | None = None
) -> None

Initialize the model with optional settings and profile.

Parameters:

Name Type Description Default
settings ModelSettings | None

Model-specific settings that will be used as defaults for this model.

 None
profile ModelProfileSpec | None

The model profile to use.

 None
Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
def __init__(
    self,
    *,
    settings: ModelSettings | None = None,
    profile: ModelProfileSpec | None = None,
) -> None:
    """Initialize the model with optional settings and profile.

    Args:
        settings: Model-specific settings that will be used as defaults for this model.
        profile: The model profile to use.
    """
    self._settings = settings
    self._profile = profile

provider property 

provider: Provider[InterfaceClient] | None

The provider for this model, if any.

__aenter__ async 

__aenter__() -> Self

Enter the model context, delegating to the provider to manage its HTTP client lifecycle.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
218
219
220
221
222
async def __aenter__(self) -> Self:
    """Enter the model context, delegating to the provider to manage its HTTP client lifecycle."""
    if self.provider is not None:
        await self.provider.__aenter__()
    return self

__aexit__ async 

__aexit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> bool | None

Exit the model context, closing the provider's HTTP client if it owns one.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
224
225
226
227
228
229
230
231
232
async def __aexit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> bool | None:
    """Exit the model context, closing the provider's HTTP client if it owns one."""
    if self.provider is not None:
        await self.provider.__aexit__(exc_type, exc_val, exc_tb)

settings property 

settings: ModelSettings | None

Get the model settings.

request abstractmethod async 

request(
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
) -> ModelResponse

Make a request to the model.

This is ultimately called by pydantic_ai._agent_graph.ModelRequestNode._make_request(...).

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
239
240
241
242
243
244
245
246
247
248
249
250
@abstractmethod
async def request(
    self,
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
) -> ModelResponse:
    """Make a request to the model.

    This is ultimately called by `pydantic_ai._agent_graph.ModelRequestNode._make_request(...)`.
    """
    raise NotImplementedError()

count_tokens async 

count_tokens(
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
) -> RequestUsage

Make a request to the model for counting tokens.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
252
253
254
255
256
257
258
259
260
async def count_tokens(
    self,
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
) -> RequestUsage:
    """Make a request to the model for counting tokens."""
    # This method is not required, but you need to implement it if you want to support `UsageLimits.count_tokens_before_request`.
    raise NotImplementedError(f'Token counting ahead of the request is not supported by {self.__class__.__name__}')

compact_messages async 

compact_messages(
    request_context: ModelRequestContext,
    *,
    instructions: str | None = None
) -> ModelResponse

Compact messages to reduce conversation context size.

This method is optional and only supported by specific providers (e.g. OpenAI Responses API). Providers that support compaction override this method with their implementation.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
262
263
264
265
266
267
268
269
270
271
272
273
274
async def compact_messages(
    self,
    request_context: ModelRequestContext,
    *,
    instructions: str | None = None,
) -> ModelResponse:
    """Compact messages to reduce conversation context size.

    This method is optional and only supported by specific providers
    (e.g. OpenAI Responses API). Providers that support compaction
    override this method with their implementation.
    """
    raise NotImplementedError(f'Message compaction is not supported by {self.__class__.__name__}')

request_stream async 

request_stream(
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
    run_context: RunContext[Any] | None = None,
) -> AsyncGenerator[StreamedResponse]

Make a request to the model and return a streaming response.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
276
277
278
279
280
281
282
283
284
285
286
287
288
289
@asynccontextmanager
async def request_stream(
    self,
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
    run_context: RunContext[Any] | None = None,
) -> AsyncGenerator[StreamedResponse]:
    """Make a request to the model and return a streaming response."""
    # This method is not required, but you need to implement it if you want to support streamed responses
    raise NotImplementedError(f'Streamed requests not supported by this {self.__class__.__name__}')
    # yield is required to make this a generator for type checking
    # noinspection PyUnreachableCode
    yield  # pragma: no cover

customize_request_parameters 

customize_request_parameters(
    model_request_parameters: ModelRequestParameters,
) -> ModelRequestParameters

Customize the request parameters for the model.

This method can be overridden by subclasses to modify the request parameters before sending them to the model. In particular, this method can be used to make modifications to the generated tool JSON schemas if necessary for vendor/model-specific reasons.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
def customize_request_parameters(self, model_request_parameters: ModelRequestParameters) -> ModelRequestParameters:
    """Customize the request parameters for the model.

    This method can be overridden by subclasses to modify the request parameters before sending them to the model.
    In particular, this method can be used to make modifications to the generated tool JSON schemas if necessary
    for vendor/model-specific reasons.
    """
    if transformer := self.profile.get('json_schema_transformer'):
        model_request_parameters = replace(
            model_request_parameters,
            function_tools=[_customize_tool_def(transformer, t) for t in model_request_parameters.function_tools],
            output_tools=[_customize_tool_def(transformer, t) for t in model_request_parameters.output_tools],
        )
        if output_object := model_request_parameters.output_object:
            model_request_parameters = replace(
                model_request_parameters,
                output_object=_customize_output_object(transformer, output_object),
            )

    return model_request_parameters

prepare_request 

prepare_request(
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
) -> tuple[ModelSettings | None, ModelRequestParameters]

Prepare request inputs before they are passed to the provider.

This merges the given model_settings with the model's own settings attribute and ensures customize_request_parameters is applied to the resolved ModelRequestParameters. Subclasses can override this method if they need to customize the preparation flow further, but most implementations should simply call self.prepare_request(...) at the start of their request (and related) methods.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
def prepare_request(
    self,
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
) -> tuple[ModelSettings | None, ModelRequestParameters]:
    """Prepare request inputs before they are passed to the provider.

    This merges the given `model_settings` with the model's own `settings` attribute and ensures
    `customize_request_parameters` is applied to the resolved
    [`ModelRequestParameters`][pydantic_ai.models.ModelRequestParameters]. Subclasses can override this method if
    they need to customize the preparation flow further, but most implementations should simply call
    `self.prepare_request(...)` at the start of their `request` (and related) methods.
    """
    model_settings = merge_model_settings(self.settings, model_settings)

    params = self.customize_request_parameters(model_request_parameters)
    params = _prepare_return_schemas(params, self.profile)

    # Resolve unified thinking setting and strip from model_settings
    if model_settings and 'thinking' in model_settings:
        thinking_value = model_settings['thinking']
        supports_thinking = self.profile.get('supports_thinking', False)
        thinking_always_enabled = self.profile.get('thinking_always_enabled', False)
        if supports_thinking or thinking_always_enabled:
            if not (thinking_value is False and thinking_always_enabled):
                params = replace(params, thinking=thinking_value)
        stripped = {k: v for k, v in model_settings.items() if k != 'thinking'}
        model_settings = cast(ModelSettings, stripped) if stripped else None

    if native_tools := params.native_tools:
        # Deduplicate native tools
        params = replace(
            params,
            native_tools=list({tool.unique_id: tool for tool in native_tools}.values()),
        )

    params = params.with_default_output_mode(self.profile.get('default_structured_output_mode', 'tool'))

    # Reset irrelevant fields
    if params.output_tools and params.output_mode != 'tool':
        params = replace(params, output_tools=[])
    if params.output_object and params.output_mode not in ('native', 'prompted'):
        params = replace(params, output_object=None)
    if params.prompted_output_template and params.output_mode not in ('prompted', 'native'):
        params = replace(params, prompted_output_template=None)  # pragma: no cover

    # Set default prompted output template
    if (
        params.output_mode == 'prompted'
        or (
            params.output_mode == 'native'
            and self.profile.get('native_output_requires_schema_in_instructions', False)
        )
    ) and params.prompted_output_template is None:
        params = replace(
            params,
            prompted_output_template=self.profile.get('prompted_output_template', DEFAULT_PROMPTED_OUTPUT_TEMPLATE),
        )

    # Append prompted_output_instructions to instruction_parts so models that use structured
    # instruction parts (for per-part system messages or cache placement) also get them.
    # Done here (after customize_request_parameters) so it uses the final resolved template.
    if output_instr := params.prompted_output_instructions:
        parts = [*(params.instruction_parts or []), InstructionPart(content=output_instr)]
        params = replace(params, instruction_parts=InstructionPart.sorted(parts))

    # Check if output mode is supported
    if params.output_mode == 'native' and not self.profile.get('supports_json_schema_output', False):
        raise UserError('Native structured output is not supported by this model.')
    if params.output_mode == 'tool' and not self.profile.get('supports_tools', True):
        raise UserError('Tool output is not supported by this model.')
    if params.allow_image_output and not self.profile.get('supports_image_output', False):
        raise UserError('Image output is not supported by this model.')

    # Check native tools and handle fallback swap
    if params.native_tools or any(t.unless_native or t.with_native for t in params.function_tools):
        params = self._resolve_native_tool_swap(params)

    return model_settings, params

prepare_messages 

prepare_messages(
    messages: list[ModelMessage],
) -> list[ModelMessage]

Pre-process the message history before it's handed to the adapter's message-prep step.

Currently translates any typed NativeToolSearch*Part instances carried over from a prior native turn (e.g. Anthropic / OpenAI Responses) into the local-shape ToolSearch*Part instances when the active model's profile doesn't support ToolSearchTool — splitting the single ModelResponse(call+return) carrying the inline server-side result into ModelResponse(call) + ModelRequest(return) so the adapter sees a normal function-call exchange against search_tools.

Also wraps non-leading SystemPromptParts as <system>-tagged UserPromptParts when the profile's supports_inline_system_prompts is False.

Subclasses normally don't need to override this; the framework calls it on the agent's behalf in _agent_graph._make_request so per-adapter message-prep code sees a homogeneous shape regardless of which provider produced the prior turn.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
def prepare_messages(self, messages: list[ModelMessage]) -> list[ModelMessage]:
    """Pre-process the message history before it's handed to the adapter's message-prep step.

    Currently translates any typed `NativeToolSearch*Part` instances carried over from a
    prior native turn (e.g. Anthropic / OpenAI Responses) into the local-shape
    `ToolSearch*Part` instances when the active model's profile doesn't support
    `ToolSearchTool` — splitting the single `ModelResponse(call+return)` carrying the
    inline server-side result into `ModelResponse(call) + ModelRequest(return)` so the
    adapter sees a normal function-call exchange against `search_tools`.

    Also wraps non-leading `SystemPromptPart`s as `<system>`-tagged `UserPromptPart`s when
    the profile's `supports_inline_system_prompts` is `False`.

    Subclasses normally don't need to override this; the framework calls it on the
    agent's behalf in `_agent_graph._make_request` so per-adapter message-prep code
    sees a homogeneous shape regardless of which provider produced the prior turn.
    """
    if ToolSearchTool not in self.profile.get('supported_native_tools', SUPPORTED_NATIVE_TOOLS):
        from .._tool_search import synthesize_local_tool_search_messages

        messages = synthesize_local_tool_search_messages(messages)

    if not self.profile.get('supports_inline_system_prompts', False):
        messages = _wrap_non_leading_system_prompts(messages)

    return messages

model_name abstractmethod property 

model_name: str

The model name.

model_id property 

model_id: str

The fully qualified model name in 'provider:model_name' format.

label property 

label: str

Human-friendly display label for the model.

Handles common patterns: - gpt-5 -> GPT 5 - claude-sonnet-4-5 -> Claude Sonnet 4.5 - gemini-2.5-pro -> Gemini 2.5 Pro - meta-llama/llama-3-70b -> Llama 3 70b (OpenRouter style)

supported_native_tools classmethod 

supported_native_tools() -> (
    frozenset[type[AbstractNativeTool]]
)

Return the set of native tool types this model class can handle.

Subclasses should override this to reflect their actual capabilities. Default is empty set - subclasses must explicitly declare support.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
547
548
549
550
551
552
553
554
@classmethod
def supported_native_tools(cls) -> frozenset[type[AbstractNativeTool]]:
    """Return the set of native tool types this model class can handle.

    Subclasses should override this to reflect their actual capabilities.
    Default is empty set - subclasses must explicitly declare support.
    """
    return frozenset()

profile cached property 

profile: ModelProfile

The model profile.

Resolution order (later layers override earlier ones): 1. DEFAULT_PROFILE — base values for every key in ModelProfile. 2. The provider's model_profile(model_name) result — provider-specific defaults for this model. 3. The user's profile= argument — partial dict merged on top, OR a callable (default) -> profile for full control.

After resolution we compute the intersection of the profile's supported_native_tools and the model class's implemented tools, ensuring model.profile['supported_native_tools'] is the single source of truth for what's actually usable.

system abstractmethod property 

system: str

The model provider, ex: openai.

Use to populate the gen_ai.system OpenTelemetry semantic convention attribute, so should use well-known values listed in https://opentelemetry.io/docs/specs/semconv/attributes-registry/gen-ai/#gen-ai-system when applicable.

base_url property 

base_url: str | None

The base URL for the provider API, if available.

StreamedResponse dataclass

Bases: ABC

Streamed response from an LLM when calling a tool.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
@dataclass
class StreamedResponse(ABC):
    """Streamed response from an LLM when calling a tool."""

    model_request_parameters: ModelRequestParameters

    final_result_event: FinalResultEvent | None = field(default=None, init=False)

    provider_response_id: str | None = field(default=None, init=False)
    provider_details: dict[str, Any] | None = field(default=None, init=False)
    finish_reason: FinishReason | None = field(default=None, init=False)

    _event_iterator: AsyncIterator[ModelResponseStreamEvent] | None = field(default=None, init=False)
    _usage: RequestUsage = field(default_factory=RequestUsage, init=False)
    _cancelled: bool = field(default=False, init=False)
    _finished: bool = field(default=False, init=False)

    @cached_property
    def _parts_manager(self) -> ModelResponsePartsManager:
        # Built lazily so subclasses don't need to remember `super().__post_init__()`.
        # `model_request_parameters` is handed in so streamed `ToolCallPart`s auto-promote
        # to their typed subclasses (via `ToolDefinition.tool_kind`) from the first
        # `PartStartEvent` — consumers see typed parts throughout the stream rather than
        # only after a post-stream pass.
        return ModelResponsePartsManager(model_request_parameters=self.model_request_parameters)

    def __aiter__(self) -> AsyncIterator[ModelResponseStreamEvent]:  # noqa: C901
        """Stream the response as an async iterable of [`ModelResponseStreamEvent`][pydantic_ai.messages.ModelResponseStreamEvent]s.

        This proxies the `_event_iterator()` and emits all events, while also checking for matches
        on the result schema and emitting a [`FinalResultEvent`][pydantic_ai.messages.FinalResultEvent] if/when the
        first match is found.
        """
        if self._event_iterator is None:

            async def iterator_with_final_event(
                iterator: AsyncIterator[ModelResponseStreamEvent],
            ) -> AsyncIterator[ModelResponseStreamEvent]:
                async for event in iterator:
                    yield event
                    if (
                        final_result_event := _get_final_result_event(event, self.model_request_parameters)
                    ) is not None:
                        self.final_result_event = final_result_event
                        yield final_result_event
                        break

                # If we broke out of the above loop, we need to yield the rest of the events
                # If we didn't, this will just be a no-op
                async for event in iterator:
                    yield event

            async def iterator_with_part_end(
                iterator: AsyncIterator[ModelResponseStreamEvent],
            ) -> AsyncIterator[ModelResponseStreamEvent]:
                last_start_event: PartStartEvent | None = None

                def part_end_event(next_part: ModelResponsePart | None = None) -> PartEndEvent | None:
                    if not last_start_event:
                        return None

                    index = last_start_event.index
                    part = self._parts_manager.get_parts()[index]
                    if not isinstance(part, TextPart | ThinkingPart | BaseToolCallPart):
                        # Parts other than these 3 don't have deltas, so don't need an end part.
                        return None

                    return PartEndEvent(
                        index=index,
                        part=part,
                        next_part_kind=next_part.part_kind if next_part else None,
                    )

                async for event in iterator:
                    if isinstance(event, PartStartEvent):
                        if last_start_event:
                            end_event = part_end_event(event.part)
                            if end_event:
                                yield end_event

                            event.previous_part_kind = last_start_event.part.part_kind
                        last_start_event = event

                    yield event

                end_event = part_end_event()
                if end_event:
                    yield end_event

            async def iterator_with_cancel_guard(
                iterator: AsyncIterator[ModelResponseStreamEvent],
            ) -> AsyncIterator[ModelResponseStreamEvent]:
                # Suppress transport errors caused by `cancel()` tearing down the
                # connection mid-stream. The try/except has to live inside an
                # async generator body so it's active at every `await` during
                # iteration.
                try:
                    async for event in iterator:
                        yield event
                except self.get_stream_cancel_errors():
                    if not self.cancelled:
                        raise
                else:
                    # Only natural `StopAsyncIteration` flips `_finished`. Early
                    # `break` / `aclose()` (raising `GeneratorExit` at the suspended
                    # `yield`) and any in-flight exception leave `_finished=False`
                    # so `get()` reports the truncated response as `'incomplete'`
                    # rather than silently stamping it `'complete'`. The cancel
                    # branch above explicitly sets `_cancelled` (→ `'interrupted'`).
                    self._finished = True

            self._event_iterator = iterator_with_cancel_guard(
                iterator_with_part_end(iterator_with_final_event(self._get_event_iterator()))
            )
        return self._event_iterator

    async def cancel(self) -> None:
        """Cancel the stream, stopping token generation.

        Sets `self._cancelled = True` before delegating to `close_stream()`
        so the flag is visible to any iterator that observes the transport error
        raised when the underlying connection is torn down, even if
        `close_stream()` itself raises.
        """
        if self.cancelled:
            return
        self._cancelled = True
        await self.close_stream()

    def get_stream_cancel_errors(self) -> tuple[type[BaseException], ...]:
        """Return transport errors caused by `cancel()` tearing down the stream.

        The default covers model classes whose SDKs iterate `httpx` responses
        directly (Anthropic, OpenAI, Groq, Mistral, Google GenAI, HuggingFace,
        and the custom Gemini client), since they let bare `httpx` errors
        propagate from chunk reads. Model classes that use other transports
        (for example gRPC or botocore) should override this method.
        """
        return (httpx.StreamError, httpx.TransportError)

    async def close_stream(self) -> None:
        """Close the underlying HTTP/gRPC connection.

        Model classes must override this to stop token generation (and billing)
        on the remote side. Integrations that cannot support cancellation should
        leave the default implementation so `cancel()` fails clearly rather than
        silently reporting successful cancellation while generation continues.
        """
        raise NotImplementedError(
            f'Stream cancellation is not implemented for {type(self).__name__}. '
            'This model class must override `close_stream()` to support streaming cancellation.'
        )

    # TODO: We should not have public private methods which need to be overwritten.
    @abstractmethod
    async def _get_event_iterator(self) -> AsyncIterator[ModelResponseStreamEvent]:
        """Return an async iterator of [`ModelResponseStreamEvent`][pydantic_ai.messages.ModelResponseStreamEvent]s.

        This method should be implemented by subclasses to translate the vendor-specific stream of events into
        pydantic_ai-format events.

        It should use the `_parts_manager` to handle deltas, and should update the `_usage` attributes as it goes.
        """
        raise NotImplementedError()
        # noinspection PyUnreachableCode
        yield

    def get(self) -> ModelResponse:
        """Build a [`ModelResponse`][pydantic_ai.messages.ModelResponse] from the data received from the stream so far."""
        if self._cancelled:
            state: ModelResponseState = 'interrupted'
        elif self._finished:
            state = 'complete'
        else:
            state = 'incomplete'
        return ModelResponse(
            parts=self._parts_manager.get_parts(),
            model_name=self.model_name,
            timestamp=self.timestamp,
            usage=self._usage,
            provider_name=self.provider_name,
            provider_url=self.provider_url,
            provider_response_id=self.provider_response_id,
            provider_details=self.provider_details,
            finish_reason=self.finish_reason,
            state=state,
        )

    @property
    def usage(self) -> RequestUsage:
        """Get the usage of the response so far. This will not be the final usage until the stream is exhausted."""
        return self._usage

    @property
    @abstractmethod
    def model_name(self) -> str:
        """Get the model name of the response."""
        raise NotImplementedError()

    @property
    @abstractmethod
    def provider_name(self) -> str | None:
        """Get the provider name."""
        raise NotImplementedError()

    @property
    @abstractmethod
    def provider_url(self) -> str | None:
        """Get the provider base URL."""
        raise NotImplementedError()

    @property
    @abstractmethod
    def timestamp(self) -> datetime:
        """Get the timestamp of the response."""
        raise NotImplementedError()

    @property
    def cancelled(self) -> bool:
        """Whether the stream has been cancelled via `cancel()`."""
        return self._cancelled

__aiter__ 

__aiter__() -> AsyncIterator[ModelResponseStreamEvent]

Stream the response as an async iterable of ModelResponseStreamEvents.

This proxies the _event_iterator() and emits all events, while also checking for matches on the result schema and emitting a FinalResultEvent if/when the first match is found.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
def __aiter__(self) -> AsyncIterator[ModelResponseStreamEvent]:  # noqa: C901
    """Stream the response as an async iterable of [`ModelResponseStreamEvent`][pydantic_ai.messages.ModelResponseStreamEvent]s.

    This proxies the `_event_iterator()` and emits all events, while also checking for matches
    on the result schema and emitting a [`FinalResultEvent`][pydantic_ai.messages.FinalResultEvent] if/when the
    first match is found.
    """
    if self._event_iterator is None:

        async def iterator_with_final_event(
            iterator: AsyncIterator[ModelResponseStreamEvent],
        ) -> AsyncIterator[ModelResponseStreamEvent]:
            async for event in iterator:
                yield event
                if (
                    final_result_event := _get_final_result_event(event, self.model_request_parameters)
                ) is not None:
                    self.final_result_event = final_result_event
                    yield final_result_event
                    break

            # If we broke out of the above loop, we need to yield the rest of the events
            # If we didn't, this will just be a no-op
            async for event in iterator:
                yield event

        async def iterator_with_part_end(
            iterator: AsyncIterator[ModelResponseStreamEvent],
        ) -> AsyncIterator[ModelResponseStreamEvent]:
            last_start_event: PartStartEvent | None = None

            def part_end_event(next_part: ModelResponsePart | None = None) -> PartEndEvent | None:
                if not last_start_event:
                    return None

                index = last_start_event.index
                part = self._parts_manager.get_parts()[index]
                if not isinstance(part, TextPart | ThinkingPart | BaseToolCallPart):
                    # Parts other than these 3 don't have deltas, so don't need an end part.
                    return None

                return PartEndEvent(
                    index=index,
                    part=part,
                    next_part_kind=next_part.part_kind if next_part else None,
                )

            async for event in iterator:
                if isinstance(event, PartStartEvent):
                    if last_start_event:
                        end_event = part_end_event(event.part)
                        if end_event:
                            yield end_event

                        event.previous_part_kind = last_start_event.part.part_kind
                    last_start_event = event

                yield event

            end_event = part_end_event()
            if end_event:
                yield end_event

        async def iterator_with_cancel_guard(
            iterator: AsyncIterator[ModelResponseStreamEvent],
        ) -> AsyncIterator[ModelResponseStreamEvent]:
            # Suppress transport errors caused by `cancel()` tearing down the
            # connection mid-stream. The try/except has to live inside an
            # async generator body so it's active at every `await` during
            # iteration.
            try:
                async for event in iterator:
                    yield event
            except self.get_stream_cancel_errors():
                if not self.cancelled:
                    raise
            else:
                # Only natural `StopAsyncIteration` flips `_finished`. Early
                # `break` / `aclose()` (raising `GeneratorExit` at the suspended
                # `yield`) and any in-flight exception leave `_finished=False`
                # so `get()` reports the truncated response as `'incomplete'`
                # rather than silently stamping it `'complete'`. The cancel
                # branch above explicitly sets `_cancelled` (→ `'interrupted'`).
                self._finished = True

        self._event_iterator = iterator_with_cancel_guard(
            iterator_with_part_end(iterator_with_final_event(self._get_event_iterator()))
        )
    return self._event_iterator

cancel async 

cancel() -> None

Cancel the stream, stopping token generation.

Sets self._cancelled = True before delegating to close_stream() so the flag is visible to any iterator that observes the transport error raised when the underlying connection is torn down, even if close_stream() itself raises.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
768
769
770
771
772
773
774
775
776
777
778
779
async def cancel(self) -> None:
    """Cancel the stream, stopping token generation.

    Sets `self._cancelled = True` before delegating to `close_stream()`
    so the flag is visible to any iterator that observes the transport error
    raised when the underlying connection is torn down, even if
    `close_stream()` itself raises.
    """
    if self.cancelled:
        return
    self._cancelled = True
    await self.close_stream()

get_stream_cancel_errors 

get_stream_cancel_errors() -> (
    tuple[type[BaseException], ...]
)

Return transport errors caused by cancel() tearing down the stream.

The default covers model classes whose SDKs iterate httpx responses directly (Anthropic, OpenAI, Groq, Mistral, Google GenAI, HuggingFace, and the custom Gemini client), since they let bare httpx errors propagate from chunk reads. Model classes that use other transports (for example gRPC or botocore) should override this method.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
781
782
783
784
785
786
787
788
789
790
def get_stream_cancel_errors(self) -> tuple[type[BaseException], ...]:
    """Return transport errors caused by `cancel()` tearing down the stream.

    The default covers model classes whose SDKs iterate `httpx` responses
    directly (Anthropic, OpenAI, Groq, Mistral, Google GenAI, HuggingFace,
    and the custom Gemini client), since they let bare `httpx` errors
    propagate from chunk reads. Model classes that use other transports
    (for example gRPC or botocore) should override this method.
    """
    return (httpx.StreamError, httpx.TransportError)

close_stream async 

close_stream() -> None

Close the underlying HTTP/gRPC connection.

Model classes must override this to stop token generation (and billing) on the remote side. Integrations that cannot support cancellation should leave the default implementation so cancel() fails clearly rather than silently reporting successful cancellation while generation continues.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
792
793
794
795
796
797
798
799
800
801
802
803
async def close_stream(self) -> None:
    """Close the underlying HTTP/gRPC connection.

    Model classes must override this to stop token generation (and billing)
    on the remote side. Integrations that cannot support cancellation should
    leave the default implementation so `cancel()` fails clearly rather than
    silently reporting successful cancellation while generation continues.
    """
    raise NotImplementedError(
        f'Stream cancellation is not implemented for {type(self).__name__}. '
        'This model class must override `close_stream()` to support streaming cancellation.'
    )

get 

get() -> ModelResponse

Build a ModelResponse from the data received from the stream so far.

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
def get(self) -> ModelResponse:
    """Build a [`ModelResponse`][pydantic_ai.messages.ModelResponse] from the data received from the stream so far."""
    if self._cancelled:
        state: ModelResponseState = 'interrupted'
    elif self._finished:
        state = 'complete'
    else:
        state = 'incomplete'
    return ModelResponse(
        parts=self._parts_manager.get_parts(),
        model_name=self.model_name,
        timestamp=self.timestamp,
        usage=self._usage,
        provider_name=self.provider_name,
        provider_url=self.provider_url,
        provider_response_id=self.provider_response_id,
        provider_details=self.provider_details,
        finish_reason=self.finish_reason,
        state=state,
    )

usage property 

usage: RequestUsage

Get the usage of the response so far. This will not be the final usage until the stream is exhausted.

model_name abstractmethod property 

model_name: str

Get the model name of the response.

provider_name abstractmethod property 

provider_name: str | None

Get the provider name.

provider_url abstractmethod property 

provider_url: str | None

Get the provider base URL.

timestamp abstractmethod property 

timestamp: datetime

Get the timestamp of the response.

cancelled property 

cancelled: bool

Whether the stream has been cancelled via cancel().

ALLOW_MODEL_REQUESTS module-attribute 

ALLOW_MODEL_REQUESTS = True

Whether to allow requests to models.

This global setting allows you to disable request to most models, e.g. to make sure you don't accidentally make costly requests to a model during tests.

The testing models TestModel and FunctionModel are no affected by this setting.

check_allow_model_requests 

check_allow_model_requests() -> None

Check if model requests are allowed.

If you're defining your own models that have costs or latency associated with their use, you should call this in Model.request and Model.request_stream.

Raises:

Type Description
RuntimeError

If model requests are not allowed.
Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
886
887
888
889
890
891
892
893
894
895
896
def check_allow_model_requests() -> None:
    """Check if model requests are allowed.

    If you're defining your own models that have costs or latency associated with their use, you should call this in
    [`Model.request`][pydantic_ai.models.Model.request] and [`Model.request_stream`][pydantic_ai.models.Model.request_stream].

    Raises:
        RuntimeError: If model requests are not allowed.
    """
    if not ALLOW_MODEL_REQUESTS:
        raise RuntimeError('Model requests are not allowed, since ALLOW_MODEL_REQUESTS is False')

override_allow_model_requests 

override_allow_model_requests(
    allow_model_requests: bool,
) -> Generator[None]

Context manager to temporarily override ALLOW_MODEL_REQUESTS.

Parameters:

Name Type Description Default
allow_model_requests bool

Whether to allow model requests within the context.

 required
Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
899
900
901
902
903
904
905
906
907
908
909
910
911
912
@contextmanager
def override_allow_model_requests(allow_model_requests: bool) -> Generator[None]:
    """Context manager to temporarily override [`ALLOW_MODEL_REQUESTS`][pydantic_ai.models.ALLOW_MODEL_REQUESTS].

    Args:
        allow_model_requests: Whether to allow model requests within the context.
    """
    global ALLOW_MODEL_REQUESTS
    old_value = ALLOW_MODEL_REQUESTS
    ALLOW_MODEL_REQUESTS = allow_model_requests  # pyright: ignore[reportConstantRedefinition]
    try:
        yield
    finally:
        ALLOW_MODEL_REQUESTS = old_value  # pyright: ignore[reportConstantRedefinition]