hivekit 0.2.0__tar.gz → 0.3.1__tar.gz

hivekit-0.3.1/PKG-INFO

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: hivekit
+Version: 0.3.1
+Summary: Toolkits for using hive agents, including CLI and SDK.
+License: 
+                                         Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+              any Contribution intentionally submitted for inclusion in the Work
+              by You to the Licensor shall be under the terms and conditions of
+              this License, without any additional terms or conditions.
+              Notwithstanding the above, nothing herein shall supersede or modify
+              the terms of any separate license agreement you may have executed
+              with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+              names, trademarks, service marks, or product names of the Licensor,
+              except as required for reasonable and customary use in describing the
+              origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+              agreed to in writing, Licensor provides the Work (and each
+              Contributor provides its Contributions) on an "AS IS" BASIS,
+              WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+              implied, including, without limitation, any warranties or conditions
+              of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+              PARTICULAR PURPOSE. You are solely responsible for determining the
+              appropriateness of using or redistributing the Work and assume any
+              risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+              whether in tort (including negligence), contract, or otherwise,
+              unless required by applicable law (such as deliberate and grossly
+              negligent acts) or agreed to in writing, shall any Contributor be
+              liable to You for damages, including any direct, indirect, special,
+              incidental, or consequential damages of any character arising as a
+              result of this License or out of the use or inability to use the
+              Work (including but not limited to damages for loss of goodwill,
+              work stoppage, computer failure or malfunction, or any and all
+              other commercial damages or losses), even if such Contributor
+              has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+              the Work or Derivative Works thereof, You may choose to offer,
+              and charge a fee for, acceptance of support, warranty, indemnity,
+              or other liability obligations and/or rights consistent with this
+              License. However, in accepting such obligations, You may act only
+              on Your own behalf and on Your sole responsibility, not on behalf
+              of any other Contributor, and only if You agree to indemnify,
+              defend, and hold each Contributor harmless for any liability
+              incurred by, or claims asserted against, such Contributor by reason
+              of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           APPENDIX: How to apply the Apache License to your work.
+        
+              To apply the Apache License to your work, attach the following
+              boilerplate notice, with the fields enclosed by brackets "[]"
+              replaced with your own identifying information. (Don't include
+              the brackets!)  The text should be enclosed in the appropriate
+              comment syntax for the file format. We also recommend that a
+              file or class name and description of purpose be included on the
+              same "printed page" as the copyright notice for easier
+              identification within third-party archives.
+        
+           Copyright [yyyy] [name of copyright owner]
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+        
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=5.1
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: pydantic>=1.8.2
+Requires-Dist: gitpython>=3.1.24
+Requires-Dist: rich>=12.5.1
+Requires-Dist: kubernetes>=33.1.0
+Requires-Dist: portforward>=0.3.0
+Requires-Dist: argcomplete>=3.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: authlib>=1.2.0
+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
+Dynamic: license-file
+
+```
+       ███          █████   █████  ███                       █████   ████  ███   █████
+      ░░░███       ░░███   ░░███  ░░░                       ░░███   ███░  ░░░   ░░███
+        ░░░███      ░███    ░███  ████  █████ █████  ██████  ░███  ███    ████  ███████
+          ░░░███    ░███████████ ░░███ ░░███ ░░███  ███░░███ ░███████    ░░███ ░░░███░
+           ███░     ░███░░░░░███  ░███  ░███  ░███ ░███████  ░███░░███    ░███   ░███
+         ███░       ░███    ░███  ░███  ░░███ ███  ░███░░░   ░███ ░░███   ░███   ░███ ███
+       ███░         █████   █████ █████  ░░█████   ░░██████  █████ ░░████ █████  ░░█████
+      ░░░          ░░░░░   ░░░░░ ░░░░░    ░░░░░     ░░░░░░  ░░░░░   ░░░░ ░░░░░    ░░░░░
+```
+
+<div align="center">
+
+**> HiveKit**
+
+Command-line interface for managing Hive AI agent experiments
+
+[![PyPI version](https://badge.fury.io/py/hivekit.svg)](https://badge.fury.io/py/hivekit)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
+
+</div>
+
+## Installation
+
+```bash
+pip install hivekit
+```
+
+**Requirements:** Python 3.12+
+
+
+## Support
+
+- 📖 [Documentation](https://docs.hiverge.ai)
+
+## License
+
+Apache 2.0 License - see [LICENSE](LICENSE)

{hivekit-0.2.0 → hivekit-0.3.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hivekit"
-version = "0.2.0"
+version = "0.3.1"
 description = "Toolkits for using hive agents, including CLI and SDK."
 readme = "README.md"
 requires-python = ">=3.12"
-license = "Apache-2.0"
+license = { file = "LICENSE" }
 
 dependencies = [
     "PyYAML>=5.1",
@@ -34,7 +34,7 @@ dev = [
 ]
 
 test = [
-  "pytest>=6.2.4",
+  "pytest>=9.1.1",
   "flask==3.1.3",
   "requests",
   "psutil",

{hivekit-0.2.0 → hivekit-0.3.1}/src/cli/config.py

@@ -9,6 +9,7 @@ from typing import Optional
 
 import pydantic
 import yaml
+from kubernetes.utils import parse_quantity
 from pydantic import (
     ConfigDict,
     Field,
@@ -28,6 +29,64 @@ class BaseModel(pydantic.BaseModel):
     model_config = ConfigDict(extra="forbid", coerce_numbers_to_str=True)
 
 
+# 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 hash appended (see now_2_hash),
+# 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",
+    }
+)
+
+# 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 hash appended (see now_2_hash),
+# 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):
     cpu: str = Field(
         default="1",
@@ -45,6 +104,60 @@ class ResourceConfig(BaseModel):
     )
     extended_resources: Optional[dict] = None
 
+    @field_validator("cpu")
+    @classmethod
+    def validate_cpu(cls, v):
+        try:
+            cores = parse_quantity(v)
+        except ValueError:
+            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}'")
+        return v
+
+    @field_validator("memory")
+    @classmethod
+    def validate_memory(cls, v):
+        try:
+            memory_bytes = parse_quantity(v)
+        except ValueError:
+            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}'")
+        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
@@ -114,6 +227,10 @@ class PromptConfig(BaseModel):
         default=None,
         description="A list of ideas which will be randomly sampled to inject into the Hive.",
     )
+    arxiv_ids: Optional[list[str]] = Field(
+        default=None,
+        description="A list of arXiv IDs to provide as reference material to the Hive.",
+    )
 
 
 class RepoConfig(BaseModel):
@@ -205,6 +322,26 @@ class RuntimeConfig(BaseModel):
         description="Whether the evaluator is stochastic and the Hive should account for this. Default to False.",
     )
 
+    @field_validator("num_agents")
+    @classmethod
+    def validate_num_agents(cls, v):
+        # One sandbox is provisioned per agent.
+        if v < 1:
+            raise ValueError(f"num_agents must be at least 1, got {v}.")
+        return v
+
+    @field_validator("max_runtime_seconds")
+    @classmethod
+    def validate_max_runtime_seconds(cls, v):
+        # -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}."
+            )
+        return v
+
 
 class HiveConfig(BaseModel):
     apiversion: str = Field(
@@ -218,15 +355,24 @@ class HiveConfig(BaseModel):
     @field_validator("experiment_name")
     @classmethod
     def validate_experiment_name(cls, v):
-        if v.endswith("-"):
+        base_name = v
+        auto_hashed = v.endswith("-")
+        if auto_hashed:
             v = f"{v}{now_2_hash()}"
         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
 
@@ -291,7 +437,7 @@ def _lookup_description(schema: dict, loc: tuple) -> str | None:
     return None
 
 
-def validate_repo_files_exist(base_dir: str, repo: RepoConfig) -> None:
+def validate_repo_files_exist(base_dir: str, repo: RepoConfig, allow_missing: bool = False) -> None:
     """Validate that the files referenced by the repo config exist in base_dir.
 
     Called after the source has been materialized (cloned or local dir), so it
@@ -299,6 +445,10 @@ def validate_repo_files_exist(base_dir: str, repo: RepoConfig) -> None:
     `file.py:1-10`) on target_code/additional_context entries are stripped
     before checking the path. evaluation_script has no range syntax, so its
     path is used verbatim (a ':' there is part of the filename).
+
+    Missing files are normally a hard error. With allow_missing=True the check
+    is downgraded to a warning: the referenced files may legitimately be absent
+    from the materialized source and supplied by the base image instead.
     """
     # (field name, referenced path) pairs. Line ranges are stripped from
     # target_code/additional_context; evaluation_script is used verbatim.
@@ -319,6 +469,12 @@ def validate_repo_files_exist(base_dir: str, repo: RepoConfig) -> None:
             )
             blocks.append(f"repo.{field}:\n{lines}")
         details = "\n\n".join(blocks)
