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.
