Skip to content

Commit 9248bcb

Browse files
committed
docs: add 'Why floe-guard?' objection-handling section
The highest-leverage adoption add: handle the 'why not just X' a dev asks before adopting — max_tokens/max_rpm (caps size, not dollars), usage logs/dashboards (after the fact), a logging callback (can't halt), and a hand-rolled counter (races under parallel agents; floe-guard reserves atomically). All accurate to shipped main (reserve/settle landed via #19).
1 parent 3a4d39e commit 9248bcb

1 file changed

Lines changed: 19 additions & 0 deletions

File tree

README.md

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,25 @@ This rigs a loop against a **stub LLM** — no real API key, no account, no netw
4545
It prices each fake `gpt-4o` call offline and the guard halts the loop after a few
4646
iterations. This is the reproducible "stop the loop" demo.
4747

48+
## Why floe-guard?
49+
50+
You can already *see* what your agent spends — the problem is seeing it too late.
51+
floe-guard is the part that **stops the call**, not the part that reports the damage.
52+
53+
- **`max_tokens` / `max_rpm`** cap size and rate, not **dollars** — a cheap model
54+
stuck in a loop still drains the budget.
55+
- **Usage logs and provider dashboards** tell you what you spent *after* it's gone.
56+
floe-guard refuses the call *before* it crosses your ceiling.
57+
- **A cost callback that just logs** is notified after the fact and can't halt the
58+
run — enforcement has to stand in front of the next call. That's where it lives.
59+
- **A hand-rolled `spent += cost` counter races under parallel agents** (CrewAI
60+
fan-out, `asyncio`, `Promise.all`): N calls read the same under-limit total and
61+
all fire. floe-guard reserves atomically (`reserve()`/`settle()`), so the ceiling
62+
holds under concurrency.
63+
64+
The whole job: a hard stop **before** the next call, that **holds under fan-out**
65+
no account, no network, no crypto.
66+
4867
## How it works
4968

5069
The guard sits **in the call path**, not on an event bus. A passive listener is

0 commit comments

Comments
 (0)