🚀 Gemini Nexus DB — Enterprise Core v13.9

---

📌 О проекте

Gemini Nexus DB (v13.9 Enterprise by NeuroStarNet) — это автономный десктопный комплекс и диспетчер оркестрации пула краудсорсинговых API-ключей Google Gemini и Gemma.

Приложение предназначено для высокоскоростной многопоточной валидации (пинга) ключей, мониторинга лимитов RPM/TPM и региональных блокировок, балансировки рабочих ключей по параллельным потокам для downstream-воркеров нейроперевода (таких как SuperGeminiTranslator, Telegram-боты очереди), а также защищенного экспорта и шифрования базы данных.

---

🏛️ Архитектура и Data Flow

+-------------------------------------------------------------------------------+
|                       CustomTkinter GUI (GeminiNexus)                         |
|  [ Manager / CRUD ]    [ Key Checker ]    [ Stream Splitter ]    [ FAQ / Doc ]|
+------------------------------------+------------------------------------------+
                                     |
              +----------------------+----------------------+
              |                                             |
              v                                             v
   +--------------------+                       +-----------------------+
   |  SQLite Database   |                       | ThreadPoolExecutor    |
   | (WAL, NORMAL sync) |                       | (Multi-thread Checker)|
   +--------------------+                       +-----------+-----------+
              |                                             |
              |                                             v
              |                                 +-----------------------+
              |                                 | HTTP POST Dispatcher  |
              |                                 | urllib + PySocks      |
              |                                 +-----------+-----------+
              v                                             |
   +--------------------+                                   v
   | Cryptography Subsys|                       +-----------------------+
   | PBKDF2-HMAC-SHA256 |                       | Google Generative API |
   | CTR Stream Cipher  |                       | :generateContent      |
   +--------------------+                       +-----------------------+

---

✨ Ключевые возможности

📡 1. Многопоточный чекер ключей (Key Validator)

• Параллельная проверка: Асинхронное выполнение через ThreadPoolExecutor с настраиваемым количеством воркеров.
• Джиттер и паузы: Рандомизированная задержка между запросами (delay_min .. delay_max) для предотвращения мгновенных срабатываний Rate Limit (429).
• Мгновенный контроль: Прерываемый цикл ожидания — кнопки «Пауза» и «Стоп» реагируют моментально.
• Поддержка прокси: Встроенный диспетчер HTTP/HTTPS и SOCKS4/SOCKS5 (через PySocks) с авторизацией.
• Выборочный пинг (Selective Ping):
  • ⏳ Только Серые — проверка новых/непроверенных ключей (UNCHECKED).
  • 🟡 Только Желтые — повторный опрос ключей с временными лимитами (RESOURCE_EXHAUSTED, TIMEOUT, 503).
  • 🔴 Только Красные — диагностика мертвых и заблокированных ключей.
  • 🔄 Желтые + Серые / Все нерабочие.

🔀 2. Динамический сплиттер потоков (Stream Splitter)

• Round-Robin балансировка: Равномерное распределение валидных (status='OK' и is_ignored=0) ключей по $N$ потокам.
• Изоляция ключей: Возможность точечно исключить отдельный ключ из сплиттера (is_ignored=1) без его удаления из базы.
• Пакетный экспорт: Выгрузка потоков в отдельные файлы valid_keys_stream_<id>.txt для независимых воркеров перевода или копирование выбранного потока в буфер обмена.

🔐 3. Криптографическая подсистема (Zero-Dependency Crypto)

• Стойкое шифрование: Pure-Python потоковый шифр на базе PBKDF2-HMAC-SHA256 (100,000 итераций) + SHA-256 CTR Keystream.
• Контроль целостности: Имитовставка HMAC-SHA256 для защиты шифротекста от модификаций и мгновенного обнаружения неверного пароля.
• Форматы экспорта:
  • 🔒 Зашифрованный JSON (.enc.json) — защищенный паролем бэкап.
  • 📄 Чистый JSON (.json) — структурированная выгрузка.
  • 📋 Список ключей (.txt) — плоский список для CLI-утилит.
  • 📓 Obsidian Markdown (.md) — выгрузка с комментариями и метаданными донатеров.

🗄️ 4. СУБД SQLite (WAL Concurrency)

• Высокая производительность и защита от блокировок с PRAGMA journal_mode=WAL; и PRAGMA foreign_keys=ON;.
• Привязка ключей к донатерам/владельцам, ведение заметок к донатерам и отдельным ключам.
• Каскадное удаление, пакетная очистка мертвых ключей и сброс статусов в один клик.

