renga_ai

Библиотека для автоматизации Renga через COM с использованием comtypes.

Для публикации и репозитория проект называется renga_ai, при этом текущий Python-пакет и публичный import-путь сохраняются как renga_api.

Проект состоит из двух разных рабочих направлений, которые не стоит смешивать:

• Renga API — COM-автоматизация приложения, проекта, модели, объектов, параметров и introspection.
• Renga STDL — шаблоны категорий и стилей Renga, .json/.lua/.rst, примеры SDK и локальный RstBuilder.

Основной Python-пакет проекта — renga_api.

• renga_api.core — low-level и core API для прямой работы с COM.
• renga_api.skills — agent-facing слой с функциями, которые удобно вызывать из ИИ-агента.
• renga_api на верхнем уровне напрямую реэкспортирует agent-facing API.

Документация

• README.md — обзор проекта, архитектуры, правил работы и текущего рабочего процесса.
• AGENTS.md — постоянные указания агентам для этого репозитория.
• TODO.md — рабочий журнал задач и текущего состояния.
• RengaAPI_Docs/ — локальная Markdown-версия документации Renga COM API.
• RengaSTDL_Docs/ — локальная Markdown-версия документации Renga STDL, примеры SDK и RstBuilder.

Что уже есть в проекте

• Функциональный API для подключения к Renga и работы с проектом и моделью.
• Управление локальными процессами Renga для устранения неоднозначности между несколькими COM-экземплярами.
• Reflection по RengaCOMAPI.tlb для поиска интерфейсов и анализа сигнатур.
• Probe и глубокий JSON-дамп COM-объектов.
• Agent-facing каталог функций для вызова из LLM-инструментов.
• Базовые операции над моделью: уровни, стены, выборка объектов, удаление по id.
• Демонстрационные text-skills для построения слов стенами.
• Базовые обёртки для STDL: импорт категории и создание style из category.

Структура проекта

renga_ai/
├── AGENTS.md                    # проектные правила для агентов и постоянные рабочие соглашения
├── AGENT_EXAMPLE.md             # минимальный пример прямого использования `renga_api`
├── README.md                    # основная документация по проекту, архитектуре и рабочему процессу
├── TODO.md                      # единый журнал задач, статусов и важных итогов
├── pyproject.toml               # метаданные пакета, зависимости и настройки инструментов
├── tlb/                         # локальная копия `RengaCOMAPI.tlb` для reflection и генерации типов
├── tests/                       # unit-тесты для skills, process helpers и геометрии demo-алгоритмов
├── RengaAPI_Docs/               # локальная документация по Renga COM API
├── RengaSTDL_Docs/              # локальная документация по Renga STDL и материалы SDK
└── renga_api/                   # основной Python-пакет проекта
    ├── catalogs.py              # общие каталоги GUID, quantity и других стабильных справочников API
    ├── core/                    # COM-core и low-level helpers, не зависящие от агентного сценария
    └── skills/                  # agent-facing wrappers поверх core-функций

Примечание по дампам:

• каталог dumps/ не хранится в репозитории как постоянная часть дерева;
• он создаётся по месту работы при вызове dump_to_file(...);
• это нормальный рабочий артефакт для исследования, а не часть пакета.

Чёткое разделение: Renga API и Renga STDL

Renga API

Это COM-автоматизация Renga из Python.

Сюда относятся:

• подключение к приложению;
• открытие и сохранение проекта;
• доступ к модели и объектам;
• создание и удаление объектов;
• чтение параметров и свойств;
• probe интерфейсов;
• dump объектов и геометрии;
• reflection по RengaCOMAPI.tlb.

Основные источники:

