Restructure agent-sdk repository into UV workspace with simplified structure (#33)

Co-authored-by: openhands <openhands@all-hands.dev>

Author: xingyaoww

.github/workflows/tests.yml

@@ -28,7 +28,16 @@ jobs:
         run: uv sync --frozen --group dev
 
       - name: Run tests with coverage
-        run: CI=true uv run pytest -vvxss --basetemp="${{ runner.temp }}/pytest" -o tmp_path_retention=none -o tmp_path_retention_count=0 --cov=openhands --cov-report=term-missing tests/
+        run: |
+          CI=true uv run pytest \
+            -vvxss \
+            --basetemp="${{ runner.temp }}/pytest" \
+            -o tmp_path_retention=none \
+            -o tmp_path_retention_count=0 \
+            --cov=openhands/core \
+            --cov=openhands/tools \
+            --cov-report=term-missing \
+            openhands/core/tests openhands/tools/tests tests
 
       - name: Build coverage XML (separate step, lower mem)
         if: always()

examples/hello_world.py

@@ -13,7 +13,7 @@
     Tool,
     get_logger,
 )
-from openhands.core.runtime.tools import (
+from openhands.tools import (
     BashExecutor,
     FileEditorExecutor,
     execute_bash_tool,

openhands/__init__.py

@@ -1,38 +1 @@
-"""OpenHands package."""
-
-import os
-from importlib.metadata import PackageNotFoundError, version
-from pathlib import Path
-
-
-__package_name__ = "openhands-sdk"
-
-
-def get_version():
-    # Try getting the version from pyproject.toml
-    try:
-        root_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-        candidate_paths = [
-            Path(root_dir) / "pyproject.toml",
-            Path(root_dir) / "openhands" / "pyproject.toml",
-        ]
-        for file_path in candidate_paths:
-            if file_path.is_file():
-                with open(file_path, "r") as f:
-                    for line in f:
-                        if line.strip().startswith("version ="):
-                            return line.split("=", 1)[1].strip().strip('"').strip("'")
-    except FileNotFoundError:
-        pass
-
-    try:
-        return version(__package_name__)
-    except (ImportError, PackageNotFoundError):
-        pass
-    return "unknown"
-
-
-try:
-    __version__ = get_version()
-except Exception:
-    __version__ = "unknown"
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

openhands/core/__init__.py

@@ -1,10 +1,17 @@
+from importlib.metadata import PackageNotFoundError, version
+
 from .agenthub import AgentBase, CodeActAgent
 from .config import LLMConfig, MCPConfig, OpenHandsConfig
 from .conversation import Conversation
 from .llm import LLM, ImageContent, Message, TextContent
 from .logger import get_logger
-from .runtime import ActionBase, ObservationBase, Tool
+from .tool import ActionBase, ObservationBase, Tool
+
 
+try:
+    __version__ = version("openhands-core")
+except PackageNotFoundError:
+    __version__ = "0.0.0"  # fallback for editable/unbuilt environments
 
 __all__ = [
     "LLM",
@@ -21,4 +28,5 @@
     "MCPConfig",
     "get_logger",
     "Conversation",
+    "__version__",
 ]

openhands/core/agenthub/agent.py

@@ -4,7 +4,7 @@
 from openhands.core.llm import LLM
 from openhands.core.llm.message import Message
 from openhands.core.logger import get_logger
-from openhands.core.runtime import ActionBase, ObservationBase, Tool
+from openhands.core.tool import ActionBase, ObservationBase, Tool
 
 
 logger = get_logger(__name__)

openhands/core/agenthub/codeact_agent/codeact_agent.py

@@ -8,19 +8,53 @@
     Message as LiteLLMMessage,
     ModelResponse,
 )
+from pydantic import Field
 
 from openhands.core.agenthub.agent import AgentBase
 from openhands.core.agenthub.history import AgentHistory
 from openhands.core.context.env_context import EnvContext
 from openhands.core.context.prompt import PromptManager
 from openhands.core.llm import LLM, Message, TextContent, get_llm_metadata
 from openhands.core.logger import get_logger
-from openhands.core.runtime import ActionBase, ObservationBase, Tool
-from openhands.core.runtime.tools import FinishAction, finish_tool
+from openhands.core.tool import ActionBase, ObservationBase, Tool, ToolAnnotations
 
 
 logger = get_logger(__name__)
 
+"""Finish tool implementation."""
+
+
+class FinishAction(ActionBase):
+    message: str = Field(description="Final message to send to the user.")
+
+
+TOOL_DESCRIPTION = """Signals the completion of the current task or conversation.
+
+Use this tool when:
+- You have successfully completed the user's requested task
+- You cannot proceed further due to technical limitations or missing information
+
+The message should include:
+- A clear summary of actions taken and their results
+- Any next steps for the user
+- Explanation if you're unable to complete the task
+- Any follow-up questions if more information is needed
+"""
+
+
+finish_tool = Tool(
+    name="finish",
+    input_schema=FinishAction,
+    description=TOOL_DESCRIPTION,
+    annotations=ToolAnnotations(
+        title="finish",
+        readOnlyHint=True,
+        destructiveHint=False,
+        idempotentHint=True,
+        openWorldHint=False,
+    ),
+)
+
 
 class CodeActAgent(AgentBase):
     def __init__(

openhands/core/conversation/conversation.py

@@ -8,7 +8,7 @@
 
 from openhands.core.agenthub.agent import AgentBase
 from openhands.core.llm import Message, TextContent
-from openhands.core.runtime import ActionBase, ObservationBase
+from openhands.core.tool import ActionBase, ObservationBase
 
 
 OnEvent = Callable[[Message | ActionBase | ObservationBase], None]

openhands/core/llm/metadata.py

@@ -1,21 +1,28 @@
 import os
 
-import openhands
-
 
 def get_llm_metadata(
     model_name: str,
     agent_name: str,
     session_id: str | None = None,
     user_id: str | None = None,
 ) -> dict:
+    import openhands.core
+    openhands_tools_version: str = "n/a"
+    try:
+        import openhands.tools
+        openhands_tools_version = openhands.tools.__version__
+    except ModuleNotFoundError:
+        pass
+
     metadata = {
-        "trace_version": openhands.__version__,
+        "trace_version": openhands.core.__version__,
         "tags": [
             f"model:{model_name}",
             f"agent:{agent_name}",
             f"web_host:{os.environ.get('WEB_HOST', 'unspecified')}",
-            f"openhands_version:{openhands.__version__}",
+            f"openhands_version:{openhands.core.__version__}",
+            f"openhands_tools_version:{openhands_tools_version}",
         ],
     }
     if session_id is not None:

openhands/core/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "openhands-sdk"
+version = "1.0.0"
+description = "OpenHands SDK - Core functionality for building AI agents"
+
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=2.11.3",
+    "litellm>=1.75.9",
+    "pydantic>=2.11.7",
+    "python-frontmatter>=1.1.0",
+    "tenacity>=9.1.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["openhands"]