Kururi AI CLI

Image rotation classifier with a ViT model. The CLI runs on CPU, CUDA, or Apple MPS, auto-downloads the checkpoint from a GitHub Release, and supports single-file or recursive directory processing.

Features

• Auto checkpoint download on first run (URL/sha256 configurable via args or env).
• Single image prediction or recursive directory batch processing.
• Optional saving of rotation-corrected images.
• Pure-Python CLI (no comments, typed, minimal dependencies).

Requirements

• Python 3.12.9
• PyTorch, TorchVision, timm, Pillow (installed via uv pip install -e cli)

Setup

git clone https://github.com/kandotrun/kururi-ai.git
cd kururi-ai
uv venv .venv
source .venv/bin/activate
uv pip install -e cli

Model download

• If models/kururi-orient-v1.pth is missing, the CLI downloads it from the configured URL.
• Set URL and hash via args or environment variables:

export KURURI_MODEL_URL="https://github.com/<owner>/<repo>/releases/download/v0.1.0/kururi-orient-v1.pth"
export KURURI_MODEL_SHA256="<sha256sum>"
# optional
export KURURI_MODEL_TIMEOUT=1800

• Default URL is a placeholder: https://github.com/OWNER/REPO/releases/download/v0.1.0/kururi-orient-v1.pth. Replace it after publishing your Release.

Usage

Single image:

uv run python cli/main.py predict \
  --image /path/to/image.jpg \
  --device cpu \
  --model-name vit_large_patch16_224 \
  --save-rotated /path/to/fixed.jpg

Recursive directory:

uv run python cli/main.py predict \
  --dir /path/to/images \
  --save-rotated-dir outputs \
  --device cpu \
  --model-name vit_large_patch16_224

Supported extensions: jpg, jpeg, png, bmp, tif, tiff, webp.

Try with bundled samples (recursive):

uv run python cli/main.py predict \
  --dir samples \
  --save-rotated-dir samples_out \
  --device cpu

Sample inputs and corrected outputs (thumbnails):

#	Input	Corrected output
1
2
3
4
5

Checkpoint options

• --checkpoint path (default models/kururi-orient-v1.pth)
• --checkpoint-url override download URL
• --checkpoint-sha256 integrity check
• --download-timeout seconds (default 1800 or KURURI_MODEL_TIMEOUT)

Publish the model to GitHub Release

1. Compute hash: shasum -a 256 models/kururi-orient-v1.pth
2. Create a Release and upload kururi-orient-v1.pth as an asset.
3. Update README, env examples, and default URL in code/CI with the Release URL and sha256.

License

• Code and packaged model are released under the MIT License. See LICENSE.
• Original model by Yuki Arano (新野ユキ)
  • Twitter: https://x.com/yuki_arano
  • GitHub: https://github.com/ObuchiYuki
  • Original post: https://x.com/yuki_arano/status/1788051297108902073
  • iOS app: https://apps.apple.com/jp/app/ai%E3%81%8C%E5%86%99%E7%9C%9F%E3%81%AE%E5%90%91%E3%81%8D%E3%82%92%E4%BF%AE%E6%AD%A3-%E3%81%8F%E3%82%8B%E3%82%8Aai/id6480589907

Japanese documentation

See README.ja.md for the Japanese version.