floe-guard: Instructions file for Codex

AGENTS.md — floe-guard

Instructions for AI coding agents. Most often you're here to add floe-guard to an agent (below); the last section covers working on this repo.

What floe-guard is

It tells you what every AI call really costs. It meters STT + TTS + LLM + telephony per call, out of the box (Pipecat and LiveKit, Python & TypeScript), and keeps a live ledger of your agent's real spend. Connect free (one key) for your Coverage Score and 7-day history. It also hard-stops the next turn before it crosses your USD ceiling — a runaway loop dies at $0.10 instead of $4,000. Runs in your process: no account, no signup, no network, no telemetry. It also guards any LLM agent (OpenAI, Anthropic, CrewAI, LangChain, …) via plain check() / record() or an adapter. Python (pip) + TypeScript (npm). MIT. Built by Floe — know what every AI call really costs: cost per call across every vendor, margin per client, and rebilling your own customers off the actuals.

Add it to an agent — unattended steps

1. Install

   • Python: pip install floe-guard
   • TypeScript / Node: npm i floe-guard

2. Wire the hard-stop around each model call (check before, record after):

   from floe_guard import BudgetGuard
   
   guard = BudgetGuard(limit_usd=5.00)   # the ceiling
   guard.check()                         # before each LLM call — raises BudgetExceeded if it'd cross
   resp = call_your_llm(...)             # your existing call
   guard.record("gpt-4o", resp.usage.prompt_tokens, resp.usage.completion_tokens)
   

   TypeScript is the same shape (guard.check() / guard.record(...)); see js/.

   • Framework adapters (no manual check/record): OpenAI, Anthropic, Gemini, CrewAI, LangChain, LangGraph, LiteLLM, Vercel AI SDK — README §"Framework adapters".
   • Voice (per-turn): Python floe_guard.integrations.pipecat / .livekit; TS floe-guard/adapters/{livekit,vapi,retell} — reserve-before-turn.
   • Paid tools: reserve_tool() / settle_tool() block before the tool runs.

3. Verify offline (no key, no network): floe-guard demo — the guard halts a stubbed loop after a few iterations. No repo checkout (the wheel does not ship examples/).