AI DataBase wAPI Core

1. English / 2. 日本語

AI DataBase wAPI Core (aidbwapi_core)

Основной серверный мод для Minecraft 1.21.1 (NeoForge), предоставляющий функциональность асинхронных запросов к внешним AI (LLM API, совместимым с OpenAI) и лёгкое постоянное хранилище на основе JSON (функциональность базы данных). Этот мод сам по себе не предоставляет отдельных функций (таких как чат-боты); он разработан как системная инфраструктура (Core), позволяющая другим модам (зависимым модам) легко использовать продвинутые AI-функции и хранилище данных через Java API (AiCoreAPI / DatabaseManager).

🚀 Возможности и архитектура

1. Сеть AI-запросов (продвинутая интеграция с AI и автономное переключение при сбоях)

Оснащён системой автономного переключения при сбоях и ограничения скорости, разработанной для обеспечения безопасной и надёжной связи с внешними API при минимизации нагрузки на сервер.

• Полная асинхронная обработка и последовательные очереди (Async Executor): Все HTTP-запросы к AI выполняются с использованием CompletableFuture и стандартного механизма Java HttpClient (асинхронный ввод-вывод), что гарантирует, что тики Minecraft никогда не блокируются. Кроме того, для безопасности предусмотрено, что «число одновременных выполнений всегда не более одного (управление очередью)», что предотвращает множественную одновременную отправку одной и той же строки запроса.
• Сброс по требованию (Lazy Reset): Проверки инициализации «суточных лимитов выполнения» и «поминутных лимитов выполнения» для моделей не используют периодические серверные задачи (постоянный мониторинг). Вместо этого применяется механизм Lazy Reset, при котором вычисления и сбросы выполняются на лету путём сравнения временных меток в момент следующего запроса, что даёт нулевую нагрузку на сервер в режиме ожидания.
• Распределение ключей и распределённый Round-Robin (приоритет и балансировка нагрузки): Для одного провайдера или модели можно зарегистрировать несколько API-ключей. Вы можете задать приоритет (priority: меньшие значения означают более высокий приоритет) для каждого ModelEntry. Система автоматически переключается (на другую модель/ключ) на следующий по приоритету в случае ошибок или исчерпания лимита. Кроме того, если существует несколько моделей с одинаковым приоритетом, система распределяет запросы методом «Round-Robin», автоматически предотвращая концентрацию нагрузки на конкретном API-ключе. Это позволяет безопасно работать, агрегируя квоты лимитов от нескольких бесплатных API-ключей.

• Система штрафных баллов (Penalty Point, PP) и вероятностное пропускание (Penalty System): При возникновении ошибок связи модель не отключается сразу. Вместо этого ей назначаются штрафные баллы (PP) в зависимости от серьёзности ошибки, при этом применяется временная задержка (по умолчанию: 429 = 60 с, 5xx = 120 с, Timeout = 60 с, сбой соединения = 300 с).

  • HTTP 429 (превышен лимит): +1 PP
  • HTTP 5xx (ошибка сервера): +5 PP
  • Timeout / сбой соединения / DNS: +7 PP
  • Успешная связь: PP уменьшается вдвое (PP /= 2)

  При выборе кандидата на выполнение модели с PP временно пропускаются с вероятностью, вычисляемой как: $$\frac{PP}{PP + 4.0}$$ Система автономно избегает или подавляет доступ к нестабильным в данный момент конечным точкам, переходя к следующему кандидату.

• Отказоустойчивый цикл на 100 раундов: Если все модели-кандидаты в данный момент находятся в состоянии вероятностного пропуска или задержки, система возвращается к началу списка кандидатов для повторного выбора. Для предотвращения бесконечных циклов надёжная защита завершает процесс после максимум 100 раундов, либо выбирая доступную модель с наивысшим приоритетом (наименьшим значением приоритета) в качестве компромисса, либо возвращая полный отказ на уровень API.
• Обработка исключений (HTTP 400 Bad Request): Если возникает ошибка, связанная с конфигурацией, например HTTP 401 (неавторизован) или HTTP 404 (модель не найдена), конкретная модель автоматически отключается (disabled), и система немедленно переключается (повторяет попытку) на следующего кандидата. Однако для HTTP 400 (Bad Request), поскольку проблема, скорее всего, связана с конкретным запросом или структурой данных, переключение моделей вряд ли поможет. Поэтому система немедленно возвращает ошибку вызывающему зависимому моду без переключения (мгновенное прекращение бесполезных циклов).

