floe-guard — know what every AI call costs
floe-guard meters STT + TTS + LLM +
telephony per call (Pipecat,
LiveKit — Python & TypeScript)
and keeps a live ledger of your agent's real spend. Connect free for your Coverage
Score and 7-day history. It also hard-stops the next turn before it crosses a USD
ceiling. In-process, no account, no telemetry. Guards any LLM/tool call the same way. Budget, not balance —
it caps spend, holds no money, needs no account.
This is the library skill. For the whole govern-your-spend workflow (spend
policies, voice coverage, hosted upgrade, Coverage Score), add the full Floe skill:
npx skills add floe-labs/agent-skills.
Install
- Python:
pip install floe-guard
- TypeScript / Node:
npm i floe-guard
Wire the hard-stop
check() before each model call (raises if it would cross the ceiling), record()
after (prices the tokens offline and accrues them):
from floe_guard import BudgetGuard
guard = BudgetGuard(limit_usd=5.00)
guard.check() # raises BudgetExceeded before an over-budget call runs
resp = call_your_llm(...)
guard.record("gpt-4o", resp.usage.prompt_tokens, resp.usage.completion_tokens)
Verify offline (no key, no network): floe-guard demo.
Skip the manual wiring — adapters
- Frameworks: OpenAI, Anthropic, Gemini, CrewAI, LangChain, LangGraph, LiteLLM,
Vercel AI SDK.
- Voice (per-turn, prices STT + LLM + TTS + telephony): Python
floe_guard.integrations.pipecat / .livekit; TS
floe-guard/adapters/{livekit,vapi,retell}.
- Pre-call admission:
floe_guard.gates (retell / vapi / pre_call) reject
an over-budget call before it connects.
- Paid tools:
reserve_tool() / settle_tool() block before the tool runs.
Rules
- Enforcement lives in the call path:
check() / reserve() before the call.
record() alone meters after the fact — it can't stop a call already made.
- Fail-closed: an unpriceable model raises
UnpriceableModelError unless you pass
a price_overrides rate or fail_closed=False.
- Use
reserve() / settle() (not check() then record()) under concurrency.
- Read
advisory() (near-limit flag + $/min burn rate) to taper before the hard-stop.
- Opt-in only, off by default:
BudgetGuard.from_floe(api_key=…) (hosted headroom)
and enable_sync() / floe-guard push (ledger sync for Coverage Score) are the only
things that touch the network — nothing does without an explicit opt-in.
References
1---2name: floe-guard3description: Know what every AI call really costs — floe-guard meters STT + TTS + LLM + telephony per call (Pipecat, LiveKit — Python & TypeScript), keeps a live ledger of real spend, and hard-stops the next turn before it crosses a USD ceiling. Free Coverage Score + 7-day history on connect. Use when an agent's spend must be seen and capped in-process with no account or telemetry; also guards any LLM agent and paid tool calls.4license: MIT5homepage: https://github.com/Floe-Labs/floe-guard6metadata:7 source: https://skillmd.com/skills/floe-labs/floe-guard8---910# floe-guard — know what every AI call costs1112floe-guard meters STT + TTS + LLM +13telephony **per call** ([Pipecat](https://github.com/Floe-Labs/floe-guard#pipecat-voice),14[LiveKit](https://github.com/Floe-Labs/floe-guard#livekit-voice) — Python & TypeScript)15and keeps a **live ledger** of your agent's real spend. Connect free for your **Coverage16Score** and **7-day history**. It also hard-stops the next turn *before* it crosses a USD17ceiling. In-process, no account, no telemetry. Guards **any** LLM/tool call the same way. Budget, not balance —18it caps spend, holds no money, needs no account.1920> This is the **library** skill. For the whole govern-your-spend workflow (spend21> policies, voice coverage, hosted upgrade, Coverage Score), add the full Floe skill:22> `npx skills add floe-labs/agent-skills`.2324## Install2526- Python: `pip install floe-guard`27- TypeScript / Node: `npm i floe-guard`2829## Wire the hard-stop3031`check()` before each model call (raises if it would cross the ceiling), `record()`32after (prices the tokens offline and accrues them):3334```python35from floe_guard import BudgetGuard3637guard = BudgetGuard(limit_usd=5.00)38guard.check() # raises BudgetExceeded before an over-budget call runs39resp = call_your_llm(...)40guard.record("gpt-4o", resp.usage.prompt_tokens, resp.usage.completion_tokens)41```4243Verify offline (no key, no network): `floe-guard demo`.4445## Skip the manual wiring — adapters4647- **Frameworks**: OpenAI, Anthropic, Gemini, CrewAI, LangChain, LangGraph, LiteLLM,48 Vercel AI SDK.49- **Voice** (per-turn, prices STT + LLM + TTS + telephony): Python50 `floe_guard.integrations.pipecat` / `.livekit`; TS51 `floe-guard/adapters/{livekit,vapi,retell}`.52- **Pre-call admission**: `floe_guard.gates` (`retell` / `vapi` / `pre_call`) reject53 an over-budget call before it connects.54- **Paid tools**: `reserve_tool()` / `settle_tool()` block *before* the tool runs.5556## Rules5758- Enforcement lives **in the call path**: `check()` / `reserve()` *before* the call.59 `record()` alone meters after the fact — it can't stop a call already made.60- **Fail-closed**: an unpriceable model raises `UnpriceableModelError` unless you pass61 a `price_overrides` rate or `fail_closed=False`.62- Use `reserve()` / `settle()` (not `check()` then `record()`) under concurrency.63- Read `advisory()` (near-limit flag + `$/min` burn rate) to taper before the hard-stop.64- **Opt-in only, off by default**: `BudgetGuard.from_floe(api_key=…)` (hosted headroom)65 and `enable_sync()` / `floe-guard push` (ledger sync for Coverage Score) are the only66 things that touch the network — nothing does without an explicit opt-in.6768## References6970- Full guide: https://github.com/Floe-Labs/floe-guard#readme71- Integration steps for an agent: https://github.com/Floe-Labs/floe-guard/blob/main/AGENTS.md72- The full Floe skill: https://github.com/Floe-Labs/agent-skills