claude-code-conductor 2.22.0__tar.gz → 2.24.0__tar.gz

{claude_code_conductor-2.22.0 → claude_code_conductor-2.24.0}/.claude/hooks/select_tier.py

@@ -31,6 +31,7 @@ import os
 import random
 import re
 import sys
+from typing import NamedTuple
 from pathlib import Path
 
 try:
@@ -110,6 +111,69 @@ _PROMPT_HISTORY_SCAN_LINES = 1000
 
 TIERS: tuple[str, ...] = ("haiku", "sonnet", "opus")
 
+# cost-aware tie-break の拮抗判定閾値（v2.23.0）。
+# Beta サンプルは 0〜1 スケール。成功率 5pt 以内＝実質同等とみなす拮抗判定閾値。
+# 過大は成功率犠牲リスク、過小は無発動。調整可能化は v2.24.0。
+EPSILON: float = 0.05
+
+
+class SelectionResult(NamedTuple):
+    """select_tier_detailed の戻り値（NamedTuple = immutable）。
+
+    tier: 選択された tier 名。
+    mode: "uniform" または "thompson"。
+    cost_tiebreak: Thompson 分岐で cost tie-break が発動した場合 True。
+    contenders: 拮抗判定に入った tier のタプル（observability/デバッグ用）。
+        frozen 安全のため list ではなく tuple を使用。
+    """
+
+    tier: str
+    mode: str
+    cost_tiebreak: bool = False
+    contenders: tuple[str, ...] = ()
+
+
+def _cost_tiebreak(
+    samples: dict[str, float],
+    cost_map: dict[str, float] | None,
+    *,
+    epsilon: float = EPSILON,
+) -> tuple[str, bool, tuple[str, ...]]:
+    """Thompson サンプル拮抗群内で min-max 正規化コストが最安の tier を返す。
+
+    Args:
+        samples: {tier: beta_sample} の dict（Thompson Sampling 結果）。
+        cost_map: {tier: cost} の dict。None なら cost を見ず従来挙動。
+            cost は実測 rate_usd_per_mtok または静的参照単価（ハイブリッド）。
+            v2.24.0 で rate 化（USD/MTok）により実測・静的とも同次元で整合済み。
+            ``cost_map`` は None、または contenders 全件をキーとして含む dict を
+            渡すこと。partial dict を渡すと ``cost_map[t]`` で KeyError が発生する。
+            ``select_tier_detailed`` 経由では呼び出し側（main）が全 TIERS 分を
+            構築して保証する。
+        epsilon: 拮抗判定の閾値（デフォルト EPSILON=0.05）。
+
+    Returns:
+        (chosen, did_tiebreak, contenders) のタプル。
+        - chosen: 選択された tier 名。
+        - did_tiebreak: cost tie-break が発動した場合 True。
+        - contenders: 拮抗判定に入った tier のタプル。
+    """
+    max_sample = max(samples.values())
+    contenders = [t for t in samples if max_sample - samples[t] <= epsilon]
+
+    if len(contenders) <= 1 or cost_map is None:
+        # 従来挙動と完全一致: max(samples, key=lambda t: samples[t]) と同じ式
+        chosen = max(samples, key=lambda t: samples[t])
+        return chosen, False, tuple(contenders)
+
+    # 拮抗群内で min-max 正規化コストを計算し最安 tier を選ぶ
+    costs = {t: cost_map[t] for t in contenders}
+    lo, hi = min(costs.values()), max(costs.values())
+    norm = {t: ((costs[t] - lo) / (hi - lo) if hi > lo else 0.0) for t in contenders}
+    # 同値安定 tie-break: norm 同値時はサンプル大（=従来選好）を優先 → 決定論
+    chosen = min(contenders, key=lambda t: (norm[t], -samples[t]))
+    return chosen, True, tuple(contenders)
+
 
 def _prompt_prefix_and_hash(prompt: str) -> tuple[str, str]:
     """prompt から (prefix, hash) を抽出する。
@@ -226,34 +290,67 @@ def estimate_complexity(prompt: str) -> str:
     return "medium"
 
 
-def select_tier(
+def select_tier_detailed(
     params: dict[str, tuple[float, float, int]],
     *,
     rng: random.Random | None = None,
-) -> tuple[str, str]:
-    """Beta サンプリングまたは uniform 選択で推奨 Tier を返す。
+    cost_map: dict[str, float] | None = None,
+) -> SelectionResult:
+    """Beta サンプリングまたは uniform 選択で推奨 Tier を SelectionResult で返す。
 
     Args:
         params: ``read_tier_params`` の戻り値。
             ``{"haiku": (alpha, beta, trials), ...}``
         rng: テスト用に決定論的にしたい場合は ``random.Random(seed)`` を渡す。
+        cost_map: {tier: cost} の dict、または None。
+            None（cost を見ない＝従来 Thompson）または「params の全 tier キーを
+            含む完全な dict」のいずれか。partial dict は渡されない前提
+            （呼び出し側が全 TIERS 分を構築して保証する）。
+            uniform 分岐では cost_map の有無に関わらず完全無視する（探索保護）。
 
     Returns:
-        ``(tier, mode)`` のタプル。``mode`` は ``"thompson"`` / ``"uniform"`` で、
-        プロンプトに「学習データ収集中」と表示するかの分岐に使う。
+        SelectionResult（tier, mode, cost_tiebreak, contenders）。
+        mode は ``"thompson"`` / ``"uniform"``。
     """
     rng = rng or random
     total_trials = sum(p[2] for p in params.values())
     if total_trials < LEARNING_THRESHOLD:
-        return rng.choice(TIERS), "uniform"
+        # uniform: cost を完全無視・従来挙動完全維持
+        return SelectionResult(rng.choice(TIERS), "uniform", False, ())
 
-    # 純 Thompson Sampling: 各 tier の Beta(α, β) からサンプリング、最大値を選ぶ
+    # Thompson Sampling: rng の消費順序を従来 select_tier と完全一致させる
     samples = {
         tier: rng.betavariate(p[0], p[1])
         for tier, p in params.items()
     }
-    chosen = max(samples, key=lambda t: samples[t])
-    return chosen, "thompson"
+    chosen, did_tiebreak, contenders = _cost_tiebreak(samples, cost_map)
+    return SelectionResult(chosen, "thompson", did_tiebreak, contenders)
+
+
+def select_tier(
+    params: dict[str, tuple[float, float, int]],
+    *,
+    rng: random.Random | None = None,
+    cost_map: dict[str, float] | None = None,
+) -> tuple[str, str]:
+    """Beta サンプリングまたは uniform 選択で推奨 Tier を返す。
+
+    Args:
+        params: ``read_tier_params`` の戻り値。
+            ``{"haiku": (alpha, beta, trials), ...}``
+        rng: テスト用に決定論的にしたい場合は ``random.Random(seed)`` を渡す。
+        cost_map: {tier: cost} の dict、または None。
+            None なら cost を見ず従来の Thompson Sampling と完全一致。
+            uniform 分岐では cost_map の有無に関わらず完全無視する。
+            詳細は :func:`select_tier_detailed` を参照。
+
+    Returns:
+        ``(tier, mode)`` のタプル。``mode`` は ``"thompson"`` / ``"uniform"`` で、
+        プロンプトに「学習データ収集中」と表示するかの分岐に使う。
+        戻り値型は v2.22.0 以前と完全に不変。
+    """
+    result = select_tier_detailed(params, rng=rng, cost_map=cost_map)
+    return result.tier, result.mode
 
 
 # Phase 2-B: 失敗率による昇格マッピング（haiku → sonnet, sonnet → opus）。
