langfun 0.1.2.dev202509120804__py3-none-any.whl → 0.1.2.dev202512150805__py3-none-any.whl

langfun/core/data/conversion/openai.py

@@ -19,17 +19,25 @@ import langfun.core as lf
 from langfun.core import modalities as lf_modalities
 
 
-class OpenAIMessageConverter(lf.MessageConverter):
-  """Converter to OpenAI API."""
+class OpenAIChatCompletionAPIMessageConverter(lf.MessageConverter):
+  """Converter for OpenAI Chat Completion API.
 
-  FORMAT_ID = 'openai'
+  This converter translates `lf.Message` objects into the JSON format
+  required by the OpenAI Chat Completions API
+  (https://platform.openai.com/docs/api-reference/chat) and vice versa.
+  It handles text and image modalities, mapping Langfun roles to OpenAI
+  roles ('system', 'user', 'assistant'). An optional `chunk_preprocessor`
+  can be provided to modify or filter chunks before conversion.
+  """
+
+  FORMAT_ID = 'openai_chat_completion_api'
 
   chunk_preprocessor: Annotated[
       Callable[[str | lf.Modality], Any] | None,
       (
           'Chunk preprocessor for Langfun chunk to OpenAI chunk conversion. '
           'It will be applied before each Langfun chunk is converted. '
-          'If returns None, the chunk will be skipped.'
+          'If it returns None, the chunk will be skipped.'
       )
   ] = None
 
@@ -41,22 +49,29 @@ class OpenAIMessageConverter(lf.MessageConverter):
         chunk = self.chunk_preprocessor(chunk)
         if chunk is None:
           continue
-
-      if isinstance(chunk, str):
-        item = dict(type='text', text=chunk)
-      elif isinstance(chunk, lf_modalities.Image):
-        item = dict(
-            type='image_url', image_url=dict(url=chunk.embeddable_uri)
-        )
-      # TODO(daiyip): Support audio_input.
-      else:
-        raise ValueError(f'Unsupported content type: {chunk!r}.')
-      parts.append(item)
+      parts.append(self.chunk_to_json(type(message), chunk))
     return dict(
         role=self.get_role(message),
         content=parts,
     )
 
+  def chunk_to_json(
+      self,
+      message_cls: type[lf.Message],
+      chunk: str | lf.Modality
+  ) -> dict[str, Any]:
+    """Converts a Langfun chunk to OpenAI chunk."""
+    del message_cls
+    if isinstance(chunk, str):
+      return dict(type='text', text=chunk)
+    elif isinstance(chunk, lf_modalities.Image):
+      return dict(
+          type='image_url', image_url=dict(url=chunk.embeddable_uri)
+      )
+    # TODO(daiyip): Support audio_input.
+    else:
+      raise ValueError(f'Unsupported content type: {chunk!r}.')
+
   def get_role(self, message: lf.Message) -> str:
     """Returns the role of the message."""
     if isinstance(message, lf.SystemMessage):
@@ -92,40 +107,139 @@ class OpenAIMessageConverter(lf.MessageConverter):
     assert isinstance(content, list)
     chunks = []
     for item in content:
-      t = self._safe_read(item, 'type')
-      if t == 'text':
-        chunk = self._safe_read(item, 'text')
-      elif t == 'image_url':
-        chunk = lf_modalities.Image.from_uri(
-            self._safe_read(self._safe_read(item, 'image_url'), 'url')
-        )
-      else:
-        raise ValueError(f'Unsupported content type: {item!r}.')
-      chunks.append(chunk)
+      chunks.append(self.json_to_chunk(item))
     return message_cls.from_chunks(chunks)
 
+  def json_to_chunk(self, json: dict[str, Any]) -> str | lf.Modality:
+    """Returns a Langfun chunk from OpenAI chunk JSON."""
+    t = self._safe_read(json, 'type')
+    if t == 'text':
+      return self._safe_read(json, 'text')
+    elif t == 'image_url':
+      return lf_modalities.Image.from_uri(
+          self._safe_read(self._safe_read(json, 'image_url'), 'url')
+      )
+    else:
+      raise ValueError(f'Unsupported content type: {json!r}.')
+
 
