ImageSorcery 06 - MVP

Это серия постов от идеи ImageSorcery до 100+ звёзд на гитхабе и ~100 ежедневных установок с PyPi.

ImageSorcery 01 - Как я свой open source вайбкодил
ImageSorcery 02 - Превращение ImageWizard в ImageSorcery
ImageSorcery 03 - шаг за шагом: PoC, Initial commit
ImageSorcery 04 - README.MD
ImageSorcery 05 - автотесты; просто покажи ему пример

По результатам предыдущих приседаний с ИИ у нас на руках прототипы detect, crop и get_metainfo - функций на python, которые понадобятся ИИ агенту чтобы выполнить задачу вроде “вырежи здание на этом фото”. Также у нас уже есть git репозиторий с работающим MCP сервером подключенным в Cline. С полным покрытием одного единственного tool hello_world тестами формата e2e на pytest. И линтер rufus.

Приступаю к тулзам. По одной за шаг. С покрытием тестами и актуализацией README. От самой простой get_metainfo к самой сложной detect. Благо есть работающие реализации от PoC, которые нужны были как пример и подстраховка.

“Изучи @README.MD и следуй правилам работы с кодом от туда. Прочитай код hello_world tool и тесты на него. Прочитай код прототипа get_metainfo/crop/detect. Реализуй соответствующий tool. Напиши тесты. Актуализируй README. Не завершай задачу пока все тесты не пройдут, а также линтер.”

С реализацией проблем конечно уже не было, вот с тестами detect снова пришлось повозиться. Лентяй Gemini flash решил, что если detect tool запускается и возвращает хоть что-то - этого уже достаточно. Пришлось гонять его и в хвост и в гриву чтобы были написаны позитивные и негативные сценарии и прочие едж кейсы.

Каждый отдельный тул разумеется коммитил.

Где-то в процессе обнаружил что тесты на объявление tool могут быть также достаточно подробными. И самое главное - результаты crop (сохранение файла) оказывается есть в /tmp/pytest/.  Это означало что я могу проверять тесты, которые работают с изображениями, а не слепо доверять их коду и статусу passed. Это меня в будущем много раз выручит. Например, когда при реализации blur для теста генерировался полностью черный квадрат и после выполнения blur контрольный пиксель проверялся на соответствие цвета заблюренному черному - черному 🤦. С точки зрения алгоритма всё идеально - не прикопаешься 😅 А я глядя на два одинаковых черных квадрата ржал в голосину. Пришлось заставить его тестировать на шахматке.

Шаг выполнен ✅

Теперь у меня был MCP сервер, который позволял подключенному к нему MCP клиенту вроде Cline выполнить заветное “вырежи с этого фото собаку”. Был ведь? ...

В дев сборке всё работало. Но если я хотел публиковать это как MVP, мне нужно было убедиться, что те, кто найдут его на просторах гитхаба, смогут им воспользоваться. В будущем мне понадобится опубликовать пакет на pypi, но на данном этапе нужно было убедиться что хотя бы через клонирование репозитория всё заведётся.

Я удалил MCP из Cline, склонировал репу в новую директорию и попросил Cline доустановить, подключить и проверить. 

🫠 Разумеется ничего не заработало в этом моем стейдже.

Оказывается модели Ultralytics не качаются по неведомой мне причине, когда MCP запущен как процесс(?). Пока я писал прототипы, и запускал detect как отдельный python скрипт, а не как модуль в составе сервера, все нужные мне модели скачались и могли переиспользоваться в последующем. А чистая установка доступа к ним не имела и всё падало.

Такую нетривиальную проблему конечно же не смогли решить никакие ИИ, но день плотного дебага и глубоких обсуждений с Gemini и параллельно Claude (на всякий случай. По факту ничего такого, чего не знал Gemini он не сказал) привёл меня к реализации –post-installation режима и архитектурному решению с выделением отдельно от tools директории scripts, куда попали скрипты установки и скачивания моделей.

Теперь ImageSorcery была готова к публикации как MVP!

P.S. если кто-то знает как обойти проблему со скачиванием моделей в рантайме - дайте знать. Я бы очень хотел найти альтернативные решения.

ImageSorcery 05 - автотесты; просто покажи ему пример

Это серия постов от идеи ImageSorcery до 100+ звёзд на гитхабе и 100+ ежедневных установок с PyPI.

ImageSorcery 01 - Как я свой open source вайбкодил
ImageSorcery 02 - Превращение ImageWizard в ImageSorcery
ImageSorcery 03 - шаг за шагом: PoC, Initial commit
ImageSorcery 04 - README.MD

