langfun 0.1.2.dev202504270803__py3-none-any.whl → 0.1.2.dev202504290805__py3-none-any.whl

langfun/core/agentic/action.py

@@ -15,6 +15,7 @@
 
 import abc
 import contextlib
+import functools
 import threading
 import time
 import typing
@@ -31,8 +32,7 @@ class Action(pg.Object):
   def _on_bound(self):
     super()._on_bound()
     self._session = None
-    self._result = None
-    self._metadata = {}
+    self._invocation: ActionInvocation | None = None
 
   @property
   def session(self) -> Optional['Session']:
@@ -42,12 +42,12 @@ class Action(pg.Object):
   @property
   def result(self) -> Any:
     """Returns the result of the action."""
-    return self._result
+    return self._invocation.result if self._invocation else None
 
   @property
   def metadata(self) -> dict[str, Any] | None:
     """Returns the metadata associated with the result from previous call."""
-    return self._metadata
+    return self._invocation.metadata if self._invocation else None
 
   def __call__(
       self,
@@ -58,31 +58,57 @@ class Action(pg.Object):
       **kwargs
   ) -> Any:
     """Executes the action."""
-    new_session = session is None
-    if new_session:
+    if session is None:
       session = Session()
       if show_progress:
         lf.console.display(pg.view(session, name='agent_session'))
 
-    with session.track_action(self):
-      if verbose:
-        session.info(f'Executing action {self!r}...', keep=False)
-
-      result = self.call(session=session, verbose=verbose, **kwargs)
+      # For the top-level action, we store the session in the metadata.
+      self._session = session
+    else:
+      self._session = None
 
+    with session.track_action(self) as invocation:
       if verbose:
-        session.info(
-            f'Action {self.__class__.__name__} completed successfully.',
-            keep=False,
-            result=result
-        )
+        session.info('Action execution started.', keep=False, action=self)
 
-      # For the top-level action, we store the session in the metadata.
-      if new_session:
-        self._session = session
-      self._result = result
-      self._metadata = session.current_action.metadata
-      return self._result
+      try:
+        result = self.call(session=session, verbose=verbose, **kwargs)
+        self._invocation.end(result)
+        if verbose:
+          session.info(
+              (
+                  f'Action execution succeeded in '
+                  f'{self._invocation.execution.elapse:.2f} seconds.'
+              ),
+              keep=False,
+              result=result
+          )
+      except BaseException as e:
+        error = pg.utils.ErrorInfo.from_exception(e)
+        self._invocation.end(result=None, error=error)
+        if invocation.parent_action is session.root:
+          session.error(
+              (
+                  f'Top-level action execution failed in '
+                  f'{self._invocation.execution.elapse:.2f} seconds.'
+              ),
+              keep=True,
+              action=self,
+              error=error
+          )
+        else:
+          session.warning(
+              (
+                  f'Action execution failed in '
+                  f'{self._invocation.execution.elapse:.2f} seconds.'
+              ),
+              keep=False,
+              action=self,
+              error=error
+          )
+        raise
+      return result
 
   @abc.abstractmethod
   def call(self, session: 'Session', **kwargs) -> Any:
@@ -146,6 +172,38 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
     self._tab_control = None
     self._time_badge = None
 
