Providence
Python

Providence

リファクタリングされたProvidentiaネットワーク。

GitHub
image

Providentia Networkは、GoogleのGeminiモデル、ネイティブC++コプロセッサ、およびオプションの思考グラフ可視化機能を用いてマルチブランチ推論を orchestrate するDjangoベースのバックエンドです。このドキュメントは現在のアーキテクチャを要約し、システムをローカルで構築・実行するために必要なコマンドを提供します。

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

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

recently proposed Tree of Thoughts (ToT), a framework that generalizes over chain-of-thought prompting and encourages exploration over thoughts that serve as intermediate steps for general problem solving with language models.

ToT maintains a tree of thoughts, where thoughts represent coherent language sequences that serve as intermediate steps toward solving a problem. This approach enables an LM to self-evaluate the progress through intermediate thoughts made towards solving a problem through a deliberate reasoning process. The LM's ability to generate and evaluate thoughts is then combined with search algorithms (e.g., breadth-first search and depth-first search) to enable systematic exploration of thoughts with lookahead and backtracking.

システムアーキテクチャ

高レベルデータフロー

クライアント -> /speech/simple_response (Django RESTビュー)
      -> Python ThinkingManager (speech/context_manager/ThinkingManager.py)
      -> C++ "Kievan Rus" シンカー (speech/context_manager/Kievan Rus/*.cpp)
      -> Gemini API (JSON over HTTPS)
      -> バイナリペイロード (ステータス + コンテキスト + サマリー)
      -> 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ペイロード）を解析し、JSONをContextStruct（Pydantic）に対して検証します。
    • ブランチごとのprobability_of_success、増分potential_score、possible_setbacks、ブランチラベルを記録します。
    • レベルごとに少なくとも2つのブランチ探索を保証し、累積ポテンシャルスコアを集計します。
    • テキストツリーを出力し、オプションでPNG図をレンダリングします（下記参照）。

  • C++ "Kievan Rus" シンカー (speech/context_manager/Kievan Rus/)
    引数解析、環境読み込み、Gemini HTTP呼び出し（libcurl）、プロンプト構築、バイナリシリアライゼーションのためにヘッダー/ソースにモジュール化されています。

    • プロセス環境または.envからGemini APIキーを読み取ります。
    • 2つのGeminiリクエストを発行します：1つは構造化分析用、もう1つはナラティブサマリー用です。
    • 構造化コンテキストとサマリーを、Pythonが消費するポータブルなバイナリ形式にエンコードします。
    • ルートMakefileターゲットbuild-thinkerがモジュールを再コンパイルし（g++17、-lcurl）、サーバー実行時に自動的にチェーンされます。

  • グラフレンダリング (plotting/graphing.py)
    Matplotlib（Aggバックエンド）を使用して最終的な思考ツリーを可視化します。各ノードにはブランチラベル、折り返された計画テキスト、確率、ステップごとのポテンシャル差分、累積ポテンシャルが含まれ、"final"または"regretted"状態のハイライトが表示されます。画像はspeech/context_manager/graphs/に保存されます。

  • Geminiエージェント (speech/gemini/agent.py)
    Googleのgenaiクライアントの軽量ラッパーです。C++モジュールはレイテンシが重要な推論のためにこの機能をミラーリングしています。

ブランチングとスコアリングのセマンティクス

  • ThinkingManagerはツリーの深さを制限し（max_iterations = 8）、各ノードがイテレーション制限に達しない限り、少なくとも2つのラベル付きブランチ（例：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の開発ヘッダー。
  • .envまたはプロセス環境に配置されたGemini APIキー（GEMINI_API_KEY）へのアクセス。
  • （オプション）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

サーバーは、KIEVAN_RUS_ENV_PATHが設定されていない限り、プロジェクトルートの.envを期待します。

一般的なMakeターゲット

ターゲット 説明
make run C++ヘルパーをビルドし、Django開発サーバーを起動
make migrate マイグレーションを実行（makemigrations + migrate）
make prepare environment.ymlからConda環境を作成
make update Conda環境を作成/更新（pruning付き）
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++ヘルパーを同期状態に保つため、推論ロジックに集中できます。ハッピーハッキング！