AI Factory SDK
Python SDK for the AI Factory Compute API — submit and manage HPC jobs from Python.
Features
- Synchronous and asynchronous clients (
AIFactoryClient,AsyncAIFactoryClient) - Typed request/response models with Pydantic validation
- Job polling with configurable timeout and retry (
client.wait()) - Automatic retry on transient errors (429, 5xx)
- PEP 561 compatible — full type annotation coverage
Installation
pip install ai-factory-sdk
Or with uv:
uv add ai-factory-sdk
Pre-release versions
Development builds published from the dev branch use PEP 440 pre-release
suffixes (e.g., 0.2.0.dev1). Install them with:
pip install ai-factory-sdk --pre
Quick Start
from ai_factory.sdk import AIFactoryClient, JobRequest
# Credentials via environment: AI_FACTORY_API_KEY, AI_FACTORY_SLURM_USER
# Or pass explicitly:
with AIFactoryClient(token="...", slurm_user="jane") as client:
# Submit a job
resp = client.submit_job(
JobRequest(name="hello", script="#!/bin/bash\necho Hello from SLURM")
)
print(f"Submitted job {resp.job_id}")
# Wait for completion
if resp.job_id is not None:
detail = client.wait(str(resp.job_id), timeout=3600)
print(f"Job finished with status: {detail.status}")
Async Usage
import asyncio
from ai_factory.sdk import AsyncAIFactoryClient, JobRequest
async def main():
async with AsyncAIFactoryClient(token="...", slurm_user="jane") as client:
resp = await client.submit_job(
JobRequest(name="async-job", script="#!/bin/bash\nsleep 10 && echo done")
)
if resp.job_id is not None:
detail = await client.wait(str(resp.job_id))
print(detail.status)
asyncio.run(main())
Container Jobs
from ai_factory.sdk import AIFactoryClient, ContainerJobRequest
with AIFactoryClient(token="...", slurm_user="jane") as client:
resp = client.submit_container(
ContainerJobRequest(
name="gpu-training",
image="docker://nvcr.io/nvidia/pytorch:24.01-py3",
container_command="python train.py",
gres="gpu:a40:1",
time_limit=120,
)
)
Configuration
| Parameter | Environment Variable | Default |
|---|---|---|
base_url |
AI_FACTORY_API_URL |
https://compute-api.ai-factory.datalab.tuwien.ac.at/compute-api/v1 |
token |
AI_FACTORY_API_KEY |
(required) |
slurm_user |
AI_FACTORY_SLURM_USER |
(required) |
timeout |
— | 30.0 (HTTP timeout in seconds) |
Constructor parameters take precedence over environment variables.
API Reference
Clients
| Class | Description |
|---|---|
AIFactoryClient |
Synchronous client (context manager) |
AsyncAIFactoryClient |
Asynchronous client (async context manager) |
Methods
| Method | Description |
|---|---|
submit_job(request) |
Submit a Slurm job script |
submit_container(request) |
Submit a containerised job |
get_job(job_id) |
Get job details by ID |
list_jobs(...) |
List jobs with optional filters and pagination |
cancel_job(job_id) |
Cancel a running or pending job |
wait(job_id, ...) |
Poll until the job reaches a terminal state |
Request Models
| Model | Fields |
|---|---|
JobRequest |
name, script, partition, tasks, cpus_per_task, time_limit, gres, standard_output, standard_error |
ContainerJobRequest |
name, image, container_command, partition, tasks, cpus_per_task, time_limit, gres, standard_output, standard_error |
Response Models
| Model | Fields |
|---|---|
SubmitJobResponse |
job_id, output_dir, logs_url |
JobDetail |
job_id, name, status, partition, nodes, exit_code, duration, start_time, end_time, submit_time, working_directory, standard_output, standard_error, gres, output_dir, logs_url |
JobListItem |
job_id, name, status, duration, start_time, end_time |
JobList |
jobs, total, limit, offset |
CancelJobResponse |
message |
Exceptions
| Exception | When |
|---|---|
SDKError |
Base for all SDK errors |
APIError |
Non-2xx HTTP response |
AuthError |
401 or 403 response |
NotFoundError |
404 response |
WaitTimeoutError |
wait() exceeded its deadline |
Requirements
License
Metadata
Release files for ai-factory-sdk 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ai_factory_sdk-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for ai_factory_sdk-0.1.1-py3-none-any.whl |
Release files / ai_factory_sdk-0.1.1-py3-none-any.whl
| Download URL | ai_factory_sdk-0.1.1-py3-none-any.whl |
|---|---|
| Size | 12.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
95793a34fa3c03bb9a6af631768597c15b587688d5bab26ca15a4a807d067487
|
|
BLAKE2b-256 checksum How to use checksums |
1b331ffaa77490c8a7ee5430a6cdfa3a1477ea1d3ea6a0eab60517372ef81867
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.13
|
Security for ai-factory-sdk 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.