Floe-Labs/floe-guard

The spend meter, cost/margin, & budget gate for AI voice agents. Meters STT + TTS + LLM + telephony per call, out of the box (Pipecat, LiveKit — Python & TypeScript). Hard-stops the next turn before it crosses your ceiling. Local, no account, no telemetry. Built by Floe.

What is 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 アカウント（1つのキー）を接続し、カバレッジスコアと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 および音声ツールキットと統合可能。独自の交渉価格を組み込むこともできます。