AfriLink SDK

Version: 0.8.28

Last Updated: September 3, 2026

Train & Finetune on a GPU Cluster from Any Notebook

AfriLink SDK gives you one-line access to dedicated GPUs for training and finetuning across text, vision and multimodal models. Works on Google Colab, Kaggle, Jupyter, VS Code, and any Python environment.

Supported backends:

| Backend | Environment var | What it targets | | k3s (default) | (none needed) | DataSpires K3s GPU cluster via REST orchestrator | | opentoken-a100 | AFRILINK_BACKEND=opentoken-a100 | OpenToken NVIDIA A100 80 GB over SSH |

pip install afrilink-sdk

Which API should I use?

Rule of thumb: If you are adapting a language model with adapters, use finetune(). If you are running a Python training script you wrote (or a non-LLM task), use train(). Do not call train(container="afrilink-finetune") to fine-tune an LLM unless you have a custom training script — finetune() is the managed path.

After either API completes, download weights with client.download_model(job_id, local_dir).

Quick Start — Finetune an LLM

from afrilink import AfriLinkClient

client = AfriLinkClient()
client.authenticate()   # reads AFRILINK_API_KEY from notebook secrets / env

import pandas as pd
data = pd.DataFrame({"text": [
    "Below is an instruction...\n\n### Response:\nHere is the answer..."
]})

job = client.finetune(
    model="qwen2.5-0.5b",
    training_mode="low",
    data=data,
    gpus=1,
    time_limit="01:00:00",
)
result = job.run(wait=True)

if result["status"] == "completed":
    client.download_model(result["job_id"], "./my-model")

Quick Start — Train a Vision Model (V100)

from afrilink import AfriLinkClient

client = AfriLinkClient()
client.authenticate()

# Submit a YOLOv8 training job to the V100
job = client.train(
    script="train_yolo.py",        # your training script
    container="afrilink-yolo",      # pre-built container with YOLOv8 + PyTorch
    data="./dataset.tar.gz",        # dataset (uploaded automatically)
    data_config="dataset.yaml",     # YOLO dataset.yaml
    gpus=1,
    time_limit="02:00:00",
)
result = job.run(wait=True)
print(job.get_logs(tail=50))
client.download_model(result["job_id"], "./yolo-out")

Quick Start — Train on the K3s Cluster

The K3s backend submits jobs to the DataSpires GPU cluster via the orchestrator REST API. Files are staged through S3-compatible presigned URLs.

import os
os.environ["AFRILINK_BACKEND"] = "k3s"

from afrilink import AfriLinkClient

client = AfriLinkClient()
client.authenticate(api_key="afk_live_…")  # API key required for K3s

job = client.train(
    script_content="""
import time, os
print("Running on the K3s cluster...")
for i in range(5):
    print(f"Step {i}/5")
    time.sleep(1)

# Write outputs — the orchestrator syncs /workspace/job/output/ back to S3
os.makedirs("/workspace/job/output", exist_ok=True)
with open("/workspace/job/output/result.txt", "w") as f:
    f.write("Training complete")
""",
    container="python:3.11-slim",  # any public Docker image
    gpus=1,
    time_limit="00:30:00",
)
result = job.run(wait=True, poll_interval=5)
print(result["status"])  # "completed" or "failed"

# Download output files locally
from pathlib import Path
job.k8s_runner.download_output(job.job_id, Path("./outputs"))

Quick Start — Custom Container

from afrilink import AfriLinkClient

client = AfriLinkClient()
client.authenticate()

# Define exactly the environment your training needs.
spec = dict(
    base_image="pytorch",                                # preset
    pip_packages=["transformers>=4.45", "accelerate>=0.34", "peft>=0.13"],
    apt_packages=["git"],
    model_source={
        "kind": "huggingface",
        "id": "Qwen/Qwen2.5-0.5B-Instruct",
    },
)

# Builds the image on Cloud Build (~5 min first time, instant on cache hit
# for the same spec on subsequent runs), runs on the Tesla V100, deletes the
# local image layer afterwards, returns the artefact directory.
result = client.build_and_train(
    script="my_train.py",
    gpus=1,
    time_limit_hours=0.5,
    reuse_existing_image=True,   # default — short-circuits identical specs
    **spec,
)
client.download_model(result["run"]["job_id"], "./output")

Installation

pip install 'afrilink-sdk'

