Ontology MCP Server Rl Stable Baselines3

## 🚀 オントロジー強化学習コマースエージェント

🛍️ **オントロジー強化学習コマースエージェント**（旧称 "オントロジーMCPサーバー"）は、最新の強化学習によるクローズドループを強調しています。このシステムは、依然としてモデルコンテキストプロトコル（MCP）に依存して、オントロジー推論、電子商取引のビジネスロジック、メモリ、およびGradio UIを組み合わせることで、エンドツーエンドの完全なショッピングアシスタント体験を再現することができます。

🤖 **強化学習によるエージェント**：Stable Baselines3 PPOのトレーニングパイプラインが組み込まれています。これは、**データ → トレーニング → 評価 → デプロイメント**の全フローをカバーし、エージェントが実際の会話記録とツールログから継続的に学習し、より安全で効率的なツールチェーンポリシーを自動的に発見できるようにします。

## 🚀 クイックスタート

### オプションA: Docker（推奨）

**必要条件**
- Docker 20.10以上
- Docker Compose 2.0以上
- 8GB以上のRAM
- 20GB以上のディスクスペース

**ワンクリック起動**

```bash
# 1. リポジトリをクローンする
git clone <repository-url>
cd ontology-mcp-server-RL-Stable-Baselines3

# 2. 環境変数を設定する
cp .env.example .env
nano .env  # LLM APIキーを入力する

# 3. すべてのサービスを起動する
docker-compose up -d

# 4. ログを表示する
docker-compose logs -f

# 5. サービスを停止する
docker-compose down

サービスエンドポイント

• MCPサーバー: http://localhost:8000
• エージェントUI: http://localhost:7860
• トレーニングダッシュボード: http://localhost:7861

一般的なコマンド

# 単一のサービスを再起動する
docker-compose restart agent-ui

# デバッグ用にコンテナに入る
docker exec -it ontology-agent-ui bash

# ステータスを確認する
docker-compose ps

# クリーンアップして再構築する（注意して使用）
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d

GPUサポート（オプション）

nvidia-docker をインストールした後、docker-compose.yml の training-dashboard の下にあるGPUブロックのコメントを解除します。

distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

オプションB: ローカル開発

1. 環境の準備

必要条件

• Python 3.10以上
• 推論/デモ用に8GB以上のRAM（強化学習トレーニング用に32GB以上）
• Linux/macOS/WSL2
• GPU（オプション、VRAM 12GB以上のNVIDIA推奨）
• 40GB以上のディスク（データベース、Chromaベクトル、強化学習チェックポイント用）

依存関係のインストール

git clone <repository-url>
cd ontology-mcp-server-RL-Stable-Baselines3
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

2. データベースの初期化

Dockerデプロイメントでは、初回起動時にこれらの手順が自動的に実行されます。手動手順はローカル開発用です。

export ONTOLOGY_DATA_DIR="$(pwd)/data"
python scripts/init_database.py        # テーブルを作成する
python scripts/seed_data.py            # 基本的なユーザー/製品を追加する
python scripts/add_bulk_products.py    # オプション: 1000以上の製品を追加する
python scripts/add_bulk_users.py       # オプション: 200以上のユーザーを追加する
python scripts/update_demo_user_names.py --seed 2025

サンプルユーザー

サンプル製品

• iPhone 15 Pro Max（9,999元）
• iPhone 15 Pro（8,999元）
• iPhone 15（5,999元）
• AirPods Pro 2（1,899元）
• アクセサリーなど

3. LLMの設定

src/agent/config.yaml は、DeepSeek、OpenAI互換API、またはローカルのOllamaをサポートしています。

llm:
  provider: "deepseek"
  api_url: "https://api.deepseek.com/v1"
  api_key: "your-api-key-here"
  model: "deepseek-chat"
  temperature: 0.7
  max_tokens: 2000

または環境変数を使用して設定することもできます。

export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"

# ローカルのOllama（qwen3:8bの例）
export LLM_PROVIDER="ollama"
export OLLAMA_API_URL="http://localhost:11434/v1"
export OLLAMA_MODEL="qwen3:8b"
export OLLAMA_API_KEY="ollama"  # Ollamaは値を無視します

3.1 MCPベースURLの設定

トレーニングスクリプト (train_rl_agent.py) とGradioエージェントの両方がHTTPを介してMCPを呼び出します。必要に応じて MCP_BASE_URL を上書きします。

# ローカル/開発環境
export MCP_BASE_URL="http://127.0.0.1:8000"

# Docker/本番環境（コンテナ間通信）
export MCP_BASE_URL="http://ontology-mcp-server:8000"

4. サービスの起動

オプション1: start_all.sh（推奨）

./scripts/start_all.sh
# デフォルトではlogs/server.logに集約されます（日次でローテーション）。各スクリプトの独立したログを復元するには、実行前にDISABLE_SCRIPT_LOG_FILES=0をエクスポートします
tail -f logs/server.log

すべてを停止するには：

./scripts/stop_all.sh

オプション2: 個別に起動する

./scripts/run_server.sh
./scripts/run_agent.sh
./scripts/run_training_dashboard.sh
./scripts/run_tensorboard.sh

オプション3: 手動コマンド

# ターミナル1: MCPサーバー（FastAPI）
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
uvicorn ontology_mcp_server.server:app --host 0.0.0.0 --port 8000

# ターミナル2: Gradio UI
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://127.0.0.1:8000"
python -m agent.gradio_ui

# ターミナル3: 強化学習トレーニングダッシュボード
source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://127.0.0.1:8000"
python scripts/run_training_dashboard.py

# ターミナル4: TensorBoard
source .venv/bin/activate
tensorboard --logdir data/rl_training/logs/tensorboard --host 0.0.0.0 --port 6006

Gradioのバインドアドレス/ポートを変更するには、起動前に GRADIO_SERVER_NAME と GRADIO_SERVER_PORT を設定します。run_agent.sh / run_training_dashboard.sh は AGENT_HOST/PORT と TRAINING_DASHBOARD_HOST/PORT を受け入れ、これらの値をGradioの環境変数に転送して、ポート7860/7861を独立させます。

5. UIにアクセスする

http://127.0.0.1:7860 にアクセスします。

タブ:

• 💬 計画: 入力エリア、AI応答、推論計画、ライブ状態
• 🔧 ツール呼び出し: ツール名/パラメータ、タイムスタンプ、結果、エラー
• 🧠 メモリ: 履歴リスト、要約、検索コントロール、セッション管理
• 🛍️ コマース分析: 品質メトリクス、意図分析、会話状態、推薦エンジン
• 📋 実行ログ: 完全なLLM入力/出力とツールトレース

メモリフロー（Mermaid）

flowchart LR
  subgraph Ingest[取り込みと保存]
    direction TB
    U(ユーザー入力)
    U --> AT(ChromaMemory.add_turn)
    AT --> SUM(要約の生成)
    SUM --> DB((ChromaDBコレクション))
    AT --> DB
  end

  subgraph Extract[抽出]
    direction TB
    AT --> EX(ユーザーコンテキスト抽出器)
    EX --> UM(ユーザーコンテキストマネージャー)
  end

  subgraph Retrieval[検索と注入]
    direction TB
    UM --> CTX(プロンプト用のコンテキストを取得)
    CTX --> NOTE_CTX(コンテキストと履歴を注入)
    NOTE_CTX --> AGT(エージェント / LLM)
  end

  AGT --> TC(ツール呼び出し)
  TC --> AT
  TC -->|create_orderがORD...を生成する場合...| UM

6. サンプル会話

ユーザー: こんにちは
AI: こんにちは！ようこそ...（意図: 挨拶）

ユーザー: 携帯電話をおすすめしてください。
AI: [commerce.search_products] 4つのiPhoneモデルが返されます...

ユーザー: iPhone 15 Pro Maxは在庫がありますか？
AI: [commerce.check_stock] 在庫あり、50台...

ユーザー: カートに追加してください
AI: [commerce.add_to_cart] 追加されました...（状態: 閲覧 → カート）

7. 対話シーケンス図

完全な会話（推薦 → マルチ検索 → チェックアウト → アフターサービス → 分析）のログ駆動セグメントは、 にあります。各セクションにはMermaidシーケンス図とPNGスナップショットが含まれており、生のログ、ツール呼び出し、およびUI状態を照合することができます。

8. オプションの強化学習ループ

• scripts/generate_dialogue_corpus.py で最新の200の完全に実際のシナリオを生成します。
• python test_rl_modules.py で強化学習モジュールを健全性チェックします。
• python train_rl_agent.py --timesteps ... でPPOトレーニングを開始します。
• 詳細は以下の 🧠 強化学習（フェーズ6） を参照してください。

🔧 MCPサーバーAPI

MCPサーバーはHTTPエンドポイントを公開しています。

ヘルスチェック

curl http://localhost:8000/health

機能リスト

curl http://localhost:8000/capabilities

ツールを呼び出す

curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "commerce.search_products",
    "params": {
      "available_only": true,
      "limit": 5
    }
  }'

21のツール

オントロジーツール（3つ）

1. ontology.explain_discount
2. ontology.normalize_product
3. ontology.validate_order

コマースツール（18つ） 4. commerce.search_products 5. commerce.get_product_detail 6. commerce.check_stock 7. commerce.get_product_recommendations 8. commerce.get_product_reviews 9. commerce.add_to_cart 10. commerce.view_cart 11. commerce.remove_from_cart 12. commerce.create_order 13. commerce.get_order_detail 14. commerce.cancel_order 15. commerce.get_user_orders 16. commerce.process_payment 17. commerce.track_shipment 18. commerce.get_shipment_status 19. commerce.create_support_ticket 20. commerce.process_return 21. commerce.get_user_profile

🧠 エージェントアーキテクチャ

コアコンポーネント

1. ReActエージェント (react_agent.py)

   • LangChain ReActワークフロー（推論 + 行動）
   • 自動ツール選択と推論トレース
   • マルチターン対話の認識

2. 会話状態 (conversation_state.py)

   • 8つのフェーズ: 挨拶 → 閲覧 → 選択 → カート → チェックアウト → 追跡 → サービス → アイドル
   • VIPステータス、カート状態、閲覧履歴を追跡
   • キーワードとツールの使用から自動的に状態遷移を検出

3. システムプロンプト (prompts.py)

   • 電子商取引のペルソナ: プロフェッショナルで友好的なショッピングアドバイザー
   • 中国語のプロンプトを生成する際には丁寧な「nin」トーンを使用し、システム用語を避ける
   • 危険な操作（支払い、キャンセル）を確認する
   • 即座に拒否するのではなく、説明を求める質問を促す

4. 会話メモリ (chroma_memory.py)

   • バックエンド: ChromaDB
   • 検索モード: recent、similarity、hybrid
   • 各ターンを自動的に要約する
   • data/chroma_memory/ に永続化される

5. 品質追跡 (quality_metrics.py)

   • 会話品質スコア（0-1）
   • ユーザー満足度の推定
   • ツールの効率とレイテンシーを追跡

6. 意図トラッカー (intent_tracker.py)

   • 14の意図（挨拶、検索、カート表示、チェックアウト、注文追跡など）
   • 信頼度スコアと履歴

7. 推薦エンジン (recommendation_engine.py)

   • パーソナライズされた製品推薦
   • 閲覧/カート履歴と会員レベルを使用する

🧠 強化学習（フェーズ6）

ハードウェアのヒント: PPOトレーニングは、8コア以上、32GB以上のRAM、およびVRAM 12GB以上のGPU（RTX 3080/4090/A6000）で恩恵を受けます。CPUのみでも可能ですが、100Kステップのトレーニングには5-8時間かかる場合があり、GPUを使用すると約1時間に短縮されます。data/rl_training/ には15GB以上のスペースを確保してください。

目標と利点

• ReActエージェントがStable Baselines3 PPOを通じて自己改善するようにする。
• ユーザーコンテキスト/意図/ツールの使用/製品情報を128次元の状態にエンコードする。
• 多目的の報酬（タスク成功、効率、満足度、安全性）。
• Gymnasium環境は、ビジネスロジックを再実装することなくLangChainエージェントを再利用する。

モジュールの概要 (src/agent/rl_agent/)

シナリオコーパス data/training_scenarios/sample_dialogues.json には、5つのシナリオカテゴリにまたがる200の実際の会話が含まれており、実際のユーザー/注文/製品を参照しています。

クローズドループ: データ → トレーニング → アプリケーション

1. データ段階

   • データベースが埋められていることを確認します: add_bulk_products.py、add_bulk_users.py、update_demo_user_names.py --seed 2025。
   • 200の実際のシナリオを生成します: python scripts/generate_dialogue_corpus.py。
   • オプションの検証スニペット（カテゴリのカウント）はREADME.zh.mdに示されています。

2. トレーニング

source .venv/bin/activate
export ONTOLOGY_DATA_DIR="$(pwd)/data"
export MCP_BASE_URL="http://localhost:8000"
export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"
export TRAIN_DEVICE="gpu"  # フォールバックしてcpuにする
python test_rl_modules.py
python train_rl_agent.py \
  --timesteps 100000 \
  --eval-freq 2000 \
  --checkpoint-freq 20000 \
  --output-dir data/rl_training \
  --max-steps-per-episode 12 \
  --scenario-file data/training_scenarios/sample_dialogues.json \
  --device "${TRAIN_DEVICE:-gpu}"

ログは data/rl_training/logs/tensorboard/ にストリーミングされます。

3. 評価とアーティファクト

• 最良のモデル: data/rl_training/best_model/best_model.zip
• 最終的なモデル: data/rl_training/models/ppo_ecommerce_final.zip
• チェックポイント: data/rl_training/checkpoints/ppo_ecommerce_step_*.zip
• エピソードの統計情報: data/rl_training/logs/training_log.json

4. デプロイメント

python - <<'PY'
from agent.react_agent import LangChainAgent
from agent.rl_agent.ppo_trainer import PPOTrainer

agent = LangChainAgent(max_iterations=6)
trainer = PPOTrainer(agent, output_dir="data/rl_training")
trainer.create_env(max_steps_per_episode=10)
trainer.load_model("data/rl_training/best_model/best_model.zip")

query = "I need ten flagship Huawei phones, budget around 7000"
action_idx, action_name, _ = trainer.predict(query)
print("RL suggested action:", action_idx, action_name)

result = agent.run(query)
print(result["final_answer"])
PY

強化学習ダッシュボード（Gradio）

src/training_dashboard/ は、コーパスの集計、トレーニングのオーケストレーション、メトリクスの可視化、モデルの登録、およびホットリロードを備えた独立したコンソールを提供します。

1. config/training_dashboard.example.yaml を config/training_dashboard.yaml にコピーし、パスを調整します。
2. PYTHONPATH=src python scripts/run_training_dashboard.py で起動します。
3. タブ: 概要（ライブステータス、報酬/長さのグラフ、ログ）、コーパス管理（静的/ログの混合）、トレーニングコントロール、モデル管理。

報酬の内訳

• R_task: 注文が成功した場合は+10点。重要な情報が欠けているか、空の返答がある場合は減点されます。
• R_efficiency: ツールの呼び出しが少なく、レイテンシーが低い場合は報酬が与えられ、過度の呼び出しはペナルティを受けます。
• R_satisfaction: ライブ品質スコアを使用して、積極的なガイダンスに報酬を与えます。
• R_safety: +1点から始まり、SHACLの検証に失敗したり、安全でないツールを使用したりすると最大10点減点されます。

チューニングのヒント

• リソースが許す場合は --use-text-embedding を有効にして、より豊富な状態を得ることができます。
• PPOTrainer の reward_weights を調整して、成功と安全性のバランスを取ります。
• max_steps_per_episode: 頻繁な評価には短いエピソードを、完全なショッピングジャーニーには長いエピソードを使用します。

🏗️ オントロジーとアーキテクチャ

オントロジーセマンティックモデル

システムは、完全な関係とプロパティを持つ 12のコアビジネスエンティティ を定義しています。

コアトランザクションエンティティ

1. ユーザー

   • プロパティ: user_id、username、email、phone、user_level（Regular/VIP/SVIP）、total_spent、credit_score
   • 操作: ユーザーの照会、ユーザー認証
   • 関係: 注文を作成する、カートアイテムを所有する、サポートチケットを開始する

2. 製品

   • プロパティ: product_id、product_name、category、brand、model、price、stock_quantity、specs
   • 操作: 製品の検索、製品の詳細を取得する、在庫を確認する、推薦を取得する、レビューを取得する
   • 関係: カートアイテム、注文アイテム、およびレビューによって参照される

3. カートアイテム

   • プロパティ: cart_id、user_id、product_id、quantity、added_at
   • 操作: カートに追加する、カートを表示する、カートから削除する
   • 関係: ユーザーを製品にリンクする

4. 注文

   • プロパティ: order_id、order_no、total_amount、discount_amount、final_amount、order_status、payment_status
   • 操作: 注文を作成する、注文の詳細を取得する、注文をキャンセルする、ユーザーの注文を取得する
   • 関係: 注文アイテムを含む、支払いと出荷記録を生成する
   • オントロジー推論: 割引金額は、ユーザーレベル、注文金額、および初回注文ステータスに基づいてオントロジールールによって計算されます。

5. 注文アイテム

   • プロパティ: item_id、order_id、product_id、product_name、quantity、unit_price、subtotal
   • 関係: 注文は複数の注文アイテムを含み、各注文アイテムは製品を参照します。

6. 支払い

   • プロパティ: payment_id、order_id、payment_method、payment_amount、payment_status、transaction_id、payment_time
   • 操作: 支払いを処理する
   • 関係: 注文から生成される
   • 注意: トランザクションIDは支払いの領収書として機能します。

7. 出荷

   • プロパティ: shipment_id、order_id、tracking_no、carrier、current_status、current_location、estimated_delivery
   • 操作: 出荷を追跡する、出荷ステータスを取得する
   • 関係: 注文から生成される、出荷トラックを記録する

8. 出荷トラック

   • プロパティ: track_id、shipment_id、status、location、description、track_time
   • 関係: 複数のトラックは1つの出荷に属します。

カスタマーサービスとアフターサービスエンティティ

9. サポートチケット

   • プロパティ: ticket_id、ticket_no、user_id、order_id、category、priority、status、subject、description
   • 操作: サポートチケットを作成する
   • 関係: ユーザーが注文に対して作成する、サポートメッセージを含む

10. サポートメッセージ

    • プロパティ: message_id、ticket_id、sender_type、sender_id、message_content、sent_at
    • 関係: 複数のメッセージは1つのサポートチケットに属します。

11. 返品

    • プロパティ: return_id、return_no、order_id、user_id、return_type（return/exchange）、reason、status、refund_amount
    • 操作: 返品を処理する
    • 関係: 注文から開始される

12. レビュー

    • プロパティ: review_id、product_id、user_id、order_id、rating（1-5星）、content、images
    • 操作: 製品のレビューを取得する
    • 関係: ユーザーが製品をレビューする

アーキテクチャ図

エンティティ関係:

• ユーザー → 注文 → 注文アイテム → 製品
• 注文 → カートアイテム → 製品
• 注文 → 支払い（payment_amount、payment_method、transaction_id）
• 注文 → 出荷 → 出荷トラック（location、time）
• ユーザー/注文 → サポートチケット → サポートメッセージ
• 注文 → 返品（return_no、return_type、refund_amount）
• 製品 → レビュー（rating、content）

オントロジー推論:

• 割引ルール: VIP/SVIP会員割引、ボリューム割引（≥5000/≥10000）、初回注文割引
• 配送ルール: 無料配送（注文 ≥500またはVIP/SVIP）、翌日配達（SVIP）、遠隔地域の追加料金
• 返品ポリシー: 7日間の無理由返品（Regular）、15日間（VIP/SVIP）、カテゴリ別のルール

MCPツールレイヤー: 21のツールがオントロジー推論を介して12のエンティティに対して操作します。 ReActエージェント: ツールを呼び出し、強化学習（PPOモデル、報酬システム）によって最適化されます。

🎯 オントロジールールのカバレッジ

ontology_rules.ttl の100%が ecommerce_ontology.py で実装されています。

ユーザーレベルルール（2つ）

割引ルール（5つ）

会員割引とボリューム割引は重複しません—最適な割引が適用されます。

配送ルール（5つ）

返品/交換ルール（5つ）

コンボ戦略（2つ）

SHACL検証

commerce_service.py は、注文を作成する前にSHACL検証を呼び出してデータの整合性を確保し、最上位の違反とトリプル数をログに記録します。

📊 Gradio UIの機能

• 💬 計画: 入力エリア、AI応答、推論計画、ライブ状態
• 🔧 ツール呼び出し: ツール名/パラメータ、タイムスタンプ、結果、エラー
• 🧠 メモリ: 履歴リスト、要約、検索コントロール、セッション管理
• 🛍️ コマース分析: 品質メトリクス、意図分析、会話状態、推薦エンジン
• 📋 実行ログ: 完全なLLM入力/出力とツールトレース

📚 ドキュメント

• フェーズ3完了レポート
• フェーズ4完了レポート
• メモリガイド
• メモリ設定ガイド
• 実行ログガイド
• Gradio UIガイド
• エージェント使用ガイド

🧪 テスト

source .venv/bin/activate
python test_memory_quick.py
python test_execution_log.py
python test_phase4_shopping.py
python test_phase4_advanced.py
python test_gradio_ecommerce.py
python test_rl_modules.py

pytest tests/
pytest tests/test_services.py
pytest tests/test_commerce_service.py
python train_rl_agent.py --timesteps 20000 --eval-freq 2000 --checkpoint-freq 5000

⚙️ 設定

環境変数

MCP / データルート

export ONTOLOGY_DATA_DIR="$(pwd)/data"
export APP_HOST=0.0.0.0
export APP_PORT=8000

オントロジートグル（config.yaml）

ontology:
   use_owlready2: true  # デフォルトで有効になっています。config.yamlで変更できます。

実行時に一時的に無効にするには、ONTOLOGY_USE_OWLREADY2=false 環境変数を設定して上記の設定を上書きします。

エージェント & LLM

export MCP_BASE_URL="http://127.0.0.1:8000"
export OPENAI_API_URL="https://api.deepseek.com/v1"
export OPENAI_API_KEY="your-api-key"
export OPENAI_MODEL="deepseek-chat"
export LLM_PROVIDER="deepseek"

Gradioサービス

export GRADIO_SERVER_NAME=0.0.0.0
export GRADIO_SERVER_PORT=7860
export AGENT_HOST=0.0.0.0
export AGENT_PORT=7860
export TRAINING_DASHBOARD_HOST=0.0.0.0
export TRAINING_DASHBOARD_PORT=7861
export LOG_DIR="$(pwd)/logs"
export TB_LOG_DIR="$(pwd)/data/rl_training/logs/tensorboard"
export TB_HOST=0.0.0.0
export TB_PORT=6006

# 統一ログ出力
export ONTOLOGY_SERVER_LOG_DIR="$(pwd)/logs"   # デフォルトもrepo/logsです
# 0に設定すると、各run_*.shが個別のログファイルを生成する旧動作に戻ります
export DISABLE_SCRIPT_LOG_FILES=1

強化学習ヘルパー

export TRAIN_DEVICE=gpu
export RL_OUTPUT_DIR="$(pwd)/data/rl_training"

メモリ

export MEMORY_ENABLED=true
export MEMORY_BACKEND=chromadb
export CHROMA_PERSIST_DIR="data/chroma_memory"
export MEMORY_RETRIEVAL_MODE=recent
export MEMORY_MAX_TURNS=10

config.yamlの例

完全なオプション（DeepSeek/Ollama、メモリ、エージェントのトグル）については、src/agent/config.yaml を参照してください。

🗄️ データベーススキーマ

SQLiteデータベース data/ecommerce.db には12のテーブルが含まれています。

• users、products、cart_items、orders、order_items
• payments、shipments、shipment_tracks
• support_tickets、support_messages、returns、reviews

🎯 ユースケース

1. 検索と推薦: commerce.search_products + 推薦エンジン
2. 完全な購入フロー: 閲覧 → 選択 → カート → チェックアウト → 支払い → 追跡
3. 注文管理: commerce.get_user_orders、キャンセル/返品フロー
4. オントロジー推論: ontology.explain_discount を使用したコンテキストに応じた割引の説明

🤝 コントリビューション

1. プロジェクトをフォークします。
2. git checkout -b feature/AmazingFeature
3. git commit -m 'Add some AmazingFeature'
4. git push origin feature/AmazingFeature
5. プルリクエストを開きます。

🏷️ リリースハイライト

v1.5.3 (2025-12-01) — 確認メモリと完全なツールトレース

• 確認モードの永続化: ユーザーが重要なツール（注文作成/支払い）を承認すると、実行されたツールの引数と観測結果が tool_log、メモリ、および会話状態に書き戻されるようになり、次のターンでは完了した注文が表示され、チェックアウトに戻ることが避けられます。
• 検証ガードの強制停止: ontology_validate_order が重要なツールとしてマークされ、SHACL検証が実行されるまで最終的な回答がブロックされ、注文が確認された直後にエージェントがユーザーに支払いを続行するように促すようになりました。
• エンドツーエンドのツール透過性: ストリーミングイベントが完全な観測ペイロードを送信し、Gradio UIがJSONを切り捨てなくなったため、監査とデバッグが大幅に容易になりました。
• 新しいフィールドレポート: メモリ関連の教訓を記録するために、 が追加されました（英語と中国語のインデックス付き）。これにより、将来の貢献者が回帰を避けることができます。

v1.5.2 (2025-11-29) — ストリーミングトレースのベースライン ✅

• 真のストリーミングパイプライン: react_agent.py がジェネレータベースの run_stream を公開するようになり、DeepSeekアダプターがトークンの差分を送信し、Gradio UIが思考と最終的な回答をトークンごとにレンダリングするようになりました（コミット 505b39e → 7c99e84 → aab0956）。
• 検索精度の向上: 設定可能なマルチストラテジーの意図トラッカー、LLMベースのクエリリライター、FTS5の全文インデックス + ハイブリッドフォールバック（FTS5 → LIKE → カテゴリ）により、「電子製品」などの一般的なクエリの精度が大幅に向上し、ニッチな意図のリコール率も維持されます。
• トレーサビリティツール: が各会話ターンをMermaid図とPNGの証拠で記録し（推薦 → マルチ検索 → チェックアウト → アフターサービス → 分析）、両方のREADMEがこれを指すようになりました。タグ v1.5.2 は、下流の強化学習実験のベースラインをマークしています。

v1.5.1 (2025-11-23)

• インラインチャート（Markdown + Base64 PNG）に意図/ユーザーコンテキストのメタデータが追加され、_filter_charts_by_intent() のプライバシーガードが導入されました。
• analytics_service.py に5つのチャートデータエンドポイントと analytics_get_chart_data MCPツール（22番目の機能）が追加されました。
• 依存関係の調整: plotly>=6.1.0,<7.0.0、kaleido==0.2.1；診断スクリプト（verify_chart_fix.py、test_chart_feature.py）とデータ/ログのバックアップが追加されました。
• トレーニングダッシュボードのUX改善: クリックでコーパスをプレビューできるようになり、同期されたJSONビューが追加され、マルチインスタンスのデバッグ用にホスト/ポートのログが表示されるようになりました。

v1.2.3 (2025-11-15) — リネームと謝辞

• 名称が オントロジー強化学習コマースエージェント に変更され、強化学習のコンテキストが文書化されました。
• Stable Baselines3/Gymnasium/TensorBoardなどへの謝辞が追加されました。
• ツール: 注文IDの検証が追加されて OverflowError を回避し、Ollamaが qwen3:8b をサポートするようになりました。

v1.2.2 (2025-11-12) — READMEの強化学習ガイド

• READMEの冒頭に強化学習のクローズドループの説明が追加され、データ → トレーニング → TensorBoard → デプロイメントが強調されました。

v1.2.0 (2025-11-11) — 動的ユーザーコンテキストシステム

• ユーザーID、電話番号、住所、注文ID、製品IDが自動的に抽出されるようになりました。
• プロンプトの注入により連続性が確保され、正規表現エンジンが多言語/幅のバリエーションを処理するようになりました。
• セットベースの重複排除、厳格な ORD... 検証、製品IDの範囲ガードが導入されました。
• テスト: tests/test_user_context.py

v1.2.1 (2025-11-11) — 最近の注文追跡のホットフィックス

• create_order が有効な ORD... IDの観測/入力解析を強制するようになり、set_recent_order() が呼び出されるようになりました。

v1.1.0 (2025-11-10) — Gradio UIの強化

• 10個のクイックテストボタン（オントロジーとSHACLアクション）が追加されました。
• ストリーミング応答、積極的なボタン状態管理、ジェネレータの修正が行われました。

v1.0.0 (2025-11-08) — 注文検証のベースライン

• 注文作成前に自動的にSHACL検証が行われ、詳細な違反ログが記録されるようになりました。
• プロンプトの改善と100%のルールカバレッジ（割引/配送/返品/コンビネーション）が実現されました。

ベースバージョン (2025-10)

• フェーズ1-5が完了: ORM、オントロジー、21のツール、ReActエージェント、Gradio UI

📦 バージョン履歴

📝 変更履歴

2025-12-01

• 確認ループの永続化: 確認ブランチが実行されたツール（引数 + 観測結果）を tool_log、メモリ、および ConversationState に戻すようになり、後続のターンでは完了した注文がすぐに表示され、チェックアウトを再実行することが避けられます。
• 必須のSHACL検証: ontology_validate_order が CRITICAL_TOOLS リストに追加され、検証が完了するまで最終的な返信がブロックされます。注文が確認された後、エージェントは積極的に支払いを続行するかどうかを尋ねます。
• チャットでの完全なツール出力: ストリーミングイベントが完全なJSON観測結果を含むようになり、Gradio UIが長いペイロードを切り捨てなくなったため、監査とデバッグが簡単になりました。
• 新しい教訓記事: 意図検出と推論にメモリを使用する際の実践的なやり方とやらないことをまとめた docs/articles/12-memory-intent-lessons.md が公開されました。

2025-11-30

• オントロジー優先の推論カバレッジ: ecommerce_ontology.py が割引、物流、返品、キャンセルの4つのフローで ontology_rules.ttl を優先的に読み込むようになり、ルールがヒットした場合は rule_applied を返し、一致するものがない場合は静的な戦略に戻ります。対応する tests/test_commerce_service.py、tests/test_services.py が全量のpytestを通過しています。
• ログの統一と日次ローテーション: すべてのPythonモジュールが logs/server.log に書き込まれるようになり（日次で切り替え、server_YYYYMMDD.log でアーカイブ）、start_all.sh がデフォルトで DISABLE_SCRIPT_LOG_FILES=1 を設定して重複するログを防ぎます。古い動作が必要な場合は手動で0に設定できます。新しい ONTOLOGY_SERVER_LOG_DIR/ONTOLOGY_LOG_BACKUP_COUNT が追加されて、出力ディレクトリと保存日数を制御できるようになりました。
• オントロジーアセットのクリーンアップ: ontology_commerce.ttl と ontology_ecommerce.ttl がSWRLの接頭辞、変数、割引エンティティとルールを補完し、Owlready2/外部エンジンの読み取りがより安定するようになりました。README/設定セクションが新しいログ変数と使用方法を同期して記録しています。

2025-11-29

• 真のストリーミングループ: react_agent.py がジェネレータベースの run_stream を公開するようになり、DeepSeekアダプターがトークンの差分を送信し、Gradio UIが思考と最終的な回答をトークンごとにレンダリングするようになり、透明な推理の再生が可能になりました。
• 意図 + 検索スタック: 設定可能なマルチストラテジーの意図トラッカー、LLM駆動の query_rewriter.py、および commerce_service.py/db_service.py のFTS5→LIKE→カテゴリのフォールバックにより、「電子製品」などの幅広いクエリが大幅に改善され、ニッチな意図のリコール率も維持されます。
• トレーサビリティのあるドキュメント: が5つのログベースのシーケンスをMermaid + PNGの証拠で記録し、READMEがこれにリンクしており、タグ v1.5.2 がバージョン履歴表の新しいベースラインをマークしています。

詳細な中国語の変更履歴は README.zh.md を参照してください（上記の英語のハイライトを反映しています）。

🙏 謝辞

• LangChain & FastAPI – ReActエージェントのオーケストレーション + MCPサーバー
• Gradio – 5タブの電子商取引UIシェル
• ChromaDB & SQLite – セマンティックメモリ + コマースデータ
• Stable Baselines3 / Gymnasium / TensorBoard – 強化学習のトレーニングと可視化
• DeepSeek – LLMプロ