Nous.Session.Guardrails (nous v0.13.3)
View SourceSession limit checking and guardrail functions.
Works with Nous.Session.Config to enforce turn limits,
token budgets, and compaction triggers.
Example: GenServer integration
defmodule MySession do
use GenServer
def handle_call({:send, message}, _from, state) do
case Guardrails.check_limits(state.config, state.turns, state.in_tokens, state.out_tokens) do
:ok ->
# proceed with agent call
...
{:error, reason} ->
{:reply, {:error, reason}, state}
end
end
endSummary
Functions
Checks whether a session has exceeded its configured limits.
Returns remaining budget as {remaining_turns, remaining_tokens}.
Checks if the session should trigger compaction.
Returns a summary map of the session's current state against its limits.
Functions
@spec check_limits( Nous.Session.Config.t(), non_neg_integer(), non_neg_integer(), non_neg_integer() ) :: :ok | {:error, :max_turns_reached | :max_budget_reached}
Checks whether a session has exceeded its configured limits.
Returns :ok if within limits, or {:error, reason} if a limit is hit.
Examples
iex> config = %Nous.Session.Config{max_turns: 10, max_budget_tokens: 100_000}
iex> Nous.Session.Guardrails.check_limits(config, 5, 1000, 2000)
:ok
iex> config = %Nous.Session.Config{max_turns: 10, max_budget_tokens: 100_000}
iex> Nous.Session.Guardrails.check_limits(config, 10, 1000, 2000)
{:error, :max_turns_reached}@spec remaining( Nous.Session.Config.t(), non_neg_integer(), non_neg_integer(), non_neg_integer() ) :: {non_neg_integer(), non_neg_integer()}
Returns remaining budget as {remaining_turns, remaining_tokens}.
Examples
iex> config = %Nous.Session.Config{max_turns: 10, max_budget_tokens: 100_000}
iex> Nous.Session.Guardrails.remaining(config, 3, 5000, 10000)
{7, 85000}@spec should_compact?(Nous.Session.Config.t(), non_neg_integer()) :: boolean()
Checks if the session should trigger compaction.
Examples
iex> config = %Nous.Session.Config{compact_after_turns: 20}
iex> Nous.Session.Guardrails.should_compact?(config, 25)
true
iex> config = %Nous.Session.Config{compact_after_turns: 20}
iex> Nous.Session.Guardrails.should_compact?(config, 15)
false@spec summary( Nous.Session.Config.t(), non_neg_integer(), non_neg_integer(), non_neg_integer() ) :: map()
Returns a summary map of the session's current state against its limits.
Useful for logging or exposing session health to users.
Examples
Nous.Session.Guardrails.summary(config, 5, 10_000, 20_000)
#=> %{
#=> turns: %{current: 5, max: 10, remaining: 5},
#=> tokens: %{used: 30_000, max: 200_000, remaining: 170_000},
#=> needs_compaction: false
#=> }