Cost & budget

LogicGrid calculates a USD cost estimate for every LLM call and accumulates it across an entire run. You can read the total off the trace, alert on a threshold via BudgetWarningEvent, or hard-stop the run with MaxBudgetUsd.

How cost is computed

Each LlmClient knows the rate card for its provider (see PricingTable). After every LLM response, the framework multiplies prompt-token and completion-token counts by the per-token rates and emits a CostEstimate:

public sealed class CostEstimate
{
    public decimal InputCostUsd  { get; }
    public decimal OutputCostUsd { get; }
    public decimal TotalCostUsd => InputCostUsd + OutputCostUsd;
    public string  Currency => "USD";
    public static CostEstimate Zero { get; }
    public static CostEstimate operator +(CostEstimate a, CostEstimate b);
}

Ollama and other unpriced/local providers return CostEstimate.Zero — the field is always present, you just see $0.0000.

Reading total cost from the trace

var ctx = new AgentContext().WithTracing(out var trace);
await admin.RunAsync(input);

Console.WriteLine($"Cost: ${trace.TotalCost.TotalCostUsd:0.0000}");
Console.WriteLine($"  in:  ${trace.TotalCost.InputCostUsd:0.0000}");
Console.WriteLine($"  out: ${trace.TotalCost.OutputCostUsd:0.0000}");

Capping spend with MaxBudgetUsd

Set the cap on the admin's AdminOptions. The admin checks spend after every agent completes and stops the run with BudgetExceededException once it crosses the limit.

var admin = new GroupChatAdmin<string, string>(
    "Editorial", llm, agents,
    options: new AdminOptions
    {
        MaxBudgetUsd = 0.50m,                  // hard cap
        BudgetWarningThreshold = 0.75f,        // warn at 75 %
    });

try
{
    var output = await admin.RunAsync("…");
}
catch (BudgetExceededException ex)
{
    Console.WriteLine($"Run stopped: {ex.Message}");
}

ReflexionAdmin carries the same fields on its ReflexionOptions.

Budget events

BudgetWarningEvent and BudgetExceededEvent fire on the bus before the exception is thrown. Subscribe to them for alerting:

ctx.EventBus!.Subscribe<BudgetWarningEvent>(e =>
    myAlerts.Notify($"run {e.RunId} at {e.PercentUsed:P0} of budget"));

ctx.EventBus!.Subscribe<BudgetExceededEvent>(e =>
    myAlerts.Page($"run {e.RunId} exceeded ${e.LimitUsd:F2}"));

Both events are also captured on the trace under trace.BudgetEvents.

When the cost is $0.0000

Three reasons:

1. You're running Ollama / a local provider. No rate card, no cost. This is by design.
2. The provider is OpenAiCompatibleClient pointing at vLLM / TEI / your own host. Rate is unknown to LogicGrid.
3. Token usage was zero because the call failed before the LLM responded.

If you want to track real cost for a self-hosted provider that bills internally, supply your own pricing — wrap the client and override the cost calculation, or compute it externally from the TokenUsage on each LlmCallCompletedEvent.

Common pitfalls

• Budget cap on a chatty group chat with no DONE clause. The loop runs to MaxLoops every time, hitting the budget before finishing. Make termination explicit in the agents' system prompts.
• Underestimating MaxBudgetUsd. A reflexion loop with a slow critic can use 5x the tokens of a single-shot pipeline. Run a few representative requests with tracing on, look at trace.TotalCost, then set the cap a comfortable margin above the observed worst case.
• Catching BudgetExceededException and retrying. Don't — you just spend the budget twice. Treat the exception as a failed run and surface it.

See also

• Tracing — full trace shape including BudgetEvents.
• Events — BudgetWarningEvent, BudgetExceededEvent payloads.
• Admins — AdminOptions reference.