💡 導讀：一份航海地圖若只畫航線、不標暗礁，讀者會以為每一段都同樣安全……

如果一張航海圖只畫出順暢的航線，卻不標示暗礁與淺灘，船長可能會面臨觸礁風險。在生醫與基因研究領域，AI 的分析報告也是一樣——不僅要呈現預測結果，更要清楚寫明資料從哪裡來、有哪些缺漏，以及 AI 目前「還做不到什麼」。

💡 一、核心概念：認識 AI 報告的四大「誠實指標」

1. 數位指紋（Evidence Provenance & SHA-256）
   • 概念：就像每個人有獨一無二的指紋，每一份輸入 AI 的資料經過數學公式計算後，都會產生一串獨特的暗號（SHA-256 雜湊值）。
   • 作用：這能讓研究員隨時核對：「我們現在看到的這份報告，跟當初輸入的原始資料是不是完全吻合？有沒有被不小心改動過？」
     SHA-256 能協助核對資料內容是否一致，但雜湊值本身不能證明資料來源一定真實，也不能單獨保證研究結果可重現。
2. 資料缺了，絕不隨便「補零」（Missing Values）
   • 概念：在科學上，「數據沒測到（未知）」跟「數值等於 0」完全是兩回事。
   • 作用：如果某個基因位點缺乏實驗分數，報告中必須老實保留空白（null）並標註 MISSING_SCORE。若為了方便隨便補個 0，可能會讓讀者誤以為「這項指標經過測試且確定沒有影響」。
3. 主動貼上「警告標籤」（Model Limitations）
   • 概念：負責任的 AI 報告會主動列出模型的邊界。在這次的示範中，報告明確指出三點：
     • 無法驗證遠距離機制：無法預測 distant/trans-regulatory 等遠端調控機制。
     • 缺乏族群與組織校準：尚未針對特定組織或不同族群進行完整的效能驗證。
     • 不能當作臨床診斷：產生的分數不能直接拿來當作醫院幫病人開藥或確診的依據。
4. 標示「待人類專家審閱」（Manual Review）
   • 概念：報告中會強制標註 manual_review = REQUIRED。
   • 作用：這是在提醒所有人：AI 只是輔助調查的「實習生」，它的結果必須經過人類醫生或遺傳學專家複查認可後才能採用。

💡 二、技術原理與研究用途

總結：

這個範例最重要的不是產生一個分數，而是示範如何讓結果具備可追溯性（Provenance）、可驗證性（SHA256）、限制揭露（Limitations）與人工審查（Manual Review）等資訊，避免輸出被誤用為臨床判讀或超出證據範圍的結論。

💡 三、今日動手做：獨立可重現的合成資料程式小練習（Mini Demo)

文章中附帶的 Python 程式（DAY28_INLINE_DEMO.py），就像是一個「透明報告自動生成器」：

1. 檢查安全防護：程式會先檢查輸入的字元格式，避免有人在檔案名稱中混入壞程式碼或格式錯誤的文字。
2. 計算資料指紋：幫輸入的練習資料產生 SHA-256 雜湊碼。
3. 打包輸出：同時產生電腦好處理的 day28_report.json 檔案，以及人類方便閱讀的 Markdown 文章。報告中會完整包含上述的數位指紋、缺值標示、三條模型限制以及待審審查狀態。

"""Small offline evidence report inspired by the separate Day28 Reporter MVP."""
import argparse
import hashlib
import json
import math
import re
from pathlib import Path

# 教學用途的合成資料輸入
# 故意限制為 synthetic，避免被誤解為真實生醫分析結果
INPUT = {"data_kind": "SYNTHETIC_EDUCATIONAL_DEMO",
         "variant_id": "synthetic-example-001", "score": None,
         "provenance": {"source_type": "synthetic",
                        "source_id": "day28-inline-fixture-001"}}
# 除了輸出結果，也需明確揭露模型限制
LIMITATIONS = ["No trans-regulatory or tissue-specific mechanism validation",
               "No reference-allele or ancestry-performance validation",
               "No calibrated disease probability or clinical classification"]
# 限制識別碼格式，避免特殊字元污染報告內容
IDENTIFIER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}\Z", re.ASCII)

def valid_identifier(value, field):
    """Allow short ASCII identifiers that cannot add Markdown syntax or lines."""
    if not isinstance(value, str) or IDENTIFIER.fullmatch(value) is None:
        raise ValueError(f"{field} must be 1-64 ASCII letters, digits, dot, underscore or hyphen; start alphanumeric")
    return value

