Metadata-Version: 2.4
Name: sagemaker-ops-cli
Version: 0.1.0
Summary: CLI and TUI for submitting and monitoring Amazon SageMaker Processing Jobs and Pipelines.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.34.0
Requires-Dist: botocore>=1.34.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Requires-Dist: textual>=0.58.0
Provides-Extra: yaml
Requires-Dist: PyYAML>=6.0.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: moto[logs,sagemaker]>=5.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# SageMaker Ops CLI

`smops` 是一个面向 SageMaker Processing Job 和 SageMaker Pipeline 的命令行工具：

- 提交 SageMaker Processing Job
- 启动 SageMaker Pipeline execution
- 用 TUI 查看正在运行的 Processing Jobs
- 用 TUI 查看正在运行和最近结束的 Pipeline executions、steps 状态和失败 step 的 CloudWatch 日志尾部
- 支持单个、多个或所有 AWS profiles

## 安装

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
```

从 GitHub 直接安装：

```bash
pip install git+https://github.com/southpolemonkey/smops.git
```

从本地 wheel 安装：

```bash
pip install dist/sagemaker_ops_cli-0.1.0-py3-none-any.whl
```

如果要读取 YAML 配置:

```bash
pip install -e '.[yaml]'
```

## 构建 Python 包

```bash
pip install -e '.[dev]'
python -m build
```

构建产物会输出到 `dist/`：

- `sagemaker_ops_cli-0.1.0-py3-none-any.whl`
- `sagemaker_ops_cli-0.1.0.tar.gz`

## 提交 Processing Job

配置文件直接使用 boto3 `create_processing_job` 的参数结构。

```bash
smops processing submit \
  --profile dev \
  --region us-east-1 \
  --config examples/processing-job.json
```

只检查请求内容，不提交：

```bash
smops processing submit --config examples/processing-job.json --dry-run
```

## 启动 Pipeline

```bash
smops pipeline start \
  --profile dev \
  --region us-east-1 \
  --name my-pipeline \
  --display-name manual-run-001 \
  --parameter InputDate=2026-06-30 \
  --parameter Mode=prod
```

## TUI 查看 Processing Jobs

```bash
smops tui processing --profile dev --region us-east-1
```

多个 profile：

```bash
smops tui processing --profile dev --profile prod --region us-east-1
```

所有 profile：

```bash
smops tui processing --all-profiles
```

快捷键：

- `↑/↓` 或 `←/→` 切换 job
- `r` 刷新
- `q` 退出

## TUI 查看 Pipelines

```bash
smops tui pipelines --profile dev --region us-east-1
```

只看某个 pipeline：

```bash
smops tui pipelines --profile dev --region us-east-1 --name my-pipeline
```

默认会显示正在运行的 executions，以及最近 3 小时内结束的 executions，方便查看成功/失败结果。可以用 `--hours` 调整窗口：

```bash
smops tui pipelines --profile dev --region us-east-1 --name my-pipeline --hours 6
```

快捷键：

- `←/→` 在 executions 和 steps 面板之间切换
- `↑/↓` 移动当前面板选中行
- `l` 加载选中失败 step 的 CloudWatch 日志尾部
- `r` 刷新
- `q` 退出

目前自动支持这些 step 的日志定位：

- ProcessingJob: `/aws/sagemaker/ProcessingJobs`
- TrainingJob: `/aws/sagemaker/TrainingJobs`
- TransformJob: `/aws/sagemaker/TransformJobs`

## 非交互式查看

```bash
smops processing list --profile dev --region us-east-1
smops pipeline list --profile dev --region us-east-1
smops pipeline list --profile dev --region us-east-1 --name my-pipeline --hours 6
smops pipeline steps --profile dev --region us-east-1 --execution-arn arn:aws:sagemaker:...
```

`processing list` 默认每页读取 20 个 running jobs。输出 `Next token` 时，用它继续翻页：

```bash
smops processing list --profile dev --region us-east-1 --max-results 20
smops processing list --profile dev --region us-east-1 --max-results 20 --next-token '<token>'
```

`pipeline list` 不传 `--name` 时默认每页只扫描 10 个 pipelines，避免真实账号里 pipelines 很多时卡住。输出 `Next token` 时，用它继续翻页：

```bash
smops pipeline list --profile dev --region us-east-1 --pipeline-page-size 10
smops pipeline list --profile dev --region us-east-1 --pipeline-page-size 10 --next-token '<token>'
```

## AWS 权限

运行账号需要至少具备这些权限：

- `sagemaker:CreateProcessingJob`
- `sagemaker:StartPipelineExecution`
- `sagemaker:ListProcessingJobs`
- `sagemaker:DescribeProcessingJob`
- `sagemaker:ListPipelines`
- `sagemaker:ListPipelineExecutions`
- `sagemaker:DescribePipelineExecution`
- `sagemaker:ListPipelineExecutionSteps`
- `logs:DescribeLogStreams`
- `logs:GetLogEvents`


## Mock AWS Profile

仓库里提供了一套 mock AWS 配置，方便本地演示 profile 切换和 CLI 参数解析，不会写入真实 `~/.aws`：

```bash
export AWS_CONFIG_FILE=examples/aws/config
export AWS_SHARED_CREDENTIALS_FILE=examples/aws/credentials
export AWS_PROFILE=mock-dev
export AWS_DEFAULT_REGION=us-east-1
```

也可以直接加载样例环境变量：

```bash
set -a
source examples/aws/mock.env
set +a
```

然后运行：

```bash
smops processing submit --config examples/processing-job.json --dry-run
smops processing list --profile mock-dev
smops tui processing --profile mock-dev
```

注意：这套 credentials 是 dummy 值，只适合 dry-run、mock、本地端点或配合 botocore Stubber/moto 使用；直接访问真实 AWS 会认证失败。

## E2E 测试

测试使用 `moto` 模拟 AWS SageMaker 和 CloudWatch Logs，不会访问真实 AWS：

```bash
pip install -e '.[dev]'
pytest
```

覆盖范围包括：

- Processing Job 提交和 running job 分页列表
- Pipeline execution 启动和 active/recent execution 列表
- Pipeline steps 状态展示
- 失败 step 的 CloudWatch Logs tail
- Processing Job TUI 的上下左右键导航
- Pipeline TUI 的 executions、steps 和失败日志加载
- 多 AWS profile 解析

Moto 目前还没有实现 `list_pipeline_execution_steps`，测试里对这一个 paginator 做了内存 fake，其余 SageMaker/Logs 调用都在 moto 环境中执行。
