ark-sdk-development

# ARK SDK and Type Development

## Type Generation Pipeline

Types flow through the ARK stack:

```
CRD YAML (ark/config/crd/)
    ↓ make ark-sdk-build (automatic)
ark-sdk Python types + overlay utilities
    ↓
ark-api Pydantic models (manual updates if exposing new fields)
    ↓ make ark-api-build → generates openapi.json
ark-dashboard TypeScript types
    ↓ npm run generate:api → generates types.ts
```

## ark-sdk: Automatic Type Generation

CRD types are **automatically generated** from Kubernetes CRD YAML files.

```bash
make ark-sdk-build
```

This runs:
1. `crd_to_openapi.py` - converts CRDs to OpenAPI schema
2. `openapi-generator-cli` - generates Python types from schema
3. Copies overlay files on top of generated code
4. Builds wheel package

### Adding Custom SDK Functionality (Overlays)

The `lib/ark-sdk/gen_sdk/overlay/python/ark_sdk/` directory contains custom Python modules that are copied on top of generated code. This is how utilities like `client.py`, `k8s.py`, and `executor.py` are added.

To add custom SDK functionality:
1. Add Python files to `lib/ark-sdk/gen_sdk/overlay/python/ark_sdk/`
2. Run `make ark-sdk-build`

## ark-api: Manual Model Updates

The ark-api has **manually written** Pydantic models in `services/ark-api/ark-api/src/ark_api/models/`.

When to update ark-api models:
- When exposing new CRD fields via the HTTP API
- When adding new API response types

```bash
make ark-api-build
```

This generates `services/ark-api/openapi.json` from FastAPI routes and Pydantic models.

### Pydantic Model Naming (CRITICAL)

Pydantic model class names **MUST be globally unique** across all model files. When multiple files define classes with the same name (e.g., `ConfigMapKeyRef`, `Header`, `ValueFrom`), FastAPI generates non-deterministic OpenAPI schema names like `ark_api__models__agents__Header-Input`. These names depend on import order and cause CI failures when `types.ts` differs between environments.

**Solution**: Prefix class names with thei