3.1.4 AI & Automation — AI Usage & Limits — Tokens and Tracking

AI Usage and Limits define how PraismaGPT consumption is tracked and constrained at tenant, organization, and user level. The goal is to provide predictable usage behavior, prevent abuse, and ensure fair resource allocation while maintaining full visibility for administrators.

Usage Measurement Model

AI usage is measured using normalized units derived from request size and response complexity. These units are aggregated into token-based metrics for reporting and enforcement.

Tracked dimensions:

Tenant and organization

User and role

Feature and module

Time window

Example usage record:

AIUsage::record([ 'tenant_id' => tenant('id'), 'user_id' => auth()->id(), 'feature' => 'translation', 'tokens' => $tokens ]);

Token Accounting

Tokens represent the computational cost of AI interactions. Both input and output tokens are counted deterministically.

Token rules:

Counted per request

Attributed to initiating user

Aggregated per billing period

Token balances are updated atomically to prevent race conditions.

Limits and Quotas

Limits are enforced through configurable quotas defined at plan or tenant level.

Supported limits:

Tokens per day or month

Requests per time window

Feature-specific caps

Example quota check:

if (!AIQuota::allows($user, $tokens)) { abort(429, 'AI usage limit exceeded'); }

Rate Limiting and Throttling

In addition to quota limits, rate limiting protects the system from burst abuse. Throttling slows request processing without rejecting valid usage where possible.

Throttling behavior:

Gradual backoff

Clear user feedback

Automatic recovery

Usage Visibility

Users can view their own AI usage, while administrators can access aggregated views across teams and tenants.

Visible metrics:

Tokens consumed

Remaining quota

Usage per feature

Visibility promotes responsible usage and planning.

Enforcement and Fallback

When limits are reached, AI features are disabled gracefully for the affected scope. Core platform functionality remains available.

No partial responses are returned after enforcement.

Auditing and Reporting

All usage records are retained according to analytics retention policies. Records support billing verification, capacity planning, and audit requirements.

Security and Isolation

AI usage data is tenant-scoped and access-controlled. No usage information is exposed across tenants. Logs exclude content payloads and retain metadata only.