В прошлой серии мы поговорили про важность README для вайбкодинга. В этой не менее важная тема - автотесты. 

Не поленюсь ещё раз всем напомнить что я джун в python, а это значит что даже с самым качественным README я не могу на 100% утверждать что понимаю как работает проект написанный целиком ИИ. Из-за чего я не могу полностью доверять ИИ, когда он его меняет. Это приводит нас к выводу о необходимости автотестов. Не только как к способу повысить качество, надёжность и прочие пафосные метрики. А как к единственно возможному способу реализовать, а в дальнейшем развивать проект через вайбкодинг.

Вперёд вайбкодить автотесты!

Сказано - сделано. Cline + Gemini flash:

“Прочитай @README.MD для понимания проекта. Напиши автотест, который будут проверять наш единственный hello world tool.”

Тест на pytest готов ваншотом. Он passed 🎉! Казалось бы, пора открывать шампанское. Но как говорится: доверяй, но проверяй. На проверку это оказался юнит тест. Он конечно технически проверяет что функция написания в файле hello_world.py работает. Но он не проверяет, объявляет ли такой tool мой MCP сервер, возможно ли вызвать этот tool, вернёт ли он значение в ожидаемом MCP клиентом формате. 

Я совершил классическую для вайбкодера ошибку - поставил задачу не достаточно чётко.

Ок, откатываем все изменения (благо я с самого начала завёл git - обязательную вещь для вайбкодинга и обычной разработки) и промптим заново: 

“Прочитай @README.MD для понимания проекта. Напиши e2e автотест, который будут проверять наш единственный hello world tool подключаясь к этому MCP серверу как MCP клиент”

Я знал что ImageSorcery в своём зачаточном виде работает через stdio - стандартный протокол для MCP серверов работающих локально. Это значит что его можно запустить как подпроцесс и, отправив в него нужные данные, получить ответ.

Правда это не звучит как простая типовая задача? Вот и я так подумал. Вот и Gemini Flash так подумал. И облажался. И Pro облажался. И o3-mini. И Sonnet.

Ну мне не привыкать к тому как ИИ лажают. Взял дело в свои руки. И тоже облажался 🤦. Целый день я потратил в тщетных попытках отправить по stdio хоть что-то и получить хоть какой-то ответ. А разгадка одна - безблагодатность нужно звать батю. Благо такой батя в виде коллеги python senior software developer у меня имелся. Я пришёл к нему в слезах со словами что в попытках покрыть автотестами MCP сервер работающий по stdio что только не испробовал и на этом мои полномочия всё, закончились. Он, взглянув одним глазом на проект и ситуацию в целом сказал: “Просто покажи своей ИИшке пример MCP сервера покрытого автотестами. Таких что ли нет на GitHub? У нас в python фиг найдёшь задачу, которую до тебя ещё не решили и не обернули в удобную либу.”

А официальная документация тем временем имела ссылку на GitHub с официальными примерами. А в этих примерах используется либа FastMCP. Я скормил пример Cline - отличный результат ваншотом. Попросил переписать всю реализацию на FastMCP - так же ваншот, и тесты не упали. Попросил актуализировать в связи изменениями README. git commit.

Этот шаг готов ✅

Я уже точно не помню, но где-то в процессе (до или после тестов) добавил ещё и линтер ruff. Но это было так просто что я даже не запомнил где и как это случилось. Линтер нужен, чтобы держать код в едином стиле. Полезно для вайбкодинга и в целом.

Теперь я готов приступать к реализации MVP.

Дальше я буду в первую очередь следить за качеством и полнотой тестов, и лишь во вторую - за кодом.

Но это уже в следующий серии.

ImageSorcery 01 - Как я свой open source вайбкодил
ImageSorcery 02 - Превращение ImageWizard в ImageSorcery
ImageSorcery 03 - шаг за шагом: PoC, Initial commit
ImageSorcery 04 - README.MD

Это серия постов от идеи ImageSorcery до 100+ звёзд на гитхабе и 100+ ежедневных установок с PyPI.

В прошлой серии был готов PoC в виде набора python скриптов для определения объектов на изображении и обрезки изображения по координатам этих объектов. А так же initial commit репозитория с hello world MCP.

