openhands-sdk 1.5.0__py3-none-any.whl → 1.7.2__py3-none-any.whl

openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -1,20 +1,44 @@
 import os
+from collections.abc import Sequence
+from enum import Enum
 
 from pydantic import Field, model_validator
 
 from openhands.sdk.context.condenser.base import RollingCondenser
+from openhands.sdk.context.condenser.utils import (
+    get_suffix_length_for_token_reduction,
+    get_total_token_count,
+)
 from openhands.sdk.context.prompts import render_template
 from openhands.sdk.context.view import View
+from openhands.sdk.event.base import LLMConvertibleEvent
 from openhands.sdk.event.condenser import Condensation
 from openhands.sdk.event.llm_convertible import MessageEvent
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.observability.laminar import observe
 
 
+class Reason(Enum):
+    """Reasons for condensation."""
+
+    REQUEST = "request"
+    TOKENS = "tokens"
+    EVENTS = "events"
+
+
 class LLMSummarizingCondenser(RollingCondenser):
+    """LLM-based condenser that summarizes forgotten events.
+
+    Uses an independent LLM (stored in the `llm` attribute) for generating summaries
+    of forgotten events. The optional `agent_llm` parameter passed to condense() is
+    the LLM used by the agent for token counting purposes, and you should not assume
+    it is the same as the one defined in this condenser.
+    """
+
     llm: LLM
-    max_size: int = Field(default=120, gt=0)
-    keep_first: int = Field(default=4, ge=0)
+    max_size: int = Field(default=240, gt=0)
+    max_tokens: int | None = None
+    keep_first: int = Field(default=2, ge=0)
 
     @model_validator(mode="after")
     def validate_keep_first_vs_max_size(self):
@@ -29,23 +53,47 @@ class LLMSummarizingCondenser(RollingCondenser):
     def handles_condensation_requests(self) -> bool:
         return True
 
