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: MIT5---67# floe-guard — know what every AI call costs89floe-guard meters STT + TTS + LLM +10telephony **per call** ([Pipecat](https://github.com/Floe-Labs/floe-guard#pipecat-voice),11[LiveKit](https://github.com/Floe-Labs/floe-guard#livekit-voice) — Python & TypeScript)12and keeps a **live ledger** of your agent's real spend. Connect free for your **Coverage13Score** and **7-day history**. It also hard-stops the next turn *before* it crosses a USD14ceiling. In-process, no account, no telemetry. Guards **any** LLM/tool call the same way. Budget, not balance —15it caps spend, holds no money, needs no account.1617> This is the **library** skill. For the whole govern-your-spend workflow (spend18> policies, voice coverage, hosted upgrade, Coverage Score), add the full Floe skill:19> `npx skills add floe-labs/agent-skills`.2021## Install2223- Python: `pip install floe-guard`24- TypeScript / Node: `npm i floe-guard`2526## Wire the hard-stop2728`check()` before each model call (raises if it would cross the ceiling), `record()`29after (prices the tokens offline and accrues them):3031```python32from floe_guard import BudgetGuard3334guard = BudgetGuard(limit_usd=5.00)35guard.check() # raises BudgetExceeded before an over-budget call runs36resp = call_your_llm(...)37guard.record("gpt-4o", resp.usage.prompt_tokens, resp.usage.completion_tokens)38```3940Verify offline (no key, no network): `floe-guard demo`.4142## Skip the manual wiring — adapters4344- **Frameworks**: OpenAI, Anthropic, Gemini, CrewAI, LangChain, LangGraph, LiteLLM,45 Vercel AI SDK.46- **Voice** (per-turn, prices STT + LLM + TTS + telephony): Python47 `floe_guard.integrations.pipecat` / `.livekit`; TS48 `floe-guard/adapters/{livekit,vapi,retell}`.49- **Pre-call admission**: `floe_guard.gates` (`retell` / `vapi` / `pre_call`) reject50 an over-budget call before it connects.51- **Paid tools**: `reserve_tool()` / `settle_tool()` block *before* the tool runs.5253## Rules5455- Enforcement lives **in the call path**: `check()` / `reserve()` *before* the call.56 `record()` alone meters after the fact — it can't stop a call already made.57- **Fail-closed**: an unpriceable model raises `UnpriceableModelError` unless you pass58 a `price_overrides` rate or `fail_closed=False`.59- Use `reserve()` / `settle()` (not `check()` then `record()`) under concurrency.60- Read `advisory()` (near-limit flag + `$/min` burn rate) to taper before the hard-stop.61- **Opt-in only, off by default**: `BudgetGuard.from_floe(api_key=…)` (hosted headroom)62 and `enable_sync()` / `floe-guard push` (ledger sync for Coverage Score) are the only63 things that touch the network — nothing does without an explicit opt-in.6465## References6667- Full guide: https://github.com/Floe-Labs/floe-guard#readme68- Integration steps for an agent: https://github.com/Floe-Labs/floe-guard/blob/main/AGENTS.md69- The full Floe skill: https://github.com/Floe-Labs/agent-skills
Floe-Labs