+  def _on_parent_change(self, *args, **kwargs):
+    super()._on_parent_change(*args, **kwargs)
+    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."""
+    pos = 0
+    for x in self._iter_children(count_item_cls):
+      if x is item:
+        return pos
+      pos += 1
+    return -1
+
+  @functools.cached_property
+  def id(self) -> str:
+    parent = self.sym_parent
+    if isinstance(parent, ActionInvocation):
+      # Current execution trace is the body of an action.
+      return parent.id
+    elif isinstance(parent, pg.List):
+      container = parent.sym_parent
+      if isinstance(container, ExecutionTrace):
+        # Current execution trace is a phase.
+        group_id = (
+            self.name or f'g{container.indexof(self, ExecutionTrace) + 1}'
+        )
+        return f'{container.id}/{group_id}'
+      elif isinstance(container, ParallelExecutions):
+        # Current execution trace is a parallel branch.
+        return f'{container.id}/b{self.sym_path.key + 1}'
+    return ''
+
   def reset(self) -> None:
     """Resets the execution trace."""
     self.rebind(items=[], skip_notification=True, raise_on_no_change=False)
@@ -194,58 +252,59 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
   @property
   def queries(self) -> list[lf_structured.QueryInvocation]:
     """Returns queries from the sequence."""
-    return self._child_items(lf_structured.QueryInvocation)
+    return list(self._iter_children(lf_structured.QueryInvocation))
 
   @property
   def actions(self) -> list['ActionInvocation']:
     """Returns action invocations from the sequence."""
-    return self._child_items(ActionInvocation)
+    return list(self._iter_children(ActionInvocation))
 
   @property
   def logs(self) -> list[lf.logging.LogEntry]:
     """Returns logs from the sequence."""
-    return self._child_items(lf.logging.LogEntry)
+    return list(self._iter_children(lf.logging.LogEntry))
 
   @property
   def all_queries(self) -> list[lf_structured.QueryInvocation]:
     """Returns all queries from current trace and its child execution items."""
-    return self._all_child_items(lf_structured.QueryInvocation)
+    return list(self._iter_subtree(lf_structured.QueryInvocation))
 
   @property
   def all_actions(self) -> list['ActionInvocation']:
     """Returns all actions from current trace and its child execution items."""
-    return self._all_child_items(ActionInvocation)
+    return list(self._iter_subtree(ActionInvocation))
 
   @property
   def all_logs(self) -> list[lf.logging.LogEntry]:
     """Returns all logs from current trace and its child execution items."""
-    return self._all_child_items(lf.logging.LogEntry)
+    return list(self._iter_subtree(lf.logging.LogEntry))
 
-  def _child_items(self, item_cls: Type[Any]) -> list[Any]:
-    child_items = []
+  def _iter_children(self, item_cls: Type[Any]) -> Iterator[TracedItem]:
     for item in self.items:
       if isinstance(item, item_cls):
-        child_items.append(item)
+        yield item
       elif isinstance(item, ExecutionTrace):
-        child_items.extend(item._child_items(item_cls))  # pylint: disable=protected-access
+        for x in item._iter_children(item_cls):  # pylint: disable=protected-access
+          yield x
       elif isinstance(item, ParallelExecutions):
         for branch in item.branches:
-          child_items.extend(branch._child_items(item_cls))  # pylint: disable=protected-access
-    return child_items
+          for x in branch._iter_children(item_cls):  # pylint: disable=protected-access
+            yield x
 
-  def _all_child_items(self, item_cls: Type[Any]) -> list[Any]:
-    child_items = []
+  def _iter_subtree(self, item_cls: Type[Any]) -> Iterator[TracedItem]:
     for item in self.items:
       if isinstance(item, item_cls):
-        child_items.append(item)
+        yield item
       if isinstance(item, ActionInvocation):
-        child_items.extend(item.execution._all_child_items(item_cls))  # pylint: disable=protected-access
+        for x in item.execution._iter_subtree(item_cls):  # pylint: disable=protected-access
+          yield x
       elif isinstance(item, ExecutionTrace):
-        child_items.extend(item._all_child_items(item_cls))  # pylint: disable=protected-access
+        for x in item._iter_subtree(item_cls):  # pylint: disable=protected-access
+          yield x
       elif isinstance(item, ParallelExecutions):
         for branch in item.branches:
-          child_items.extend(branch._all_child_items(item_cls))  # pylint: disable=protected-access
-    return child_items
+          for x in branch._iter_subtree(item_cls):  # pylint: disable=protected-access
+            yield x
 
   def append(self, item: TracedItem) -> None:
     """Appends an item to the sequence."""
@@ -359,7 +418,7 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
     elif isinstance(item, lf_structured.QueryInvocation):
       css_class = 'query'
     elif isinstance(item, lf.logging.LogEntry):
-      css_class = 'log'
+      css_class = f'log-{item.level}'
     elif isinstance(item, ExecutionTrace):
       css_class = 'phase'
     elif isinstance(item, ParallelExecutions):
@@ -379,13 +438,7 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
     if isinstance(item, ActionInvocation):
       return pg.views.html.controls.Label(
           item.action.__class__.__name__,
-          tooltip=pg.format(
-              item.action,
-              verbose=False,
-              hide_default_values=True,
-              max_str_len=80,
-              max_bytes_len=20,
-          ),
+          tooltip=f'[{item.id}] Action invocation',
       )
     elif isinstance(item, lf_structured.QueryInvocation):
       schema_title = 'str'
@@ -393,30 +446,22 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
         schema_title = lf_structured.annotation(item.schema.spec)
       return pg.views.html.controls.Label(
           schema_title,
-          tooltip=(
-              pg.format(
-                  item.input,
-                  verbose=False,
-                  hide_default_values=True,
-                  max_str_len=80,
-                  max_bytes_len=20,
-              )
-          ),
+          tooltip=f'[{item.id}] lf.Query invocation'
       )
     elif isinstance(item, lf.logging.LogEntry):
       return pg.views.html.controls.Label(
-          'Log',
+          item.level.title(),
           tooltip=item.message,
       )
     elif isinstance(item, ExecutionTrace):
       return pg.views.html.controls.Label(
           item.name or 'Phase',
-          tooltip=f'Execution phase {item.name!r}.'
+          tooltip=f'[{item.id}] Execution group {item.name!r}'
       )
     elif isinstance(item, ParallelExecutions):
       return pg.views.html.controls.Label(
           item.name or 'Parallel',
-          tooltip='Parallel executions.'
+          tooltip=f'[{item.id}] Parallel executions'
       )
     else:
       raise ValueError(f'Unsupported item type: {type(item)}')
@@ -431,13 +476,13 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
           padding: 10px;
         }
         .tab-button.phase > ::before {
-          content: "P";
+          content: "G";
           font-weight: bold;
           color: purple;
           padding: 10px;
         }
         .tab-button.parallel > ::before {
-          content: "||";
+          content: "P";
           font-weight: bold;
           color: blue;
           padding: 10px;
@@ -448,11 +493,26 @@ class ExecutionTrace(pg.Object, pg.views.html.HtmlTreeView.Extension):
           color: orange;
           padding: 10px;
         }
-        .tab-button.log > ::before {
-          content: "L";
-          font-weight: bold;
-          color: green;
-          padding: 10px;
+        .tab-button.log-debug > ::before {
+          content: "🔍";
+          padding: 7px;
+        }
+        .tab-button.log-info > ::before {
+          content: "ⓘ";
+          color: blue;
+          padding: 7px;
+        }
+        .tab-button.log-warning > ::before {
+          content: "❗";
+          padding: 7px;
+        }
+        .tab-button.log-error > ::before {
+          content: "‼️";
+          padding: 7px;
+        }
+        .tab-button.log-fatal > ::before {
+          content: "❌";
+          padding: 7px;
         }
         .details.execution-trace, .details.action-invocation {
           border: 1px solid #eee;
@@ -504,6 +564,22 @@ class ParallelExecutions(pg.Object, pg.views.html.HtmlTreeView.Extension):
     self._tab_control = None
     self._lock = threading.Lock()
 
+  def _on_parent_change(self, *args, **kwargs):
+    super()._on_parent_change(*args, **kwargs)
+    self.__dict__.pop('id', None)
+
+  @functools.cached_property
+  def id(self) -> str:
+    parent = self.sym_parent
+    if isinstance(parent, pg.List):
+      container = parent.sym_parent
+      if isinstance(container, ExecutionTrace):
+        parallel_id = (
+            self.name or f'p{container.indexof(self, ParallelExecutions) + 1}'
+        )
+        return f'{container.id}/{parallel_id}'
+    return ''
+
   def add(self) -> ExecutionTrace:
     """Appends a branch to the parallel execution."""
     with self._lock, pg.notify_on_change(False):
@@ -547,7 +623,7 @@ class ParallelExecutions(pg.Object, pg.views.html.HtmlTreeView.Extension):
     return pg.views.html.controls.Tab(
         label=pg.views.html.controls.Label(
             branch.name,
-            tooltip=f'Execution thread {branch.name!r}.'
+            tooltip=f'[{branch.id}] Branch {branch.name!r}'
         ),
         content=pg.view(branch),
     )
@@ -567,6 +643,11 @@ class ActionInvocation(pg.Object, pg.views.html.HtmlTreeView.Extension):
       'The metadata returned by the action.'
   ] = {}
 
+  error: Annotated[
+      pg.utils.ErrorInfo | None,
+      'Error from the action if failed.'
+  ] = None
+
   execution: Annotated[
       ExecutionTrace,
       'The execution sequence of the action.'
@@ -579,6 +660,33 @@ class ActionInvocation(pg.Object, pg.views.html.HtmlTreeView.Extension):
     super()._on_bound()
     self._tab_control = None
 
+  def _on_parent_change(self, *args, **kwargs):
+    super()._on_parent_change(*args, **kwargs)
+    self.__dict__.pop('id', None)
+
+  @property
+  def parent_action(self) -> Optional['ActionInvocation']:
+    """Returns the parent action invocation."""
+    return self.sym_ancestor(lambda x: isinstance(x, ActionInvocation))
+
+  @functools.cached_property
+  def id(self) -> str:
+    """Returns the id of the action invocation."""
+    parent = self.sym_parent
+    if isinstance(parent, Session):
+      return f'{parent.id}:'
+    elif isinstance(parent, pg.List):
+      container = parent.sym_parent
+      if isinstance(container, ExecutionTrace):
+        action_id = f'a{container.indexof(self, ActionInvocation) + 1}'
+        return f'{container.id}/{action_id}'
+    return ''
+
+  @property
+  def has_error(self) -> bool:
+    """Returns True if the action invocation has an error."""
+    return self.error is not None
+
   @property
   def logs(self) -> list[lf.logging.LogEntry]:
     """Returns immediate child logs from execution sequence."""
@@ -618,14 +726,17 @@ class ActionInvocation(pg.Object, pg.views.html.HtmlTreeView.Extension):
     """Starts the execution of the action."""
     self.execution.start()
 
-  def end(self, result: Any, metadata: dict[str, Any]) -> None:
+  def end(
+      self,
+      result: Any,
+      error: pg.utils.ErrorInfo | None = None,
+      metadata: dict[str, Any] | None = None,
+  ) -> None:
     """Ends the execution of the action with result and metadata."""
-    self.rebind(
-        result=result,
-        metadata=metadata,
-        skip_notification=True,
-        raise_on_no_change=False
-    )
+    rebind_dict = dict(result=result, error=error)
+    if metadata is not None:
+      rebind_dict['metadata'] = metadata
+    self.rebind(**rebind_dict, skip_notification=True, raise_on_no_change=False)
     self.execution.stop()
     if self._tab_control is not None:
       if self.metadata:
@@ -641,19 +752,33 @@ class ActionInvocation(pg.Object, pg.views.html.HtmlTreeView.Extension):
                 name='metadata',
             )
         )
-      self._tab_control.insert(
-          1,
-          pg.views.html.controls.Tab(
-              'result',
-              pg.view(
-                  self.result,
-                  collapse_level=None,
-                  enable_summary_tooltip=False
-              ),
-              name='result',
-          ),
-      )
-      self._tab_control.select(['metadata', 'result'])
+      if self.has_error:
+        self._tab_control.insert(
+            1,
+            pg.views.html.controls.Tab(
+                'error',
+                pg.view(
+                    self.error,
+                    collapse_level=None,
+                    enable_summary_tooltip=False
+                ),
+                name='error',
+            )
+        )
+      else:
+        self._tab_control.insert(
+            1,
+            pg.views.html.controls.Tab(
+                'result',
+                pg.view(
+                    self.result,
+                    collapse_level=None,
+                    enable_summary_tooltip=False
+                ),
+                name='result',
+            ),
+        )
+      self._tab_control.select(['error', 'metadata', 'result'])
 
   #
   # HTML views.
@@ -806,7 +931,7 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
     self._current_execution = self.root.execution
     if self.id is None:
       self.rebind(
-          id=f'session@{uuid.uuid4().hex[-7:]}',
+          id=f'agent@{uuid.uuid4().hex[-7:]}',
           skip_notification=True
       )
 
@@ -821,6 +946,7 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
       self._current_execution.start()
 
     invocation = ActionInvocation(pg.maybe_ref(action))
+    action._invocation = invocation  # pylint: disable=protected-access
     parent_action = self._current_action
     parent_execution = self._current_execution
     parent_execution.append(invocation)
@@ -832,16 +958,18 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
       self._current_action.start()
       yield invocation
     finally:
-      # Stop the execution of the current action.
-      invocation.end(action.result, action.metadata)
       self._current_execution = parent_execution
       self._current_action = parent_action
       if parent_action is self.root:
-        parent_action.end(result=action.result, metadata=action.metadata)
+        parent_action.end(
+            result=invocation.result,
+            metadata=invocation.metadata,
+            error=invocation.error
+        )
 
   @contextlib.contextmanager
   def track_phase(self, name: str | None) -> Iterator[ExecutionTrace]:
-    """Context manager for starting a new execution phase."""
+    """Context manager for starting a new execution phase (group)."""
     parent_execution = self._current_execution
     if name is None:
       phase = parent_execution
@@ -878,6 +1006,12 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
         try:
           yield queries
         finally:
+          for i, query in enumerate(queries):
+            query.rebind(
+                id=f'{execution.id}/q{len(execution.queries) + i + 1}',
+                skip_notification=False,
+                raise_on_no_change=False
+            )
           execution.extend(queries)
 
   #
@@ -897,7 +1031,7 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
       ] = None,
       default: Any = lf.RAISE_IF_HAS_ERROR,
       *,
-      lm: lf.LanguageModel | None = None,
+      lm: lf.LanguageModel,
       examples: list[lf_structured.MappingExample] | None = None,
       **kwargs
       ) -> Any:
@@ -931,14 +1065,24 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
       The result of the query.
     """
     with self.track_queries():
