feat(firmware): credit balance tracking and dollar displays

Author: b3nw

src/rotator_library/client/rotating_client.py

@@ -524,6 +524,25 @@ async def get_quota_stats(
 
             stats = await manager.get_stats_for_endpoint()
 
+            # Filter out stale quota groups that no longer exist in the provider's
+            # current model_quota_groups (e.g. after a group rename like
+            # firmware_global → credits($))
+            plugin = self._get_provider_instance(provider)
+            if plugin and hasattr(plugin, "model_quota_groups"):
+                valid_groups = set(plugin.model_quota_groups.keys())
+                if valid_groups:
+                    stale_groups = [
+                        g
+                        for g in stats.get("quota_groups", {})
+                        if g not in valid_groups
+                    ]
+                    for g in stale_groups:
+                        del stats["quota_groups"][g]
+                    # Also clean stale groups from per-credential group_usage
+                    for cred_data in stats.get("credentials", {}).values():
+                        for g in stale_groups:
+                            cred_data.get("group_usage", {}).pop(g, None)
+
             # Skip providers with no activity AND no quota data
             # (filters out invalid/unused providers, but keeps quota-tracked providers visible)
             has_requests = stats.get("total_requests", 0) > 0

src/rotator_library/providers/firmware_provider.py

@@ -1,8 +1,8 @@
 """
 Firmware.ai Provider with Quota Tracking
 
-Provider implementation for the Firmware.ai API with 5-hour rolling window quota tracking.
-Uses the FirmwareQuotaTracker mixin to fetch quota usage from their API.
+Provider implementation for the Firmware.ai API with credit-based quota tracking.
+Uses the FirmwareQuotaTracker mixin to fetch credit balance from their API.
 
 Environment variables:
     FIRMWARE_API_BASE: API base URL (default: https://app.firmware.ai/api/v1)
@@ -34,10 +34,12 @@ class FirmwareProvider(FirmwareQuotaTracker, ProviderInterface):
     Provider implementation for the Firmware.ai API with quota tracking.
     """
 
-    # Quota groups for tracking 5-hour rolling window limits
+    # Quota groups for tracking credit-based limits
     # Uses a virtual model "firmware/_quota" for credential-level quota tracking
+    # Single quota group: all models share the same credential-level credit balance.
+    # Named 'credits($)' so the TUI auto-formats values as dollars.
     model_quota_groups = {
-        "firmware_global": ["firmware/_quota"],
+        "credits($)": ["firmware/_quota"],
     }
 
     def __init__(self, *args, **kwargs):
@@ -74,22 +76,22 @@ def get_model_quota_group(self, model: str) -> Optional[str]:
         Returns:
             Quota group identifier for shared credential-level tracking
         """
-        return "firmware_global"
+        return "credits($)"
 
     def get_models_in_quota_group(self, group: str) -> List[str]:
         """
         Get all models in a quota group.
 
         For Firmware.ai, we use a virtual model "firmware/_quota" to track the
-        credential-level 5-hour rolling window quota.
+        credential-level credit-based quota.
 
         Args:
             group: Quota group name
 
         Returns:
             List of model names in the group
         """
-        if group == "firmware_global":
+        if group == "credits($)":
             return ["firmware/_quota"]
         return []
 
@@ -98,17 +100,16 @@ def get_usage_reset_config(self, credential: str) -> Optional[Dict[str, Any]]:
         Return usage reset configuration for Firmware.ai credentials.
 
         Firmware.ai uses per_model mode to track usage at the model level,
-        with 5-hour rolling window quotas managed via the background job.
+        with credit-based quota managed via the background job.
 
         Args:
             credential: The API key (unused, same config for all)
 
         Returns:
-            Configuration with per_model mode and 5-hour window
+            Configuration with per_model mode
         """
         return {
             "mode": "per_model",
-            "window_seconds": 18000,  # 5 hours (5-hour rolling window)
             "field_name": "models",
         }
 
@@ -179,12 +180,16 @@ async def refresh_single_credential(
                         self._quota_cache[api_key] = usage_data
 
                         # Calculate values for usage manager
+                        credits_balance = usage_data.get("credits", 0.0)
                         remaining_fraction = usage_data.get("remaining_fraction", 0.0)
-                        reset_ts = usage_data.get("reset_at")
 
                         # Store baseline in usage manager
                         # Since Firmware.ai uses credential-level quota, we use a virtual model name
-                        if remaining_fraction <= 0.0 and reset_ts:
+                        # Express credits as synthetic request-count values (in cents)
+                        # so the quota group window gets a non-zero limit for visibility
+                        credits_as_cents = int(credits_balance * 100)
+
+                        if remaining_fraction <= 0.0:
                             stable_id = usage_manager.registry.get_stable_id(
                                 api_key, usage_manager.provider
                             )
@@ -193,20 +198,22 @@ async def refresh_single_credential(
                                 await usage_manager.tracking.apply_cooldown(
                                     state=state,
                                     reason="quota_exhausted",
-                                    until=reset_ts,
+                                    duration=3600,  # 1 hour cooldown
                                     model_or_group="firmware/_quota",
                                     source="api_quota",
                                 )
                         await usage_manager.update_quota_baseline(
                             api_key,
                             "firmware/_quota",  # Virtual model for credential-level tracking
-                            quota_reset_ts=reset_ts,
+                            quota_max_requests=credits_as_cents,
+                            quota_used=0,
+                            quota_reset_ts=None,
+                            force=True,
                         )
 
                         lib_logger.debug(
                             f"Updated Firmware.ai quota baseline: "
-                            f"{remaining_fraction * 100:.1f}% remaining, "
-                            f"active_window={usage_data.get('has_active_window', False)}"
+                            f"{credits_balance:.2f} credits remaining"
                         )
 
                 except Exception as e:
@@ -220,3 +227,6 @@ async def refresh_single_credential(
                 refresh_single_credential(api_key, client) for api_key in credentials
             ]
             await asyncio.gather(*tasks, return_exceptions=True)
+
+
+

src/rotator_library/providers/utilities/firmware_quota_tracker.py

@@ -2,14 +2,13 @@
 Firmware.ai Quota Tracking Mixin
 
 Provides quota tracking for the Firmware.ai provider using their quota usage API.
-Firmware.ai uses a 5-hour rolling window quota system where:
-- `used` is already a ratio (0 to 1) indicating quota utilization
-- `reset` is an ISO 8601 UTC timestamp, or null when no active window
+Firmware.ai uses a credit-based quota system where:
+- `credits` is the remaining credit balance (absolute value, e.g. 31.95)
 
 API Details:
 - Endpoint: GET https://app.firmware.ai/api/v1/quota
 - Auth: Authorization: Bearer <api_key>
-- Response: { used: float, reset: string|null }
+- Response: { credits: float }
 
 Required from provider:
     - self.api_base: str (API base URL)
@@ -33,9 +32,8 @@ class FirmwareQuotaTracker:
     Mixin class providing quota tracking functionality for Firmware.ai provider.
 
     This mixin adds the following capabilities:
-    - Fetch quota usage from the Firmware.ai API
-    - Track 5-hour rolling window quota limits
-    - Parse ISO 8601 reset timestamps
+    - Fetch credit balance from the Firmware.ai API
+    - Track remaining credits
 
     Usage:
         class FirmwareProvider(FirmwareQuotaTracker, ProviderInterface):
@@ -76,10 +74,10 @@ async def fetch_quota_usage(
             {
                 "status": "success" | "error",
                 "error": str | None,
-                "used": float,  # 0.0 to 1.0 (from API directly)
-                "remaining_fraction": float,  # 1.0 - used
-                "reset_at": float | None,  # Unix timestamp (seconds)
-                "has_active_window": bool,  # True if reset is not null
+                "credits": float,  # Remaining credit balance
+                "remaining_fraction": float,  # 1.0 if credits > 0, else 0.0
+                "reset_at": float | None,  # Always None (no rolling window)
+                "has_active_window": bool,  # Always False (credit-based)
                 "fetched_at": float,
             }
         """
@@ -103,35 +101,30 @@ async def fetch_quota_usage(
             response.raise_for_status()
             data = response.json()
 
-            # Parse response - API returns ratio directly
-            used_raw = data.get("used")
-            # Validate used is numeric
-            if not isinstance(used_raw, (int, float)):
+            # Parse response - API returns absolute credit balance
+            credits_raw = data.get("credits")
+            # Validate credits is numeric
+            if not isinstance(credits_raw, (int, float)):
                 lib_logger.warning(
-                    f"Firmware.ai quota API returned non-numeric 'used' value: {used_raw}"
+                    f"Firmware.ai quota API returned non-numeric 'credits' value: {credits_raw}"
                 )
-                used = 0.0
+                credits_balance = 0.0
             else:
-                used = float(used_raw)
-            reset_iso = data.get("reset")
+                credits_balance = float(credits_raw)
 
-            # Calculate remaining (inverse of used), clamped to 0.0-1.0
-            remaining_fraction = max(0.0, min(1.0, 1.0 - used))
+            # Credit-based system: available if credits > 0
+            # remaining_fraction is 1.0 if credits available, 0.0 if exhausted
+            remaining_fraction = 1.0 if credits_balance > 0.0 else 0.0
 
-            # Parse ISO 8601 reset timestamp
-            reset_at = None
-            if reset_iso is not None:
-                reset_at = self._parse_iso_timestamp(reset_iso)
-            # Only mark active window if we successfully parsed the timestamp
-            has_active_window = reset_at is not None
+            # Parse optional reset/reload date (ISO 8601 string)
+            reset_date = data.get("reset")  # e.g., "2023-04-01T00:00:00.000Z"
 
             return {
                 "status": "success",
                 "error": None,
-                "used": used,
+                "credits": credits_balance,
                 "remaining_fraction": remaining_fraction,
-                "reset_at": reset_at,
-                "has_active_window": has_active_window,
+                "reset_date": reset_date,  # ISO 8601 string or None
                 "fetched_at": time.time(),
             }
 
@@ -193,10 +186,22 @@ def get_remaining_fraction(self, usage_data: Dict[str, Any]) -> float:
             usage_data: Response from fetch_quota_usage()
 
         Returns:
-            Remaining fraction (0.0 to 1.0)
+            Remaining fraction (0.0 or 1.0 for credit-based system)
         """
         return usage_data.get("remaining_fraction", 0.0)
 
+    def get_credits_balance(self, usage_data: Dict[str, Any]) -> float:
+        """
+        Get the remaining credit balance from usage data.
+
+        Args:
+            usage_data: Response from fetch_quota_usage()
+
+        Returns:
+            Remaining credits (absolute value)
+        """
+        return usage_data.get("credits", 0.0)
+
     def get_reset_timestamp(self, usage_data: Dict[str, Any]) -> Optional[float]:
         """
         Get the next reset timestamp from usage data.
@@ -235,8 +240,7 @@ async def refresh_quota_usage(
 
             lib_logger.debug(
                 f"Firmware.ai quota for {credential_identifier}: "
-                f"{usage_data['remaining_fraction'] * 100:.1f}% remaining, "
-                f"active_window={usage_data['has_active_window']}"
+                f"{usage_data.get('credits', 0.0):.2f} credits remaining"
             )
 
         return usage_data