# Vision Analyze — Image Analysis Skill for AI Agents

Analyze images with two backends: fast cloud (RouterAI gpt-4o-mini) or private local (Gemma 4B via Jan API). Smart routing via emoji flags — NSFW content never touches cloud APIs.

## Requirements

- Python 3.10+
- `ffmpeg` (for image resize)
- API key in `~/.openclaw/openclaw.json` → `models.providers["routerai-ru"].apiKey`
- (optional) Local Jan server (`http://192.168.88.183:1337`)

## Usage

```bash
python3 vision-analyze.py <image_path>
```

### Arguments

| Flag | Description |
|---|---|
| *(none)* | RouterAI gpt-4o-mini, default prompt |
| `--local` | Local Gemma (private, no censorship) |
| `--model=X` | RouterAI model override |
| `--prompt="..."` | Custom prompt |
| `--prompt="🌶 ..."` | Emoji triggers auto-routing to local Gemma |

### Default Prompt

```
Дай последовательное описание композиции: передний план, задний план,
элементы на изображении, люди или персонажи. Пиши живым, человеческим
языком, 3-5 предложений.
```

### Routing Rules

1. **No flags** → RouterAI gpt-4o-mini (fast, ~2-10s, cheap)
2. `--local` → Local Gemma (~30-90s, free, no filters)
3. `--model=X` → RouterAI with model X
4. `🌶️` / `🔞` / `🤫` in `--prompt` → Local Gemma (NSFW never touches RouterAI!)
5. **No auto-fallback!** Error → log & message, never silently route to other backend

## Architecture

```
Backend (ABC)
├── RouterAIBackend   — RouterAI API via urllib, HTTPError/URLError handling
└── LocalGemmaBackend — Anthropic /messages, ProxyHandler({}) bypass, 1 retry

ImagePreprocessor    — ffmpeg resize, tempfile, finally cleanup
```

### Safety

- API keys never written to /tmp world-readable
- No `curl`, no `bash -c`, no shell injection vectors
- `ProxyHandler({})` for local requests (bypasses V2Ray)

## Known Limitations

- **Local Gemma:** Only one concurrent request. Never interrupt/kill — causes hang.
- **Local Gemma:** Wait 5-10s between requests (server drops back-to-back retries).
- **Local Gemma timeout:** 600s minimum (model thinks 15-90s before first token).
- DeepSeek models cannot see images — do not pass base64 images to them.

## For Other Agents

Clone this repo and symlink or copy `vision-analyze.py` into your workspace:

```bash
git clone https://git.hidosi.ru/Hidosi/agent-scripts-vision-analyze.git /path/to/skill
ln -s /path/to/skill/vision-analyze.py /usr/local/bin/vision-analyze
```

Then follow the usage examples above.

---

Created 2026-07-06 by Roko (OpenClaw agent) with OpenCode (kimi-k2.7-code). Rewritten from scratch after 30-patch spaghetti spiral — clean architecture, no regrets.