ARK SDK

The ARK Python SDK provides programmatic access to ARK Kubernetes resources.

Installation

Install via uv or pip:


# Install via uv:
uv add "ark-sdk @ https://github.com/mckinsey/agents-at-scale-ark/releases/download/v0.1.31/ark_sdk-0.1.31-py3-none-any.whl"
 
# or pip:
pip install https://github.com/mckinsey/agents-at-scale-ark/releases/download/v0.1.31/ark_sdk-0.1.31-py3-none-any.whl

Or directory add to your pyproject.toml:


[tool.uv.sources]
ark-sdk = { url = "https://github.com/mckinsey/agents-at-scale-ark/releases/download/v0.1.31/ark_sdk-0.1.31-py3-none-any.whl" }

Or requirements.txt:


ark-sdk @ https://github.com/mckinsey/agents-at-scale-ark/releases/download/v0.1.31/ark_sdk-0.1.31-py3-none-any.whl

Updating Types When CRDs Change

ARK uses Kubernetes CRDs as the source of truth. When CRDs change, types must be updated through the stack.

Changes to the CRDs must be reflected in the Ark SDK, these changes must then be reflected in consumers of the SDK such as the Ark APIs, and consumers of those APIs, such as the Ark dashboard.

Mechanically, the process works like this:


# Changes are made in the ark CRDs at:
#   config/crd/bases/*.yaml:
 
# The Python SDK is regenerated from the CRDs. The CRDs are converted into
# an OpenAI spec and then this regenerated the ark sdk types:
make ark-sdk-build
 
# Consumers of the ark api update their code. When a CRD change is made and the
# sdk is regenerated, the ark-api models must be updated (manually).
# After this, the ark-api can be built:
make ark-api-build
 
# This genreated the services/ark-api/openapi.json, based on the FastAPI models.
 
# Finally, the ark dashboard can have its Typescript types automatically updated
# based on the new ark-api routes and models:
cp ../../ark-api/openapi.json ../out/
npm run generate:api
 
# This generate:
# lib/api/generated/types.ts
 
 
## Local Development Workflow
 
When developing new functionality in `ark-sdk`, follow this workflow:
 
1. Add new functionality to overlay files in `lib/ark-sdk/gen_sdk/overlay/python/ark_sdk/`.
 
2. Build & Test - Run `make ark-sdk-build` to generate the wheel file, then `make ark-sdk-test` to verify changes work correctly.
 
3. Use in Services - Copy the generated wheel to your service's `out/` directory and test with `devspace dev` to verify integration. The service will automatically use the local wheel file instead of the PyPI version.
 
## Production Deployment
 
1. Deploy to PyPI - Trigger deployment via GitHub Actions to publish new version to PyPI.
 
2. Update Services - Update consuming services' `pyproject.toml` to use the new ark-sdk version, then rebuild and deploy.
 
 
## Adding Custom SDK Functionality
 
To add custom functionality to the ARK SDK, place Python modules in `lib/ark-sdk/gen_sdk/overlay/python/ark_sdk/` and run `make ark-sdk-build`. The build system automatically tracks overlay files and rebuilds when they change, copying them into the generated SDK package.
 
## Usage
 
Online documentation is work in progress [ticket AAS-2658]. For usage examples, see the [ark-apis service](https://github.com/mckinsey/agents-at-scale-ark/tree/main/services/ark-api).