alantech/marsha

Marsha – 由 LLM 驅動的「程式語言」

是什麼 – Marsha 讓你以小型、類似 Markdown 的方式描述一個資料處理任務。你宣告輸入與輸出的「類型」，撰寫簡短的自然語言說明，並提供少量的輸入-輸出範例。Marsha 編譯器會將此規格傳送給 LLM（預設使用 OpenAI 的 API，但任何相容的端點皆可），產生 Python 程式碼，以範例作為測試執行，並回傳可直接執行的腳本。

核心理念

• 宣告式語法 – .mrsh 檔案看起來像 Markdown。類型使用 CSV 風格的表格定義，函數透過 # func … 標題宣告，後接說明與範例區塊。
• 以範例為基礎的測試 – 你提供的範例會成為測試套件，編譯器用它來驗證產生的程式碼，降低輸出錯誤的機率。
• LLM 作為後端編譯器 – 將規格轉換為 Python 的重負工作由 LLM 完成。你可以透過設定、命令列旗標或環境變數選擇模型。
• 即用型輸出 – 產生的 Python 程式碼包含微型 CLI 包裝器（或簡單的 REST 伺服器），因此你可以直接從終端機呼叫編譯後的函數。

如何使用

1. 從倉儲安裝套件：

   uv pip install git+https://github.com/alantech/marsha
   

2. 使用 Marsha 語法（類型定義、# func … 區塊、說明與範例）撰寫 my_task.mrsh 檔案。
3. 編譯它：

   python -m marsha my_task.mrsh
   

   該命令會連接設定的 LLM，產生 Python 程式碼，執行測試，並寫出結果腳本。
4. 以 CLI 工具或小型 Web 服務的形式執行產生的腳本：

   python -m my_task --help          # 查看產生的 CLI 選項
   python -m my_task -s 8080         # 啟動 REST 伺服器
   

設定 – Marsha 從標準作業系統位置（Linux 上為 ~/.config/marsha/config.json 等）讀取 JSON 設定檔。你可以設定 api_base、api_key、model 和 model_strong。環境變數（OPENAI_ORG、OPENAI_SECRET_KEY/OPENAI_API_KEY）可用於預設的 OpenAI 後端。--api-base 和 --model 旗標可在命令列上覆蓋這些設定。

命令列選項（精選亮點）：

• -q – 僅產生程式碼，跳過修正階段（較便宜，但可靠性較低）。
• -a N – 嘗試最多 N 次編譯，失敗時重試。
• -n N – 每次嘗試執行 N 個並行的 LLM「思考路徑」；第一個成功路徑勝出。
• --exclude-main-helper – 排除自動產生的 CLI 包裝器。
• --exclude-sanity-check – 跳過 Marsha 定義的初始一致性檢查。
• -s – 將編譯統計資訊寫入檔案。

路線圖亮點

• 將平均正確率提升至 90% 以上。
• 加入編輯器的語法強調外掛。
• 支援 Python 以外的目標語言。
• 引入模組系統與「反編譯器」，可將現有的 Python 代碼還原為 Marsha 語法。
• 建構視覺化 GUI 編輯器與更豐富的除錯輔助工具。

適用對象 – 希望以更高層次、基於範例的方式生成小型資料處理腳本（例如 pandas 流水線），但不想逐行手動撰寫程式碼的開發者，且願意在測試驅動監督下讓 LLM 產生實作。