-      return lf_structured.query(
-          prompt,
-          schema=schema,
-          default=default,
-          lm=lm,
-          examples=examples,
-          **kwargs
-      )
+      start_time = time.time()
+      try:
+        return lf_structured.query(
+            prompt,
+            schema=schema,
+            default=default,
+            lm=lm,
+            examples=examples,
+            **kwargs
+        )
+      except BaseException as e:
+        elapse = time.time() - start_time
+        self.warning(
+            f'Failed to query LLM ({lm.model_id}) in {elapse:.2f} seconds.',
+            error=pg.utils.ErrorInfo.from_exception(e),
+            keep=False,
+        )
+        raise
 
   def concurrent_map(
       self,
@@ -1069,11 +1213,15 @@ class Session(pg.Object, pg.views.html.HtmlTreeView.Extension):
       **kwargs
   ) -> None:
     """Logs a message to the session."""
+    action_name = self._current_action.action.__class__.__name__
+    execution = self._current_execution
     log_entry = lf.logging.log(
-        level, f'[{self.id}]: {message}]', **kwargs
+        level,
+        f'[{execution.id} ({action_name})]: {message}',
+        **kwargs
     )
     if keep:
-      self._current_execution.append(log_entry)
+      execution.append(log_entry)
 
   def debug(self, message: str, keep: bool = True, **kwargs):
     """Logs a debug message to the session."""

