langfun 0.1.2.dev202509020804__py3-none-any.whl → 0.1.2.dev202511110805__py3-none-any.whl

langfun/core/component.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""langfun Component."""
+"""Base component for Langfun."""
 
 from typing import ContextManager
 import pyglove as pg
@@ -22,7 +22,37 @@ RAISE_IF_HAS_ERROR = (pg.MISSING_VALUE,)
 
 
 class Component(pg.ContextualObject):
-  """Base class for langfun components."""
+  """Base class for Langfun components.
+
+  Langfun components are context-aware symbolic objects powered by PyGlove.
+  (See [PyGlove basics](https://pyglove.readthedocs.io/en/latest/basics.html)
+  for more details).
+
+  **Context-awareness**
+
+  Langfun components can have contextual attributes using `lf.contextual`,
+  whose values can be provided or overridden via `lf.context` or
+  `lf.use_settings`.
+
+  Example:
+  ```python
+  import langfun as lf
+
+  class Bar(lf.Component):
+    y = lf.contextual(1)
+
+  class Foo(lf.Component):
+    x = lf.contextual(0)
+    bar = Bar()
+
+  f = Foo()
+  assert f.x == 0 and f.bar.y == 1
+
+  # `lf.context` overrides `lf.contextual` attributes.
+  with lf.context(x=10, y=20):
+    assert f.x == 10 and f.bar.y == 20
+  ```
+  """
 
   # Allow symbolic assignment, which invalidates the object and recomputes
   # states upon update.
@@ -78,6 +108,15 @@ def use_settings(
 ) -> ContextManager[dict[str, pg.utils.ContextualOverride]]:
   """Shortcut method for overriding component attributes.
 
+  Example:
+
+  ```
+  with lf.use_settings(
+      lm=lf.llms.Gpt35(),
+      temperature=0.0):
+    lf.query('who are you?')
+  ```
+
   Args:
     cascade: If True, this override will apply to both current scope and nested
       scope, meaning that this `lf.context` will take precedence over all
@@ -85,6 +124,6 @@ def use_settings(
     **settings: Key/values as override for component attributes.
 
   Returns:
-    A dict of attribute names to their contextual overrides.
+    A context manager for overriding settings.
   """
   return context(cascade=cascade, override_attrs=True, **settings)

langfun/core/concurrent.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Utility library for handling concurrency in langfun."""
+"""Utilities for concurrency in Langfun."""
 
 import abc
 import collections
@@ -97,7 +97,7 @@ class RetryError(RuntimeError):
 
 
 def with_retry(
-    func: Callable[[Any], Any],
+    func: Callable[..., Any],
     retry_on_errors: Union[
         Union[Type[BaseException], Tuple[Type[BaseException], str]],
         Sequence[Union[Type[BaseException], Tuple[Type[BaseException], str]]],
@@ -108,10 +108,25 @@ def with_retry(
     max_retry_interval: int = 300,
     seed: int | None = None,
 ) -> Callable[..., Any]:
-  """Derives a user function with retry on error.
+  """Decorator-like function to add retry mechanism to a function.
+
+  Example:
+
+  ```
+  def flaky_function():
+    if random.random() < 0.5:
+      raise ValueError('error')
+    return 1
+
+  reliable_function = lf.with_retry(
+      flaky_function,
+      retry_on_errors=ValueError,
+      max_attempts=3)
+  reliable_function()
+  ```
 
   Args:
-    func: A user function.
+    func: The function to add retry mechanism.
     retry_on_errors: A sequence of exception types or tuples of exception type
       and error messages (described in regular expression) as the desired
       exception types to retry.
@@ -128,8 +143,7 @@ def with_retry(
       determined based on current time.
 
   Returns:
-    A function with the same signature of the input function, with the retry
-    capability.
+    A function with the same signature of `func`, but with retry capability.
   """
 
   def _func(*args, **kwargs):
@@ -179,6 +193,24 @@ def concurrent_execute(
 ) -> list[Any]:
   """Executes a function concurrently under current component context.
 
+  `lf.concurrent_execute` applies a function to each item in an iterable of
+  inputs in parallel and returns a list of results in the same order as the
+  inputs. It is a convenient wrapper around `lf.concurrent_map` for synchronous
+  bulk processing.
+
+  **Example:**
+
+  ```python
+  import langfun as lf
+
+  def square(x):
+    return x ** 2
+
+  results = lf.concurrent_execute(square, [1, 2, 3, 4], max_workers=2)
+  print(results)
+  # Output: [1, 4, 9, 16]
+  ```
+
   Args:
     func: A user function.
     parallel_inputs: The inputs for `func` which will be processed in parallel.
@@ -649,6 +681,38 @@ def concurrent_map(
 ) -> Iterator[Any]:
   """Maps inputs to outptus via func concurrently under current context.
 
+  `lf.concurrent_map` applies a function to each item in an iterable of
+  inputs in parallel and yields `(input, output, error)` tuples as they are
+  completed. It supports features like ordered/unordered results, progress
+  bars, timeouts, and automatic retries for transient errors.
+
+  **Example:**
+
+  ```python
+  import langfun as lf
+  import time
+  import random
+
+  def flaky_square(x):
+    time.sleep(random.random())
+    if random.random() < 0.3:
+      raise ValueError("Flaky error")
+    return x ** 2
+
+  # Unordered execution with progress bar and retries
+  for input, output, error in lf.concurrent_map(
+      flaky_square,
+      range(10),
+      max_workers=3,
+      show_progress=True,
+      retry_on_errors=ValueError,
+      max_attempts=3):
+    if error:
+      print(f"Input {input} failed with error: {error}")
+    else:
+      print(f"Input {input} succeeded with output: {output}")
+  ```
+
   Args:
     func: A user function.
     parallel_inputs: The inputs for `func` which will be processed in parallel.

langfun/core/concurrent_test.py

@@ -262,6 +262,7 @@ class ProgressControlTest(unittest.TestCase):
     with contextlib.redirect_stderr(string_io):
       ctrl.update(1)
       ctrl.refresh()
+      sys.stderr.flush()
     self.assertEqual(string_io.getvalue(), '')
     concurrent.progress_bar = 'tqdm'
 
@@ -274,6 +275,7 @@ class ProgressControlTest(unittest.TestCase):
       ctrl.set_status('bar')
       ctrl.update(10)
       ctrl.refresh()
+      sys.stderr.flush()
     self.assertEqual(
         string_io.getvalue(),
         '\x1b[1m\x1b[31mfoo\x1b[0m: \x1b[34m10% (10/100)\x1b[0m : bar\n'
@@ -288,6 +290,7 @@ class ProgressControlTest(unittest.TestCase):
       self.assertIsInstance(ctrl, concurrent._TqdmProgressControl)
       ctrl.update(10)
       ctrl.refresh()
+      sys.stderr.flush()
     self.assertIn('10/100', string_io.getvalue())
 
     tqdm = concurrent.tqdm
@@ -316,6 +319,7 @@ class ProgressBarTest(unittest.TestCase):
       for _ in concurrent.concurrent_execute(fun, range(5)):
         concurrent.ProgressBar.refresh()
       concurrent.ProgressBar.uninstall(bar_id)
+      sys.stderr.flush()
     output_str = string_io.getvalue()
     self.assertIn('100%', output_str)
     self.assertIn('5/5', output_str)
@@ -332,7 +336,7 @@ class ProgressBarTest(unittest.TestCase):
         concurrent.ProgressBar.update(bar_id, 0, status=1)
       concurrent.ProgressBar.uninstall(bar_id)
       sys.stderr.flush()
-      time.sleep(1)
+    time.sleep(1)
     self.assertIn('1/4', string_io.getvalue())
     # TODO(daiyip): Re-enable once flakiness is fixed.
     # self.assertIn('2/4', string_io.getvalue())
@@ -564,7 +568,8 @@ class ConcurrentMapTest(unittest.TestCase):
               fun, [1, 2, 3], timeout=1.5, max_workers=1, show_progress=True
           )
       ], key=lambda x: x[0])
-      string_io.flush()
+      sys.stderr.flush()
+
     self.assertEqual(   # pylint: disable=g-generic-assert
         output,
         [
@@ -592,6 +597,7 @@ class ConcurrentMapTest(unittest.TestCase):
               show_progress=bar_id, status_fn=lambda p: dict(x=1, y=1)
           )
       ], key=lambda x: x[0])
+      sys.stderr.flush()
 
     self.assertEqual(  # pylint: disable=g-generic-assert
         output,
@@ -602,6 +608,7 @@ class ConcurrentMapTest(unittest.TestCase):
         ],
     )
     concurrent.ProgressBar.uninstall(bar_id)
+    concurrent.ProgressBar.refresh()
     self.assertIn('100%', string_io.getvalue())
 
 

langfun/core/console.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Console utilities."""
+"""Utilities for console output and notebook display."""
 
 import sys
 from typing import Any

langfun/core/data/conversion/anthropic.py

@@ -21,7 +21,14 @@ from langfun.core import modalities as lf_modalities
 
 
 class AnthropicMessageConverter(lf.MessageConverter):
-  """Converter to Anthropic public API."""
+  """Converter between Langfun messages and Anthropic API message format.
+
+  This converter translates `lf.Message` objects into the JSON format required
+  by the Anthropic API and vice versa. It handles text and modalities like
+  images and PDFs by encoding them in base64 format as expected by Anthropic.
+  An optional `chunk_preprocessor` can be provided to modify or filter
+  chunks before conversion.
+  """
 
   FORMAT_ID = 'anthropic'
 
@@ -30,12 +37,12 @@ class AnthropicMessageConverter(lf.MessageConverter):
       (
           'Chunk preprocessor for Langfun chunk to Anthropic 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
 
   def to_value(self, message: lf.Message) -> dict[str, Any]:
-    """Converts a Langfun message to Gemini API."""
+    """Converts a Langfun message to Anthropic API."""
     content = []
     for chunk in message.chunk():
       if self.chunk_preprocessor:
@@ -97,6 +104,8 @@ class AnthropicMessageConverter(lf.MessageConverter):
                 self._safe_read(source, 'media_type')
             ).from_bytes(base64.b64decode(self._safe_read(source, 'data')))
         )
+      elif t in ('server_tool_use', 'web_search_tool_result'):
+        continue
       else:
         raise ValueError(f'Unsupported content part: {part!r}.')
     message = message_cls.from_chunks(chunks)

langfun/core/data/conversion/anthropic_test.py

@@ -253,14 +253,16 @@ class AnthropicConversionTest(unittest.TestCase):
     )
     self.assertEqual(
         m.text,
-        'What are the common words from <<[[obj0]]>> and <<[[obj1]]>> ?'
+        'What are the common words from <<[[image:dc6e1e43]]>> and'
+        ' <<[[pdf:5daf5f31]]>> ?'
     )
-    self.assertIsInstance(m.obj0, lf_modalities.Image)
-    self.assertEqual(m.obj0.mime_type, 'image/png')
-    self.assertEqual(m.obj0.to_bytes(), image_content)
+    modalities = m.modalities()
+    self.assertIsInstance(modalities[0], lf_modalities.Image)
+    self.assertEqual(modalities[0].mime_type, 'image/png')
+    self.assertEqual(modalities[0].content, image_content)
 
-    self.assertIsInstance(m.obj1, lf_modalities.PDF)
-    self.assertEqual(m.obj1.to_bytes(), pdf_content)
+    self.assertIsInstance(modalities[1], lf_modalities.PDF)
+    self.assertEqual(modalities[1].content, pdf_content)
 
 
 if __name__ == '__main__':

langfun/core/data/conversion/gemini.py

@@ -21,7 +21,14 @@ from langfun.core import modalities as lf_modalities
 
 
 class GeminiMessageConverter(lf.MessageConverter):
-  """Converter to Gemini public API."""
+  """Converter between Langfun messages and Gemini API message format.
+
+  This converter translates `lf.Message` objects into the JSON format required
+  by the public Gemini API (e.g., via Vertex AI or Google AI Studio) and
+  vice versa. It handles text and modalities like images, extracting thought
+  chunks if present. An optional `chunk_preprocessor` can be provided to
+  modify or filter chunks before conversion.
+  """
 
   FORMAT_ID = 'gemini'
 
@@ -30,7 +37,7 @@ class GeminiMessageConverter(lf.MessageConverter):
       (
           'Chunk preprocessor for Langfun chunk to Gemini 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
 

langfun/core/data/conversion/gemini_test.py

@@ -225,19 +225,22 @@ class GeminiConversionTest(unittest.TestCase):
     self.assertEqual(
         m.text,
         (
-            'What are the common words from <<[[obj0]]>> , <<[[obj1]]>> '
-            'and <<[[obj2]]>> ?'
+            'What are the common words from <<[[image:dc6e1e43]]>> , '
+            '<<[[pdf:4dc12e93]]>> and <<[[video:7e169565]]>> ?'
         )
     )
-    self.assertIsInstance(m.obj0, lf_modalities.Image)
-    self.assertEqual(m.obj0.mime_type, 'image/png')
-    self.assertEqual(m.obj0.to_bytes(), image_content)
+    self.assertIsInstance(m.modalities()[0], lf_modalities.Image)
+    self.assertEqual(m.modalities()[0].mime_type, 'image/png')
+    self.assertEqual(m.modalities()[0].to_bytes(), image_content)
 
-    self.assertIsInstance(m.obj1, lf_modalities.PDF)
-    self.assertEqual(m.obj1.uri, 'https://my.pdf')
+    self.assertIsInstance(m.modalities()[1], lf_modalities.PDF)
+    self.assertEqual(m.modalities()[1].uri, 'https://my.pdf')
 
-    self.assertIsInstance(m.obj2, lf_modalities.Video)
-    self.assertEqual(m.obj2.uri, 'https://www.youtube.com/watch?v=abcd')
+    self.assertIsInstance(m.modalities()[2], lf_modalities.Video)
+    self.assertEqual(
+        m.modalities()[2].uri,
+        'https://www.youtube.com/watch?v=abcd'
+    )
 
 
 if __name__ == '__main__':

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
+)