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

{claude_code_conductor-2.22.0 → claude_code_conductor-2.23.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 は実測 avg_cost_usd または静的参照単価（ハイブリッド）。
+            混在スケール（USD vs per-MTok）の厳密化は v2.24.0。
+            ``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,28 @@ def main() -> int:
     else:
         params = c3_db.read_tier_params(complexity)
 
-    tier, mode = select_tier(params)
+    # v2.23.0: cost_map をハイブリッド解決（実測 avg_cost を主に、欠損 tier は静的単価で補完）。
+    # 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_for_complexity(complexity)  # {tier: avg} 実測>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 +589,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.23.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [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.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-conductor
-Version: 2.22.0
+Version: 2.23.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.23.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.23.0"

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

@@ -194,7 +194,7 @@ def _render_human(snapshot: dict[str, Any]) -> None:
             )
     print()
 
-    print("== Tier 別平均コスト（粗い概算 / 精度向上は v2.23.0） ==")
+    print("== Tier 別平均コスト（粗い概算 / 精度向上は v2.24.0） ==")
     tier_cost = snapshot.get("tier_cost", [])
     if not tier_cost:
         print("（cost 紐づけデータ未収集）")
@@ -208,4 +208,4 @@ def _render_human(snapshot: dict[str, Any]) -> None:
                 f"${row['total_cost_usd']:>9.4f}"
             )
     print()
-    print("（注: データ紐づけ蓄積。cost-aware routing 本体は v2.23.0 予定）")
+    print("（注: cost-aware routing 本体（tie-break）実装済み。精度向上は v2.24.0 予定）")

{claude_code_conductor-2.22.0 → claude_code_conductor-2.23.0}/src/c3/db.py

@@ -759,6 +759,39 @@ def read_tier_cost_summary(
     ]
 
 
+def read_tier_cost_for_complexity(
+    complexity: str,
+    *,
+    db_path: Path | None = None,
+) -> dict[str, float]:
+    """complexity 別の tier 平均コストを {tier: avg_cost_usd} で返す。
+
+    tie-break のハイブリッド cost 源（実測 avg_cost）。
+    complexity 一致 & avg_cost_usd > 0 のみ。
+    ``read_tier_cost_summary`` の薄いラッパー。
+
+    DB アクセスは ``read_tier_cost_summary`` に委譲するため、
+    DB 例外処理・busy_timeout・read 規約は同関数から継承される。
+    データ/DB 不在で ``read_tier_cost_summary`` が ``[]`` を返す場合、
+    本関数は ``{}`` を返す。
+
+    Args:
+        complexity: フィルタ対象の complexity 値（"simple" / "medium" / "complex"）。
+        db_path: c3.db のパス。省略時は :func:`locate_c3_db` で探索
+                 （``read_tier_cost_summary`` に委譲）。
+
+    Returns:
+        ``{tier: avg_cost_usd}`` の dict。
+        該当データ不在・DB 不在・エラー時は ``{}``。
+    """
+    rows = read_tier_cost_summary(db_path=db_path)
+    return {
+        r["tier"]: r["avg_cost_usd"]
+        for r in rows
+        if r["complexity"] == complexity and r["avg_cost_usd"] > 0
+    }
+
+
 def get_ingest_offset(
     file_key: str,
     *,

{claude_code_conductor-2.22.0 → claude_code_conductor-2.23.0}/src/c3/pricing.py

@@ -10,6 +10,7 @@
   - resolve_tier(model) -> str | None
   - compute_cost_usd(...) -> tuple[float, bool]
   - known_models() -> tuple[str, ...]
+  - tier_reference_cost(tier) -> float
 
 設計判断（plan-report T1 §2):
   Opus は世代で単価が約 3 倍異なる（4.1/4 = $15 系、4.5/4.6/4.7 = $5 系）ため、
@@ -148,6 +149,46 @@ def compute_cost_usd(
     return (cost, True)
 
 
+# ---------------------------------------------------------------------------
+# tier → 参照単価マッピング（v2.23.0 T1）
+# tie-break 静的 fallback 用。tier 名から _PRICING キーへの対応表。
+# 注意: select_tier.py の TIERS と同期必須。新 tier を TIERS に追加する場合は
+# 本 dict も更新すること（未更新だと tier_reference_cost が未知 tier に 0.0 を返し、
+# cost_map に混入して min-max 正規化で最安誤判定につながる）。
+# ---------------------------------------------------------------------------
+_TIER_REFERENCE_KEY: dict[str, str] = {
+    "haiku":  "haiku-4-5",
+    "sonnet": "sonnet-4-5",
+    "opus":   "opus-4-5",
+}
+
+
+def tier_reference_cost(tier: str) -> float:
+    """tier 名から静的参照単価（input + output 単価和、USD/MTok）を返す。
+
+    tie-break の static fallback 用。実測 avg_cost が利用可能な場合は
+    実測値を優先し、本関数はデータ不足/欠損 tier の補完にのみ使用すること。
+
+    min-max 正規化で使用するため、絶対値より haiku < sonnet < opus の
+    順位が重要（_PRICING の現行世代単価で単調性が保証される）。
+
+    Args:
+        tier: "haiku" / "sonnet" / "opus" のいずれか。
+
+    Returns:
+        _PRICING[_TIER_REFERENCE_KEY[tier]] の input + output 単価和（USD/MTok）。
+        未知 tier（_TIER_REFERENCE_KEY に存在しないキー）は 0.0 を返す。
+    """
+    key = _TIER_REFERENCE_KEY.get(tier)
+    if key is None:
+        return 0.0
+    pricing = _PRICING.get(key)
+    if pricing is None:
+        return 0.0
+    inp_price, out_price, _cache_write, _cache_read = pricing
+    return inp_price + out_price
+
+
 def known_models() -> tuple[str, ...]:
     """単価表のキー一覧を返す（テスト・デバッグ用）。