fix: close fail-closed bypass for usage-present/model-missing responses

- litellm _record_response: route through guard.record() whenever a response
  has usage tokens, even if the model id is missing, so the guard's
  fail-closed/fail-open policy applies instead of a silent unmetered skip
  (which also skewed the next check() by leaving _last_cost stale). A
  no-usage response stays a no-op.
- errors: correct UnpriceableModelWarning docstring — the warning is ALWAYS
  emitted; fail-closed mode additionally raises UnpriceableModelError
- tests: usage-present/model-missing fails closed (and warns+skips when
  fail-open); no-usage response is a no-op

Author: achris7

src/floe_guard/errors.py

@@ -44,4 +44,9 @@ def __init__(self, model: str) -> None:
 
 
 class UnpriceableModelWarning(UserWarning):
-    """Warned (loudly) when an unpriceable model is seen in non-fail-closed mode."""
+    """Warned (loudly) whenever an unpriceable model is seen.
+
+    Always emitted regardless of ``fail_closed``. In fail-closed mode an
+    :class:`UnpriceableModelError` is additionally raised; in fail-open mode the
+    warning is emitted and the call's spend is skipped.
+    """

src/floe_guard/integrations/litellm.py

@@ -58,8 +58,14 @@ def _usage_from(response: Any) -> tuple[int, int]:
 def _record_response(guard: BudgetGuard, kwargs: dict[str, Any], response: Any) -> None:
     model = _model_from(kwargs, response)
     prompt_tokens, completion_tokens = _usage_from(response)
-    if model:
-        guard.record(model, prompt_tokens, completion_tokens)
+    if prompt_tokens <= 0 and completion_tokens <= 0:
+        # No tokens were spent (e.g. a usage-less event) — nothing to meter.
+        return
+    # There IS spend to account for. Route it through record() even when the
+    # model id is missing, so the guard's configured policy applies (fail-closed
+    # → warn + raise; fail-open → warn + skip). Silently skipping here would let
+    # a real, completed call go unmetered and skew the next check().
+    guard.record(model, prompt_tokens, completion_tokens)
 
 
 def guarded_completion(guard: BudgetGuard, **kwargs: Any) -> Any:

tests/test_litellm_adapter.py

@@ -11,7 +11,7 @@
 
 import pytest
 
-from floe_guard import BudgetGuard
+from floe_guard import BudgetGuard, UnpriceableModelError, UnpriceableModelWarning
 from floe_guard.integrations.litellm import _model_from, _record_response, _usage_from
 
 
@@ -55,3 +55,30 @@ def test_record_response_accrues_dict_response() -> None:
     resp = {"model": "gpt-4o", "usage": {"prompt_tokens": 1_000, "completion_tokens": 1_000}}
     _record_response(guard, {}, resp)
     assert guard.spent_usd == pytest.approx(0.0125)
+
+
+def test_usage_present_but_model_missing_fails_closed() -> None:
+    # The Major fix: tokens were spent but the model id is missing. This MUST go
+    # through record() (fail-closed → raise), not be silently skipped unmetered.
+    guard = BudgetGuard(limit_usd=1.0)  # fail_closed defaults to True
+    resp = {"usage": {"prompt_tokens": 1_000, "completion_tokens": 1_000}}
+    with pytest.warns(UnpriceableModelWarning):
+        with pytest.raises(UnpriceableModelError):
+            _record_response(guard, {}, resp)
+    assert guard.spent_usd == 0.0
+
+
+def test_usage_present_but_model_missing_fail_open_warns_and_skips() -> None:
+    guard = BudgetGuard(limit_usd=1.0, fail_closed=False)
+    resp = {"usage": {"prompt_tokens": 1_000, "completion_tokens": 1_000}}
+    with pytest.warns(UnpriceableModelWarning):
+        _record_response(guard, {}, resp)
+    assert guard.spent_usd == 0.0
+
+
+def test_no_usage_response_is_a_noop() -> None:
+    # A genuinely empty (no-usage) response: nothing spent, so no record/raise.
+    guard = BudgetGuard(limit_usd=1.0)
+    _record_response(guard, {}, {})  # no model, no usage
+    _record_response(guard, {}, {"usage": {"prompt_tokens": 0, "completion_tokens": 0}})
+    assert guard.spent_usd == 0.0