> For the complete documentation index, see [llms.txt](https://docs.xenoraa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xenoraa.com/xenoraa-super-admin-operations-manual/xena-ai-platform-management.md).

# Xena AI Platform Management

## Xena AI Platform Management

Xena AI is the core intelligence engine of Xenoraa, providing tenants with a natural-language business analyst that can interact with their CRM, POS, and financial data. As a Super Admin, you are responsible for monitoring AI usage, managing tenant credits, updating the global AI knowledge base, and reviewing system logs.

***

### 1. Xena AI Architecture & Token Flow

Xena AI is powered by OpenAI's models via a secure server-side proxy. To prevent abuse and manage API costs, Xenoraa implements a token-based credit system.

```
Tenant Prompt (Xena Chat) 
  ──> Credit Check (xena_credits table) 
    ──> Tool Discovery (XenaController@getTools) 
      ──> OpenAI API Call (via Server Proxy) 
        ──> Tool Dispatch (XenaActionService) 
          ──> Deduct Credits 
            ──> Stream Response (SSE)
```

* **Credit Cost:** Each AI prompt costs **1 Credit** by default. Complex operations involving multiple tool executions may cost up to **2-3 Credits**.
* **Plan Allocations:** Professional plans receive **100 Credits/month**; Business plans receive **300 Credits/month**.
* **Top-Ups:** Tenants can purchase additional credit packs from their dashboard, which must be approved or provisioned by the Super Admin.

***

### 2. Step-by-Step AI Management Workflows

#### Workflow A: Monitoring Global AI Usage

To monitor platform-wide AI engagement and API cost telemetry, use the Xena Dashboard.

1. Navigate to **Xena AI Dashboard** (`/superadmin/xena/dashboard`).
2. Review the core metrics:
   * **Total AI Prompts:** Total prompts executed across the platform.
   * **API Token Cost:** Estimated OpenAI API cost in USD/INR.
   * **Top Active Tenants:** List of tenants with the highest AI engagement.
   * **Tool Execution Rate:** Breakdown of which tools (e.g., `crm_list_leads`, `accounts_list_expenses`) are run most frequently.

***

#### Workflow B: Managing Tenant AI Credits & Top-Ups

If a tenant runs out of credits or purchases a top-up pack offline, you must manually adjust their credit balance.

1. Navigate to **Xena Tenants** (`/superadmin/xena/tenants`).
2. Search for the tenant's company name.
3. Click **Top-Up Credits** to open the credit management modal.
4. **Select Action:** Choose **Add Credits** (or **Deduct Credits** if correcting an error).
5. **Enter Amount:** Enter the number of credits to add (e.g., `100` or `500`).
6. **Enter Note:** Write a reason for the adjustment (e.g., "Purchased 100 Credit Pack — Invoice #INV-2026-098").
7. Click **Save Changes**. The system updates the `xena_credits` table and logs the transaction. The tenant's credit balance updates instantly.

***

#### Workflow C: Managing the Global AI Knowledge Base

You can feed custom business rules, platform updates, and domain-specific knowledge directly into Xena's system prompt using the Knowledge Base manager. This ensures Xena always has the latest context about your platform.

1. Navigate to **Xena Knowledge Base** (`/superadmin/xena/knowledge`).
2. **Add Knowledge Entry:** Click **Add New Entry**.
3. Enter a **Title** (e.g., "GST Tax Rate Updates — July 2026").
4. Enter the **Content** (detailed rules, tax brackets, or guidelines).
5. Select the **Category** (CRM, Accounts, POS, General).
6. Click **Save & Publish**.
7. The system will compile this entry and inject it into the `buildSystemPrompt()` payload on the next AI request.

***

### 3. Auditing Tenant AI Logs & Daily Snapshots

If a tenant reports that Xena is behaving unexpectedly or failing to run tools:

1. Navigate to **Xena Tenant Logs** (`/superadmin/xena/tenant/{userId}/logs`).
2. Select the tenant to view their full chat history, prompt payloads, and tool execution logs.
3. Check the **Status** column for tool failures or API exceptions.
4. **Trigger Daily Snapshot:** If Xena's context is stale, click **Trigger Daily Snapshot** (`/superadmin/xena/tenant/{userId}/snapshot`). This runs the `xena:daily-snapshot` Artisan command, which compiles their CRM, POS, and financial summaries into a cached memory file for Xena to read, restoring peak performance.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xenoraa.com/xenoraa-super-admin-operations-manual/xena-ai-platform-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.