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

langfun/core/structured/scoring.py

@@ -35,38 +35,50 @@ def score(
     return_scoring_results: bool = False,
     **kwargs,
 ) -> list[float] | list[lf.LMScoringResult]:
-  """Scores the outputs based on the prompt.
-
-  Examples:
-    ```
-    # Example 1: Scoring text output based on the user prompt.
-    scores = lf.score('{{x}} + {{y}} =', ['1', '2', '3'], lm=lm, x=1, y=2)
-    assert len(scores) == 3
-
-    # Example 2: Scoring int output based on the formulated OOP prompt.
-    scores = lf.score('1 + 1 =', [1, 2, 3], lm=lm)
-    assert len(scores) == 3
-
-    class Answer(pg.Object):
-      result: int
-
-    # Example 3: Scoring object output based on the formulated OOP prompt.
-    scores = lf.score('1 + 1 =', [Answer(1), Answer(2), Answer(3)], lm=lm)
-    assert len(scores) == 3
-
-    # Example 4: Scoring object field value based on the formulated OOP prompt
-    # and the generated tokens before the first `pg.oneof`.
-    scores = lf.score('1 + 1 =', [Answer(pg.oneof([1, 2, 3]))], lm=lm)
-    assert len(scores) == 3
-
-    # Example 5: Scoring multiple prompt/completion pairs.
-    scores = lf.score(
-        ['1 + 1=', '2 + 3='],
-        ['2', '4'],
-        lm=lm
-    )
-    assert len(scores) == 2
-    ```
+  """Scores completions based on a prompt using a language model.
+
+  `lf.score` computes the likelihood of each completion being generated given
+  a prompt, according to the specified language model. It can score text
+  completions or structured objects. If `schema` is provided, Langfun
+  formats the prompt and completions appropriately before scoring.
+
+  **Example 1: Score text completions**
+  ```python
+  import langfun as lf
+  scores = lf.score(
+      '1 + 1 =',
+      ['2', '3', '4'],
+      lm=lf.llms.Gemini25Flash())
+  print([f'{s:.3f}' for s in scores])
+  # Output: ['-0.001', '-2.345', '-3.456']
+  ```
+
+  **Example 2: Score structured completions**
+  ```python
+  import langfun as lf
+  import pyglove as pg
+
+  class Answer(pg.Object):
+    result: int
+
+  scores = lf.score(
+      '1 + 1 =',
+      [Answer(result=2), Answer(result=3), Answer(result=4)],
+      lm=lf.llms.Gemini25Flash())
+  print([f'{s:.3f}' for s in scores])
+  # Output: ['-0.001', '-2.345', '-3.456']
+  ```
+
+  **Example 3: Score multiple prompt/completion pairs**
+  ```python
+  import langfun as lf
+  scores = lf.score(
+      ['1 + 1 =', '2 + 2 ='],
+      ['2', '4'],
+      lm=lf.llms.Gemini25Flash())
+  print([f'{s:.3f}' for s in scores])
+  # Output: ['-0.001', '-0.002']
+  ```
 
   Args:
     prompt: The prompt(s) based on which each completion will be scored.
