Merge pull request #32 from Floe-Labs/release/py-0.2.0-groq-pricing-crewai-hardstop

release: py 0.2.0 / js 0.2.1 — Groq pricing, reliable CrewAI hard-stop, gated publishing

Author: shivamfloe

.github/workflows/ci.yml

@@ -62,8 +62,10 @@ jobs:
           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]"
+      # (instead of skipping). langchain-core covers the LangChain handler
+      # tests; litellm covers the callback-swallowing regression tests (the
+      # CrewAI adapter tests stub crewai itself, so the heavy extra stays out).
+      - run: pip install -e ".[dev,langchain,litellm]"
       - name: Pytest
         run: pytest -q
 

.github/workflows/publish-npm.yml

@@ -1,24 +1,34 @@
 name: Publish to npm
 
+# Runs after the full CI workflow succeeds on main (not on the raw push), so a
+# red lint/cost-map-sync/python job blocks an npm release too. The old js/**
+# path filter is gone; the version gate below already makes no-op runs cheap.
 on:
-  push:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
     branches: [main]
-    # The npm package lives in js/; only publish when it (or this workflow) changes.
-    paths:
-      - 'js/**'
-      - '.github/workflows/publish-npm.yml'
   workflow_dispatch:
 
 concurrency:
   group: publish-npm-${{ github.ref }}
   cancel-in-progress: false
 
 permissions:
-  contents: read
+  contents: write # push the release tag; npm auth stays the token secret
 
 jobs:
   publish:
-    if: github.ref == 'refs/heads/main'
+    # workflow_run's `branches` filter matches the HEAD branch NAME of the
+    # triggering run — a fork PR from a branch named "main" would match it. The
+    # event/head_repository checks restrict publishing to push-triggered CI on
+    # this repo's own main.
+    if: >-
+      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') ||
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push' &&
+       github.event.workflow_run.head_repository.full_name == github.repository)
     runs-on: ubuntu-latest
     timeout-minutes: 15
     defaults:
@@ -28,6 +38,9 @@ jobs:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           persist-credentials: false
+          # workflow_run checks out the default branch by default; pin to the
+          # exact commit CI validated.
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
 
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
@@ -69,3 +82,16 @@ jobs:
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Tag the release
+        # Maps the published artifact back to its exact commit ("js-" prefix:
+        # the PyPI package versions independently and tags "py-v<version>").
+        if: steps.check.outputs.should_publish == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PKG_VERSION: ${{ steps.check.outputs.version }}
+        run: |
+          gh api "repos/${{ github.repository }}/git/refs" \
+            -f ref="refs/tags/js-v$PKG_VERSION" \
+            -f sha="$(git rev-parse HEAD)" \
+            || echo "::warning::tag js-v$PKG_VERSION already exists or could not be created"

.github/workflows/publish.yml

@@ -1,7 +1,12 @@
 name: Publish to PyPI
 
+# Runs after the full CI workflow (lint, python matrix, cost-map-sync, js)
+# succeeds on main — not on the raw push. npm 0.2.0 once shipped while main CI
+# was red on cost-map-sync; gating on workflow_run closes that hole.
 on:
-  push:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
     branches: [main]
   workflow_dispatch:
 
@@ -10,17 +15,29 @@ concurrency:
   cancel-in-progress: false
 
 permissions:
-  contents: read
+  contents: write # push the release tag; PyPI auth stays the token secret
 
 jobs:
   publish:
-    if: github.ref == 'refs/heads/main'
+    # workflow_run's `branches` filter matches the HEAD branch NAME of the
+    # triggering run — a fork PR from a branch named "main" would match it. The
+    # event/head_repository checks restrict publishing to push-triggered CI on
+    # this repo's own main.
+    if: >-
+      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main') ||
+      (github.event_name == 'workflow_run' &&
+       github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event == 'push' &&
+       github.event.workflow_run.head_repository.full_name == github.repository)
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           persist-credentials: false
+          # workflow_run checks out the default branch by default; pin to the
+          # exact commit CI validated.
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
 
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
@@ -77,3 +94,16 @@ jobs:
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Tag the release
+        # Maps the published artifact back to its exact commit ("py-" prefix:
+        # the npm package versions independently and tags "js-v<version>").
+        if: steps.check.outputs.should_publish == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PKG_VERSION: ${{ steps.meta.outputs.version }}
+        run: |
+          gh api "repos/${{ github.repository }}/git/refs" \
+            -f ref="refs/tags/py-v$PKG_VERSION" \
+            -f sha="$(git rev-parse HEAD)" \
+            || echo "::warning::tag py-v$PKG_VERSION already exists or could not be created"

