Merge remote-tracking branch 'origin/main' into feat/vercel-ai-sdk

# Conflicts:
#	README.md

Author: Copilot

.github/workflows/ci.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.13'
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check .
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      # Install the framework extras so the adapter handler tests actually run
+      # (instead of skipping). langchain-core covers the LangChain handler tests.
+      - run: pip install -e ".[dev,langchain]"
+      - name: Pytest
+        run: pytest -q
+
+  test-bare:
+    # Locks the dependency-free contract: the package and its test suite must
+    # work with NO framework extra installed (handler tests skip cleanly, no
+    # import errors). This is what publish.yml runs before releasing.
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.13'
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - name: Pytest (no extras)
+        run: pytest -q

README.md

@@ -1,5 +1,10 @@
 # floe-guard
 
+[![PyPI version](https://img.shields.io/pypi/v/floe-guard.svg)](https://pypi.org/project/floe-guard/)
+[![Downloads](https://static.pepy.tech/badge/floe-guard/month)](https://pepy.tech/project/floe-guard)
+[![Python versions](https://img.shields.io/pypi/pyversions/floe-guard.svg)](https://pypi.org/project/floe-guard/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
 **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.
@@ -26,8 +31,9 @@ BUDGET EXCEEDED — call blocked
   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) -->
+![floe-guard hard-stopping a runaway loop before it crosses a $0.10 ceiling](docs/stop-the-loop.gif)
+
+_Run it yourself: `python examples/runaway_loop.py` — no API key, no account, no network._
 
 ## See it stop a loop (no API key needed)
 
@@ -108,6 +114,25 @@ response = guarded_completion(guard, model="gpt-4o", messages=[...])
 Prefer the LiteLLM-native callback? Register `budget_guard_callback(guard)` on
 `litellm.callbacks`.
 
+### LangChain
+
+```bash
+pip install floe-guard[langchain] langchain-openai   # langchain-openai only for the ChatOpenAI example below
+```
+
+```python
+from langchain_openai import ChatOpenAI
+from floe_guard import BudgetGuard
+from floe_guard.integrations.langchain import budget_guard_callback_handler
+
+guard = BudgetGuard(limit_usd=1.00)
+llm = ChatOpenAI(model="gpt-4o", callbacks=[budget_guard_callback_handler(guard)])
+llm.invoke("hello")            # checks budget before the call, records spend after
+```
+
+The handler checks the budget on LLM start (raising `BudgetExceeded` aborts the
+call before it runs) and records token usage on LLM end.
+
 ### Vercel AI SDK
 
 The Vercel AI SDK is TypeScript-only, so it ships as a separate npm package that
@@ -133,10 +158,6 @@ The middleware `check()`s before each call (throwing `BudgetExceeded` to halt th
 run) and `record()`s priced usage after — same semantics as the Python guard. See
 [`js/README.md`](js/README.md).
 
-### Coming next
-
-LangChain (callback) is 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
@@ -158,12 +179,45 @@ Floe moves enforcement server-side against a real credit line:
 - **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).
+Set `FLOE_API_KEY` (your agent key, `floe_<hex>`) and floe-guard can read your
+agent's **server-side remaining budget** from the live Floe endpoint:
+
+```python
+from floe_guard import hosted_enforcement_available, hosted_remaining_usd
+
+if hosted_enforcement_available():       # True when FLOE_API_KEY is set
+    remaining = hosted_remaining_usd()   # USD left, read from Floe's server
+```
+
+`hosted_remaining_usd()` GETs `/v1/agents/credit-remaining` and returns the USD
+remaining — the minimum of your auto-borrow headroom and your session spend
+remaining. It raises `HostedEnforcementError` on a bad/missing key (401), a
+closed or suspended agent (403), an unprovisioned agent (404), or a network
+failure.
+
+Env vars:
 
-→ **[dev-dashboard.floelabs.xyz](https://dev-dashboard.floelabs.xyz)** ·
-**[floelabs.xyz](https://floelabs.xyz)**
+- `FLOE_API_KEY` — your agent key. Required for the read.
+- `FLOE_API_BASE_URL` — override the API host (defaults to
+  `https://credit-api.floelabs.xyz`).
+
+Honest scope: this call only **reads** the remaining budget. The un-bypassable,
+cross-vendor *enforcement* is the hosted Floe product running server-side — not
+this client. Use the number to inform a local ceiling; the server stays the
+source of truth.
+
+→ **[dev-dashboard.floelabs.xyz](https://dev-dashboard.floelabs.xyz/?utm_source=floe-guard&utm_medium=readme&utm_campaign=oss)** ·
+**[floelabs.xyz](https://floelabs.xyz/?utm_source=floe-guard&utm_medium=readme&utm_campaign=oss)**
+
+## Built with floe-guard
+
+Using floe-guard in your project? Add the badge so others find it:
+
+[![guarded by floe-guard](https://img.shields.io/badge/guarded%20by-floe--guard-2f81f7.svg)](https://github.com/Floe-Labs/floe-guard)
+
+```markdown
+[![guarded by floe-guard](https://img.shields.io/badge/guarded%20by-floe--guard-2f81f7.svg)](https://github.com/Floe-Labs/floe-guard)
+```
 
 ## Development
 

docs/INSTRUMENTATION.md

@@ -0,0 +1,65 @@
+# Instrumentation
+
+How we measure floe-guard's adoption — and the one thing we deliberately *don't* do.
+
+## No runtime telemetry (deliberate)
+
+floe-guard does **not** phone home. It sends no usage events, no install pings, no
+identifiers — nothing leaves your process at runtime except hosted-budget reads
+you explicitly opt into by setting `FLOE_API_KEY` (the *Upgrade to hosted Floe*
+path) — never otherwise.
+
+This is a choice, not an oversight. A guardrail's whole value is trust: a library
+that silently exfiltrates usage from people's agents is the opposite of a tool you
+hand a budget to. Runtime telemetry in OSS dev tools reliably triggers backlash
+and forks. So we measure adoption only from **public, outside-in signals** — the
+ones below — and accept that they're coarser than telemetry. That trade is correct
+for this project.
+
+## The signals we track
+
+| Runbook KPI | How it's measured | Source |
+|---|---|---|
+| Star velocity | GitHub stargazers over time | `scripts/metrics.py` → GitHub API |
+| Fork count | GitHub forks | `scripts/metrics.py` |
+| Install velocity (`pip install`) | PyPI download counts (day/week/month) | `scripts/metrics.py` → pypistats.org |
+| README reach | repo views & unique clones | `scripts/metrics.py` (needs `GITHUB_TOKEN`) |
+| README → site click-through | UTM params on outbound links | Floe web analytics |
+| Install → hosted signup | UTM `utm_source=floe-guard` lands in the signup funnel | Floe web analytics |
+| "Built with floe-guard" usage | badge backlinks | GitHub code/badge search |
+
+### Snapshot script
+
+```bash
+python scripts/metrics.py                    # stars, forks, PyPI downloads
+GITHUB_TOKEN=ghp_xxx python scripts/metrics.py   # + repo views/clones
+```
+
+It prints real numbers only — if a source is unreachable it says so rather than
+guessing. Run it on a schedule and diff snapshots to get *velocity* (the runbook's
+actual target), not just totals.
+
+### UTM scheme
+
+Outbound links in the README carry:
+
+```
+?utm_source=floe-guard&utm_medium=readme&utm_campaign=oss
+```
+
+So clicks from this repo into `dev-dashboard.floelabs.xyz` / `floelabs.xyz` are
+attributable in Floe's web analytics, and any session that converts to a hosted
+signup keeps `utm_source=floe-guard` — that's the **install → signup** handoff the
+runbook calls the critical metric. The conversion side lives in the Floe web app's
+funnel, not in this repo.
+
+### "Built with floe-guard" badge
+
+Downstream projects can advertise usage with the badge in the README's *Built with
+floe-guard* section. Each embed is a backlink — searchable on GitHub — and is the
+honest version of a "powered by" usage signal (opt-in, public, no tracking).
+
+## What's still manual
+
+- Posting the launch content and seeding (the runbook's Week-1/2 GTM motion).
+- Wiring the UTM-tagged sessions into a dashboard on the Floe web side.

docs/stop-the-loop.gif

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }
 authors = [{ name = "Floe Labs" }]
-keywords = ["llm", "agents", "budget", "guardrail", "crewai", "litellm", "cost", "openai", "anthropic"]
+keywords = ["llm", "agents", "budget", "guardrail", "crewai", "litellm", "langchain", "cost", "openai", "anthropic"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -26,6 +26,7 @@ dependencies = []
 [project.optional-dependencies]
 litellm = ["litellm>=1.0"]
 crewai = ["crewai>=0.30", "litellm>=1.0"]
+langchain = ["langchain-core>=0.3"]
 dev = ["pytest>=7.0", "ruff>=0.4"]
 
 [project.urls]

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

@@ -0,0 +1,93 @@
+"""Pull floe-guard's public adoption metrics into a single snapshot.
+
+No dependencies — stdlib only. Reads public APIs:
+  - GitHub repo stats (stars, forks, watchers)         — no auth needed
+  - GitHub traffic (views, clones)                     — needs a token with push access
+  - PyPI downloads (last day / week / month)           — no auth needed (pypistats.org)
+
+Usage:
+    python scripts/metrics.py
+    GITHUB_TOKEN=ghp_xxx python scripts/metrics.py   # also fetch traffic (views/clones)
+
+These are the runbook KPIs (star velocity, forks, install velocity). Run it on a
+schedule and diff snapshots to get velocity. It only reports real numbers — if a
+source is unreachable it says so rather than guessing.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+REPO = "Floe-Labs/floe-guard"
+PACKAGE = "floe-guard"
+
+
+def _get(
+    url: str, headers: dict[str, str] | None = None, timeout: float = 15.0
+) -> dict[str, object]:
+    req = urllib.request.Request(url, headers=headers or {})
+    with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 (trusted hosts)
+        return json.loads(resp.read().decode())
+
+
+def github_repo() -> dict[str, object]:
+    try:
+        d = _get(
+            f"https://api.github.com/repos/{REPO}",
+            headers={"Accept": "application/vnd.github+json", "User-Agent": "floe-guard-metrics"},
+        )
+        return {
+            "stars": d.get("stargazers_count"),
+            "forks": d.get("forks_count"),
+            "watchers": d.get("subscribers_count"),
+            "open_issues": d.get("open_issues_count"),
+        }
+    except (urllib.error.URLError, ValueError) as e:
+        return {"error": f"github repo stats unavailable: {e}"}
+
+
+def github_traffic() -> dict[str, object]:
+    token = os.environ.get("GITHUB_TOKEN", "").strip()
+    if not token:
+        return {"note": "set GITHUB_TOKEN (push access) to fetch views/clones"}
+    hdr = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "floe-guard-metrics",
+    }
+    out: dict[str, object] = {}
+    for kind in ("views", "clones"):
+        try:
+            d = _get(f"https://api.github.com/repos/{REPO}/traffic/{kind}", headers=hdr)
+            out[kind] = {"count": d.get("count"), "uniques": d.get("uniques")}
+        except (urllib.error.URLError, ValueError) as e:
+            out[kind] = {"error": str(e)}
+    return out
+
+
+def pypi_downloads() -> dict[str, object]:
+    try:
+        d = _get(
+            f"https://pypistats.org/api/packages/{PACKAGE}/recent",
+            headers={"User-Agent": "floe-guard-metrics"},
+        )
+        return d.get("data", {"error": "no data field"})
+    except (urllib.error.URLError, ValueError) as e:
+        return {"error": f"pypistats unavailable (new packages take ~1 day to appear): {e}"}
+
+
+def main() -> None:
+    snapshot = {
+        "repo": REPO,
+        "package": PACKAGE,
+        "github": github_repo(),
+        "traffic": github_traffic(),
+        "pypi_downloads_recent": pypi_downloads(),
+    }
+    print(json.dumps(snapshot, indent=2))
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -16,10 +16,12 @@
 from .errors import (
     BudgetExceeded,
     FloeGuardError,
+    HostedEnforcementError,
     UnpriceableModelError,
     UnpriceableModelWarning,
 )
 from .guard import BudgetGuard
+from .hosted import hosted_enforcement_available, hosted_remaining_usd
 from .pricing import ManualPrice, PricedModel, price_tokens, resolve_price
 
 __version__ = "0.1.0"
@@ -28,10 +30,13 @@
     "BudgetGuard",
     "BudgetExceeded",
     "FloeGuardError",
+    "HostedEnforcementError",
     "UnpriceableModelError",
     "UnpriceableModelWarning",
     "ManualPrice",
     "PricedModel",
     "price_tokens",
     "resolve_price",
+    "hosted_enforcement_available",
+    "hosted_remaining_usd",
 ]