The limits of an AI task: how much the task may use, and how much each user may use in it, in a calendar day and month of the site time zone.

Scopes, units, periods

Units: :money (US dollars, a Decimal; stored as a decimal string, read through PhoenixKitAI.Money), :requests, :tokens. Periods: :day, :month — the calendar day and month of the site time zone (Settings → time_zone, PhoenixKit.Utils.TimeZone), each from its local midnight to the next.

A limit is an amount per (unit, period). An empty cell inherits the next layer's default; with no default there is no limit. 0 allows nothing.

Which limit is in force

Cell by cell (unit and period), the first that is set:

• :user — the user's personal exception (phoenix_kit_ai_task_user_limits), then the task's default for its users (limits["user"] of phoenix_kit_ai_task_settings), then the declaration's default_limits.user;
• :task — the task's own (limits["task"]), then the declaration's default_limits.task.

A task declared with user_limits: false (its module limits its users itself) has no :user scope here: the declaration's and the stored user values are ignored (and kept), and setting a user limit or forgiving one is {:error, :user_limits_off}.

What is counted

The task's rows of the journal (phoenix_kit_ai_requests, metadata->>'task'), successful ones only (status = 'success'): a failed call costs nothing and a refusal is an error row, so neither counts. Money is the cost sum (dollars), tokens the total_tokens sum, requests the rows — so a cached answer (a zero-cost success row) counts as one request and no money or tokens. Money is what a row's cost says (PhoenixKitAI.CallCost: the provider's own cost, else a catalogue, the endpoint's manual or the built-in Anthropic price, metadata.cost_source; the vision verbs are priced like chat, making or editing images only by the provider's own cost): an endpoint none of them prices (money_counted?/2) adds nothing to it, and there requests and tokens are what limits a task.

The check

check/3 runs before every provider call that names a declared task (after the model check, before PhoenixKitAI.Budget). A limit whose count has reached it refuses the call with {:error, {:task_limit_exceeded, scope, unit, period}} until its window ends or the limit is raised; the refusal is a journal row like every guard refusal. There is no reservation: calls running at the same time can each go past a limit by their own size.

At the warn percent (the task's warn_percent, default 80) a user's limit tells the user and the task's limit tells the watchers (PhoenixKitAI.GuardEvents); a reached limit tells both. Each once per window.

Forgiving

forgive/6 restarts the count of one scope and period from that moment to the end of the window; the limit itself stays. The moment is kept only as the limit_forgiven event.

Every function here that changes something takes the scope of the person doing it and needs ai.manage (PhoenixKitAI.Guard.may_manage?/1); the change goes to the Activity log.

The check fails open: a database error reads as nothing used.

The cache

A call reads a task's settings row and personal limits from a per-node cache (the request cache's flags table), loaded on the first call of the task: a task without limits costs no query. Every change through this module drops the task's entry here and broadcasts {:task_limits_changed, task_key} on topic/0, which PhoenixKitAI.GuardWatch turns into the same drop on every node; a restarted watch drops the whole cache, since it may have missed a broadcast. An entry is also read again after 60 seconds, which bounds what a lost broadcast can leave behind. A change made inside the caller's own Repo.transaction drops the cache before that transaction commits, so a call in between may cache the old values again; the 60 seconds bound that too. The usage and forgiving are always read from the database, and only when a limit is in force.