.github/workflows/version-guard.yml

@@ -0,0 +1,66 @@
+name: Version Guard
+
+# Publishing is version-gated on main, so a source change merged without a
+# version bump silently never ships — that is exactly how PyPI fell 3.5 weeks
+# behind the repo. Fail the PR instead, unless the change is deliberately
+# unreleased (apply the skip-version-guard label).
+#
+# Lives in its own workflow (not ci.yml) so the labeled/unlabeled trigger types
+# — needed for the skip label to re-evaluate without a manual re-run — don't
+# re-run and cancel the whole CI matrix on every label change.
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+concurrency:
+  group: version-guard-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  version-guard:
+    if: ${{ !contains(github.event.pull_request.labels.*.name, 'skip-version-guard') }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+          # The checkout is refs/pull/N/merge — a synthetic merge commit whose
+          # first parent is the CURRENT base tip. Depth 2 makes HEAD^1
+          # resolvable; comparing against it (rather than the event's
+          # pull_request.base.sha snapshot, which goes stale as the base moves)
+          # means a release merged to main after the PR opened still counts.
+          fetch-depth: 2
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: '3.13'
+      - name: Require a version bump when package source changes
+        run: |
+          set -euo pipefail
+          changed=$(git diff --name-only HEAD^1 HEAD)
+          fail=0
+
+          # pyproject.toml is included: dependency/extras changes alter the
+          # shipped artifact just like src changes do.
+          if echo "$changed" | grep -q '^\(src/floe_guard/\|pyproject\.toml\)'; then
+            old=$(git show "HEAD^1:pyproject.toml" | python -c "import sys,tomllib;print(tomllib.loads(sys.stdin.read())['project']['version'])")
+            new=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+            if [ "$old" = "$new" ]; then
+              echo "::error::Python package source or packaging metadata changed but pyproject.toml version is still $new — bump it (or label the PR skip-version-guard)."
+              fail=1
+            fi
+          fi
+
+          if echo "$changed" | grep -q '^js/\(src/\|package\.json\)'; then
+            old=$(git show "HEAD^1:js/package.json" | python -c "import sys,json;print(json.loads(sys.stdin.read())['version'])")
+            new=$(python -c "import json;print(json.load(open('js/package.json'))['version'])")
+            if [ "$old" = "$new" ]; then
+              echo "::error::js package source or packaging metadata changed but js/package.json version is still $new — bump it (or label the PR skip-version-guard)."
+              fail=1
+            fi
+          fi
+
+          exit "$fail"

CHANGELOG.md

@@ -10,10 +10,83 @@ both packages adhere to [Semantic Versioning](https://semver.org/).
 
 ## Unreleased
 
-## js 0.2.0 — 2026-07-08
+## py 0.2.0 / js 0.2.1 — 2026-07-10
+
+Everything the repo grew between the 0.1.0 uploads and this release ships here —
+the earlier revision of this changelog misattributed several of these features
+to the py 0.1.0 entry; that entry now reflects what the released artifact
+actually contained.
+
+### Added (py)
+
+- **Concurrency-safe enforcement**: atomic `reserve()` / `settle()` /
+  `release()` with a lock-guarded running total, closing the
+  check-then-record race that let parallel callers blow the ceiling
+  (issue #18). `check()` / `record()` are unchanged for sequential use.
+- **Context-aware budgeting**: `BudgetGuard.advisory()` returning a
+  `BudgetAdvisory` (`near_limit`, `used_bps`, `remaining_usd`, totals), with a
+  `near_limit_bps` constructor threshold (default 8000 = 80%).
+- **Adapters**: LangChain (`budget_guard_callback_handler`), OpenAI
+  (`guarded_completion` / `guarded_acompletion`), and Anthropic (same pair,
+  with cache-token metering) — each behind an optional extra
+  (`[langchain]`, `[openai]`, `[anthropic]`).
+- **Hosted budget read**: `hosted_remaining_usd()` (GET
+  `/v1/agents/credit-remaining`, opt-in via `FLOE_API_KEY`, host override via
+  `FLOE_API_BASE_URL`), `HostedEnforcementError`, and package-root export of
+  `hosted_enforcement_available()`. This is the package's only network call
+  and never runs unless you set the key.
+
+### Added (py + js)
+
+- **Groq pricing**: curated Groq models vendored in the cost map —
+  `llama-3.1-8b-instant`, `llama-3.3-70b-versatile`,
+  `meta-llama/llama-4-scout-17b-16e-instruct`, `qwen/qwen3-32b` (new for py;
+  these four already shipped in js 0.2.0), plus the current production lineup
+  `openai/gpt-oss-120b`, `openai/gpt-oss-20b`, `openai/gpt-oss-safeguard-20b`
+  (new for both packages). Kept as an explicit allowlist
+  (`scripts/update-cost-map.mjs`) so generic multi-provider names stay
+  fail-closed instead of under-metering.
+- **Smarter model-id resolution** (both packages, identical logic): lookup
+  candidates are tried most-specific-first — the raw id, the id with a known
+  `openai/` / `anthropic/` / `groq/` first segment stripped (so
+  `groq/qwen/qwen3-32b` and ChatGroq's `qwen/qwen3-32b` hit the same entry),
+  then the bare last segment; each also with a trailing dated-snapshot suffix
+  removed, so an unlisted snapshot like `claude-opus-4-8-<date>` prices at its
+  alias entry instead of failing closed. Unknown provider prefixes are
+  deliberately not bridged.
+- Cost-map refresh adds `claude-sonnet-5` (both packages; the py package also
+  gains `claude-fable-5`, which already shipped in js 0.2.0 —
+  `claude-opus-4-8` and `claude-sonnet-4-6` shipped in the 0.1.0 maps) and
+  warns when a curated Groq model disappears upstream instead of silently
+  dropping it.
+
+### Fixed (py)
+
+- **CrewAI / LiteLLM-callback silent footgun**: LiteLLM runs custom-logger
+  hooks inside `except Exception`, so the callback's enforcement raise
+  (pre-call `BudgetExceeded`, fail-closed `UnpriceableModelError`) could be
+  swallowed and a crew kept running unmetered with no visible signal. The
+  callback now records the violation on its `tripped` attribute and logs it at
+  ERROR level on the `floe_guard` logger, and
+  `budget_guarded_llm` returns a `crewai.LLM` subclass that re-raises
+  `tripped` and runs `check()` in the call path — outside LiteLLM — so the
+  crew hard-stops at the next call. `guard_crew` now returns the registered
+  callback (previously `None`) and reuses an existing registration for the
+  same guard.
+
+### Changed (py + js)
+
+- Price lookup order is now most-specific-first (raw id before stripped
+  forms) for both `price_overrides` and the cost map. Previously the bare name
+  was tried before the raw id.
+
+## js 0.2.0 — published 2026-07-10
 
 ### Added
 
+- Curated Groq cost-map entries: `llama-3.1-8b-instant`,
+  `llama-3.3-70b-versatile`, `meta-llama/llama-4-scout-17b-16e-instruct`,
+  `qwen/qwen3-32b`, plus `claude-fable-5`.
 - **Vercel AI SDK v5 support.** The middleware now works with both `ai@4`
   (`LanguageModelV1Middleware`, `promptTokens`/`completionTokens`) and `ai@5`
   (`LanguageModelV2Middleware`, `inputTokens`/`outputTokens`) from a single
@@ -30,18 +103,18 @@ both packages adhere to [Semantic Versioning](https://semver.org/).
 
 ## py 0.1.0 / js 0.1.0 — 2026-06
 
-Initial public release.
+Initial public releases (PyPI 2026-06-15, npm 2026-06-16).
 
-- `BudgetGuard` with `check()` / `record()`, concurrency-safe
-  `reserve()` / `settle()` / `release()`, and `advisory()` for context-aware
-  budgeting (taper before the hard-stop).
-- Offline pricing from a vendored LiteLLM cost map; unpriceable models fail
-  closed (`UnpriceableModelError`) with manual `price_overrides` as the
-  escape hatch.
-- Python adapters: CrewAI, LiteLLM, LangChain, OpenAI, Anthropic — each behind
-  an optional extra; the core stays dependency-free.
+- `BudgetGuard` with `check()` / `record()` (sequential; the atomic
+  reservation API landed in py 0.2.0).
+- Offline pricing from a vendored LiteLLM cost map covering OpenAI and
+  Anthropic; unpriceable models fail closed (`UnpriceableModelError`) with
+  manual `price_overrides` as the escape hatch.
+- Python adapters: CrewAI and LiteLLM, behind optional extras; the core stays
+  dependency-free. (The LangChain, OpenAI, and Anthropic adapters landed in
+  py 0.2.0.)
+- Hosted-Floe hook as a stub (`hosted_enforcement_available()` under
+  `floe_guard.hosted`); this release performs no network calls of any kind.
 - TypeScript package (`js/`) with Vercel AI SDK middleware
   (`budgetGuardMiddleware`), verified against `ai@4`.
-- Optional hosted-Floe budget read (`hosted_remaining_usd()`) via
-  `FLOE_API_KEY` — the only network call in the package, opt-in.
 - No runtime telemetry of any kind.

README.md

@@ -103,6 +103,23 @@ guard = BudgetGuard(
 # or, set fail_closed=False to warn-and-skip for models you accept un-metered.
 ```
 
+### What the bundled map prices
+
+The vendored map deliberately covers **OpenAI, Anthropic, and a curated set of
+Groq models** (the allowlist lives in
+[`scripts/update-cost-map.mjs`](scripts/update-cost-map.mjs)) — not all of
+LiteLLM's upstream list. Generic open-weights names (`qwen3-32b`,
+`gpt-oss-120b`) are served by many vendors at very different prices, so
+resolving them at one vendor's rate would under-meter a spend guard; they stay
+unpriceable unless you scope them (`groq/…`) or pass a manual price.
+
+Model ids resolve flexibly: provider-prefixed forms work
+(`openai/gpt-4o`, `groq/qwen/qwen3-32b` and the ChatGroq `qwen/qwen3-32b` both
+hit the same entry), and a dated snapshot the map doesn't list yet
+(`claude-opus-4-8-<date>`) prices at its alias entry instead of failing closed.
+Everything else — Gemini, Mistral, Cohere, Ollama, Bedrock, self-hosted —
+needs `price_overrides` (or `fail_closed=False` to accept it un-metered).
+
 ## Context-aware budgeting
 
 The hard-stop is the guarantee; `advisory()` is the *upside*. Read it before a
@@ -142,17 +159,26 @@ pip install floe-guard[crewai]
 ```
 
 ```python
-from crewai import Crew
+from crewai import Agent, Crew
 from floe_guard import BudgetGuard
-from floe_guard.integrations.crewai import guard_crew
+from floe_guard.integrations.crewai import budget_guarded_llm
 
 guard = BudgetGuard(limit_usd=1.00)
-guard_crew(guard)              # one line — enforces across the whole crew
-Crew(agents=[...], tasks=[...]).kickoff()
+llm = budget_guarded_llm(guard, "gpt-4o")   # meters AND hard-stops
+Crew(agents=[Agent(..., llm=llm)], tasks=[...]).kickoff()
 ```
 
-CrewAI runs on LiteLLM, so one callback caps every agent and task under a single
-budget.
+CrewAI runs on LiteLLM, so one callback meters every agent and task under a
+single budget. Use `budget_guarded_llm` (not just `guard_crew`) to get the hard
+stop: LiteLLM can swallow exceptions raised inside its callbacks (verified on
+litellm 1.91.x), so a callback alone may keep the crew running past a
+violation. `budget_guarded_llm` also enforces in the LLM call path — where a
+raise reliably reaches CrewAI — re-raising any violation the callback recorded
+before the next call runs. `guard_crew(guard)` remains available for metering
+existing crews; check the returned callback's `tripped` attribute (and the
+`floe_guard` logger's ERROR output) if you use it alone. A recorded violation
+latches for the life of the callback — after remediating (say, adding a price
+override), call `callback.reset()` or build a fresh guard.
 
 ### LiteLLM
 
@@ -169,7 +195,12 @@ response = guarded_completion(guard, model="gpt-4o", messages=[...])
 ```
 
 Prefer the LiteLLM-native callback? Register `budget_guard_callback(guard)` on
-`litellm.callbacks`.
+`litellm.callbacks` — but know its limit: LiteLLM runs callbacks inside
+`except Exception`, so the callback's enforcement raise can be swallowed and
+your loop keeps going. The callback records any violation on its `tripped`
+attribute and logs it at ERROR level; consult `tripped` in your own loop, or
+use `guarded_completion` (which enforces at the call site) for the guaranteed
+stop. Wrapper enforcement is tested against litellm 1.91.x.
 
 ### LangChain