colabhive 0.5.0__tar.gz

colabhive-0.5.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 ColabHive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

colabhive-0.5.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include colabhive *.py
+recursive-exclude tests *
+recursive-exclude examples *
+global-exclude __pycache__
+global-exclude *.py[cod]
+

colabhive-0.5.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.1
+Name: colabhive
+Version: 0.5.0
+Summary: Official Python SDK for ColabHive Builder APIs
+Home-page: https://github.com/colabhive/colabhive-sdk-python
+Author: ColabHive Team
+Author-email: ColabHive Team <support@colabhive.com>
+License: MIT
+Project-URL: Homepage, https://colabhive.com
+Project-URL: Documentation, https://docs.colabhive.com
+Project-URL: Repository, https://github.com/colabhive/colabhive-sdk-python
+Project-URL: Issues, https://github.com/colabhive/colabhive-sdk-python/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# ColabHive Python SDK
+
+Official Python client for ColabHive Builder APIs.
+
+Train machine learning models on distributed GPUs without managing infrastructure.
+
+## Installation
+
+```bash
+pip install colabhive
+```
+
+## Quick Start
+
+```python
+from colabhive import ColabHive
+
+# Initialize client
+client = ColabHive(
+    api_key="your_api_key_here",
+    account_id="your_account_id_here"
+)
+
+# Upload dataset
+dataset = client.datasets.upload(
+    name="my_training_data",
+    file="./data.csv"
+)
+print(f"Dataset uploaded: {dataset.id}")
+
+# Train model
+job = client.training.create(
+    model="xgboost-regression",
+    dataset_id=dataset.id,
+    job_name="My First Model"
+)
+print(f"Training started: {job.id}")
+
+# Wait for completion
+job.wait()
+
+if job.status == "completed":
+    print("Training complete!")
+    print(f"Metrics: {job.metrics}")
+else:
+    print(f"Training failed: {job.error_message}")
+```
+
+## Authentication
+
+Get your API key and account ID from [console.colabhive.com](https://console.colabhive.com/api-keys).
+
+```python
+client = ColabHive(
+    api_key="colabhive_sk_...",
+    account_id="0914e1c6-..."
+)
+```
+
+## Features
+
+### Datasets
+
+```python
+# Upload
+dataset = client.datasets.upload(name="data", file="./train.csv")
+
+# List
+datasets = client.datasets.list(limit=10)
+
+# Get
+dataset = client.datasets.get("dataset-id")
+
+# Delete
+client.datasets.delete("dataset-id")
+```
+
+### Training
+
+```python
+# Create training job
+job = client.training.create(
+    model="xgboost-regression",
+    dataset_id="dataset-id",
+    job_name="Experiment 1",
+    hyperparameters={
+        "n_estimators": 100,
+        "max_depth": 6
+    }
+)
+
+# List jobs
+jobs = client.training.list(limit=10, status="running")
+
+# Get job
+job = client.training.get("run-id")
+
+# Wait for completion
+job.wait(poll_interval=5, timeout=3600, verbose=True)
+
+# Get metrics
+metrics = job.metrics
+print(metrics)
+
+# Delete job
+client.training.delete("run-id")
+```
+
+### Models
+
+```python
+# List models
+models = client.models.list()
+
+# Get model
+model = client.models.get("model-id")
+
+# Download model
+path = client.models.download("model-id", "./my_model.pkl")
+
+# Delete model
+client.models.delete("model-id")
+```
+
+### Model Configurations
+
+```python
+# List available model configs
+configs = client.training.model_configs(category="ml_classical")
+
+for config in configs:
+    print(config.model_name, config.display_name)
+    print(config.default_hyperparameters)
+```
+
+## Advanced Usage
+
+### Context Manager
+
+```python
+with ColabHive(api_key="...", account_id="...") as client:
+    dataset = client.datasets.upload("data", "./train.csv")
+    job = client.training.create("xgboost-regression", dataset.id)
+    job.wait()
+```
+
+### Custom Base URL
+
+```python
+# For production
+client = ColabHive(
+    api_key="...",
+    account_id="...",
+    base_url="https://api.colabhive.com"
+)
+
+# For local development
+client = ColabHive(
+    api_key="...",
+    account_id="...",
+    base_url="http://localhost:8014"
+)
+```
+
+### Error Handling
+
+```python
+from colabhive import ColabHive, ValidationError, NotFoundError, APIError
+
+client = ColabHive(api_key="...", account_id="...")
+
+try:
+    dataset = client.datasets.upload("data", "./nonexistent.csv")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+except APIError as e:
+    print(f"API error: {e.message} (status: {e.status_code})")
+```
+
+## Requirements
+
+- Python 3.8+
+- httpx >= 0.24.0
+- pydantic >= 2.0.0
+
+## Documentation
+
+- [Full Documentation](https://docs.colabhive.com)
+- [API Reference](https://docs.colabhive.com/api)
+- [Examples](https://docs.colabhive.com/examples)
+
+## Support
+
+- **Discord**: [discord.gg/colabhive](https://discord.gg/colabhive)
+- **Email**: support@colabhive.com
+- **Issues**: [GitHub Issues](https://github.com/colabhive/colabhive-sdk-python/issues)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

colabhive-0.5.0/README.md

@@ -0,0 +1,202 @@
+# ColabHive Python SDK
+
+Official Python client for ColabHive Builder APIs.
+
+Train machine learning models on distributed GPUs without managing infrastructure.
+
+## Installation
+
+```bash
+pip install colabhive
+```
+
+## Quick Start
+
+```python
+from colabhive import ColabHive
+
+# Initialize client
+client = ColabHive(
+    api_key="your_api_key_here",
+    account_id="your_account_id_here"
+)
+
+# Upload dataset
+dataset = client.datasets.upload(
+    name="my_training_data",
+    file="./data.csv"
+)
+print(f"Dataset uploaded: {dataset.id}")
+
+# Train model
+job = client.training.create(
+    model="xgboost-regression",
+    dataset_id=dataset.id,
+    job_name="My First Model"
+)
+print(f"Training started: {job.id}")
+
+# Wait for completion
+job.wait()
+
+if job.status == "completed":
+    print("Training complete!")
+    print(f"Metrics: {job.metrics}")
+else:
+    print(f"Training failed: {job.error_message}")
+```
+
+## Authentication
+
+Get your API key and account ID from [console.colabhive.com](https://console.colabhive.com/api-keys).
+
+```python
+client = ColabHive(
+    api_key="colabhive_sk_...",
+    account_id="0914e1c6-..."
+)
+```
+
+## Features
+
+### Datasets
+
+```python
+# Upload
+dataset = client.datasets.upload(name="data", file="./train.csv")
+
+# List
+datasets = client.datasets.list(limit=10)
+
+# Get
+dataset = client.datasets.get("dataset-id")
+
+# Delete
+client.datasets.delete("dataset-id")
+```
+
+### Training
+
+```python
+# Create training job
+job = client.training.create(
+    model="xgboost-regression",
+    dataset_id="dataset-id",
+    job_name="Experiment 1",
+    hyperparameters={
+        "n_estimators": 100,
+        "max_depth": 6
+    }
+)
+
+# List jobs
+jobs = client.training.list(limit=10, status="running")
+
+# Get job
+job = client.training.get("run-id")
+
+# Wait for completion
+job.wait(poll_interval=5, timeout=3600, verbose=True)
+
+# Get metrics
+metrics = job.metrics
+print(metrics)
+
+# Delete job
+client.training.delete("run-id")
+```
+
+### Models
+
+```python
+# List models
+models = client.models.list()
+
+# Get model
+model = client.models.get("model-id")
+
+# Download model
+path = client.models.download("model-id", "./my_model.pkl")
+
+# Delete model
+client.models.delete("model-id")
+```
+
+### Model Configurations
+
+```python
+# List available model configs
+configs = client.training.model_configs(category="ml_classical")
+
+for config in configs:
+    print(config.model_name, config.display_name)
+    print(config.default_hyperparameters)
+```
+
+## Advanced Usage
+
+### Context Manager
+
+```python
+with ColabHive(api_key="...", account_id="...") as client:
+    dataset = client.datasets.upload("data", "./train.csv")
+    job = client.training.create("xgboost-regression", dataset.id)
+    job.wait()
+```
+
+### Custom Base URL
+
+```python
+# For production
+client = ColabHive(
+    api_key="...",
+    account_id="...",
+    base_url="https://api.colabhive.com"
+)
+
+# For local development
+client = ColabHive(
+    api_key="...",
+    account_id="...",
+    base_url="http://localhost:8014"
+)
+```
+
+### Error Handling
+
+```python
+from colabhive import ColabHive, ValidationError, NotFoundError, APIError
+
+client = ColabHive(api_key="...", account_id="...")
+
+try:
+    dataset = client.datasets.upload("data", "./nonexistent.csv")
+except ValidationError as e:
+    print(f"Invalid request: {e.message}")
+except NotFoundError as e:
+    print(f"Not found: {e.message}")
+except APIError as e:
+    print(f"API error: {e.message} (status: {e.status_code})")
+```
+
+## Requirements
+
+- Python 3.8+
+- httpx >= 0.24.0
+- pydantic >= 2.0.0
+
+## Documentation
+
+- [Full Documentation](https://docs.colabhive.com)
+- [API Reference](https://docs.colabhive.com/api)
+- [Examples](https://docs.colabhive.com/examples)
+
+## Support
+
+- **Discord**: [discord.gg/colabhive](https://discord.gg/colabhive)
+- **Email**: support@colabhive.com
+- **Issues**: [GitHub Issues](https://github.com/colabhive/colabhive-sdk-python/issues)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

colabhive-0.5.0/colabhive/__init__.py

@@ -0,0 +1,34 @@
+"""ColabHive Python SDK
+
+Official Python client for ColabHive Builder APIs.
+"""
+
+__version__ = "0.5.0"
+
+from .client import ColabHive
+from .types import Dataset, TrainingJob, Model, Endpoint, Artifact, ArtifactRef
+from .exceptions import (
+    ColabHiveError,
+    AuthenticationError,
+    NotFoundError,
+    ValidationError,
+    RateLimitError,
+    APIError,
+)
+
+__all__ = [
+    "ColabHive",
+    "Dataset",
+    "TrainingJob",
+    "Model",
+    "Endpoint",
+    "Artifact",
+    "ArtifactRef",
+    "ColabHiveError",
+    "AuthenticationError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "APIError",
+]
+

colabhive-0.5.0/colabhive/actions.py

@@ -0,0 +1,192 @@
+"""Actions API — the unified, plugin-ready invocation surface.
+
+The Actions surface is computed by the Builder Gateway from existing
+``inference_endpoints`` + ``model_configs`` + ``training_jobs`` (no new tables):
+every visible base model, tool, specialist and user-trained endpoint is exposed
+as a single "action" addressable by a stable ``slug`` (its endpoint name). This
+lets you discover and invoke *any* capability through one uniform contract
+instead of special-casing per model.
+
+Access via: ``client.actions``
+
+Routes wrapped (all under ``/api/builder/v1``):
+
+- ``GET  /actions``               -> :meth:`ActionsAPI.list`
+- ``GET  /actions/{slug}``        -> :meth:`ActionsAPI.get`
+- ``POST /actions/{slug}:invoke`` -> :meth:`ActionsAPI.invoke`
+- ``GET  /invocations/{id}``      -> :meth:`ActionsAPI.poll`
+"""
+
+from typing import Any, Dict, List, Optional
+
+from .exceptions import raise_for_status
+
+
+class ActionsAPI:
+    """API for the unified action surface (discover + invoke by slug)."""
+
+    def __init__(self, client):
+        self.client = client
+
+    def list(
+        self,
+        kind: Optional[str] = None,
+        task_type: Optional[str] = None,
+        search: Optional[str] = None,
+        base_only: Optional[bool] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """
+        Discover all invocable actions visible to your account.
+
+        Returns base models (LLMs, specialists, tools), generative models and
+        your own trained endpoints, each enriched with an auto-generated
+        ``input_schema`` and, for trained models, training lineage.
+
+        Args:
+            kind: Filter by kind (llm, specialist, tool, trained_model, generative, model)
+            task_type: Filter by task type (chat, classification, regression,
+                       forecasting, embeddings, ...)
+            search: Free-text search over slug, display name and description
+            base_only: True = only base models, False = only trained models,
+                       None = both (default)
+            limit: Maximum number of actions to return (1-200, default: 50)
+            offset: Pagination offset (default: 0)
+
+        Returns:
+            List of action dicts. Each has ``slug``, ``display_name``,
+            ``description``, ``kind``, ``task_type``, ``input_schema``,
+            ``output_schema``, ``invoke_url`` and (for trained models)
+            ``training`` lineage.
+
+        Example:
+            >>> # Find every chat-capable action I can invoke
+            >>> actions = client.actions.list(kind="llm", task_type="chat")
+            >>> for a in actions:
+            ...     print(a["slug"], "-", a["display_name"])
+        """
+        params: Dict[str, Any] = {"limit": limit, "offset": offset}
+        if kind is not None:
+            params["kind"] = kind
+        if task_type is not None:
+            params["task_type"] = task_type
+        if search is not None:
+            params["search"] = search
+        if base_only is not None:
+            params["base_only"] = base_only
+
+        response = self.client._http.get(
+            f"{self.client.base_url}/api/builder/v1/actions",
+            params=params,
+        )
+        raise_for_status(response)
+        return response.json().get("actions", [])
+
+    def get(self, slug: str) -> Dict[str, Any]:
+        """
+        Get a single action's detail by slug.
+
+        Args:
+            slug: The action slug (the endpoint name, e.g. "mistral-7b-instruct-public")
+
+        Returns:
+            Action dict (same shape as an element of :meth:`list`).
+
+        Example:
+            >>> action = client.actions.get("mistral-7b-instruct-public")
+            >>> print(action["input_schema"])
+        """
+        response = self.client._http.get(
+            f"{self.client.base_url}/api/builder/v1/actions/{slug}"
+        )
+        raise_for_status(response)
+        return response.json()
+
+    def invoke(
+        self,
+        slug: str,
+        input_data: Dict[str, Any],
+        sync: bool = True,
+        sync_timeout: float = 30.0,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        """
+        Invoke an action by slug (the unified invocation entry point).
+
+        Resolves the slug to its endpoint and dispatches to the orchestrator —
+        the invocation body is the same contract as ``endpoints.infer``.
+
+        Args:
+            slug: The action slug to invoke.
+            input_data: Input payload for the action (goes to the ``input`` field).
+            sync: If True (default) the server waits for the result; if False it
+                  returns immediately with an ``invocation_id`` to poll.
+            sync_timeout: Max seconds the server blocks in sync mode (1-300, default: 30).
+            timeout: Optional HTTP client timeout override. Defaults to
+                     ``sync_timeout + 5`` in sync mode, else 30s.
+
+        Returns:
+            Invocation dict with ``invocation_id``, ``action_slug``, ``status``
+            and ``model_state``. In a completed sync call it also carries
+            ``result``, ``error`` and ``metrics``; otherwise it carries a
+            ``poll_url`` to use with :meth:`poll`.
+
+        Example:
+            >>> # Synchronous invocation
+            >>> resp = client.actions.invoke(
+            ...     "mistral-7b-instruct-public",
+            ...     {"messages": [{"role": "user", "content": "Say PASS"}]},
+            ... )
+            >>> print(resp["result"])
+            >>>
+            >>> # Fire-and-poll
+            >>> resp = client.actions.invoke("sdxl-public", {"prompt": "a fox"}, sync=False)
+            >>> final = client.actions.poll(resp["invocation_id"])
+        """
+        request_kwargs: Dict[str, Any] = {
+            "json": {
+                "input": input_data,
+                "sync": sync,
+                "sync_timeout_s": sync_timeout,
+            },
+            # Server blocks for sync, so set HTTP timeout = sync_timeout + buffer
+            "timeout": timeout or (sync_timeout + 5 if sync else 30),
+        }
+
+        response = self.client._http.post(
+            f"{self.client.base_url}/api/builder/v1/actions/{slug}:invoke",
+            **request_kwargs,
+        )
+        raise_for_status(response)
+        return response.json()
+
+    def poll(self, invocation_id: str) -> Dict[str, Any]:
+        """
+        Poll the status/result of an invocation.
+
+        Use this with the ``invocation_id`` returned by an async
+        :meth:`invoke` (``sync=False``).
+
+        Args:
+            invocation_id: The invocation id to poll.
+
+        Returns:
+            Invocation status dict with ``invocation_id``, ``status``,
+            ``status_detail``, ``result``, ``error``, ``metrics`` and timestamps.
+
+        Example:
+            >>> resp = client.actions.invoke("sdxl-public", {"prompt": "a fox"}, sync=False)
+            >>> import time
+            >>> while True:
+            ...     inv = client.actions.poll(resp["invocation_id"])
+            ...     if inv["status"] in ("completed", "succeeded", "failed"):
+            ...         break
+            ...     time.sleep(1)
+            >>> print(inv["result"])
+        """
+        response = self.client._http.get(
+            f"{self.client.base_url}/api/builder/v1/invocations/{invocation_id}"
+        )
+        raise_for_status(response)
+        return response.json()