How OpenMontage Budget Governance Works: Observe, Warn, and Cap Modes Explained

OpenMontage controls AI pipeline spending through the CostTracker class in tools/cost_tracker.py, which enforces one of three governance modes—Observe, Warn, or Cap—to either monitor costs passively, flag budget overruns with warnings, or raise exceptions that halt execution when limits are exceeded.

OpenMontage implements a sophisticated budget governance system that governs every paid operation across its video generation pipeline. At the core of this system lies the CostTracker class, which coordinates with the orchestrator to estimate, reserve, and reconcile costs according to a configurable BudgetMode defined in lib/config_model.py. Understanding how these modes interact with the usable budget calculation is essential for managing operational expenses in both experimental and production deployments.

Core Architecture of the Budget Governance System

The CostTracker Class

The CostTracker class serves as the central authority for all financial operations within OpenMontage. When a pipeline executes, every paid operation first produces an estimate, then the orchestrator reserves that amount before running the tool. This two-phase commit pattern ensures that the system can verify budget availability before incurring actual costs.

The class tracks both estimated and actual spending through methods like estimate() (which creates entries), reserve() (which commits budget), and reconcile() (which records final costs). According to the source code in tools/cost_tracker.py, the constructor defaults to BudgetMode.WARN when no mode is explicitly specified (lines 44-50).

BudgetMode Enumeration

The governance behavior depends entirely on which BudgetMode the CostTracker is instantiated with:

• BudgetMode.OBSERVE – Monitoring only, zero enforcement
• BudgetMode.WARN – Soft enforcement with visible alerts
• BudgetMode.CAP – Hard enforcement that blocks operations

The Three Budget Governance Modes

Observe Mode: Passive Monitoring

In Observe mode, the budget is only monitored with no restrictions or approvals enforced. All estimates are recorded, but the orchestrator never stops a reservation or raises errors regardless of the amount requested.

According to lines 26-33 in tools/cost_tracker.py, the checks for single-action thresholds and new-tool approvals are explicitly bypassed when the mode is OBSERVE. This allows unrestricted experimentation where every cost is logged for later analysis without interrupting the creative workflow.

from lib.config_model import BudgetMode
from tools.cost_tracker import CostTracker

# Observe mode logs everything but never blocks

tracker = CostTracker(budget_total_usd=5.0, mode=BudgetMode.OBSERVE)
entry_id = tracker.estimate("openai_image", "generate", 0.60)
tracker.reserve(entry_id)  # Succeeds even though $0.60 exceeds single-action defaults

Warn Mode: Soft Enforcement with Alerts

Warn mode is the default configuration that allows reservations to proceed but records a budget-warning on the entry when the requested amount exceeds the usable budget. The pipeline continues execution, giving users visible feedback that the budget will be overrun without stopping the operation.

As implemented in lines 42-53 of tools/cost_tracker.py, when estimated_usd exceeds usable_budget_usd, the code sets budget_warning=True and attaches a warning message to the entry. No exception is raised, ensuring that long-running pipelines complete while maintaining an audit trail of budget violations.

# Warn mode flags overruns but continues execution

tracker_warn = CostTracker(budget_total_usd=5.0, mode=BudgetMode.WARN)
entry_id = tracker_warn.estimate("openai_image", "generate", 4.8)
tracker_warn.reserve(entry_id)  # Succeeds with budget_warning=True flag

Cap Mode: Hard Budget Enforcement

Cap mode provides strict financial control by blocking reservations that would exceed the usable budget. When an estimate would overrun the available funds, the system raises a BudgetExceededError, causing the orchestrator to pause or abort the pipeline immediately.

In lines 48-50 of tools/cost_tracker.py, the code explicitly checks if self.mode == BudgetMode.CAP and raises the exception before the reservation is recorded. This prevents any single operation from pushing the total spend beyond the allocated budget, making it ideal for production environments with strict cost controls.

# Cap mode raises exceptions on budget overrun

tracker_cap = CostTracker(budget_total_usd=5.0, mode=BudgetMode.CAP)
entry_id = tracker_cap.estimate("openai_image", "generate", 4.8)

