langfun 0.1.2.dev202509250804__py3-none-any.whl → 0.1.2.dev202509270803__py3-none-any.whl

langfun/core/llms/__init__.py

@@ -99,6 +99,8 @@ VertexAIGeminiFlash1_5 = VertexAIGemini15Flash
 # OpenAI models.
 from langfun.core.llms.openai import OpenAI
 
+from langfun.core.llms.openai import Gpt5
+from langfun.core.llms.openai import Gpt5Mini
 from langfun.core.llms.openai import Gpt41
 from langfun.core.llms.openai import GptO3
 from langfun.core.llms.openai import GptO4Mini

langfun/core/llms/openai.py

@@ -49,6 +49,53 @@ class OpenAIModelInfo(lf.ModelInfo):
 #
 
 SUPPORTED_MODELS = [
+    # GPT-5 models
+    OpenAIModelInfo(
+        model_id='gpt-5',
+        alias_for='gpt-5-2025-08-07',
+        in_service=True,
+        model_type='instruction-tuned',
+        description='GPT 5 model (latest stable).',
+        url='https://platform.openai.com/docs/models/gpt-5',
+        input_modalities=OpenAIModelInfo.INPUT_IMAGE_TYPES,
+        context_length=lf.ModelInfo.ContextLength(
+            max_input_tokens=400_000,
+            max_output_tokens=128_000,
+        ),
+        pricing=lf.ModelInfo.Pricing(
+            cost_per_1m_cached_input_tokens=0.125,
+            cost_per_1m_input_tokens=1.25,
+            cost_per_1m_output_tokens=10.0,
+        ),
+        # Tier 5 rate limits.
+        rate_limits=lf.ModelInfo.RateLimits(
+            max_requests_per_minute=15_000,
+            max_tokens_per_minute=40_000_000,
+        ),
+    ),
+    OpenAIModelInfo(
+        model_id='gpt-5-mini',
+        alias_for='gpt-5-mini-2025-08-07',
+        in_service=True,
+        model_type='instruction-tuned',
+        description='GPT 5 mini model (latest stable).',
+        url='https://platform.openai.com/docs/models/gpt-5-mini',
+        input_modalities=OpenAIModelInfo.INPUT_IMAGE_TYPES,
+        context_length=lf.ModelInfo.ContextLength(
+            max_input_tokens=400_000,
+            max_output_tokens=128_000,
+        ),
+        pricing=lf.ModelInfo.Pricing(
+            cost_per_1m_cached_input_tokens=0.025,
+            cost_per_1m_input_tokens=0.25,
+            cost_per_1m_output_tokens=2.0,
+        ),
+        # Tier 5 rate limits.
+        rate_limits=lf.ModelInfo.RateLimits(
+            max_requests_per_minute=180_000_000,
+            max_tokens_per_minute=30_000_000,
+        ),
+    ),
     # GPT-4.1 models
     OpenAIModelInfo(
         model_id='gpt-4.1',
@@ -1069,6 +1116,16 @@ class OpenAI(openai_compatible.OpenAICompatible):
     return super()._request_args(options)
 
 
+class Gpt5(OpenAI):
+  """GPT-5."""
+  model = 'gpt-5'
+
+
+class Gpt5Mini(OpenAI):
+  """GPT-5 mini."""
+  model = 'gpt-5-mini'
+
+
 class Gpt41(OpenAI):
   """GPT-4.1."""
   model = 'gpt-4.1'

langfun/env/__init__.py

@@ -13,16 +13,12 @@
 # limitations under the License.
 """Environment for LLM agents."""
 
-# pylint: disable=g-importing-member, g-bad-import-order
-from langfun.env.interface import EnvironmentId
-from langfun.env.interface import SandboxId
-
+# 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 EnvironmentEventHandler
 
 from langfun.env.interface import Environment
 from langfun.env.interface import Sandbox
@@ -35,4 +31,7 @@ from langfun.env.base_feature import BaseFeature
 from langfun.env import load_balancers
 from langfun.env.load_balancers import LoadBalancer
 
+from langfun.env import event_handlers
+EventHandler = event_handlers.EventHandler
+
 # Google-internal imports.

langfun/env/base_environment.py

@@ -34,6 +34,7 @@ import langfun.core as lf
 from langfun.env import base_sandbox
 from langfun.env import interface
 from langfun.env import load_balancers
+from langfun.env.event_handlers import base as event_handler_base
 import pyglove as pg
 
 
@@ -65,10 +66,20 @@ class BaseEnvironment(interface.Environment):
   load_balancer: Annotated[
       load_balancers.LoadBalancer,
       (
-          'The load balancer for the environment.'
+          'The load balancer for the environment to acquire sandboxes.'
       )
   ] = load_balancers.RoundRobin()
 
+  sandbox_keepalive_interval: Annotated[
+      float | None,
+      (
+          'The interval in seconds to send keepalive pings to sandboxes. '
+          'If None, sandbox keepalive is disabled. Please note that sandbox '
+          'keepalive is different from feature housekeeping. Usually sandbox '
+          'keepalive and feature housekeeping are different operations.'
+      )
+  ] = None
+
   proactive_session_setup: Annotated[
       bool,
       (
@@ -79,6 +90,13 @@ class BaseEnvironment(interface.Environment):
       )
   ] = True
 
+  event_handlers: Annotated[
+      list[event_handler_base.EventHandler],
+      (
+          'User handler for the environment events.'
+      )
+  ] = []
+
   outage_grace_period: Annotated[
       float,
       (
@@ -97,13 +115,15 @@ class BaseEnvironment(interface.Environment):
       )
   ] = 10.0
 
-  stats_report_interval: Annotated[
+  housekeep_interval: Annotated[
       float,
       (
-          'The interval in seconds for reporting the environment stats. '
-          'If 0, stats will not be reported.'
+          'The interval in seconds for environment housekeeping. It recycles '
+          'the dead sandboxes in the pool. This interval is the minimal time '
+          'to detect outage while there is no request to obtain new sandboxes.'
+          'This is applicable only when the environment enables pooling.'
       )
-  ] = 60.0
+  ] = 10.0
 
   pool_operation_max_parallelism: Annotated[
       int,
@@ -145,6 +165,7 @@ class BaseEnvironment(interface.Environment):
       sandbox_id: str,
       reusable: bool,
       proactive_session_setup: bool,
+      keepalive_interval: float | None,
   ) -> base_sandbox.BaseSandbox:
     """Creates a sandbox with the given identifier.
 
@@ -153,6 +174,8 @@ class BaseEnvironment(interface.Environment):
       reusable: Whether the sandbox is reusable across user sessions.
       proactive_session_setup: Whether the sandbox performs session setup work
         before a user session is started.
+      keepalive_interval: Interval to ping the sandbox for keeping it alive.
+        If None, the sandbox will not be pinged.
 
     Returns:
       The created sandbox.
@@ -194,6 +217,7 @@ class BaseEnvironment(interface.Environment):
   def _start(self) -> None:
     """Implementation of starting the environment."""
     if self.min_pool_size > 0:
+      # Pre-allocate the sandbox pool before usage.
       self._sandbox_pool = [None] * self.min_pool_size
       for i, sandbox, _ in lf.concurrent_map(
           lambda i: self._bring_up_sandbox_with_retry(
@@ -207,12 +231,15 @@ class BaseEnvironment(interface.Environment):
           ),
       ):
         self._sandbox_pool[i] = sandbox
+
     self._next_sandbox_id = len(self._sandbox_pool)
-    self._housekeep_thread = threading.Thread(
-        target=self._housekeep_loop, daemon=True
-    )
-    self._housekeep_counter = 0
-    self._housekeep_thread.start()
+
+    if self.enable_pooling:
+      self._housekeep_thread = threading.Thread(
+          target=self._housekeep_loop, daemon=True
+      )
+      self._housekeep_counter = 0
+      self._housekeep_thread.start()
 
   def _shutdown(self) -> None:
     """Implementation of shutting down the environment."""
@@ -256,7 +283,7 @@ class BaseEnvironment(interface.Environment):
   @property
   def enable_pooling(self) -> bool:
     """Returns whether the environment enables pooling."""
-    return self.min_pool_size > 0
+    return self.max_pool_size > 0
 
   @property
   def status(self) -> interface.Environment.Status:
@@ -314,11 +341,6 @@ class BaseEnvironment(interface.Environment):
       self._start_time = time.time()
       self._set_status(self.Status.ONLINE)
       self.on_start(duration=time.time() - starting_time)
-
-      pg.logging.info(
-          '[%s]: %s started in %.2f seconds.',
-          self.id, self.__class__.__name__, time.time() - starting_time
-      )
     except BaseException as e:
       self.on_start(duration=time.time() - starting_time, error=e)
       self.shutdown()
@@ -338,13 +360,8 @@ class BaseEnvironment(interface.Environment):
     self._set_status(self.Status.SHUTTING_DOWN)
 
     try:
-      with pg.timeit('env.shutdown') as t:
-        self._shutdown()
+      self._shutdown()
       self.on_shutdown()
-      pg.logging.info(
-          '[%s]: %s shutdown in %.2f seconds.',
-          self.id, self.__class__.__name__, t.elapse
-      )
     except BaseException as e:  # pylint: disable=broad-except
       self.on_shutdown(error=e)
       raise e
@@ -416,6 +433,7 @@ class BaseEnvironment(interface.Environment):
         sandbox_id=sandbox_id,
         reusable=self.enable_pooling,
         proactive_session_setup=self.proactive_session_setup,
+        keepalive_interval=self.sandbox_keepalive_interval,
     )
     for handler in self.event_handlers:
       sandbox.add_event_handler(handler)
@@ -482,19 +500,8 @@ class BaseEnvironment(interface.Environment):
 
   def _housekeep_loop(self) -> None:
     """Housekeeping loop for the environment."""
-    pg.logging.info(
-        '[%s]: %s maintenance thread started.', self.id, self.__class__.__name__
-    )
-    stats_report_time = time.time()
     while self._status not in (self.Status.SHUTTING_DOWN, self.Status.OFFLINE):
       housekeep_start_time = time.time()
-      if time.time() - stats_report_time > self.stats_report_interval:
-        pg.logging.info(
-            '[%s] %s stats: %s.',
-            self.id, self.__class__.__name__, self.stats()
-        )
-        stats_report_time = time.time()
-
       dead_pool_indices = [
           i for i, s in enumerate(self._sandbox_pool)
           if s.status == interface.Sandbox.Status.OFFLINE
@@ -514,7 +521,7 @@ class BaseEnvironment(interface.Environment):
         break
       self._housekeep_counter += 1
       self.on_housekeep(time.time() - housekeep_start_time)
-      time.sleep(1)
+      time.sleep(self.housekeep_interval)
 
   def _replace_dead_sandboxes(self, dead_pool_indices: list[int]) -> bool:
     """Replaces a dead sandbox with a new one.

langfun/env/base_feature.py

@@ -23,6 +23,7 @@ the `Environment` and `Sandbox` interfaces directly.
 """
 
 import functools
+import os
 import time
 from typing import Annotated, Callable
 
@@ -106,6 +107,14 @@ class BaseFeature(interface.Feature):
     assert self._sandbox is not None, 'Feature has not been set up yet.'
     return self._sandbox
 
+  @property
+  def working_dir(self) -> str | None:
+    """Returns the working directory of the feature."""
+    sandbox_workdir = self.sandbox.working_dir
+    if sandbox_workdir is None:
+      return None
+    return os.path.join(sandbox_workdir, self.name)
+
   #
   # Setup and teardown of the feature.
   #
@@ -204,7 +213,7 @@ class BaseFeature(interface.Feature):
       self,
       name: str,
       duration: float,
-      error: BaseException | None,
+      error: BaseException | None = None,
       **kwargs
   ) -> None:
     """Called when a sandbox activity is performed."""

langfun/env/base_sandbox.py

@@ -29,6 +29,7 @@ import time
 from typing import Annotated, Any, Callable, Iterator, Sequence, Type
 
 from langfun.env import interface
+from langfun.env.event_handlers import base as event_handler_base
 import pyglove as pg
 
 
@@ -36,7 +37,7 @@ class BaseSandbox(interface.Sandbox):
   """Base class for a sandbox."""
 
   id: Annotated[
-      interface.SandboxId,
+      interface.Sandbox.Id,
       'The identifier for the sandbox.'
   ]
 
@@ -242,14 +243,14 @@ class BaseSandbox(interface.Sandbox):
 
   def add_event_handler(
       self,
-      event_handler: interface.EnvironmentEventHandler | None
+      event_handler: event_handler_base.EventHandler | None
   ) -> None:
     """Sets the event handler for the sandbox."""
     self._event_handlers.append(event_handler)
 
   def remove_event_handler(
       self,
-      event_handler: interface.EnvironmentEventHandler | None
+      event_handler: event_handler_base.EventHandler | None
   ) -> None:
     """Removes the event handler for the sandbox."""
     self._event_handlers.remove(event_handler)
@@ -357,10 +358,6 @@ class BaseSandbox(interface.Sandbox):
 
       duration = time.time() - starting_time
       self.on_start(duration)
-      pg.logging.info(
-          '[%s]: Sandbox started in %.2f seconds.',
-          self.id, duration
-      )
     except BaseException as e:  # pylint: disable=broad-except
       duration = time.time() - starting_time
       pg.logging.error(
@@ -422,7 +419,6 @@ class BaseSandbox(interface.Sandbox):
       return
 
     self._set_status(interface.Sandbox.Status.SHUTTING_DOWN)
-    shutdown_start_time = time.time()
 
     if (self._housekeep_thread is not None
         and threading.current_thread() is not self._housekeep_thread):
@@ -433,15 +429,6 @@ class BaseSandbox(interface.Sandbox):
     try:
       self._shutdown()
       self._set_status(interface.Sandbox.Status.OFFLINE)
-
-      pg.logging.info(
-          '[%s]: Sandbox shutdown in %.2f seconds. '
-          '(lifetime: %.2f seconds, teardown errors: %s)',
-          self.id,
-          time.time() - shutdown_start_time,
-          time.time() - self._start_time if self._start_time else 0,
-          teardown_error
-      )
       self.on_shutdown(teardown_error)
       shutdown_error = None
     except BaseException as e:  # pylint: disable=broad-except
@@ -656,14 +643,6 @@ class BaseSandbox(interface.Sandbox):
       self._set_status(interface.Sandbox.Status.ACQUIRED)
       shutdown_sandbox = True
 
-    pg.logging.info(
-        '[%s]: User session %s ended. '
-        '(lifetime: %.2f seconds, teardown errors: %s).',
-        self.id,
-        self._session_id,
-        time.time() - self._session_start_time,
-        end_session_error
-    )
     self._session_start_time = None
     self._session_event_handler = None
 
@@ -687,9 +666,31 @@ class BaseSandbox(interface.Sandbox):
     last_ping = now
     last_housekeep_time = {name: now for name in self._features.keys()}
 
+    def _next_housekeep_wait_time() -> float:
+      # Decide how long to sleep for the next housekeeping.
+      next_housekeep_time = None
+      if self.keepalive_interval is not None:
+        next_housekeep_time = last_ping + self.keepalive_interval
+
+      for name, feature in self._features.items():
+        if feature.housekeep_interval is None:
+          continue
+        next_feature_housekeep_time = (
+            last_housekeep_time[name] + feature.housekeep_interval
+        )
+        if (next_housekeep_time is None
+            or next_housekeep_time > next_feature_housekeep_time):
+          next_housekeep_time = next_feature_housekeep_time
+
+      # Housekeep loop is installed when at least one feature requires
+      # housekeeping or the sandbox has a keepalive interval.
+      assert next_housekeep_time is not None
+      return max(0, next_housekeep_time - time.time())
+
     while self._status not in (self.Status.SHUTTING_DOWN, self.Status.OFFLINE):
       housekeep_start = time.time()
       if self.keepalive_interval is not None:
+
         if time.time() - last_ping > self.keepalive_interval:
           try:
             self.ping()
@@ -731,7 +732,7 @@ class BaseSandbox(interface.Sandbox):
 
       self._housekeep_counter += 1
       self.on_housekeep(time.time() - housekeep_start)
-      time.sleep(1)
+      time.sleep(_next_housekeep_wait_time())
 
   #
   # Event handlers subclasses can override.