Merge pull request #1 from Floe-Labs/feat/initial-floe-guard

Week-1 MLV: floe-guard local budget guardrail

Author: achris7

.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to floe-guard
+
+`floe-guard` is a local budget guardrail for AI agents: it hard-stops an agent
+before its next LLM call when it would cross a spend ceiling. It runs in-process
+with no account. Hosted Floe is the upgrade path — enforcement moves server-side
+so the ceiling becomes un-bypassable and cross-vendor.
+
+Contributions are welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/Floe-Labs/floe-guard.git
+cd floe-guard
+pip install -e ".[dev]"
+```
+
+Run the checks before opening a PR:
+
+```bash
+pytest               # tests
+ruff check .         # lint
+ruff format .        # format
+```
+
+The optional adapters need their extras to run/import:
+
+```bash
+pip install -e ".[crewai]"    # CrewAI adapter
+pip install -e ".[litellm]"   # LiteLLM adapter
+```
+
+## Contribution flow
+
+1. Fork the repo and create a branch off `main` (e.g. `feat/your-change`).
+2. Make your change with tests, and keep `pytest` + `ruff` green.
+3. Open a **draft pull request** against `main` and describe what changed and why.
+
+## Code style
+
+- Python 3.10+ with type hints.
+- Formatting and linting are handled by `ruff` (config in `pyproject.toml`) — run
+  `ruff format .` and `ruff check .` before pushing.
+- Keep the core (`src/floe_guard/`) dependency-free; framework integrations belong
+  in `src/floe_guard/integrations/` behind an optional extra.
+- Prefer small, focused changes with tests that describe behavior.
+
+## Areas we'd love help with
+
+- **LangChain adapter** (callback-based enforcement).
+- **Vercel AI SDK adapter** (TypeScript middleware / port).
+- **Cost-map coverage** — keeping the bundled pricing map current and broad.
+
+Open an issue first if you want to discuss a larger change.

README.md

@@ -0,0 +1,154 @@
+# floe-guard
+
+**A local budget guardrail for AI agents.** It hard-stops your agent *before its
+next LLM call* when it would cross a spend ceiling — so a runaway loop dies at
+$0.10 instead of $4,000. No account, no signup, no network. Runs in your process.
+
+```bash
+pip install floe-guard
+```
+
+```python
+from floe_guard import BudgetGuard
+
+guard = BudgetGuard(limit_usd=5.00)   # your ceiling
+guard.check()                         # before each LLM call — raises if it'd cross
+response = call_your_llm(...)         # your existing call
+guard.record("gpt-4o", response.usage.prompt_tokens, response.usage.completion_tokens)
+```
+
+When the next call would cross the ceiling, the guard raises `BudgetExceeded` and
+prints:
+
+```
+BUDGET EXCEEDED — call blocked
+  spent so far: $5.001250  |  ceiling: $5.000000
+  The next call would cross your budget; floe-guard stopped your agent before it ran.
+```
+
+_Animated demo coming — run `python examples/runaway_loop.py` to watch it stop a loop live._
+<!-- TODO: record docs/stop-the-loop.gif and restore the embed: ![stop the loop](docs/stop-the-loop.gif) -->
+
+## See it stop a loop (no API key needed)
+
+```bash
+python examples/runaway_loop.py
+```
+
+This rigs a loop against a **stub LLM** — no real API key, no account, no network.
+It prices each fake `gpt-4o` call offline and the guard halts the loop after a few
+iterations. This is the reproducible "stop the loop" demo.
+
+## How it works
+
+The guard sits **in the call path**, not on an event bus. A passive listener is
+told about spend *after the fact* and can't halt anything — so enforcement has to
+be the thing standing in front of the next call:
+
+- **`check()`** runs before each LLM call. It predicts the next call's cost from
+  the last one and raises `BudgetExceeded` if that would cross your ceiling — the
+  call never runs. (A running-total check also catches an overshoot if an estimate
+  came in low.)
+- **`record(model, prompt_tokens, completion_tokens)`** runs after each response.
+  It prices the tokens **offline** from a bundled
+  [LiteLLM cost map](src/floe_guard/cost_map.json) and adds the USD to a running
+  total.
+
+### Unpriceable models fail closed
+
+If a model isn't in the cost map and you didn't supply a price, the guard **warns
+loudly and refuses** (`UnpriceableModelError`) rather than silently treat it as
+free — *you can't cap spend you can't measure.* Give it a price to enforce it:
+
+```python
+from floe_guard import BudgetGuard, ManualPrice
+
+guard = BudgetGuard(
+    limit_usd=5.00,
+    price_overrides={"my-self-hosted-model": ManualPrice(1e-6, 2e-6)},  # USD/token
+)
+# or, set fail_closed=False to warn-and-skip for models you accept un-metered.
+```
+
+## Framework adapters (optional extras)
+
+### CrewAI
+
+```bash
+pip install floe-guard[crewai]
+```
+
+```python
+from crewai import Crew
+from floe_guard import BudgetGuard
+from floe_guard.integrations.crewai import guard_crew
+
+guard = BudgetGuard(limit_usd=1.00)
+guard_crew(guard)              # one line — enforces across the whole crew
+Crew(agents=[...], tasks=[...]).kickoff()
+```
+
+CrewAI runs on LiteLLM, so one callback caps every agent and task under a single
+budget.
+
+### LiteLLM
+
+```bash
+pip install floe-guard[litellm]
+```
+
+```python
+from floe_guard import BudgetGuard
+from floe_guard.integrations.litellm import guarded_completion
+
+guard = BudgetGuard(limit_usd=1.00)
+response = guarded_completion(guard, model="gpt-4o", messages=[...])
+```
+
+Prefer the LiteLLM-native callback? Register `budget_guard_callback(guard)` on
+`litellm.callbacks`.
+
+### Coming next
+
+LangChain (callback) and the Vercel AI SDK (TypeScript middleware) are next. Open
+an issue if you want one sooner.
+
+## Honest about what this is
+
+floe-guard is a **local, estimate-based** guardrail. It prices tokens from a
+vendored cost map *inside your process*:
+
+- The cost map can drift as vendors change prices — refresh it like any snapshot.
+- It only sees the vendors you instrument.
+- A determined agent or a bug could route around an in-process check.
+
+It's genuinely useful on its own, and it's honest about its limits. No inflated
+metrics, no "zero defaults" claims — it's a free local stop, not a vault.
+
+## Upgrade to hosted Floe
+
+When you need the ceiling to be **un-bypassable** and **cross-vendor**, hosted
+Floe moves enforcement server-side against a real credit line:
+
+- **Un-bypassable** — enforced at the spend rail, not in your process.
+- **Cross-vendor** — one budget over LLM tokens *and* paid (x402) tool calls.
+- **Team budgets + analytics** — shared ceilings, per-agent isolation, spend history.
+
+Set `FLOE_API_KEY` and floe-guard exposes a hook to delegate enforcement to
+hosted Floe (see [`src/floe_guard/hosted.py`](src/floe_guard/hosted.py) — wiring
+the live endpoint is in progress; the local guard is fully functional today).
+
+→ **[dev-dashboard.floelabs.xyz](https://dev-dashboard.floelabs.xyz)** ·
+**[floelabs.xyz](https://floelabs.xyz)**
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest released version of `floe-guard` is supported with security fixes.
+Please upgrade to the latest version before reporting an issue.
+
+## Reporting a vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Report them privately by email to **security@floelabs.xyz**. If you do not get a
+response, use **hello@floelabs.xyz** as a fallback contact.
+
+Please include:
+
+- a description of the vulnerability and its impact,
+- steps to reproduce (a minimal proof of concept helps),
+- the affected version.
+
+## What to expect
+
+- We aim to acknowledge your report within **3 business days**.
+- We will keep you updated on our assessment and the fix.
+- Please give us a reasonable window to release a fix before any public disclosure.
+
+Thank you for helping keep `floe-guard` and its users safe.

docs/stop-the-loop.gif.PLACEHOLDER.txt

@@ -0,0 +1,6 @@
+TODO: record this GIF.
+
+This is a placeholder for docs/stop-the-loop.gif — a short screen recording of
+`python examples/runaway_loop.py` running and the guard printing
+`BUDGET EXCEEDED — call blocked`. Replace this file with the recorded .gif
+(keep the filename so the README reference resolves).

examples/runaway_loop.py

@@ -0,0 +1,58 @@
+"""Stop-the-loop demo — runs with NO API key and NO account.
+
+A naive agent loop that calls an LLM forever. The only thing standing between you
+and a five-figure overnight bill is ``floe-guard``: it hard-stops the loop before
+the call that would cross your $0.10 ceiling.
+
+Run it::
+
+    python examples/runaway_loop.py
+
+The "LLM" here is a stub that returns fixed token usage — no network, no key, no
+crewai/litellm needed. The cost is computed offline from the bundled cost map,
+exactly as it would be for a real ``gpt-4o`` call.
+"""
+
+from __future__ import annotations
+
+from floe_guard import BudgetExceeded, BudgetGuard
+
+MODEL = "gpt-4o"
+
+
+def stub_llm(prompt: str) -> dict[str, object]:
+    """A fake LLM call. No network, no API key — returns fixed token usage."""
+    return {
+        "model": MODEL,
+        "text": "...thinking... let me call myself again...",
+        "prompt_tokens": 1_000,
+        "completion_tokens": 1_000,
+    }
+
+
+def main() -> None:
+    # $0.10 ceiling. gpt-4o at 1k in + 1k out ≈ $0.0125/call, so the guard should
+    # stop the loop after a handful of iterations — well before any real damage.
+    guard = BudgetGuard(limit_usd=0.10)
+
+    print(f"Starting a runaway loop with a ${guard.limit_usd:.2f} budget...\n")
+    call = 0
+    while True:  # a real runaway loop never decides to stop on its own
+        call += 1
+        try:
+            guard.check()  # <-- the kill-switch: raises before the crossing call
+        except BudgetExceeded:
+            print(f"\nLoop stopped at call #{call}. The agent never got to spend past the budget.")
+            break
+
+        response = stub_llm("keep going")
+        cost = guard.record(
+            str(response["model"]),
+            int(response["prompt_tokens"]),  # type: ignore[arg-type]
+            int(response["completion_tokens"]),  # type: ignore[arg-type]
+        )
+        print(f"  call #{call}: +${cost:.4f}  (running total ${guard.spent_usd:.4f})")
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "floe-guard"
+version = "0.1.0"
+description = "Local budget guardrail for AI agents — hard-stops a runaway loop before its next LLM call crosses a spend ceiling. No account, no network."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Floe Labs" }]
+keywords = ["llm", "agents", "budget", "guardrail", "crewai", "litellm", "cost", "openai", "anthropic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+litellm = ["litellm>=1.0"]
+crewai = ["crewai>=0.30", "litellm>=1.0"]
+dev = ["pytest>=7.0", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://floelabs.xyz"
+Dashboard = "https://dev-dashboard.floelabs.xyz"
+Source = "https://github.com/Floe-Labs/floe-guard"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/floe_guard"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/floe_guard/cost_map.json" = "floe_guard/cost_map.json"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+filterwarnings = ["error::floe_guard.errors.UnpriceableModelWarning"]