langfun/core/agentic/action_eval.py

@@ -34,9 +34,11 @@ class ActionEval(lf.eval.v2.Evaluation):
   def process(self, example: lf.eval.v2.Example) -> tuple[str, dict[str, Any]]:
     example_input = example.input
     action = example_input.action
-    session = action_lib.Session(id=str(example.id))
+    session = action_lib.Session(id=f'{self.id}#example-{example.id}')
     with lf.logging.use_log_level('fatal'):
-      action(session=session, **self.action_args)
+      kwargs = self.action_args.copy()
+      kwargs.update(verbose=True)
+      action(session=session, **kwargs)
     return session.final_result, dict(session=session)
 
 

langfun/core/agentic/action_test.py

@@ -22,54 +22,108 @@ import langfun.core.structured as lf_structured
 import pyglove as pg
 
 
-class SessionTest(unittest.TestCase):
+class Bar(action_lib.Action):
+  simulate_action_error: bool = False
+
+  def call(self, session, *, lm, **kwargs):
+    assert session.current_action.action is self
+    session.info('Begin Bar')
+    session.query('bar', lm=lm)
+    session.add_metadata(note='bar')
+    if self.simulate_action_error:
+      raise ValueError('Bar error')
+    return 2
+
+
+class Foo(action_lib.Action):
+  x: int
+  simulate_action_error: bool = False
+  simulate_query_error: bool = False
+
+  def call(self, session, *, lm, **kwargs):
+    assert session.current_action.action is self
+    with session.track_phase('prepare'):
+      session.info('Begin Foo', x=1)
+      session.query(
+          'foo',
+          schema=int if self.simulate_query_error else None,
+          lm=lm
+      )
+    with session.track_queries():
+      self.make_additional_query(lm)
+    session.add_metadata(note='foo')
+
+    def _sub_task(i):
+      session.add_metadata(**{f'subtask_{i}': i})
+      return lf_structured.query(f'subtask_{i}', lm=lm)
+
+    for i, output, error in session.concurrent_map(
+        _sub_task, range(3), max_workers=2, silence_on_errors=None,
+    ):
+      assert isinstance(i, int), i
+      assert isinstance(output, str), output
+      assert error is None, error
+    return self.x + Bar(
+        simulate_action_error=self.simulate_action_error
+    )(session, lm=lm)
+
+  def make_additional_query(self, lm):
+    lf_structured.query('additional query', lm=lm)
+
+
+class ActionInvocationTest(unittest.TestCase):
+
+  def test_basics(self):
+    action_invocation = action_lib.ActionInvocation(
+        action=Foo(1)
+    )
+    self.assertEqual(action_invocation.id, '')
+    root = action_lib.ActionInvocation(action=action_lib.RootAction())
+    root.execution.append(action_invocation)
+    self.assertIs(action_invocation.parent_action, root)
+    self.assertEqual(action_invocation.id, '/a1')
+
+
+class ExecutionTraceTest(unittest.TestCase):
 
   def test_basics(self):
