Metadata-Version: 2.4
Name: visionhub-client
Version: 0.1.0
Summary: Client SDK for connecting Colab or local YOLO training runs to VisionHub AI.
Author: VisionHub AI
License-Expression: MIT
Keywords: mlops,computer-vision,colab,yolo,training
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: PyYAML>=6.0.0
Provides-Extra: yolo
Requires-Dist: ultralytics>=8.0.0; extra == "yolo"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: responses>=0.24.0; extra == "dev"
Dynamic: license-file

# visionhub-client

Python SDK de ket noi Google Colab hoac may local ve VisionHub AI trong luc train model computer vision. Thu vien nay duoc viet moi theo dac ta chuc nang, khong copy source code, endpoint rieng, logo hay tai san cua Ultralytics HUB/hub-sdk.

## Install

```bash
pip install -U visionhub-client
```

Neu train YOLO bang Ultralytics:

```bash
pip install -U "visionhub-client[yolo]"
```

Trong repo nay co the cai local:

```bash
pip install -e ./visionhub-client
```

## Google Colab quickstart

```python
!pip install -U visionhub-client ultralytics

from visionhub_client import VisionHubClient
from ultralytics import YOLO

client = VisionHubClient(
    api_url="https://hub.example.com",
    job_id="job_123",
    token="vhc_xxxxx",
)

client.connect()
client.start_heartbeat(interval=30)

dataset_yaml = client.download_dataset()
config = client.get_training_config()
checkpoint = client.download_latest_checkpoint()

model = YOLO(checkpoint or config["base_model"])
client.attach_ultralytics_callbacks(model)

model.train(
    data=dataset_yaml,
    epochs=config["epochs"],
    imgsz=config["imgsz"],
    batch=config["batch"],
    optimizer=config.get("optimizer", "auto"),
    lr0=config.get("lr0", 0.01),
    patience=config.get("patience", 50),
    resume=bool(checkpoint),
)

client.upload_final_model()
client.finish()
```

## Env-based usage

```bash
export VISIONHUB_API_URL="https://hub.example.com"
export VISIONHUB_JOB_ID="job_123"
export VISIONHUB_TOKEN="vhc_xxxxx"
export VISIONHUB_RUNTIME_ID="runtime_456"
```

```python
from visionhub_client import VisionHubClient

client = VisionHubClient.from_env()
client.connect()
client.prepare()
client.train_yolo()
client.finish()
```

## Resume from a specific checkpoint

```python
from visionhub_client import VisionHubClient
from ultralytics import YOLO

client = VisionHubClient.from_env()
client.connect()

checkpoint_path = client.download_checkpoint("ckpt_abc123")
config = client.get_training_config()

model = YOLO(checkpoint_path)
client.attach_ultralytics_callbacks(model)

model.train(
    data=client.download_dataset(),
    epochs=config["epochs"],
    imgsz=config["imgsz"],
    batch=config["batch"],
    resume=True,
)

client.finish()
```

## Mock training

Dung de test Hub UI khi chua co Colab/training that:

```python
from visionhub_client import VisionHubClient

client = VisionHubClient(
    api_url="http://localhost:4010",
    job_id="job-colab-traffic",
    token="dev-token",
)

client.simulate_training(
    epochs=20,
    disconnect_at_epoch=8,
    checkpoint_every_epoch=True,
)
```

## CLI

```bash
visionhub connect --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub heartbeat --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub download-dataset --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub download-checkpoint --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub upload-checkpoint --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token --file last.pt --epoch 10
visionhub train-yolo --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token --simulate --epochs 5
```

## API endpoints used

- `POST /api/colab/connect`
- `POST /api/colab/heartbeat`
- `POST /api/colab/disconnect`
- `POST /api/colab/finish`
- `POST /api/colab/fail`
- `POST /api/colab/status`
- `GET /api/colab/jobs/:jobId/config`
- `GET /api/colab/jobs/:jobId/dataset`
- `GET /api/colab/jobs/:jobId/base-model`
- `GET /api/colab/jobs/:jobId/checkpoints/latest`
- `GET /api/colab/jobs/:jobId/checkpoints/:checkpointId/download`
- `POST /api/colab/jobs/:jobId/logs`
- `POST /api/colab/jobs/:jobId/metrics`
- `POST /api/colab/jobs/:jobId/system-metrics`
- `POST /api/colab/jobs/:jobId/checkpoints/init-upload`
- `PUT /api/colab/jobs/:jobId/checkpoints/:checkpointId/chunks/:chunkIndex`
- `POST /api/colab/jobs/:jobId/checkpoints/:checkpointId/complete`
- `POST /api/colab/jobs/:jobId/checkpoints/:checkpointId/abort`

## Security notes

- Do not use user passwords in Colab.
- Use job-scoped tokens with narrow permissions.
- Tokens are sent as `Authorization: Bearer <token>`.
- The SDK masks tokens in summaries and never logs the full token intentionally.
- Checkpoints become usable only after the server verifies checksum.
- Metric/log upload failures are buffered and should not stop training.

## Local state

The SDK writes local state under `/content/visionhub/state/{job_id}.json` in Colab, or `.visionhub/state/{job_id}.json` locally. This helps resume or debug interrupted sessions.