🖥️ 5. Современный GUI (CustomTkinter) & UX

• Темная тема и интуитивная боковая навигация.
• 🔍 Динамическое масштабирование UI (100% – 200%): Переключение масштаба интерфейса на лету с сохранением в БД — идеальная читаемость на HiDPI и 2.8K/4K экранах.
• Системный фикс буфера обмена: Полная поддержка горячих клавиш (Ctrl+C, Ctrl+V, Ctrl+X, Ctrl+A) и контекстного меню как в Windows, так и в Linux Wayland / X11 в русской и английской раскладках.

---

📊 Классификатор статусов Google Gemini API

Статус	Категория	Индикатор	Описание и действие
OK	Валидный	🟢	Ключ полностью работоспособен и готов к выдаче в потоки перевода.
RESOURCE_EXHAUSTED	Временный	🟡	Превышен лимит RPM/TPM (HTTP 429). Ключ живой, разгрузится со временем.
UNRESTRICTED	Политика API	⚠️	Политика безопасности Google (от 19 июня): ключ требует привязки к сервису в Google Cloud Console.
SERVICE_UNAVAILABLE	Временный	🟡	Сбой серверов или перегрузка мощностей Google (HTTP 502/503).
INTERNAL_ERROR	Временный	🟡	Внутренняя ошибка Google (HTTP 500). Требуется повторный опрос.
DEADLINE_EXCEEDED	Временный	🟡	Таймаут генерации ответа на стороне Google (HTTP 504).
TIMEOUT	Сеть	🟡	Сетевой сбой или недоступность локального прокси. Авто-повтор через 2 сек.
FAILED_PRECONDITION	Фатальный	❌	Региональный блок аккаунта или отсутствие биллинга (HTTP 400).
PERMISSION_DENIED	Фатальный	❌	Доступ запрещен, ключ заблокирован или отозван (HTTP 403).
UNAUTHORIZED	Фатальный	❌	Ключ не существует или удален (HTTP 401).
NOT_FOUND	Ошибка конфига	❌	Указанный ID модели не найден в API Google (HTTP 404).

---

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

Вариант 1. Запуск на NixOS / с установленным Nix (Рекомендуется)

Проект содержит готовый декларативный Flake и автоматический лаунчер:

# Универсальный запуск в один клик (сам настроит окружение)
./run.sh

# Либо через Nix Flake
nix run

# Либо войти в среду разработки
nix develop

При использовании direnv окружение загрузится автоматически при переходе в директорию (direnv allow).

---

Вариант 2. Стандартный запуск (Python venv / Pip)

Требования: Python 3.10+ и системная библиотека Tkinter (python3-tk в Debian/Ubuntu).

# 1. Клонирование репозитория
git clone git@github.com:detkeroot/ping_keys.git
cd ping_keys

# 2. Создание и активация виртуального окружения
python3 -m venv .venv
source .venv/bin/activate  # На Windows: .venv\Scripts\activate

# 3. Установка зависимостей
pip install -r requirements.txt

# 4. Запуск приложения
python3 ping_keys_NeuroStarNet_v13.9.py

---

📁 Структура репозитория

.
├── ping_keys_NeuroStarNet_v13.9.py   # Основное монолитное приложение (GUI, DB, Checker, Crypto)
├── run.sh                           # Универсальный исполняемый лаунчер
├── flake.nix                         # Декларативный Flake для NixOS (devShell + app)
├── flake.lock                        # Зафиксированные хэши зависимостей Nix
├── shell.nix                         # Классический nix-shell fallback
├── .envrc                           # Автозагрузка окружения через direnv
├── requirements.txt                 # Зависимости Python (customtkinter, PySocks)
├── pyproject.toml                   # Метаданные проекта и настройки линтера ruff
├── .gitignore                       # Изоляция баз данных с ключами и кэшей
├── AGENTS.md                         # Инструкции для AI-ассистентов и разработчиков
└── README.md                         # Документация проекта

---

🔒 Безопасность и конфиденциальность

• Файлы базы данных (*.db, *.db-shm, *.db-wal) и экспортированные дампы ключей строго изолированы в .gitignore и никогда не попадают в систему контроля версий.
• При первом запуске на новой машине приложение автоматически инициализирует чистую локальную структуру таблиц SQLite через init_db().

---

👤 Автор

• Автор & Архитектура: NeuroStarNet / detker
• Проект: Gemini Nexus Core DB
• Лицензия: MIT