Documentation: Misleading docstring in CostTracker class about budget blocking #10554

New issue

Open

opened 2026-04-18 17:12:44 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-18 17:12:44 +00:00

Owner

Metadata

Commit: Current HEAD
Branch: main

Background and Context

The CostTracker class in src/cleveragents/providers/cost_tracker.py has misleading docstrings that suggest the class itself enforces budget blocking. However, the actual implementation only returns budget status information and delegates the responsibility of blocking requests to the caller.

The class docstring states:

"""Track costs and enforce budget limits for provider usage.

Manages per-plan and per-day budget tracking with configurable
warning and blocking thresholds. Uses dependency injection for
the cost table.

And the module docstring says:

"""Cost tracking and budget enforcement for provider usage.

Tracks token consumption and monetary costs per plan execution,
enforces budget limits, and emits warnings/blocks when thresholds
are approached or exceeded.

Expected Behavior

The docstrings should clearly state that:

CostTracker tracks costs and returns budget status information
The caller is responsible for enforcing blocking based on the returned BudgetCheckResult
The class does not itself block or raise exceptions when budgets are exceeded

Actual Behavior

The docstrings imply that CostTracker enforces blocking, which is misleading. The record_usage() method returns a BudgetCheckResult with status=BudgetStatus.EXCEEDED, but the caller must handle the blocking logic.

Acceptance Criteria

Class docstring in CostTracker is updated to clarify that it returns budget status information
Module docstring is updated to clarify that the caller is responsible for enforcement
The distinction between tracking and enforcement is clearly documented
All references to "blocking" in the docstrings are clarified to indicate this is the caller's responsibility

Subtasks

Update CostTracker class docstring to remove misleading "enforce" language
Update module docstring to clarify caller responsibility for blocking
Add clarifying comments to record_usage() method about return value usage
Review and update any related documentation or examples

Definition of Done

This issue is complete when:

The docstrings accurately reflect the actual behavior of the CostTracker class
It is clear that CostTracker returns status information rather than enforcing blocking
The responsibility for blocking is explicitly stated to be the caller's
Documentation changes are reviewed and approved

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit:** Current HEAD - **Branch:** main ## Background and Context The `CostTracker` class in `src/cleveragents/providers/cost_tracker.py` has misleading docstrings that suggest the class itself enforces budget blocking. However, the actual implementation only returns budget status information and delegates the responsibility of blocking requests to the caller. The class docstring states: ```python """Track costs and enforce budget limits for provider usage. Manages per-plan and per-day budget tracking with configurable warning and blocking thresholds. Uses dependency injection for the cost table. ``` And the module docstring says: ```python """Cost tracking and budget enforcement for provider usage. Tracks token consumption and monetary costs per plan execution, enforces budget limits, and emits warnings/blocks when thresholds are approached or exceeded. ``` ## Expected Behavior The docstrings should clearly state that: - `CostTracker` tracks costs and returns budget status information - The caller is responsible for enforcing blocking based on the returned `BudgetCheckResult` - The class does not itself block or raise exceptions when budgets are exceeded ## Actual Behavior The docstrings imply that `CostTracker` enforces blocking, which is misleading. The `record_usage()` method returns a `BudgetCheckResult` with `status=BudgetStatus.EXCEEDED`, but the caller must handle the blocking logic. ## Acceptance Criteria - [ ] Class docstring in `CostTracker` is updated to clarify that it returns budget status information - [ ] Module docstring is updated to clarify that the caller is responsible for enforcement - [ ] The distinction between tracking and enforcement is clearly documented - [ ] All references to "blocking" in the docstrings are clarified to indicate this is the caller's responsibility ## Subtasks - [ ] Update `CostTracker` class docstring to remove misleading "enforce" language - [ ] Update module docstring to clarify caller responsibility for blocking - [ ] Add clarifying comments to `record_usage()` method about return value usage - [ ] Review and update any related documentation or examples ## Definition of Done This issue is complete when: 1. The docstrings accurately reflect the actual behavior of the `CostTracker` class 2. It is clear that `CostTracker` returns status information rather than enforcing blocking 3. The responsibility for blocking is explicitly stated to be the caller's 4. Documentation changes are reviewed and approved --- **Automated by CleverAgents Bot** Agent: new-issue-creator

HAL9000 added the

labels

2026-04-18 17:13:31 +00:00