Move system_prompt_role from OpenAIModel to OpenAIModelProfile (#2573)

Author: Kludex

pydantic_ai_slim/pydantic_ai/models/openai.py

@@ -9,7 +9,7 @@
 from typing import Any, Literal, Union, cast, overload
 
 from pydantic import ValidationError
-from typing_extensions import assert_never
+from typing_extensions import assert_never, deprecated
 
 from .. import ModelHTTPError, UnexpectedModelBehavior, _utils, usage
 from .._output import DEFAULT_OUTPUT_TOOL_NAME, OutputObjectDefinition
@@ -40,7 +40,7 @@
     VideoUrl,
 )
 from ..profiles import ModelProfile, ModelProfileSpec
-from ..profiles.openai import OpenAIModelProfile
+from ..profiles.openai import OpenAIModelProfile, OpenAISystemPromptRole
 from ..providers import Provider, infer_provider
 from ..settings import ModelSettings
 from ..tools import ToolDefinition
@@ -100,8 +100,6 @@
 allows this model to be used more easily with other model types (ie, Ollama, Deepseek).
 """
 
-OpenAISystemPromptRole = Literal['system', 'developer', 'user']
-
 
 class OpenAIModelSettings(ModelSettings, total=False):
     """Settings used for an OpenAI model request."""
@@ -196,11 +194,60 @@ class OpenAIModel(Model):
     """
 
     client: AsyncOpenAI = field(repr=False)
-    system_prompt_role: OpenAISystemPromptRole | None = field(default=None, repr=False)
 
     _model_name: OpenAIModelName = field(repr=False)
     _system: str = field(default='openai', repr=False)
 
