SuperPicky CLI (skill)

SuperPicky — bird photo AI culling (superpicky_cli.py, birdid_cli.py). This skill only covers CLI paths under $SKILL (directory containing this file).

Three entry modes (run.sh)

All user-facing commands go through ${SKILL}/scripts/run.sh (use the absolute path when cwd is not $SKILL). There are three entry modes (plus one helper):

Helper (not a separate “product” entry): --py PATH — run a script with the same venv. PATH may be absolute, or relative to .upstream/ (internally normalized to an absolute path before exec).

Absolute paths (required for agents / cron)

• - install.sh / run.sh / capture-cli-help.sh: when another tool invokes them, use the full absolute path (e.g. ${SKILL}/scripts/run.sh, never rely on cd + ./scripts/run.sh).
• run.sh internals: always exec Python with absolute paths for superpicky_cli.py, birdid_cli.py, ebird_region_query.py, and the --py script (relative args become ${SKILL}/.upstream/...).

Interactive (from $SKILL):

CODEBLOCK0

Automation (example):

CODEBLOCK1

Layout

$SKILL = skill root.

CODEBLOCK2

Reference (minimal)

Install

From $SKILL (or call ${SKILL}/scripts/install.sh by absolute path):

CODEBLOCK3

1. 1. Python 3.10–3.12 preferred; python -m venv must work.
2. $SKILL/.upstream/ + $SKILL/.upstream/.venv/.
3. Torch: macOS → base + PyPI torch; NVIDIA + nvidia-smi → requirements_cuda.txt; else requirements.txt or fallback.
4. verify_environment after pip unless --skip-verify / SKIP_VERIFY=1 — failures → [superpicky-cli verify] ERROR: and exit 1.

Entry details & examples

Wrapper meta-help: ${SKILL}/scripts/run.sh --help. SuperPicky top-level: ${SKILL}/scripts/run.sh -h.

CODEBLOCK4

ebird_region_query.py (entry 3) — --region-query

Resolves country codes (e.g. AU, CN) and region codes (e.g. AU-SA, CN-31) for --birdid-country, --birdid-region, birdid_cli -c/-r, and process --birdid-*.

• - Data: .upstream/birdid/data/ebird_regions.json (EN + name_cn) + codes from birdid/avonet_filter.py REGION_BOUNDS (inline # labels for entries not in JSON).
• Match: case-insensitive substring on code, English name, Chinese name; pinyin if optional pypinyin is installed in .venv (pip install pypinyin). Fuzzy: difflib ratio on tokens / whole fields; tune with --min-score (default 0.5).

CODEBLOCK5

Direct: "${SKILL}/.upstream/.venv/bin/python" "${SKILL}/scripts/ebird_region_query.py" -h
Tests: "${SKILL}/.upstream/.venv/bin/python" "${SKILL}/scripts/ebird_region_query_test.py"

Manual: source "${SKILL}/.upstream/.venv/bin/activate" && cd "${SKILL}/.upstream" && python "${SKILL}/.upstream/superpicky_cli.py" …

Refresh --help capture

CODEBLOCK6

Upstream-only install

CODEBLOCK7

Repo cwd = clone root. Models needed for real process / identify, not for -h. Pip quirks: reference/SOURCE.md.

superpicky_cli.py (entry 1)

Via skill: "${SKILL}/scripts/run.sh" … (no --birdid / --region-query prefix)
Subcommands: process | reset | restar | info | burst | identify
Flags: reference/cli-help-captured.txt

INLINECODE118: -s sharpness, -n TOPIQ, -c confidence, --flight/--no-flight, --burst/--no-burst, --xmp/--no-xmp, --no-organize, --no-cleanup, -q, -i / --auto-identify, --birdid-*, --keep-temp-files / --no-keep-temp-files, --cleanup-days, --save-crop.
reset / restar: -y; restar needs .superpicky/report.db.
burst: preview unless --execute.
identify: single image, --top, --write-exif, etc.

birdid_cli.py (entry 2)

Via skill: "${SKILL}/scripts/run.sh" --birdid …
Subcommands: identify | organize | reset | list-countries — details in cli-help-captured.txt (search birdid_cli).

Agent checklist

1. 1. Resolve $SKILL to an absolute directory; invoke "${SKILL}/scripts/run.sh" (and install.sh) by full path, not ./scripts/....
2. "${SKILL}/scripts/install.sh" if .upstream/.venv missing.
3. "${SKILL}/scripts/run.sh" --region-query … when the user gives a place name and you need an eBird -c / -r / --birdid-region code.
4. -y on destructive reset / restar / birdid organize|reset when appropriate.
5. Pipeline: process → optional restar; reset clears; restar needs report.db.
6. Star folder names: English + Chinese variants in upstream.