-    test = self
-
-    class Bar(action_lib.Action):
-
-      def call(self, session, *, lm, **kwargs):
-        test.assertIs(session.current_action.action, self)
-        session.info('Begin Bar')
-        session.query('bar', lm=lm)
-        session.add_metadata(note='bar')
-        return 2
-
-    class Foo(action_lib.Action):
-      x: int
-
-      def call(self, session, *, lm, **kwargs):
-        test.assertIs(session.current_action.action, self)
-        with session.track_phase('prepare'):
-          session.info('Begin Foo', x=1)
-          session.query('foo', lm=lm)
-        with session.track_queries():
-          self.make_additional_query(lm)
-        session.add_metadata(note='foo')
-
-        def _sub_task(i):
-          session.add_metadata(**{f'subtask_{i}': i})
-          return lf_structured.query(f'subtask_{i}', lm=lm)
-
-        for i, output, error in session.concurrent_map(
-            _sub_task, range(3), max_workers=2, silence_on_errors=None,
-        ):
-          assert isinstance(i, int), i
-          assert isinstance(output, str), output
-          assert error is None, error
-        return self.x + Bar()(session, lm=lm)
-
-      def make_additional_query(self, lm):
-        lf_structured.query('additional query', lm=lm)
+    execution = action_lib.ExecutionTrace()
+    self.assertEqual(execution.id, '')
 
+    root = action_lib.ActionInvocation(action=action_lib.RootAction())
+    action_invocation = action_lib.ActionInvocation(
+        action=Foo(1)
+    )
+    root.execution.append(action_invocation)
+    self.assertEqual(action_invocation.execution.id, '/a1')
+
+    root.execution.reset()
+    self.assertEqual(len(root.execution), 0)
+
+
+class SessionTest(unittest.TestCase):
+
+  def test_succeeded_trajectory(self):
     lm = fake.StaticResponse('lm response')
     foo = Foo(1)
-    self.assertEqual(foo(lm=lm, verbose=True), 3)
+    self.assertIsNone(foo.session)
+    self.assertIsNone(foo.result)
+    self.assertIsNone(foo.metadata)
+
+    session = action_lib.Session(id='agent@1')
+    self.assertEqual(session.id, 'agent@1')
+
+    # Render HTML view to trigger dynamic update during execution.
+    _ = session.to_html()
+
+    self.assertEqual(foo(session, lm=lm, verbose=True), 3)
+
+    self.assertIsNone(foo.session)
+    self.assertEqual(foo.result, 3)
+    self.assertEqual(
+        foo.metadata, dict(note='foo', subtask_0=0, subtask_1=1, subtask_2=2)
+    )
 
-    session = foo.session
-    self.assertIn('session@', session.id)
-    self.assertIsNotNone(session)
     self.assertIsInstance(session.root.action, action_lib.RootAction)
     self.assertIs(session.current_action, session.root)
 
