hypercli-sdk 2026.4.13.post3__tar.gz → 2026.4.17__tar.gz

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypercli-sdk
-Version: 2026.4.13.post3
+Version: 2026.4.17
 Summary: Python SDK for HyperCLI - GPU orchestration and HyperAgent API
 Project-URL: Homepage, https://hypercli.com
 Project-URL: Documentation, https://docs.hypercli.com
@@ -140,11 +140,14 @@ OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_a
 agent = client.deployments.create_openclaw(
     name="docs-demo",
     start=True,
+    heartbeat={"every": "0m"},  # disable upstream OpenClaw heartbeat runs
     registry_url="git.nedos.co",
     registry_auth={"username": "ci", "password": "token"},
 )
 ```
 
+`heartbeat` maps directly to upstream OpenClaw config at `config.agents.defaults.heartbeat`. Omit it to keep upstream defaults, or pass values such as `heartbeat={"every": "1h", "target": "last"}`.
+
 ## Error Handling
 
 ```python

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/README.md

@@ -109,11 +109,14 @@ OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_a
 agent = client.deployments.create_openclaw(
     name="docs-demo",
     start=True,
+    heartbeat={"every": "0m"},  # disable upstream OpenClaw heartbeat runs
     registry_url="git.nedos.co",
     registry_auth={"username": "ci", "password": "token"},
 )
 ```
 
+`heartbeat` maps directly to upstream OpenClaw config at `config.agents.defaults.heartbeat`. Omit it to keep upstream defaults, or pass values such as `heartbeat={"every": "1h", "target": "last"}`.
+
 ## Error Handling
 
 ```python

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/hypercli/__init__.py

@@ -78,7 +78,7 @@ from .gateway import (
     extract_gateway_chat_tool_calls,
     normalize_gateway_chat_message,
 )
-__version__ = "2026.4.13.post3"
+__version__ = "2026.4.17"
 __all__ = [
     "HyperCLI",
     "configure",

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/hypercli/agents.py

@@ -191,14 +191,23 @@ def _build_agent_launch(
     registry_url: str | None = None,
     registry_auth: dict | None = None,
     gateway_token: str | None = None,
+    heartbeat: dict | None = None,
 ) -> tuple[dict, str]:
-    prepared_config = dict(config or {})
+    prepared_config = copy.deepcopy(config or {})
     nested_launch_keys = sorted(LAUNCH_CONFIG_KEYS.intersection(prepared_config.keys()))
     if nested_launch_keys:
         raise ValueError(
             "Launch settings must be top-level fields, not nested under config: "
             + ", ".join(nested_launch_keys)
         )
+    if heartbeat:
+        agents_cfg = dict(prepared_config.get("agents") or {})
+        defaults_cfg = dict(agents_cfg.get("defaults") or {})
+        heartbeat_cfg = dict(defaults_cfg.get("heartbeat") or {})
+        heartbeat_cfg.update(dict(heartbeat))
+        defaults_cfg["heartbeat"] = heartbeat_cfg
+        agents_cfg["defaults"] = defaults_cfg
+        prepared_config["agents"] = agents_cfg
     env_map = dict(env or {})
     if env:
         env_map.update(env)
@@ -1015,6 +1024,7 @@ class Deployments:
         registry_url: str = None,
         registry_auth: dict = None,
         gateway_token: str = None,
+        heartbeat: dict = None,
         meta_ui: dict = None,
         dry_run: bool = False,
         start: bool = True,
@@ -1045,6 +1055,7 @@ class Deployments:
             registry_url=registry_url,
             registry_auth=registry_auth,
             gateway_token=gateway_token,
+            heartbeat=heartbeat,
         )
         body: dict = {**launch_payload, "start": start}
         if dry_run:
@@ -1083,6 +1094,7 @@ class Deployments:
         registry_url: str = None,
         registry_auth: dict = None,
         gateway_token: str = None,
+        heartbeat: dict = None,
         meta_ui: dict = None,
         dry_run: bool = False,
         start: bool = True,
@@ -1110,6 +1122,7 @@ class Deployments:
             registry_url=registry_url,
             registry_auth=registry_auth,
             gateway_token=gateway_token,
+            heartbeat=heartbeat,
             meta_ui=meta_ui,
             dry_run=dry_run,
             start=start,
@@ -1185,6 +1198,7 @@ class Deployments:
         registry_url: str = None,
         registry_auth: dict = None,
         gateway_token: str = None,
