Souq works fully without AI. With an AI provider connected, the dashboard gains two features. Both are behind the AI assistant permission in Admin roles.
Connect a provider
Any service that speaks the OpenAI chat completions API works. In .env:
AI_BASE_URL="https://api.openai.com/v1"
AI_API_KEY="sk-..."
AI_MODEL="gpt-4o-mini"
Other examples: OpenRouter (https://openrouter.ai/api/v1), Azure OpenAI, or a model on your own machine with Ollama (http://localhost:11434/v1, no key). Restart the server. Without AI_BASE_URL the AI buttons explain how to switch them on.
Store assistant
Dashboard > AI assistant has a chat where the team asks questions in Arabic or English, for example:
- How are sales this month compared with last month?
- Which products should I restock first?
- Which governorates buy the most?
- Suggest a coupon for slow-moving products.
For each question the server builds a short text snapshot of the store (src/lib/assistant.ts): this month's revenue and orders, order counts by status, sales by governorate and by day, best sellers and revenue by department over 90 days, products that are not selling, low-stock variants, coupons and their use, the latest orders and a catalogue summary. The model answers from that snapshot only and is told not to invent figures. It cannot change anything in the store.
The snapshot holds no customer phone numbers, emails or addresses: only order codes, totals, statuses and governorates.
The three insight panels next to the chat (best sellers, revenue by department, products not selling) are computed directly from the database and work without AI.
Write with AI (product descriptions)
In the product form, Write with AI writes the Arabic and English descriptions together from the product names, the department and the facts you type (fabric, fit, origin, care), in one of three tones: warm, minimal or refined. The Arabic is written for Gulf shoppers, not translated from the English, and the model is told never to invent materials, certifications or delivery promises. Read the result before saving.
Limits and cost
Each signed-in account can send 15 chat questions and 10 description requests per minute. Each chat question sends the snapshot (a few thousand characters) and the last 12 messages of the conversation, so a small, inexpensive model is usually enough.
Changing the prompts
The instructions given to the model are in src/lib/ai.ts (chatAboutStore and describeProduct). To give the assistant more data, add lines to storeSnapshot in src/lib/assistant.ts.