The core package depends on requests (used for auth and the k3s orchestrator). The [build] extra pulls cryptography, needed for the GCP service-account JWT signing the custom-container path uses. Without [build] only the curated client.train() and client.finetune() paths work.

Heavy libraries (torch, transformers, peft, etc.) are only loaded when you actually call into code that needs them, and are pre-installed in most notebook environments.

Authentication

As of v0.8.x the SDK uses stateless API-key auth — no email/password prompts, no 12-hour certificate refreshes, no SSH key management on your side.

Get an API key

1. Sign up at dataspires.com.
2. Go to Profile → AfriLink SDK keys, click Create new key, copy the afk_live_… value (shown once).
3. Add it to your notebook environment as AFRILINK_API_KEY.

Set the key

from afrilink import AfriLinkClient

client = AfriLinkClient()
client.authenticate()   # resolves from secret / env / argument in that order

What happens at auth time

Both phases together take ~1–2 seconds. The session keeps the JWT in memory for the kernel lifetime — no on-disk state. To rotate the key, revoke it on the dashboard and mint a new one.

Built-in User Guide

The SDK ships with an inline reference manual you can query from any notebook cell using a slash-style syntax:

import afrilink

afrilink/help          # top-level index of all topics
afrilink/quickstart    # step-by-step getting started guide
afrilink/auth          # authentication
afrilink/finetune      # finetune job parameters & training modes
afrilink/training      # general training jobs and containers
afrilink/specs         # V100 hardware spec sheet
afrilink/datasets      # dataset formats and upload
afrilink/billing       # rates, credits, invoices

Each page prints a formatted reference to your notebook output — no internet connection required.

API Reference

AfriLinkClient

Main entry point. Created once per notebook session.

client.finetune()

job = client.finetune(
    model="qwen2.5-0.5b",         # model ID from registry
    training_mode="low",           # "low" | "medium" | "high"
    data=my_dataframe,             # pandas DataFrame, HF Dataset, or file path
    gpus=1,                        # silently clamped to 1 (V100 backend has 1 GPU)
    time_limit="01:00:00",         # max wallclock (HH:MM:SS)
    output_dir=None,               # default: /workspace/job/output
)

Training modes:

The V100 backend has 1 GPU — distributed training (gpus>1) is silently clamped to 1 with a console note. Multi-GPU is on the roadmap.

client.train()

job = client.train(
    script="train_yolo.py",        # local Python script to upload and run
    container="afrilink-yolo",      # pre-built container
    data="./dataset/",              # local path, archive, DataFrame, or remote path
    data_config="dataset.yaml",     # config file (e.g. YOLO dataset.yaml)
    gpus=1,
    time_limit="04:00:00",
    script_args=["--epochs", "100"],
    extra_files=["weights.pt"],
    container_env={"KEY": "val"},
)

Curated containers (container= argument):

Need a different stack? Use client.build_image() / client.build_and_train() (next section).

Data handling:

Container file paths

Every uploaded file lands under /workspace/job/input/ inside the container. Write artefacts to /workspace/job/output/ so they can be synced back.

--data auto-injection. When you pass data=, the SDK appends --data /workspace/job/input/<name> to the command that runs your script. Parse it with argparse (or read the path directly):

import argparse

parser = argparse.ArgumentParser()
parser.add_argument("--data", default="/workspace/job/input")
args = parser.parse_args()
# args.data is /workspace/job/input/dir  or  /workspace/job/input/file.csv

Environment variables available inside the container:

Plus any keys you pass via container_env=.

K3s output retrieval. Your script must write outputs to /workspace/job/output/. The orchestrator syncs that prefix to S3 when the job completes. Download locally with:

from pathlib import Path
job.k8s_runner.download_output(job.job_id, Path("./my-outputs"))

This calls GET /api/v1/jobs/{id}/files?prefix=output to list files, then POST /api/v1/jobs/{id}/presigned-urls to get download URLs, and streams each file to disk.

TrainJob / FinetuneJob

Returned by client.train() / client.finetune().

run() result dict — V100 backend:

{
    "job_id": "a1b2c3d4",
    "container_id": "d9072f194771...",
    "status": "completed",        # or "submitted" / "failed" / "cancelled"
    "output_dir": "/mnt/data/sdk-jobs/a1b2c3d4/output",
    "billing": {
        "total_gpu_minutes": 5.0,
        "total_cost_usd": 0.1667,
        "rate_per_gpu_hour": 0.60,
        "billing_source": "wall-clock-docker",
    },
}