-    def should_condense(self, view: View) -> bool:
-        if view.unhandled_condensation_request:
-            return True
-        return len(view) > self.max_size
+    def get_condensation_reasons(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> set[Reason]:
+        """Determine the reasons why the view should be condensed.
+
+        Args:
+            view: The current view to evaluate.
+            agent_llm: The LLM used by the agent. Required if token counting is needed.
 
-    @observe(ignore_inputs=["view"])
-    def get_condensation(self, view: View) -> Condensation:
-        head = view[: self.keep_first]
-        target_size = self.max_size // 2
+        Returns:
+            A set of Reason enums indicating why condensation is needed.
+        """
+        reasons = set()
+
+        # Reason 1: Unhandled condensation request. The view handles the detection of
+        # these requests while processing the event stream.
         if view.unhandled_condensation_request:
-            # Condensation triggered by a condensation request
-            # should be calculated based on the view size.
-            target_size = len(view) // 2
-        # Number of events to keep from the tail -- target size, minus however many
-        # prefix events from the head, minus one for the summarization event
-        events_from_tail = target_size - len(head) - 1
+            reasons.add(Reason.REQUEST)
 
+        # Reason 2: Token limit is provided and exceeded.
+        if self.max_tokens and agent_llm:
+            total_tokens = get_total_token_count(view.events, agent_llm)
+            if total_tokens > self.max_tokens:
+                reasons.add(Reason.TOKENS)
+
+        # Reason 3: View exceeds maximum size in number of events.
+        if len(view) > self.max_size:
+            reasons.add(Reason.EVENTS)
+
+        return reasons
+
+    def should_condense(self, view: View, agent_llm: LLM | None = None) -> bool:
+        reasons = self.get_condensation_reasons(view, agent_llm)
+        return reasons != set()
+
+    def _get_summary_event_content(self, view: View) -> str:
+        """Extract the text content from the summary event in the view, if any.
+
+        If there is no summary event or it does not contain text content, returns an
+        empty string.
+        """
         summary_event_content: str = ""
 
         summary_event = view.summary_event
@@ -54,9 +102,25 @@ class LLMSummarizingCondenser(RollingCondenser):
             if isinstance(message_content, TextContent):
                 summary_event_content = message_content.text
 
-        # Identify events to be forgotten (those not in head or tail)
-        forgotten_events = view[self.keep_first : -events_from_tail]
-
+        return summary_event_content
+
+    def _generate_condensation(
+        self,
+        summary_event_content: str,
+        forgotten_events: Sequence[LLMConvertibleEvent],
+        summary_offset: int,
+    ) -> Condensation:
+        """Generate a condensation by using the condenser's LLM to summarize forgotten
+        events.
+
+        Args:
+            summary_event_content: The content of the previous summary event.
+            forgotten_events: The list of events to be summarized.
+            summary_offset: The index where the summary event should be inserted.
+
+        Returns:
+            Condensation: The generated condensation object.
+        """
         # Convert events to strings for the template
         event_strings = [str(forgotten_event) for forgotten_event in forgotten_events]
 
@@ -84,6 +148,91 @@ class LLMSummarizingCondenser(RollingCondenser):
         return Condensation(
             forgotten_event_ids=[event.id for event in forgotten_events],
             summary=summary,
-            summary_offset=self.keep_first,
+            summary_offset=summary_offset,
             llm_response_id=llm_response.id,
         )
+
+    def _get_forgotten_events(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> tuple[Sequence[LLMConvertibleEvent], int]:
+        """Identify events to be forgotten and the summary offset.
+
+        Relies on the condensation reasons to determine how many events we need to drop
+        in order to maintain our resource constraints. Uses manipulation indices to
+        ensure forgetting ranges respect atomic unit boundaries.
+
+        Args:
+            view: The current view from which to identify forgotten events.
+            agent_llm: The LLM used by the agent, required for token-based calculations.
+
+        Returns:
+            A tuple of (events to forget, summary_offset).
+        """
+        reasons = self.get_condensation_reasons(view, agent_llm=agent_llm)
+        assert reasons != set(), "No condensation reasons found."
+
+        suffix_events_to_keep: set[int] = set()
+
+        if Reason.REQUEST in reasons:
+            target_size = len(view) // 2
+            suffix_events_to_keep.add(target_size - self.keep_first - 1)
+
+        if Reason.EVENTS in reasons:
+            target_size = self.max_size // 2
+            suffix_events_to_keep.add(target_size - self.keep_first - 1)
+
+        if Reason.TOKENS in reasons:
+            # Compute the number of tokens we need to eliminate to be under half the
+            # max_tokens value. We know max_tokens and the agent LLM are not None here
+            # because we can't have Reason.TOKENS without them.
+            assert self.max_tokens is not None
+            assert agent_llm is not None
+
+            total_tokens = get_total_token_count(view.events, agent_llm)
+            tokens_to_reduce = total_tokens - (self.max_tokens // 2)
+
+            suffix_events_to_keep.add(
+                get_suffix_length_for_token_reduction(
+                    events=view.events[self.keep_first :],
+                    llm=agent_llm,
+                    token_reduction=tokens_to_reduce,
+                )
+            )
+
+        # We might have multiple reasons to condense, so pick the strictest condensation
+        # to ensure all resource constraints are met.
+        events_from_tail = min(suffix_events_to_keep)
+
+        # Calculate naive forgetting end (without considering atomic boundaries)
+        naive_end = len(view) - events_from_tail
+
+        # Find actual forgetting_start: smallest manipulation index > keep_first
+        forgetting_start = view.find_next_manipulation_index(
+            self.keep_first, strict=True
+        )
+
+        # Find actual forgetting_end: smallest manipulation index >= naive_end
+        forgetting_end = view.find_next_manipulation_index(naive_end, strict=False)
+
+        # Extract events to forget using boundary-aware indices
+        forgotten_events = view[forgetting_start:forgetting_end]
+
+        # Summary offset is the same as forgetting_start
+        return forgotten_events, forgetting_start
+
+    @observe(ignore_inputs=["view", "agent_llm"])
+    def get_condensation(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> Condensation:
+        # The condensation is dependent on the events we want to drop and the previous
+        # summary.
+        summary_event_content = self._get_summary_event_content(view)
+        forgotten_events, summary_offset = self._get_forgotten_events(
+            view, agent_llm=agent_llm
+        )
+
+        return self._generate_condensation(
+            summary_event_content=summary_event_content,
+            forgotten_events=forgotten_events,
+            summary_offset=summary_offset,
+        )

openhands/sdk/context/condenser/no_op_condenser.py

@@ -1,6 +1,7 @@
 from openhands.sdk.context.condenser.base import CondenserBase
 from openhands.sdk.context.view import View
 from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.llm import LLM
 
 
 class NoOpCondenser(CondenserBase):
@@ -9,5 +10,5 @@ class NoOpCondenser(CondenserBase):
     Primarily intended for testing purposes.
     """
 
-    def condense(self, view: View) -> View | Condensation:
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:  # noqa: ARG002
         return view

openhands/sdk/context/condenser/pipeline_condenser.py

@@ -1,15 +1,16 @@
 from openhands.sdk.context.condenser.base import CondenserBase
 from openhands.sdk.context.view import View
 from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.llm import LLM
 
 
 class PipelineCondenser(CondenserBase):
     """A condenser that applies a sequence of condensers in order.
 
     All condensers are defined primarily by their `condense` method, which takes a
-    `View` and returns either a new `View` or a `Condensation` event. That means we can
-    chain multiple condensers together by passing `View`s along and exiting early if any
-    condenser returns a `Condensation`.
+    `View` and an optional `agent_llm` parameter, returning either a new `View` or a
+    `Condensation` event. That means we can chain multiple condensers together by
+    passing `View`s along and exiting early if any condenser returns a `Condensation`.
 
     For example:
 
@@ -20,20 +21,20 @@ class PipelineCondenser(CondenserBase):
             CondenserC(...),
         ])
 
-        result = condenser.condense(view)
+        result = condenser.condense(view, agent_llm=agent_llm)
 
         # Doing the same thing without the pipeline condenser requires more boilerplate
         # for the monadic chaining
         other_result = view
 
         if isinstance(other_result, View):
-            other_result = CondenserA(...).condense(other_result)
+            other_result = CondenserA(...).condense(other_result, agent_llm=agent_llm)
 
         if isinstance(other_result, View):
-            other_result = CondenserB(...).condense(other_result)
+            other_result = CondenserB(...).condense(other_result, agent_llm=agent_llm)
 
         if isinstance(other_result, View):
-            other_result = CondenserC(...).condense(other_result)
+            other_result = CondenserC(...).condense(other_result, agent_llm=agent_llm)
 
         assert result == other_result
     """
@@ -41,12 +42,12 @@ class PipelineCondenser(CondenserBase):
     condensers: list[CondenserBase]
     """The list of condensers to apply in order."""
 
-    def condense(self, view: View) -> View | Condensation:
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
         result: View | Condensation = view
         for condenser in self.condensers:
             if isinstance(result, Condensation):
                 break
-            result = condenser.condense(result)
+            result = condenser.condense(result, agent_llm=agent_llm)
         return result
 
     def handles_condensation_requests(self) -> bool:

openhands/sdk/context/condenser/utils.py

@@ -0,0 +1,149 @@
+from collections.abc import Sequence
+
+from openhands.sdk.event.base import LLMConvertibleEvent
+from openhands.sdk.llm import LLM
+
+
+def get_total_token_count(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+) -> int:
+    """Calculate the total token count for a list of LLM convertible events.
+
+    This function converts the events to LLM messages and uses the provided LLM
+    to count the total number of tokens. This is useful for understanding how many
+    tokens a sequence of events will consume in the context window.
+
+    Args:
+        events: List of LLM convertible events to count tokens for
+        llm: The LLM instance to use for token counting (uses the litellm's token
+            counting utilities)
+
+    Returns:
+        Total token count for all events converted to messages
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Hello, how are you?", source="user"),
+        ...     MessageEvent.from_text("I'm doing great!", source="agent"),
+        ... ]
+        >>> token_count = get_total_token_count(events, llm)
+        >>> print(f"Total tokens: {token_count}")
+    """
+    messages = LLMConvertibleEvent.events_to_messages(list(events))
+    return llm.get_token_count(messages)
+
+
+def get_shortest_prefix_above_token_count(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+    token_count: int,
+) -> int:
+    """Find the length of the shortest prefix whose token count exceeds the target.
+
+    This function performs a binary search to efficiently find the shortest prefix
+    of events that, when converted to messages, has a total token count greater than
+    the specified target token count.
+
+    Args:
+        events: List of LLM convertible events to search through
+        llm: The LLM instance to use for token counting (uses the model's tokenizer)
+        token_count: The target token count threshold
+
+    Returns:
+        The length of the shortest prefix that exceeds the token count.
+        Returns 0 if no events are provided.
+        Returns len(events) if all events combined don't exceed the token count.
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Hi", source="user"),
+        ...     MessageEvent.from_text("Hello", source="agent"),
+        ...     MessageEvent.from_text("How are you?", source="user"),
+        ...     MessageEvent.from_text("Great!", source="agent"),
+        ... ]
+        >>> prefix_len = get_shortest_prefix_above_token_count(events, llm, 20)
+        >>> # prefix_len might be 2 if first 2 events exceed 20 tokens
+    """
+    if not events:
+        return 0
+
+    # Check if all events combined don't exceed the token count
+    total_tokens = get_total_token_count(events, llm)
+    if total_tokens <= token_count:
+        return len(events)
+
+    # Binary search for the shortest prefix
+    left, right = 1, len(events)
+
+    while left < right:
+        mid = (left + right) // 2
+        prefix_tokens = get_total_token_count(events[:mid], llm)
+
+        if prefix_tokens > token_count:
+            # This prefix exceeds the count, try to find a shorter one
+            right = mid
+        else:
+            # This prefix doesn't exceed, we need a longer one
+            left = mid + 1
+
+    return left
+
+
+def get_suffix_length_for_token_reduction(
+    events: Sequence[LLMConvertibleEvent],
+    llm: LLM,
+    token_reduction: int,
+) -> int:
+    """Find how many suffix events can be kept while reducing tokens by target amount.
+
+    This function determines the maximum number of events from the end of the list
+    that can be retained while ensuring the total token count is reduced by at least
+    the specified amount. It uses the get_shortest_prefix_above_token_count function
+    to find the prefix that must be removed.
+
+    Args:
+        events: List of LLM convertible events
+        llm: The LLM instance to use for token counting (uses the model's tokenizer)
+        token_reduction: The minimum number of tokens to reduce by
+
+    Returns:
+        The number of events from the end that can be kept (suffix length).
+
+    Example:
+        >>> from openhands.sdk.llm import LLM
+        >>> from openhands.sdk.event.llm_convertible import MessageEvent
+        >>>
+        >>> llm = LLM(model="gpt-4")
+        >>> events = [
+        ...     MessageEvent.from_text("Event 1", source="user"),
+        ...     MessageEvent.from_text("Event 2", source="agent"),
+        ...     MessageEvent.from_text("Event 3", source="user"),
+        ...     MessageEvent.from_text("Event 4", source="agent"),
+        ... ]
+        >>> # Suppose total is 100 tokens, and we want to reduce by 40 tokens
+        >>> suffix_len = get_suffix_length_for_token_reduction(events, llm, 40)
+        >>> # suffix_len tells us how many events from the end we can keep
+        >>> # If first 2 events = 45 tokens, suffix_len = 2 (keep last 2 events)
+    """
+    if not events:
+        return 0
+
+    if token_reduction <= 0:
+        return len(events)
+
+    # Find the shortest prefix that exceeds the token reduction target
+    prefix_length = get_shortest_prefix_above_token_count(events, llm, token_reduction)
+
+    # The suffix length is what remains after removing the prefix
+    suffix_length = len(events) - prefix_length
+
+    return suffix_length

openhands/sdk/context/prompts/prompt.py

@@ -4,7 +4,45 @@ import re
 import sys
 from functools import lru_cache
 
-from jinja2 import Environment, FileSystemBytecodeCache, FileSystemLoader, Template
+from jinja2 import (
+    BaseLoader,
+    Environment,
+    FileSystemBytecodeCache,
+    Template,
+    TemplateNotFound,
+)
+
+
+class FlexibleFileSystemLoader(BaseLoader):
+    """A Jinja2 loader that supports both relative paths (within a base directory)
+    and absolute paths anywhere on the filesystem.
+    """
+
+    def __init__(self, searchpath: str):
+        self.searchpath = os.path.abspath(searchpath)
+
+    def get_source(self, environment, template):  # noqa: ARG002
+        # If template is an absolute path, use it directly
+        if os.path.isabs(template):
+            path = template
+        else:
+            # Otherwise, look for it in the searchpath
+            path = os.path.join(self.searchpath, template)
+
+        if not os.path.exists(path):
+            raise TemplateNotFound(template)
+
+        mtime = os.path.getmtime(path)
+        with open(path, encoding="utf-8") as f:
+            source = f.read()
+
+        def uptodate():
+            try:
+                return os.path.getmtime(path) == mtime
+            except OSError:
+                return False
+
+        return source, path, uptodate
 
 
 def refine(text: str) -> str:
@@ -27,7 +65,7 @@ def _get_env(prompt_dir: str) -> Environment:
     os.makedirs(cache_folder, exist_ok=True)
     bcc = FileSystemBytecodeCache(directory=cache_folder)
     env = Environment(
-        loader=FileSystemLoader(prompt_dir),
+        loader=FlexibleFileSystemLoader(prompt_dir),
         bytecode_cache=bcc,
         autoescape=False,
     )

openhands/sdk/context/prompts/templates/system_message_suffix.j2

@@ -14,7 +14,7 @@ Please follow them while working.
 
 {{ system_message_suffix }}
 {% endif %}
-{% if secret_names %}
+{% if secret_infos %}
 <CUSTOM_SECRETS>
 ### Credential Access
 * Automatic secret injection: When you reference a registered secret key in your bash command, the secret value will be automatically exported as an environment variable before your command executes.
@@ -25,8 +25,8 @@ Please follow them while working.
 * If it still fails, report it to the user.
 
 You have access to the following environment variables
-{% for secret_name in secret_names %}
-* **${{ secret_name }}**
+{% for secret_info in secret_infos %}
+* **${{ secret_info.name }}**{% if secret_info.description %} - {{ secret_info.description }}{% endif %}
 {% endfor %}
 </CUSTOM_SECRETS>
 {% endif %}

openhands/sdk/context/skills/__init__.py

@@ -1,6 +1,7 @@
 from openhands.sdk.context.skills.exceptions import SkillValidationError
 from openhands.sdk.context.skills.skill import (
     Skill,
+    load_project_skills,
     load_public_skills,
     load_skills_from_dir,
     load_user_skills,
@@ -21,6 +22,7 @@ __all__ = [
     "SkillKnowledge",
     "load_skills_from_dir",
     "load_user_skills",
+    "load_project_skills",
     "load_public_skills",
     "SkillValidationError",
 ]