openhands-sdk 1.7.3__py3-none-any.whl

openhands/sdk/context/agent_context.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import pathlib
+from collections.abc import Mapping
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from openhands.sdk.context.prompts import render_template
+from openhands.sdk.context.skills import (
+    Skill,
+    SkillKnowledge,
+    load_public_skills,
+    load_user_skills,
+)
+from openhands.sdk.llm import Message, TextContent
+from openhands.sdk.llm.utils.model_prompt_spec import get_model_prompt_spec
+from openhands.sdk.logger import get_logger
+from openhands.sdk.secret import SecretSource, SecretValue
+
+
+logger = get_logger(__name__)
+
+PROMPT_DIR = pathlib.Path(__file__).parent / "prompts" / "templates"
+
+
+class AgentContext(BaseModel):
+    """Central structure for managing prompt extension.
+
+    AgentContext unifies all the contextual inputs that shape how the system
+    extends and interprets user prompts. It combines both static environment
+    details and dynamic, user-activated extensions from skills.
+
+    Specifically, it provides:
+    - **Repository context / Repo Skills**: Information about the active codebase,
+      branches, and repo-specific instructions contributed by repo skills.
+    - **Runtime context**: Current execution environment (hosts, working
+      directory, secrets, date, etc.).
+    - **Conversation instructions**: Optional task- or channel-specific rules
+      that constrain or guide the agent’s behavior across the session.
+    - **Knowledge Skills**: Extensible components that can be triggered by user input
+      to inject knowledge or domain-specific guidance.
+
+    Together, these elements make AgentContext the primary container responsible
+    for assembling, formatting, and injecting all prompt-relevant context into
+    LLM interactions.
+    """  # noqa: E501
+
+    skills: list[Skill] = Field(
+        default_factory=list,
+        description="List of available skills that can extend the user's input.",
+    )
+    system_message_suffix: str | None = Field(
+        default=None, description="Optional suffix to append to the system prompt."
+    )
+    user_message_suffix: str | None = Field(
+        default=None, description="Optional suffix to append to the user's message."
+    )
+    load_user_skills: bool = Field(
+        default=False,
+        description=(
+            "Whether to automatically load user skills from ~/.openhands/skills/ "
+            "and ~/.openhands/microagents/ (for backward compatibility). "
+        ),
+    )
+    load_public_skills: bool = Field(
+        default=False,
+        description=(
+            "Whether to automatically load skills from the public OpenHands "
+            "skills repository at https://github.com/OpenHands/skills. "
+            "This allows you to get the latest skills without SDK updates."
+        ),
+    )
+    secrets: Mapping[str, SecretValue] | None = Field(
+        default=None,
+        description=(
+            "Dictionary mapping secret keys to values or secret sources. "
+            "Secrets are used for authentication and sensitive data handling. "
+            "Values can be either strings or SecretSource instances "
+            "(str | SecretSource)."
+        ),
+    )
+
+    @field_validator("skills")
+    @classmethod
+    def _validate_skills(cls, v: list[Skill], _info):
+        if not v:
+            return v
+        # Check for duplicate skill names
+        seen_names = set()
+        for skill in v:
+            if skill.name in seen_names:
+                raise ValueError(f"Duplicate skill name found: {skill.name}")
+            seen_names.add(skill.name)
+        return v
+
+    @model_validator(mode="after")
+    def _load_user_skills(self):
+        """Load user skills from home directory if enabled."""
+        if not self.load_user_skills:
+            return self
+
+        try:
+            user_skills = load_user_skills()
+            # Merge user skills with explicit skills, avoiding duplicates
+            existing_names = {skill.name for skill in self.skills}
+            for user_skill in user_skills:
+                if user_skill.name not in existing_names:
+                    self.skills.append(user_skill)
+                else:
+                    logger.warning(
+                        f"Skipping user skill '{user_skill.name}' "
+                        f"(already in explicit skills)"
+                    )
+        except Exception as e:
+            logger.warning(f"Failed to load user skills: {str(e)}")
+
+        return self
+
+    @model_validator(mode="after")
+    def _load_public_skills(self):
+        """Load public skills from OpenHands skills repository if enabled."""
+        if not self.load_public_skills:
+            return self
+        try:
+            public_skills = load_public_skills()
+            # Merge public skills with explicit skills, avoiding duplicates
+            existing_names = {skill.name for skill in self.skills}
+            for public_skill in public_skills:
+                if public_skill.name not in existing_names:
+                    self.skills.append(public_skill)
+                else:
+                    logger.warning(
+                        f"Skipping public skill '{public_skill.name}' "
+                        f"(already in existing skills)"
+                    )
+        except Exception as e:
+            logger.warning(f"Failed to load public skills: {str(e)}")
+        return self
+
+    def get_secret_infos(self) -> list[dict[str, str]]:
+        """Get secret information (name and description) from the secrets field.
+
+        Returns:
+            List of dictionaries with 'name' and 'description' keys.
+            Returns an empty list if no secrets are configured.
+            Description will be None if not available.
+        """
+        if not self.secrets:
+            return []
+        secret_infos = []
+        for name, secret_value in self.secrets.items():
+            description = None
+            if isinstance(secret_value, SecretSource):
+                description = secret_value.description
+            secret_infos.append({"name": name, "description": description})
+        return secret_infos
+
+    def get_system_message_suffix(
+        self,
+        llm_model: str | None = None,
+        llm_model_canonical: str | None = None,
+    ) -> str | None:
+        """Get the system message with repo skill content and custom suffix.
+
+        Custom suffix can typically includes:
+        - Repository information (repo name, branch name, PR number, etc.)
+        - Runtime information (e.g., available hosts, current date)
+        - Conversation instructions (e.g., user preferences, task details)
+        - Repository-specific instructions (collected from repo skills)
+        """
+        repo_skills = [s for s in self.skills if s.trigger is None]
+
+        # Gate vendor-specific repo skills based on model family.
+        if llm_model or llm_model_canonical:
+            spec = get_model_prompt_spec(llm_model or "", llm_model_canonical)
+            family = (spec.family or "").lower()
+            if family:
+                filtered: list[Skill] = []
+                for s in repo_skills:
+                    n = (s.name or "").lower()
+                    if n == "claude" and not (
+                        "anthropic" in family or "claude" in family
+                    ):
+                        continue
+                    if n == "gemini" and not (
+                        "gemini" in family or "google_gemini" in family
+                    ):
+                        continue
+                    filtered.append(s)
+                repo_skills = filtered
+
+        logger.debug(f"Triggered {len(repo_skills)} repository skills: {repo_skills}")
+        # Build the workspace context information
+        secret_infos = self.get_secret_infos()
+        if repo_skills or self.system_message_suffix or secret_infos:
+            formatted_text = render_template(
+                prompt_dir=str(PROMPT_DIR),
+                template_name="system_message_suffix.j2",
+                repo_skills=repo_skills,
+                system_message_suffix=self.system_message_suffix or "",
+                secret_infos=secret_infos,
+            ).strip()
+            return formatted_text
+        elif self.system_message_suffix and self.system_message_suffix.strip():
+            return self.system_message_suffix.strip()
+        return None
+
+    def get_user_message_suffix(
+        self, user_message: Message, skip_skill_names: list[str]
+    ) -> tuple[TextContent, list[str]] | None:
+        """Augment the user’s message with knowledge recalled from skills.
+
+        This works by:
+        - Extracting the text content of the user message
+        - Matching skill triggers against the query
+        - Returning formatted knowledge and triggered skill names if relevant skills were triggered
+        """  # noqa: E501
+
+        user_message_suffix = None
+        if self.user_message_suffix and self.user_message_suffix.strip():
+            user_message_suffix = self.user_message_suffix.strip()
+
+        query = "\n".join(
+            c.text for c in user_message.content if isinstance(c, TextContent)
+        ).strip()
+        recalled_knowledge: list[SkillKnowledge] = []
+        # skip empty queries, but still return user_message_suffix if it exists
+        if not query:
+            if user_message_suffix:
+                return TextContent(text=user_message_suffix), []
+            return None
+        # Search for skill triggers in the query
+        for skill in self.skills:
+            if not isinstance(skill, Skill):
+                continue
+            trigger = skill.match_trigger(query)
+            if trigger and skill.name not in skip_skill_names:
+                logger.info(
+                    "Skill '%s' triggered by keyword '%s'",
+                    skill.name,
+                    trigger,
+                )
+                recalled_knowledge.append(
+                    SkillKnowledge(
+                        name=skill.name,
+                        trigger=trigger,
+                        content=skill.content,
+                    )
+                )
+        if recalled_knowledge:
+            formatted_skill_text = render_template(
+                prompt_dir=str(PROMPT_DIR),
+                template_name="skill_knowledge_info.j2",
+                triggered_agents=recalled_knowledge,
+            )
+            if user_message_suffix:
+                formatted_skill_text += "\n" + user_message_suffix
+            return TextContent(text=formatted_skill_text), [
+                k.name for k in recalled_knowledge
+            ]
+
+        if user_message_suffix:
+            return TextContent(text=user_message_suffix), []
+        return None