@@ -324,6 +421,7 @@ def write_tier_selection(
     prompt_prefix: str | None = None,
     prompt_hash: str | None = None,
     session_id: str | None = None,
+    cost_tiebreak: bool = False,
 ) -> None:
     """直近の選択結果を ``tier_selection.json`` に書く。
 
@@ -339,6 +437,10 @@ def write_tier_selection(
 
     ``session_id`` を任意で含める。UserPromptSubmit payload の session UUID。
     None のときは tier_selection.json のキー自体を省略する（後方互換）。
+
+    ``cost_tiebreak`` を任意で含める（v2.23.0）。
+    Thompson Sampling の拮抗群内で cost tie-break が発動した場合のみ True。
+    False のときはキー自体を省略する（escalated/session_id と同パターン）。
     """
     os.makedirs(os.path.dirname(TIER_SELECTION_PATH), exist_ok=True)
     payload: dict[str, object] = {
@@ -360,6 +462,8 @@ def write_tier_selection(
         payload["prompt_hash"] = prompt_hash
     if session_id is not None:
         payload["session_id"] = session_id
+    if cost_tiebreak:
+        payload["cost_tiebreak"] = True
     try:
         with open(TIER_SELECTION_PATH, "w", encoding="utf-8") as f:
             json.dump(payload, f, ensure_ascii=False)
@@ -376,8 +480,13 @@ def build_additional_context(
     *,
     escalation_reason: str | None = None,
     complexity_source: str | None = None,
+    cost_tiebreak: bool = False,
 ) -> str:
-    """親 Claude に追加注入する文字列を組み立てる。"""
+    """親 Claude に追加注入する文字列を組み立てる。
+
+    ``cost_tiebreak`` が True のとき、suffix に cost-aware 発動を示す文言を追加する（v2.23.0）。
+    False のときは不変（既存文言と完全一致）。
+    """
     trials = sum(p[2] for p in params.values())
     if mode == "uniform":
         confidence = f"学習データ収集中（合計 {trials}/{LEARNING_THRESHOLD} 試行）"
@@ -390,6 +499,8 @@ def build_additional_context(
         suffix += f" [Phase 2-B 昇格: {escalation_reason}]"
     if complexity_source:
         suffix += f" [複雑度判定: {complexity_source}]"
+    if cost_tiebreak:
+        suffix += " [cost-aware: 成功率拮抗のため低コスト Tier を選択]"
 
     return (
         f"[tier-routing 推奨] 複雑度: {complexity} / 推奨 Tier: {tier}（{confidence}）。"
@@ -445,7 +556,29 @@ def main() -> int:
     else:
         params = c3_db.read_tier_params(complexity)
 
-    tier, mode = select_tier(params)
+    # v2.24.0: cost_map をハイブリッド解決（実測 rate USD/MTok を主に、欠損 tier は静的単価で補完）。
+    # rate 化により measured(実測)と tier_reference_cost(静的)が同次元（USD/MTok）になり単位整合済み。
+    # c3_db が None または pricing import 失敗時は cost_map=None で従来 Thompson にデグレード。
+    # cost_map=None の場合、select_tier_detailed/_cost_tiebreak は従来 Thompson 挙動と完全一致（引数定義参照）。
+    cost_map = None
+    if c3_db is not None:
+        try:
+            from c3 import pricing  # type: ignore[import-not-found]
+            measured = c3_db.read_tier_cost_rate_for_complexity(complexity)  # {tier: rate USD/MTok} 実測>0 のみ
+            cost_map = {}
+            for tier_name in TIERS:
+                if tier_name in measured and measured[tier_name] > 0:
+                    cost_map[tier_name] = measured[tier_name]
+                else:
+                    # tier_reference_cost は未知 tier に 0.0 を返すが、TIERS と _TIER_REFERENCE_KEY は
+                    # 同期前提のため現行 3 tier（haiku/sonnet/opus）では 0.0 混入は起きない。
+                    cost_map[tier_name] = pricing.tier_reference_cost(tier_name)  # 静的 fallback
+        except ImportError:
+            cost_map = None
+
+    result = select_tier_detailed(params, cost_map=cost_map)
+    tier, mode = result.tier, result.mode
+    cost_tiebreak = result.cost_tiebreak
 
     # Phase 2-B: failure rate に基づく escalation
     effective_tier, escalation_reason = maybe_escalate(complexity, tier)
@@ -457,12 +590,14 @@ def main() -> int:
         prompt_prefix=prompt_prefix,
         prompt_hash=prompt_hash,
         session_id=session_id,
+        cost_tiebreak=cost_tiebreak,
     )
 
     context_text = build_additional_context(
         complexity, effective_tier, mode, params,
         escalation_reason=escalation_reason,
         complexity_source=complexity_source,
+        cost_tiebreak=cost_tiebreak,
     )
     output = {
         "hookSpecificOutput": {

{claude_code_conductor-2.22.0 → claude_code_conductor-2.24.0}/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## [2.24.0] - 2026-05-25
+
+**tier-routing cost 精度向上**: tie-break が使う cost データを model 一致集計・USD/MTok レート化により信頼できるものにする。新関数 2 つを追加し、`select_tier` の cost_map 源を rate 関数へ切替。既存関数・tie-break ロジックは完全不変。
+
+**スコープ注記**:
+- `tier_bandit.total_cost_usd`/`cost_samples` への書き込み・cost-weighted Thompson 本格統合は **v2.25.0+**。
+- migration なし。**破壊的変更なし**（新関数追加・cost_map 値の意味変更のみ・既存関数 docstring 含め完全不変）。
+
+### 機能追加
+
+- **`src/c3/db.py`: `read_tier_cost_rate_summary(*, db_path=None) -> list[dict]`（新規）**: model 一致集計・(session, tier) 重複排除・USD/MTok レート化を行う精度向上版の cost 集計関数。`agent_cost_runs` を `agent_type <> 'mainline'` で読み、Python 側で `pricing.resolve_tier(model)` により tier 振り分け。`(session_id, tier)` 粒度で集約後、`tier_recent_outcomes` と突合して `(complexity, tier)` 別に集計。`rate_usd_per_mtok = total_cost_usd / (billable_tokens / 1_000_000)`（`billable_tokens = input_tokens + output_tokens`）で `tier_reference_cost`（USD/MTok）と同次元にする。`billable_tokens == 0` の (complexity,tier) は除外。未知 model 行はスキップ。戻り値 dict キー: `complexity / tier / sessions / total_cost_usd / billable_tokens / rate_usd_per_mtok`。内部畳み込み部は DB 非依存の純関数 `_compute_tier_cost_rate_summary` に分離。
+
+- **`src/c3/db.py`: `read_tier_cost_rate_for_complexity(complexity, *, db_path=None) -> dict[str, float]`（新規）**: `read_tier_cost_rate_summary` を complexity 一致 & `rate_usd_per_mtok > 0` でフィルタし `{tier: rate_usd_per_mtok}` を返す薄いラッパー（v2.23.0 の `read_tier_cost_for_complexity` と対称）。データ/DB 不在で `{}`。
+
+### 変更
+
+- **`.claude/hooks/select_tier.py`**: `main()` の cost_map 構築で `read_tier_cost_for_complexity` → `read_tier_cost_rate_for_complexity` に切替。tie-break ロジック不変・cost_map の値の意味が絶対 USD → USD/MTok レートに変化し、静的 `tier_reference_cost` と単位整合。コメント更新（「混在スケール・厳密化は v2.24.0」→「v2.24.0 で rate 化により整合済み」）。
+
+- **`src/c3/cli_tier.py`**: `c3 tier stats` に「Tier 別 USD/MTok レート（model 一致・tie-break が使用）」セクションを追加（complexity/tier/sessions/rate_usd_per_mtok 表示・データなしで「（rate データ未収集）」）。既存 session 合計 USD セクションも維持。「精度向上は v2.24.0」注記を「（粗い概算・session 合計 USD）」に更新。`--json` 出力に `tier_cost_rate` キー自動反映。DB 由来テキストへ `sanitize_terminal_text` 適用。
+
+- **`src/c3/__init__.py`**: `__version__` を `"2.23.0"` から `"2.24.0"` に更新。
+
+### 後方互換
+
+- 既存 `read_tier_cost_summary` / `read_tier_cost_for_complexity` は docstring 含め完全不変。
+- migration なし（`agent_cost_runs` の token 4 列 + model 列は v2.21.0 (002 migration) で既存）。
+
+## [2.23.0] - 2026-05-25
+
+**tier-routing cost-aware tie-break**: `select_tier` の Thompson Sampling 分岐に「拮抗 tier 群内コスト tie-break」を追加する。サンプル最大から ε(=0.05) 以内の拮抗 tier が複数ある場合のみ、min-max 正規化コストが最安の tier を選ぶ。単独最大なら従来通り（挙動不変）。成功率を犠牲にしない最小スコープの cost 統合。
+
+**スコープ注記**:
+- **最小スコープ＝tie-break のみ**。精度向上（model 一致集計・agent_id 単位紐づけ）と `tier_bandit.total_cost_usd`/`cost_samples` への書き込みは **v2.24.0**。
+- cost は**ハイブリッド源**（実測 avg_cost を主・欠損 tier は静的参照単価で補完）。実測 USD と静的 per-MTok の混在スケールは min-max 正規化で**拮抗群内の概算順位**に畳む（厳密な単位整合は v2.24.0）。
+- LEARNING_THRESHOLD(30) 未満は cost 完全無視（uniform のまま・探索保護）。escalation は不変。
+- migration なし（読み出しのみ・書き込みなし）。**破壊的変更なし**（optional kw-only 引数追加・None/False 時従来動作・出力キー条件付き追加のみ）。
+
+### 機能追加
+
+- **`src/c3/pricing.py`: `tier_reference_cost(tier) -> float`（新規）**: tier 名から input+output 静的参照単価和を返す純関数。haiku < sonnet < opus の単調性を保証。未知 tier は 0.0 を返す。`_TIER_REFERENCE_KEY` 定数で TIERS との同期チェックを明示。
+
+- **`src/c3/db.py`: `read_tier_cost_for_complexity(complexity, *, db_path=None) -> dict[str, float]`（新規）**: `read_tier_cost_summary` を complexity 一致・avg_cost_usd > 0 でフィルタし `{tier: avg_cost_usd}` を返す薄いラッパー。テーブル不在・データ不在・DB 不在で `{}`。
+
+- **`.claude/hooks/select_tier.py`**: `EPSILON=0.05` 定数 / `SelectionResult`（NamedTuple: tier/mode/cost_tiebreak/contenders）/ `_cost_tiebreak`（拮抗群 min-max 最安・同値はサンプル大優先で決定論）/ `select_tier_detailed(params, *, rng, cost_map)`（2 層 API の詳細版）を追加。
+
+### 変更
+
+- **`.claude/hooks/select_tier.py`**: `select_tier` に kw-only `cost_map=None` を追加し `select_tier_detailed` への委譲に変更（**戻り値型 (tier, mode) 不変**）。`write_tier_selection`/`build_additional_context` に `cost_tiebreak: bool = False` を追加（True 時のみ json キー追加 / context suffix「[cost-aware: 成功率拮抗のため低コスト Tier を選択]」追記）。`main()` で cost_map をハイブリッド解決し `select_tier_detailed` を使用（c3_db/pricing import 失敗時は cost_map=None で従来 Thompson にデグレード）。
+
+- **`src/c3/__init__.py`**: `__version__` を `"2.22.0"` から `"2.23.0"` に更新。
+
+- **注記更新**: `c3 tier stats` の「精度向上は v2.23.0」を「精度向上は v2.24.0」へ、「cost-aware routing 本体は v2.23.0 予定」を「cost-aware routing 本体（tie-break）実装済み。精度向上は v2.24.0 予定」へ更新。
+
 ## [2.22.0] - 2026-05-25
 
 **tier-routing cost 紐づけデータ蓄積**: tier_recent_outcomes に session_id 列を追加し、agent_cost_runs と JOIN できるデータ基盤を整備する。`c3 tier stats` に complexity×tier 別の平均コストセクションを追加する。cost-aware routing 本体は v2.23.0。

{claude_code_conductor-2.22.0 → claude_code_conductor-2.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-conductor
-Version: 2.22.0
+Version: 2.24.0
 Summary: Multi-agent orchestration framework for Claude Code with Codex/Cursor adapters (C3)
 Project-URL: Homepage, https://github.com/satoh-y-0323/claude-code-conductor
 Project-URL: Repository, https://github.com/satoh-y-0323/claude-code-conductor

{claude_code_conductor-2.22.0 → claude_code_conductor-2.24.0}/src/c3/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Conductor (C3) - multi-agent orchestration framework for Claude Code."""
 
-__version__ = "2.22.0"
+__version__ = "2.24.0"

{claude_code_conductor-2.22.0 → claude_code_conductor-2.24.0}/src/c3/cli_tier.py

@@ -22,6 +22,7 @@ import sys
 from typing import Any
 
 from c3 import db as c3_db
+from c3._terminal import sanitize_terminal_text
 
 
 logger = logging.getLogger(__name__)
@@ -118,6 +119,8 @@ def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
 
     tier_cost: list[dict[str, Any]] = c3_db.read_tier_cost_summary(db_path=db_path)
 
+    tier_cost_rate: list[dict[str, Any]] = c3_db.read_tier_cost_rate_summary(db_path=db_path)
+
     if total_trials < _LEARNING_THRESHOLD:
         mode = "uniform"
     else:
@@ -133,6 +136,7 @@ def _collect_snapshot(db_path, recent_limit: int) -> dict[str, Any]:
         "recent_outcomes": recent_outcomes,
         "agent_cost": agent_cost,
         "tier_cost": tier_cost,
+        "tier_cost_rate": tier_cost_rate,
     }
 
 
@@ -184,9 +188,10 @@ def _render_human(snapshot: dict[str, Any]) -> None:
             f"{'in_tok':>9}  {'out_tok':>9}  {'cache_r':>9}  {'cache_w':>9}"
         )
         for row in agent_cost:
-            note = "  （マクロ集計・tier 学習対象外）" if row["agent_type"] == "mainline" else ""
+            agent_type_safe = sanitize_terminal_text(str(row["agent_type"]))
+            note = "  （マクロ集計・tier 学習対象外）" if agent_type_safe == "mainline" else ""
             print(
-                f"{row['agent_type']:<16} {row['runs']:>5}  "
+                f"{agent_type_safe:<16} {row['runs']:>5}  "
                 f"${row['total_cost_usd']:>9.4f}  "
                 f"{row['input_tokens']:>9}  {row['output_tokens']:>9}  "
                 f"{row['cache_read_tokens']:>9}  {row['cache_create_tokens']:>9}"
@@ -194,18 +199,37 @@ def _render_human(snapshot: dict[str, Any]) -> None:
             )
     print()
 
-    print("== Tier 別平均コスト（粗い概算 / 精度向上は v2.23.0） ==")
+    print("== Tier 別平均コスト（粗い概算・session 合計 USD） ==")
     tier_cost = snapshot.get("tier_cost", [])
     if not tier_cost:
         print("（cost 紐づけデータ未収集）")
     else:
         print(f"{'complexity':<12} {'tier':<8} {'sessions':>8}  {'avg_usd':>10}  {'total_usd':>10}")
         for row in tier_cost:
+            complexity_safe = sanitize_terminal_text(str(row["complexity"]))
+            tier_safe = sanitize_terminal_text(str(row["tier"]))
             print(
-                f"{row['complexity']:<12} {row['tier']:<8} "
+                f"{complexity_safe:<12} {tier_safe:<8} "
                 f"{row['sessions']:>8}  "
                 f"${row['avg_cost_usd']:>9.4f}  "
                 f"${row['total_cost_usd']:>9.4f}"
             )
     print()
-    print("（注: データ紐づけ蓄積。cost-aware routing 本体は v2.23.0 予定）")
+    print("（注: 粗い概算・session 合計 USD。v2.24.0 より rate セクション追加済み）")
+    print()
+
+    print("== Tier 別 USD/MTok レート（model 一致・tie-break が使用） ==")
+    tier_cost_rate = snapshot.get("tier_cost_rate", [])
+    if not tier_cost_rate:
+        print("（rate データ未収集）")
+    else:
+        print(f"{'complexity':<12} {'tier':<8} {'sessions':>8}  {'rate_usd_per_mtok':>18}")
+        for row in tier_cost_rate:
+            complexity_safe = sanitize_terminal_text(str(row["complexity"]))
+            tier_safe = sanitize_terminal_text(str(row["tier"]))
+            print(
+                f"{complexity_safe:<12} {tier_safe:<8} "
+                f"{row['sessions']:>8}  "
+                f"{row['rate_usd_per_mtok']:>18.4f}"
+            )
+    print()