Как я уже говорил, я предпочитаю двигаться небольшими шагами - так проще и ИИ реализовать изменения и человеку их понять. А так же я говорил, что в python я джун и с пониманием проекта мне нужна была помощь. Поэтому следующим шагом я попросил Cline тщательно заполнить README.MD в котором подробно описать проект. Это описание понадобится в будущем не только мне, но и самому Cline  для реализации задач. 

Всем разработчикам, а особенно вайбкодерам настоятельно рекомендую держать README.MD актуальным и подробным, так как он позволяет легко вгрузиться в контекст и понять что где лежит, как делать типичные изменения, каким правилам следовать и т.п.

Многие инструменты имеют собственные аналогичные решения Rules у Cursor, CLAUDE.MD у Claude-code, GEMINI.MD у gemini-cli и т.п. Но я рекомендую использовать старый добрый README.MD или CONTRIBUTING.MD так как 

1. Это уже давно зарекомендовавший себя метод устоявшийся в нашей индустрии

2. К README.MD особое отношение у git-хостингов и прочих инструментов

3. Это универсальный документ, и используя его вы не обязываете других разработчиков использовать ваш ИИ инструмент.

Учитывая что ИИ инструменты платные и я изначально планировал делать этот проект open source, последний пункт для меня ключевой. Сейчас у меня во всех gemini.md, README.MD и т.п. просто одно правило "At the beggining of any task read README.MD"

Конечно ваншотом этот шаг не получился, так как я изначально не знал что именно мне нужно в README.MD видеть. Но как только в нём стало достаточно информации о проекте чтобы даже мне джуну он стал абсолютно понятен - и этот шаг был сделан. git commit.

А дальше я его постоянно дополнял, обновлял и развивал. Сейчас https://github.com/sunriseapps/imagesorcery-mcp/blob/master/README.md - самый проработанный README.MD из тех которые я когда-либо писал. Теперь это не просто инструмент получения контекста для разработчика или ИИ-агента, но и лицо проекта для всего интернета.

Со временем, когда проект разросся, от главного README.MD отпочковалось ещё несколько аналогичных документов.

• https://github.com/sunriseapps/imagesorcery-mcp/blob/master/CONFIG.md

• https://github.com/sunriseapps/imagesorcery-mcp/blob/master/src/imagesorcery_mcp/README.md

• https://github.com/sunriseapps/imagesorcery-mcp/blob/master/src/imagesorcery_mcp/prompts/README.md

• https://github.com/sunriseapps/imagesorcery-mcp/blob/master/src/imagesorcery_mcp/resources/README.md

• https://github.com/sunriseapps/imagesorcery-mcp/blob/master/src/imagesorcery_mcp/tools/README.md

• https://github.com/sunriseapps/imagesorcery-mcp/blob/master/src/imagesorcery_mcp/scripts/README.md

Их количество множится по мере развития проекта. Сейчас я подумываю о разделении их на README.MD и CONTRIBUTING.MD. Но пока что это просто мысли. Буду рад если в комментариях поделитесь своими на этот счёт.

ImageSorcery 01 - Как я свой open source вайбкодил
ImageSorcery 02 - Превращение ImageWizard в ImageSorcery
ImageSorcery 03 - шаг за шагом: PoC, Initial commit

Это серия постов от идеи ImageSorcery до 100+ звёзд на гитхабе и 100+ ежедневных установок с PyPI.

В прошлый серии мы с Gemini 2.0 flash определили стек: python, OpenCV, Ultralytics и никакого ImageMagic. 

Начал я как обычно с малого. В Cline попросил своего любимого бесплатного друга Gemini накидать скрипт на python который получает данные о размере (ширина, высота в пикселях) изображения. Дальше больше - скрипт crop который обрезает изображение по указанным аргументам. С последним пришлось повозиться и даже переключиться на Pro версию, благо она тоже бесплатная, пусть и с жёсткими лимитами.

PoC готов, можно приступать к реализации MVP.

Как вы помните, в python я тот ещё джун. Так что я не стал рисковать своим любимым бесплатным Gemini flash и даже pro, а сразу переключился в бесплатный браузерный Claude (лучший ии-кодер что тогда, что сейчас) и попросил дать мне подробнейшую инструкцию по разворачиванию проекта который будет имплементировать простейший hello world MCP сервер.

Нет смысла ваншотить такой проект за раз даже с Claude Opus 4.1. Что он не вывезет, что я не осилю осознать все нюансы за один заход. По этому предпочитаю действовать по комплиментарным шагам, на каждом из которых получать работающий продукт с небольшими изменениями, пока не получу финальный результат.

