oproxy/README.md

# oproxy.py - The Strategic AI Proxy for Local LLMs

`oproxy.py` は、RTX 3060 (12GB) などのローカル環境で **Cline** や **Zed** といった AI Agent を極限まで効率よく運用するために設計された、高機能・対話型リバースプロキシです。

## 🛠 主要機能 (Features)

### 1. ⚡ 魂のカラー・パルス (Visual Pulse)

AIとの通信状況をコンソール上にリアルタイムで可視化します。

* **`^^^^` (Cyan)**: リクエスト送信中（サイズに応じて脈動）。
* **`|` (Yellow)**: ターゲットへの到達。
* **`vvvv` (Green)**: レスポンス（ストリーミング）受信中。
* **`*` (Yellow)**: 通信の正常完了。

### 2. 🧠 戦略的モデル分析 (Strategic Analysis: `l` / `ll`)

単なるモデル一覧ではありません。12GB VRAM という「戦場」を生き抜くための分析を行います。

* **カラー判定**:
* **GREEN**: VRAMに余裕を持って収まる安全圏。
* **YELLOW**: 12GBの限界に近い。他のアプリを閉じないと溢れる可能性あり。
* **RED**: 12GBを超過。システムRAM（CPU推論）に溢れ、速度が極端に低下する警告。


* **詳細表示 (`ll`)**: パラメータサイズ、量子化ビット数（Q4, Q3等）を瞬時に把握。

### 3. 📉 VRAM リアルタイム監視 (VRAM Status: `s`)

Ollama の内部 API (`/api/ps`) を叩き、現在 VRAM にどのモデルがロードされ、何 GB 専有しているかを色付きで表示します。

### 4. 🔍 インテリジェント・データダンプ (Smart Dump: `d` / `dd`)

AI Agent (Cline 等) が「なぜか思い通りに動かない」時の強力なデバッグツールです。

* **`d`**: **次の1リクエストだけ**、その中身（JSON）を美しく整形してぶちまけます。
* **`dd`**: ダンプ予約のキャンセル。
* **自動オフ**: 1回ダンプすると自動的にOFFに戻るため、ログが汚れるのを防ぎます。

### 5. 🏗 動的ターゲット・スイッチ (Dynamic Switching)

プロキシを再起動することなく、ポート番号（例: `11432`, `11435`）を直接打ち込むだけで、背後の Ollama インスタンスを瞬時に切り替えます。

---

## ⌨️ コマンドリファレンス (Commands)

| コマンド | 機能 |
| --- | --- |
| **`l`** | モデルリストを表示（サイズに応じた色分け分析付き） |
| **`ll`** | 量子化ビット数を含む、詳細なモデル分析を表示 |
| **`s`** | 現在の VRAM 使用状況（どのモデルが専有中か）を表示 |
| **`d`** | **[DUMP ON]** 次のリクエスト・レスポンスを完全表示 |
| **`dd`** | **[DUMP OFF]** ダンプ予約の解除 |
| **`数字`** | ターゲットとする Ollama のポート番号を即時変更 |
| **`q`** | プロキシの安全な終了 |

---

## 🚀 導入のメリット

1. **Agent対応の判断**: `d` でダンプを見れば、モデルが正しく「ツール呼び出し（JSON）」を行っているか一目瞭然です。
2. **30bモデルの運用**: RTX 3060 で 30b クラスを動かす際、`s` と `l` の分析により「あ、これはQ3量子化じゃないと無理だ」といった戦略的な判断が可能になります。
3. **長考への耐性**: 600秒のタイムアウト設定により、巨大モデルの深い思考（Reasoning）を途中で遮断しません。