langfun 0.0.2.dev20240429__py3-none-any.whl → 0.1.2.dev202501150804__py3-none-any.whl

langfun/core/template.py

@@ -17,7 +17,7 @@ import contextlib
 import dataclasses
 import functools
 import inspect
-from typing import Annotated, Any, Callable, Iterator, Set, Tuple, Type
+from typing import Annotated, Any, Callable, Iterator, Set, Tuple, Type, Union
 
 import jinja2
 from jinja2 import meta as jinja2_meta
@@ -47,6 +47,7 @@ class Template(
     natural_language.NaturalLanguageFormattable,
     component.Component,
     pg.typing.CustomTyping,
+    pg.views.HtmlTreeView.Extension
 ):
   """Langfun string template.
 
@@ -231,6 +232,16 @@ class Template(
     """Returns the missing variable names."""
     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."""
+    return '{% raw %}' + text + '{% endraw %}'
+
+  @classmethod
+  def from_raw_str(cls, text: str) -> 'Template':
+    """Returns a template that preserve the text as original."""
+    return cls(cls.raw_str(text), clean=False)
+
   def render(
       self,
       *,
@@ -495,6 +506,109 @@ class Template(
     t.sym_setparent(self)
     return t
 
+  @classmethod
+  def from_value(
+      cls,
+      value: Union[str, message_lib.Message, 'Template'],
+      **kwargs
+  ) -> 'Template':
+    """Create a template object from a string or template."""
+    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)
+      # 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(
+      self,
+      *,
+      view: pg.views.HtmlTreeView,
+      root_path: pg.KeyPath | None = None,
+      collapse_level: int | None = None,
+      extra_flags: dict[str, Any] | None = None,
+      debug: bool = False,
+      **kwargs,
+  ):
+    extra_flags = extra_flags if extra_flags is not None else {}
+    collapse_template_vars_level: int | None = extra_flags.get(
+        'collapse_template_vars_level', 1
+    )
+
+    def render_template_str():
+      return pg.Html.element(
+          'div',
+          [
+              pg.Html.element('span', [self.template_str])
+          ],
+          css_classes=['template-str'],
+      )
+
+    def render_fields():
+      return view.complex_value(
+          {k: v for k, v in self.sym_items()},
+          name='fields',
+          root_path=root_path,
+          parent=self,
+          exclude_keys=['template_str', 'clean'],
+          collapse_level=max(
+              collapse_template_vars_level, collapse_level
+          ) if collapse_level is not None else None,
+          extra_flags=extra_flags,
+          debug=debug,
+          **view.get_passthrough_kwargs(
+              remove=['exclude_keys'],
+              **kwargs,
+          )
+      )
+
+    return pg.views.html.controls.TabControl([
+        pg.views.html.controls.Tab(
+            'template_str',
+            render_template_str(),
+        ),
+        pg.views.html.controls.Tab(
+            'variables',
+            render_fields(),
+        ),
+    ], selected=1)
+
+  @classmethod
+  def _html_tree_view_css_styles(cls) -> list[str]:
+    return super()._html_tree_view_css_styles() + [
+        """
+        /* Langfun Template styles. */
+        .template-str {
+            padding: 10px;
+            margin: 10px 5px 10px 5px;
+            font-style: italic;
+            font-size: 1.1em;
+            white-space: pre-wrap;
+            border: 1px solid #EEE;
+            border-radius: 5px;
+            background-color: #EEE;
+            color: #cc2986;
+        }
+        """
+    ]
+
+  @classmethod
+  @functools.cache
+  def _html_tree_view_config(cls) -> dict[str, Any]:
+    return pg.views.HtmlTreeView.get_kwargs(
+        super()._html_tree_view_config(),
+        dict(
+            css_classes=['lf-template'],
+        )
+    )
+
 
 # Register converter from str to LangFunc, therefore we can always
 # pass strs to attributes that accept LangFunc.

langfun/core/template_test.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 """Template test."""
 import inspect
+from typing import Any
 import unittest
 
 from langfun.core import component
@@ -98,6 +99,21 @@ class BasicTest(unittest.TestCase):
     self.assertEqual(d.z.render(), 'Bye, 1')
     self.assertEqual(d.p.render(), 'Again Hello, 1')
 