2. Система хранения JSON (функциональность базы данных)

Основа, позволяющая зависимым модам сохранять и загружать свои данные с чрезвычайной лёгкостью. Формат хранения строго фиксирован на JSON.

• Регистрация категорий и иерархическое управление: Вызвав registerCategory("my_mod") во время инициализации, зависимые моды (внешние моды) автоматически создают структуру каталогов, связанную с именем этой категории. Данные автоматически сортируются в папки «Общие данные (Global)» и «Индивидуальные данные игрока (UUID)». (Примечание: данные не могут быть сохранены без предварительной регистрации).
• Кэширование в памяти и динамическое разрешение: Часто используемые данные кэшируются в виде Map в памяти при загрузке. Последующие операции get/set обрабатываются немедленно без дискового ввода-вывода. Корневой путь для каталога хранения автоматически определяется путём получения правильного пути (например, root/world/aidbwapi_core/) во время ServerStartedEvent.
• Синхронный и немедленный механизм сохранения: При выполнении операции записи (set()) в базу данных обновляется кэш в памяти и выполняется немедленная синхронная запись в файл (flush). (Примечание: хотя логи ошибок используют фоновый таймер задержки каждые 3 часа, сама БД не имеет функции асинхронного автосохранения с задержкой). Для безопасности также реализована команда ручного принудительного сохранения (db save).

💻 Требования и установка

• Minecraft: 1.21.1
• Загрузчик модов: NeoForge 21.1.219 или новее
• Java: Java 21 или выше
• Сторона: Требуется как на сервере, так и на клиенте Установка: Поместите этот мод (aidbwapi_core-x.x.x.jar) в папку mods вашего сервера или клиента и запустите.

⚙️ Конфигурация и структура каталогов

Все настройки, базы данных и логи ошибок размещаются в корневой директории сервера или, для клиентов, в saves/[имя_мира]/.

• config/aidbwapi_core-common.toml: Базовые рабочие настройки всего мода.

  • commandPermissionLevel: Требуемый уровень OP для всех команд /dbwapi (по умолчанию: 2). Можно изменить от 0 до 4.
  • requestTimeoutSeconds: Таймаут ответа при общении с ИИ (по умолчанию: 60 секунд).
  • penaltyCurveFactor: Коэффициент корректировки кривой вероятности пропуска PP (по умолчанию: 4.0).
  • Другие настройки включают время кулдауна для различных HTTP-ошибок (rateLimitSeconds и т. д.) и интервал периодической записи логов ошибок (flushIntervalMinutes). Некоторые базовые настройки можно изменить и сохранить на лету через игровые команды.

• config/aidbwapi_core-keynames.json: Хранит URL-адреса конечных точек ИИ, API-ключи в открытом виде, списки моделей и различные настройки ограничений скорости (dailyLimit, minuteLimit) в структурированном формате.

  • ⚠️ [ВАЖНО] Безопасность API-ключей и способ регистрации По спецификации этого мода API-ключи не шифруются и сохраняются в открытом виде в этом JSON-файле. Хотя ключи можно зарегистрировать через игровые команды (/dbwapi keyname setkey), из-за особенностей Minecraft полная команда, введённая вами в чат (строка API-ключа в открытом виде), будет записана как есть в logs/latest.log сервера и в файлы консольного лога. В целях безопасности избегайте ввода команд в игре. Вместо этого мы настоятельно рекомендуем открыть этот файл напрямую в текстовом редакторе, отредактировать/сохранить поле "apiKey": "sk-xxxx...", а затем выполнить в игре команду /dbwapi reload для перезагрузки настроек.

• [Корень сохранения мира]/aidbwapi_core/[имя_категории]/: Корень для хранения настроек и данных каждой категории, сохраняемой и кэшируемой через CategoryDatabaseHandle и т. п.

  • global.json для общих данных и папка players/ с файлами `.json` для отдельных игроков размещаются непосредственно в категории.

• [Корень сохранения мира]/aidbwapi_core/log/: Место, куда в фоновом режиме экспортируется в формате JSON история ошибок (отладочные логи) обработки ИИ и БД, накопленная в памяти.

  • По умолчанию хранится максимум 20 файлов последних логов ошибок, более старые файлы автоматически ротируются (удаляются).
  • Любые несохранённые состояния ошибок, оставшиеся в памяти, сбрасываются при остановке/завершении работы сервера (ServerStoppingEvent), чтобы гарантировать их сохранение на диск.

🛠️ Справочник команд

Первоначальная настройка ИИ и различные настройки/управление моделями легко выполняются через игровые команды. Все команды начинаются с /dbwapi.

• Аргументы и подсказки: При вводе идентификаторов (KeyName или имени модели) в игре будут отображаться подсказки (автодополнение по Tab) для всех зарегистрированных настроек. Синтаксические ошибки или недостаток аргументов отклоняются в соответствии со стандартами Brigadier.
• Цвета формата сообщений: Все ответы команд начинаются с [AiDb] (зелёный). Цель операции (значения или имена) выделяется жёлтым. Ошибки и предупреждения выводятся красным текстом.
• Строгая защита вывода API-ключей: Когда информация об API-ключе выводится в чат через команды отображения (info или list), она маскируется для защиты: "Если исходный ключ длиной 5 символов или больше, отображаются только первые 4 символа, а все остальные маскируются ``." "Если ключ длиной 4 символа или меньше, в виде исключения все символы маскируются ``." Исходные ключи никогда не выводятся на экран или в логи.

📌 Общие и конфигурация

• /dbwapi status: Сводка работы системы. Отображает количество загруженных KeyName и моделей, а также количество ошибок ИИ и БД, currently queued в памяти для вывода.
• /dbwapi reload: Принудительно перезагружает конфигурационные файлы TOML и JSON (keynames.json). Всегда выполняйте это после ручного редактирования текста.
• /dbwapi version: Отображает версию этого мода.
• /dbwapi config show: Отображает текущие применённые настройки отладочного лога (debugLogging) и таймаута общения с ИИ (requestTimeoutSeconds).
• /dbwapi config debug true|false: Мгновенно включает/выключает уровень отладки (подробный вывод логов) и сохраняет настройку.
• /dbwapi config timeout <секунды>: Изменяет и сохраняет таймаут общения с ИИ (базовая настройка).

📌 Управление KeyName

Централизованное управление набором из URL (конечной точки провайдера) и API-ключа как общесистемным "зарегистрированным именем (keyName)".

• /dbwapi keyname list / `info `: Отображает список всех зарегистрированных KeyName или подробности конкретного KeyName. (API-ключи маскируются).
• `/dbwapi keyname add : Регистрирует набор данных подключения для нового провайдера ИИ (совместимого с OpenAI). ※ Хотя дублирующиеся зарегистрированные имена (keyName) являются ошибкой, регистрация одинаковых apiUrlиapiKey` под разными именами разрешена (для балансировки нагрузки).
• `/dbwapi keyname seturl `: Обновляет только URL конечной точки API существующего KeyName.
• `/dbwapi keyname setkey `: Обновляет API-ключ существующего KeyName. (※ Внимание: риск утечки в логи. Для безопасности рекомендуется прямое редактирование JSON.)
• `/dbwapi keyname remove [confirm]: Удаление с защитой от случайного выполнения. Требует true` в конце для выполнения.

📌 Управление моделями и отказоустойчивостью

Идентификаторы моделей всегда указываются как **`.<имя_модели>** (например, taro_groq.llama-3-70b`).

• /dbwapi model list / `info .<имя_модели>`: Отображает рабочее состояние всех моделей (приоритет, статус penalty/PP, текущее состояние и т. д.) и подробные метрики лимитов для отдельных моделей.
• `/dbwapi model add .<имя_модели> [dailyLimit] [minuteLimit]: Добавляет новую доступную модель к родительскому KeyName. Используйте -1` для неограниченного количества.

• `/dbwapi model move .<имя_модели> up|down: Перемещает/меняет приоритет указанной модели на один уровень вверх (up) или на один уровень вниз (down`).

• `/dbwapi model limit .<model_name> daily|minute : Изменяет максимальные лимиты для модели (-1` — без ограничений). Изменения применяются сразу.

• `/dbwapi model enable .<model_name>/disable .<model_name>`: Включает или временно отключает лотерейную настройку для конкретной модели.

  • [Восстановление после автоотключения]: Если возникает проблема с конфигурацией эндпоинта (например, HTTP 401/403 Invalid API Key или HTTP 404 Not Found), система автоматически принудительно отключает модель (disabled). После устранения несоответствия (например, через seturl) восстановите её вручную этой командой enable.
• `/dbwapi model reset .<model_name>`: Мгновенно сбрасывает накопленные PP (штраф) и статус перезарядки целевой модели до нуля.
• /dbwapi model resetall: Сбрасывает «все модели», зарегистрированные в данный момент, разом.
• `/dbwapi model remove .<model_name> [confirm]: Удаляет указанную модель. (※ Требуется защитная блокировка; true` в конце обязателен).

📌 AI Test, Error Logs, & DB Management (Tests & Logger)

• /dbwapi ai status: Показывает количество AI-запросов, обрабатываемых в данный момент (Active), и тех, что находятся в очереди ожидания асинхронной обработки (Queue).
• /dbwapi ai test: Использует «текущую действительную модель», чтобы отправить короткий тестовый запрос и проверить, действительно ли возвращается текстовый ответ.
• /dbwapi ai errors [count]: Выводит историю последних ошибок связи с AI (до 50 записей, по умолчанию 10).
• /dbwapi ai errors clear: Очищает память истории ошибок для отображения.
• /dbwapi db list: Показывает список всех названий категорий, зарегистрированных в данный момент в DatabaseManager.
• `/dbwapi db info `: Показывает такие метрики, как корневой путь хранилища, общее количество ключей БД и текущее количество кэшированных UUID игроков.
• /dbwapi db errors [count] / db errors clear: То же, что и ai errors, но для логов, специфичных для БД (например, FILE_WRITE_ERROR).
• /dbwapi db save: Явно принудительно записывает (flush) все изменения во всех базах данных в памяти в файл.

📦 For Developers: Java API Implementation (API Layer for Developers)

Инфраструктура Core используется путём вызова её через синглтон (getInstance()) или различные статические методы из Java-кода вашего зависимого мода. Перед реализацией добавьте aidbwapi_core как зависимость (например, compileOnly) в ваш build.gradle.

1. Asynchronous Request to AI (AiCoreAPI)

Все внутренние проверки лимитов, распределение ключей, failover и конвейеры обработки исключений скрыты.

import com.morwapi.aidbwapi_core.api.AiCoreAPI;

// Результаты выполнения возвращаются асинхронно как CompletableFuture<String>.
AiCoreAPI.getInstance().requestAI("Tell me the appeal of Minecraft in 100 characters")
    .thenAccept(response -> {
        // [При успехе] Обработка строки ответа ИИ (response).
        System.out.println("AI Response: " + response);
        
        // ⚠️ [ВНИМАНИЕ] Это выполняется в "отдельном потоке (внутри AsyncExecutor)".
        // Для безопасного доступа к миру Minecraft (отправка сообщений в чат, установка блоков, операции с сущностями и т.д.)
        // необходимо вернуть обработку в главный поток (Server Thread)
        // с помощью очереди задач вроде server.execute(() -> { ... }).
    })
    .exceptionally(ex -> {
        // [При ошибке/исключении] Срабатывает, если все модели недоступны,
        // превышен лимит повторов (100) или неверны параметры запроса (HTTP 400).
        System.out.println("AI Communication Error: " + ex.getMessage());
        return null; // Требование CompletableFuture
    });

