langfun 0.1.2.dev202510230805__py3-none-any.whl → 0.1.2.dev202511160804__py3-none-any.whl

langfun/core/structured/completion_test.py

@@ -407,22 +407,17 @@ class CompleteStructureTest(unittest.TestCase):
       image: modalities.Image
       name: str
 
+    image_elephant = modalities.Image.from_bytes(b'image_of_elephant')
+    image_rabbit = modalities.Image.from_bytes(b'image_of_rabbit')
     input_value = schema_lib.mark_missing(
-        Animal.partial(
-            modalities.Image.from_bytes(b'image_of_elephant'),
-        )
+        Animal.partial(image_elephant)
     )
     l = completion._CompleteStructure(
         input=input_value,
         examples=[
             mapping.MappingExample(
-                input=Animal.partial(
-                    modalities.Image.from_bytes(b'image_of_rabbit')
-                ),
-                output=Animal(
-                    modalities.Image.from_bytes(b'image_of_rabbit'),
-                    'rabbit',
-                ),
+                input=Animal.partial(image_rabbit),
+                output=Animal(image_rabbit, 'rabbit'),
             )
         ],
     )
@@ -430,7 +425,7 @@ class CompleteStructureTest(unittest.TestCase):
     self.maxDiff = None
     self.assertEqual(
         lm_input.text,
-        inspect.cleandoc("""
+        inspect.cleandoc(f"""
             Please generate the OUTPUT_OBJECT by completing the MISSING fields from the last INPUT_OBJECT.
 
             INSTRUCTIONS:
@@ -457,22 +452,22 @@ class CompleteStructureTest(unittest.TestCase):
               ```python
               Animal(
                 image=ModalityRef(
-                  name='examples[0].input.image'
+                  id='{image_rabbit.id}'
                 ),
                 name=MISSING(str)
               )
               ```
 
             MODALITY_REFERENCES:
-              {
-                'examples[0].input.image': <<[[examples[0].input.image]]>>
-              }
+              {{
+                '{image_rabbit.id}': <<[[{image_rabbit.id}]]>>
+              }}
 
             OUTPUT_OBJECT:
               ```python
               Animal(
                 image=ModalityRef(
-                  name='examples[0].output.image'
+                  id='{image_rabbit.id}'
                 ),
                 name='rabbit'
               )
@@ -483,16 +478,16 @@ class CompleteStructureTest(unittest.TestCase):
               ```python
               Animal(
                 image=ModalityRef(
-                  name='input.image'
+                  id='{image_elephant.id}'
                 ),
                 name=MISSING(str)
               )
               ```
 
             MODALITY_REFERENCES:
-              {
-                'input.image': <<[[input.image]]>>
-              }
+              {{
+                '{image_elephant.id}': <<[[{image_elephant.id}]]>>
+              }}
 
             OUTPUT_OBJECT:
             """),
@@ -500,39 +495,27 @@ class CompleteStructureTest(unittest.TestCase):
     self.assertTrue(
         pg.eq(
             {
-                'examples': lm_input.get('examples'),
-                'input': lm_input.get('input'),
+                'examples': lm_input.__template_input__.examples,
+                'input': lm_input.__template_input__.mapping_request.input,
             },
             {
                 'examples': [
                     mapping.MappingExample(
-                        input=Animal.partial(
-                            image=modalities.Image.from_bytes(
-                                b'image_of_rabbit'
-                            )
-                        ),
-                        output=Animal.partial(
-                            image=modalities.Image.from_bytes(
-                                b'image_of_rabbit'
-                            ),
-                            name='rabbit',
-                        ),
+                        input=Animal.partial(image_rabbit),
+                        output=Animal.partial(image_rabbit, 'rabbit'),
                     )
                 ],
-                'input': Animal(
-                    image=modalities.Image.from_bytes(b'image_of_elephant'),
-                    name=schema_lib.MISSING,
-                ),
+                'input': Animal(image_elephant, name=schema_lib.MISSING),
             },
         )
     )
     lm_output = l(
         input=input_value,
-        lm=fake.StaticResponse(inspect.cleandoc("""
+        lm=fake.StaticResponse(inspect.cleandoc(f"""
             ```python
             Animal(
               image=ModalityRef(
-                name='input.image'
+                id='{image_elephant.id}'
               ),
               name='elephant'
             )
@@ -542,10 +525,7 @@ class CompleteStructureTest(unittest.TestCase):
     self.assertTrue(
         pg.eq(
             lm_output.result,
-            Animal(
-                image=modalities.Image.from_bytes(b'image_of_elephant'),
-                name='elephant',
-            ),
+            Animal(image=image_elephant, name='elephant'),
         )
     )
 

langfun/core/structured/description.py

@@ -23,7 +23,7 @@ import pyglove as pg
 
 @pg.use_init_args(['examples'])
 class _DescribeStructure(mapping.Mapping):
-  """Describe a structured value in natural language."""
+  """Describes a structured value in natural language."""
 
   input_title = 'PYTHON_OBJECT'
   context_title = 'CONTEXT_FOR_DESCRIPTION'
@@ -47,64 +47,68 @@ def describe(
     cache_seed: int | None = 0,
     **kwargs,
 ) -> str:
-  """Describes a structured value using natural language.
-
-  Examples:
-
-    ```
-    class FlightDuration(pg.Object):
-      hours: int
-      minutes: int
-
-    class Flight(pg.Object):
-      airline: str
-      flight_number: str
-      departure_airport: str
-      arrival_airport: str
-      departure_time: str
-      arrival_time: str
-      duration: FlightDuration
-      stops: int
-      price: float
-
-    text = lf.describe(
-        Flight(
-            airline='United Airlines',
-            flight_number='UA2631',
-            depature_airport: 'SFO',
-            arrival_airport: 'JFK',
-            depature_time: '2023-09-07T05:15:00',
-            arrival_time: '2023-09-07T12:12:00',
-            duration: FlightDuration(
-                hours=7,
-                minutes=57
-            ),
-            stops=1,
-            price=227,
-        ))
-    print(text)
-
-    >> The flight is operated by United Airlines, has the flight number UA2631,
-    >> departs from San Francisco International Airport (SFO), arrives at John
-    >> F. Kennedy International Airport (JFK), It departs at
-    >> 2023-09-07T05:15:00, arrives at 2023-09-07T12:12:00, has a duration of 7
-    >> hours and 57 minutes, makes 1 stop, and costs $227.
-    ```
+  """Describes a structured value in natural language using an LLM.
+
+  `lf.describe` takes a Python object, often a `pg.Object` instance,
+  and uses a language model to generate a human-readable, natural language
+  description of its content. It is the inverse of `lf.parse`.
+
+  **Example:**
+
+  ```python
+  import langfun as lf
+  import pyglove as pg
+
+  class FlightDuration(pg.Object):
+    hours: int
+    minutes: int
+
+  class Flight(pg.Object):
+    airline: str
+    flight_number: str
+    departure_airport: str
+    arrival_airport: str
+    departure_time: str
+    arrival_time: str
+    duration: FlightDuration
+    stops: int
+    price: float
+
+  flight_info = Flight(
+      airline='United Airlines',
+      flight_number='UA2631',
+      departure_airport='SFO',
+      arrival_airport='JFK',
+      departure_time='2023-09-07T05:15:00',
+      arrival_time='2023-09-07T12:12:00',
+      duration=FlightDuration(hours=7, minutes=57),
+      stops=1,
+      price=227,
+  )
+
+  description = lf.describe(flight_info, lm=lf.llms.Gemini25Flash())
+  print(description)
+  # Possible output:
+  # The flight is operated by United Airlines, with the flight number UA2631,
+  # departing from SFO at 2023-09-07T05:15:00 and arriving at JFK at
+  # 2023-09-07T12:12:00. The flight duration is 7 hours and 57 minutes,
+  # with 1 stop, and costs $227.
+  ```
 
   Args:
     value: A structured value to be mapped.
     context: The context information for describing the structured value.
     lm: The language model to use. If not specified, the language model from
       `lf.context` context manager will be used.
-    examples: An optional list of fewshot examples for helping parsing. If None,
-      the default one-shot example will be added.
+    examples: An optional list of fewshot examples for guiding description.
+      If None, default examples will be used.
     cache_seed: Seed for computing cache key. The cache key is determined by a
       tuple of (lm, prompt, cache seed). If None, cache will be disabled for
       the query even cache is configured by the LM.
-    **kwargs: Keyword arguments passed to the `lf.structured.DescribeStructure`.
+    **kwargs: Keyword arguments passed to the `_DescribeStructure`.
 
   Returns:
-    The parsed result based on the schema.
+    A natural language description of the input value.
   """
   return _DescribeStructure(
       input=value,
@@ -115,10 +119,10 @@ def describe(
 
 
 def default_describe_examples() -> list[mapping.MappingExample]:
-  """Default describe examples."""
+  """Returns default examples for `lf.describe`."""
 
   class Country(pg.Object):
-    """A example dataclass for structured mapping."""
+    """An example dataclass for structured mapping."""
 
     name: str
     continents: list[

langfun/core/structured/function_generation.py

@@ -26,10 +26,10 @@ import pyglove as pg
 
 
 def unittest_gen(signature, lm, num_retries=1):
-  """Generates unit tests for a python function signature."""
+  """Generates unit tests for a Python function signature."""
 
   class UnitTest(pg.Object):
-    """A valid unit test for a python function."""
+    """A valid unit test for a Python function."""
 
     input: dict[str, Any]
     expected_output: Any
@@ -55,7 +55,7 @@ def unittest_gen(signature, lm, num_retries=1):
 
 
 def unittest_with_test_cases(f, unittests):
-  """Applies unit tests to a python function to be tested."""
+  """Applies unit tests to a Python function to be tested."""
   if not unittests:
     raise ValueError(f"No unit tests provided: {unittests}")
 
@@ -87,10 +87,10 @@ def _function_gen(
     ] = None,
     unittest_num_retries: int = 1,
 ):
-  """Generates a python function with LLM and verify its quality with unit testing."""
+  """Generates a Python function with LLM and verifies it with unit testing."""
 
   class PythonFunctionPrompt(template.Template):
-    r"""A template for a python function generation.
+    r"""A template for a Python function generation.
 
     Please reply to the last PYTHON_FUNCTION_SIGNATURE with a self-sufficient,
     error-free, and efficiently coded PYTHON_FUNCTION, crafted to the standards
@@ -195,11 +195,28 @@ def function_gen(
     ] = None,
     unittest_num_retries: int = 1,
 ):
-  """A decorator for automating function generation using a language model.
+  r"""Decorator for generating function implementations using an LLM.
 
-  This decorator should be applied to functions that are not yet implemented. It
-  facilitates the implementation via the specified LLM, ensuring
-  quality through unit tests.
+  `lf.function_gen` is a decorator that automatically generates the
+  implementation of a Python function based on its signature and docstring,
+  using the specified language model. This is useful for quickly prototyping
+  functions or generating boilerplate code.
+
+  The decorator can also automatically generate and run unit tests to verify
+  the correctness of the generated implementation.
+
+  **Example:**
+
+  ```python
+  import langfun as lf
+
+  @lf.function_gen(lm=lf.llms.Gemini25Flash())
+  def product(a: int, b: int) -> int:
+    \"\"\"Returns product of a and b.\"\"\"
+
+  print(product(2, 3))
+  # Output: 6
+  ```
 
   Args:
       lm (lf.LanguageModel): The language model used for generating function
@@ -212,10 +229,10 @@ def function_gen(
         tests. You can either provide a list of test cases as tuples of inputs
         and outputs, or a function that throws an error if a test fails, or let
         LLM automatically create the unit test cases. If a generated function is
-        and returned, it should pass all the unittests.
+        returned, it should pass all the unit tests.
       unittest_num_retries: If unittest is set to "auto", this parameter
-        specifies the number of times the LLM's attempts to generate unit test
-        cases.
+        specifies the number of times the LLM should attempt to generate unit
+        test cases.
 
   Returns:
       The implemented function object.

langfun/core/structured/mapping.py

@@ -22,7 +22,16 @@ import pyglove as pg
 
 
 class MappingError(Exception):  # pylint: disable=g-bad-exception-name
-  """Mapping error."""
+  """Error raised during a structured mapping task.
+
+  `MappingError` is raised when a language model's response cannot be
+  successfully parsed or transformed into the target structure defined by
+  the schema in structured mapping operations like `lf.query` and `lf.parse`.
+
+  This error encapsulates both the original exception that occurred during
+  parsing (`cause`) and the language model response (`lm_response`) that led
+  to the failure, allowing for easier debugging of mapping issues.
+  """
 
   def __init__(self, lm_response: lf.Message, cause: Exception):
     self._lm_response = lm_response
@@ -62,7 +71,53 @@ class MappingError(Exception):  # pylint: disable=g-bad-exception-name
 class MappingExample(lf.NaturalLanguageFormattable,
                      lf.Component,
                      pg.views.HtmlTreeView.Extension):
-  """Mapping example between text, schema and structured value."""
+  """Represents an example for a structured mapping task.
+
+  A `MappingExample` defines a single instance of a mapping between an input
+  value and an output value, optionally guided by a schema and/or a natural
+  language context. It is primarily used to provide few-shot examples to
+  structured mapping operations (e.g., `lf.query`, `lf.complete`,
+  and `lf.describe`), helping to guide the LLM in performing the desired mapping
+  task. If `output` is not provided, the example represents a request to perform
+  mapping on the `input`.
+
+  **Key Attributes:**
+
+  *   `input`: The source value for the mapping (e.g., text, an object).
+  *   `output`: The target value for the mapping (e.g., a structured object,
+      text). If not provided, this example represents a request to perform
+      the mapping.
+  *   `schema`: An optional `lf.structured.Schema` that defines or constrains
+      the structure of the `output`. If provided, the LLM will be instructed
+      to produce an output conforming to this schema.
+  *   `context`: Optional natural language context that provides additional
+      information relevant to the mapping task.
+  *   `metadata`: Optional dictionary for additional metadata.
+
+  **Example:**
+
+  ```python
+  import langfun as lf
+  import pyglove as pg
+
+  # Example for translating English to French
+  lf.MappingExample(
+      input="Hello",
+      output="Bonjour"
+  )
+
+  # Example for extracting structured data
+  class Flight(pg.Object):
+    airline: str
+    flight_number: str
+
+  lf.MappingExample(
+      input="I want to book flight AA123.",
+      output=Flight(airline="AA", flight_number="123"),
+      schema=Flight
+  )
+  ```
+  """
 
   input: pg.typing.Annotated[
       pg.typing.Any(transform=schema_lib.mark_missing),
@@ -84,7 +139,7 @@ class MappingExample(lf.NaturalLanguageFormattable,
       # Automatic conversion from annotation to schema.
       schema_lib.schema_spec(noneable=True),
       (
-          'A `lf.structured.Schema` object that constrains target value '
+          'A `lf.structured.Schema` object that constrains target value. '
           'If None, the target is expected to be a natural language-based '
           'response returned from LMs.'
       ),
@@ -99,18 +154,16 @@ class MappingExample(lf.NaturalLanguageFormattable,
       dict[str, Any],
       (
           'The metadata associated with the mapping example, '
-          'which chould carry structured data, such as tool function input. '
+          'which could carry structured data, such as tool function input. '
           'It is a `pg.Dict` object whose keys can be accessed by attributes.'
       ),
   ] = pg.Dict()
 
-  def schema_repr(
-      self, protocol: schema_lib.SchemaProtocol = 'python', **kwargs
-  ) -> str:
+  def schema_repr(self, protocol: str = 'python', **kwargs) -> str:
     """Returns the string representation of schema based on protocol."""
     if self.schema is None:
       return ''
-    return self.schema.schema_str(protocol, **kwargs)
+    return schema_lib.schema_repr(self.schema, protocol=protocol, **kwargs)
 
   @property
   def has_output(self) -> bool:
@@ -121,12 +174,14 @@ class MappingExample(lf.NaturalLanguageFormattable,
   def value_repr(
       cls,
       value: Any,
-      protocol: schema_lib.SchemaProtocol = 'python',
+      protocol: str = 'python',
       use_modality_ref: bool = False,
       **kwargs
   ) -> str:
     if isinstance(value, str):
       return value
+    if isinstance(value, lf.Message):
+      return str(value)
     if isinstance(value, lf.Modality):
       with lf.modality.format_modality_as_ref():
         return str(value)
@@ -134,11 +189,11 @@ class MappingExample(lf.NaturalLanguageFormattable,
     # Placehold modalities if they are present.
     if use_modality_ref and pg.contains(value, type=lf.Modality):
       value = lf.ModalityRef.placehold(value)
-    return schema_lib.value_repr(protocol).repr(value, **kwargs)
+    return schema_lib.value_repr(value, protocol=protocol, **kwargs)
 
   def input_repr(
       self,
-      protocol: schema_lib.SchemaProtocol = 'python',
+      protocol: str = 'python',
       compact: bool = False,
       verbose: bool = True,
       **kwargs
@@ -150,7 +205,7 @@ class MappingExample(lf.NaturalLanguageFormattable,
 
   def output_repr(
       self,
-      protocol: schema_lib.SchemaProtocol = 'python',
+      protocol: str = 'python',
       compact: bool = False,
       verbose: bool = True,
       **kwargs
@@ -192,9 +247,7 @@ class MappingExample(lf.NaturalLanguageFormattable,
 
     def render_value(view, *, value, **kwargs):
       if isinstance(value, lf.Template):
-        # Make a shallow copy to make sure modalities are rooted by
-        # the input.
-        value = value.clone().render()
+        value = value.render()
       if value is None:
         return None
       return view.render(value, **kwargs)
@@ -242,7 +295,7 @@ class MappingExample(lf.NaturalLanguageFormattable,
 
 
 class Mapping(lf.LangFunc):
-  """Base class for mapping.
+  """Base class for LLM-based mapping operations.
 
   {{ preamble }}
 
@@ -263,19 +316,19 @@ class Mapping(lf.LangFunc):
       pg.Symbolic,
       (
           'The mapping input. It could be `lf.Message` (a pg.Symbolic '
-          'subclass) as natural language input, or other symbolic object '
+          'subclass) as natural language input, or other symbolic objects '
           'as structured input.'
       ),
   ]
 
   context: Annotated[
-      str | None, 'The mapping context. A string as natural language '
+      str | None, 'The mapping context as a natural language string.'
   ] = None
 
   schema: pg.typing.Annotated[
       # Automatic conversion from annotation to schema.
       schema_lib.schema_spec(noneable=True),
-      'A `lf.structured.Schema` object that constrains mapping output ',
+      'A `lf.structured.Schema` object that constrains mapping output.',
   ] = None
 
   permission: Annotated[
@@ -286,12 +339,8 @@ class Mapping(lf.LangFunc):
   @property
   def mapping_request(self) -> MappingExample:
     """Returns a MappingExample as the mapping request."""
-    if isinstance(self.input, lf.Message):
-      input_value = self.input.text
-    else:
-      input_value = pg.Ref(self.input)
     return MappingExample(
-        input=input_value,
+        input=pg.Ref(self.input),
         schema=pg.Ref(self.schema),
         context=self.context,
     )
@@ -382,16 +431,16 @@ class Mapping(lf.LangFunc):
   default: Annotated[
       Any,
       (
-          'The default value to use if the LM response is not a valid code '
-          'based on the schema (after autofix). '
-          'If unspecified, error will be raisen.'
+          'The default value to use if parsing fails (after autofix). '
+          'If `lf.RAISE_IF_HAS_ERROR` is used (default), an error will be '
+          'raised instead.'
       ),
   ] = lf.RAISE_IF_HAS_ERROR
 
   response_postprocess: Annotated[
       Callable[[str], str] | None,
       (
-          'A callable object that post process the raw LLM response before '
+          'A callable object that post-processes the raw LLM response before '
           'parsing it into the output Python object.'
       )
   ] = None
@@ -402,11 +451,6 @@ class Mapping(lf.LangFunc):
 
   def transform_input(self, lm_input: lf.Message) -> lf.Message:
     # Find modalities to fill the input message.
-    lm_input.metadata.update(
-        examples=pg.Ref(self.examples),
-        input=pg.Ref(self.input),
-        schema=pg.Ref(self.schema) if self.schema is not None else None,
-    )
     if isinstance(self.input, lf.Message):
       lm_input.source = self.input
     return lm_input
@@ -429,7 +473,7 @@ class Mapping(lf.LangFunc):
     return lm_output
 
   def parse_result(self, lm_output: lf.Message) -> Any:
-    """Parse result from LLM response."""
+    """Parses result from LLM response."""
     schema = self.mapping_request.schema
     if schema is None:
       return None
@@ -443,7 +487,7 @@ class Mapping(lf.LangFunc):
       response_text = '\n'.join(
           tc.text for tc in lm_output.metadata['tool_calls']
       )
-    return schema.parse(
+    return schema.parse_value(
         response_text,
         protocol=self.protocol,
         additional_context=self.globals(),
@@ -453,7 +497,7 @@ class Mapping(lf.LangFunc):
     )
 
   def postprocess_response(self, response: lf.Message) -> lf.Message:
-    """Post process LLM response."""
+    """Post-processes LLM response."""
     if self.response_postprocess is not None:
       postprocessed_text = self.response_postprocess(response.text)
       if postprocessed_text != response.text:
@@ -461,7 +505,7 @@ class Mapping(lf.LangFunc):
     return response
 
   def postprocess_result(self, result: Any) -> Any:
-    """Post process structured output."""
+    """Post-processes structured output."""
     return result
 
   def globals(self) -> dict[str, Any]: