upload: README.md

README.md

@@ -1,10 +1,135 @@
----
-title: Level Bridge Chat
-emoji: 😻
-colorFrom: green
-colorTo: blue
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: Level Bridge Chat
+emoji: 💬
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+pinned: false
+---
+
+# Level Bridge Chat
+
+ダッシュボードに埋め込めるチャット型広告改善提案システム。
+
+情報量（level1〜3）に応じた2種類の返答を自動生成します:
+- **現在の提案**: 今ある情報で出せる最善提案
+- **次レベル予告**: 追加情報で何が可能になるかの予告
+
+## Embedding
+
+```html
+<!-- 基本埋め込み -->
+<iframe
+  src="https://your-space.hf.space?campaign_name=サマーセール&industry=EC&cvr=2.1"
+  width="420"
+  height="680"
+  style="border:none; border-radius:12px;">
+</iframe>
+```
+
+### URLパラメータ（初期化）
+
+| パラメータ | 型 | 説明 | 例 |
+|---|---|---|---|
+| `campaign_name` | string | キャンペーン名 | `サマーセール` |
+| `industry` | string | 業界 | `EC` |
+| `cvr` | number | CVR (%) | `2.1` |
+| `ctr` | number | CTR (%) | `0.8` |
+| `cpa` | number | CPA (円) | `3500` |
+
+## API Endpoint
+
+```
+POST /api/chat/bridge
+Content-Type: application/json
+
+{
+  "session_id": null,
+  "message": "",
+  "dashboard_context": {
+    "campaign_name": "サマーセール",
+    "industry": "EC",
+    "metrics": { "cvr": 2.1, "ctr": 0.8, "cpa": null },
+    "image_base64": null
+  }
+}
+```
+
+### Response
+
+```json
+{
+  "ok": true,
+  "session_id": "uuid",
+  "turn_number": 1,
+  "inferred_level": "level2",
+  "level_confidence": "high",
+  "level_reason": "at least one metric present",
+  "best_now": {
+    "summary": "...",
+    "actions": ["..."],
+    "confidence": "mid",
+    "reasoning_basis": ["cvr", "campaign_name"]
+  },
+  "next_level_preview": {
+    "current_level": "level2",
+    "next_level": "level3",
+    "needed_info": [{"key": "image_base64", "label": "クリエイティブ画像", "example": "バナー画像"}],
+    "what_will_be_possible": ["クリエイティブ要素の具体的改善提案"],
+    "expected_impact": "..."
+  },
+  "follow_up_question": "..."
+}
+```
+
+## Level Rules
+
+| Level | 条件 | 今できること |
+|---|---|---|
+| level1 | campaign_name or industry のみ | 業界仮説ベースの提案 |
+| level2 | CVR/CTR/CPA のいずれかあり | ファネル診断・優先度付き打ち手 |
+| level3 | image_base64 あり | クリエイティブ視覚要素の改善提案 |
+
+Level は会話内で上方向にのみ更新されます（情報は蓄積され続けます）。
+
+## Environment Variables
+
+| 変数 | デフォルト | 説明 |
+|---|---|---|
+| `MOCK_MODE` | `true` | `true` の間はモック応答を返す |
+| `SESSION_TTL_SEC` | `1800` | セッション有効期間（秒） |
+| `MAX_SESSIONS` | `1000` | 最大同時セッション数 |
+| `MAX_IMAGE_SIZE_MB` | `5` | 画像の最大サイズ（MB） |
+| `PORT` | `7860` | サーバーポート |
+
+## Real Implementation
+
+`mock_responses.py` の以下の関数を実装してください:
+
+```python
+def level1_propose(ctx: AccumulatedContext, history: list) -> BestNow:
+    # Level 1 の実際のロジック（LLM呼び出しなど）
+    ...
+
+def level2_propose(ctx: AccumulatedContext, history: list) -> BestNow:
+    # Level 2 の実際のロジック
+    ...
+
+def level3_propose(ctx: AccumulatedContext, history: list) -> BestNow:
+    # Level 3 の実際のロジック（画像base64を ctx.image_base64 で参照）
+    ...
+```
+
+実装後、`MOCK_MODE=false` に設定します。
+
+## MCP Readiness
+
+将来 MCP ツールとして公開する場合、`bridge_service.process_request()` を薄くラップするだけで対応できます。
+Pydantic モデルがそのまま JSON Schema になります。
+
+## Health Check
+
+```
+GET /healthz
+→ {"ok": true, "sessions": 42}
+```