Ai v2

docs/espocrm-extensions/espocrm-ai/features/access-control.md

@@ -1,11 +1,83 @@
-!!! Info
-
-    By default, regular and portal users don’t have access to AI features. Administrator needs to enable access in Roles.
+# Access Control
 
+Ebla AI uses EspoCRM's built-in **Roles** system together with normal entity permissions. In practice, users need:
 
+- The relevant **AI scope** enabled in their Role
+- The normal **read / create / edit** permission for the affected entity
 
-![img.png](../../../_static/images/espocrm-extensions/ai/features/img_10.png)
+By default, regular and portal users do not have access to AI features until an Administrator enables them.
 
-!!! Note
+!!! info
 
-    AI Sandbox feature is only available for Admin users
+    Navigate to **Administration → Roles** and enable the required AI scopes for the relevant Role.
+
+![AI Role Scopes](../../../_static/images/espocrm-extensions/ai/features/ai-role-scopes.png)
+
+## Available AI Permission Scopes
+
+Each AI feature has its own permission scope:
+
+| Scope | Controls |
+|-------|----------|
+| `Ai` | Base AI access. Required for all AI-powered features. |
+| `AiChat` | Record-level AI Chat panel and Admin Assistant chat access |
+| `AiEmailComposer` | AI actions in email compose, reply, and email template body editing |
+| `AiFieldAction` | AI actions on text, varchar, wysiwyg, and stream comment content |
+| `AiFormula` | AI formula functions such as `eblaAi\textGenerate`, `eblaAi\runPrompt`, `eblaAi\analyzeImage`, `eblaAi\generateImage`, and `eblaAi\generateSpeech` |
+| `AiRecordSummary` | AI Summary panel on record detail views |
+| `AiSmartPaste` | Smart Paste on list views, relationship panels, and new-record forms |
+| `AiVision` | Image analysis and AI image generation |
+
+## How Feature Access Is Evaluated
+
+The AI scope alone is not enough. The user also needs the standard entity permission required by the feature.
+
+Examples:
+
+- **AI Chat** requires `Ai` + `AiChat` and read access to the current record
+- **AI Summary** requires `AiRecordSummary` and read access to the current record
+- **Smart Paste** requires `Ai` + `AiSmartPaste` and create or edit access to the target entity
+- **AI Create** requires `Ai` and create access to the target entity
+- **Email Translation** requires `Ai` and read access to Email
+- **Image Analysis / Generation** requires `Ai` + `AiVision`
+
+!!! note "Administrators"
+
+    Administrators can access the admin-facing Ebla AI pages, but normal record permissions still matter when a feature reads or writes CRM data.
+
+## Roles Configuration Tips
+
+Recommended patterns:
+
+- Grant `Ai` as the base permission first
+- Add only the feature scopes the role should use
+- Keep `AiChat`, `AiRecordSummary`, and `AiSmartPaste` separate so usage can be controlled more precisely
+- Grant `AiVision` only to users who should analyze or generate images
+
+## Token Usage Limits
+
+In addition to scope-based access control, Ebla AI supports token usage limits.
+
+### Per-User Override
+
+1. Navigate to **Administration → Users**.
+2. Open the user record.
+3. Set **AI Monthly Token Limit**.
+
+Even though the field name says **Monthly**, it acts as the user's personal token-limit override for the currently configured system period:
+
+- **Daily**
+- **Weekly**
+- **Monthly**
+
+Set it to `0` to fall back to the global default limit.
+
+### What Happens at the Limit
+
+When the effective limit is reached:
+
+- New AI requests are blocked
+- The user receives an error explaining that their token limit has been reached
+- Administrators are not blocked by token limits
+
+See [Token Usage Statistics](token-usage.md) for details.

docs/espocrm-extensions/espocrm-ai/features/admin-assistant.md