def build_report(record=INPUT):
    # 基本輸入格式驗證
    if not isinstance(record, dict):
        raise ValueError("Record must be a JSON object")
    provenance = record.get("provenance", {})
    if not isinstance(provenance, dict):
        raise ValueError("Provenance must be a JSON object")
    variant_id = valid_identifier(record.get("variant_id"), "variant_id")
    source_id = valid_identifier(provenance.get("source_id"), "source_id")
      # 僅接受明確標示的合成資料
    if record.get("data_kind") != "SYNTHETIC_EDUCATIONAL_DEMO" or \
       provenance.get("source_type") != "synthetic":
        raise ValueError("Only explicit synthetic teaching input is accepted")
    score = record.get("score")
    # score 允許數值或 null、排除 NaN、Infinity 等特殊值
    if score is not None and (not isinstance(score, (int, float)) or
                              isinstance(score, bool) or not math.isfinite(score)):
        raise ValueError("Score must be finite numeric or null")

    # 建立輸入資料的 SHA-256 指紋，方便後續追蹤與重現
    canonical = json.dumps(record, ensure_ascii=False, sort_keys=True,
                           separators=(",", ":")).encode("utf-8")
    
    return {"report_kind": "SYNTHETIC_EDUCATIONAL_DEMO",
            "variant_id": variant_id,
            # 資料來源與證據追蹤資訊
            "evidence_provenance": {"source_type": "synthetic",
                "source_id": source_id,
                "input_sha256": hashlib.sha256(canonical).hexdigest()},
            "score": score,

            # 明確區分缺漏分數與示範分數
            "score_status": "MISSING_SCORE" if score is None else "SYNTHETIC_SCORE",

            # 已知限制必須一併呈現
            "model_limitations": LIMITATIONS,

            # 強制要求人工審查

            "manual_review": "REQUIRED",
            # 不聲稱信心校準或臨床分類能力
            "confidence_calibrated": False,

             # 本範例不呼叫任何外部服務
            "clinical_classification": None,
            "real_api_calls": 0}

def markdown(report):
    # 報告格式驗證
    if not isinstance(report, dict) or not isinstance(report.get("evidence_provenance"), dict):
        raise ValueError("Report and evidence_provenance must be JSON objects")
    variant_id = valid_identifier(report.get("variant_id"), "variant_id")
    source_id = valid_identifier(report["evidence_provenance"].get("source_id"), "source_id")
    score_text = "missing (JSON null)" if report["score"] is None else str(report["score"])
    limitations = "\n".join(f"- {item}" for item in report["model_limitations"])

    # 產生人類可閱讀的 Markdown 報告
    return (f"# Synthetic Evidence Report: {variant_id}\n\n"
            f"Source ID: {source_id}\n\n"
            f"Input SHA-256: {report['evidence_provenance']['input_sha256']}\n\n"
            f"Score: {score_text} ({report['score_status']})\n\n"
            f"Manual review: {report['manual_review']}\n\n"
            f"## Model limitations\n\n{limitations}\n\n"
            "Educational synthetic data only; no model call or clinical decision.\n")

def write_report(output_dir, record=INPUT):
    report = build_report(record)
    folder = Path(output_dir)
    folder.mkdir(parents=True, exist_ok=True)
    # 同時輸出 JSON 與 Markdown
    (folder / "day28_report.json").write_text(
        json.dumps(report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
    (folder / "day28_report.md").write_text(markdown(report), encoding="utf-8")
    return {"status": "PASS", "report_mode": "SEPARATE_MVP_INSPIRED_INLINE_DEMO",
            "score_status": report["score_status"], "manual_review": report["manual_review"],
            "json_file": str(folder / "day28_report.json"),
            "markdown_file": str(folder / "day28_report.md"), "real_api_calls": 0}

def main():
    # CLI 入口
    parser = argparse.ArgumentParser(description="Synthetic evidence report lesson")
    parser.add_argument("--output-dir", default="day28_output")
    args = parser.parse_args()
    print(json.dumps(write_report(args.output_dir), ensure_ascii=False, sort_keys=True))

if __name__ == "__main__":
    main()

▶ 執行方式

python3.12 DAY28_INLINE_DEMO.py --output-dir day28_output

▶ 預期與實測結果

{"json_file": "day28_output/day28_report.json", "manual_review": "REQUIRED", "markdown_file": "day28_output/day28_report.md", "real_api_calls": 0, "report_mode": "SEPARATE_MVP_INSPIRED_INLINE_DEMO", "score_status": "MISSING_SCORE", "status": "PASS"}

✅ 本日 Checklist

• [ ] 能在 JSON 找到 evidence_provenance.source_id 與輸入 SHA-256。
• [ ] 能找到 score=null、score_status=MISSING_SCORE、manual_review=REQUIRED。
• [ ] 能開啟 Markdown 查看三條 model_limitations，驗證非法識別碼被拒絕，並說明 Reporter 仍是 SEPARATE_MVP。

四、總結：科學講求「可重現」與「知之為知之」

這篇教學的核心目的，是希望研究者在開發或使用生醫 AI 工具時，建立一套負責任的科學態度：數據公開透明、保留原始缺值、誠實標示限制，並且永遠由人類進行最後的把關。

五、明日預告

明天 Day29 將從證據界線走向基因資料的倫理與隱私；Day30 再整理整個專欄的知識與程式對照。

延伸閱讀與來源

• AlphaGenome 官方 FAQ｜模型限制
• Google DeepMind｜AlphaGenome 研究用途與限制