@@ -78,6 +132,9 @@ class SessionTest(unittest.TestCase):
     #
 
     root = session.root
+    self.assertIsNone(root.parent_action)
+    self.assertEqual(root.id, 'agent@1:')
+    self.assertEqual(root.execution.id, 'agent@1:')
     self.assertEqual(len(root.execution.items), 1)
     self.assertIs(root.execution.items[0].action, foo)
 
@@ -104,33 +161,57 @@ class SessionTest(unittest.TestCase):
 
     # Inspecting the top-level action (Foo)
     foo_invocation = root.execution.items[0]
+    self.assertIs(foo_invocation.parent_action, root)
+    self.assertEqual(foo_invocation.id, 'agent@1:/a1')
+    self.assertEqual(foo_invocation.execution.id, 'agent@1:/a1')
     self.assertEqual(len(foo_invocation.execution.items), 4)
 
     # Prepare phase.
     prepare_phase = foo_invocation.execution.items[0]
-    self.assertIsInstance(
-        prepare_phase, action_lib.ExecutionTrace
-    )
+    self.assertIsInstance(prepare_phase, action_lib.ExecutionTrace)
+    self.assertEqual(prepare_phase.id, 'agent@1:/a1/prepare')
     self.assertEqual(len(prepare_phase.items), 2)
     self.assertTrue(prepare_phase.has_started)
     self.assertTrue(prepare_phase.has_stopped)
     self.assertEqual(prepare_phase.usage_summary.total.num_requests, 1)
+    self.assertIsInstance(prepare_phase.items[0], lf.logging.LogEntry)
+    self.assertIsInstance(prepare_phase.items[1], lf_structured.QueryInvocation)
+    self.assertEqual(prepare_phase.items[1].id, 'agent@1:/a1/prepare/q1')
 
     # Tracked queries.
     query_invocation = foo_invocation.execution.items[1]
     self.assertIsInstance(query_invocation, lf_structured.QueryInvocation)
+    self.assertEqual(query_invocation.id, 'agent@1:/a1/q2')
     self.assertIs(query_invocation.lm, lm)
+    self.assertEqual(
+        foo_invocation.execution.indexof(
+            query_invocation, lf_structured.QueryInvocation
+        ),
+        1
+    )
+    self.assertEqual(
+        root.execution.indexof(
+            query_invocation, lf_structured.QueryInvocation
+        ),
+        -1
+    )
 
     # Tracked parallel executions.
     parallel_executions = foo_invocation.execution.items[2]
+    self.assertEqual(parallel_executions.id, 'agent@1:/a1/p1')
     self.assertIsInstance(parallel_executions, action_lib.ParallelExecutions)
     self.assertEqual(len(parallel_executions), 3)
+    self.assertEqual(parallel_executions[0].id, 'agent@1:/a1/p1/b1')
+    self.assertEqual(parallel_executions[1].id, 'agent@1:/a1/p1/b2')
+    self.assertEqual(parallel_executions[2].id, 'agent@1:/a1/p1/b3')
     self.assertEqual(len(parallel_executions[0].queries), 1)
     self.assertEqual(len(parallel_executions[1].queries), 1)
     self.assertEqual(len(parallel_executions[2].queries), 1)
 
     # Invocation to Bar.
     bar_invocation = foo_invocation.execution.items[3]
+    self.assertIs(bar_invocation.parent_action, foo_invocation)
+    self.assertEqual(bar_invocation.id, 'agent@1:/a1/a1')
     self.assertIsInstance(bar_invocation, action_lib.ActionInvocation)
     self.assertIsInstance(bar_invocation.action, Bar)
     self.assertEqual(bar_invocation.result, 2)
@@ -144,6 +225,51 @@ class SessionTest(unittest.TestCase):
     json_str = session.to_json_str(save_ref_value=True)
     self.assertIsInstance(pg.from_json_str(json_str), action_lib.Session)
 
+  def test_failed_action(self):
+    lm = fake.StaticResponse('lm response')
+    foo = Foo(1, simulate_action_error=True)
+    with self.assertRaisesRegex(ValueError, 'Bar error'):
+      foo(lm=lm)
+
+    session = foo.session
+    self.assertIsNotNone(session)
+    self.assertIsInstance(session.root.action, action_lib.RootAction)
+    self.assertIs(session.current_action, session.root)
+
+    # Inspecting the root invocation.
+    root = session.root
+    self.assertRegex(root.id, 'agent@.*:')
+    self.assertTrue(root.has_error)
+    foo_invocation = root.execution.items[0]
+    self.assertIsInstance(foo_invocation, action_lib.ActionInvocation)
+    self.assertTrue(foo_invocation.has_error)
+    bar_invocation = foo_invocation.execution.items[3]
+    self.assertIsInstance(bar_invocation, action_lib.ActionInvocation)
+    self.assertTrue(bar_invocation.has_error)
+
+    # Save to HTML
+    self.assertIn('error', session.to_html().content)
+
+  def test_failed_query(self):
+    lm = fake.StaticResponse('lm response')
+    foo = Foo(1, simulate_query_error=True)
+    with self.assertRaisesRegex(lf_structured.MappingError, 'SyntaxError'):
+      foo(lm=lm)
+
+    session = foo.session
+    self.assertIsNotNone(session)
+    self.assertIsInstance(session.root.action, action_lib.RootAction)
+    self.assertIs(session.current_action, session.root)
+
+    # Inspecting the root invocation.
+    root = session.root
+    self.assertRegex(root.id, 'agent@.*:')
+    self.assertTrue(root.has_error)
+    foo_invocation = root.execution.items[0]
+    self.assertIsInstance(foo_invocation, action_lib.ActionInvocation)
+    self.assertTrue(foo_invocation.has_error)
+    self.assertEqual(len(foo_invocation.execution.items), 2)
+
   def test_log(self):
     session = action_lib.Session()
     session.debug('hi', x=1, y=2)