Написание инструкции - задача с нечётким ТЗ. Такую никогда нельзя пытаться делать ваншотом. Поэтому сперва получаю первую версию по максимально абстрактному промпту, но дав ей столько контекста сколько смог насобирать в интернете и своей голове. А затем по шагам вычитываю - прошу внести исправления - снова вычитываю - снова прошу исправить и так по кругу пока не получаю результат который я понимаю и к которому у меня нет претензий.

И так инструкция готова, закидываю её в Cline + Gemini flash и ... получаю ошибку активации. Вы же помните что в python я джун и понятия о venv не имею? Даю ему шанс исправить ошибку самостоятельно, но бесполезно - он не справляется. Откатываю всё назад, переключаю модель на Gemini Pro - результат тот же. Плюю на экономию, переключаю модель на Claude Sonnet - результат тот же, но оно сожрало 3 бакса 🤬

Плюю на этих бестолковых ИИ и беру дело в свои руки. Рано железякам нас ещё заменять!

Пол дня бесполезного рыскания по stack overflow и дебага, во время которого я случайно обнаружил, что venv активируется если git bash terminal открыт в отдельном окне, а не внутри VSCode. Оказывается эта шарманка будучи запущенной внутри IDE в пути C:\Users\titulus\work сочетание \t воспринимает как знак табуляции из-за чего пытается активировать venv в C:\Users    itulus\work 😵‍💫

Очевидного решения или даже упоминания этого бага я не обнаружил, так что просто уехал со всем своим проектом в WSL, благо VSCode отлично с ним работает. В Linux окружении, разумеется, таких проблем не возникло. Cline Gemini flash ваншотом по той самой инструкции от Claude создал MCP сервер, самостоятельно к нему подключился (вот за это я его обожаю) и проверил.

Я завёл git репозиторий и закоммитил initial commit. Первый шаг сделан ✅

ImageSorcery 01 - Как я свой open source вайбкодил
ImageSorcery 02 - Превращение ImageWizard в ImageSorcery

Это серия постов от идеи ImageSorcery до 100+ звёзд на гитхабе и 100+ ежедневных установок с PyPI.

В прошлый раз мы выяснили, что при правильной настройке бесплатных инструментов, бесплатная LLM Gemini может оказаться не хуже Claude в написании документации. И закончили на вопросе, почему никто раньше не привязал MCP к ImageMagic?

А вот почему

Первым делом после звонка с Системным Аналитиком я дал Cline в своём VSCode право на запуск команд в терминале. Затем взял первый попавшийся скриншот мобильного приложения и попросил вырезать NavBar используя ImageMagic. Gemini flash вырезал какую-то случайную часть экрана.

Я переключился на Gemini pro - результат тот же. o3 от OpenAI и Sonnet от Anthropic также облажались.

Долго думал. Я знал что все эти модели мультимодальные и наверняка знают что такое NavBar. Тут явно что-то не сходилось. Я полез раскрывать свёрнутые секции их размышлений и обнаружил что: 

1. Все они понимают, что изображено и “видят” NavBar. 

2. Никто из них не способен вычислить точные координаты этого NavBar.

3. Они даже размеров изображения не знают. 

Из-за чего все они действовали наугад.

Оказывается LLM не умеют определять точные координаты объектов, которые они видят, не говоря уже про их точную геометрию.

В этом и крылся ответ на вопрос “а чего раньше это никто не сделал?”. 

С этой дилеммой я пошёл к Gemini. Сокращённая переписка:

👤: какой аналог npmjs.com для питона?
🤖: PyPi

👤: у него сайт есть?
🤖: pypi.org

👤: порекомендуй мне 5 - 10 пакетов для распознавания изображений на python моя задача - определять координаты объектов для будущего crop
ИИ: Pillow, OpenCV, scikit-image, TensorFlow Object Detection API, Detectron2, YOLO, Tesseract OCR, SimpleCV, imutils. Рекомендации:
1) Начните с OpenCV или scikit-image.
2) Если вам нужна более высокая точность или нужно распознавать определенные типы объектов, рассмотрите TensorFlow Object Detection API, Detectron2 или YOLO.
3) Используйте Pillow для загрузки, сохранения и предварительной обработки изображений.
4) Используйте imutils для упрощения работы с OpenCV.
5) Если вам нужно распознавать текст, используйте Tesseract OCR.

