KINGSTON-115/llm-pid-tuner

説明

LLM‑PID‑Tunerは、物理システム（加熱プレート、モーター、オーブンなど）のPIDコントローラーを調整するためのデスクトップツールで、大規模言語モデル（LLM）に新しいP、I、D値を提案させることで動作します。3つのモードで動作します：

ハードウェアモード – Arduino/ESP32（または他のMCU）からシリアルポート経由でライブCSVデータを読み取り、データをLLMに送信し、新しいPIDセットポイントを受信してボードに書き戻します。
ローカルシミュレーター – Pythonの熱システムモデル（simulator.py）を実行し、ハードウェアなしで調整ループを確認できます。
MATLAB/Simulinkモード – MATLABエンジンを介してSimulink PIDブロックを駆動し、LLMに調整させます。このプログラムは、初心者向けに既製のWindows .exeとして配布されていますが、ソースはPythonで直接実行することもできます。

対象ユーザー

PID制御デバイスをすでに持っているが、適切なゲインを見つけるのに苦労しているホビイストやエンジニア。
ハードウェアにコミットする前に、LLM駆動の制御ループ最適化を試してみたい方。
シンプルなシリアルCSVプロトコルまたはSimulinkモデルに慣れているユーザー。

できること（およびできないこと）

機能	詳細
リアルタイムPID提案	センサー/アクチュエータデータを読み取り、パフォーマンス（誤差、オーバーシュート、定常状態）を評価し、LLMに新しいPIDセットポイントを要求し、安全制限を適用し、パフォーマンスが低下した場合はロールバックできます。
視覚化	デスクトップUI（またはTUI）はライブ曲線と現在のPID値を表示し、セットポイントをその場で変更できます（`t`キー）。
ハードウェア統合	シリアルで`timestamp_ms,setpoint,input,pwm,error,p,i,d`をストリーミングする小さなArduino/ESP32ファームウェア（`firmware.cpp`）を使用します。
シミュレーション	`simulator.py`は熱システムを模倣し、ボードなしでループ全体をテストできます。
Simulinkサポート	MATLABエンジンを呼び出してSimulinkモデルを実行し、出力信号を読み取り、PIDブロックを調整します。
オフライン使用	`LLM_API_BASE_URL`をローカルサーバーに設定することで、OpenAI互換のローカルモデル（Ollama、LM Studioなど）で動作します。
魔法のボタンコントローラーではない	完全な制御を保証したり、安全回路を置き換えたり、単独でベンチマークレベルのパフォーマンスを生成したりするものではありません。

始め方（クイックスタート）

最新のリリースからWindows実行可能ファイルをダウンロード（llm‑pid‑tuner.exe）。
提供されたfirmware.cppを実行するボードを接続（または同じCSVシリアル形式に従う任意のデバイス）。config.jsonのSERIAL_PORTをAUTOまたは実際のCOMポートに設定します。
config.jsonを編集 – 最低限、LLMフィールドを入力します：
```
{
  "LLM_API_KEY": "sk‑your‑key",
  "LLM_API_BASE_URL": "https://api.openai.com/v1",
  "LLM_MODEL_NAME": "gpt-4o",
  "LLM_PROVIDER": "openai"
}
```
（URLを変更し、プロバイダーをopenaiのままにすることでローカルモデルも使用できます。）
exeを実行 – ハードウェアモードを選択し、シリアルポートをスキャンさせ、UIが応答をプロットするのを確認します。
観察 – ツールは自動的に新しいPID値を要求し、制限を適用し、新しいパラメータがシステムを悪化させる場合はロールバックします。誤差、オーバーシュート、定常状態の基準が数回連続して満たされると、調整が停止します。

ハードウェアがない場合は、代わりにシミュレーターを実行： pip install -r requirements.txt && python simulator.py。

アーキテクチャ概要

+-------------------+        +-------------------+        +-------------------+
| Local simulator   |  API   | LLM / AI tuner    |  API   | Real hardware     |
| (simulator.py)    |<------>| (tuner.py)        |<------>| (firmware.cpp)    |
+-------------------+        +-------------------+        +-------------------+

シミュレーター：ファームウェアと同じCSVストリームを出力する暖房システムのPythonモデル。
チューナー：コアループ – データ読み取り → 評価 → LLM呼び出し → 安全適用 → 新しいPID書き込み。
ファームウェア：CSVプロトコルを実装し、PIDコントローラーを実行する最小限のArduino/ESP32スケッチ。
デスクトップランチャー（launcher.py）は、ハードウェアとシミュレーションを選択でき、GUIとTUIを切り替えます。
サポートスクリプト：doctor.py（環境チェック）、system_id.py（ステップ応答同定）、pid_safety.py（制限適用）、benchmark.py（開発テスト）。

ツールの設定

config.json – プライマリ設定ファイル。初回実行時に自動生成されます。
主要セクション：
- シリアル：SERIAL_PORT、BAUD_RATE、HARDWARE_PROFILE（デフォルトはgeneric_serial_csv）。
- LLM：APIキー、ベースURL、モデル名、プロバイダー（openai、anthropic、openai_claude、orcarouterなど）。
- 調整動作：GOOD_ENOUGH_AVG_ERROR、GOOD_ENOUGH_OVERSHOOT、REQUIRED_STABLE_ROUNDSなどのしきい値。
- Simulink：.slxファイル、PIDブロック、出力信号、オプションのMATLABルートへのパス。
- オプション：プロキシ設定、CSVエクスポートパス、カスタムプロンプトオーバーライド。
環境変数はJSON値をオーバーライドします。これはCIやシークレット管理に便利です。

拡張/カスタマイズ

プロンプト調整 – セッション開始時に自然言語の好みを入力するか（調整前ダイアログ）、llm/prompts.pyを編集してLLMが受け取るシステムプロンプトを変更します。
新しいハードウェアプロファイルの追加 – 期待されるCSV列またはカスタムパーサーを実装し、プロファイル名をconfig.jsonにリストします。
LLMの交換 – OpenAI /v1/chat/completionsスキーマに従う任意のサービスが動作します。LLM_API_BASE_URLとLLM_PROVIDERを変更するだけです。
貢献 – リポジトリは最新機能用のdevブランチとリリース用の安定mainブランチを使用しています。

安全上の注意

チューナーはPIDゲインを提案するだけであり、ハードウェアの安全回路を置き換えるものではありません。暖房機器を扱う際は、常に温度制限、ウォッチドッグタイマー、物理的なキルスイッチを維持してください。

ライセンス

MIT – コードを自由に使用、変更、再配布できます。