@@ -74,8 +86,7 @@ def score(
     schema: The schema as the output type. If None, it will be inferred from
       the completions.
     lm: The language model used for scoring.
-    examples: Fewshot exemplars used together with the prompt in getting the
-      completions.
+    examples: Few-shot examples used to construct the prompt for scoring.
     protocol: The protocol for formulating the prompt based on objects.
     return_scoring_results: If True, returns a list of `lf.LMScoringResult`,
       otherwise returns a list of floats as the scores of each completion.

langfun/core/structured/tokenization.py

@@ -23,7 +23,7 @@ import pyglove as pg
 
 
 def tokenize(
-    prompt: Union[str, pg.Symbolic] | list[str | pg.Symbolic],
+    prompt: Union[str, pg.Symbolic, list[str | pg.Symbolic]],
     schema: Union[
         schema_lib.Schema, Type[Any], list[Type[Any]], dict[str, Any], None
     ] = None,
@@ -33,20 +33,35 @@ def tokenize(
     protocol: schema_lib.SchemaProtocol = 'python',
     **kwargs,
 ) -> list[tuple[str | bytes, int]]:
-  """Tokenize the prompt for `lf.query`.
+  """Renders a prompt and tokenizes it using a language model.
+
+  `lf.tokenize` first renders a prompt based on the provided `prompt`,
+  `schema`, and `examples`, similar to `lf.query`, and then uses the
+  specified language model (`lm`) to tokenize the resulting message.
+  This is useful for understanding how a prompt is seen by the model or
+  for estimating token counts before sending requests.
+
+  **Example:**
+
+  ```python
+  import langfun as lf
+  tokens = lf.tokenize('Hello world!', lm=lf.llms.Gpt4())
+  print(tokens)
+  # Output might look like: [('Hello', 15339), (' world', 1917), ('!', 0)]
+  ```
 
   Args:
-    prompt: The prompt(s) based on which each completion will be scored.
-    schema: The schema as the output type. If None, it will be inferred from
-      the completions.
-    lm: The language model used for scoring.
-    examples: Fewshot exemplars used together with the prompt in getting the
-      completions.
+    prompt: The prompt to render and tokenize. Can be a string, `pg.Symbolic`,
+      or `lf.Template`.
+    schema: The schema for formatting the prompt, if `prompt` is structured or
+      if schema-based formatting is needed.
+    lm: The language model to use for tokenization.
+    examples: Few-shot examples to include in the rendered prompt.
     protocol: The protocol for formulating the prompt based on objects.
     **kwargs: Keyword arguments that are referred by the prompt.
 
   Returns:
-    A list of (text, token_id) tuples.
+    A list of (token_str, token_id) tuples representing the tokenized prompt.
   """
   input_message = querying.query_prompt(
       prompt,

langfun/core/subscription.py

@@ -35,7 +35,7 @@ EventType = TypeVar('EventType')
 
 
 class EventHandler(Generic[EventType], metaclass=abc.ABCMeta):
-  """Interface for event subscriber."""
+  """Interface for event handler."""
 
   @classmethod
   @functools.cache
@@ -51,7 +51,7 @@ class EventHandler(Generic[EventType], metaclass=abc.ABCMeta):
 
   @classmethod
   def accepts(cls, event: Event[Any]) -> bool:
-    """Returns True if current event handler class can accepts an event."""
+    """Returns True if current event handler class can accept an event."""
     return isinstance(event, cls.event_type())
 
   @abc.abstractmethod

langfun/core/template.py

@@ -49,20 +49,94 @@ class Template(
     pg.typing.CustomTyping,
     pg.views.HtmlTreeView.Extension
 ):
-  """Langfun string template.
-
-  Langfun uses jinja2 as its template engine. Pleaes check out
-  https://jinja.palletsprojects.com/en/3.1.x/templates/ for detailed
-  explanation on the template language.
+  r"""Langfun string template.
+
+  `lf.Template` provides a flexible way to define and render prompts using
+  the Jinja2 templating engine. It supports variable substitution, composition
+  of templates, multi-modal content, and easy reuse through subclassing.
+
+  **Key Features:**
+
+  *   **Jinja2 Syntax**: Leverages the full power of Jinja2 for
+      expressions, loops, and conditional logic within templates.
+      (See [Jinja2 documentation](
+      https://jinja.palletsprojects.com/en/3.1.x/templates/))
+  *   **Composition**: Templates can include other `lf.Template`, `lf.Message`
+      and message-convertible objects, allowing complex prompts to be built from
+      reusable components.
+  *   **Multi-Modal Support**: Seamlessly integrates multi-modal objects
+      (like `lf.Image`, `lf.Audio`) into templates.
+  *   **Subclassing**: Define reusable prompt structures by subclassing
+      `lf.Template` and setting defaults.
+  *   **Context Awareness**: Variables can be resolved from `render()`
+      arguments, template attributes, or the surrounding `lf.context`.
+
+  **1. Basic Usage:**
+  Variables are indicated by `{{variable_name}}`.
+
+  ```python
+  t = lf.Template("Hello, {{name}}!", name="World")
+  print(t.render())
+  # Output: Hello, World!
+  ```
+
+  **2. Providing Variables at Render Time:**
+  Variables can be provided when calling `render()`:
+
+  ```python
+  t = lf.Template("Hello, {{name}}!")
+  print(t.render(name="Alice"))
+  # Output: Hello, Alice!
+  ```
+
+  **3. Composition:**
+  Embed templates within other templates for modularity:
+
+  ```python
+  t = lf.Template(
+      "{{greeting}}, {{question}}",
+      greeting=lf.Template("Hello {{user}}", user="Bob"),
+      question=lf.UserMessage("How are you?")
+  )
+  print(t.render())
+  # Output: Hello Bob, How are you?
+  ```
+
+  **4. Multi-Modal Content:**
+  Reference modality objects in the template string:
+
+  ```python
+  image = lf.Image.from_path(...)
+  t = lf.Template("Describe this image: <<[[{{image.id}}]]>>", image=image)
+  # When rendered, 't' can be passed to a multi-modal model.
+  ```
+
+  **5. Subclassing for Reusability:**
+  Define a reusable template via subclassing. The docstring can serve as the
+  default template string if it doesn't contain "THIS IS NOT A TEMPLATE".
+
+  ```python
+  class Greeting(lf.Template):
+    '''Greeting prompt.
+
+    Hello, {{user}}!
+    '''
+    user: str = 'guest'
+
+  print(Greeting().render())
+  # Output: Hello, guest!
+  print(Greeting(user='Admin').render())
+  # Output: Hello, Admin!
+  ```
   """
 
   template_str: Annotated[
       str,
       (
-          'A template string in jinja2 syntax. During `render`, the variables '
-          'will be resolved from 1) the `kwargs` dict passed to the `render` '
-          'method; 2) the attributes of this object; and 3) the attributes of '
-          'its containing objects.'
+          'A template string in jinja2 syntax. During `render`, variables '
+          'will be resolved from: 1) keyword arguments passed to `render`; '
+          '2) attributes of this object; and 3) attributes of its containing '
+          'objects.'
       ),
   ]
 
@@ -70,16 +144,16 @@ class Template(
       bool,
       (
           'If True, `inspect.cleandoc` will be applied on `template_str` to '
-          'additional indention, etc. Otherwise, the original form of the '
-          'template string will be used.'
+          'remove leading/trailing spaces and fix indentation. Otherwise, '
+          'the `template_str` will be used as is.'
       ),
   ] = True
 
   __kwargs__: Annotated[
       Any,
       (
-          'Wildcard keyword arguments for `__init__` that can be referred in '
-          'the template string. This allows modularization of prompt with '
+          'Wildcard keyword arguments for `__init__` that can be referred to '
+          'in the template string. This allows modularizing prompts with '
           'fully or partially bound variables.'
       ),
   ]
@@ -196,12 +270,14 @@ class Template(
     """Returns referred variables.
 
     Args:
-      specified: If True, include only variables that are specified. If False,
-        include only variables that are not specified. If None, include both.
-      closure: If True, include variables from referred LangFuncs recursively.
-        Otherwise, include the immediate used variables.
-      leaf: If True, include only the non-LangFunc variables. If False, include
-        LangFunc variables. If None, include both.
+      specified: If True, include only variables specified with a value.
+        If False, include only variables that are not specified.
+        If None, include both specified and unspecified variables.
+      closure: If True, include variables from referred `lf.Template` objects
+        recursively. Otherwise, only include variables used in this template.
+      leaf: If True, include only variables that are not `lf.Template` objects.
+        If False, include only variables that are `lf.Template` objects.
+        If None, include both.
 
     Returns:
       A list of variable names that match the criteria.
@@ -230,17 +306,17 @@ class Template(
 
   @property
   def missing_vars(self) -> Set[str]:
-    """Returns the missing variable names."""
+    """Returns missing variable names from this and referred templates."""
     return self.vars(closure=True, specified=False)
 
   @classmethod
   def raw_str(cls, text: str) -> str:
-    """Returns a template string that preserve the text as original."""
+    """Returns a template string that preserves the text as original."""
     return '{% raw %}' + text + '{% endraw %}'
 
   @classmethod
   def from_raw_str(cls, text: str) -> 'Template':
-    """Returns a template that preserve the text as original."""
+    """Returns a template that preserves the text as original."""
     return cls(cls.raw_str(text), clean=False)
 
   def render(
@@ -254,18 +330,20 @@ class Template(
     """Renders the template with variables from the context.
 
     Args:
-      allow_partial: Allow partial rendering, this means that unresolved
-        variables are allowed and remain in the output text.
-      implicit: If True, reuse the rendering output if a parent LangFunc
-        is rendering current LangFunc multiple times. This is important
-        for making sure all references to the same LangFunc within a single
+      allow_partial: If True, allows partial rendering, which leaves unresolved
+        variables in place in the output text. Otherwise, raises error when
+        there are unresolved variables.
+      implicit: If True, reuse the rendering output if a parent `lf.Template`
+        is rendering current `lf.Template` multiple times. This is important
+        for making sure all references to the same `lf.Template` within a single
         top-level rendering would return the same result. If False, every call
         to `render` will trigger the actual rendering process.
       message_cls: The message class used for creating the return value.
-      **kwargs: Values for template variables.
+      **kwargs: Values for template variables, which override values from
+        member attributes or context.
 
     Returns:
-      An Message object as the rendered result.
+      A Message object containing the rendered result.
     """
     try:
       pg.object_utils.thread_local_push(_TLS_RENDER_STACK, self)
@@ -310,6 +388,17 @@ class Template(
                       f'The value for template variable {var_name!r} is not '
                       f'provided. Template: {self.template_str!r}'
                   )
+              # Short-circuit common types that do not need conversions.
+              elif not isinstance(
+                  var_value, (
+                      bool, int, float, str, list, dict,
+                      Template, message_lib.Message, modality.Modality
+                  )
+              ) and message_lib.Message.is_convertible(type(var_value)):
+                # Automatically convert the value to a message if it is
+                # convertible. This allows users to drop message convertible
+                # objects into template for nested rendering.
+                var_value = message_lib.Message.from_value(var_value)
               inputs[var_name] = var_value
 
             # Enable Python format for builtin types during template rendering,
@@ -389,7 +478,14 @@ class Template(
       assert top is self, (top, self)
 
   def additional_metadata(self) -> dict[str, Any]:
-    """Returns additional metadta to be carried in the rendered message."""
+    """Returns additional metadata to be carried in the rendered message.
+
+    Subclasses can override this method to inject additional metadata based on
+    their own logic.
+
+    Returns:
+      A dict of metadata to be added to the output message.
+    """
     metadata = {}
     # Carry metadata from `lf.context`.
     for k, v in component.all_contextual_values().items():
@@ -414,7 +510,7 @@ class Template(
       child_transform: Callable[[pg.KeyPath, pg.typing.Field, Any], Any]
       | None = None,
   ) -> Tuple[bool, Any]:
-    """Makes it applicable to pg.typing.Str()."""
+    """Makes template applicable to `pg.typing.Str()`."""
     del allow_partial
     del child_transform
 
@@ -448,10 +544,11 @@ class Template(
 
   @property
   def DEFAULT(self) -> 'Template':
-    """Referring to the default value used for this template.
+    """Refers to the default value used for this template.
 
-    This method is intended to be used in template for referring to the default
-    value of current template. There are two scenarios:
+    This property is intended to be used in template string for referring to
+    the default value of current template, useful for wrapping the default
+    template. For example:
 
     Scenario 1: Use instance-level template_str to override the class default.
 
@@ -535,22 +632,24 @@ class Template(
       value: Union[str, message_lib.Message, 'Template'],
       **kwargs
   ) -> 'Template':
-    """Create a template object from a string or template."""
+    """Creates a template object from a value."""
     if isinstance(value, cls):
       return value.clone(override=kwargs) if kwargs else value  # pylint: disable=no-value-for-parameter
     if isinstance(value, str):
       return cls(template_str=value, **kwargs)
+    if isinstance(value, Template):
+      lfun = cls(template_str=value.template_str, **kwargs)  # pylint: disable=attribute-error
+      # So lfun could acccess all attributes from value.
+      lfun.sym_setparent(value)
+      return lfun
+    if message_lib.Message.is_convertible(type(value)):
+      value = message_lib.Message.from_value(value)
     if isinstance(value, message_lib.Message):
       for k, v in value.metadata.sym_items():  # pylint: disable=attribute-error
         kwargs[_ADDITIONAL_METADATA_PREFIX + k] = v
       t = cls(template_str=value.text, **kwargs)
       t._referred_modalities = value.referred_modalities
       return t
-    if isinstance(value, Template):
-      lfun = cls(template_str=value.template_str, **kwargs)  # pylint: disable=attribute-error
-      # So lfun could acccess all attributes from value.
-      lfun.sym_setparent(value)
-      return lfun
     return cls(template_str='{{input}}', input=value, **kwargs)
 
   def _html_tree_view_content(

langfun/core/template_test.py

@@ -198,6 +198,24 @@ class FromValueTest(unittest.TestCase):
     )
     self.assertEqual(message.metadata, m.metadata)
 
+  def test_from_message_convertible(self):
+
+    class MyFormat(pg.Object):
+      text: str
+
+    class MyConverter(message_lib.MessageConverter):  # pylint: disable=unused-variable
+      FORMAT_ID = 'int'
+      OUTPUT_TYPE = MyFormat
+
+      def to_value(self, m: message_lib.Message) -> MyFormat:
+        return MyFormat(text=m.text)
+
+      def from_value(self, value: MyFormat) -> message_lib.Message:
+        return message_lib.UserMessage(value.text)
+
+    t = Template.from_value(MyFormat(text='1'))
+    self.assertEqual(t.render(), '1')
+
   def test_from_same_template(self):
     t = Template('Hello {{x}}', x=1)
     t2 = Template.from_value(t)
@@ -584,6 +602,28 @@ class RenderTest(unittest.TestCase):
           )
       )
 
+  def test_render_with_message_convertible_type(self):
+    class MyFormat(pg.Object):
+      text: str
+
+    class MyConverter(message_lib.MessageConverter):  # pylint: disable=unused-variable
+      FORMAT_ID = 'another-format'
+      OUTPUT_TYPE = MyFormat
+
+      def to_value(self, m: message_lib.Message) -> MyFormat:
+        return MyFormat(text=m.text)
+
+      def from_value(self, value: MyFormat) -> message_lib.Message:
+        return message_lib.UserMessage(value.text)
+
+    t = Template('Hello {{x}}', x=MyFormat(text='world'))
+    rendered_message = t.render()
+    self.assertEqual(rendered_message, 'Hello world')
+    self.assertIsInstance(
+        rendered_message.__template_input__['x'], message_lib.UserMessage
+    )
+    self.assertEqual(rendered_message.__template_input__['x'].text, 'world')
+
 
 class TemplateRenderEventTest(unittest.TestCase):
 

{langfun-0.1.2.dev202511030805.dist-info → langfun-0.1.2.dev202511050805.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langfun
-Version: 0.1.2.dev202511030805
+Version: 0.1.2.dev202511050805
 Summary: Langfun: Language as Functions.
 Home-page: https://github.com/google/langfun
 Author: Langfun Authors