Floe-Labs/floe-guard

什麼是 floe‑guard？

floe‑guard 是一個輕量級程式庫（支援 Python 與 TypeScript），可讓您為應用程式發出的每一次 AI 呼叫設定並強制執行美元預算——無論呼叫的是大型語言模型、語音轉文字服務、文字轉語音服務、電話服務商，或任何其他 AI 相關供應商。

為何重要

• AI 代理通常會呼叫多個服務（OpenAI、Anthropic、Gemini、語音 STT/TTS、電話服務等）。
• 這些呼叫可能迅速累積成本，而傳統的使用限制（max_tokens、max_rpm）無法防止支出失控。
• floe‑guard 會在每次呼叫完成後立即記錄其真實 USD 成本，並能在下一個呼叫可能超出預算前主動停止。

核心概念

概念	作用
BudgetGuard	透過指定美元上限（例如 BudgetGuard(limit_usd=5.00)）實例化的主類別。提供 check()（呼叫前）與 record()（呼叫後）方法。
硬停止	如果 check() 預測下一個呼叫會超出上限，則拋出 BudgetExceeded，呼叫根本不會到達供應商。
即時帳本	所有支出均在進程內（無需帳戶，無需網路）保存，可匯出為 JSONL。可選地將帳本推送到 Floe 的主機服務，以取得「覆蓋率評分」與 7 天歷史記錄。
適配器	為流行技術堆疊提供即用型包裝器：OpenAI、Anthropic、Gemini、CrewAI、LiteLLM、LangChain、LangGraph、Vercel AI SDK，以及 Pipecat、LiveKit、Vapi、Retell 的語音適配器。它們會自動在請求前呼叫 check()，在請求後呼叫 record()。
費率卡	套件內建一個內嵌成本地圖（公開價格快照）。您可透過自訂 FLOE_RATE_CARD JSON 覆蓋任意價格，使監控反映協商後的合約價格而非公開報價。
工具預留	對於付費工具，您可在工具執行前呼叫 reserve_tool()，執行後呼叫 settle_tool()，即使多個呼叫並行發生，也能保證原子級預算檢查。
持久化	SqliteStore 支援多個進程共享同一日預算（window="utc-day"）。

使用方式（Python 範例）

from floe_guard import BudgetGuard

guard = BudgetGuard(limit_usd=5.00)   # $5 上限

guard.check()                         # 若下一個呼叫會超 $5，則拋出例外
response = client.chat.completions.create(  # 您正常的 LLM 呼叫
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
# 呼叫完成後記錄支出
guard.record(
    model="gpt-4o",
    prompt_tokens=response.usage.prompt_tokens,
    completion_tokens=response.usage.completion_tokens,
)

如果該呼叫會使總支出超過 $5，guard.check() 會拋出 BudgetExceeded，請求根本不會發送到 OpenAI。

語音呼叫支援

語音管道涉及多個階段（STT → LLM → TTS → 電話）。floe‑guard 提供每輪適配器，在每輪開始前預留預算，結束後結算，確保整個語音會話始終在統一美元上限內。

無帳戶、無遙測模式

• 預設情況下所有操作均在本機執行——無需 API 金鑰、無需註冊、無出站遙測。
• 可選擇連接免費 Floe 帳戶（一個金鑰）以取得「覆蓋率評分」與 7 天支出歷史，但核心執行完全離線運行。

可立即執行的快速示範

• pip install floe-guard && floe-guard demo – 顯示一個在 $0.10 上限前停止的模擬 LLM 迴圈。
• floe-guard estimate gpt-4o --calls 1000 --tokens-in 800 --tokens-out 300 – 使用內嵌地圖估算工作負載成本。
• 語音呼叫成本示範（examples/voice_call_cost_livekit.py） – 無需任何網路呼叫，列印各階段成本分解。

哪些人可能需要它？

• 可能陷入迴圈的自主代理（CrewAI、LangChain 等）開發者。
• 按使用量向客戶收費，需確保從不超收的團隊。
• 任何希望獲得事前預防型支出防護，而非事後使用報告的人。

---

總結：floe‑guard 是一個實用、開源的防護機制，可測量每次 AI 相關 API 呼叫的實際美元成本，並在您設定的預算超限前提前停止執行。它支援離線運行，與主流 LLM 和語音工具包整合，並允許您插入自己的協商費率。