Providentia Network — это бэкенд на Django, который координирует многоветвевое рассуждение с использованием моделей Gemini от Google, нативного сопроцессора на C++ и опциональной визуализации графа мыслей. Этот документ описывает текущую архитектуру и содержит команды, необходимые для сборки и запуска системы локально.

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

 Yao et el. (2023) and Long (2023)

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

ToT поддерживает дерево мыслей, где мысли представляют собой связные языковые последовательности, служащие промежуточными шагами к решению проблемы. Этот подход позволяет LM самостоятельно оценивать прогресс через промежуточные мысли, сделанные для решения проблемы, с помощью продуманного процесса рассуждения. Способность LM генерировать и оценивать мысли затем комбинируется с алгоритмами поиска (например, поиск в ширину и поиск в глубину), чтобы обеспечить систематическое исследование мыслей с предвидением и возвратом.

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

Поток данных высокого уровня

Клиент -> /speech/simple_response (Django REST представление)
      -> Python ThinkingManager (speech/context_manager/ThinkingManager.py)
      -> C++ «Киевская Русь» мыслитель (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++ «Киевская Русь» мыслитель (speech/context_manager/Kievan Rus/)
Модуляризирован на заголовочные файлы и исходники для разбора аргументов, загрузки окружения, HTTP-вызовов Gemini (libcurl), построения промптов и бинарной сериализации.
- Читает ключ Gemini API из переменных окружения процесса или .env.
- Выполняет два запроса к Gemini: один для структурированного анализа, второй для повествовательной сводки.
- Кодирует структурированный контекст и сводку в переносимый бинарный формат, потребляемый Python.
- Цель Makefile build-thinker перекомпилирует модуль (g++17, -lcurl) и автоматически вызывается при запуске сервера.
Отрисовка графов (plotting/graphing.py)
Использует Matplotlib (бэкенд 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 (рекомендуется virtualenv или Conda окружение).
g++ с поддержкой C++17 и заголовочные файлы разработки для libcurl.
Доступ к ключу Gemini API (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++ мыслитель, затем запускает `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 dev сервер
`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=ваш-ключ
# опциональные настройки 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++ (модуляризированные исходники)
├── gemini/
│   └── agent.py               # Python обертка клиента Gemini
plotting/
├── graphing.py                # Отрисовщик деревьев мыслей на Matplotlib
README.md
Makefile

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

Providence