+  def test_raw_text(self):
+    self.assertEqual(
+        Template(
+            '{{a}}' + Template.raw_str('\n{{d}}, {%x%}\n') + '{{b}}',
+            a='hi', b=1
+        ).render().text,
+        'hi\n{{d}}, {%x%}\n1'
+    )
+
+  def test_from_raw_str(self):
+    self.assertEqual(
+        Template.from_raw_str('\n{{d}}, {%x%}\n').render().text,
+        '\n{{d}}, {%x%}\n'
+    )
+
 
 class DefinitionTest(unittest.TestCase):
 
@@ -309,7 +325,7 @@ class RenderTest(unittest.TestCase):
         Template(
             'This is {{ x }} and {{ a }}', x=1, a=CustomModality('foo')
         ).render(),
-        'This is 1 and {{a}}',
+        'This is 1 and <<[[a]]>>',
     )
 
   def test_render_with_default(self):
@@ -537,5 +553,59 @@ class TemplateRenderEventTest(unittest.TestCase):
     self.assertEqual(render_stacks, [[l]])
 
 
+class HtmlTest(unittest.TestCase):
+
+  def test_html(self):
+
+    class Foo(Template):
+      """Template Foo.
+
+      {{x}} + {{y}} = ?
+      """
+      x: Any
+      y: Any
+
+    class Bar(Template):
+      """Template Bar.
+
+      {{y}} + {{z}}
+      """
+      y: Any
+
+    self.assertIn(
+        inspect.cleandoc(
+            """
+            /* Langfun Template styles. */
+            .template-str {
+                padding: 10px;
+                margin: 10px 5px 10px 5px;
+                font-style: italic;
+                font-size: 1.1em;
+                white-space: pre-wrap;
+                border: 1px solid #EEE;
+                border-radius: 5px;
+                background-color: #EEE;
+                color: #cc2986;
+            }
+            """
+        ),
+        Foo(x=1, y=2).to_html().style_section,
+    )
+    self.assertIn(
+        'template-str',
+        Foo(x=Bar('{{y}} + {{z}}'), y=1).to_html(
+            enable_summary_tooltip=False,
+        ).content,
+    )
+    self.assertIn(
+        'template-str',
+        Foo(x=Bar('{{y}} + {{z}}'), y=1).to_html(
+            enable_summary_tooltip=False,
+            collapse_level=0,
+            key_style='label',
+        ).content,
+    )
+
+
 if __name__ == '__main__':
   unittest.main()

langfun/core/templates/conversation.py

@@ -38,6 +38,11 @@ class Conversation(Completion):
       '(Optional) Preamble before beginning the conversation.',
   ] = None
 
+  role: Annotated[
+      str | None,
+      '(Optional) User defined role for the AI response in the conversation.',
+  ] = None
+
   conversation_context: Annotated[
       lf.LangFunc | None,
       (
@@ -71,6 +76,10 @@ class Conversation(Completion):
     with lf.context(**kwargs):
       # Call LM based on the prompt generated from `input_message`.
       lm_response = super().__call__()
+      if self.role is not None:
+        lm_response.rebind(
+            sender=self.role, skip_notification=True, raise_on_no_change=False
+        )
 
       # Add current turn to memory.
       self.add(self.input_message, lm_response)

langfun/core/templates/conversation_test.py

@@ -83,6 +83,7 @@ class ConversationTest(unittest.TestCase):
   def test_call(self):
     c = Conversation(
         lm=QuestionCounter(),
+        role='Agent',
         preamble="You are a helpful and joyful AI bot. Now let's chat.",
     )
     # First round.
@@ -102,7 +103,7 @@ class ConversationTest(unittest.TestCase):
         inspect.cleandoc("""
         You are a helpful and joyful AI bot. Now let's chat.
         User: Hello
-        AI: Response 1.
+        Agent: Response 1.
         User: How are you?
         """),
     )
@@ -114,9 +115,9 @@ class ConversationTest(unittest.TestCase):
         inspect.cleandoc("""
         You are a helpful and joyful AI bot. Now let's chat.
         User: Hello
-        AI: Response 1.
+        Agent: Response 1.
         User: How are you?
-        AI: Response 2.
+        Agent: Response 2.
         User: Okay, bye.
         """),
     )

langfun/core/templates/selfplay_test.py

@@ -57,7 +57,11 @@ class SelfPlayTest(unittest.TestCase):
 
     with lf.context(lm=NumberGuesser(guesses=[50, 20, 5, 10])):
       self.assertEqual(
-          g(), lf.AIMessage('10', score=0.0, logprobs=None, usage=None)
+          g(),
+          lf.AIMessage(
+              '10', score=0.0, logprobs=None, is_cached=False,
+              usage=lf.UsageNotAvailable()
+          )
       )
 
     self.assertEqual(g.num_turns, 4)