run() result dict — K3s backend:

{
    "job_id": "a1b2c3d4",
    "status": "completed",        # or "queued" / "failed" / "timeout"
    "billing": None,              # billing not yet wired for K3s
}
# On failure, also includes:
#   "error": "<last 200 log lines from the pod>"

K3s async job discovery:

Submit without blocking, then list or poll from the same or a new session:

result = job.run(wait=False)
job_id = result["job_id"]

# List your active jobs (queued, running, failed)
for entry in client.list_jobs():
    print(entry["job_id"], entry["state"], entry.get("reason"), entry.get("message"))

# Poll a specific job by id (works even after notebook restart)
status = client.get_job_status(job_id)
print(status["state"])  # queued | running | completed | failed | missing
if status.get("reason"):
    print(status["reason"], status.get("message"))

# Block until done, then download outputs
job.run(wait=True)  # or poll get_job_status() in a loop
client.download_model(job_id, "./outputs")

list_jobs() returns queued, running, and failed jobs. list_jobs(include_completed=True) also includes completed jobs while they remain in the cluster (up to 3 days). Failed jobs include optional reason and message fields when the orchestrator can determine why the pod did not start. Jobs submitted before the orchestrator user-label deploy won't appear in list results but remain queryable via get_job_status(job_id).

Requires a deployed orchestrator with GET /api/v1/jobs — see v0.8.0_continuation.md §16.

Custom Containers — client.build_image() / client.build_and_train()

If the curated containers don't have the framework, version, or model you need, define it yourself. Cloud Build builds the image, Artifact Registry hosts it, the V100 runs it ephemerally.

Define the spec

spec = dict(
    base_image="pytorch",                                # preset name, or full image:tag
    pip_packages=["transformers>=4.45", "accelerate>=0.34"],
    apt_packages=["git"],
    pip_index_url=None,                                  # optional alternative index
    pip_extra_index_urls=[],
    model_source={                                       # fetched at job runtime
        "kind": "huggingface",                           # huggingface | url | git | gs | s3
        "id": "Qwen/Qwen2.5-0.5B-Instruct",
        "revision": "main",
    },
    env={"WANDB_PROJECT": "demo"},                       # baked into image (non-secret)
)

Presets for base_image:

You can also pass any full image:tag you want.

Model sources (model_source=):

The model is fetched at container runtime, not baked at build time — that keeps user images thin (~2 GB instead of 7+ GB) and means you can iterate on dependencies without re-shipping weights. The downloaded model lands at /workspace/models/<sanitised_id>/ and the path is exposed via MODELS_DIR env var to your script.

For gated HF models (Llama, Gemma, etc.): add HUGGINGFACE_TOKEN as a notebook secret and the SDK forwards it to the container automatically.

Check the cache before building

hit = client.find_existing_image(
    base_image="pytorch",
    pip_packages=["transformers>=4.45", "accelerate>=0.34"],
    apt_packages=["git"],
    model_source={"kind": "huggingface", "id": "Qwen/Qwen2.5-0.5B-Instruct"},
)
# hit == None  → no match, will build
# hit == {"image": "...", "source": "v100" | "artifact_registry", "spec_hash": "..."}

The hash includes only the inputs that change what gets baked into the image:

Two specs that produce a runtime-equivalent image hash to the same value → instant cache hit. A version bump on any pip package, an extra apt dep, a different model revision → fresh hash → fresh build.

Build and run

# Build only — useful if you want to inspect the image or run it multiple ways
build = client.build_image(**spec, script="my_train.py")
# build["image"] = "europe-west4-docker.pkg.dev/.../<job>:latest"
# build["status"] = "success"
# build["build_id"] = "<...>"

# Build (or skip if cached) + run + cleanup, all in one call
result = client.build_and_train(
    **spec,
    script="my_train.py",
    data="./train.jsonl",
    gpus=1,
    time_limit_hours=1.0,
    reuse_existing_image=True,   # default; False forces a fresh build
    cleanup_image_after=True,    # default; False keeps the V100's local layer
)
# result["build"]["status"] = "success" (fresh) or "cached" (reused)
# result["run"]["status"]   = "completed"
# result["run"]["output_dir"] = "/mnt/data/sdk-jobs/<job_id>/output"

