langfun 0.1.2.dev202511030805__py3-none-any.whl → 0.1.2.dev202511050805__py3-none-any.whl

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,7 +154,7 @@ 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()
@@ -242,7 +297,7 @@ class MappingExample(lf.NaturalLanguageFormattable,
 
 
 class Mapping(lf.LangFunc):
-  """Base class for mapping.
+  """Base class for LLM-based mapping operations.
 
   {{ preamble }}
 
@@ -263,19 +318,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[
@@ -378,16 +433,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
@@ -420,7 +475,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
@@ -444,7 +499,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:
@@ -452,7 +507,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]:

langfun/core/structured/parsing.py

@@ -24,7 +24,7 @@ import pyglove as pg
 
 @lf.use_init_args(['schema', 'default', 'examples'])
 class _ParseStructure(mapping.Mapping):
-  """Parse an object out from a natural language text."""
+  """Parses an object out from a natural language text."""
 
   context_title = 'USER_REQUEST'
   input_title = 'LM_RESPONSE'
@@ -39,7 +39,7 @@ class _ParseStructure(mapping.Mapping):
 
 
 class _ParseStructureJson(_ParseStructure):
-  """Parse an object out from a NL text using JSON as the protocol."""
+  """Parses an object out from a NL text using JSON as the protocol."""
 
   preamble = """
       Please help translate the last LM response into JSON based on the request and the schema:
@@ -55,7 +55,7 @@ class _ParseStructureJson(_ParseStructure):
 
 
 class _ParseStructurePython(_ParseStructure):
-  """Parse an object out from a NL text using Python as the protocol."""
+  """Parses an object out from a NL text using Python as the protocol."""
 
   preamble = """
       Please help translate the last {{ input_title }} into {{ output_title}} based on {{ schema_title }}.
@@ -88,55 +88,55 @@ def parse(
     returns_message: bool = False,
     **kwargs,
 ) -> Any:
-  """Parse a natural language message based on schema.
-
-  Examples:
-
-    ```
-    class FlightDuration(pg.Object):
-      hours: int
-      minutes: int
-
-    class Flight(pg.Object):
-      airline: str
-      flight_number: str
-      departure_airport_code: str
-      arrival_airport_code: str
-      departure_time: str
-      arrival_time: str
-      duration: FlightDuration
-      stops: int
-      price: float
-
-    input = '''
-      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.
-      '''
-
-    r = lf.parse(input, Flight)
-    assert isinstance(r, Flight)
-    assert r.airline == 'United Airlines'
-    assert r.departure_airport_code == 'SFO'
-    assert r.duration.hour = 7
-    ```
+  """Parses a natural language message into a structured object using an LLM.
+
+  `lf.parse` extracts structured information from a natural language string
+  or message according to a provided schema. It is the inverse of
+  `lf.describe`.
+
+  **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_code: str
+    arrival_airport_code: str
+    duration: FlightDuration
+    price: float
+
+  text = '''
+  The flight is UA2631 of United Airlines, from SFO to JFK,
+  duration is 7 hours and 57 minutes, costing $227.
+  '''
+
+  flight = lf.parse(text, Flight, lm=lf.llms.Gemini25Flash())
+  assert flight.airline == 'United Airlines'
+  assert flight.duration.hours == 7
+  ```
 
   Args:
     message: A `lf.Message` object  or a string as the natural language input.
       It provides the complete context for the parsing.
-    schema: A `lf.transforms.ParsingSchema` object or equivalent annotations.
-    default: The default value if parsing failed. If not specified, error will
-      be raised.
+    schema: A `lf.Schema` object or equivalent annotations.
+    default: The default value to return if parsing fails. If
+      `lf.RAISE_IF_HAS_ERROR` is used (default), an error will be raised
+      instead.
     user_prompt: An optional user prompt as the description or ask for the
-      message, which provide more context for parsing.
+      message, which provides more context for parsing.
     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 parsing. If None,
+      default examples will be used.
     include_context: If True, include the request sent to LLM for obtaining the
-      response to pares. Otherwise include only the response.
+      response to parse. Otherwise include only the response.
     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.
@@ -146,10 +146,10 @@ def parse(
       `autofix_lm` from `lf.context` context manager will be used. Otherwise it
       will use `lm`.
     protocol: The protocol for schema/value representation. Applicable values
-      are 'json' and 'python'. By default 'python' will be used.`
+      are 'json' and 'python'. By default 'python' will be used.
     returns_message: If True, returns `lf.Message` as the output, instead of
       returning the structured `message.result`.
-    **kwargs: Keyword arguments passed to the `lf.structured.ParseStructure`
+    **kwargs: Keyword arguments passed to the `_ParseStructure`
       transform.
 
   Returns:
@@ -223,7 +223,7 @@ async def aparse(
 
 
 def call(
-    prompt: str | lf.Template,
+    prompt: Union[str, lf.Template, lf.Message],
     schema: Union[
         None, schema_lib.Schema, Type[Any], list[Type[Any]], dict[str, Any]
     ] = None,
@@ -240,27 +240,43 @@ def call(
     returns_message: bool = False,
     **kwargs,
 ) -> Any:
-  """Call a language model with prompt and formulate response in return type.
-
-  Examples::
-
-    # Call with constant string-type prompt.
-    lf.call('Compute one plus one', lm=lf.llms.Gpt35())
-    >> "two"
-
-    # Call with returning a structured (int) type.
-    lf.call('Compute one plus one', int, lm=lf.llms.Gpt35())
-    >> 2
-
-    # Call with a template string with variables.
-    lf.call('Compute {{x}} plus {{y}}', int,
-            x='one', y='one', lm=lf.llms.Gpt35())
-    >> 2
-
-    # Call with an `lf.Template` object with variables.
-    lf.call(lf.Template('Compute {{x}} plus {{y}}', x=1), int,
-            y=1, lm=lf.llms.Gpt35())
-    >> 2
+  """Calls a language model and parses the response according to a schema.
+
+  `lf.call` first calls a language model with a prompt to obtain a natural
+  language response, then calls the language model again to parse this
+  response into a structured format defined by `schema`. If `schema` is not
+  provided, it returns the raw natural language response.
+
+  **Example:**
+
+  1.  **Call with a Natural Language Prompt**:
+      By default, `lf.call` with a string prompt returns a natural language
+      response:
+      ```python
+      r = lf.call('Compute one plus one', lm=lf.llms.Gpt4())
+      print(r)
+      # Output: 2
+      ```
+
+  2.  **Call with Structured Output**:
+      If `schema` is provided, `lf.call` parses the LLM response into the
+      specified schema using a second LM call:
+      ```python
+      r = lf.call('Compute one plus one', int, lm=lf.llms.Gpt4())
+      print(r)
+      # Output: 2
+      ```
+
+  3.  **Call with Templated Prompt**:
+      The prompt can be a template string with placeholders (e.g., `{{x}}`,
+      `{{y}}`), whose values are provided as keyword arguments:
+      ```python
+      r = lf.call(
+          'Compute {{x}} plus {{y}}',
+          int, x='one', y='one', lm=lf.llms.Gpt4())
+      print(r)
+      # Output: 2
+      ```
 
   Args:
     prompt: User prompt that will be sent to LM, which could be a string or a
@@ -272,10 +288,10 @@ def call(
       If not specified, `lm` from `lf.context` context manager will be used.
     parsing_lm: Language model that will be used for parsing. If None, the `lm`
       for prompting the LM will be used.
-    parsing_examples: Examples for parsing the output. If None,
-      `lf.structured.DEFAULT_PARSE_EXAMPLES` will be used.
+    parsing_examples: Examples for parsing the output. If None, no examples
+      will be used for parsing.
     parsing_include_context: If True, include the request sent to LLM for
-      obtaining the response to pares. Otherwise include only the response.
+      obtaining the response to parse. Otherwise include only the response.
     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.
@@ -284,10 +300,10 @@ def call(
     autofix_lm: The language model to use for autofix. If not specified, the
       `autofix_lm` from `lf.context` context manager will be used. Otherwise it
       will use `parsing_lm`.
-    response_postprocess: A callback function to post process the text response
+    response_postprocess: A callback function to post-process the text response
       before sending for parsing.
     protocol: The protocol for schema/value representation. Applicable values
-      are 'json' and 'python'. By default 'python' will be used.`
+      are 'json' and 'python'. By default 'python' will be used.
     returns_message: If True, return a `lf.Message` object instead of its text
       or result.
     **kwargs: Keyword arguments. Including options that control the calling
@@ -387,7 +403,7 @@ def _parse_structure_cls(
 
 
 def default_parse_examples() -> list[mapping.MappingExample]:
-  """Default parsing examples."""
+  """Returns default parsing examples."""
 
   class AdditionResults(pg.Object):
     one_plus_one_equals: int | None

langfun/core/structured/parsing_test.py

@@ -745,9 +745,6 @@ class CallTest(unittest.TestCase):
         parsing.call('what is one plus two?', int, lm=lm, autofix=3), 3
     )
 
-  def test_call_with_structured_input(self):
-    self.assertEqual(parsing.call(1, lm=fake.StaticResponse('2')), '2')
-
   def test_call_with_response_postprocess(self):
     target_str = '@TARGET_STR@'
     random_str = '!RANDOM_STR!'