feat(quota): Add Firmware.ai quota tracking with 5-hour rolling window #92

b3nw · 2026-01-21T01:10:45Z

Summary

Add FirmwareProvider with periodic quota refresh
Add FirmwareQuotaTracker mixin for fetching quota usage from /api/v1/quota endpoint
Track credential-level quota using virtual model firmware/_quota for quota group aggregation
Display quota percentage in TUI when max_requests is unavailable (Firmware doesn't expose this)

How it works

Firmware.ai uses a 5-hour rolling window quota system:

GET /api/v1/quota returns { used: float, reset: string|null }
used is already a 0-1 ratio (e.g., 0.026 = 2.6% used)
reset is an ISO 8601 timestamp when quota resets, or null when no active window

Important

Adds Firmware.ai quota tracking with a 5-hour rolling window using a new provider class and mixin, updating usage management and client display.

Behavior:
- Adds FirmwareProvider class in firmware_provider.py for handling Firmware.ai API with 5-hour rolling window quota tracking.
- Implements FirmwareQuotaTracker mixin in firmware_quota_tracker.py for fetching and parsing quota usage.
- Updates get_quota_stats() in client.py to display quota percentage when max_requests is unavailable.
Quota Tracking:
- FirmwareProvider uses a virtual model _quota for credential-level tracking.
- fetch_quota_usage() in FirmwareQuotaTracker fetches quota data and calculates remaining fraction.
- Handles null reset timestamps and parses ISO 8601 timestamps.
Usage Management:
- Modifies UsageManager in usage_manager.py to support Firmware.ai's rolling window and handle null reset timestamps.
- Adds environment variable FIRMWARE_QUOTA_REFRESH_INTERVAL for refresh interval configuration.

^{This description was created by}^{for 9d5165b. You can customize this summary. It will automatically update as commits are pushed.}

mirrobot-agent · 2026-01-21T01:11:28Z

I'm starting my review of the Firmware.ai quota tracking implementation. It's great to see the 5-hour rolling window being addressed! I'll dive into the details now.

mirrobot-agent

Overall Assessment

The implementation of Firmware.ai quota tracking is solid and integrates well with the existing provider architecture. The handling of the 5-hour rolling window is a great addition, and the fallback logic for providers that only expose utilization percentages (rather than absolute request counts) is a significant improvement for the TUI display.

Architectural Feedback

Virtual Model Tracking: Using _quota (or firmware/_quota) for credential-level tracking is a consistent and effective way to handle providers that don't expose per-model quotas.
Usage Manager Integration: The fallback logic in UsageManager to extract provider info from model names is a clever solution for handling raw API keys.

Key Suggestions

Consistency in Model Naming: Standardize on either _quota or firmware/_quota throughout FirmwareProvider to avoid potential mismatches in the usage manager.
Refined Error Logging: Consider providing slightly more detail in the error logs where it is safe to do so, to aid in troubleshooting API issues.
Parallel Fetching: The use of a semaphore to limit concurrency in run_background_job is excellent.

Questions for the Author

None at this time. The plan and implementation are very clear.

This review was generated by an AI assistant.

src/rotator_library/providers/firmware_provider.py

mirrobot-agent · 2026-01-21T01:13:04Z

src/rotator_library/providers/utilities/firmware_quota_tracker.py

+            }
+        except Exception as e:
+            # Log exception type only - message may contain sensitive data
+            lib_logger.warning(f"Failed to fetch Firmware.ai quota: {type(e).__name__}")


While logging only the exception type is good for security (avoiding leaking API keys or sensitive data), it might make debugging harder. Since the URL doesn't contain the API key in this case, consider if logging a truncated or sanitized version of the error message would be helpful.

mirrobot-agent · 2026-01-21T01:13:04Z

src/rotator_library/providers/utilities/firmware_quota_tracker.py

+        try:
+            # Handle 'Z' suffix by replacing with UTC offset
+            if iso_string.endswith("Z"):
+                iso_string = iso_string.replace("Z", "+00:00")


In Python 3.11+, datetime.fromisoformat() supports the Z suffix directly. If the project targets Python 3.11 or newer, you can simplify this. Otherwise, this manual replacement is a safe fallback for older versions.

b3nw · 2026-01-21T02:07:23Z

@mirrobot-agent re-review

mirrobot-agent · 2026-01-21T02:07:59Z

@b3nw, I'm starting my re-review of the Firmware.ai quota tracking implementation. I'll check the latest changes and see if my previous suggestions were addressed.

mirrobot-agent

Overall Assessment

The standardization on firmware/_quota for virtual model tracking is a great improvement and addresses my previous feedback perfectly. This ensures consistent provider resolution in the UsageManager. The integration with the 5-hour rolling window and the TUI display logic remains solid.

Architectural Feedback

Consistent Model Naming: Using the provider/model pattern for virtual models like firmware/_quota is an excellent practice that simplifies provider identification across the library.
TUI Display Fallback: The logic to use avg_remaining_pct when absolute request counts are unavailable is a clean solution for providers like Firmware.