-def _as_openai_format(
+def _as_openai_chat_completion_api_format(
     self,
     chunk_preprocessor: Callable[[str | lf.Modality], Any] | None = None,
     **kwargs
 ) -> dict[str, Any]:
   """Returns an OpenAI format message."""
-  return OpenAIMessageConverter(
+  return OpenAIChatCompletionAPIMessageConverter(
       chunk_preprocessor=chunk_preprocessor, **kwargs
   ).to_value(self)
 
 
 @classmethod
-def _from_openai_format(
+def _from_openai_chat_completion_api_format(
     cls,
     openai_message: dict[str, Any],
     **kwargs
 ) -> lf.Message:
   """Creates a Langfun message from the OpenAI format message."""
   del cls
-  return OpenAIMessageConverter(**kwargs).from_value(openai_message)
+  return OpenAIChatCompletionAPIMessageConverter(
+      **kwargs
+  ).from_value(openai_message)
 
 # Set shortcut methods in lf.Message.
-lf.Message.as_openai_format = _as_openai_format
-lf.Message.from_openai_format = _from_openai_format
+lf.Message.as_openai_chat_completion_api_format = (
+    _as_openai_chat_completion_api_format
+)
+
+lf.Message.from_openai_chat_completion_api_format = (
+    _from_openai_chat_completion_api_format
+)
+
+
+#
+# OpenAI Responses API message converter.
+#
+
+
+class OpenAIResponsesAPIMessageConverter(
+    OpenAIChatCompletionAPIMessageConverter
+):
+  """Converter for OpenAI Responses API.
+
+  This converter translates `lf.Message` objects into the JSON format
+  required by the OpenAI Responses API
+  (https://platform.openai.com/docs/api-reference/responses/create),
+  which is used for human-in-the-loop rating, and vice versa.
+  It extends `OpenAIChatCompletionAPIMessageConverter` but uses different
+  type names for content chunks (e.g., 'input_text', 'output_image').
+  """
+
+  FORMAT_ID = 'openai_responses_api'
+
+  def to_value(self, message: lf.Message) -> dict[str, Any]:
+    """Converts a Langfun message to OpenAI API."""
+    message_json = super().to_value(message)
+    message_json['type'] = 'message'
+    return message_json
+
+  def chunk_to_json(
+      self,
+      message_cls: type[lf.Message],
+      chunk: str | lf.Modality
+  ) -> dict[str, Any]:
+    """Converts a Langfun chunk to OpenAI chunk."""
+    source = 'output' if issubclass(message_cls, lf.AIMessage) else 'input'
+
+    if isinstance(chunk, str):
+      return dict(type=f'{source}_text', text=chunk)
+    elif isinstance(chunk, lf_modalities.Image):
+      return dict(
+          type=f'{source}_image', image_url=chunk.embeddable_uri
+      )
+    # TODO(daiyip): Support audio_input.
+    else:
+      raise ValueError(f'Unsupported content type: {chunk!r}.')
+
+  def json_to_chunk(self, json: dict[str, Any]) -> str | lf.Modality:
+    """Returns a Langfun chunk from OpenAI chunk JSON."""
+    t = self._safe_read(json, 'type')
+    if t in ('input_text', 'output_text'):
+      return self._safe_read(json, 'text')
+    elif t in ('input_image', 'output_image'):
+      return lf_modalities.Image.from_uri(self._safe_read(json, 'image_url'))
+    else:
+      raise ValueError(f'Unsupported content type: {json!r}.')
+
+
+def _as_openai_responses_api_format(
+    self,
+    chunk_preprocessor: Callable[[str | lf.Modality], Any] | None = None,
+    **kwargs
+) -> dict[str, Any]:
+  """Returns an OpenAI format message."""
+  return OpenAIResponsesAPIMessageConverter(
+      chunk_preprocessor=chunk_preprocessor, **kwargs
+  ).to_value(self)
+
+
+@classmethod
+def _from_openai_responses_api_format(
+    cls,
+    openai_message: dict[str, Any],
+    **kwargs
+) -> lf.Message:
+  """Creates a Langfun message from the OpenAI format message."""
+  del cls
+  return OpenAIResponsesAPIMessageConverter(
+      **kwargs
+  ).from_value(openai_message)
+
+
+# Set shortcut methods in lf.Message.
+lf.Message.as_openai_responses_api_format = (
+    _as_openai_responses_api_format
+)
+
+lf.Message.from_openai_responses_api_format = (
+    _from_openai_responses_api_format
+)

langfun/core/data/conversion/openai_test.py

@@ -30,25 +30,25 @@ image_content = (
 )
 
 
-class OpenAIConversionTest(unittest.TestCase):
+class OpenAIChatCompletionAPIConverterTest(unittest.TestCase):
 
   def test_as_format_with_role(self):
     self.assertEqual(
-        lf.UserMessage('hi').as_format('openai'),
+        lf.UserMessage('hi').as_format('openai_chat_completion_api'),
         {
             'role': 'user',
             'content': [{'type': 'text', 'text': 'hi'}],
         },
     )
     self.assertEqual(
-        lf.AIMessage('hi').as_format('openai'),
+        lf.AIMessage('hi').as_format('openai_chat_completion_api'),
         {
             'role': 'assistant',
             'content': [{'type': 'text', 'text': 'hi'}],
         },
     )
     self.assertEqual(
-        lf.SystemMessage('hi').as_format('openai'),
+        lf.SystemMessage('hi').as_format('openai_chat_completion_api'),
         {
             'role': 'system',
             'content': [{'type': 'text', 'text': 'hi'}],
@@ -60,7 +60,7 @@ class OpenAIConversionTest(unittest.TestCase):
         lf.Template(
             'What is this {{image}}?',
             image=lf_modalities.Image.from_bytes(image_content)
-        ).render().as_format('openai'),
+        ).render().as_format('openai_chat_completion_api'),
         {
             'role': 'user',
             'content': [
@@ -90,7 +90,7 @@ class OpenAIConversionTest(unittest.TestCase):
         lf.Template(
             'What is this {{image}}?',
             image=lf_modalities.Image.from_bytes(image_content)
-        ).render().as_openai_format(
+        ).render().as_openai_chat_completion_api_format(
             chunk_preprocessor=lambda x: x if isinstance(x, str) else None
         ),
         {
@@ -114,7 +114,7 @@ class OpenAIConversionTest(unittest.TestCase):
             {
                 'content': 'this is a text',
             },
-            format='openai',
+            format='openai_chat_completion_api',
         ),
         lf.AIMessage('this is a text'),
     )
@@ -126,7 +126,7 @@ class OpenAIConversionTest(unittest.TestCase):
                 'role': 'user',
                 'content': [{'type': 'text', 'text': 'hi'}],
             },
-            format='openai',
+            format='openai_chat_completion_api',
         ),
         lf.UserMessage('hi'),
     )
@@ -136,7 +136,7 @@ class OpenAIConversionTest(unittest.TestCase):
                 'role': 'assistant',
                 'content': [{'type': 'text', 'text': 'hi'}],
             },
-            format='openai',
+            format='openai_chat_completion_api',
         ),
         lf.AIMessage('hi'),
     )