+    @overload
+    def __init__(
+        self,
+        model_name: OpenAIModelName,
+        *,
+        provider: Literal[
+            'openai',
+            'deepseek',
+            'azure',
+            'openrouter',
+            'moonshotai',
+            'vercel',
+            'grok',
+            'fireworks',
+            'together',
+            'heroku',
+            'github',
+            'ollama',
+        ]
+        | Provider[AsyncOpenAI] = 'openai',
+        profile: ModelProfileSpec | None = None,
+        settings: ModelSettings | None = None,
+    ) -> None: ...
+
+    @deprecated('Set the `system_prompt_role` in the `OpenAIModelProfile` instead.')
+    @overload
+    def __init__(
+        self,
+        model_name: OpenAIModelName,
+        *,
+        provider: Literal[
+            'openai',
+            'deepseek',
+            'azure',
+            'openrouter',
+            'moonshotai',
+            'vercel',
+            'grok',
+            'fireworks',
+            'together',
+            'heroku',
+            'github',
+            'ollama',
+        ]
+        | Provider[AsyncOpenAI] = 'openai',
+        profile: ModelProfileSpec | None = None,
+        system_prompt_role: OpenAISystemPromptRole | None = None,
+        settings: ModelSettings | None = None,
+    ) -> None: ...
+
     def __init__(
         self,
         model_name: OpenAIModelName,
@@ -242,14 +289,20 @@ def __init__(
             provider = infer_provider(provider)
         self.client = provider.client
 
-        self.system_prompt_role = system_prompt_role
-
         super().__init__(settings=settings, profile=profile or provider.model_profile)
 
+        if system_prompt_role is not None:
+            self.profile = OpenAIModelProfile(openai_system_prompt_role=system_prompt_role).update(self.profile)
+
     @property
     def base_url(self) -> str:
         return str(self.client.base_url)
 
+    @property
+    @deprecated('Set the `system_prompt_role` in the `OpenAIModelProfile` instead.')
+    def system_prompt_role(self) -> OpenAISystemPromptRole | None:
+        return OpenAIModelProfile.from_profile(self.profile).openai_system_prompt_role
+
     async def request(
         self,
         messages: list[ModelMessage],
@@ -561,9 +614,10 @@ def _map_tool_definition(self, f: ToolDefinition) -> chat.ChatCompletionToolPara
     async def _map_user_message(self, message: ModelRequest) -> AsyncIterable[chat.ChatCompletionMessageParam]:
         for part in message.parts:
             if isinstance(part, SystemPromptPart):
-                if self.system_prompt_role == 'developer':
+                system_prompt_role = OpenAIModelProfile.from_profile(self.profile).openai_system_prompt_role
+                if system_prompt_role == 'developer':
                     yield chat.ChatCompletionDeveloperMessageParam(role='developer', content=part.content)
-                elif self.system_prompt_role == 'user':
+                elif system_prompt_role == 'user':
                     yield chat.ChatCompletionUserMessageParam(role='user', content=part.content)
                 else:
                     yield chat.ChatCompletionSystemMessageParam(role='system', content=part.content)
@@ -659,7 +713,6 @@ class OpenAIResponsesModel(Model):
     """
 
     client: AsyncOpenAI = field(repr=False)
-    system_prompt_role: OpenAISystemPromptRole | None = field(default=None)
 
     _model_name: OpenAIModelName = field(repr=False)
     _system: str = field(default='openai', repr=False)

pydantic_ai_slim/pydantic_ai/profiles/openai.py

@@ -2,11 +2,13 @@
 
 import re
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, Literal
 
 from . import ModelProfile
 from ._json_schema import JsonSchema, JsonSchemaTransformer
 
+OpenAISystemPromptRole = Literal['system', 'developer', 'user']
+
 
 @dataclass
 class OpenAIModelProfile(ModelProfile):
@@ -26,8 +28,10 @@ class OpenAIModelProfile(ModelProfile):
     # safe to pass that value along.  Default is `True` to preserve existing
     # behaviour for OpenAI itself and most providers.
     openai_supports_tool_choice_required: bool = True
-    """Whether the provider accepts the value ``tool_choice='required'`` in the
-    request payload."""
+    """Whether the provider accepts the value ``tool_choice='required'`` in the request payload."""
+
+    openai_system_prompt_role: OpenAISystemPromptRole | None = None
+    """The role to use for the system prompt message. If not provided, defaults to `'system'`."""
 
 
 def openai_model_profile(model_name: str) -> ModelProfile:
@@ -36,11 +40,17 @@ def openai_model_profile(model_name: str) -> ModelProfile:
     # Structured Outputs (output mode 'native') is only supported with the gpt-4o-mini, gpt-4o-mini-2024-07-18, and gpt-4o-2024-08-06 model snapshots and later.
     # We leave it in here for all models because the `default_structured_output_mode` is `'tool'`, so `native` is only used
     # when the user specifically uses the `NativeOutput` marker, so an error from the API is acceptable.
+
+    # The o1-mini model doesn't support the `system` role, so we default to `user`.
+    # See https://github.com/pydantic/pydantic-ai/issues/974 for more details.
+    openai_system_prompt_role = 'user' if model_name.startswith('o1-mini') else None
+
     return OpenAIModelProfile(
         json_schema_transformer=OpenAIJsonSchemaTransformer,
         supports_json_schema_output=True,
         supports_json_object_output=True,
         openai_supports_sampling_settings=not is_reasoning_model,
+        openai_system_prompt_role=openai_system_prompt_role,
     )
 
 

tests/models/cassettes/test_openai/test_system_prompt_role_o1_mini.yaml

@@ -0,0 +1,80 @@
+interactions:
+- request:
+    headers:
+      accept:
+      - application/json
+      accept-encoding:
+      - gzip, deflate
+      connection:
+      - keep-alive
+      content-length:
+      - '162'
+      content-type:
+      - application/json
+      host:
+      - api.openai.com
+    method: POST
+    parsed_body:
+      messages:
+      - content: You are a helpful assistant.
+        role: user
+      - content: What's the capital of France?
+        role: user
+      model: o1-mini
+      stream: false
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    headers:
+      access-control-expose-headers:
+      - X-Request-ID
+      alt-svc:
+      - h3=":443"; ma=86400
+      connection:
+      - keep-alive
+      content-length:
+      - '818'
+      content-type:
+      - application/json
+      openai-organization:
+      - pydantic-28gund
+      openai-processing-ms:
+      - '2319'
+      openai-project:
+      - proj_dKobscVY9YJxeEaDJen54e3d
+      openai-version:
+      - '2020-10-01'
+      strict-transport-security:
+      - max-age=31536000; includeSubDomains; preload
+      transfer-encoding:
+      - chunked
+    parsed_body:
+      choices:
+      - finish_reason: stop
+        index: 0
+        message:
+          annotations: []
+          content: The capital of France is **Paris**.
+          refusal: null
+          role: assistant
+      created: 1755256071
+      id: chatcmpl-C4mZjhnq5PQ6hDaKfMKb1WtXeSYzu
+      model: o1-mini-2024-09-12
+      object: chat.completion
+      service_tier: default
+      system_fingerprint: fp_79455e3cfb
+      usage:
+        completion_tokens: 212
+        completion_tokens_details:
+          accepted_prediction_tokens: 0
+          audio_tokens: 0
+          reasoning_tokens: 192
+          rejected_prediction_tokens: 0
+        prompt_tokens: 30
+        prompt_tokens_details:
+          audio_tokens: 0
+          cached_tokens: 0
+        total_tokens: 242
+    status:
+      code: 200
+      message: OK
+version: 1

tests/models/test_openai.py

@@ -673,6 +673,7 @@ async def test_no_delta(allow_model_requests: None):
         assert result.usage() == snapshot(RunUsage(requests=1, input_tokens=6, output_tokens=3))
 
 
+@pytest.mark.filterwarnings('ignore:Set the `system_prompt_role` in the `OpenAIModelProfile` instead.')
 @pytest.mark.parametrize('system_prompt_role', ['system', 'developer', 'user', None])
 async def test_system_prompt_role(
     allow_model_requests: None, system_prompt_role: OpenAISystemPromptRole | None
@@ -681,8 +682,8 @@ async def test_system_prompt_role(
 
     c = completion_message(ChatCompletionMessage(content='world', role='assistant'))
     mock_client = MockOpenAI.create_mock(c)
-    m = OpenAIModel('gpt-4o', system_prompt_role=system_prompt_role, provider=OpenAIProvider(openai_client=mock_client))
-    assert m.system_prompt_role == system_prompt_role
+    m = OpenAIModel('gpt-4o', system_prompt_role=system_prompt_role, provider=OpenAIProvider(openai_client=mock_client))  # type: ignore[reportDeprecated]
+    assert m.system_prompt_role == system_prompt_role  # type: ignore[reportDeprecated]
 
     agent = Agent(m, system_prompt='some instructions')
     result = await agent.run('hello')
@@ -701,13 +702,31 @@ async def test_system_prompt_role(
     ]
 
 
+async def test_system_prompt_role_o1_mini(allow_model_requests: None, openai_api_key: str):
+    model = OpenAIModel('o1-mini', provider=OpenAIProvider(api_key=openai_api_key))
+    agent = Agent(model=model, system_prompt='You are a helpful assistant.')
+
+    result = await agent.run("What's the capital of France?")
+    assert result.output == snapshot('The capital of France is **Paris**.')
+
+
+async def test_openai_pass_custom_system_prompt_role(allow_model_requests: None, openai_api_key: str):
+    profile = ModelProfile(supports_tools=False)
+    model = OpenAIModel(  # type: ignore[reportDeprecated]
+        'o1-mini', profile=profile, provider=OpenAIProvider(api_key=openai_api_key), system_prompt_role='user'
+    )
+    profile = OpenAIModelProfile.from_profile(model.profile)
+    assert profile.openai_system_prompt_role == 'user'
+    assert profile.supports_tools is False
+
+
 @pytest.mark.parametrize('system_prompt_role', ['system', 'developer'])
 async def test_openai_o1_mini_system_role(
     allow_model_requests: None,
     system_prompt_role: Literal['system', 'developer'],
     openai_api_key: str,
 ) -> None:
-    model = OpenAIModel(
+    model = OpenAIModel(  # type: ignore[reportDeprecated]
         'o1-mini', provider=OpenAIProvider(api_key=openai_api_key), system_prompt_role=system_prompt_role
     )
     agent = Agent(model=model, system_prompt='You are a helpful assistant.')