# qai-cli

A CLI for the Qualcomm model MLOps pipeline — browse and download models from Qualcomm AI Hub, fine-tune them on custom datasets using SageMaker, validate inference, and prepare artifacts for Qualcomm hardware deployment.

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- AWS account with credentials configured (`aws configure`) when using `qai-cli infra`
- AWS CDK CLI (`npm install -g aws-cdk`) when using `qai-cli infra setup` or `qai-cli infra destroy`

## Installation

```bash
git clone <repo>
cd qai-cli
uv sync
```

Run commands with `uv run qai-cli <command>` or activate the venv first:

```bash
source .venv/bin/activate
qai-cli --help
```

## Quick start

```bash
# 1. Create config.yaml in the current directory
qai-cli init

# 2. Edit config.yaml — at minimum set s3.bucket and sagemaker.role_name

# 3. Provision AWS infrastructure (S3 bucket + SageMaker IAM role).
#    This is the step that requires the AWS CDK CLI.
qai-cli infra setup
```

## Configuration

`qai-cli init` writes a `config.yaml` in the current directory. The fields you must fill in before using the tool:

```yaml
aws:
  region: us-east-1
  profile: default          # AWS CLI profile name

s3:
  bucket: your-unique-bucket-name

sagemaker:
  role_name: qai-cli-sagemaker-role
```

To provision an MLflow tracking server, set:

```yaml
mlflow:
  mode: create
  tracking_server_name: your-tracking-server-name
```

To use an existing MLflow tracking server, set:

```yaml
mlflow:
  mode: existing
  tracking_server_name: your-tracking-server-name
```

## Commands

### `init`

```
qai-cli init                  Write config.yaml
qai-cli init --output <path>  Write config to a custom path
qai-cli init --force          Overwrite an existing config file
```

### `infra`

```
qai-cli infra setup                         Deploy the CDK stack
qai-cli infra setup --no-bootstrap          Deploy without running CDK bootstrap
qai-cli infra status                        Show CDK stack/resource status
qai-cli infra destroy                       Destroy stack, retaining S3 data
qai-cli infra destroy --yes                 Destroy stack without confirmation
qai-cli infra destroy --delete-bucket-data  Destroy stack and delete S3 data
```

## AWS permissions required

The IAM user or role running the CLI needs:

| Action | Service |
|---|---|
| CreateBucket, DeleteBucket, PutObject, GetObject, ListBucket, DeleteObject | S3 |
| CreateRole, GetRole, DeleteRole, AttachRolePolicy, DetachRolePolicy | IAM |
| CreateStack, UpdateStack, DeleteStack, DescribeStacks, DescribeStackEvents | CloudFormation |
| GetCallerIdentity | STS |
| CreateMlflowTrackingServer, DescribeMlflowTrackingServer, DeleteMlflowTrackingServer | SageMaker AI, when `mlflow.mode` is `create` or `existing` |

`AdministratorAccess` covers all of the above.