@@ -0,0 +1,94 @@
+# AI Admin Assistant
+
+The AI Admin Assistant provides a full-page conversational workspace for EspoCRM administrators. It is designed for administrative and configuration tasks such as reviewing metadata, planning changes, helping with formulas, and assisting with entity or layout updates.
+
+Unlike the record-level **AI Chat** panel, this feature runs in **admin mode** and uses a broader tool set intended for CRM administration.
+
+!!! note
+
+    Experimental Feature — The AI Admin Assistant may use significant tokens and can produce incorrect answers. Always verify critical changes before applying them. Use it in a Sandbox environment only.
+
+![AI Admin Assistant](../../../_static/images/espocrm-extensions/ai/features/ai-admin-assistant-page.png)
+
+## Where to Find It
+
+1. Navigate to **Administration**.
+2. Open the **Ebla AI Administration** section.
+3. Click **AI Assistant**.
+
+## Requirements
+
+- The user must be an **Administrator**.
+- The user must have access to AI chat features.
+- A default AI provider must be configured in **Administration → AI Settings**.
+- You can optionally assign a dedicated profile using **AI Admin Assistant Default Profile** in **Administration → AI Settings → AI Features**.
+
+## What It Can Help With
+
+Typical use cases include:
+
+- Explaining how a CRM area works
+- Creating new entity & relationship 
+- Reviewing entity fields and layouts
+- Suggesting formula logic
+- Drafting translation labels
+- Helping plan changes before implementation
+- Assisting with admin-oriented CRM questions
+
+!!! note
+
+    The Admin Assistant is intended for administrators. It uses a broader tool set than record chat and should be treated as an administrative helper, not an unattended automation engine.
+
+## Interface Overview
+
+The page includes:
+
+- A main conversation area
+- A message input with multi-line support
+- Suggested starter prompts
+- A sidebar with saved conversations
+- A **New Chat** action
+- Per-message **Copy** buttons
+
+## Conversation Persistence
+
+The Admin Assistant keeps conversation history in two places:
+
+- **Browser-side conversation list** for quick switching between recent chats
+- **Server-side persisted history** so the active chat can continue across refreshes
+
+Current behavior:
+
+- Up to 30 recent conversations are kept in the browser list
+- Older browser-side conversations are trimmed automatically
+- Conversations older than 7 days are removed from the local sidebar list
+- The active server-side conversation is stored per admin conversation ID
+
+## Using the Assistant
+
+1. Open **Administration → AI Assistant**.
+2. Type your request in the message box.
+3. Press **Enter** to send, or use **Shift+Enter** for a new line.
+4. Review the response.
+5. Start a new conversation when you want a separate context.
+
+Examples:
+
+- "Explain how EspoCRM layouts work."
+- "Help me design fields for a custom Project entity."
+- "Draft a before-save formula that builds a reference number."
+- "What should I check before adding a many-to-many relationship?"
+
+## Best Practices
+
+- Be specific about the entity, field, or layout you are asking about.
+- Use separate chats for unrelated admin topics.
+- Review any suggested configuration carefully before applying it.
+- Use the AI Sandbox if you want to test prompts against a record context first.
+
+## Related Features
+
+- [AI Sandbox](sandbox.md) - Test prompts and record-aware instructions
+- [AI Profiles](ai-profiles.md) - Assign a dedicated profile to the assistant
+- [AI Chat Panel](ai-chat.md) - Record-level AI assistant for end users
+- [Admin Settings](admin-settings.md) - Configure the default profile used by the assistant

docs/espocrm-extensions/espocrm-ai/features/admin-settings.md

