langfun 0.1.2.dev202511030805__tar.gz → 0.1.2.dev202511050805__tar.gz

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/PKG-INFO

@@ -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

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/agentic/action.py

@@ -36,7 +36,12 @@ class ActionTimeoutError(ActionError):
 
 
 class Action(pg.Object):
-  """Base class for Langfun's agentic actions.
+  """Base class for agentic actions.
+
+  An `Action` represents a single, executable step or task that an agent can
+  perform, such as calling a tool, querying a language model, or returning a
+  final answer. Actions are designed to be composable and trackable within a
+  `Session`.
 
   # Developing Actions
 
@@ -149,7 +154,7 @@ class Action(pg.Object):
 
   # Explicitly create and pass a session.
   with lf.Session(id='my_agent_session') as session:
-    result = calc(session=session) # Pass the session explicitly
+    result = calc(session=session)  # Pass the session explicitly
     print(result)
   ```
 
@@ -320,7 +325,14 @@ TracedItem = Union[
 
 
 class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
-  """Trace of the execution of an action."""
+  """Trace of an execution, containing queries, logs, and sub-actions.
+
+  `ExecutionTrace` records the sequence of operations performed during an
+  action's execution or within a specific phase of execution (demarcated by
+  `session.track_phase`). It captures `lf.query` calls, log entries, and
+  nested `ActionInvocation` objects in the order they occurred. It also
+  aggregates LLM usage summaries from its child items.
+  """
 
   name: Annotated[
       str | None,
@@ -328,7 +340,7 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
           'The name of the execution trace. If None, the trace is unnamed, '
           'which is the case for the top-level trace of an action. An '
           'execution trace could have sub-traces, called phases, which are '
-          'created and named by `session.phase()` context manager.'
+          'created and named by `session.track_phase()` context manager.'
       )
   ] = None
 
@@ -362,7 +374,7 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
     self.__dict__.pop('id', None)
 
   def indexof(self, item: TracedItem, count_item_cls: Type[Any]) -> int:
-    """Returns the index of the child items of given type."""
+    """Returns the index of the child item of given type."""
     pos = 0
     for x in self._iter_children(count_item_cls):
       if x is item:
@@ -787,7 +799,12 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
 
 
 class ParallelExecutions(pg.Object, pg.views.html.HtmlTreeView.Extension):
-  """A class for encapsulating parallel execution traces."""
+  """A container for multiple parallel execution traces.
+
+  When `session.concurrent_map` is used, it creates a `ParallelExecutions`
+  object to hold an `ExecutionTrace` for each parallel branch of execution,
+  allowing inspection of parallel workflows.
+  """
 
   name: Annotated[
       str | None,
@@ -876,7 +893,14 @@ class ParallelExecutions(pg.Object, pg.views.html.HtmlTreeView.Extension):
 
 
 class ActionInvocation(pg.Object, pg.views.html.HtmlTreeView.Extension):
-  """A class for capturing the invocation of an action."""
+  """An invocation of an action, capturing its execution and result.
+
+  `ActionInvocation` represents a single call to an `Action`. It contains
+  the `Action` object itself, its result or error, associated metadata,
+  and an `ExecutionTrace` detailing the steps taken during its execution
+  (queries, logs, sub-actions). Invocations form a tree structure within a
+  `Session`, reflecting the hierarchy of agentic operations.
+  """
 
   action: Annotated[
       Action,
@@ -1406,7 +1430,50 @@ class SessionLogging(SessionEventHandler):
 
 
 class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
-  """Session for performing an agentic task."""
+  """Manages the execution trajectory of agentic actions.
+
+  A `Session` tracks the execution of a root `Action` and all its
+  sub-actions, including LLM queries (`lf.query`), logging messages,
+  and nested actions. It provides a complete, hierarchical trace of an
+  agent's workflow, which is important for debugging, analysis, and
+  visualization.
+
+  Sessions can be created implicitly when an action is called without an
+  active session, or explicitly for more control.
+
+  **1. Implicit Session:**
+  When an action is called without a session, Langfun creates one automatically.
+
+  ```python
+  action = MyAction()
+  action()
+  session = action.session  # Access the implicit session
+  ```
+
+  **2. Explicit Session:**
+  Use a `with` statement to manage a session explicitly. This is useful for
+  setting session IDs or capturing the trajectory of multiple top-level actions.
+
+  ```python
+  with lf.Session(id='my-session') as session:
+    action1()
+    action2()
+  ```
+
+  **3. Accessing Trajectory:**
+  The `session.root` attribute provides access to the `ActionInvocation` tree.
+
+  ```python
+  with lf.Session() as session:
+    my_action()
+
+  # Get all queries in the session
+  print(session.all_queries)
+
+  # Get all top-level action calls in the session
+  print(session.root.actions)
+  ```
+  """
 
   root: Annotated[
       ActionInvocation,
@@ -1559,7 +1626,7 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
       )
 
   def update_progress(self, title: str, **kwargs: Any) -> None:
-    """Update the progress of current action's execution.
+    """Updates the progress of current action's execution.
 
     Args:
       title: The title of the progress update.

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/agentic/action_eval.py

@@ -24,7 +24,14 @@ import pyglove as pg
 
 
 class ActionEval(lf.eval.v2.Evaluation):
-  """Agent evaluation."""
+  """Evaluation for agentic actions.
+
+  `ActionEval` is a specialized evaluation class for executing and evaluating
+  agentic actions based on provided inputs. Each input example is expected to
+  contain an `action` attribute. The `process` method executes the action
+  within a dedicated `Session`, captures the final result, and returns it
+  along with the session details in the metadata.
+  """
 
   action_args: Annotated[
       dict[str, Any],
@@ -68,7 +75,7 @@ class ExampleView(pg.Object):
 class ActionEvalV1(lf_eval.Matching):
   """Base class for action evaluations.
 
-  The input function should returns a list of pg.Dict, with `action` and
+  The input function should return a list of pg.Dict, with `action` and
   `groundtruth` fields.
   """
   # We override the schema and prompt to dummy values since they are not used.

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/async_support.py

@@ -11,7 +11,7 @@
 # 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.
-"""Utility for async IO in Langfun."""
+"""Utilities for asynchronous programming in Langfun."""
 
 import asyncio
 import contextlib
@@ -23,7 +23,20 @@ import pyglove as pg
 async def invoke_async(
     sync_callable: Callable[..., Any], *args, **kwargs
 ) -> Any:
-  """Invokes a callable asynchronously with `lf.context` manager enabled."""
+  """Invokes a sync callable asynchronously in a separate thread.
+
+  This is useful for wrapping a sync function into an async function,
+  allowing multiple calls of the sync function to run concurrently.
+  `lf.context` will be propagated to the thread that runs the sync callable.
+
+  Args:
+    sync_callable: The sync callable to invoke.
+    *args: Positional arguments to pass to the callable.
+    **kwargs: Keyword arguments to pass to the callable.
+
+  Returns:
+    An awaitable that resolves to the return value of the sync_callable.
+  """
   return await asyncio.to_thread(
       # Enable `lf.context` manager for async calls.
       pg.with_contextual_override(sync_callable), *args, **kwargs
@@ -35,7 +48,23 @@ def invoke_sync(
     *args,
     **kwargs
 ) -> Any:
-  """Invokes a async callable synchronously."""
+  """Invokes an async callable synchronously.
+
+  This is useful for calling an async function from a sync context.
+  If there is an existing async event loop in current thread managed by
+  `lf.sync_context_manager`, it will be used for running the async callable.
+  Otherwise, `anyio.run` will be used to run the async callable in a new
+  event loop.
+  `lf.context` will be propagated to the async callable.
+
+  Args:
+    async_callable: The async callable to invoke.
+    *args: Positional arguments to pass to the callable.
+    **kwargs: Keyword arguments to pass to the callable.
+
+  Returns:
+    The return value of the async_callable.
+  """
   async def _invoke():
     return await async_callable(*args, **kwargs)
   invoke_fn = pg.with_contextual_override(_invoke)

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/coding/python/correction.py

@@ -19,13 +19,23 @@ import pyglove as pg
 
 
 class CodeWithError(pg.Object):
-  """Python code with error."""
+  """A structure representing Python code along with an execution error.
+
+  This is used as input to a language model for error correction, providing
+  the model with the code that failed and the error message it produced.
+  """
 
   code: str
   error: str
 
 
 class CorrectedCode(pg.Object):
+  """A structure containing corrected Python code.
+
+  This is used as the output schema when asking a language model to correct
+  code, expecting the model to return the fixed code in the `corrected_code`
+  field.
+  """
   corrected_code: str
 
 
@@ -49,7 +59,7 @@ def run_with_correction(
     code: The source code that may or may not be problematic.
     error: An optional initial error for `code` when it's problematic, usually
       caught from elsewhere when it ran. If None, code will be executed once to
-      verify if its good and obtain a feedback error message.
+      verify if it's good and obtain a feedback error message.
     global_vars: A dict of str to value as the global variables that could be
       accessed within the corrected code.
     lm: Language model to be used. If not specified, it will try to use the `lm`
@@ -57,15 +67,15 @@ def run_with_correction(
     max_attempts: Max number of attempts for the correction.
     sandbox: If True, run code in sandbox; If False, run code in current
       process. If None, run in sandbox first, if the output could not be
-      serialized and pass to current process, run the code again in current
+      serialized and passed to current process, run the code again in current
       process.
     permission: The permission to run the code.
     timeout: The timeout for running the corrected code. If None, there is no
       timeout. Applicable only when sandbox is set to True.
     returns_code: If True, the return value is a tuple of (result, final code).
       Otherwise the return value is the result only.
-    returns_stdout: If True, the stdout (a str) will be returned.
-    outputs_intermediate: If True, intermediate output will be outputted as a
+    returns_stdout: If True, the stdout (a string) will be returned.
+    outputs_intermediate: If True, intermediate output will be output as a
       dict, with the last line's value accessible by key '__result__'. Otherwise
       the value of the last line will be returned.
 
@@ -161,7 +171,7 @@ def correct(
     code: The source code that may or may not be problematic.
     error: An optional initial error for `code` when it's problematic, usually
       caught from elsewhere when it ran. If None, code will be executed once to
-      verify if its good and obtain a feedback error message.
+      verify if it's good and obtain a feedback error message.
     global_vars: A dict of str to value as the global variables that could be
       accessed within the corrected code.
     lm: Language model to be used. If not specified, it will try to use the `lm`
@@ -169,7 +179,7 @@ def correct(
     max_attempts: Max number of attempts for the correction.
     sandbox: If True, run code in sandbox; If False, run code in current
       process. If None, run in sandbox first, if the output could not be
-      serialized and pass to current process, run the code again in current
+      serialized and passed to current process, run the code again in current
       process.
     timeout: The timeout for running the corrected code. If None, there is no
       timeout. Applicable only when sandbox is set to True.
@@ -193,7 +203,7 @@ def correct(
 
 
 def _error_feedback_str(error: Exception) -> str:
-  """Returns the error str for feedback."""
+  """Returns the error string for feedback."""
   if isinstance(error, pg.coding.CodeError):
     return pg.decolor(error.format(include_complete_code=False))
   else:
@@ -201,7 +211,7 @@ def _error_feedback_str(error: Exception) -> str:
 
 
 def _maybe_custom_validate(result: Any) -> Any:
-  """Apply custom validation through __validate_generation__ method."""
+  """Applies custom validation through __validate__ method."""
   if isinstance(result, dict) and "__result__" in result:
     r = result["__result__"]
   else:

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/coding/python/execution.py

@@ -45,17 +45,17 @@ def evaluate(
     global_vars: An optional dict as the globals that could be referenced by the
       code.
     permission: Permission for the Python code to run.
-    returns_stdout: If True, the stdout (a str) will be returned.
+    returns_stdout: If True, the stdout (a string) will be returned.
     outputs_intermediate: Applicable when returns_stdout is False. If True,
-      intermediate output will be outputted as a dict, with the last line's
-      value accessible by key '__result__' and the std output accessible by
+      intermediate output will be output as a dict, with the last line's
+      value accessible by key '__result__' and the stdout accessible by
       key '__stdout__'. Otherwise the value of the last line will be returned.
 
   Returns:
     The value of the last line of the code block. Or a dict of variable
     names of all locals to their evaluated values as the output of the code to
     run. The value for the last line can be accessed by key '__result__'. Or the
-    stdout as a str.
+    stdout as a string.
   """
   return pg.coding.evaluate(
       parsing.clean(code),
@@ -85,28 +85,30 @@ def run(
 
   Args:
     code: Python code to run.
-    global_vars: An optional dict of
+    global_vars: An optional dict as the globals that could be referenced by the
+      code.
     permission: Permission for the Python code to run.
-    returns_stdout: If True, the stdout (a str) will be returned.
+    returns_stdout: If True, the stdout (a string) will be returned.
     outputs_intermediate: Applicable when returns_stdout is False. If True,
-      intermediate output will be outputted as a dict, with the last line's
-      value accessible by key '__result__' and the std output accessible by
+      intermediate output will be output as a dict, with the last line's
+      value accessible by key '__result__' and the stdout accessible by
       key '__stdout__'. Otherwise the value of the last line will be returned.
     sandbox: If True, run code in sandbox; If False, run code in current
       process. If None, run in sandbox first, if the output could not be
-      serialized and pass to current process, run the code again in current
+      serialized and passed to current process, run the code again in current
       process.
-    timeout: Execution timeout in seconds. If None, wait the code the complete.
+    timeout: Execution timeout in seconds. If None, wait for the code to
+      complete.
 
   Returns:
     The value of the last line of the code block. Or a dict of variable
     names of all locals to their evaluated values as the output of the code to
     run. The value for the last line can be accessed by key '__result__'. Or the
-    stdout as a str.
+    stdout as a string.
 
   Raises:
     TimeoutError: If the execution time exceeds the timeout.
-    Exception: Exception  that are raised from the code.
+    Exception: Exceptions that are raised from the code.
   """
   return pg.coding.run(
       parsing.clean(code),

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/coding/python/generation.py

@@ -22,9 +22,13 @@ import pyglove as pg
 
 
 class PythonCode(pg.Object):
-  """Symbolic class for Python code.
+  """Represents a piece of Python code that can be executed.
 
-  The value of the last expression of the source will be the returned value.
+  When `PythonCode` is instantiated within a `PythonCode.auto_run()` context,
+  it automatically executes the code and returns the result of the last
+  expression. Otherwise, it acts as a container for the source code, which
+  can be executed by calling the instance. The class also supports automatic
+  error correction via `lf.coding.run_with_correction` when called.
   """
 
   source: Annotated[
@@ -56,7 +60,7 @@ class PythonCode(pg.Object):
         Otherwise, auto call will be disabled.
       sandbox: If True, run code in sandbox; If False, run code in current
         process. If None, run in sandbox first, if the output could not be
-        serialized and pass to current process, run the code again in current
+        serialized and passed to current process, run the code again in current
         process. Applicable when `enabled` is set to True.
       timeout: Timeout in seconds. Applicable when both `enabled` and `sandbox`
         are set to True.
@@ -98,17 +102,17 @@ class PythonCode(pg.Object):
     Args:
       sandbox: If True, run code in sandbox; If False, run code in current
         process. If None, run in sandbox first, if the output could not be
-        serialized and pass to current process, run the code again in current
+        serialized and passed to current process, run the code again in current
         process.
       timeout: Timeout in seconds. If None, there is no timeout. Applicable when
         sandbox is set to True.
       global_vars: Global variables that could be accessed from the source code.
-      returns_stdout: If True, the stdout (a str) will be returned.
+      returns_stdout: If True, the stdout (a string) will be returned.
       outputs_intermediate: Applicable when returns_stdout is False. If True,
-        intermediate output will be outputted as a dict, with the last line's
-        value accessible by key '__result__' and the std output accessible by 
+        intermediate output will be output as a dict, with the last line's
+        value accessible by key '__result__' and the stdout accessible by
         key '__stdout__'. Otherwise the value of the last line will be returned.
-      autofix: Number of attempts to auto fix the generated code. If 0, autofix
+      autofix: Number of attempts to autofix the generated code. If 0, autofix
         is disabled.
       autofix_lm: Language model to be used. If not specified, it will try to
         use the `lm` under `lf.context`.
@@ -117,8 +121,8 @@ class PythonCode(pg.Object):
       The value of the last expression in the source code. Or a dict of local
       variable names defined in the source code to their values if
       `outputs_intermediate` is set to True. The value for the last line can be
-      accessed by key '__result__'. Or the stdout as a str if `returns_stdout`
-      is set to True.
+      accessed by key '__result__'. Or the stdout as a string if
+      `returns_stdout` is set to True.
 
     Raises:
       TimeoutError: If `sandbox` is True and timeout has reached.
@@ -152,12 +156,12 @@ class PythonCode(pg.Object):
     Args:
       sandbox: If True, run code in sandbox; If False, run code in current
         process. If None, run in sandbox first, if the output could not be
-        serialized and pass to current process, run the code again in current
+        serialized and passed to current process, run the code again in current
         process.
       timeout: Timeout in seconds. If None, there is no timeout. Applicable when
         sandbox is set to True.
       global_vars: Global variables that could be accessed from the source code.
-      autofix: Number of attempts to auto fix the generated code. If 0, autofix
+      autofix: Number of attempts to autofix the generated code. If 0, autofix
         is disabled. Auto-fix is not supported for 'json' protocol.
       autofix_lm: Language model to be used. If not specified, it will try to
         use the `lm` under `lf.context`.
@@ -182,10 +186,11 @@ class PythonCode(pg.Object):
 
 
 class PythonFunction(pg.Object):
-  """Generated Python function via source code.
+  """Represents a Python function defined by source code.
 
-  The source code will be directly passed into eval() for execution and the
-  output of the function will be returned.
+  This class takes Python source code that defines a function and makes it
+  callable. The source code is evaluated to create a function object, which
+  can then be invoked like a regular Python function.
   """
 
   name: str
@@ -214,7 +219,7 @@ class PythonFunction(pg.Object):
       *args: Positional arguments that will be passed to the implementation.
       sandbox: If True, run code in sandbox; If False, run code in current
         process. If None, run in sandbox first, if the output could not be
-        serialized and pass to current process, run the code again in current
+        serialized and passed to current process, run the code again in current
         process.
       timeout: Timeout in seconds. If None, there is no timeout. Applicable when
         sandbox is set to True.

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/coding/python/sandboxing.py

@@ -23,7 +23,14 @@ import pyglove as pg
 
 
 class SandboxOutput(pg.Object):
-  """Sandbox output."""
+  """A structure containing the output from a sandbox execution.
+
+  Attributes:
+    stdout: The standard output captured during execution.
+    stderr: The standard error captured during execution.
+    output_files: A dictionary of file names to their byte content for files
+      generated during execution.
+  """
 
   stdout: Annotated[
       str,
@@ -42,7 +49,14 @@ class SandboxOutput(pg.Object):
 
 
 class BaseSandbox(pg.Object):
-  """Interface and partial implementation for Python sandbox."""
+  """Base class for Python code sandboxing.
+
+  A sandbox provides an isolated environment for executing Python code,
+  typically with restrictions on file system access, network calls, or other
+  potentially harmful operations. This base class defines the interface for
+  sandboxes, including methods for running code (`run`), uploading files
+  (`upload`), and managing the sandbox lifecycle (`setup`, `cleanup`).
+  """
 
   def _on_bound(self):
     super()._on_bound()
@@ -111,7 +125,13 @@ class BaseSandbox(pg.Object):
 
 
 class MultiProcessingSandbox(BaseSandbox):
-  """Sandbox using multiprocessing."""
+  """A sandbox implementation using Python's `multiprocessing`.
+
+  This sandbox executes code in a separate process, providing isolation from
+  the main process. It uses a temporary directory for file operations,
+  which is cleaned up when the sandbox is closed. It relies on
+  `pg.coding.run` with `sandbox=True` for execution.
+  """
 
   def _on_bound(self):
     super()._on_bound()

{langfun-0.1.2.dev202511030805 → langfun-0.1.2.dev202511050805}/langfun/core/component.py

@@ -11,7 +11,7 @@
 # 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.
-"""langfun Component."""
+"""Base component for Langfun."""
 
 from typing import ContextManager
 import pyglove as pg
@@ -22,7 +22,37 @@ RAISE_IF_HAS_ERROR = (pg.MISSING_VALUE,)
 
 
 class Component(pg.ContextualObject):
-  """Base class for langfun components."""
+  """Base class for Langfun components.
+
+  Langfun components are context-aware symbolic objects powered by PyGlove.
+  (See [PyGlove basics](https://pyglove.readthedocs.io/en/latest/basics.html)
+  for more details).
+
+  **Context-awareness**
+
+  Langfun components can have contextual attributes using `lf.contextual`,
+  whose values can be provided or overridden via `lf.context` or
+  `lf.use_settings`.
+
+  Example:
+  ```python
+  import langfun as lf
+
+  class Bar(lf.Component):
+    y = lf.contextual(1)
+
+  class Foo(lf.Component):
+    x = lf.contextual(0)
+    bar = Bar()
+
+  f = Foo()
+  assert f.x == 0 and f.bar.y == 1
+
+  # `lf.context` overrides `lf.contextual` attributes.
+  with lf.context(x=10, y=20):
+    assert f.x == 10 and f.bar.y == 20
+  ```
+  """
 
   # Allow symbolic assignment, which invalidates the object and recomputes
   # states upon update.
@@ -78,6 +108,15 @@ def use_settings(
 ) -> ContextManager[dict[str, pg.utils.ContextualOverride]]:
   """Shortcut method for overriding component attributes.
 
+  Example:
+
+  ```
+  with lf.use_settings(
+      lm=lf.llms.Gpt35(),
+      temperature=0.0):
+    lf.query('who are you?')
+  ```
+
   Args:
     cascade: If True, this override will apply to both current scope and nested
       scope, meaning that this `lf.context` will take precedence over all
@@ -85,6 +124,6 @@ def use_settings(
     **settings: Key/values as override for component attributes.
 
   Returns:
-    A dict of attribute names to their contextual overrides.
+    A context manager for overriding settings.
   """
   return context(cascade=cascade, override_attrs=True, **settings)