try:
    tracker_cap.reserve(entry_id)  # Raises BudgetExceededError

except Exception as e:
    print("Budget cap enforced:", e)

Budget Calculation and Approval Checks

Calculating Usable Budget

The usable budget is not simply the total budget minus spent funds. OpenMontage implements a reserve mechanism that holds back a percentage of the total budget to prevent race conditions in multi-operation pipelines.

According to lines 86-90 in tools/cost_tracker.py, the usable_budget_usd property calculates the available funds by subtracting both actual spent amounts and reserved amounts from the total, while maintaining a reserve_pct hold-back (defaulting to 10%). This ensures that parallel operations do not collectively exceed the budget cap.

Single-Action and New-Tool Approvals

Before accepting a reservation in Warn or Cap modes, the system performs two additional safety checks that may raise ApprovalRequiredError:

1. Single-action threshold – Any estimate larger than single_action_approval_usd (default $0.50) triggers an approval requirement (lines 26-33). This prevents accidentally expensive operations from running without explicit consent.

2. New paid-tool approval – The first paid use of any tool that has not been previously approved also raises an error (lines 34-41). This ensures that novel AI services are explicitly vetted before incurring charges.

Both checks are completely bypassed in Observe mode, allowing rapid prototyping without administrative overhead.

Reservation Flow in Practice

The complete budget governance flow follows these stages:

1. Estimate – The estimate() method creates an entry tracking the tool name, operation, and projected cost.

2. Reserve – The reserve() method checks thresholds (unless in Observe mode), verifies tool approvals, and compares estimated_usd against usable_budget_usd:

   • OBSERVE – Skips all checks; reservation always succeeds
   • WARN – Reservation succeeds; adds warning flag if over budget
   • CAP – Raises BudgetExceededError if over budget

3. Execution – The tool runs only if reservation succeeded.

4. Reconcile – The reconcile() method records actual costs, updating spent totals versus reserved amounts to free up unused budget allocations.

Summary

• OpenMontage budget governance centers on the CostTracker class in tools/cost_tracker.py, which manages the financial lifecycle of AI operations through estimate, reserve, and reconcile phases.
• Observe mode provides passive monitoring where all checks are bypassed (lines 26-33), enabling unrestricted experimentation without spending caps.
• Warn mode (the default) allows over-budget operations to proceed while flagging entries with budget_warning=True (lines 42-53), ensuring visibility without disrupting creative workflows.
• Cap mode enforces hard budget limits by raising BudgetExceededError (lines 48-50) when reservations would exceed the usable budget calculated with a 10% reserve hold-back.
• Additional safety mechanisms include single-action thresholds ($0.50 default) and new-tool approval requirements that operate in Warn and Cap modes but are disabled in Observe mode.

Frequently Asked Questions

What is the default budget mode in OpenMontage?

The default mode is Warn (BudgetMode.WARN). According to lines 44-50 in tools/cost_tracker.py, the CostTracker constructor sets mode: BudgetMode = BudgetMode.WARN, meaning the system will allow operations to proceed but flag overruns with warnings unless explicitly configured otherwise.

How does the usable budget differ from the total budget?

The usable budget is calculated by subtracting both spent funds and reserved amounts from the total budget, then applying a 10% reserve hold-back (reserve_pct). As implemented in the usable_budget_usd property (lines 86-90 of tools/cost_tracker.py), this prevents parallel operations from collectively exceeding the budget by maintaining a safety buffer.

When does OpenMontage require manual approval for tool usage?

Manual approval through ApprovalRequiredError is required in Warn and Cap modes when either: (1) a single operation exceeds the single_action_approval_usd threshold (default $0.50), or (2) a paid tool is used for the first time without prior approval. These checks are located in lines 26-41 of tools/cost_tracker.py and are completely bypassed in Observe mode.

Can I switch budget modes during pipeline execution?

No, the budget mode is immutable for the lifecycle of a CostTracker instance. The mode is set at initialization in the constructor (lines 44-50) and governs all subsequent reserve() calls. To change governance behavior mid-pipeline, you must instantiate a new CostTracker with the desired BudgetMode and transfer state if necessary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}