@@ -0,0 +1,204 @@
+# Admin Settings
+
+Global AI settings are managed from **Administration → AI Settings**. These settings control provider selection, feature defaults, token limits, response caching, translation behavior, Smart Paste visibility, and Create with AI visibility.
+
+
+## General Tab
+
+The **General** tab contains the core extension-wide settings.
+
+![AI Settings General Tap](../../../_static/images/espocrm-extensions/ai/features/admin-settings-general-tap.png)
+
+### Default AI Provider
+
+The **Default AI Provider** setting determines which configured provider is used when a feature does not explicitly resolve another provider from an AI Profile.
+
+Most UI-based AI actions also expect a default provider to be set before their buttons become visible.
+
+### Default AI Profile
+
+The **Default AI Profile** is the fallback profile used when a feature does not have:
+
+- An entity-specific profile
+- A feature-specific default profile
+- A prompt-linked profile
+
+### Global AI Instructions
+
+The **Global AI Instructions** field lets you define text that is prepended to every AI request across the extension.
+
+Use this for:
+
+- Company-wide response rules
+- Tone and formatting guidance
+- Language instructions
+- Restrictions or compliance reminders
+
+!!! note
+
+    Global AI Instructions are combined with the selected AI Profile context and the feature-specific prompt. The global instructions are applied first.
+
+### Variable Substitution
+
+Global AI Instructions and AI Profile context fields support `{varName}` placeholders.
+
+**Always available:**
+
+| Variable | Replaced with |
+|----------|---------------|
+| `{userName}` | Current user's full name |
+| `{userRole}` | `Administrator` or `User` |
+| `{companyName}` | Company name from Settings |
+| `{today}` | Current date in `YYYY-MM-DD` format |
+| `{language}` | Current user's language code |
+
+**Available when a feature runs against a record context:**
+
+| Variable | Replaced with |
+|----------|---------------|
+| `{entityType}` | Entity type, such as `Contact` or `Opportunity` |
+| `{entityName}` | The record name |
+| `{entityId}` | The record ID |
+
+Unknown placeholders are left unchanged.
+
+## Translate Tab
+
+The **Translate** tab contains language and email-translation settings.
+
+![AI Settings Translate Tab](../../../_static/images/espocrm-extensions/ai/features/admin-settings-translate-tab.png)
+### AI Translate Languages
+
+It controls the language list shown by translation actions in text fields, varchar fields, WYSIWYG fields, and stream comments.
+
+Behavior:
+
+- If one language is configured, the UI shows a single **Translate** action
+- If multiple languages are configured, the UI shows a **Translate To** sub-menu
+
+### Enable Email Translate
+
+Enable **Email Translate** to show the **Translate** button on Email detail views.
+
+### AI Email Translate Default Profile
+
+Set a dedicated profile if you want email translations to use a different model or context than the global default.
+
+### AI Email Translate Default Prompt
+
+Set the prompt used for the email translation request.
+
+!!! important
+
+    Email translation expects a translation prompt to be configured. For reliable use, set **AI Email Translate Default Prompt** explicitly.
+
+## Token Limits Tab
+
+![AI Settings Token Limits Tab](../../../_static/images/espocrm-extensions/ai/features/admin-settings-token-limits-tab.png)
+
+### Default Token Limit
+
+The **Default Token Limit** sets the fallback system-wide token quota for non-admin users.
+
+- `0` means unlimited
+- Applies only when the user does not have a personal override
+
+### Token Limit Period
+
+The **Token Limit Period** defines the enforcement window:
+
+- **Daily**
+- **Weekly**
+- **Monthly**
+
+### Per-User Override
+
+Each user record has an **AI Monthly Token Limit** field. Even though the label says *Monthly*, the value acts as that user's personal override for the currently configured period.
+
+### Max Tool-Call Iterations
+
+It limits how many consecutive tool-call rounds the AI Chat engine can perform in one request.
+
+Use cases:
+
+- Lower values reduce cost and keep tool usage tight
+- Higher values help with more complex multi-step chat tasks
+
+## Response Cache Tab
+
+The response cache reuses identical AI responses for selected features.
+
+![AI Settings Response Cache Tab](../../../_static/images/espocrm-extensions/ai/features/admin-settings-response-cache-tab.png)
+### Settings
+
+- **Response Cache** 
+- **Cache TTL** in days
+
+### What Is Cached
+
+The current implementation uses response caching for several feature APIs, including:
+
+- Email composer actions
+- Email template generation
+- PDF template generation
+- Field text actions
+
+Some AI interactions are intentionally excluded, especially tool-using chat flows.
+
+### Cache Notes
+
+- Cached responses return faster
+- Cached responses do not consume new tokens on the cache-hit request
+- Cache hits are visible in **AI Log**
+
+## AI Features Tab
+
+This tab lets you assign default profiles per feature.
+
+| Setting | Used By |
+|---------|---------|
+| **Default AI Profile** | Global fallback for all features |
+| **AI Chat Default Profile** | Record-level AI Chat |
+| **AI Summary Default Profile** | AI Summary |
+| **AI Email Composer Default Profile** | Draft, reply, polish, grammar, tone |
+| **AI Field Action Default Profile** | Text field and stream comment AI actions |
+| **AI Smart Paste Default Profile** | Smart Paste |
+| **AI Vision Default Profile** | Image analysis and image generation |
+| **AI Admin Assistant Default Profile** | Admin Assistant |
+| **AI Email Translate Default Profile** | Email translation |
+
+![AI Settings AI Features Tab](../../../_static/images/espocrm-extensions/ai/features/admin-settings-ai-features-tab.png)
+## Smart Paste Scopes
+
+The **Smart Paste Scopes** field controls where Smart Paste buttons appear.
+
+Recommended configuration:
+
+1. Open **Administration → AI Settings → General**.
+2. Select the entity types you want to support.
+3. Save.
+
+!!! tip
+
+    Explicitly selecting the scopes gives the most predictable button visibility across main list views, relationship panels, and new-record forms.
+
+## AI Create Scopes
+
+The **AI Create Scopes** field controls where **Create with AI** appears.
+
+1. Open **Administration → AI Settings → General**.
+2. Select the entity types that should show **Create with AI**.
+3. Save.
+
+The button then appears:
+
+- In the main list view header
+- In supported relationship panel lists
+
+## Related Features
+
+- [AI Profiles](ai-profiles.md)
+- [AI Prompts](ai-prompts.md)
+- [AI Smart Paste](smart-paste.md)
+- [AI Create from List View](ai-create.md)
+- [Token Usage & Limits](token-usage.md)