Key Suggestions

Docstring Consistency: A minor nit regarding the docstring in FirmwareProvider to match the updated model name.

Questions for the Author

None. The implementation is clear and well-structured.

This review was generated by an AI assistant.

src/rotator_library/providers/firmware_provider.py

Mirrowel · 2026-01-21T11:26:04Z

@b3nw Resolve merge conflicts here so it can be merged

Mirrowel · 2026-01-21T14:40:03Z

/mirrobot-review

mirrobot-agent

Follow-up Review

This update successfully implements Firmware.ai quota tracking and integrates it into the wider library ecosystem. The implementation is robust and addresses previous feedback regarding model naming consistency and secure error logging.

Assessment of New Changes:

Firmware Provider: The new provider and its associated mixin correctly handle the 5-hour rolling window quota system. The use of firmware/_quota for credential-level tracking is consistent and well-implemented.
Improved Display Logic: The updates in RotatingClient to fallback to avg_remaining_pct and handle percentage-based displays are a significant improvement for the TUI, especially for providers like Firmware that don't expose absolute request limits.
Usage Manager: The new fallback logic to extract provider info from model names (e.g., firmware/model) is a clever and necessary addition for supporting providers with virtual models.
Security: The error handling in fetch_quota_usage has been refined to avoid logging sensitive data, which is an excellent practice.

Overall Status:
The changes are high-quality, idiomatic, and ready to be merged.

This review was generated by an AI assistant.

src/rotator_library/providers/firmware_provider.py

Mirrowel

You forgot the AI PLAN.MD file

Implement quota tracking for Firmware.ai provider using their /api/v1/quota endpoint. The provider tracks a 5-hour rolling window quota where `used` is already a 0-1 ratio from the API. - Add FirmwareQuotaTracker mixin with configurable api_base - Add FirmwareProvider with background job for periodic quota refresh - Parse ISO 8601 reset timestamps with proper Z suffix handling - Validate API response types and clamp remaining fraction to 0.0-1.0 - Support FIRMWARE_QUOTA_REFRESH_INTERVAL env var (default: 300s)

b3nw requested a review from Mirrowel as a code owner January 21, 2026 01:10

mirrobot-agent bot reviewed Jan 21, 2026

View reviewed changes

mirrobot-agent bot previously approved these changes Jan 21, 2026

View reviewed changes

src/rotator_library/providers/firmware_provider.py Outdated Show resolved Hide resolved

b3nw dismissed mirrobot-agent[bot]’s stale review via 75873b3 January 21, 2026 14:38

b3nw force-pushed the feature/firmware-quota-tracking branch from bf41d7a to 75873b3 Compare January 21, 2026 14:38

mirrobot-agent bot previously approved these changes Jan 21, 2026

View reviewed changes

src/rotator_library/providers/firmware_provider.py Show resolved Hide resolved

Mirrowel requested changes Jan 21, 2026

View reviewed changes

b3nw dismissed mirrobot-agent[bot]’s stale review via 1005d67 January 21, 2026 15:39

b3nw force-pushed the feature/firmware-quota-tracking branch from 75873b3 to 1005d67 Compare January 21, 2026 15:39

b3nw added 2 commits January 21, 2026 15:58

fix: use consistent firmware/_quota model name in quota groups

6f456da

b3nw force-pushed the feature/firmware-quota-tracking branch from 1005d67 to 6f456da Compare January 21, 2026 15:58

Mirrowel approved these changes Jan 21, 2026

View reviewed changes

Mirrowel merged commit d4c1ac0 into Mirrowel:dev Jan 21, 2026
2 of 3 checks passed

Uh oh!

feat(quota): Add Firmware.ai quota tracking with 5-hour rolling window #92

feat(quota): Add Firmware.ai quota tracking with 5-hour rolling window #92

Conversation

b3nw commented Jan 21, 2026 • edited by ellipsis-dev bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

How it works

Uh oh!

mirrobot-agent bot commented Jan 21, 2026

Uh oh!

mirrobot-agent bot left a comment

Choose a reason for hiding this comment

Overall Assessment

Architectural Feedback

Key Suggestions

Questions for the Author

Uh oh!

Uh oh!

mirrobot-agent bot Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

mirrobot-agent bot Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

b3nw commented Jan 21, 2026

Uh oh!

mirrobot-agent bot commented Jan 21, 2026

Uh oh!

mirrobot-agent bot left a comment

Choose a reason for hiding this comment

Overall Assessment

Architectural Feedback

Key Suggestions

Questions for the Author

Uh oh!

Uh oh!

Mirrowel commented Jan 21, 2026

Uh oh!

Mirrowel commented Jan 21, 2026

Uh oh!

mirrobot-agent bot left a comment

Choose a reason for hiding this comment

Follow-up Review

Uh oh!

Uh oh!

Mirrowel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

b3nw commented Jan 21, 2026 •

edited by ellipsis-dev bot

Loading