AfriLink SDK

Version: 0.9.3

One-line access to GPUs for training, finetuning, and inference — from any notebook.

pip install 'afrilink-sdk>=0.9.3'

Works in: Google Colab · Kaggle · Jupyter · VS Code · any Python 3.8+ environment

Pilot scope: This documentation covers the k3s backend only (the default). Other backends exist in the full SDK but are not part of this pilot and are not documented here. You do not need to set AFRILINK_BACKEND.

Contents

1. 60-second quickstart
2. Authentication
3. Which method should I use?
4. Known limitations
5. Backend (k3s)
6. Guides by task — Pretrain · Finetune · Generate
7. Working with your output model
8. API reference
9. Hardware & billing
10. Model & dataset registry
11. Troubleshooting
12. Built-in help

60-second quickstart

from afrilink import AfriLinkClient

client = AfriLinkClient()
client.authenticate(api_key="afk_live_…")  # or set AFRILINK_API_KEY

job = client.pretrain(
    kind="image-classify",
    model="resnet18",
    data="./images/",
    params={"epochs": 5, "num_classes": 2},
    gpus=1,
)
result = job.run(wait=True)
print(result["status"])  # "completed" | "failed" | "timeout" | …
if result["status"] != "completed":
    print(result.get("error") or result.get("reason"))

finetune() and generate() use the same client → job → job.run() pattern. See Guides by task.

Authentication

Auth is a single stateless API key — no passwords, no certificate refresh, no SSH key management on your side.

Get a key

1. Sign up at dataspires.com.
2. Profile → AfriLink SDK keys → Create new key. Copy the afk_live_… value — it's shown once.
3. Store it as AFRILINK_API_KEY.

Set the key

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

Errors

authenticate() raises Exception (message like API key auth failed: …) on a bad or revoked key. Wrap it if you want a soft failure:

try:
    client.authenticate()
except Exception as e:
    print("Auth failed:", e)

After a successful call, the short-lived session JWT lives in memory for the kernel lifetime — nothing is written to disk. Rotate a key by revoking it on the dashboard and minting a new one.

Which method should I use?

Rule of thumb: train from zero → pretrain(). Adapt existing weights → finetune(). Frozen answers → generate().

Deprecated APIs (removed in 1.0.0)

# Before (deprecated)
job = client.train(script="train_yolo.py", container="afrilink-yolo", data="./data/")

# After
job = client.pretrain(kind="yolo-detect", weights="yolo11n.pt", data="./data/", data_config="data.yaml")

Known limitations

Backend (k3s)

status vs state (not a typo)

Two related schemas:

result = job.run(wait=True)
print(result["status"])                 # job.run() → status

for entry in client.list_jobs():
    print(entry["job_id"], entry["state"], entry.get("reason"))

print(client.get_job_status(result["job_id"])["state"])

Guides by task

Pretrain

(YOLO, CNN, or transformer recipes — platform owns the training loop)

job = client.pretrain(
    kind="image-classify",
    model="resnet18",
    data="./images/",
    params={"epochs": 5, "num_classes": 2},
    gpus=1,
    time_limit="02:00:00",   # HH:MM:SS string — see note below
)
result = job.run(wait=True)

YOLO:

job = client.pretrain(
    kind="yolo-detect",
    weights="yolo11n.pt",    # or scratch=True for random init
    data="./dataset/",
    data_config="data.yaml",
    gpus=1,
    time_limit="02:00:00",
)
result = job.run(wait=True)

Time limits: pretrain(), finetune(), and generate() take time_limit as a string HH:MM:SS. (Other SDK APIs outside this pilot use time_limit_hours as a float — do not mix them up.)

Curated containers from kind=:

K3s output retrieval

Write artefacts to /workspace/job/output/. The orchestrator syncs that prefix on completion.

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

Passing data= on pretrain / finetune / generate already uploads your dataset. You only need client.upload_dataset(...) for advanced, separate staging:

remote = client.upload_dataset("./my_data/", dataset_name="assignment2")

Finetune

(LoRA/QLoRA on an LLM/VLM — afrilink-finetune container)

import pandas as pd

data = pd.DataFrame({"text": ["Below is an instruction...\n\n### Response:\n..."]})

job = client.finetune(
    model="qwen2.5-0.5b",
    training_mode="low",     # low | medium | high
    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")
else:
    print(result.get("error") or result.get("reason"))

For VLMs, pass task= (captioning / VQA) with image+text data. See afrilink/finetune in Built-in help.

Generate

(frozen inference — no weight updates)

job = client.generate(
    model="smolvlm-256m",
    data="./manifest_dir/",
    outputs=["text", "confidence"],   # add "hidden_states" for analysis
    max_new_tokens=64,
    temperature=0.0,
)
result = job.run(wait=True)

Job failures (all three verbs)

job.run(wait=True) does not raise on a failed training/generate job. It returns a dict:

{
  "job_id": "a1b2c3d4",
  "status": "failed",          # or "timeout", "cancelled", …
  "error": "<log tail>",       # often present
  "reason": "…",               # optional (k3s)
  "billing": null              # often null on this pilot
}

Check result["status"] == "completed" before downloading outputs. Auth and submit-time validation errors (bad key, not authenticated, invalid gpus / time_limit) do raise.

Working with your model

Convert to GGUF for Ollama / llama.cpp

1. Merge the adapter in Python (notebook):

from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel

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. Run these in a terminal (not a notebook cell):

python convert_hf_to_gguf.py ./my-model-merged --outfile my-model.gguf --outtype f16
./llama-quantize my-model.gguf my-model-q4.gguf Q4_K_M
ollama create my-model -f Modelfile && ollama run my-model

Publish to Hugging Face Hub

from huggingface_hub import HfApi

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

API reference

AfriLinkClient (pilot-relevant)

Job objects (PretrainJob / FinetuneJob / GenerateJob)

Returned by pretrain() / finetune() / generate(). Not returned by build_and_train() (that API is out of pilot scope and returns a nested dict when used on its own backend).

Async discovery:

result = job.run(wait=False)          # {"job_id", "status": "submitted", …}
status = client.get_job_status(result["job_id"])
print(status["state"], status.get("reason"))

list_jobs(include_completed=True) includes finished jobs for up to ~3 days.

Hardware & billing

Jobs run on the DataSpires k3s GPU cluster. Prefer small models and training_mode="low" (QLoRA) for workshop / assignment budgets.

Limits: up to 24h time_limit; hard max 32 GPUs (SDK warns above 8). Past time_limit, the run stops — check for status/state of timeout or cancelled.

Billing: invoices at dataspires.com/dashboard/billing. On this pilot, result["billing"] is often null; use job.estimated_cost_usd() only as a planning ceiling.

Model & dataset registry

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

Troubleshooting

Built-in help

Prefer afrilink.docs("topic") — it always works. The slash form is also supported when the topic is a quoted string.

import afrilink

afrilink.docs("help")       # recommended
afrilink.docs("finetune")
afrilink.docs("pretrain")
afrilink.docs("generate")
afrilink.docs("choose")
afrilink.docs("billing")

# Equivalent quoted slash form (module implements __truediv__):
afrilink / "help"
afrilink / "finetune"

afrilink/help (unquoted) works only because help is a Python builtin; we map that object to the "help" page. Unquoted names like afrilink/finetune usually raise NameError unless finetune is already bound in your scope — do not copy those bare forms from older docs.

Links

• Docs: dataspires.com/docs
• Repository / Issues: github.com/DataSpires/afrilink-sdk
• License: MIT