pzqpzq/LSF_MDia

📚 機器方言學（MDia）

是什麼 – MDia 是一個研究級的 Python 庫，可將大型語言模型（LLM）的中間推理步驟視為 機器間通訊協定。與傳遞冗長的人類可讀思考鏈不同，發言者模型 會輸出一個緊湊的 語言象徵框架（LSF）卡——一種「方言」，定義了符號、語法、可重用運算子、有效性規則和經驗性概況。聆聽者模型 隨後解析並執行該方言。MDia 提供了建立、演化、分析、選擇、路由和驗證這些方言卡的完整生命週期，並保證嚴格的可重現性。

🎯 核心概念

概念	含義
方言卡（LSF）	持久化規範 `D = (V, G, O, R, ρ)` – 符號、語法、運算子、規則和資料驅動的概況。
發言者 → 聆聽者	一個模型產生方言卡，另一個模型消費它。
效用是關係性的	方言的價值取決於發言者、聆聽者、任務、路由策略和令牌預算。
決定論流水線	八個 CLI 階段（`collect → create → evolve → profile → select → run → validate-rules → report`），在任何保留評估前凍結證據。
建構即可重現	不可變的資料分割、內容衍生 ID、完整的令牌計數，以及一個無需任何外部 API 金鑰即可運行的玩具離線範例。

⚙️ 主要功能（如 README 所述）

相容黑盒 LLM – 可與任何基於 API 的模型相容；無需存取隱藏狀態。
可重用的方言卡 – 版本化、雜湊識別、可歸檔，便於後續重用。
路由策略 – single、aggregate、compose 和 abstain/raw-fallback 計畫，尊重預算、風險和聆聽者開放性。
基於規則的驗證 – 100 條機器社會語言學規則的銀行，每條規則均有證據等級（完整、強、未評估）。
跨異質模型的分析 – 捕捉準確性、令牌成本、失敗模式、公開性、教學優勢等。
CLI 優先設計 – mdia 命令包含每個流水線階段的子命令；--help 顯示詳細選項。
離線決定論範例 – examples/toy/ 提供固定用例，可在無任何 API 金鑰的情況下本地運行整個生命週期。
詳盡的文件 – 架構、流水線、規則驗證、擴充指南，以及論文到程式碼的對應。
CI 與品質門檻 – 跨 Python 3.10–3.12 的測試、靜態分析（ruff, mypy）、格式化和密鑰掃描。

🚀 典型使用情境

情境	MDia 如何協助
模型間通訊研究	建立可重用的 LSF，進行演化，並測量不同模型家族如何從彼此的方言中獲益。
高效推理	以緊湊的方言卡取代冗長的 CoT 追蹤，保留下游聆聽者所需的狀態，生成令牌減少約 70%（論文報告）。
課程式教學	使用較弱的發言者生成「教學方言」，其他模型可高效率採用。
預算限制下的穩健路由	部署 `single` 或 `compose` 路由計畫，在尊重令牌預算的同時避免聆聽者已知抗拒的方言。
可審計的可重現性	在測試評估前凍結方言選擇和路由決策，確保不從保留資料中洩漏。

📦 安裝（來自 README）

# 克隆倉儲
git clone https://github.com/pzqpzq/LSF_MDia.git
cd LSF_MDia

# 建立虛擬環境（需 Python 3.10+）
python -m venv .venv
source .venv/bin/activate

# 以可編輯模式安裝套件（拉取所有相依性）
pip install -e .

玩具示範無需外部 API 金鑰；真實運行需按 docs/extending.md 所述新增相容的模型提供者適配器。

🏃‍♀️ 快速入門範例（來自 README）

# 執行決定論玩具流水線
mdia pipeline --config configs/toy_mdia.yaml

該命令會建立一個版本化執行目錄（runs/<run_id>/），包含：

原始追蹤資料，
生成的方言卡，
演化和路由器驗證概況，
冷凍的方言庫，
路由計畫、預測、令牌計數和完整的可重現性報告。使用相同種子重新執行將完全重現相同結果。

📉 局限與範圍（如所述或暗示）

僅限研究級 – 專為受控實驗設計，非生產級服務堆疊。
基準特定的固定用例 – 離線示範使用小規模可再分發資料集；重現論文數字需精確模型版本和私有基準資料。
依賴黑盒 – MDia 假設底層 LLM 可透過標準 API 查詢；不支援暴露內部狀態的模型。
規則庫保守 – 100 條規則中僅 19 條有強實證支持；其餘標記為弱證據。
路由決策必須凍結 – 框架強制驗證與測試分割嚴格分離，可能對快速原型設計感到受限。

📄 授權

專案採用 MIT 授權（見 LICENSE）。

📚 引用（來自 README）

若在出版物中使用 MDia，請引用配套的 ICML 2026 海報和 arXiv 預印本：

@inproceedings{mdia2026,
  title = {Machine Dialectology: from verbose reasoning traces to a measurable ecology of machine dialects},
  author = {…},
  booktitle = {Proceedings of the 2026 International Conference on Machine Learning (ICML)},
  year = {2026},
  url = {https://arxiv.org/abs/2606.29354},
  note = {Poster 61557}
}

（確切作者列表可從 arXiv 項目取得。）

🔗 接下來

閱讀架構指南（docs/architecture.md）以了解如何實作新模型提供者。
探索規則系統（docs/rules.md）若想新增或修改社會語言學約束。
嘗試玩具流水線 並檢查生成的 report.md，查看溯源連結如何記錄。
檢查遺留工作區（legacy/）以取得 CLSR 框架的早期版本，如需歷史背景。

MDia 是一個真正的開源研究平台，用於研究異質 LLM 代理之間的可重用符號協定。以上所有資訊均直接取自倉儲的 README。