+        heartbeat: dict = None,
         dry_run: bool = False,
     ) -> Agent:
         """Start a previously stopped agent.
@@ -1208,6 +1222,7 @@ class Deployments:
             registry_url=registry_url,
             registry_auth=registry_auth,
             gateway_token=gateway_token,
+            heartbeat=heartbeat,
         )
         body: dict[str, Any] = dict(launch_payload)
         if dry_run:
@@ -1236,6 +1251,7 @@ class Deployments:
         registry_url: str = None,
         registry_auth: dict = None,
         gateway_token: str = None,
+        heartbeat: dict = None,
         dry_run: bool = False,
         openclaw_routes: dict | None = None,
         openclaw_route_options: dict | None = None,
@@ -1259,6 +1275,7 @@ class Deployments:
             registry_url=registry_url,
             registry_auth=registry_auth,
             gateway_token=gateway_token,
+            heartbeat=heartbeat,
             dry_run=dry_run,
         )
 

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/hypercli/voice.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 """Voice API client."""
+import os
 from pathlib import Path
 from typing import TYPE_CHECKING
 import base64
@@ -17,9 +18,22 @@ def _encode_reference_audio(ref_audio: bytes | str | Path) -> str:
     return base64.b64encode(audio_bytes).decode()
 
 
+def _default_voice_timeout() -> float:
+    raw_value = os.environ.get("HYPER_VOICE_TIMEOUT_SECONDS", "300").strip()
+    try:
+        return float(raw_value)
+    except ValueError:
+        return 300.0
+
+
+def _resolve_voice_timeout(timeout: float | None) -> float:
+    if timeout is not None:
+        return float(timeout)
+    return _default_voice_timeout()
+
+
 class VoiceAPI:
     """Voice capability API wrapper."""
-
     DEFAULT_TIMEOUT = 300.0
 
     def __init__(self, http: "HTTPClient"):
@@ -32,7 +46,7 @@ class VoiceAPI:
         voice: str = "Chelsie",
         language: str = "auto",
         response_format: str = "mp3",
-        timeout: float = DEFAULT_TIMEOUT,
+        timeout: float | None = None,
     ) -> bytes:
         return self._http.post_bytes(
             "/agents/voice/tts",
@@ -42,7 +56,7 @@ class VoiceAPI:
                 "language": language,
                 "response_format": response_format,
             },
-            timeout=timeout,
+            timeout=_resolve_voice_timeout(timeout),
         )
 
     def clone(
@@ -53,7 +67,7 @@ class VoiceAPI:
         language: str = "auto",
         x_vector_only: bool = True,
         response_format: str = "mp3",
-        timeout: float = DEFAULT_TIMEOUT,
+        timeout: float | None = None,
     ) -> bytes:
         return self._http.post_bytes(
             "/agents/voice/clone",
@@ -64,7 +78,7 @@ class VoiceAPI:
                 "x_vector_only": x_vector_only,
                 "response_format": response_format,
             },
-            timeout=timeout,
+            timeout=_resolve_voice_timeout(timeout),
         )
 
     def design(
@@ -74,7 +88,7 @@ class VoiceAPI:
         description: str,
         language: str = "auto",
         response_format: str = "mp3",
-        timeout: float = DEFAULT_TIMEOUT,
+        timeout: float | None = None,
     ) -> bytes:
         return self._http.post_bytes(
             "/agents/voice/design",
@@ -84,5 +98,5 @@ class VoiceAPI:
                 "language": language,
                 "response_format": response_format,
             },
-            timeout=timeout,
+            timeout=_resolve_voice_timeout(timeout),
         )

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypercli-sdk"
-version = "2026.4.13.post3"
+version = "2026.4.17"
 description = "Python SDK for HyperCLI - GPU orchestration and HyperAgent API"
 readme = "README.md"
 requires-python = ">=3.10"

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/tests/integration/test_agents.py

@@ -12,32 +12,48 @@ def _create_agent_with_available_tier(client: HyperCLI, name: str, tags: list[st
     budget = client.deployments.budget()
     slots = (budget or {}).get("slots") or {}
 
-    tier = next((candidate for candidate in ("large", "medium", "small") if int((slots.get(candidate) or {}).get("available") or 0) > 0), None)
-    if not tier:
+    tiers = [
+        candidate
+        for candidate in ("large", "medium", "small")
+        if int((slots.get(candidate) or {}).get("available") or 0) > 0
+    ]
+    if not tiers:
         raise AssertionError("No available entitlement slots for integration agent tests")
 
-    agent_id: str | None = None
-    try:
-        agent = client.deployments.create(
-            name=name,
-            size=tier,
-            start=False,
-            tags=tags,
-        )
-        agent_id = agent.id
-        client.deployments.start_openclaw(agent.id, dry_run=True)
-        return agent.id, tier
-    except APIError as exc:
-        if agent_id:
-            try:
-                client.deployments.delete(agent_id)
-            except APIError:
-                pass
-        if exc.status_code == 429:
-            raise AssertionError(
-                f"Budget reported '{tier}' available but dry-run start was rejected for slot exhaustion"
-            ) from exc
-        raise
+    last_error: Exception | None = None
+    for tier in tiers:
+        agent_id: str | None = None
+        try:
+            agent = client.deployments.create(
+                name=name,
+                size=tier,
+                start=False,
+                tags=tags,
+            )
+            agent_id = agent.id
+            client.deployments.start_openclaw(agent.id, dry_run=True)
+            return agent.id, tier
+        except APIError as exc:
+            if agent_id:
+                try:
+                    client.deployments.delete(agent_id)
+                except APIError:
+                    pass
+            if exc.status_code == 429:
+                last_error = AssertionError(
+                    f"Budget reported '{tier}' available but dry-run start was rejected for slot exhaustion"
+                )
+                continue
+            if exc.status_code == 503 and "No connected clusters available for tags" in str(exc.detail):
+                last_error = AssertionError(
+                    f"Tier '{tier}' has entitlement capacity but no connected clusters are advertising that tag"
+                )
+                continue
+            raise
+
+    if last_error:
+        raise last_error
+    raise AssertionError("Failed to create an integration agent with any available tier")
 
 
 def test_list_agents_requires_agent_key(client, test_agent_api_key: str):

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/tests/test_agents.py

@@ -416,6 +416,27 @@ def test_build_agent_launch_includes_command_and_entrypoint():
     assert launch["routes"] == {"web": {"port": 80, "prefix": ""}}
 
 
+def test_build_agent_launch_merges_heartbeat_defaults():
+    launch, _gateway_token = _build_agent_launch(
+        {"agents": {"defaults": {"model": "openai/gpt-5.4", "heartbeat": {"target": "last"}}}},
+        heartbeat={"every": "0m", "includeSystemPromptSection": False},
+        gateway_token="gw-token",
+    )
+
+    assert launch["config"] == {
+        "agents": {
+            "defaults": {
+                "model": "openai/gpt-5.4",
+                "heartbeat": {
+                    "target": "last",
+                    "every": "0m",
+                    "includeSystemPromptSection": False,
+                },
+            }
+        }
+    }
+
+
 def test_build_openclaw_routes_defaults():
     assert build_openclaw_routes() == {
         "openclaw": {"port": 18789, "auth": False, "prefix": ""},
@@ -485,6 +506,35 @@ def test_create_openclaw_respects_explicit_empty_routes(agents_client):
         assert posted_json["image"] == DEFAULT_OPENCLAW_IMAGE
         assert posted_json["routes"] == {}
 
+
+def test_create_openclaw_includes_heartbeat_when_requested(agents_client):
+    with patch("httpx.Client") as mock_client_class, patch("hypercli.agents.secrets.token_hex", return_value="gw-token-123"):
+        mock_client = MagicMock()
+        mock_response = Mock()
+        mock_response.status_code = 200
+        mock_response.json.return_value = {
+            "id": "agent-123",
+            "user_id": "user-456",
+            "pod_id": "pod-789",
+            "pod_name": "test-pod",
+            "state": "starting",
+        }
+        mock_client.post.return_value = mock_response
+        mock_client.__enter__.return_value = mock_client
+        mock_client.__exit__.return_value = False
+        mock_client_class.return_value = mock_client
+
+        agents_client.create_openclaw(
+            name="test-agent",
+            heartbeat={"every": "0m", "includeSystemPromptSection": False},
+        )
+
+        posted_json = mock_client.post.call_args[1]["json"]
+        assert posted_json["config"]["agents"]["defaults"]["heartbeat"] == {
+            "every": "0m",
+            "includeSystemPromptSection": False,
+        }
+
 @pytest.fixture
 def mock_http():
     http = Mock(spec=HTTPClient)
@@ -970,7 +1020,7 @@ def test_agents_create_scoped_key(agents_client):
             "key_id": "key-123",
             "name": "agent-client",
             "api_key": "hyper_api_scoped",
-            "tags": ["agent=agent-123"],
+            "tags": ["agent:agent-123"],
         }
         mock_client.post.return_value = mock_response
         mock_client.__enter__.return_value = mock_client

{hypercli_sdk-2026.4.13.post3 → hypercli_sdk-2026.4.17}/tests/test_voice.py

@@ -70,3 +70,14 @@ def test_voice_design_posts_description():
             VoiceAPI.DEFAULT_TIMEOUT,
         )
     ]
+
+
+def test_voice_timeout_uses_env_default(monkeypatch):
+    monkeypatch.setenv("HYPER_VOICE_TIMEOUT_SECONDS", "720")
+
+    http = DummyVoiceHTTP()
+    voice = VoiceAPI(http)
+
+    voice.tts("hello")
+
+    assert http.calls[0][2] == 720.0