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

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.'
       ),
   ]
@@ -171,6 +245,7 @@ class Template(
 
     # Last render output.
     self._cached_render_output = None
+    self._referred_modalities = None
 
   @property
   def render_output(self) -> message_lib.Message | None:
@@ -195,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.
@@ -229,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(
@@ -253,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)
@@ -309,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,
@@ -322,24 +412,46 @@ class Template(
                 compact=True,
                 python_format=True,
             ):
-              # Natural language formattable objects will be returned in natural
-              # language when they are directly returned as rendering elements
+
+              # Capture the modality objects whose references are being
+              # rendered
               # in the template.
-              with modality.format_modality_as_ref():
-                rendered_text = self._template.render(**inputs)
+              with modality.capture_rendered_modalities() as modality_refs:
+
+                # Natural language formattable objects will be returned in
+                # natural language when they are directly returned as rendering
+                # elements in the template.
+                with modality.format_modality_as_ref():
+                  rendered_text = self._template.render(**inputs)
 
-            # Carry additional metadata.
-            metadata = self.additional_metadata()
+              # Carry the modality references passed from the constructor.
+              # This is to support modality objects that is already rendered
+              # in the template string.
+              if self._referred_modalities:
+                modality_refs.update(self._referred_modalities)
 
         if self.clean:
           rendered_text = rendered_text.strip()
 
-        metadata.update(
-            {k: pg.Ref(v) for k, v in inputs.items() if not inspect.ismethod(v)}
-        )
+        # Fill message metadata.
+        metadata = {
+            '__template_input__': {
+                k: pg.Ref(v) for k, v in inputs.items()
+                if not inspect.ismethod(v)
+            },
+        }
+
+        # Carry additional metadata.
+        # TODO(daiyip): Consider to put additional metadata into a separate
+        # key under `metadata`.
+        metadata.update(self.additional_metadata())
 
         # Fill the variables for rendering the template as metadata.
-        message = message_cls(text=rendered_text, metadata=metadata)
+        message = message_cls(
+            text=rendered_text,
+            referred_modalities=modality_refs,
+            metadata=metadata
+        )
 
         # Tag input as rendered message.
         message.tag(message_lib.Message.TAG_RENDERED)
@@ -366,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():
@@ -374,7 +493,7 @@ class Template(
         metadata[k.removeprefix(_ADDITIONAL_METADATA_PREFIX)] = v
 
     # Carry metadata from fields.
-    for k, v in self.sym_init_args.items():
+    for k, v in self.sym_init_args.sym_items():
       if k.startswith(_ADDITIONAL_METADATA_PREFIX):
         metadata[k.removeprefix(_ADDITIONAL_METADATA_PREFIX)] = v
     return metadata
@@ -391,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
 
@@ -425,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.
 
@@ -512,19 +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, message_lib.Message):
-      kwargs.update(value.metadata)
-      return cls(template_str=value.text, **kwargs)
     if isinstance(value, Template):
-      lfun = cls(template_str=value.template_str, **kwargs)
+      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
     return cls(template_str='{{input}}', input=value, **kwargs)
 
   def _html_tree_view_content(

langfun/core/template_test.py

@@ -176,6 +176,69 @@ class DefinitionTest(unittest.TestCase):
       Template('{{x=1')
 
 
+class FromValueTest(unittest.TestCase):
+
+  def test_from_str(self):
+    t = Template.from_value('Hello {{x}}', x=1)
+    self.assertTrue(pg.eq(t, Template('Hello {{x}}', x=1)))
+    self.assertEqual(t.render(), 'Hello 1')
+
+  def test_from_message(self):
+    class CustomModality(modality.Modality):
+      content: str
+
+      def to_bytes(self):
+        return self.content.encode()
+
+    message = Template('{{image}}', image=CustomModality('foo')).render()
+    t = Template.from_value(message)
+    m = t.render()
+    self.assertTrue(
+        pg.eq(m.modalities(), [CustomModality('foo')])
+    )
+    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)
+    self.assertTrue(pg.eq(t, t2))
+    self.assertEqual(t2.x, 1)
+
+  def test_from_different_template(self):
+    t = Template('Hello {{x}}', x=1)
+
+    class MyTemplate(Template):
+      pass
+
+    t2 = MyTemplate.from_value(t, x=2)
+    self.assertIsInstance(t2, MyTemplate)
+    self.assertEqual(t2.template_str, t.template_str)
+    self.assertEqual(t2.x, 2)
+
+  def test_from_python_object(self):
+    t = Template.from_value(pg.Dict(x=1, y=2))
+    self.assertEqual(t.template_str, '{{input}}')
+    self.assertEqual(t.input, pg.Dict(x=1, y=2))
+
+
 class VarsTest(unittest.TestCase):
 
   def assert_missing_vars(self, t: Template, missing_vars: set[str]):
@@ -251,6 +314,10 @@ class VarsTest(unittest.TestCase):
 
 class RenderTest(unittest.TestCase):
 
+  def setUp(self):
+    super().setUp()
+    self.maxDiff = None
+
   def test_clean(self):
     l = Template('\n Hello\n ')
     self.assertEqual(l.render(), 'Hello')
@@ -279,19 +346,20 @@ class RenderTest(unittest.TestCase):
     )
     v = l.render()
     self.assertEqual(v, 'How are you 1')