• renga_api/core/*
• renga_api/skills/*
• RengaAPI_Docs/
• tlb/RengaCOMAPI.tlb

Renga STDL

Это отдельный слой работы с шаблонами категорий и стилей Renga.

Сюда относятся:

• .json и .lua шаблоны;
• сборка .rst через RstBuilder.exe;
• ручной импорт категории в Renga;
• создание style на основе category;
• проверка фактического поведения шаблона внутри Renga;
• отладка через AecApp.log.

Основные источники:

• RengaSTDL_Docs/README.md
• RengaSTDL_Docs/MODULAR/*
• RengaSTDL_Docs/Samples/*
• RengaSTDL_Docs/RstBuilder/RstBuilder.exe

Важно:

• Renga STDL не равен Renga API;
• успешная сборка .rst не доказывает корректность геометрии;
• часть ошибок STDL проявляется только во время исполнения Lua внутри Renga;
• при проблемах с шаблоном сначала нужен runtime-лог, а не подбор геометрии вслепую.
• параметр executable_lua в документации и CLI RstBuilder.exe в этом проекте нужно понимать как путь к исполняемому .lua-скрипту шаблона, а не как путь к lua.exe; по названию параметра это легко понять неправильно.

Примечание по RstBuilder.exe:

• корректный вызов на практике выглядит так: RstBuilder.exe configuration.json run.lua -s 1.0 -o category.rst;
• то есть вторым позиционным аргументом передаётся файл Lua-скрипта шаблона;
• отдельный путь к lua.exe для этого сценария не требуется.

Текущий подтверждённый путь к логу:

C:\Users\user\AppData\Local\Renga Software\Renga Professional\AecApp.log

Почему dump - это ключевой инструмент

Для этого проекта dump_object(...) и dump_selected_object(...) - это основные инструменты исследования Renga API.

Dump нужен для того, чтобы:

• увидеть, какие интерфейсы реально поддерживает конкретный COM-объект;
• не гадать по названиям интерфейсов и свойств;
• получить реальные параметры, свойства и их значения;
• понять, какие методы безопасно вызываются на чтение;
• увидеть geometry-related интерфейсы;
• сопоставить живой объект из модели с тем, что описано в RengaAPI_Docs/.

Рекомендуемый порядок исследования неизвестного объекта:

1. Получить объект через существующие agent-facing функции.
2. Выполнить dump_object(...) или dump_selected_object().
3. Сохранить результат через renga_api.core.dump_to_file(...), если нужен артефакт для анализа.
4. Посмотреть interface_summary, interfaces, parameters, properties, geometry.
5. Найти интересующие интерфейсы и члены в RengaAPI_Docs/ и RengaCOMAPI.tlb.
6. Только после этого менять код или добавлять новый skill.

Пример:

from renga_api import dump_selected_object
from renga_api.core import dump_to_file

payload = dump_selected_object()
if payload is not None:
    path = dump_to_file(payload, prefix="selected")
    print(path)

Установка

pip install -e .

Для разработки:

pip install -e ".[dev]"

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

Подключение к уже открытой Renga

from renga_api import list_renga_processes, open_renga

print(list_renga_processes())
print(open_renga(mode="active"))

Создание новой модели и стены

from renga_api import create_level, create_model, create_wall, find_base_level, open_renga

open_renga(mode="new", visible=True)
create_model()

level = create_level(name="Level 0")
level_id = level["level_id"] if level else find_base_level()
result = create_wall(level_id=level_id, end_x=6000.0, thickness=200.0, height=3000.0)
print(result)

Построение слова из стен

from renga_api import create_word_from_walls, find_base_level, open_renga

open_renga(mode="active")
level_id = find_base_level()
result = create_word_from_walls("СЛОВО", level_id=level_id)
print(result)

Просмотр каталога доступных skills

from renga_api import get_skills_catalog

for skill in get_skills_catalog():
    print(skill["module"], skill["name"])
    print(skill["description"])

Возможные проблемы при запуске через командную строку

При вызове python -c "..." из shell-инструментов может наблюдаться отсутствие вывода print(). Возможные причины:

• Буферизация stdout — Python буферизует вывод, и он не попадает в stdout до завершения процесса. Флаг -u (unbuffered mode) решает эту проблему.
• Длинные многострочные команды — при передаче длинных скриптов с переносами, f-strings и экранированием кавычек через cmd.exe /c возможны проблемы с парсингом.

Это не универсальная проблема: в некоторых окружениях всё работает корректно. Если столкнулся с отсутствием вывода, попробуй:

python -u -c "from renga_api import open_renga, get_object_ids_by_category; open_renga(mode='active'); print(get_object_ids_by_category('wall'))"

Основные модули

renga_api.core.app

Подключение к приложению, проекту, модели и текущему выделению. Здесь же лежат low-level операции открытия, сохранения и закрытия приложения.

renga_api.core.process

Перечисление и завершение локальных процессов Renga. Это важно, когда в системе открыто несколько экземпляров и GetActiveObject(...) становится неоднозначным.

renga_api.core.typelib

Загрузка RengaCOMAPI.tlb, генерация COM-типов и построение реестра интерфейсов и членов интерфейсов. Это основной reflection-слой проекта.

renga_api.core.probe

Безопасная проверка поддерживаемых интерфейсов, чтение свойств и вызов методов без падения на COM-ошибках при исследовании.

renga_api.core.dump

Главный introspection-модуль проекта. Он строит JSON-совместимую структуру по живому COM-объекту, включая:

• базовые идентификаторы объекта;
• summary поддерживаемых интерфейсов;
• свойства интерфейсов;
• безопасно вызываемые методы чтения;
• параметры;
• свойства;
• geometry-related данные;
• попытку вытащить экспортированную 3D-геометрию.

renga_api.core.model

Low-level helpers для операций над моделью, транзакций и создания объектов. Все изменения модели должны идти через operation/transaction-подход.

renga_api.catalogs

Модуль общих каталогов и справочников проекта. Сюда следует выносить стабильные реестры GUID, quantity, entity type и другие подобные данные, если они используются несколькими skills или являются частью внешнего API Renga.

Важно:

• не держать такие каталоги внутри отдельных skills/*, если это не одноразовая локальная константа;
• подробно комментировать происхождение и назначение каталога прямо в модуле;
• использовать каталоги как список кандидатов для runtime-проверки, если COM-интерфейс не умеет перечислять значения напрямую.

renga_api.skills.*

Agent-facing wrappers поверх core-функций. Это основной интерфейс, через который агент должен вызывать операции в пользовательском сценарии.

Подробные инструкции для агента

Базовое правило работы

В агентном сценарии взаимодействие с Renga должно идти через:

• renga_api
• или renga_api.skills/*

Агент не должен использовать renga_api.core/* как основной интерфейс сценария, если соответствующая agent-facing функция уже существует.

Базовый алгоритм выбора действия

1. Вызвать get_skills_catalog().
2. Найти подходящую функцию по имени и описанию.
3. Импортировать и вызвать нужную функцию напрямую из renga_api.
4. Если нужной функции нет, сначала исследовать API через dump и документацию, а уже потом расширять библиотеку.

Как агенту исследовать неизвестную возможность Renga API

1. Поднять или подключить Renga через agent-facing lifecycle-функции:
   • list_renga_processes()
   • open_renga(...)
   • create_model() или open_model(...)
2. Получить интересующий объект существующими skills.
3. Выполнить dump_object(...) или dump_selected_object().
4. Подтвердить увиденные интерфейсы и сигнатуры по RengaAPI_Docs/.
5. При необходимости написать небольшой исследовательский Python-скрипт, который вызывает renga_api и воспроизводит сценарий.
6. Зафиксировать наблюдения в коде, тесте или TODO.md, если они важны для будущей разработки.

Как агенту работать со STDL

1. Найти ближайший пример в RengaSTDL_Docs/Samples/.
2. Подготовить или изменить .json и .lua.
3. Собрать .rst через RstBuilder.exe.
4. Импортировать .rst в Renga вручную.
5. Создать style на основе category.
6. Проверить фактическое поведение шаблона в Renga.
7. При ошибке смотреть AecApp.log и использовать print() в Lua для диагностики.

Уточнение по сборке:

• не интерпретировать аргумент executable_lua как путь к lua.exe;
• в рабочем сценарии SDK это путь к основному .lua-файлу шаблона, который передаётся RstBuilder.exe вторым аргументом.

Важно:

• agent-facing wrapper import_stdl_category(...) уже существует, но текущий live-сценарий импорта через COM не считается подтверждённым end-to-end;
• для STDL основной источник правды при ошибках — runtime-лог, а не только факт успешной сборки .rst.

Рекомендуемый pipeline для дополнения библиотеки

Ниже описан практический pipeline для добавления новой возможности в библиотеку.

1. Сформулировать цель

Чётко определить, что именно нужно получить:

• новый read-only introspection helper;
• новую операцию над моделью;
• новый STDL workflow helper;
• одноразовый исследовательский скрипт;
• полноценный новый skill для агента.

2. Изучить документацию

Если задача про COM API:

• искать интерфейсы, параметры и типы в RengaAPI_Docs/;
• при необходимости смотреть RengaCOMAPI.tlb через renga_api.core.typelib.

Если задача про STDL:

• начинать с RengaSTDL_Docs/;
• затем брать ближайший пример из RengaSTDL_Docs/Samples/.

3. Открыть Renga и подготовить среду

Для agent-facing сценария использовать существующие функции:

• list_renga_processes() — понять, сколько экземпляров Renga уже запущено;
• close_renga_process(...) или close_all_renga_processes() — убрать лишние процессы, если нужен однозначный active-instance;
• open_renga(mode="active" | "new") — подключиться или открыть новый экземпляр;
• create_model() или open_model(...) — создать или открыть проект;
• save_model(...) — сохранить результат проверки.

4. Получить живой объект и снять dump

Нужно не угадывать API по памяти, а работать от живого объекта:

1. создать или найти объект;
2. выполнить dump_object(...) или dump_selected_object();
3. при необходимости сохранить дамп в файл;
4. посмотреть реальные интерфейсы, параметры и свойства;
5. только после этого писать код.

5. Написать и запустить исследовательский скрипт

Если задача ещё не оформлена в skill:

• можно создать небольшой одноразовый Python-скрипт, который импортирует функции из renga_api;
• скрипт должен воспроизводить минимальный сценарий и печатать диагностический результат;
• такой скрипт нужен для быстрой проверки гипотезы, а не как постоянная архитектурная надстройка.

Практически это обычно выглядит так:

1. открыть Renga;
2. создать или открыть проект;
3. получить объект;
4. вывести dump, значения параметров, LastError, идентификаторы или результат операции;
5. проверить поведение в интерфейсе Renga.

6. Добавить логирование и диагностику

Для Python-части полезно логировать:

• входные параметры операции;
• идентификаторы объектов;
• коды возврата COM-вызовов;
• LastError, если операция вернула None или код ошибки;
• путь к сохранённому дампу.

Для STDL-части полезно логировать:

• print() в Lua;
• сообщения из AecApp.log;
• факт успешной сборки .rst;
• факт появления category/style в самом Renga.

7. Проверить результат

Проверка должна быть фактической, а не только по отсутствию исключения.

Для COM API это обычно значит:

• убедиться, что объект действительно создан или изменён;
• перечитать объект;
• повторно посмотреть свойства или dump;
• при необходимости визуально проверить модель в Renga.

Для STDL это обычно значит:

• убедиться, что category импортировалась;
• создать style;
• реально проверить геометрию в Renga;
• при ошибке вернуться к логу и примеру.

8. Оформить результат в коде

Дальше нужно решить, во что превращается найденное решение.

Если это reusable low-level логика:

• добавить helper в renga_api.core.

Если это reusable каталог констант, GUID или справочников:

• добавить его в renga_api.catalogs;
• не зашивать такие каталоги внутрь конкретного skill-модуля без необходимости;
• сопроводить каталог подробным комментарием о том, почему он существует и как должен использоваться.

Если это agent-facing сценарий:

• добавить функцию в renga_api.skills;
• реэкспортировать её через renga_api;
• убедиться, что она попадает в get_skills_catalog().

Если это одноразовая диагностика:

• не превращать её в постоянный API без необходимости;
• лучше оставить знание в TODO.md, тесте или docstring, если это важно для будущих агентов.

9. Добавить или обновить тест

Минимум:

• unit-тест на mapping, guard, разбор данных или чистую бизнес-логику;
• если логика завязана на геометрию букв или обработку данных, покрыть её без живого COM.

10. Обновить документацию и TODO

После подтверждения результата:

• обновить README.md, если поменялись публичные правила или pipeline;
• обновить TODO.md по статусу задачи;
• при необходимости добавить короткое предупреждение в docstring skill-функции.

Правила разработки

• Предпочитать функциональный стиль.
• Добавлять type hints.
• Изолировать COM-ошибки в безопасных helper-функциях там, где это уместно.
• Любые изменения модели выполнять через operation/transaction.
• Не ломать существующие JSON-структуры дампов без явной причины.
• Для агентного сценария использовать renga_api или renga_api.skills/*, а не строить orchestration поверх core без необходимости.

Текущее состояние

Сейчас в проекте уже есть рабочий wrapper-слой для agent-facing вызовов, dump/introspection, управление процессами, базовые операции над моделью и демонстрационные text-skills.

Открытые практические вопросы и следующие шаги фиксируются в TODO.md.