@@ -153,8 +279,8 @@ class SessionTest(unittest.TestCase):
     session.fatal('hi', x=1, y=2)
 
   def test_as_message(self):
-    session = action_lib.Session(id='abc')
-    self.assertEqual(session.id, 'abc')
+    session = action_lib.Session()
+    self.assertIn('agent@', session.id)
     self.assertIsInstance(session.as_message(), lf.AIMessage)
 
 

langfun/core/structured/schema.py

@@ -456,6 +456,11 @@ def class_definition(
         )
         continue
 
+      # Skip fields that are marked as excluded from the prompt sent to LLM
+      # for OOP.
+      if field.metadata.get('exclude_from_prompt', False):
+        continue
+
       # Write field doc string as comments before the field definition.
       if field.description:
         for line in field.description.split('\n'):

langfun/core/structured/schema_test.py

@@ -538,6 +538,19 @@ class SchemaPythonReprTest(unittest.TestCase):
             """) + '\n'
     )
 
+    class E(pg.Object):
+      x: str
+      y: typing.Annotated[int, 'y', dict(exclude_from_prompt=True)]
+
+    self.assertEqual(
+        schema_lib.class_definition(E),
+        inspect.cleandoc(
+            """
+            class E(Object):
+              x: str
+            """) + '\n'
+    )
+
   def test_repr(self):
     class Foo(pg.Object):
       x: int

{langfun-0.1.2.dev202504270803.dist-info → langfun-0.1.2.dev202504290805.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langfun
-Version: 0.1.2.dev202504270803
+Version: 0.1.2.dev202504290805
 Summary: Langfun: Language as Functions.
 Home-page: https://github.com/google/langfun
 Author: Langfun Authors
@@ -193,7 +193,9 @@ 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:
+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                             |
 | ------------------- | ---------------------------------------- |
@@ -201,15 +203,36 @@ If you want to customize your installation, you can select specific features usi
 | 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:
+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
 ```
 
+### Solving import issue with `libmagic`
+
+Langfun utilizes `libmagic` for automatic MIME type detection to support
+multi-modal functionalities. However, `pip install libmagic` may not work
+out-of-the-box on all operation systems, sometimes leading to an
+`'ImportError: failed to find libmagic.'` error after Langfun installation.
+
+If you encounter this error, you will need to follow the recommendations below
+to fix the installation of `libmagic` library.
+
+#### OSX
+
+```
+conda install conda-forge::libmagic
+```
+
+#### Windows:
+```
+pip install python-magic
+pip uninstall python-magic-bin
+pip install python-magic-bin
+```
+
 *Disclaimer: this is not an officially supported Google product.*

{langfun-0.1.2.dev202504270803.dist-info → langfun-0.1.2.dev202504290805.dist-info}/RECORD

@@ -26,10 +26,10 @@ langfun/core/subscription_test.py,sha256=Y4ZdbZEwm83YNZBxHff0QR4QUa4rdaNXA3_jfIc
 langfun/core/template.py,sha256=jNhYSrbLIn9kZOa03w5QZbyjgfnzJzE_ZrrMvvWY4t4,24929
 langfun/core/template_test.py,sha256=AQv_m9qE93WxhEhSlm1xaBgB4hu0UVtA53dljngkUW0,17090
 langfun/core/agentic/__init__.py,sha256=qR3jlfUO4rhIoYdRDLz-d22YZf3FvU4FW88vsjiGDQQ,1224
-langfun/core/agentic/action.py,sha256=83zH_cj0s9mxq7mnaTZXbB0Uf-y8d0ip5TrF-mabeT8,34000
-langfun/core/agentic/action_eval.py,sha256=-ZcWt_eYqnTyOe9HFGyrLJkQRd4iG3hfN4IZ-NYAWwA,4534
+langfun/core/agentic/action.py,sha256=9P7xDiZVUV9MvJDfuAfLx-xa7qvS5F0EOGWDQnjAZBw,38931
+langfun/core/agentic/action_eval.py,sha256=8cdH-ubWUL1sscqagrQltPg19vTYNKrI3CKLvluGP24,4615
 langfun/core/agentic/action_eval_test.py,sha256=tRUkWmOE9p0rpNOq19xAY2oDEnYsEEykjg6sUpAwJk0,2832
-langfun/core/agentic/action_test.py,sha256=ilirTICURoAR6LYjlg3oC3P1KSbLzJQDK4WaZONed2Q,5708
+langfun/core/agentic/action_test.py,sha256=9EZKgLaBrqTErSRoxtrSlzmCz_cbnwWu0ZqpwKLst-s,10224
 langfun/core/coding/__init__.py,sha256=5utju_fwEsImaiftx4oXKl9FAM8p281k8-Esdh_-m1w,835
 langfun/core/coding/python/__init__.py,sha256=4ByknuoNU-mOIHwHKnTtmo6oD64oMFtlqPlYWmA5Wic,1736
 langfun/core/coding/python/correction.py,sha256=7zBedlhQKMPA4cfchUMxAOFl6Zl5RqCyllRHGWys40s,7092
@@ -139,10 +139,10 @@ langfun/core/structured/parsing.py,sha256=MGvI7ypXlwfzr5XB8_TFU9Ei0_5reYqkWkv64e
 langfun/core/structured/parsing_test.py,sha256=kNPrhpdPY3iWhUld0TFYU-Zgn44wC0d6YuQ9XdVbQ8o,22346
 langfun/core/structured/querying.py,sha256=GGNtHtJcKh8rzLBNx_Df1ATvsPZzyfZuGkzSQVabdpo,24885
 langfun/core/structured/querying_test.py,sha256=vUuVUClYBFGEaO9KuD60huPE1dmP6RCRLeRnBv67NmQ,34263
-langfun/core/structured/schema.py,sha256=OGHmjyjraTnrq11Y5KrGyvKahviB1cfyvV9avd4UUZU,28126
+langfun/core/structured/schema.py,sha256=pGiAjez-ON2nKLUSeAls27gJsMto5aJnCXLVwH3pUKM,28296
 langfun/core/structured/schema_generation.py,sha256=3AcuKvv3VOtKY5zMVqODrxfOuDxzoZtGeBxHlOWDOWw,5308
 langfun/core/structured/schema_generation_test.py,sha256=RM9s71kMNg2jTePwInkiW9fK1ACN37eyPeF8OII-0zw,2950
-langfun/core/structured/schema_test.py,sha256=L-HY9GWvfO4-kWuol6tY_zpLakNrwpMAxz2jUsY_e8s,25744
+langfun/core/structured/schema_test.py,sha256=N8qNVA2hrHlxmHIoKtpzhBASa2RMVoPowF_noAfgPME,26035
 langfun/core/structured/scoring.py,sha256=Y7Jqs5VVjUQLF_9Z1uIY_dw5zasv2FF52Cz-cxGMsro,5857
 langfun/core/structured/scoring_test.py,sha256=QvlwDAzwuamKL5tCotm1L3Sx0cs3idoNK4aIEhaO4Yk,2272
 langfun/core/structured/tokenization.py,sha256=-b4_693quHeYn2AqndwucuXNmhd5NVXVTU3mmDane98,2189
@@ -156,8 +156,8 @@ langfun/core/templates/demonstration.py,sha256=vCrgYubdZM5Umqcgp8NUVGXgr4P_c-fik
 langfun/core/templates/demonstration_test.py,sha256=SafcDQ0WgI7pw05EmPI2S4v1t3ABKzup8jReCljHeK4,2162
 langfun/core/templates/selfplay.py,sha256=yhgrJbiYwq47TgzThmHrDQTF4nDrTI09CWGhuQPNv-s,2273
 langfun/core/templates/selfplay_test.py,sha256=Ot__1P1M8oJfoTp-M9-PQ6HUXqZKyMwvZ5f7yQ3yfyM,2326
-langfun-0.1.2.dev202504270803.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
-langfun-0.1.2.dev202504270803.dist-info/METADATA,sha256=-p76zsXSD3qQx9ZqulXFmhbENRRXiZr9hHLMgDuh4Us,7692
-langfun-0.1.2.dev202504270803.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
-langfun-0.1.2.dev202504270803.dist-info/top_level.txt,sha256=RhlEkHxs1qtzmmtWSwYoLVJAc1YrbPtxQ52uh8Z9VvY,8
-langfun-0.1.2.dev202504270803.dist-info/RECORD,,
+langfun-0.1.2.dev202504290805.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
+langfun-0.1.2.dev202504290805.dist-info/METADATA,sha256=KWW7NslPxpSS2u0eVRcN022ylI5TeWFdswXMnve9144,8178
+langfun-0.1.2.dev202504290805.dist-info/WHEEL,sha256=ck4Vq1_RXyvS4Jt6SI0Vz6fyVs4GWg7AINwpsaGEgPE,91
+langfun-0.1.2.dev202504290805.dist-info/top_level.txt,sha256=RhlEkHxs1qtzmmtWSwYoLVJAc1YrbPtxQ52uh8Z9VvY,8
+langfun-0.1.2.dev202504290805.dist-info/RECORD,,

{langfun-0.1.2.dev202504270803.dist-info → langfun-0.1.2.dev202504290805.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (79.0.1)
+Generator: setuptools (80.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any