👤: расскажи подробней про opencv imutils pytorch и yolo
🤖:
- OpenCV - это фундаментальная библиотека для компьютерного зрения, предоставляющая широкий спектр алгоритмов для обработки изображений и обнаружения объектов.
- imutils - это набор удобных функций, которые упрощают работу с OpenCV.
- PyTorch - это мощный фреймворк машинного обучения, который можно использовать для построения и обучения сложных моделей обнаружения объектов.
- YOLO - это семейство алгоритмов обнаружения объектов в реальном времени, известных своей скоростью и точностью.

👤: важный момент. я не хочу обучать модели сам. мне нужен готовый инструмент
🤖: Начните с OpenCV + YOLO от Ultralytics

Как можно заметить, я не силён в python от слова совсем 😅. Но я выбрал его, потому что осведомлён о его большой экосистеме инструментов ML в общем и компьютерного зрения в частности. 

И так стек найден. И с удивлением для меня, места для ImageMagic в нём не нашлось, ведь все необходимые инструменты для обработки уже есть в OpenCV.

А что стало с названием ImageWizard?

Тут всё банально. Я погуглил - это название уже занято приложением в сфере обработки изображений с ИИ 🤷. Пришлось найти незанятое. Но постарался оставить отсылку на ImageMagic

ImageSorcery 01 - Как я свой open source вайбкодил

Скажу честно, я хотел написать статью, для того чтобы рассказать о своём проекте ImageSorcery MCP. Но не хотелось писать рекламный BS о том какой он крутой. Хотелось сделать месседж более личным и искренним. Так статья превратилась в серию постов-заметок о всех тех граблях инструментах и практиках, которые мне удалось попробовать на пути от идеи до 100+ звёзд на гитхабе и ~100 ежедневных установок с pypi. А так как я фанатик экономии, весь стек в основном бесплатный (включая LLM) и часто не самый популярный.

В компании где я работаю, у меня сложилась репутация, как это принято сейчас говорить, ИИ-энтузиаста. Из-за чего ко мне однажды обратилась Системный Аналитик, которая только начала внедрять RooCode и столкнулась с какой-то проблемой полнейшего тупняка ИИ. Бесплатная веб версия Claude на раз два превращала Верхнеуровневые Бизнес Требования заказчика в детально проработанное Техническое Задание. Но копировать туда-сюда - не продуктивно, а ещё лимиты эти… Решилась она попробовать рекомендованный мною RooCode с Gemini flash. Установила впервые IDE VSCode, запустила и поставила плагин RooCode, подключила Gemini модель и попыталась скормить ему ту же задачу, но в ответ получила какой-то откровенный бред. Вместе мы выяснили, что для адекватной работы RooCode (а ещё его предшественника Cline и, скорее всего, последователя Kilo Code) требуется не просто запустить VSCode, но ещё и создать в нём проект с соответствующей директорий где-то в системе. А если ещё и все материалы сложить в эту директорию - их можно не копипастить и даже не драгндропать, а меньшонить через @ что намного удобней. (Даже мне стало плохо от обилия англицизмов в этом предложении, извините). Кроме того, выяснилось, что промпт содержал помимо текста ещё ссылку на Figma дизайн. А RooCode, несмотря на то что может используя браузер, какую-то осмысленную деятельность с этой ссылкой вести. При наличии у него Figma MCP справляется гораздо эффективнее.

И теперь бесплатный Gemini flash под капотом RooCode засиял во всей красе. Промпты стали проще и читаемей. И благодаря доступу ко всем необходимым файлам (ВБТ и шаблон) и инструментам, RooCode ваншотом не просто создал качественное ТЗ в формате markdown (привет markdown preview плагин), но ещё и наполнил его нужными скриншотами прямо в теле документа, чего Claude не мог. 

Вот только осталась одна проблема: он использовал скриншоты целых экранов, и не смог их порезать на кусочки для документирования соответствующих секций: шапка, меню т.п.

Фигня война! - сказал я, — наверняка есть MCP который это делает. 

Погуглив вместе минут 15 мы обнаружили, что такого нет. Но так как нарезка экранов на скриншоты - привычная для системного аналитика задача, она поблагодарила меня за получившийся результат и убежала на другой звонок. А я остался сидеть глядя в пустой монитор с непониманием, почему такая простая и очевидная задача ещё не решена.

Так появилась идея ImageWizard - взять ImageMagic и прикрутить к нему MCP протокол.

А почему сейчас проект и называется иначе и никакой связи с ImageMagic не имеет, расскажу в следующей серии.

• Репозиторий: https://github.com/sunriseapps/imagesorcery-mcp

• Сайт: imagesorcery.net