AI Usage & Preferences

Track AI assistant usage and manage per-user preferences including provider selection and enable/disable toggle.

User Preferences

Each user can set their preferred AI provider and enable/disable the assistant for their account.

Preferences Attributes

Field	Type	Description
id	integer	Primary key
user_id	integer	Foreign key to users (unique)
preferred_provider	string	auto, deepseek, or openai
is_enabled	boolean	Enable/disable AI for this user

Preferences Endpoints

Method	URL	Description	Permission
GET	/api/ai/preferences	Get current user's preferences	core.ai.chat
PUT	/api/ai/preferences	Update current user's preferences	core.ai.chat

curl

# Get preferences
curl -X GET https://moon-erp.test/api/ai/preferences \
  -H "Authorization: Bearer {token}"

# Update preferences
curl -X PUT https://moon-erp.test/api/ai/preferences \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"preferred_provider": "openai", "is_enabled": true}'

Usage Tracking

Every AI request is logged with token counts, costs, and cache status.

Usage Log Attributes

Field	Type	Description
id	integer	Primary key
user_id	integer	User who made the request
provider	string	Provider used (deepseek or openai)
model	string	Model used
input_tokens	integer	Input/prompt token count
output_tokens	integer	Output/completion token count
total_tokens	integer	Total token count
cost_usd	decimal(10,6)	Cost in USD
cost_egp	decimal(10,4)	Cost in EGP
cached	boolean	Whether response was served from cache
created_at	datetime	Request timestamp

Usage Endpoints

Method	URL	Description	Permission
GET	/api/ai/usage	Company-wide usage report	core.ai.usage.view
GET	/api/ai/my-usage	Current user's usage	core.ai.chat

Query Parameters (Company Usage)

Parameter	Type	Description
user_id	integer?	Filter by user
provider	string?	Filter by provider (deepseek, openai)
date_from	date?	Start date filter
date_to	date?	End date filter
month	string?	Month filter (format: YYYY-MM)

curl

# Company usage (admin)
curl -X GET "https://moon-erp.test/api/ai/usage?month=2026-03" \
  -H "Authorization: Bearer {token}"

# My usage
curl -X GET https://moon-erp.test/api/ai/my-usage \
  -H "Authorization: Bearer {token}"

Company Usage Response

{
  "data": {
    "totals": {
      "total_requests": 150,
      "total_tokens": 45000,
      "total_cost_usd": 0.0189,
      "total_cost_egp": 0.9545,
      "cached_requests": 42
    },
    "by_provider": [
      {"provider": "deepseek", "requests": 120, "tokens": 36000, "cost_usd": 0.0151, "cost_egp": 0.7626}
    ],
    "by_user": [
      {"user_id": 1, "user_name": "Ahmed", "requests": 80, "tokens": 24000, "cost_usd": 0.01, "cost_egp": 0.505}
    ]
  }
}

Permissions

Permission	Roles	Description
core.ai.settings.manage	owner, manager	View/update AI configuration
core.ai.chat	all roles	Use the AI chat and manage own preferences
core.ai.usage.view	owner, manager	View company-wide usage reports