hivekit 0.3.0__tar.gz → 0.4.0__tar.gz

{hivekit-0.3.0 → hivekit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hivekit
-Version: 0.3.0
+Version: 0.4.0
 Summary: Toolkits for using hive agents, including CLI and SDK.
 License: 
                                          Apache License
@@ -223,6 +223,7 @@ Requires-Dist: keyring>=25.0.0
 Requires-Dist: py-machineid>=0.6.0
 Requires-Dist: cryptography>=42.0.0
 Requires-Dist: ruamel.yaml>=0.18
+Requires-Dist: websocket-client>=1.7.0
 Dynamic: license-file
 
 ```

{hivekit-0.3.0 → hivekit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hivekit"
-version = "0.3.0"
+version = "0.4.0"
 description = "Toolkits for using hive agents, including CLI and SDK."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,6 +25,7 @@ dependencies = [
     "py-machineid>=0.6.0",
     "cryptography>=42.0.0",
     "ruamel.yaml>=0.18",
+    "websocket-client>=1.7.0",
 ]
 
 [dependency-groups]

{hivekit-0.3.0 → hivekit-0.4.0}/src/cli/config.py

@@ -20,7 +20,7 @@ from pydantic import (
 )
 
 from cli.utils.logger import set_log_level
-from cli.utils.time import now_2_hash
+from cli.utils.time import unique_suffix
 
 logger = logging.getLogger("hivekit")
 
@@ -29,11 +29,35 @@ class BaseModel(pydantic.BaseModel):
     model_config = ConfigDict(extra="forbid", coerce_numbers_to_str=True)
 
 
-# Per-sandbox resource caps. cpu is in whole cores; memory is in bytes (128Gi).
-# Values are k8s quantities (e.g. "500m", "2Gi"), normalized via parse_quantity
-# before comparison so every equivalent spelling is bounded uniformly.
-MAX_CPU_CORES = 64
-MAX_MEMORY_BYTES = 128 * 1024**3
+# Kubernetes caps DNS labels and label values at 63 bytes. The operator derives
+# object names/labels by appending suffixes to the experiment name (the longest
+# is "-coordinator"), so reserve that headroom to keep the derived names valid.
+K8S_LABEL_MAX_LENGTH = 63
+RESERVED_NAME_SUFFIX_LENGTH = len("-coordinator")
+MAX_EXPERIMENT_NAME_LENGTH = K8S_LABEL_MAX_LENGTH - RESERVED_NAME_SUFFIX_LENGTH
+# A name ending in '-' gets a random uniqueness suffix appended (see
+# unique_suffix), which eats into the budget the user actually controls (their
+# typed base name).
+AUTO_HASH_LENGTH = 7
+MAX_EXPERIMENT_BASE_NAME_LENGTH = MAX_EXPERIMENT_NAME_LENGTH - AUTO_HASH_LENGTH
+
+# Accelerator (GPU) types the cloud providers know how to schedule. Mirrors the
+# controller's LabelsByAcceleratorType switch. Unknown types are not rejected —
+# a provider may support more than we list here — but they trigger a warning.
+KNOWN_ACCELERATOR_TYPES = frozenset(
+    {
+        "a10",
+        "a100",
+        "a100-40gb",
+        "a100-80gb",
+        "b200",
+        "h100",
+        "h200",
+        "l4",
+        "l40s",
+        "t4",
+    }
+)
 
 
 class ResourceConfig(BaseModel):
@@ -62,8 +86,6 @@ class ResourceConfig(BaseModel):
             raise ValueError(f"cpu is not a valid quantity (e.g. '1', '500m'), got: '{v}'")
         if cores <= 0:
             raise ValueError(f"cpu must be positive, got: '{v}'")
-        if cores > MAX_CPU_CORES:
-            raise ValueError(f"cpu must be at most {MAX_CPU_CORES} cores, got: '{v}'")
         return v
 
     @field_validator("memory")
@@ -75,10 +97,40 @@ class ResourceConfig(BaseModel):
             raise ValueError(f"memory is not a valid quantity (e.g. '2Gi', '512Mi'), got: '{v}'")
         if memory_bytes <= 0:
             raise ValueError(f"memory must be positive, got: '{v}'")
-        if memory_bytes > MAX_MEMORY_BYTES:
-            raise ValueError(f"memory must be at most 128Gi, got: '{v}'")
         return v
 
+    @field_validator("accelerators")
+    @classmethod
+    def validate_accelerators(cls, v):
+        # NOTE: KNOWN_ACCELERATOR_TYPES is a hardcoded mirror of the controller's
+        # switch, so it can drift out of sync. A better approach would be a new
+        # backend endpoint that lists the currently available GPU types, letting
+        # us validate against the live source of truth instead of this static set.
+        if v is None:
+            return v
+        parts = v.split(":")
+        if len(parts) != 2:
+            raise ValueError(
+                f"accelerators must be in '<type>:<count>' format (e.g. 'a100-80gb:8'), got: '{v}'"
+            )
+        gpu_type, count = parts[0].strip(), parts[1].strip()
+        if not gpu_type:
+            raise ValueError(f"accelerators type must not be empty, got: '{v}'")
+        try:
+            n = int(count)
+        except ValueError:
+            raise ValueError(f"accelerators count must be an integer, got: '{count}'")
+        if n <= 0:
+            raise ValueError(f"accelerators count must be positive, got: '{count}'")
+        if gpu_type not in KNOWN_ACCELERATOR_TYPES:
+            logger.warning(
+                "accelerators type '%s' is not among the known GPU types (%s); "
+                "any available GPUs may be used. Please confirm with the Hiverge team.",
+                gpu_type,
+                ", ".join(sorted(KNOWN_ACCELERATOR_TYPES)),
+            )
+        return f"{gpu_type}:{n}"
+
 
 class KeyValueSet(BaseModel):
     name: str
@@ -225,24 +277,14 @@ class RepoConfig(BaseModel):
         return v
 
 
-# Platform caps. One sandbox is provisioned per agent, so num_agents is bounded
-# by the max number of sandboxes. max_runtime_seconds is bounded by the maximum
-# runtime of an experiment (6 hours).
-MAX_SANDBOXES = 32
-MAX_RUNTIME_SECONDS = 6 * 60 * 60
-
-
 class RuntimeConfig(BaseModel):
     num_agents: int = Field(
         default=1,
         description="Number of agents to use in the experiment. Default to 1.",
     )
     max_runtime_seconds: int = Field(
-        default=MAX_RUNTIME_SECONDS,
-        description=(
-            "Maximum runtime for the experiment in seconds. -1 means no limit. "
-            f"Defaults to the platform maximum of {MAX_RUNTIME_SECONDS} (6 hours)."
-        ),
+        default=-1,
+        description="Maximum runtime for the experiment in seconds. -1 means no limit.",
     )
     max_iterations: int = Field(
         default=-1,
@@ -256,30 +298,21 @@ class RuntimeConfig(BaseModel):
     @field_validator("num_agents")
     @classmethod
     def validate_num_agents(cls, v):
-        # One sandbox per agent; the platform provisions at most MAX_SANDBOXES.
+        # One sandbox is provisioned per agent.
         if v < 1:
             raise ValueError(f"num_agents must be at least 1, got {v}.")
-        if v > MAX_SANDBOXES:
-            raise ValueError(
-                f"num_agents must be at most {MAX_SANDBOXES} (one sandbox per agent), got {v}."
-            )
         return v
 
     @field_validator("max_runtime_seconds")
     @classmethod
     def validate_max_runtime_seconds(cls, v):
-        # -1 is the sentinel for "no limit"; any positive value is capped at the
-        # platform's maximum experiment runtime.
+        # -1 is the sentinel for "no limit"
         if v == -1:
             return v
         if v < 1:
             raise ValueError(
                 f"max_runtime_seconds must be -1 (no limit) or a positive integer, got {v}."
             )
-        if v > MAX_RUNTIME_SECONDS:
-            raise ValueError(
-                f"max_runtime_seconds must be at most {MAX_RUNTIME_SECONDS} (6 hours), got {v}."
-            )
         return v
 
 
@@ -295,15 +328,24 @@ class HiveConfig(BaseModel):
     @field_validator("experiment_name")
     @classmethod
     def validate_experiment_name(cls, v):
-        if v.endswith("-"):
-            v = f"{v}{now_2_hash()}"
+        base_name = v
+        auto_hashed = v.endswith("-")
+        if auto_hashed:
+            v = f"{v}{unique_suffix()}"
         if not re.fullmatch(r"[a-z0-9]([a-z0-9-]*[a-z0-9])?", v):
             raise ValueError(
-                f"Experiment name must be a valid DNS label (RFC 1123): [a-z0-9] separated by '-', got: '{v}'"
+                f"Experiment name must be a valid DNS label (RFC 1123): [a-z0-9] separated by '-', got: '{base_name}'"
             )
-        if len(v) > 63:
+        if len(v) > MAX_EXPERIMENT_NAME_LENGTH:
+            if auto_hashed:
+                raise ValueError(
+                    f"Experiment name must be no more than {MAX_EXPERIMENT_BASE_NAME_LENGTH} "
+                    f"characters when it ends in '-', got {len(base_name)}: '{base_name}'. "
+                    f"Shorten the name or drop the trailing '-'."
+                )
             raise ValueError(
-                f"Experiment name must be no more than 63 characters, got {len(v)}: '{v}'"
+                f"Experiment name must be no more than {MAX_EXPERIMENT_NAME_LENGTH} "
+                f"characters, got {len(v)}: '{v}'. Shorten the name."
             )
         return v
 

{hivekit-0.3.0 → hivekit-0.4.0}/src/cli/http_client.py

@@ -49,6 +49,14 @@ class StreamNotReadyError(Exception):
     """Raised when the log source is not yet available for streaming."""
 
 
+class ShellNotFoundError(Exception):
+    """Raised when a shell no longer exists server-side (HTTP 404).
+
+    Distinct from a transient failure: the shell's CR is gone (deleted, reaped,
+    or never existed), so the caller must give up rather than retry.
+    """
+
+
 class HttpClient:
     """
     HTTP client for communicating with the Hive backend server.
@@ -89,6 +97,67 @@ class HttpClient:
         response = self._send("post", "/experiments", "create experiment", json=experiment_data)
         return response.json()
 
+    def create_shell(self, shell_data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Create a new interactive shell.
+
+        Args:
+            shell_data: Body of the form
+                {"sandbox": <SandboxSpec>, "ttlSeconds": <int, optional>}.
+
+        Returns:
+            Server payload {"shellId": <str>, "name": <k8s Shell CR name>}.
+        """
+        response = self._send("post", "/shells", "create shell", json=shell_data)
+        return response.json()
+
+    def get_shell(self, shell_id: str) -> Dict[str, Any]:
+        """
+        Get a shell's readiness status.
+
+        Returns:
+            Server payload {"shellId", "phase", "podName", "ready": bool}.
+
+        Raises:
+            ShellNotFoundError: the shell is gone (HTTP 404) -- terminal, do not
+                retry.
+            Exception: any other failure (5xx, connection error) -- an "unknown"
+                status the caller may retry within a bounded window.
+        """
+        url = f"{self.base_url}/shells/{shell_id}"
+        response = self._request(method="get", url=url, headers=self._get_headers())
+        # 404 is the terminal "gone" signal, distinct from a retryable failure.
+        if response.status_code == HTTPStatus.NOT_FOUND:
+            raise ShellNotFoundError(shell_id)
+        # Any other non-2xx is "unknown": reuse _send()'s formatting so the detail
+        # comes from the server's JSON `error` field, not the raw body.
+        try:
+            response.raise_for_status()
+        except requests.exceptions.HTTPError as e:
+            raise Exception(f"Failed to get shell: {_http_error_detail(e)}") from e
+        return response.json()
+
+    def bearer_token(self) -> str:
+        """Return a currently-valid bearer access token for out-of-band use.
+
+        The WebSocket handshake attaches the token by hand and bypasses both the
+        session's automatic ``Authorization`` injection and the 401 re-auth
+        retry, so the token is refreshed here first (if expired/near expiry) to
+        avoid handing a stale credential to the ALB/Tyk edge.
+        """
+        token = getattr(self._session, "token", None)
+        if not token:
+            raise AuthenticationError(
+                "No access token available. Please run 'hive login' to authenticate."
+            )
+        try:
+            self._session.ensure_active_token(token)
+        except OAuthError as e:
+            raise AuthenticationError(
+                "Your credentials have expired. Please run 'hive login' to re-authenticate."
+            ) from e
+        return self._session.token["access_token"]
+
     def get_push_credentials(self, reference: str) -> Dict[str, Any]:
         """
         Request short-lived registry credentials for pushing an image.