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.

什么是 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 和语音工具包集成，并允许您插入自己的协商费率。