Providentia Network — це бекенд на основі Django, який оркеструє багатогілкове міркування за допомогою моделей Gemini від Google, нативного C++ співпроцесора та опціональних візуалізацій графа думок. Цей документ узагальнює поточну архітектуру та надає команди, необхідні для локальної збірки та запуску системи.

https://www.promptingguide.ai/techniques/tot

 Yao et el. (2023) та Long (2023)

нещодавно запропонували Tree of Thoughts (ToT) — фреймворк, який узагальнює ланцюжок міркувань (chain-of-thought prompting) та заохочує дослідження думок, що слугують проміжними кроками для загального вирішення проблем за допомогою мовних моделей.

ToT підтримує дерево думок, де думки представляють собою послідовні мовні послідовності, що слугують проміжними кроками до вирішення проблеми. Цей підхід дозволяє мовній моделі самостійно оцінювати прогрес через проміжні думки, зроблені для вирішення проблеми, за допомогою цілеспрямованого процесу міркування. Здатність мовної моделі генерувати та оцінювати думки потім поєднується з алгоритмами пошуку (наприклад, пошук у ширину та пошук у глибину) для забезпечення систематичного дослідження думок з передбаченням та відкатом.

Архітектура системи

Високорівневий потік даних

Клієнт -> /speech/simple_response (Django REST view)
      -> Python ThinkingManager (speech/context_manager/ThinkingManager.py)
      -> C++ “Kievan Rus” thinker (speech/context_manager/Kievan Rus/*.cpp)
      -> Gemini API (JSON через HTTPS)
      -> Бінарний пакет (статус + контекст + резюме)
      -> Python десеріалізатор та розширення гілок
      -> Опціональний PNG граф (speech/context_manager/graphs/)
      -> Текст відповіді Django

Основні компоненти

Django REST Endpoint (speech/views.py)
Приймає запит користувача, створює екземпляр ThinkingManager та передає кінцевий текст інструкції, повернутий агентом.
Python Thinking Manager (speech/context_manager/ThinkingManager.py)
Керує деревом думок та забезпечує дотримання архітектурних правил:
- Запускає нативний C++ помічник як підпроцес з поточним повідомленням, міткою гілки та метаданими ітерації.
- Розбирає бінарну відповідь (1 байт статусу, 4 байти довжини, UTF-8 корисні навантаження) та перевіряє JSON на відповідність ContextStruct (Pydantic).
- Записує probability_of_success для кожної гілки, інкрементальний potential_score, possible_setbacks та мітки гілок.
- Гарантує щонайменше два дослідження гілок на рівні та агрегує сукупний потенційний бал.
- Виводить текстове дерево та опціонально генерує PNG діаграму (див. нижче).
C++ “Kievan Rus” Thinker (speech/context_manager/Kievan Rus/)
Модуляризований на заголовки/джерела для розбору аргументів, завантаження середовища, викликів Gemini HTTP (libcurl), побудови запитів та бінарної серіалізації.
- Зчитує ключ API Gemini з середовища процесу або .env.
- Виконує два запити Gemini: один для структурованого аналізу, один для наративного резюме.
- Кодує структурований контекст та резюме у портативний бінарний формат, який споживається Python.
- Коренева ціль Makefile build-thinker перекомпілює модуль (g++17, -lcurl) і автоматично запускається під час роботи сервера.
Graph Rendering (plotting/graphing.py)
Використовує Matplotlib (бекeнд Agg) для візуалізації кінцевого дерева думок. Кожен вузол включає мітку гілки, обгорнутий текст плану, ймовірності, дельти потенціалу для кожного кроку, сукупний потенціал та виділення для "кінцевих" або "відкликаних" станів. Зображення зберігаються в speech/context_manager/graphs/.
Gemini Agent (speech/gemini/agent.py)
Легкий обгортковий клас навколо клієнта genai від Google. C++ модуль дублює цю функціональність для міркувань, критичних до затримки.

Семантика розгалуження та оцінки

ThinkingManager обмежує глибину дерева (max_iterations = 8), але гарантує, що кожен вузол створює щонайменше дві мічені гілки (наприклад, Primary-A, Primary-B), якщо це не обмежено лімітом ітерацій.
Кожна гілка містить:
- probability_of_success — число з плаваючою комою, обмежене [0.0, 1.0].
- potential_score — знакове зміщення, додане до cumulative_potential.
- possible_setbacks — текстова оцінка ризику, вбудована в журнали, вивід консолі та візуалізації.
Журнали виводяться для кожного створення гілки, числової оцінки та кроку візуалізації графа для полегшення налагодження.

Налаштування та використання

Передумови

Python 3 (рекомендується віртуальне середовище або середовище Conda).
g++ з підтримкою C++17 та заголовками розробки для libcurl.
Доступ до ключа API Gemini (GEMINI_API_KEY), розміщеного в .env або в середовищі процесу.
(Опціонально) Matplotlib для генерації PNG графа; без нього система виводить попередження та пропускає побудову графа.

Створення середовища

make update              # використовує environment.yml через conda/micromamba

Перевизначення стандартних налаштувань:

make update CONDA_ENV=my-env-name
make update ENV_FILE=envs/dev.yml
make update CONDA=~/.local/bin/micromamba

Збірка та запуск

make run                 # перекомпілює C++ thinker, потім запускає `python manage.py runserver`

Автономна компіляція (якщо потрібно):

make build-thinker       # cd speech/context_manager/Kievan\ Rus && g++ ... -lcurl

Сервер очікує .env у корені проекту, якщо KIEVAN_RUS_ENV_PATH не встановлено.

Поширені цілі Make

Ціль	Опис
`make run`	Зібрати C++ помічник та запустити сервер розробки Django
`make migrate`	Виконати міграції (`makemigrations` + `migrate`)
`make prepare`	Створити середовище Conda з `environment.yml`
`make update`	Оновити/створити середовище Conda з очищенням
`make build-thinker`	Перекомпілювати модуль міркувань C++
`make help`	Показати список доступних цілей (якщо визначено в Makefile)

Використовуйте PY=... для вказівки конкретного інтерпретатора або перевизначте DJANGO_SETTINGS_MODULE за потреби.

Примітки до конфігурації

.env

GEMINI_API_KEY=your-key
# опціональні налаштування Django...

KIEVAN_RUS_ENV_PATH (змінна середовища) може перевизначати розташування .env для C++ процесу.
Графи записуються в speech/context_manager/graphs/thought_graph_<root-id>.png. Видаліть каталог, щоб очистити артефакти.

Поради щодо тестування та налагодження

Бінарний протокол є суворим; некоректні відповіді від Gemini (наприклад, відсутність полів text) викликають чіткі винятки, які реєструються як рівнями Python, так і C++.
Створення гілок, розрахунок ймовірностей та візуалізація графа детально реєструють прогрес за допомогою префіксів [ThinkingManager]. Спостерігайте за консоллю Django під час розробки, щоб відстежувати потік міркувань.
Якщо Matplotlib відсутній, система продовжує роботу без виведення PNG, але реєструє помилку імпорту.

Розклад репозиторію (вибране)

speech/
├── context_manager/
│   ├── ThinkingManager.py     # Python оркестратор
│   └── Kievan Rus/            # C++ нативний thinker (модуляризовані джерела)
├── gemini/
│   └── agent.py               # Python обгортка клієнта Gemini
plotting/
├── graphing.py                # Matplotlib рендерер для дерев думок
README.md
Makefile

Бекенд Providentia Network розроблений для ітераційного експериментування: оновлюйте запити, налаштовуйте евристику оцінки або розширюйте бінарний формат за потреби. make run підтримує C++ помічник в актуальному стані, щоб ви могли зосередитися на логіці міркувань. Щасливого хакінгу!

Providence