# nbdraw

`nbdraw` is a Python CLI for generating images with GRSAI nano banana models.

`nbdraw` 是一个用于调用 GRSAI nano banana 模型进行绘图的 Python 命令行工具。

## Features / 特性

- `nbdraw draw` command for image generation
- Config priority: file < env < CLI
- Auto download to `./outputs` by default
- JSON output for script integration
- Backward-compatible `grsai_draw.py` entry

## Install / 安装

### pipx (recommended)

```bash
pipx install nbdraw
```

### pip

```bash
pip install nbdraw
```

## Quick Start / 快速开始

1. Copy example config to project root.
2. Set API key by file/env/CLI.
3. Run draw command.

```bash
cp examples/nbdraw.toml ./nbdraw.toml
nbdraw draw --prompt "professional flat vector architecture diagram"
```

Default outputs:

- `task_id`
- image `url`
- downloaded file `local_path` under `./outputs`

## Configuration / 配置

Default search order:

1. `--config <path>` if provided
2. `./nbdraw.toml`

Examples shipped in this repo:

- `examples/nbdraw.toml`

Example config:

```toml
[client]
base_url = "https://grsaiapi.com"
api_key = "sk-YOUR_API_KEY"

[draw]
model = "nano-banana-pro-vip"
aspect_ratio = "16:9"
image_size = "2K"

[poll]
interval = 5.0
max_wait = 300.0
heartbeat = 15.0
```

Environment variables:

- `GRSAI_API_KEY`
- `GRSAI_BASE_URL`

## CLI Examples / 命令示例

```bash
# Use prompt file
nbdraw draw --prompt-file prompt.md

# Use stdin
cat prompt.md | nbdraw draw --stdin

# Dry run payload only
nbdraw draw --prompt "test" --dry-run

# JSON output
nbdraw draw --prompt "test" --json

# Disable local download
nbdraw draw --prompt "test" --no-download
```

## Backward Compatibility / 向后兼容

Old command still works:

```bash
python grsai_draw.py --prompt "test"
```

It calls the new implementation and prints a deprecation notice.

## Development / 开发

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
ruff check .
pytest
python -m build
```

Or use conda:

```bash
conda activate nbdraw
pip install -e '.[dev]'
ruff check .
pytest
python -m build
```

## CI & Release

- CI: lint + tests + package build
- Release: push tag `v*` to trigger PyPI publish via GitHub Actions Trusted Publisher

## Migration Notes / 迁移说明

- Keep old options unchanged where possible.
- Recommended config:

```bash
cp examples/nbdraw.toml ./nbdraw.toml
```

- New options:
  - `--output-dir`
  - `--no-download`
  - `--json`

## License

MIT