-    self.assertIs(v.x, l.x)
-    self.assertEqual(v.x.render_output, 'are you 1')
-    self.assertIs(v.x.y, l.x.y)
-    self.assertEqual(v.x.y.render_output, 'you 1')
-    self.assertEqual(v.x.y.n, 1)
+    self.assertIs(v.__template_input__.x, l.x)
+    self.assertEqual(v.__template_input__.x.render_output, 'are you 1')
+    self.assertIs(v.__template_input__.x.y, l.x.y)
+    self.assertIs(v.__template_input__.x.y.n, l.x.y.n)
+    self.assertEqual(v.__template_input__.x.y.render_output, 'you 1')
+    self.assertEqual(v.__template_input__.x.y.n, 1)
 
   def test_render_with_call_args(self):
     l = Template('Hello {{x}} and {{y}}', x=1, y=Template('{{z}}'), z=3)
     v = l.render(x=2)
     self.assertEqual(v, 'Hello 2 and 3')
-    self.assertEqual(v.x, 2)
-    self.assertEqual(v.y, '3')
-    self.assertEqual(v.y.z, 3)
+    self.assertEqual(v.__template_input__.x, 2)
+    self.assertEqual(v.__template_input__.y, '3')
+    self.assertEqual(v.__template_input__.y.z, 3)
 
   def test_render_cache(self):
     class DynamicContent(Template):
@@ -321,11 +389,17 @@ class RenderTest(unittest.TestCase):
       def to_bytes(self):
         return self.content.encode()
 
+    foo = CustomModality('foo')
+    message = Template('This is {{ x }} and {{ a }}', x=1, a=foo).render()
     self.assertEqual(
-        Template(
-            'This is {{ x }} and {{ a }}', x=1, a=CustomModality('foo')
-        ).render(),
-        'This is 1 and <<[[a]]>>',
+        message,
+        'This is 1 and <<[[custom_modality:acbd18db]]>>',
+    )
+    self.assertIn(
+        'custom_modality:acbd18db', message.referred_modalities
+    )
+    self.assertIs(
+        message.referred_modalities['custom_modality:acbd18db'], foo
     )
 
   def test_render_with_default(self):
@@ -511,12 +585,44 @@ class RenderTest(unittest.TestCase):
     self.assert_partial(Template('Hello {{len(x)}}'), 'Hello {{len(x)}}')
 
   def test_additional_metadata(self):
-    t = Template('hi', metadata_weights=1.0, y=2)
-    self.assertEqual(t.render(), message_lib.UserMessage('hi', weights=1.0))
+    t = Template('hi {{y}}', metadata_weights=1.0, y=2, z=1)
+    self.assertEqual(
+        t.render(),
+        message_lib.UserMessage(
+            'hi 2', weights=1.0, __template_input__={'y': 2}
+        )
+    )
 
-    t = Template('hi')
-    with component.context(metadata_weights=1.0, y=2):
-      self.assertEqual(t.render(), message_lib.UserMessage('hi', weights=1.0))
+    t = Template('hi {{y}}')
+    with component.context(metadata_weights=1.0, y=3):
+      self.assertEqual(
+          t.render(z=2),
+          message_lib.UserMessage(
+              'hi 3', weights=1.0, __template_input__={'y': 3}
+          )
+      )
+
+  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/env/__init__.py

@@ -0,0 +1,43 @@
+# Copyright 2025 The Langfun Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+"""Environment for LLM agents."""
+
+# pylint: disable=g-importing-member, g-bad-import-order, g-import-not-at-top
+from langfun.env.interface import EnvironmentError   # pylint: disable=redefined-builtin
+from langfun.env.interface import EnvironmentOutageError
+from langfun.env.interface import EnvironmentOverloadError
+from langfun.env.interface import SandboxError
+from langfun.env.interface import SandboxStateError
+
+from langfun.env.interface import Environment
+from langfun.env.interface import Sandbox
+from langfun.env.interface import Feature
+
+from langfun.env.interface import EventHandler
+
+# Decorators for sandbox/feature methods.
+from langfun.env.interface import treat_as_sandbox_state_error
+from langfun.env.interface import log_activity
+
+from langfun.env.base_environment import BaseEnvironment
+from langfun.env.base_sandbox import BaseSandbox
+from langfun.env.base_feature import BaseFeature
+
+from langfun.env import load_balancers
+from langfun.env.load_balancers import LoadBalancer
+
+# Import all event handlers.
+from langfun.env.event_handlers import *
+
+# Google-internal imports.