+        if allow_missing:
+            logger.warning(
+                "The following files referenced in the config do not exist in the repository:\n%s",
+                details,
+            )
+            return
         raise ValueError(
             f"The following files referenced in the config do not exist in the "
             f"repository:\n{details}"

{hivekit-0.2.0 → hivekit-0.3.1}/src/cli/experiment.py

@@ -101,6 +101,8 @@ def build_experiment_crd(config: HiveConfig) -> Dict[str, Any]:
             experiment["spec"]["prompt"]["context"] = config.prompt.context
         if config.prompt.ideas:
             experiment["spec"]["prompt"]["ideas"] = config.prompt.ideas
+        if config.prompt.arxiv_ids:
+            experiment["spec"]["prompt"]["arxivIds"] = config.prompt.arxiv_ids
         if config.prompt.enable_evolution:
             experiment["spec"]["prompt"]["enableEvolution"] = config.prompt.enable_evolution
 

{hivekit-0.2.0 → hivekit-0.3.1}/src/cli/http_client.py

@@ -300,6 +300,25 @@ class HttpClient:
         response = self._send("get", "/experiments", "list experiments")
         return response.json()
 
+    def get_repo_download_url(self, name: str, content_uid: str) -> Dict[str, Any]:
+        """
+        Get a presigned URL to download the repository assembled at a content snapshot.
+
+        Args:
+            name: Experiment name.
+            content_uid: Content snapshot identifier (a point on the evolution chart).
+
+        Returns:
+            Object with ``url`` (presigned S3 URL) and ``expiresIn`` (seconds).
+        """
+        response = self._send(
+            "get",
+            f"/experiments/{name}/repo-download",
+            "get repo download URL",
+            params={"contentUid": content_uid},
+        )
+        return response.json()
+
     def list_coordinators(self) -> Dict[str, Any]:
         """
         List coordinator configurations.