Class: OllamaAgent::Core::Budget

Inherits:
Object
  • Object
show all
Defined in:
lib/ollama_agent/core/budget.rb

Overview

Tracks and enforces token, step, and cost budgets for an agent run. Instantiate once per run; call #record_step! after each model round-trip.

Constant Summary collapse

DEFAULT_MAX_STEPS = 
64
DEFAULT_MAX_TOKENS = 
32_768
DEFAULT_MAX_COST_USD = 
nil

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(max_steps: nil, max_tokens: nil, max_cost_usd: nil) ⇒ Budget

Returns a new instance of Budget.



15
16
17
18
19
20
21
 
# File 'lib/ollama_agent/core/budget.rb', line 15

def initialize(max_steps: nil, max_tokens: nil, max_cost_usd: nil)
  @max_steps    = max_steps    || env_int("OLLAMA_AGENT_MAX_TURNS", DEFAULT_MAX_STEPS)
  @max_tokens   = max_tokens   || env_int("OLLAMA_AGENT_MAX_TOKENS", DEFAULT_MAX_TOKENS)
  @max_cost_usd = max_cost_usd || env_float("OLLAMA_AGENT_MAX_COST_USD", DEFAULT_MAX_COST_USD)

  reset!
end

Instance Attribute Details

#cost_usd ⇒ Object (readonly)

Returns the value of attribute cost_usd.



12
13
14
 
# File 'lib/ollama_agent/core/budget.rb', line 12

def cost_usd
  @cost_usd
end

#max_cost_usd ⇒ Object (readonly)

Returns the value of attribute max_cost_usd.



12
13
14
 
# File 'lib/ollama_agent/core/budget.rb', line 12

def max_cost_usd
  @max_cost_usd
end

#max_steps ⇒ Object (readonly)

Returns the value of attribute max_steps.



12
13
14
 
# File 'lib/ollama_agent/core/budget.rb', line 12

def max_steps
  @max_steps
end

#max_tokens ⇒ Object (readonly)

Returns the value of attribute max_tokens.



12
13
14
 
# File 'lib/ollama_agent/core/budget.rb', line 12

def max_tokens
  @max_tokens
end

#steps ⇒ Object (readonly)

Returns the value of attribute steps.



12
13
14
 
# File 'lib/ollama_agent/core/budget.rb', line 12

def steps
  @steps
end

#tokens_used ⇒ Object (readonly)

Returns the value of attribute tokens_used.



12
13
14
 
# File 'lib/ollama_agent/core/budget.rb', line 12

def tokens_used
  @tokens_used
end

Instance Method Details

#cost_exceeded? ⇒ Boolean

Returns:

  • (Boolean) 


35
 
# File 'lib/ollama_agent/core/budget.rb', line 35

def cost_exceeded?    = !@max_cost_usd.nil? && @cost_usd >= @max_cost_usd

#exceeded? ⇒ Boolean

True when any limit has been hit.

Returns:

  • (Boolean) 


38
39
40
 
# File 'lib/ollama_agent/core/budget.rb', line 38

def exceeded?
  steps_exceeded? || tokens_exceeded? || cost_exceeded?
end

#exceeded_reason ⇒ Object

Human-readable reason for the first exceeded limit, or nil if none.



43
44
45
46
47
48
49
 
# File 'lib/ollama_agent/core/budget.rb', line 43

def exceeded_reason
  return "step limit (#{@max_steps})" if steps_exceeded?
  return "token limit (#{@max_tokens})"       if tokens_exceeded?
  return "cost limit ($#{@max_cost_usd})"     if cost_exceeded?

  nil
end

#record_step!(tokens: 0, cost_usd: 0.0) ⇒ Object

Record one agent step. Call after each model response.

Parameters:

  • tokens (Integer) (defaults to: 0) —

    tokens consumed in this step (prompt + completion)

  • cost_usd (Float) (defaults to: 0.0) —

    estimated cost in USD (0.0 for local models)



26
27
28
29
30
31
 
# File 'lib/ollama_agent/core/budget.rb', line 26

def record_step!(tokens: 0, cost_usd: 0.0)
  @steps       += 1
  @tokens_used += tokens.to_i
  @cost_usd    += cost_usd.to_f
  nil
end

#remaining_steps ⇒ Object 



65
66
67
 
# File 'lib/ollama_agent/core/budget.rb', line 65

def remaining_steps
  [@max_steps - @steps, 0].max
end

#reset! ⇒ Object 



51
52
53
54
55
 
# File 'lib/ollama_agent/core/budget.rb', line 51

def reset!
  @steps       = 0
  @tokens_used = 0
  @cost_usd    = 0.0
end

#steps_exceeded? ⇒ Boolean

Returns:

  • (Boolean) 


33
 
# File 'lib/ollama_agent/core/budget.rb', line 33

def steps_exceeded?   = @steps >= @max_steps

#to_h ⇒ Object 



57
58
59
60
61
62
63
 
# File 'lib/ollama_agent/core/budget.rb', line 57

def to_h
  {
    steps: @steps, max_steps: @max_steps,
    tokens_used: @tokens_used, max_tokens: @max_tokens,
    cost_usd: @cost_usd, max_cost_usd: @max_cost_usd
  }
end

#tokens_exceeded? ⇒ Boolean

Returns:

  • (Boolean) 


34
 
# File 'lib/ollama_agent/core/budget.rb', line 34

def tokens_exceeded?  = @tokens_used >= @max_tokens