openhands/sdk/context/condenser/__init__.py

@@ -0,0 +1,18 @@
+from openhands.sdk.context.condenser.base import (
+    CondenserBase,
+    RollingCondenser,
+)
+from openhands.sdk.context.condenser.llm_summarizing_condenser import (
+    LLMSummarizingCondenser,
+)
+from openhands.sdk.context.condenser.no_op_condenser import NoOpCondenser
+from openhands.sdk.context.condenser.pipeline_condenser import PipelineCondenser
+
+
+__all__ = [
+    "CondenserBase",
+    "RollingCondenser",
+    "NoOpCondenser",
+    "PipelineCondenser",
+    "LLMSummarizingCondenser",
+]

openhands/sdk/context/condenser/base.py

@@ -0,0 +1,100 @@
+from abc import ABC, abstractmethod
+from logging import getLogger
+
+from openhands.sdk.context.view import View
+from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.llm import LLM
+from openhands.sdk.utils.models import (
+    DiscriminatedUnionMixin,
+)
+
+
+logger = getLogger(__name__)
+
+
+class CondenserBase(DiscriminatedUnionMixin, ABC):
+    """Abstract condenser interface.
+
+    Condensers take a list of `Event` objects and reduce them into a potentially smaller
+    list.
+
+    Agents can use condensers to reduce the amount of events they need to consider when
+    deciding which action to take. To use a condenser, agents can call the
+    `condensed_history` method on the current `State` being considered and use the
+    results instead of the full history.
+
+    If the condenser returns a `Condensation` instead of a `View`, the agent should
+    return `Condensation.action` instead of producing its own action. On the next agent
+    step the condenser will use that condensation event to produce a new `View`.
+    """
+
+    @abstractmethod
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
+        """Condense a sequence of events into a potentially smaller list.
+
+        New condenser strategies should override this method to implement their own
+        condensation logic. Call `self.add_metadata` in the implementation to record any
+        relevant per-condensation diagnostic information.
+
+        Args:
+            view: A view of the history containing all events that should be condensed.
+            agent_llm: LLM instance used by the agent. Condensers use this for token
+                counting purposes. Defaults to None.
+
+        Returns:
+            View | Condensation: A condensed view of the events or an event indicating
+            the history has been condensed.
+        """
+
+    def handles_condensation_requests(self) -> bool:
+        """Whether this condenser handles explicit condensation requests.
+
+        If this returns True, the agent will trigger the condenser whenever a
+        CondensationRequest event is added to the history. If False, the condenser will
+        only be triggered when the agent's own logic decides to do so (e.g. context
+        window exceeded).
+
+        Returns:
+            bool: True if the condenser handles explicit condensation requests, False
+            otherwise.
+        """
+        return False
+
+
+class PipelinableCondenserBase(CondenserBase):
+    """Abstract condenser interface which may be pipelined. (Since a pipeline
+    condenser should not nest another pipeline condenser)"""
+
+
+class RollingCondenser(PipelinableCondenserBase, ABC):
+    """Base class for a specialized condenser strategy that applies condensation to a
+    rolling history.
+
+    The rolling history is generated by `View.from_events`, which analyzes all events in
+    the history and produces a `View` object representing what will be sent to the LLM.
+
+    If `should_condense` says so, the condenser is then responsible for generating a
+    `Condensation` object from the `View` object. This will be added to the event
+    history which should -- when given to `get_view` -- produce the condensed `View` to
+    be passed to the LLM.
+    """
+
+    @abstractmethod
+    def should_condense(self, view: View, agent_llm: LLM | None = None) -> bool:
+        """Determine if a view should be condensed."""
+
+    @abstractmethod
+    def get_condensation(
+        self, view: View, agent_llm: LLM | None = None
+    ) -> Condensation:
+        """Get the condensation from a view."""
+
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
+        # If we trigger the condenser-specific condensation threshold, compute and
+        # return the condensation.
+        if self.should_condense(view, agent_llm=agent_llm):
+            return self.get_condensation(view, agent_llm=agent_llm)
+
+        # Otherwise we're safe to just return the view.
+        else:
+            return view

openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -0,0 +1,248 @@
+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=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):
+        events_from_tail = self.max_size // 2 - self.keep_first - 1
+        if events_from_tail <= 0:
+            raise ValueError(
+                "keep_first must be less than max_size // 2 to leave room for "
+                "condensation"
+            )
+        return self
+
+    def handles_condensation_requests(self) -> bool:
+        return True
+
+    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.
+
+        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:
+            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
+        if isinstance(summary_event, MessageEvent):
+            message_content = summary_event.llm_message.content[0]
+            if isinstance(message_content, TextContent):
+                summary_event_content = message_content.text
+
+        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.
+
+        Raises:
+            ValueError: If forgotten_events is empty (0 events to condense).
+        """
+        if len(forgotten_events) == 0:
+            raise ValueError(
+                "Cannot condense 0 events. This typically occurs when a tool loop "
+                "spans almost the entire view, leaving no valid range for forgetting "
+                "events. Consider adjusting keep_first or max_size parameters."
+            )
+
+        # Convert events to strings for the template
+        event_strings = [str(forgotten_event) for forgotten_event in forgotten_events]
+
+        prompt = render_template(
+            os.path.join(os.path.dirname(__file__), "prompts"),
+            "summarizing_prompt.j2",
+            previous_summary=summary_event_content,
+            events=event_strings,
+        )
+
+        messages = [Message(role="user", content=[TextContent(text=prompt)])]
+
+        # Do not pass extra_body explicitly. The LLM handles forwarding
+        # litellm_extra_body only when it is non-empty.
+        llm_response = self.llm.completion(
+            messages=messages,
+        )
+        # Extract summary from the LLMResponse message
+        summary = None
+        if llm_response.message.content:
+            first_content = llm_response.message.content[0]
+            if isinstance(first_content, TextContent):
+                summary = first_content.text
+
+        return Condensation(
+            forgotten_event_ids=[event.id for event in forgotten_events],
+            summary=summary,
+            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

@@ -0,0 +1,14 @@
+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):
+    """Simple condenser that returns a view un-manipulated.
+
+    Primarily intended for testing purposes.
+    """
+
+    def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:  # noqa: ARG002
+        return view