@@ -67,7 +71,11 @@ class SelfPlayTest(unittest.TestCase):
 
     with lf.context(lm=NumberGuesser(guesses=[50, 20, 5, 2, 5, 4])):
       self.assertEqual(
-          g(), lf.AIMessage('2', score=0.0, logprobs=None, usage=None)
+          g(),
+          lf.AIMessage(
+              '2', score=0.0, logprobs=None, is_cached=False,
+              usage=lf.UsageNotAvailable()
+          )
       )
 
     self.assertEqual(g.num_turns, 10)

langfun-0.1.2.dev202501150804.dist-info/METADATA

@@ -0,0 +1,225 @@
+Metadata-Version: 2.2
+Name: langfun
+Version: 0.1.2.dev202501150804
+Summary: Langfun: Language as Functions.
+Home-page: https://github.com/google/langfun
+Author: Langfun Authors
+Author-email: langfun-authors@google.com
+License: Apache License 2.0
+Keywords: llm generative-ai machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyglove>=0.4.5.dev202409110000
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: requests>=2.31.0
+Provides-Extra: all
+Requires-Dist: pyglove>=0.4.5.dev202409110000; extra == "all"
+Requires-Dist: jinja2>=3.1.2; extra == "all"
+Requires-Dist: requests>=2.31.0; extra == "all"
+Requires-Dist: termcolor==1.1.0; extra == "all"
+Requires-Dist: tqdm>=4.64.1; extra == "all"
+Requires-Dist: google-auth>=2.16.0; extra == "all"
+Requires-Dist: python-magic>=0.4.27; extra == "all"
+Requires-Dist: python-docx>=0.8.11; extra == "all"
+Requires-Dist: pillow>=10.0.0; extra == "all"
+Requires-Dist: openpyxl>=3.1.0; extra == "all"
+Requires-Dist: pandas>=2.0.3; extra == "all"
+Provides-Extra: ui
+Requires-Dist: termcolor==1.1.0; extra == "ui"
+Requires-Dist: tqdm>=4.64.1; extra == "ui"
+Provides-Extra: vertexai
+Requires-Dist: google-auth>=2.16.0; extra == "vertexai"
+Provides-Extra: mime
+Requires-Dist: python-magic>=0.4.27; extra == "mime"
+Requires-Dist: python-docx>=0.8.11; extra == "mime"
+Requires-Dist: pillow>=10.0.0; extra == "mime"
+Requires-Dist: openpyxl>=3.1.0; extra == "mime"
+Requires-Dist: pandas>=2.0.3; extra == "mime"
+Provides-Extra: mime-auto
+Requires-Dist: python-magic>=0.4.27; extra == "mime-auto"
+Provides-Extra: mime-docx
+Requires-Dist: python-docx>=0.8.11; extra == "mime-docx"
+Provides-Extra: mime-pil
+Requires-Dist: pillow>=10.0.0; extra == "mime-pil"
+Provides-Extra: mime-xlsx
+Requires-Dist: openpyxl>=3.1.0; extra == "mime-xlsx"
+Requires-Dist: pandas>=2.0.3; extra == "mime-xlsx"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/google/langfun/main/docs/_static/logo.svg" width="520px" alt="logo"></img>
+</div>
+
+# Langfun
+
+[![PyPI version](https://badge.fury.io/py/langfun.svg)](https://badge.fury.io/py/langfun)
+[![codecov](https://codecov.io/gh/google/langfun/branch/main/graph/badge.svg)](https://codecov.io/gh/google/langfun)
+![pytest](https://github.com/google/langfun/actions/workflows/ci.yaml/badge.svg)
+
+[**Installation**](#install) | [**Getting started**](#hello-langfun) | [**Tutorial**](https://colab.research.google.com/github/google/langfun/blob/main/docs/notebooks/langfun101.ipynb) | [**Discord community**](https://discord.gg/U6wPN9R68k)
+
+## Introduction
+
+Langfun is a [PyGlove](https://github.com/google/pyglove) powered library that
+aims to *make language models (LM) fun to work with*. Its central principle is
+to enable seamless integration between natural language and programming by
+treating language as functions. Through the introduction of *Object-Oriented Prompting*, 
+Langfun empowers users to prompt LLMs using objects and types, offering enhanced
+control and simplifying agent development.
+
+To unlock the magic of Langfun, you can start with
+[Langfun 101](https://colab.research.google.com/github/google/langfun/blob/main/docs/notebooks/langfun101.ipynb). Notably, Langfun is compatible with popular LLMs such as Gemini, GPT,
+Claude, all without the need for additional fine-tuning.
+
+## Why Langfun?
+
+Langfun is *powerful and scalable*:
+
+*   Seamless integration between natural language and computer programs.
+*   Modular prompts, which allows a natural blend of texts and modalities;
+*   Efficient for both request-based workflows and batch jobs;
+*   A powerful eval framework that thrives dimension explosions.
+
+Langfun is *simple and elegant*:
+
+*   An intuitive programming model, graspable in 5 minutes;
+*   Plug-and-play into any Python codebase, making an immediate difference;
+*   Comprehensive LLMs under a unified API: Gemini, GPT, Claude, Llama3, and more.
+*   Designed for agile developement: offering intellisense, easy debugging, with minimal overhead;
+
+## Hello, Langfun
+
+```python
+import langfun as lf
+import pyglove as pg
+
+from IPython import display
+
+class Item(pg.Object):
+  name: str
+  color: str
+
+class ImageDescription(pg.Object):
+  items: list[Item]
+
+image = lf.Image.from_uri('https://upload.wikimedia.org/wikipedia/commons/thumb/8/83/Solar_system.jpg/1646px-Solar_system.jpg')
+display.display(image)
+
+desc = lf.query(
+    'Describe objects in {{my_image}} from top to bottom.',
+    ImageDescription,
+    lm=lf.llms.Gpt4o(api_key='<your-openai-api-key>'),
+    my_image=image,
+)
+print(desc)
+```
+*Output:*
+
+<img src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/83/Solar_system.jpg/1646px-Solar_system.jpg" width="520px" alt="my_image"></img>
+
+```
+ImageDescription(
+  items = [
+    0 : Item(
+      name = 'Mercury',
+      color = 'Gray'
+    ),
+    1 : Item(
+      name = 'Venus',
+      color = 'Yellow'
+    ),
+    2 : Item(
+      name = 'Earth',
+      color = 'Blue and white'
+    ),
+    3 : Item(
+      name = 'Moon',
+      color = 'Gray'
+    ),
+    4 : Item(
+      name = 'Mars',
+      color = 'Red'
+    ),
+    5 : Item(
+      name = 'Jupiter',
+      color = 'Brown and white'
+    ),
+    6 : Item(
+      name = 'Saturn',
+      color = 'Yellowish-brown with rings'
+    ),
+    7 : Item(
+      name = 'Uranus',
+      color = 'Light blue'
+    ),
+    8 : Item(
+      name = 'Neptune',
+      color = 'Dark blue'
+    )
+  ]
+)
+```
+See [Langfun 101](https://colab.research.google.com/github/google/langfun/blob/main/docs/notebooks/langfun101.ipynb) for more examples.
+
+## Install
+
+Langfun offers a range of features through [Extras](https://packaging.python.org/en/latest/tutorials/installing-packages/#installing-extras), allowing users to install only what they need. The minimal installation of Langfun requires only [PyGlove](https://github.com/google/pyglove), [Jinja2](https://github.com/pallets/jinja/), and [requests](https://github.com/psf/requests). To install Langfun with its minimal dependencies, use:
+
+```
+pip install langfun
+```
+
+For a complete installation with all dependencies, use:
+
+```
+pip install langfun[all]
+```
+
+To install a nightly build, include the `--pre` flag, like this:
+
+```
+pip install langfun[all] --pre
+```
+
+If you want to customize your installation, you can select specific features using package names like `langfun[X1, X2, ..., Xn]`, where `Xi` corresponds to a tag from the list below:
+
+| Tag                 |  Description                             |
+| ------------------- | ---------------------------------------- |
+| all                 | All Langfun features.                    |
+| vertexai            | VertexAI access.                         |
+| mime                | All MIME supports.                       |
+| mime-auto           | Automatic MIME type detection.           |
+| mime-docx           | DocX format support.                     |
+| mime-pil            | Image support for PIL.                   |
+| mime-xlsx           | XlsX format support.                     |
+| ui                  | UI enhancements                          |
+
+
+For example, to install a nightly build that includes VertexAI access, full modality support, and UI enhancements, use:
+```
+pip install langfun[vertexai,mime,ui] --pre
+```
+
+*Disclaimer: this is not an officially supported Google product.*