@@ -146,7 +146,7 @@ class OpenAIConversionTest(unittest.TestCase):
                 'role': 'system',
                 'content': [{'type': 'text', 'text': 'hi'}],
             },
-            format='openai',
+            format='openai_chat_completion_api',
         ),
         lf.SystemMessage('hi'),
     )
@@ -156,21 +156,165 @@ class OpenAIConversionTest(unittest.TestCase):
               'role': 'function',
               'content': [{'type': 'text', 'text': 'hi'}],
           },
-          format='openai',
+          format='openai_chat_completion_api',
       )
 
   def test_from_value_with_image(self):
-    m = lf.Message.from_openai_format(
+    image = lf_modalities.Image.from_bytes(image_content)
+    m = lf.Message.from_openai_chat_completion_api_format(
+        lf.Template(
+            'What is this {{image}}?',
+            image=image
+        ).render().as_format('openai_chat_completion_api'),
+    )
+    self.assertEqual(m.text, f'What is this <<[[{image.id}]]>> ?')
+    self.assertIsInstance(m.images[0], lf_modalities.Image)
+    self.assertEqual(m.images[0].mime_type, 'image/png')
+    self.assertEqual(m.images[0].to_bytes(), image_content)
+
+
+class OpenAIResponsesAPIMessageConverterTest(unittest.TestCase):
+
+  def test_as_format_with_role(self):
+    self.assertEqual(
+        lf.UserMessage('hi').as_format('openai_responses_api'),
+        {
+            'type': 'message',
+            'role': 'user',
+            'content': [{'type': 'input_text', 'text': 'hi'}],
+        },
+    )
+    self.assertEqual(
+        lf.AIMessage('hi').as_format('openai_responses_api'),
+        {
+            'type': 'message',
+            'role': 'assistant',
+            'content': [{'type': 'output_text', 'text': 'hi'}],
+        },
+    )
+    self.assertEqual(
+        lf.SystemMessage('hi').as_format('openai_responses_api'),
+        {
+            'type': 'message',
+            'role': 'system',
+            'content': [{'type': 'input_text', 'text': 'hi'}],
+        },
+    )
+
+  def test_as_format_with_image(self):
+    self.assertEqual(
         lf.Template(
             'What is this {{image}}?',
             image=lf_modalities.Image.from_bytes(image_content)
-        ).render().as_format('openai'),
+        ).render().as_format('openai_responses_api'),
+        {
+            'type': 'message',
+            'role': 'user',
+            'content': [
+                {
+                    'type': 'input_text',
+                    'text': 'What is this'
+                },
+                {
+                    'type': 'input_image',
+                    'image_url': (
+                        'data:image/png;base64,'
+                        + base64.b64encode(image_content).decode('utf-8')
+                    )
+                },
+                {
+                    'type': 'input_text',
+                    'text': '?'
+                }
+            ],
+        },
     )