### 2. JSON-база данных и категории (`CategoryDatabaseHandle`)
Регистрируйте и получайте категории через `AiCoreAPI`, а также получайте дескрипторы для `PlayerDatabase` или `GlobalDatabase` для сохранения и чтения данных.

**[ВАЖНО] Особенности и типы JsonStorageEngine:**
Эта база данных не является высокопроизводительным ORM-инструментом для прямого сохранения и полного восстановления сложных структур пользовательских классов (POJO). Из-за особенностей GSON все данные, восстанавливаемые из JSON-файлов через `get()`, загружаются как коллекции **`Map<String, Object>`** (или примитивные типы).
Поэтому, хотя при сохранении можно передавать экземпляры пользовательских классов, устройство крайне простое и предполагает, что при чтении вы будете приводить типы или восстанавливать их из Map или стандартных типов (либо десериализовать отдельно через GSON). Рекомендуется использовать с простыми Map, числами или строками.

import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;

// ------ Во время инициализации мода (например, FMLCommonSetupEvent) ------

// [1]. Автоматическая генерация и регистрация категорий
AiCoreAPI.getInstance().registerCategory("guild_mod");

// [2]. Получение дескриптора БД для работы
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");

// ------ Пример реализации (например, PlayerJoinEvent) ------
UUID playerId = player.getUUID();

// [1]. Загрузка данных (Чтение)
// Восстанавливается из JSON в формате Map и т.п. Возвращает null, если не создано.
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;

if (rawData != null) {
    // Поскольку числа могут стать Double из-за GSON, получаем как тип Number и приводим.
    killCount = ((Number) rawData).intValue();
}

// [2]. Обновление и сохранение данных (Сохранение)
killCount += 1;

// Аргументы: UUID игрока, имя ключа идентификации хранилища, сохраняемое значение (Object)
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);

// ※ В момент вызова этого метода `set()` файл записывается [синхронно и немедленно]
// в `guild_mod/players/<UUID>.json` одновременно с применением к памяти (Map на стороне кэша).

## ⚖️ Лицензия (License)

Исходный код и предоставленные бинарные файлы этого мода предоставляются и публикуются под **Apache License, Version 2.0**.
Создание и распространение коммерческих или некоммерческих модов, использующих или зависящих от этой инфраструктуры (API), разрешено свободно в рамках условий лицензии.
    



# AI DataBase wAPI Core (aidbwapi_core)


---

## 🚀 Основные функции и архитектура (Features & Architecture)

### 1. Сеть AI-запросов (продвинутая интеграция с ИИ и автономный фейловер)

*   **Сброс с отложенной оценкой (Lazy Reset):**
*   **Распределённое использование ключей и распределённый round-robin (Priority & Load Balancing):**
    *   `HTTP 429` (ограничение скорости): **+1 PP**
    *   `HTTP 5xx` (ошибка сервера): **+5 PP**
    *   `Timeout` / сбой подключения или DNS-разрешения: **+7 PP**
    
*   **Обработка исключений (HTTP 400 Bad Request):**

### 2. Система JSON-хранилища (функция базы данных)


---

## 💻 Требования и установка (Requirements & Setup)

*   **Minecraft:** 1.21.1
*   **Загрузчик модов:** NeoForge 21.1.219 и выше
*   **Java:** Java 21 и выше


---



*   **`config/aidbwapi_core-common.toml`** : Файл базовых настроек работы всего мода.
    *   `commandPermissionLevel`: требуемый уровень OP-прав для всех команд `/dbwapi` (по умолчанию `2`).
    *   `requestTimeoutSeconds`: время ожидания ответа AI-связи в секундах (по умолчанию `60` секунд).
    *   Также можно настроить время кулдауна при различных HTTP-ошибках (`rateLimitSeconds` и т.д.) и интервал периодического сброса логов ошибок (`flushIntervalMinutes`) и прочее.
*   **`config/aidbwapi_core-keynames.json`** : Структурированно сохраняются URL AI-эндпоинтов, API-ключи в открытом виде, а также список моделей и настройки различных лимитов скорости (`dailyLimit`, `minuteLimit`).

---

## 🛠️ Справочник команд (Command Reference)



