feat(provider): add cost controls and fallback #428

2026-02-25T03:29:39Z

freemo commented

2026-02-25 03:29:39 +00:00

Summary

Add token/cost tracking, budget enforcement (per-plan and per-day), provider fallback selection with capability filtering, and cost metadata for plan models. This implements cost controls so that AI spending can be monitored and capped, and provider fallback ensures service continuity when a provider is unavailable or over budget.

Changes

New modules:
- providers/cost_table.py: CostEntry + ProviderCostTable with default pricing for OpenAI, Anthropic, Google, Groq, Together, Cohere, and Mock providers.
- providers/cost_tracker.py: BudgetStatus enum, BudgetCheckResult, and CostTracker with warn-at-90%/block-at-100% enforcement.
- providers/fallback_selector.py: FallbackSelector with capability filtering (tool_calls, streaming, vision, json_mode) and budget awareness.
- domain/models/core/cost_metadata.py: CostMetadata + BudgetExhaustionEvent for plan-level audit trail.
Modified:
- config/settings.py: Added budget_per_plan, budget_per_day, and fallback_providers config keys.
- domain/models/core/plan.py: Added cost_metadata field and CLI display dict surfacing.
- providers/__init__.py: Public exports for all new classes.
Documentation: Added docs/reference/cost_controls.md with config keys, thresholds, and fallback order.
Testing:
- 71 Behave scenarios in features/cost_controls.feature (all passing).
- 6 Robot Framework integration tests in robot/cost_controls.robot.
- ASV benchmarks in benchmarks/cost_controls_bench.py.
Vulture whitelist: Updated vulture_whitelist.py with new public API symbols.

Closes #324

## Summary Add token/cost tracking, budget enforcement (per-plan and per-day), provider fallback selection with capability filtering, and cost metadata for plan models. This implements cost controls so that AI spending can be monitored and capped, and provider fallback ensures service continuity when a provider is unavailable or over budget. ### Changes - **New modules:** - `providers/cost_table.py`: `CostEntry` + `ProviderCostTable` with default pricing for OpenAI, Anthropic, Google, Groq, Together, Cohere, and Mock providers. - `providers/cost_tracker.py`: `BudgetStatus` enum, `BudgetCheckResult`, and `CostTracker` with warn-at-90%/block-at-100% enforcement. - `providers/fallback_selector.py`: `FallbackSelector` with capability filtering (tool_calls, streaming, vision, json_mode) and budget awareness. - `domain/models/core/cost_metadata.py`: `CostMetadata` + `BudgetExhaustionEvent` for plan-level audit trail. - **Modified:** - `config/settings.py`: Added `budget_per_plan`, `budget_per_day`, and `fallback_providers` config keys. - `domain/models/core/plan.py`: Added `cost_metadata` field and CLI display dict surfacing. - `providers/__init__.py`: Public exports for all new classes. - **Documentation:** Added `docs/reference/cost_controls.md` with config keys, thresholds, and fallback order. - **Testing:** - 71 Behave scenarios in `features/cost_controls.feature` (all passing). - 6 Robot Framework integration tests in `robot/cost_controls.robot`. - ASV benchmarks in `benchmarks/cost_controls_bench.py`. - **Vulture whitelist:** Updated `vulture_whitelist.py` with new public API symbols. Closes #324

freemo added this to the v3.0.0 milestone 2026-02-25 03:30:01 +00:00

freemo added the

Type

Feature

label 2026-02-25 03:30:19 +00:00

freemo force-pushed feature/m4-provider-costs from 53e3fa90a1 to 4f8b7c92d4

2026-02-25 16:39:38 +00:00

Compare

freemo scheduled this pull request to auto merge when all checks succeed 2026-02-25 16:42:20 +00:00

freemo canceled auto merging this pull request when all checks succeed 2026-02-25 16:58:46 +00:00

freemo added a new dependency 2026-02-25 17:05:41 +00:00

#324 feat(provider): add cost controls and fallback