client.download_model(result["run"]["job_id"], "./local-out")

Container lifecycle

To delete an image from Artifact Registry too: gcloud artifacts docker images delete <uri>.

Working With Your Model

Once you've downloaded the adapter, the directory is ready for standard Hugging Face tooling.

GGUF Conversion & Ollama

Convert your adapter to GGUF format for use with Ollama or llama.cpp:

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

# 1. Merge adapter into base model
base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen2.5-0.5B")
model = PeftModel.from_pretrained(base, "./my-model")
merged = model.merge_and_unload()
merged.save_pretrained("./my-model-merged")
AutoTokenizer.from_pretrained("Qwen/Qwen2.5-0.5B").save_pretrained("./my-model-merged")

# 2. Convert to GGUF (requires llama.cpp built locally)
# python convert_hf_to_gguf.py ./my-model-merged --outfile my-model.gguf --outtype f16

# 3. Quantize (optional, 4-bit)
# ./llama-quantize my-model.gguf my-model-q4.gguf Q4_K_M

# 4. Run with Ollama
# Create a Modelfile:  FROM ./my-model-q4.gguf
# ollama create my-model -f Modelfile
# ollama run my-model

Publishing to Hugging Face Hub

from huggingface_hub import HfApi

api = HfApi(token="hf_...")
repo_id = "your-username/my-finetuned-model"
api.create_repo(repo_id, exist_ok=True)

# Option A — adapter only (small, loads on top of base model)
api.upload_folder(folder_path="./my-model", repo_id=repo_id)

# Option B — full merged model
api.upload_folder(folder_path="./my-model-merged", repo_id=repo_id)

# Option C — GGUF file
api.upload_file(path_or_fileobj="./my-model-q4.gguf",
                path_in_repo="my-model-q4.gguf",
                repo_id=repo_id)

Hardware Specs

OpenToken V100 32 GB (opentoken.global) — the dedicated GPU node the SDK runs on:

Per-job memory guide for 1× V100 32 GB:

Billing

$0.60 / GPU-hour, charged per completed GPU-minute (minimum 1 minute). Credits deducted automatically from your DataSpires balance via the deduct_credits Supabase RPC at job end. Invoices appear on the DataSpires Billing dashboard in real time.

Build-time minutes on Cloud Build are absorbed by the platform — you only pay GPU-time.

Model & Dataset Registry

client.list_available_models()                      # all models
client.list_available_models(size="tiny")           # tiny | small | medium | large
client.list_available_datasets()
client.get_model_requirements("qwen2.5-0.5b", "low")

Curated models:

For anything outside this registry, use client.build_image() / client.build_and_train() with model_source=.

Architecture

Notebook (Colab / Kaggle / Local)         api.dataspires.com (Cloudflare Worker)
+---------------------+                   +---------------------------+
| AfriLink SDK        | --- POST -----→   | exchange afk_live_… for:  |
|  client.authenticate()                  |  - Supabase JWT (billing) |
|                     | ←-- response ---  |  - V100 SSH key (in-mem)  |
+---------------------+                   |  - GCP SA key (build)     |
     |        ↓                           |  - GHCR PAT (image pulls) |
     |   (in-memory state)                +---------------------------+
     |
     ↓
+---------------------+        SSH        +---------------------+
| docker_runner.py    | ----------------→ | OpenToken V100 32GB |
|  - prepare_job_dir  |   /mnt/data/      |  Docker daemon      |
|  - upload via SCP   |    sdk-jobs/      |  (containerd at     |
|  - docker run --gpus=all                |   /mnt/data/)       |
|  - docker inspect (poll)                +---------------------+
+---------------------+
     |
     ↓ build path
+---------------------+   Cloud Build    +---------------------+
| build.py            | --→ submit job → | europe-west4-       |
|  - generate Docker- |     (anadrome)   | docker.pkg.dev/...  |
|    file from spec   |                  |  afrilink-user-     |
|  - tar build context|                  |  images/<user>/<job>|
|  - upload to GCS    |                  +---------------------+
+---------------------+                            |
                                                   ↓ docker pull
                                              (V100 fetches image,
                                               runs it, deletes
                                               local layer at end)

The V100 backend, the Cloudflare Worker, the Cloud Build pipeline, the Artifact Registry, the Supabase backend — all of it lives behind client.authenticate(). As a user you set one notebook secret and get on with training.

License

MIT