### 📌 Общее (General & Config)
*   `/dbwapi reload` : Принудительно перезагружает файлы настроек TOML и JSON (`keynames.json`).
*   `/dbwapi version` : Показывает версию этого мода.
*   `/dbwapi config show` : Показывает текущие применённые настройки логов отладки (`debugLogging`) и время ожидания AI-связи в секундах (`requestTimeoutSeconds`).

### 📌 Управление ключами (KeyName) (KeyName Management)
*   `/dbwapi keyname list` / `info <keyName>` : Показывает список всех зарегистрированных KeyName или подробности указанного KeyName.
*   `/dbwapi keyname add <keyName> <apiUrl> <apiKey>` : Регистрирует новый набор данных подключения для AI-провайдера (совместимого с OpenAI).
*   `/dbwapi keyname seturl <keyName> <apiUrl>` : Обновляет только URL API-эндпоинта существующего KeyName.
*   `/dbwapi keyname setkey <keyName> <apiKey>` : Обновляет API-ключ существующего KeyName.**

### 📌 Управление моделями (Model & Failover Management)
*   `/dbwapi model move <keyName>.<имя модели> up|down` : Перемещает приоритет указанной модели (позицию в порядке Priority) на одну вверх (`up`) или на одну вниз (`down`), меняя их местами.
*   `/dbwapi model limit <keyName>.<имя модели> daily|minute <значение>` : Изменяет лимит вызовов модели (`-1` — без ограничений).
*   `/dbwapi model enable <keyName>.<имя модели>` / `disable <keyName>.<имя модели>` : Включает/временно отключает выбор указанной модели.
*   `/dbwapi model remove <keyName>.<имя модели> [confirm]` : Удаляет указанную модель.

### 📌 Тестирование работы AI, логи ошибок, управление БД (Tests & Logger)
*   `/dbwapi db errors [количество]` / `db errors clear` : По тому же принципу, что и `ai errors`, выводит в чат логи, специфичные для БД (`FILE_WRITE_ERROR` и т.д.) (по умолчанию 10 записей при пропуске) и очищает их.

---

## 📦 Для разработчиков: как использовать Java API (API Layer for Developers)

Подключите `aidbwapi_core` в `build.gradle` как зависимость (`compileOnly` и т.д.) и реализуйте.

### 1. Асинхронный запрос к AI (`AiCoreAPI`)

```java

```java
import com.morwapi.aidbwapi_core.api.AiCoreAPI;
// Результат выполнения возвращается асинхронно как CompletableFuture<String>.
AiCoreAPI.getInstance().requestAI("Расскажи о прелестях Minecraft в 100 символах")
    .thenAccept(response -> {
        System.out.println("Ответ AI: " + response);
        
    })
    .exceptionally(ex -> {
        // Тип ошибки (RATE_LIMITED, ALL_FAILED и т.д.) и подробности содержатся в сообщении (ex.getMessage()).
        System.out.println("Ошибка связи с AI: " + ex.getMessage());
        return null; // Требование CompletableFuture
    });

2. JSON-база данных и категории (CategoryDatabaseHandle)

【Важно】Спецификация и типы JsonStorageEngine:

import com.morwapi.aidbwapi_core.api.AiCoreAPI;
import com.morwapi.aidbwapi_core.api.CategoryDatabaseHandle;
import java.util.UUID;
// ------ При инициализации мода (FMLCommonSetupEvent и т.п.) ------
AiCoreAPI.getInstance().registerCategory("guild_mod");
CategoryDatabaseHandle dbHandle = AiCoreAPI.getInstance().getCategoryDatabase("guild_mod");
// ------ Пример реализации (PlayerJoinEvent и т.п.) ------
UUID playerId = player.getUUID();
Object rawData = dbHandle.getPlayerDB().get(playerId, "killCount");
int killCount = 0;
if (rawData != null) {
    killCount = ((Number) rawData).intValue();
}
killCount += 1;
dbHandle.getPlayerDB().set(playerId, "killCount", killCount);
// Файл 【синхронно и мгновенно】 записывается в `guild_mod/players/<UUID>.json`.

⚖️ Лицензия (License)