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

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]:

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 }}.
@@ -84,59 +84,59 @@ def parse(
     cache_seed: int | None = 0,
     autofix: int = 0,
     autofix_lm: lf.LanguageModel | None = None,
-    protocol: schema_lib.SchemaProtocol = 'python',
+    protocol: str = 'python',
     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:
@@ -198,7 +198,7 @@ async def aparse(
     cache_seed: int | None = 0,
     autofix: int = 0,
     autofix_lm: lf.LanguageModel | None = None,
-    protocol: schema_lib.SchemaProtocol = 'python',
+    protocol: str = 'python',
     returns_message: bool = False,
     **kwargs,
 ) -> Any:
@@ -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,
@@ -236,31 +236,47 @@ def call(
     autofix: int = 0,
     autofix_lm: lf.LanguageModel | None = None,
     response_postprocess: Callable[[str], str] | None = None,
-    protocol: schema_lib.SchemaProtocol = 'python',
+    protocol: str = 'python',
     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
@@ -351,7 +367,7 @@ async def acall(
     autofix: int = 0,
     autofix_lm: lf.LanguageModel | None = None,
     response_postprocess: Callable[[str], str] | None = None,
-    protocol: schema_lib.SchemaProtocol = 'python',
+    protocol: str = 'python',
     returns_message: bool = False,
     **kwargs,
 ) -> Any:
@@ -376,7 +392,7 @@ async def acall(
 
 
 def _parse_structure_cls(
-    protocol: schema_lib.SchemaProtocol,
+    protocol: str,
 ) -> Type[_ParseStructure]:
   if protocol == 'json':
     return _ParseStructureJson
@@ -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!'