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-haiku-4-5-20251001",
        "anthropic:claude-mythos-preview",
        "anthropic:claude-haiku-4-5",
        "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-20251101",
        "anthropic:claude-opus-4-5",
        "anthropic:claude-opus-4-6",
        "anthropic:claude-opus-4-7",
        "anthropic:claude-sonnet-4-0",
        "anthropic:claude-sonnet-4-20250514",
        "anthropic:claude-sonnet-4-5-20250929",
        "anthropic:claude-sonnet-4-5",
        "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:1",
        "bedrock:anthropic.claude-v2",
        "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-haiku-4-5-20251001",
        "gateway/anthropic:claude-mythos-preview",
        "gateway/anthropic:claude-haiku-4-5",
        "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-20251101",
        "gateway/anthropic:claude-opus-4-5",
        "gateway/anthropic:claude-opus-4-6",
        "gateway/anthropic:claude-opus-4-7",
        "gateway/anthropic:claude-sonnet-4-0",
        "gateway/anthropic:claude-sonnet-4-20250514",
        "gateway/anthropic:claude-sonnet-4-5-20250929",
        "gateway/anthropic:claude-sonnet-4-5",
        "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-image",
        "gateway/google-cloud:gemini-2.5-flash-lite-preview-09-2025",
        "gateway/google-cloud:gemini-2.5-flash-lite",
        "gateway/google-cloud:gemini-2.5-flash",
        "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-image",
        "gateway/google:gemini-2.5-flash-lite-preview-09-2025",
        "gateway/google:gemini-2.5-flash-lite",
        "gateway/google:gemini-2.5-flash",
        "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-0125",
        "gateway/openai:gpt-3.5-turbo-1106",
        "gateway/openai:gpt-3.5-turbo-16k",
        "gateway/openai:gpt-3.5-turbo",
        "gateway/openai:gpt-4-0613",
        "gateway/openai:gpt-4-turbo-2024-04-09",
        "gateway/openai:gpt-4-turbo",
        "gateway/openai:gpt-4.1-2025-04-14",
        "gateway/openai:gpt-4.1-mini-2025-04-14",
        "gateway/openai:gpt-4.1-mini",
        "gateway/openai:gpt-4.1-nano-2025-04-14",
        "gateway/openai:gpt-4.1-nano",
        "gateway/openai:gpt-4.1",
        "gateway/openai:gpt-4",
        "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-2024-07-18",
        "gateway/openai:gpt-4o-mini-search-preview-2025-03-11",
        "gateway/openai:gpt-4o-mini-search-preview",
        "gateway/openai:gpt-4o-mini",
        "gateway/openai:gpt-4o-search-preview-2025-03-11",
        "gateway/openai:gpt-4o-search-preview",
        "gateway/openai:gpt-4o",
        "gateway/openai:gpt-5-2025-08-07",
        "gateway/openai:gpt-5-chat-latest",
        "gateway/openai:gpt-5-mini-2025-08-07",
        "gateway/openai:gpt-5-mini",
        "gateway/openai:gpt-5-nano-2025-08-07",
        "gateway/openai:gpt-5-nano",
        "gateway/openai:gpt-5.1-2025-11-13",
        "gateway/openai:gpt-5.1-chat-latest",
        "gateway/openai:gpt-5.1",
        "gateway/openai:gpt-5.2-2025-12-11",
        "gateway/openai:gpt-5.2-chat-latest",
        "gateway/openai:gpt-5.2",
        "gateway/openai:gpt-5.4-mini-2026-03-17",
        "gateway/openai:gpt-5.4-mini",
        "gateway/openai:gpt-5.4-nano-2026-03-17",
        "gateway/openai:gpt-5.4-nano",
        "gateway/openai:gpt-5.4",
        "gateway/openai:gpt-5",
        "gateway/openai:o1-2024-12-17",
        "gateway/openai:o1",
        "gateway/openai:o3-2025-04-16",
        "gateway/openai:o3-mini-2025-01-31",
        "gateway/openai:o3-mini",
        "gateway/openai:o3",
        "gateway/openai:o4-mini-2025-04-16",
        "gateway/openai:o4-mini",
        "google-cloud:gemini-2.0-flash-lite",
        "google-cloud:gemini-2.0-flash",
        "google-cloud:gemini-2.5-flash-image",
        "google-cloud:gemini-2.5-flash-lite-preview-09-2025",
        "google-cloud:gemini-2.5-flash-lite",
        "google-cloud:gemini-2.5-flash-preview-09-2025",
        "google-cloud:gemini-2.5-flash",
        "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-lite",
        "google:gemini-2.0-flash",
        "google:gemini-2.5-flash-image",
        "google:gemini-2.5-flash-lite-preview-09-2025",
        "google:gemini-2.5-flash-lite",
        "google:gemini-2.5-flash-preview-09-2025",
        "google:gemini-2.5-flash",
        "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",
        "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-code-fast-1",
        "groq:llama-3.1-8b-instant",
        "groq:llama-3.3-70b-versatile",
        "groq:meta-llama/llama-guard-4-12b",
        "groq:openai/gpt-oss-120b",
        "groq:openai/gpt-oss-20b",
        "groq:whisper-large-v3",
        "groq:whisper-large-v3-turbo",
        "groq:meta-llama/llama-4-maverick-17b-128e-instruct",
        "groq:meta-llama/llama-4-scout-17b-16e-instruct",
        "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-safeguard-20b",
        "groq:playai-tts",
        "groq:playai-tts-arabic",
        "groq:qwen/qwen-3-32b",
        "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:qwen3-235b",
        "heroku:qwen3-coder-480b",
        "heroku:nova-2-lite",
        "heroku:nova-lite",
        "heroku:nova-pro",
        "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",
        "huggingface:Qwen/Qwen2.5-72B-Instruct",
        "huggingface:Qwen/Qwen3-235B-A22B",
        "huggingface:Qwen/Qwen3-32B",
        "huggingface:Qwen/QwQ-32B",
        "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-vision-preview",
        "moonshotai:moonshot-v1-128k",
        "moonshotai:moonshot-v1-32k-vision-preview",
        "moonshotai:moonshot-v1-32k",
        "moonshotai:moonshot-v1-8k-vision-preview",
        "moonshotai:moonshot-v1-8k",
        "openai:computer-use-preview-2025-03-11",
        "openai:computer-use-preview",
        "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-0613",
        "openai:gpt-3.5-turbo-16k",
        "openai:gpt-3.5-turbo",
        "openai:gpt-4-0314",
        "openai:gpt-4-0613",
        "openai:gpt-4-turbo-2024-04-09",
        "openai:gpt-4-turbo",
        "openai:gpt-4.1-2025-04-14",
        "openai:gpt-4.1-mini-2025-04-14",
        "openai:gpt-4.1-mini",
        "openai:gpt-4.1-nano-2025-04-14",
        "openai:gpt-4.1-nano",
        "openai:gpt-4.1",
        "openai:gpt-4",
        "openai:gpt-4o-2024-05-13",
        "openai:gpt-4o-2024-08-06",
        "openai:gpt-4o-2024-11-20",
        "openai:gpt-4o-audio-preview-2024-12-17",
        "openai:gpt-4o-audio-preview-2025-06-03",
        "openai:gpt-4o-audio-preview",
        "openai:gpt-4o-mini-2024-07-18",
        "openai:gpt-4o-mini-audio-preview-2024-12-17",
        "openai:gpt-4o-mini-audio-preview",
        "openai:gpt-4o-mini-search-preview-2025-03-11",
        "openai:gpt-4o-mini-search-preview",
        "openai:gpt-4o-mini",
        "openai:gpt-4o-search-preview-2025-03-11",
        "openai:gpt-4o-search-preview",
        "openai:gpt-4o",
        "openai:gpt-5-2025-08-07",
        "openai:gpt-5-chat-latest",
        "openai:gpt-5-codex",
        "openai:gpt-5-mini-2025-08-07",
        "openai:gpt-5-mini",
        "openai:gpt-5-nano-2025-08-07",
        "openai:gpt-5-nano",
        "openai:gpt-5-pro-2025-10-06",
        "openai:gpt-5-pro",
        "openai:gpt-5.1-2025-11-13",
        "openai:gpt-5.1-chat-latest",
        "openai:gpt-5.1-codex-max",
        "openai:gpt-5.1-codex",
        "openai:gpt-5.1",
        "openai:gpt-5.2-2025-12-11",
        "openai:gpt-5.2-chat-latest",
        "openai:gpt-5.2-pro-2025-12-11",
        "openai:gpt-5.2-pro",
        "openai:gpt-5.2",
        "openai:gpt-5.3-chat-latest",
        "openai:gpt-5.4-mini-2026-03-17",
        "openai:gpt-5.4-mini",
        "openai:gpt-5.4-nano-2026-03-17",
        "openai:gpt-5.4-nano",
        "openai:gpt-5.4",
        "openai:gpt-5",
        "openai:o1-2024-12-17",
        "openai:o1-pro-2025-03-19",
        "openai:o1-pro",
        "openai:o1",
        "openai:o3-2025-04-16",
        "openai:o3-deep-research-2025-06-26",
        "openai:o3-deep-research",
        "openai:o3-mini-2025-01-31",
        "openai:o3-mini",
        "openai:o3-pro-2025-06-10",
        "openai:o3-pro",
        "openai:o3",
        "openai:o4-mini-2025-04-16",
        "openai:o4-mini-deep-research-2025-06-26",
        "openai:o4-mini-deep-research",
        "openai:o4-mini",
        "openai-chat:computer-use-preview-2025-03-11",
        "openai-chat:computer-use-preview",
        "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-0613",
        "openai-chat:gpt-3.5-turbo-16k",
        "openai-chat:gpt-3.5-turbo",
        "openai-chat:gpt-4-0314",
        "openai-chat:gpt-4-0613",
        "openai-chat:gpt-4-turbo-2024-04-09",
        "openai-chat:gpt-4-turbo",
        "openai-chat:gpt-4.1-2025-04-14",
        "openai-chat:gpt-4.1-mini-2025-04-14",
        "openai-chat:gpt-4.1-mini",
        "openai-chat:gpt-4.1-nano-2025-04-14",
        "openai-chat:gpt-4.1-nano",
        "openai-chat:gpt-4.1",
        "openai-chat:gpt-4",
        "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-2024-12-17",
        "openai-chat:gpt-4o-audio-preview-2025-06-03",
        "openai-chat:gpt-4o-audio-preview",
        "openai-chat:gpt-4o-mini-2024-07-18",
        "openai-chat:gpt-4o-mini-audio-preview-2024-12-17",
        "openai-chat:gpt-4o-mini-audio-preview",
        "openai-chat:gpt-4o-mini-search-preview-2025-03-11",
        "openai-chat:gpt-4o-mini-search-preview",
        "openai-chat:gpt-4o-mini",
        "openai-chat:gpt-4o-search-preview-2025-03-11",
        "openai-chat:gpt-4o-search-preview",
        "openai-chat:gpt-4o",
        "openai-chat:gpt-5-2025-08-07",
        "openai-chat:gpt-5-chat-latest",
        "openai-chat:gpt-5-codex",
        "openai-chat:gpt-5-mini-2025-08-07",
        "openai-chat:gpt-5-mini",
        "openai-chat:gpt-5-nano-2025-08-07",
        "openai-chat:gpt-5-nano",
        "openai-chat:gpt-5-pro-2025-10-06",
        "openai-chat:gpt-5-pro",
        "openai-chat:gpt-5.1-2025-11-13",
        "openai-chat:gpt-5.1-chat-latest",
        "openai-chat:gpt-5.1-codex-max",
        "openai-chat:gpt-5.1-codex",
        "openai-chat:gpt-5.1",
        "openai-chat:gpt-5.2-2025-12-11",
        "openai-chat:gpt-5.2-chat-latest",
        "openai-chat:gpt-5.2-pro-2025-12-11",
        "openai-chat:gpt-5.2-pro",
        "openai-chat:gpt-5.2",
        "openai-chat:gpt-5.3-chat-latest",
        "openai-chat:gpt-5.4-mini-2026-03-17",
        "openai-chat:gpt-5.4-mini",
        "openai-chat:gpt-5.4-nano-2026-03-17",
        "openai-chat:gpt-5.4-nano",
        "openai-chat:gpt-5.4",
        "openai-chat:gpt-5",
        "openai-chat:o1-2024-12-17",
        "openai-chat:o1-pro-2025-03-19",
        "openai-chat:o1-pro",
        "openai-chat:o1",
        "openai-chat:o3-2025-04-16",
        "openai-chat:o3-deep-research-2025-06-26",
        "openai-chat:o3-deep-research",
        "openai-chat:o3-mini-2025-01-31",
        "openai-chat:o3-mini",
        "openai-chat:o3-pro-2025-06-10",
        "openai-chat:o3-pro",
        "openai-chat:o3",
        "openai-chat:o4-mini-2025-04-16",
        "openai-chat:o4-mini-deep-research-2025-06-26",
        "openai-chat:o4-mini-deep-research",
        "openai-chat:o4-mini",
        "test",
    ],
)

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

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

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 
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
@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 
620
621
622
623
624
625
626
627
628
629
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 
 648
 649
 650
 651
 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
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
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,
    ) -> AsyncIterator[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`.

        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

            return synthesize_local_tool_search_messages(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).'
            )

        function_tools: list[ToolDefinition] = []
        for t in params.function_tools:
            # Rule 1: drop local fallback when the native tool is supported.
            if t.unless_native and t.unless_native in supported_ids:
                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 
655
656
657
658
659
660
661
662
663
664
665
666
667
668
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 
675
676
677
678
679
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 
681
682
683
684
685
686
687
688
689
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 
696
697
698
699
700
701
702
703
704
705
706
707
@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 
709
710
711
712
713
714
715
716
717
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 
719
720
721
722
723
724
725
726
727
728
729
730
731
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,
) -> AsyncIterator[StreamedResponse]

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

Source code in pydantic_ai_slim/pydantic_ai/models/__init__.py 
733
734
735
736
737
738
739
740
741
742
743
744
745
746
@asynccontextmanager
async def request_stream(
    self,
    messages: list[ModelMessage],
    model_settings: ModelSettings | None,
    model_request_parameters: ModelRequestParameters,
    run_context: RunContext[Any] | None = None,
) -> AsyncIterator[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 
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
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 
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
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.

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 
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
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`.

    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

        return synthesize_local_tool_search_messages(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 
987
988
989
990
991
992
993
994
@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 
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
@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 
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
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 
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
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 
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
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 
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
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 
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
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 
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
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,
) -> Iterator[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 
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
@contextmanager
def override_allow_model_requests(allow_model_requests: bool) -> Iterator[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]