hypercli-sdk 0.7.0__tar.gz → 0.8.0__tar.gz

{hypercli_sdk-0.7.0 → hypercli_sdk-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypercli-sdk
-Version: 0.7.0
+Version: 0.8.0
 Summary: Python SDK for HyperCLI - GPU orchestration and LLM API
 Project-URL: Homepage, https://hypercli.com
 Project-URL: Documentation, https://docs.hypercli.com
@@ -16,10 +16,13 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: websockets>=15.0.1
+Provides-Extra: claw
+Requires-Dist: openai>=1.0.0; extra == 'claw'
 Provides-Extra: comfyui
 Requires-Dist: comfyui-workflow-templates-media-image>=0.3.0; extra == 'comfyui'
 Requires-Dist: comfyui-workflow-templates>=0.7.0; extra == 'comfyui'
 Provides-Extra: dev
+Requires-Dist: openai>=1.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.3.0; extra == 'dev'

{hypercli_sdk-0.7.0 → hypercli_sdk-0.8.0}/hypercli/__init__.py

@@ -8,6 +8,7 @@ from .renders import Render, RenderStatus
 from .files import File, AsyncFiles
 from .job import BaseJob, ComfyUIJob, GradioJob, apply_params, apply_graph_modes, find_node, find_nodes, load_template, graph_to_api, expand_subgraphs, DEFAULT_OBJECT_INFO
 from .logs import LogStream, stream_logs, fetch_logs
+from .claw import Claw, ClawKey, ClawPlan, ClawModel
 
 __version__ = "0.5.0"
 __all__ = [
@@ -56,4 +57,9 @@ __all__ = [
     "LogStream",
     "stream_logs",
     "fetch_logs",
+    # HyperClaw
+    "Claw",
+    "ClawKey",
+    "ClawPlan",
+    "ClawModel",
 ]

hypercli_sdk-0.8.0/hypercli/claw.py

@@ -0,0 +1,303 @@
+"""
+HyperClaw API client
+
+Provides access to the HyperClaw inference API for AI agents.
+Uses the official OpenAI Python client for chat completions.
+"""
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any, Union
+from datetime import datetime
+from .http import HTTPClient
+
+# OpenAI client is optional - only needed for chat
+try:
+    from openai import OpenAI
+    OPENAI_AVAILABLE = True
+except ImportError:
+    OPENAI_AVAILABLE = False
+
+
+@dataclass
+class ClawKey:
+    """HyperClaw API key with subscription details."""
+    key: str
+    plan_id: str
+    expires_at: datetime
+    tpm_limit: int
+    rpm_limit: int
+    user_id: Optional[str] = None
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "ClawKey":
+        expires = data.get("expires_at", "")
+        if isinstance(expires, str):
+            expires = datetime.fromisoformat(expires.replace("Z", "+00:00"))
+        return cls(
+            key=data["key"],
+            plan_id=data["plan_id"],
+            expires_at=expires,
+            tpm_limit=data.get("tpm_limit", 0),
+            rpm_limit=data.get("rpm_limit", 0),
+            user_id=data.get("user_id"),
+        )
+
+
+@dataclass
+class ClawPlan:
+    """HyperClaw subscription plan."""
+    id: str
+    name: str
+    price_usd: float
+    tpm_limit: int
+    rpm_limit: int
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "ClawPlan":
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            price_usd=data["price_usd"],
+            tpm_limit=data["tpm_limit"],
+            rpm_limit=data["rpm_limit"],
+        )
+
+
+@dataclass  
+class ClawModel:
+    """Available model on HyperClaw."""
+    id: str
+    name: str
+    context_length: int
+    supports_vision: bool = False
+    supports_function_calling: bool = False
+    supports_tool_choice: bool = False
+    
+    @classmethod
+    def from_dict(cls, data: dict) -> "ClawModel":
+        caps = data.get("capabilities", {})
+        return cls(
+            id=data["id"],
+            name=data.get("name", data["id"]),
+            context_length=data.get("context_length", 0),
+            supports_vision=caps.get("supports_vision", False),
+            supports_function_calling=caps.get("supports_function_calling", False),
+            supports_tool_choice=caps.get("supports_tool_choice", False),
+        )
+
+
+class Claw:
+    """
+    HyperClaw API Client
+    
+    Provides access to HyperClaw inference endpoints using the OpenAI Python client.
+    
+    Usage:
+        from hypercli import HyperCLI
+        
+        client = HyperCLI(claw_api_key="sk-...")
+        
+        # Get OpenAI client for chat
+        openai = client.claw.openai
+        response = openai.chat.completions.create(
+            model="kimi-k2.5",
+            messages=[{"role": "user", "content": "Hello!"}]
+        )
+        
+        # Or use the convenience wrapper
+        response = client.claw.chat(
+            model="kimi-k2.5",
+            messages=[{"role": "user", "content": "Hello!"}]
+        )
+        
+        # Vision
+        response = client.claw.chat(
+            model="kimi-k2.5",
+            messages=[{
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": "What's in this image?"},
+                    {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
+                ]
+            }]
+        )
+        
+        # Function calling
+        response = client.claw.chat(
+            model="kimi-k2.5",
+            messages=[...],
+            tools=[{"type": "function", "function": {...}}]
+        )
+    """
+    
+    # Default HyperClaw API base URL
+    CLAW_API_BASE = "https://api.hyperclaw.app/v1"
+    DEV_API_BASE = "https://dev-api.hyperclaw.app/v1"
+    
+    def __init__(self, http: HTTPClient, claw_api_key: str = None, dev: bool = False):
+        """
+        Initialize HyperClaw client.
+        
+        Args:
+            http: HTTPClient for making requests (used for non-OpenAI endpoints)
+            claw_api_key: Optional separate API key for HyperClaw
+            dev: Use dev API endpoint
+        """
+        self._http = http
+        self._api_key = claw_api_key or http.api_key
+        self._dev = dev
+        self._base_url = self.DEV_API_BASE if dev else self.CLAW_API_BASE
+        self._openai = None
+    
+    @property
+    def openai(self) -> "OpenAI":
+        """
+        Get OpenAI client configured for HyperClaw.
+        
+        Returns:
+            OpenAI client instance
+            
+        Raises:
+            ImportError: If openai package is not installed
+        """
+        if not OPENAI_AVAILABLE:
+            raise ImportError(
+                "OpenAI package required for chat. Install with: pip install openai"
+            )
+        
+        if self._openai is None:
+            self._openai = OpenAI(
+                api_key=self._api_key,
+                base_url=self._base_url,
+            )
+        return self._openai
+    
+    def chat(
+        self,
+        model: str,
+        messages: List[Dict],
+        temperature: float = None,
+        max_tokens: int = None,
+        tools: List[Dict] = None,
+        tool_choice: Union[str, Dict] = None,
+        stream: bool = False,
+        **kwargs
+    ):
+        """
+        Create a chat completion using the OpenAI client.
+        
+        Args:
+            model: Model ID (e.g., "kimi-k2.5")
+            messages: List of message dicts
+            temperature: Sampling temperature (0-2)
+            max_tokens: Maximum tokens to generate
+            tools: List of tool definitions for function calling
+            tool_choice: Tool choice mode ("auto", "none", or specific tool)
+            stream: Whether to stream the response
+            **kwargs: Additional parameters passed to the API
+            
+        Returns:
+            OpenAI ChatCompletion object
+        """
+        params = {
+            "model": model,
+            "messages": messages,
+            **kwargs
+        }
+        
+        if temperature is not None:
+            params["temperature"] = temperature
+        if max_tokens is not None:
+            params["max_tokens"] = max_tokens
+        if tools:
+            params["tools"] = tools
+        if tool_choice:
+            params["tool_choice"] = tool_choice
+        if stream:
+            params["stream"] = stream
+        
+        return self.openai.chat.completions.create(**params)
+    
+    def models(self) -> List[ClawModel]:
+        """
+        List available models.
+        
+        Returns:
+            List of ClawModel objects
+        """
+        response = self.openai.models.list()
+        return [
+            ClawModel.from_dict({
+                "id": m.id,
+                "name": getattr(m, "name", m.id),
+                "context_length": getattr(m, "context_length", 0),
+                "capabilities": getattr(m, "capabilities", {}),
+            })
+            for m in response.data
+        ]
+    
+    def _api_base_without_v1(self) -> str:
+        """Get API base URL without /v1 suffix."""
+        return self._base_url.replace("/v1", "")
+    
+    def key_status(self) -> ClawKey:
+        """
+        Get current API key status and subscription details.
+        
+        Returns:
+            ClawKey object with subscription info
+        """
+        r = self._http._session.get(
+            f"{self._api_base_without_v1()}/api/keys/status",
+            headers={"Authorization": f"Bearer {self._api_key}"},
+        )
+        r.raise_for_status()
+        return ClawKey.from_dict(r.json())
+    
+    def plans(self) -> List[ClawPlan]:
+        """
+        List available subscription plans.
+        
+        Returns:
+            List of ClawPlan objects
+        """
+        r = self._http._session.get(
+            f"{self._api_base_without_v1()}/api/plans",
+            headers={"Authorization": f"Bearer {self._api_key}"},
+        )
+        r.raise_for_status()
+        data = r.json()
+        return [ClawPlan.from_dict(p) for p in data.get("plans", [])]
+    
+    def discovery_health(self) -> Dict[str, Any]:
+        """
+        Get discovery service health status.
+        
+        Returns:
+            Dict with hosts_total, hosts_healthy, fallbacks_active
+        """
+        r = self._http._session.get(
+            f"{self._api_base_without_v1()}/discovery/health",
+        )
+        r.raise_for_status()
+        return r.json()
+    
+    def discovery_config(self, api_key: str = None) -> Dict[str, Any]:
+        """
+        Get discovery service configuration (requires API key).
+        
+        Args:
+            api_key: Backend API key (not the user's claw key)
+            
+        Returns:
+            Dict with hosts, fallbacks, config
+        """
+        headers = {}
+        if api_key:
+            headers["X-API-KEY"] = api_key
+        
+        r = self._http._session.get(
+            f"{self._api_base_without_v1()}/discovery/config",
+            headers=headers,
+        )
+        r.raise_for_status()
+        return r.json()

{hypercli_sdk-0.7.0 → hypercli_sdk-0.8.0}/hypercli/client.py

@@ -7,6 +7,8 @@ from .user import UserAPI
 from .instances import Instances
 from .renders import Renders
 from .files import Files
+from .claw import Claw
+from .keys import KeysAPI
 
 
 class HyperCLI:
@@ -36,7 +38,7 @@ class HyperCLI:
         user = client.user.get()
     """
 
-    def __init__(self, api_key: str = None, api_url: str = None):
+    def __init__(self, api_key: str = None, api_url: str = None, claw_api_key: str = None, claw_dev: bool = False):
         self._api_key = api_key or get_api_key()
         if not self._api_key:
             raise ValueError(
@@ -54,6 +56,8 @@ class HyperCLI:
         self.instances = Instances(self._http)
         self.renders = Renders(self._http)
         self.files = Files(self._http)
+        self.keys = KeysAPI(self._http)
+        self.claw = Claw(self._http, claw_api_key=claw_api_key, dev=claw_dev)
 
     @property
     def api_url(self) -> str:

{hypercli_sdk-0.7.0 → hypercli_sdk-0.8.0}/hypercli/jobs.py

@@ -133,6 +133,7 @@ class Jobs:
         env: dict[str, str] = None,
         ports: dict[str, int] = None,
         auth: bool = False,
+        registry_auth: dict[str, str] = None,
     ) -> Job:
         """Create a new job.
 
@@ -147,6 +148,7 @@ class Jobs:
             env: Environment variables
             ports: Ports to expose. Use {"lb": port} for HTTPS load balancer
             auth: Enable Bearer token auth on load balancer (use with ports={"lb": port})
+            registry_auth: Private registry credentials {"username": "...", "password": "..."}
         """
         payload = {
             "docker_image": image,
@@ -165,6 +167,8 @@ class Jobs:
             payload["ports"] = ports
         if auth:
             payload["auth"] = auth
+        if registry_auth:
+            payload["registry_auth"] = registry_auth
 
         data = self._http.post("/api/jobs", json=payload)
         return Job.from_dict(data)

hypercli_sdk-0.8.0/hypercli/keys.py

@@ -0,0 +1,62 @@
+"""API Keys management"""
+from dataclasses import dataclass
+from typing import List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .http import HTTPClient
+
+
+@dataclass
+class ApiKey:
+    key_id: str
+    name: str
+    api_key: Optional[str]  # Full key only on create
+    api_key_preview: Optional[str]  # Masked key on list
+    last4: Optional[str]
+    is_active: bool
+    created_at: str
+    last_used_at: Optional[str]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ApiKey":
+        return cls(
+            key_id=data.get("key_id", ""),
+            name=data.get("name", ""),
+            api_key=data.get("api_key"),
+            api_key_preview=data.get("api_key_preview"),
+            last4=data.get("last4"),
+            is_active=data.get("is_active", True),
+            created_at=data.get("created_at", ""),
+            last_used_at=data.get("last_used_at"),
+        )
+
+
+class KeysAPI:
+    """API Keys management"""
+
+    def __init__(self, http: "HTTPClient"):
+        self._http = http
+
+    def create(self, name: str = "default") -> ApiKey:
+        """Create a new API key"""
+        data = self._http.post("/api/keys", json={"name": name})
+        return ApiKey.from_dict(data)
+
+    def list(self) -> List[ApiKey]:
+        """List all API keys (masked)"""
+        data = self._http.get("/api/keys")
+        return [ApiKey.from_dict(k) for k in data]
+
+    def get(self, key_id: str) -> ApiKey:
+        """Get a specific API key (masked)"""
+        data = self._http.get(f"/api/keys/{key_id}")
+        return ApiKey.from_dict(data)
+
+    def disable(self, key_id: str) -> dict:
+        """Deactivate an API key (irreversible)"""
+        return self._http.delete(f"/api/keys/{key_id}")
+
+    def rename(self, key_id: str, name: str) -> ApiKey:
+        """Rename an API key"""
+        data = self._http.patch(f"/api/keys/{key_id}", json={"name": name})
+        return ApiKey.from_dict(data)

{hypercli_sdk-0.7.0 → hypercli_sdk-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypercli-sdk"
-version = "0.7.0"
+version = "0.8.0"
 description = "Python SDK for HyperCLI - GPU orchestration and LLM API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -26,6 +26,9 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+claw = [
+    "openai>=1.0.0",
+]
 comfyui = [
     "comfyui-workflow-templates>=0.7.0",
     "comfyui-workflow-templates-media-image>=0.3.0",
@@ -34,6 +37,7 @@ dev = [
     "pytest>=8.0.0",
     "pytest-asyncio>=0.23.0",
     "ruff>=0.3.0",
+    "openai>=1.0.0",
 ]
 
 [project.urls]

hypercli_sdk-0.8.0/tests/test_claw.py

@@ -0,0 +1,153 @@
+"""
+Tests for HyperClaw SDK client
+"""
+import pytest
+import os
+from unittest.mock import Mock, patch, MagicMock
+from hypercli.claw import Claw, ClawKey, ClawPlan, ClawModel
+
+
+class TestClawDataclasses:
+    """Tests for Claw dataclasses."""
+    
+    def test_claw_key_from_dict(self):
+        data = {
+            "key": "sk-test-123",
+            "plan_id": "5aiu",
+            "expires_at": "2026-03-07T12:00:00Z",
+            "tpm_limit": 250000,
+            "rpm_limit": 5000,
+            "user_id": "user-123"
+        }
+        key = ClawKey.from_dict(data)
+        assert key.key == "sk-test-123"
+        assert key.plan_id == "5aiu"
+        assert key.tpm_limit == 250000
+        assert key.rpm_limit == 5000
+    
+    def test_claw_plan_from_dict(self):
+        data = {
+            "id": "5aiu",
+            "name": "5 Agents",
+            "price_usd": 3.0,
+            "tpm_limit": 250000,
+            "rpm_limit": 5000
+        }
+        plan = ClawPlan.from_dict(data)
+        assert plan.id == "5aiu"
+        assert plan.price_usd == 3.0
+    
+    def test_claw_model_from_dict(self):
+        data = {
+            "id": "kimi-k2.5",
+            "name": "Kimi K2.5",
+            "context_length": 262144,
+            "capabilities": {
+                "supports_vision": True,
+                "supports_function_calling": True,
+                "supports_tool_choice": True
+            }
+        }
+        model = ClawModel.from_dict(data)
+        assert model.id == "kimi-k2.5"
+        assert model.context_length == 262144
+        assert model.supports_vision is True
+        assert model.supports_function_calling is True
+
+
+class TestClawClient:
+    """Tests for Claw client methods."""
+    
+    @pytest.fixture
+    def mock_http(self):
+        http = Mock()
+        http._api_key = "test-key"
+        http._session = Mock()
+        return http
+    
+    def test_discovery_health(self, mock_http):
+        mock_http._session.get.return_value.json.return_value = {
+            "status": "ok",
+            "hosts_total": 1,
+            "hosts_healthy": 0,
+            "fallbacks_active": 1
+        }
+        mock_http._session.get.return_value.raise_for_status = Mock()
+        
+        claw = Claw(mock_http, dev=True)
+        result = claw.discovery_health()
+        
+        assert result["status"] == "ok"
+        assert result["hosts_total"] == 1
+        mock_http._session.get.assert_called_once()
+    
+    def test_openai_client_creation(self, mock_http):
+        """Test that OpenAI client is created with correct config."""
+        claw = Claw(mock_http, claw_api_key="sk-test", dev=True)
+        
+        # Access openai property to trigger creation
+        with patch('hypercli.claw.OpenAI') as mock_openai:
+            mock_openai.return_value = MagicMock()
+            client = claw.openai
+            
+            mock_openai.assert_called_once_with(
+                api_key="sk-test",
+                base_url="https://dev-api.hyperclaw.app/v1",
+            )
+    
+    def test_chat_uses_openai_client(self, mock_http):
+        """Test that chat method uses OpenAI client."""
+        claw = Claw(mock_http, claw_api_key="sk-test", dev=True)
+        
+        with patch('hypercli.claw.OpenAI') as mock_openai:
+            mock_client = MagicMock()
+            mock_openai.return_value = mock_client
+            
+            claw.chat(
+                model="kimi-k2.5",
+                messages=[{"role": "user", "content": "Hello"}],
+                temperature=0.7,
+                max_tokens=100
+            )
+            
+            mock_client.chat.completions.create.assert_called_once_with(
+                model="kimi-k2.5",
+                messages=[{"role": "user", "content": "Hello"}],
+                temperature=0.7,
+                max_tokens=100
+            )
+
+
+class TestClawIntegration:
+    """Integration tests for Claw client (require running service)."""
+    
+    @pytest.fixture
+    def claw_client(self):
+        """Create a Claw client for integration tests."""
+        api_key = os.getenv("HYPERCLAW_API_KEY")
+        if not api_key:
+            pytest.skip("HYPERCLAW_API_KEY not set")
+        
+        # Create minimal mock http for standalone claw
+        http = Mock()
+        http._api_key = api_key
+        import requests
+        http._session = requests.Session()
+        
+        return Claw(http, claw_api_key=api_key, dev=True)
+    
+    @pytest.mark.integration
+    def test_discovery_health_integration(self, claw_client):
+        result = claw_client.discovery_health()
+        assert "status" in result
+        assert result["status"] == "ok"
+    
+    @pytest.mark.integration
+    def test_chat_integration(self, claw_client):
+        """Test actual chat completion (requires running service + credits)."""
+        response = claw_client.chat(
+            model="kimi-k2.5",
+            messages=[{"role": "user", "content": "Say 'hello' and nothing else."}],
+            max_tokens=10
+        )
+        assert response.choices[0].message.content is not None