-    self.assertEqual(m.text, 'What is this <<[[obj0]]>> ?')
-    self.assertIsInstance(m.obj0, lf_modalities.Image)
-    self.assertEqual(m.obj0.mime_type, 'image/png')
-    self.assertEqual(m.obj0.to_bytes(), image_content)
 
+  def test_as_format_with_chunk_preprocessor(self):
+    self.assertEqual(
+        lf.Template(
+            'What is this {{image}}?',
+            image=lf_modalities.Image.from_bytes(image_content)
+        ).render().as_openai_responses_api_format(
+            chunk_preprocessor=lambda x: x if isinstance(x, str) else None
+        ),
+        {
+            'type': 'message',
+            'role': 'user',
+            'content': [
+                {
+                    'type': 'input_text',
+                    'text': 'What is this'
+                },
+                {
+                    'type': 'input_text',
+                    'text': '?'
+                }
+            ],
+        },
+    )
+
+  def test_from_value_with_simple_text(self):
+    self.assertEqual(
+        lf.Message.from_value(
+            {
+                'content': 'this is a text',
+            },
+            format='openai_responses_api',
+        ),
+        lf.AIMessage('this is a text'),
+    )
+
+  def test_from_value_with_role(self):
+    self.assertEqual(
+        lf.Message.from_value(
+            {
+                'role': 'user',
+                'content': [{'type': 'input_text', 'text': 'hi'}],
+            },
+            format='openai_responses_api',
+        ),
+        lf.UserMessage('hi'),
+    )
+    self.assertEqual(
+        lf.Message.from_value(
+            {
+                'role': 'assistant',
+                'content': [{'type': 'output_text', 'text': 'hi'}],
+            },
+            format='openai_responses_api',
+        ),
+        lf.AIMessage('hi'),
+    )
+    self.assertEqual(
+        lf.Message.from_value(
+            {
+                'role': 'system',
+                'content': [{'type': 'input_text', 'text': 'hi'}],
+            },
+            format='openai_responses_api',
+        ),
+        lf.SystemMessage('hi'),
+    )
+    with self.assertRaisesRegex(ValueError, 'Unsupported role: .*'):
+      lf.Message.from_value(
+          {
+              'role': 'function',
+              'content': [{'type': 'input_text', 'text': 'hi'}],
+          },
+          format='openai_responses_api',
+      )
+
+  def test_from_value_with_image(self):
+    image = lf_modalities.Image.from_bytes(image_content)
+    m = lf.Message.from_openai_responses_api_format(
+        lf.Template(
+            'What is this {{image}}?', image=image
+        ).render().as_format('openai_responses_api'),
+    )
+    self.assertEqual(m.text, f'What is this <<[[{image.id}]]>> ?')
+    self.assertIsInstance(m.modalities()[0], lf_modalities.Image)
+    self.assertEqual(m.modalities()[0].content, image_content)
 
 if __name__ == '__main__':
   unittest.main()