openhands-sdk 1.7.0__py3-none-any.whl

openhands/sdk/context/agent_context.py

@@ -0,0 +1,240 @@
+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.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) -> 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]
+        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:
+            # TODO(test): add a test for this rendering to make sure they work
+            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,95 @@
+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.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) -> 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.
+
+        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) -> bool:
+        """Determine if a view should be condensed."""
+
+    @abstractmethod
+    def get_condensation(self, view: View) -> Condensation:
+        """Get the condensation from a view."""
+
+    def condense(self, view: View) -> View | Condensation:
+        # If we trigger the condenser-specific condensation threshold, compute and
+        # return the condensation.
+        if self.should_condense(view):
+            return self.get_condensation(view)
+
+        # Otherwise we're safe to just return the view.
+        else:
+            return view

openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -0,0 +1,89 @@
+import os
+
+from pydantic import Field, model_validator
+
+from openhands.sdk.context.condenser.base import RollingCondenser
+from openhands.sdk.context.prompts import render_template
+from openhands.sdk.context.view import View
+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 LLMSummarizingCondenser(RollingCondenser):
+    llm: LLM
+    max_size: int = Field(default=120, gt=0)
+    keep_first: int = Field(default=4, 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 should_condense(self, view: View) -> bool:
+        if view.unhandled_condensation_request:
+            return True
+        return len(view) > self.max_size
+
+    @observe(ignore_inputs=["view"])
+    def get_condensation(self, view: View) -> Condensation:
+        head = view[: self.keep_first]
+        target_size = self.max_size // 2
+        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
+
+        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
+
+        # Identify events to be forgotten (those not in head or tail)
+        forgotten_events = view[self.keep_first : -events_from_tail]
+
+        # 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=self.keep_first,
+            llm_response_id=llm_response.id,
+        )

openhands/sdk/context/condenser/no_op_condenser.py

@@ -0,0 +1,13 @@
+from openhands.sdk.context.condenser.base import CondenserBase
+from openhands.sdk.context.view import View
+from openhands.sdk.event.condenser import Condensation
+
+
+class NoOpCondenser(CondenserBase):
+    """Simple condenser that returns a view un-manipulated.
+
+    Primarily intended for testing purposes.
+    """
+
+    def condense(self, view: View) -> View | Condensation:
+        return view

openhands/sdk/context/condenser/pipeline_condenser.py

@@ -0,0 +1,55 @@
+from openhands.sdk.context.condenser.base import CondenserBase
+from openhands.sdk.context.view import View
+from openhands.sdk.event.condenser import Condensation
+
+
+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`.
+
+    For example:
+
+        # Use the pipeline condenser to chain multiple other condensers together
+        condenser = PipelineCondenser(condensers=[
+            CondenserA(...),
+            CondenserB(...),
+            CondenserC(...),
+        ])
+
+        result = condenser.condense(view)
+
+        # 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)
+
+        if isinstance(other_result, View):
+            other_result = CondenserB(...).condense(other_result)
+
+        if isinstance(other_result, View):
+            other_result = CondenserC(...).condense(other_result)
+
+        assert result == other_result
+    """
+
+    condensers: list[CondenserBase]
+    """The list of condensers to apply in order."""
+
+    def condense(self, view: View) -> View | Condensation:
+        result: View | Condensation = view
+        for condenser in self.condensers:
+            if isinstance(result, Condensation):
+                break
+            result = condenser.condense(result)
+        return result
+
+    def handles_condensation_requests(self) -> bool:
+        return any(
+            condenser.handles_condensation_requests() for condenser in self.condensers
+        )

openhands/sdk/context/condenser/prompts/summarizing_prompt.j2

@@ -0,0 +1,59 @@
+You are maintaining a context-aware state summary for an interactive agent.
+You will be given a list of events corresponding to actions taken by the agent, and the most recent previous summary if one exists.
+If the events being summarized contain ANY task-tracking, you MUST include a TASK_TRACKING section to maintain continuity.
+When referencing tasks make sure to preserve exact task IDs and statuses.
+
+Track:
+
+USER_CONTEXT: (Preserve essential user requirements, goals, and clarifications in concise form)
+
+TASK_TRACKING: {Active tasks, their IDs and statuses - PRESERVE TASK IDs}
+
+COMPLETED: (Tasks completed so far, with brief results)
+PENDING: (Tasks that still need to be done)
+CURRENT_STATE: (Current variables, data structures, or relevant state)
+
+For code-specific tasks, also include:
+CODE_STATE: {File paths, function signatures, data structures}
+TESTS: {Failing cases, error messages, outputs}
+CHANGES: {Code edits, variable updates}
+DEPS: {Dependencies, imports, external calls}
+VERSION_CONTROL_STATUS: {Repository state, current branch, PR status, commit history}
+
+PRIORITIZE:
+1. Adapt tracking format to match the actual task type
+2. Capture key user requirements and goals
+3. Distinguish between completed and pending tasks
+4. Keep all sections concise and relevant
+
+SKIP: Tracking irrelevant details for the current task type
+
+Example formats:
+
+For code tasks:
+USER_CONTEXT: Fix FITS card float representation issue
+COMPLETED: Modified mod_float() in card.py, all tests passing
+PENDING: Create PR, update documentation
+CODE_STATE: mod_float() in card.py updated
+TESTS: test_format() passed
+CHANGES: str(val) replaces f"{val:.16G}"
+DEPS: None modified
+VERSION_CONTROL_STATUS: Branch: fix-float-precision, Latest commit: a1b2c3d
+
+For other tasks:
+USER_CONTEXT: Write 20 haikus based on coin flip results
+COMPLETED: 15 haikus written for results [T,H,T,H,T,H,T,T,H,T,H,T,H,T,H]
+PENDING: 5 more haikus needed
+CURRENT_STATE: Last flip: Heads, Haiku count: 15/20
+
+<PREVIOUS SUMMARY>
+{{ previous_summary }}
+</PREVIOUS SUMMARY>
+
+{% for event in events %}
+<EVENT>
+{{ event }}
+</EVENT>
+{% endfor %}
+
+Now summarize the events using the rules above.

openhands/sdk/context/prompts/__init__.py

@@ -0,0 +1,6 @@
+from openhands.sdk.context.prompts.prompt import render_template
+
+
+__all__ = [
+    "render_template",
+]