Providentia Network 是一个基于 Django 的后端系统，它协调使用 Google Gemini 模型的多分支推理、原生 C++ 协处理器以及可选的思维图谱可视化。本文档总结了当前架构，并提供了在本地构建和运行系统所需的命令。

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

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

最近提出了思维树（Tree of Thoughts，ToT），这是一个泛化思维链提示的框架，鼓励对作为语言模型通用问题解决中间步骤的思维进行探索。

ToT 维护一棵思维树，其中思维代表连贯的语言序列，作为解决问题的中间步骤。这种方法使语言模型能够通过深思熟虑的推理过程，对解决问题的中间思维进展进行自我评估。然后，语言模型生成和评估思维的能力与搜索算法（例如广度优先搜索和深度优先搜索）相结合，从而能够通过前瞻和回溯对思维进行系统性探索。

系统架构

高层数据流

客户端 -> /speech/simple_response (Django REST 视图)
      -> Python ThinkingManager (speech/context_manager/ThinkingManager.py)
      -> C++ "Kievan Rus" 思考器 (speech/context_manager/Kievan Rus/*.cpp)
      -> Gemini API (基于 HTTPS 的 JSON)
      -> 二进制负载 (状态 + 上下文 + 摘要)
      -> Python 反序列化器 & 分支扩展
      -> 可选的 PNG 图谱 (speech/context_manager/graphs/)
      -> Django 响应文本

核心组件

Django REST 端点 (speech/views.py)
接受用户提示，实例化 ThinkingManager，并转发代理返回的最终指令文本。
Python Thinking Manager (speech/context_manager/ThinkingManager.py)
维护思维树并强制执行架构规则：
- 将当前消息、分支标签和迭代元数据作为子进程启动原生 C++ 辅助程序。
- 解析二进制响应（1 字节状态、4 字节长度、UTF-8 负载）并根据 ContextStruct（Pydantic）验证 JSON。
- 记录每个分支的 probability_of_success、增量 potential_score、possible_setbacks 和分支标签。
- 保证每层至少进行两次分支探索，并聚合累积潜力分数。
- 输出文本树，并可选择渲染 PNG 图表（见下文）。
C++ "Kievan Rus" 思考器 (speech/context_manager/Kievan Rus/)
模块化为头文件和源文件，用于参数解析、环境加载、Gemini HTTP 调用（libcurl）、提示构建和二进制序列化。
- 从进程环境或 .env 文件中读取 Gemini API 密钥。
- 发起两次 Gemini 请求：一次用于结构化分析，一次用于叙述性摘要。
- 将结构化上下文和摘要编码为 Python 可消费的可移植二进制格式。
- 根 Makefile 目标 build-thinker 重新编译该模块（g++17，-lcurl），并在运行服务器时自动链接。
图谱渲染 (plotting/graphing.py)
使用 Matplotlib（Agg 后端）可视化最终的思维树。每个节点包含分支标签、换行的计划文本、概率、每步潜力增量、累积潜力，并高亮显示"最终"或"遗憾"状态。图像输出到 speech/context_manager/graphs/。
Gemini 代理 (speech/gemini/agent.py)
围绕 Google 的 genai 客户端的轻量级封装。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 环境）。
支持 C++17 的 g++ 以及 libcurl 的开发头文件。
访问 Gemini API 密钥（GEMINI_API_KEY），放置在 .env 或进程环境中。
（可选）用于生成 PNG 图谱的 Matplotlib；没有它，系统会记录警告并跳过绘图。

环境创建

make update              # 通过 conda/micromamba 使用 environment.yml

覆盖默认值：

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 开发服务器
`make migrate`	运行迁移（`makemigrations` + `migrate`）
`make prepare`	从 `environment.yml` 创建 Conda 环境
`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（环境变量）可以覆盖 C++ 进程的 .env 位置。
图谱写入 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