逐字稿校正與規則萃取流程

# {錯誤形式: (正確形式, 實際命中次數)}——命中數是對 14 份課程逐字稿的實測值
TERM_TABLE: dict[str, tuple[str, int]] = {
    # 核心概念（語意完全相反，最嚴重）——綁定「買盤/賣盤/脈盤」前綴
    "買盤捷徑": ("買盤竭盡", 64),
    "賣盤捷徑": ("賣盤竭盡", 50),
    "脈盤捷徑": ("賣盤竭盡", 3),      # 「賣盤」也被聽成「脈盤」
    # 技術指標
    "軍線": ("均線", 10),
    "歸離": ("乖離", 3),          # 2026-08-30 重萃時漏進 quote 才補
    # 權證工具：「權陣大戶／大出權陣／用權陣」8 次全指權證
    "權陣": ("權證", 8),
    …共 115 條（2026-09-25 補「全政／全正／全鎮／全證→權證」「頭信→投信」「科轉債→可轉債」等 14 條，再補逐字稿原文欄露出的「軍量→均量」「存碼→籌碼」「贈雨→贈與」4 條）
    …2026-10-01 再補處置策略用語 57 條（累犯／處置／位階／葛蘭碧／個股名等），見下一張卡
    …2026-10-08／10-13 再補 PPA 審閱用語 18 條（停牌→聽牌、格子沖→隔日沖、自行商→自營商、開步林→開布林、魏華科→蔚華科、文貌→穩懋等），見再下一張卡
}

def fix_with_report(text):
    changes = {}
    # 長的先替換：避免短規則吃掉長規則的一部分
    for wrong in sorted(TERM_TABLE, key=len, reverse=True):
        right, _ = TERM_TABLE[wrong]
        n = text.count(wrong)
        if n:
            text = text.replace(wrong, right)
            changes[f"{wrong}→{right}"] = n
    return text, changes

# 術語校正：餵入與 quote 定位**都用 fix 後的文字**（同一空間）。餵原稿會讓
# 「權陣」這類辨音錯誤原樣穿透進 condition／quote（實測 3 張卡）；餵校正後
# 卻對原稿定位，含「權證」的 quote 會定位失敗被當幻覺丟掉。
transcript = term_fix.fix(transcript)
prompt = build_prompt(transcript, meta, rule_catalog=rule_catalog)
raw = complete_fn(prompt)                      # 測試注入假函式；正式跑 _gemini_complete
cards = parse_llm_response(raw)

for card in cards:
    prov = card.get("provenance") or {}
    match = match_quote(prov.get("quote", ""), transcript)
    status = classify_quote(match.similarity, match.anchor)   # 0.8／0.5＋連續 8 字
    position = match.position
    if status == "rejected":          # 幻覺風險，整卡丟
        quote_rejected += 1
        continue
    prov["video_id"] = video_id                  # 事實由我們填，不採信 LLM
    prov["episode_title"] = episode_title
    prov["date"] = date
    prov["quote_verified"] = status == "verified"   # ≥0.8
    prov["term_fixed"] = True            # quote 是 fix 後空間的文字
    set_quote_source(prov, transcript, match)    # 逐字稿截出的原文
    # timestamp 一律用「quote 定位 → 往前找最近標題」推導出的值覆蓋 LLM 給的值
    derived = derive_timestamp_from_quote(transcript, position)
    if derived: prov["timestamp"] = derived
    else:       prov.pop("timestamp", None)   # 寧可缺席交給護欄丟，不留猜測值

def _resolve_google_api_key() -> str:
    key = os.environ.get("GOOGLE_API_KEY")         # 1. 環境變數優先
    if not key:
        env = PROJECT_ROOT / ".env"                 # 2. 其次專案根 .env 的那一行
        if env.exists():
            for line in env.read_text(encoding="utf-8").splitlines():
                if line.startswith("GOOGLE_API_KEY="):
                    key = line.split("=", 1)[1].strip().strip('"').strip("'")
                    break
    if not key:
        raise RuntimeError("缺少 GOOGLE_API_KEY：…")   # 3. 缺就 fail fast，不靜默
    return key

def _gemini_complete(prompt: str) -> str:
    api_key = _resolve_google_api_key()
    return llm_config.call_with_rate_limit_retry(      # 每次嘗試前預約今日額度（上限 100）
        lambda: llm_config.gemini_generate(prompt, api_key, temperature=llm_config.TEXT_TEMPERATURE))

# call_with_rate_limit_retry：reserve_call（已滿就 raise DailyQuotaExceeded）→ 呼叫 →
#   被 429 擋下：退回額度、等 20／40／60 秒（伺服器有建議就照它）再試；到底仍被擋 raise RateLimited
# gemini_generate：google-genai 打一次、回傳文字；單次逾時 600 秒，SDK 只重試 503（429 留給上面那層）