plain-sight

Версия: 1.0.0

ИИ описывает то, что видит. Генеративный описатель изображений — MCP-сервер + CLI-обёртка вокруг Florence-2 (MIT) для прозаических описаний, OCR и sidecar-файлов подписей для LoRA-датасетов. Работает локально, детерминирован по умолчанию.

Родственный инструмент для ai-eyes-mcp:

Контракт честности

Описания генеративны: беглые, обычно точные и способны выдумывать детали. plain-sight делает вывод воспроизводимым (детерминированное декодирование — одно и то же изображение даёт одну и ту же подпись), но не гарантированно истинным. Для проверки конкретного утверждения об изображении используйте image_verify из ai-eyes-mcp — он измеряет, а не рассказывает. Эти два инструмента относятся к разным семействам моделей по замыслу, поэтому один может проверять другой.

Related MCP server: fm-mcp-comfyui-bridge

Инструменты (MCP)

Быстрый старт

pip install -e .
plain-sight-mcp   # starts the STDIO MCP server

Или запуск как модуль: python -m plain_sight

CLI

# One image, full paragraph
plain-sight describe hero.png

# One short sentence
plain-sight describe hero.png --detail low

# OCR
plain-sight ocr screenshot.png

# The dataset lane: caption a directory into .txt sidecars with a trigger token
plain-sight batch ./dataset --prefix "mcpt_style, " --detail high

# Re-runs are idempotent — existing sidecars are skipped unless you --overwrite
plain-sight batch ./dataset --prefix "mcpt_style, " --overwrite

Конфигурация Claude Code

{
  "mcpServers": {
    "plain-sight": {
      "command": "plain-sight-mcp",
      "env": {
        "PLAIN_SIGHT_MODEL_DIR": "/path/to/model/cache"
      }
    }
  }
}

Контракт подписей (трек датасетов)

Создан для наборов обучения LoRA (style-dataset-lab и другие):

• Точное сопоставление по имени файла: img_0042.png → img_0042.txt. Без числового суффикса — в отличие от узла SaveText в ComfyUI, который добавляет _00001.

• Простая конкатенация: sidecar-файл содержит prefix + caption + suffix без вставленного разделителя. Хотите "mcpt_style, <подпись>"? Поместите запятую с пробелом в префикс.

• Идемпотентные повторные запуски: существующие sidecar-файлы пропускаются (и ничего не стоят), если не указан --overwrite / overwrite=true.

• Детерминированность: do_sample=false + лучевой поиск — повторное создание подписи для неизменённого изображения воспроизводит тот же текст, поэтому различия имеют смысл.

Уровни детализации

Собственная лестница задач Florence-2:

high — это абзац, а не эссе — Florence-2 — компактная модель (0,77B). Её преимущество — пропускная способность и лицензия, а не глубина художественной критики. Если подпись выглядит обрезанной, увеличьте max_new_tokens (по умолчанию 1024, максимум 4096).

Конфигурация

Логирование: только stderr (stdout — канал протокола MCP), имя логгера plain_sight.

Первый вызов: модель загружается лениво — первый вызов describe/OCR загружает Florence-2 (~10–20 с на GPU; первый вызов вообще скачивает ~1,5 ГБ). Последующие вызовы — ~1–2 с на изображение при детализации high на современном GPU.

Лицензионная позиция

• Этот инструмент: MIT.

• Модель: закреплена за florence-community/Florence-2-large — официальная конверсия native-transformers релиза Microsoft Florence-2. MIT (тег лицензии на хабе проверен 2026-08-19). Коммерческое использование чистое.

• Почему не microsoft/Florence-2-large? Те же веса, та же лицензия MIT, но оригинальные репозитории поставляются с конфигами pre-native, которые загружаются только через trust_remote_code — а этот инструмент отказывается от этого по принципиальным соображениям. Конвертация сообщества загружается встроенными классами Florence-2 из transformers.

• Сознательно не предлагается: зоопарк дообученных версий Florence-2 (MiaoshouAI PromptGen, CogFlorence, SD3/Flux captioners, Castollux). Их лицензии не проверены; они не включаются, пока не будут подтверждены. Переопределение PLAIN_SIGHT_MODEL_ID на одну из них возможно, но вопрос лицензии ложится на вас.

• Без удалённого кода: движок использует только нативную поддержку Florence-2 в transformers — trust_remote_code никогда не передаётся, поэтому никакой Python-код, полученный с хаба, никогда не выполняется. Для этого требуется transformers >= 4.51.

Безопасность и доверие

Этот инструмент работает только локально.

• Обрабатываемые данные: локальные файлы изображений (только чтение); кэш моделей HuggingFace (записывается один раз при первом скачивании); sidecar-файлы подписей .txt — ЕДИНСТВЕННЫЕ файлы, которые он записывает, и только туда, куда попросил вызывающий (out_dir или рядом с изображением), а существующие sidecar-файлы заменяются только при явном --overwrite.

• Нет исходящего сетевого трафика во время выполнения — модель скачивается один раз при первом использовании, затем весь вывод происходит локально.

• Нет выполнения удалённого кода — только нативные классы transformers; trust_remote_code никогда не передаётся, поэтому никакой Python-код, полученный с хаба, никогда не выполняется.

• Нет обработки секретов, нет телеметрии — ничего не читается и никуда не отправляется.

• Только структурированные ошибки — сырые трассировки стека никогда не попадают к MCP-клиентам или пользователям CLI. Коды выхода CLI: 0 — успех · 1 — ошибка пользователя · 2 — ошибка выполнения · 3 — частичный успех.

Полная политика: SECURITY.md. Активно поддерживается; поддерживаемые версии перечислены там.

Требования

• Python >= 3.10

• transformers >= 4.51 (нативная поддержка Florence-2)

• Рекомендуется GPU CUDA (~2 ГБ VRAM при FP16); запасной вариант на CPU работает (медленнее)

• Модель скачивается ~1,5 ГБ при первом использовании

Разработка

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# CI-safe tests (no model, no GPU)
pytest tests/test_edge_cases.py -v

# Dogfood tests (real model + GPU)
pytest tests/test_dogfood.py -v

# Full verify: imports, edge tests, build
bash verify.sh

Архитектура

engine.py    Standalone Florence-2 wrapper — no MCP dependency.
             Lazy-loads the model; validation runs BEFORE the load.
             Importable directly: from plain_sight.engine import Florence2Engine

sidecars.py  The training-data contract, pure stdlib: basename pairing,
             bare concatenation, directory expansion. Testable without torch.

server.py    FastMCP wrapper exposing engine methods as MCP tools.
             Thin layer: validation, error shaping, tool metadata.

cli.py       argparse CLI over the same engine (describe / ocr / batch /
             status / selftest). Structured errors, meaningful exit codes.

Архитектура сознательно заимствована из ai-eyes-mcp — то же разделение движок/сервер, та же форма ошибок, тот же паттерн selftest. Облачный аналог того же контракта работает на Comfy Cloud как workflow caption-florence2-v1 (метаданные одного изображения на задачу; этот инструмент — массовый трек).

Лицензия

MIT

Создано MCP Tool Shop