Skip to content

Commit 478b1cd

Browse files
Mark-Htheboxer
Mark-H
and
theboxer
authored
docs: improve docs
* docs: generate API docs * docs: add recommended init * docs: remove utils that are not exposed to public * docs: remove apiClient that is not exposed to public * docs: remove globalState that is not exposed to public * docs: how to init modAI * docs: add permissions details * docs: add glossary --------- Co-authored-by: Jan Peca <pecajan@gmail.com>
1 parent 248ab85 commit 478b1cd

File tree

6 files changed

+232
-2
lines changed

6 files changed

+232
-2
lines changed

‎Writerside/m.tree‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,14 @@
77
start-page="index.md">
88

99
<toc-element topic="index.md"/>
10+
<toc-element topic="Glossary.md"/>
1011
<toc-element toc-title="Configuration">
1112
<toc-element topic="Configuration_Overview.md"/>
1213
<toc-element topic="Supported-Services.md"/>
14+
<toc-element topic="Permissions.md"/>
15+
</toc-element>
16+
<toc-element toc-title="API">
17+
<toc-element topic="Init-modAI.md"/>
1318
</toc-element>
1419
<toc-element topic="Usage.md"/>
1520
<toc-element topic="Cost.md"/>

‎Writerside/topics/Glossary.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Glossary
2+
3+
## Service
4+
The AI provider that processes and responds to user commands. Options include OpenAI, Google, Anthropic, OpenRouter, Custom, and others.
5+
6+
## Model
7+
The specific AI model from a given [Service](#service) that generates responses to user messages. Models are typically referenced using the format `service/model`. For example: `openai/gpt-4o-mini` or `anthropic/claude-3-sonnet`.
8+
9+
## Context Provider
10+
A form of [RAG](https://en.wikipedia.org/wiki/Retrieval-augmented_generation) (Retrieval-Augmented Generation) that enhances AI responses by supplying additional context from external sources. Context providers allow the AI to access relevant information from defined sources when generating responses, improving accuracy and relevance.
11+
12+
## Tool
13+
A specialized function that extends the AI's capabilities beyond text generation. Tools enable the AI to perform specific actions within your MODX environment. For example, the built-in `create_resource` tool allows the AI to directly create resources in MODX based on user instructions.
14+
15+
## Agent
16+
A configurable preset that bundles various components to create specific AI assistants. An agent can include:
17+
- [Tools](#tool) for specialized actions
18+
- [Context Providers](#context-provider) for enhanced information access
19+
- Custom system prompts that define the AI's behavior
20+
- Model parameters that control response characteristics
21+
- A specific AI [Model](#model)
22+
23+
Agents are currently the only way to utilize tools and context providers within the system.

‎Writerside/topics/Init-modAI.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Initialization
2+
3+
modAI is available globally in manager, if you need to init it elsewhere, you can follow the instructions below.
4+
5+
## Loading up pre-requisites
6+
The following script will get the `modai` service (which can be `null` if it doesn't exist or if user doesn't have appropriate permissions). Then it loads lexicons needed for the modAI's UI and load the main JS file.
7+
```php
8+
if (!$modx->services->has('modai')) {
9+
return;
10+
}
11+
12+
/** @var \modAI\modAI | null $modAI */
13+
$modAI = $modx->services->get('modai');
14+
15+
if ($modAI === null) {
16+
return;
17+
}
18+
19+
foreach ($modAI->getUILexiconTopics() as $topic) {
20+
$modx->controller->addLexiconTopic($topic);
21+
}
22+
23+
$this->modx->regClientStartupScript($this->modAI->getJSFile());
24+
```
25+
26+
## Initializing modAI
27+
When the main JS file is loaded, `ModAI.init` function will be available. It takes single `config` argument, with following parameters. We recommend using helper function to supply all necessary properties to the config `$modAI->getBaseConfig()`, you can check the usage in the example at the end of this page.
28+
29+
### Properties
30+
- `name` (string, optional): Application name
31+
- `assetsURL` (string): Base URL for application assets
32+
- `apiURL` (string): Base URL for API endpoints
33+
- `cssURL` (string): URL for application stylesheets
34+
- `translateFn` (function, optional): Translation function for internationalization
35+
- `availableAgents` (Record<string, AvailableAgent>): Map of available AI agents
36+
- `permissions` (Record<Permissions, 1 | 0>): Map of user permissions
37+
38+
### Returns
39+
An object containing initialized modules:
40+
- `chatHistory`: Chat history management
41+
- `history`: History tracking
42+
- `executor`: Command execution
43+
- `ui`: User interface components
44+
- `lng`: Language/translation utilities
45+
- `checkPermissions`: Function to check if user has specific permission
46+
- `initOnResource`: Resource initialization
47+
- `initGlobalButton`: Global button initialization
48+
49+
## Example
50+
51+
```php
52+
if (!$modx->services->has('modai')) {
53+
return;
54+
}
55+
56+
/** @var \modAI\modAI | null $modAI */
57+
$modAI = $modx->services->get('modai');
58+
59+
if ($modAI === null) {
60+
return;
61+
}
62+
63+
foreach ($modAI->getUILexiconTopics() as $topic) {
64+
$modx->controller->addLexiconTopic($topic);
65+
}
66+
67+
$baseConfig = $modAI->getBaseConfig();
68+
$modx->controller->addHtml('
69+
<script type="text/javascript">
70+
if (typeof modAI === "undefined") {
71+
Ext.onReady(function() {
72+
const modAI = ModAI.init(' . json_encode($baseConfig) . ');
73+
window.modAI = modAI;
74+
});
75+
}
76+
</script>
77+
');
78+
79+
$this->modx->regClientStartupScript($this->modAI->getJSFile());
80+
```

‎Writerside/topics/Permissions.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Permissions
2+
3+
modAI comes with `modAI Admin` access policy, `modAI` access policy template and following permissions:
4+
5+
### Manager permissions
6+
- modai_admin: Access modAI admin
7+
- modai_admin_tools: Access Tools tab
8+
- modai_admin_tool_save: Create/Update tools
9+
- modai_admin_tool_delete: Delete tools
10+
- modai_admin_context_providers: Access Context Providers tab
11+
- modai_admin_context_provider_save: Create/Update context providers
12+
- modai_admin_context_provider_delete: Delete context providers
13+
- modai_admin_agents: Access Agents tab
14+
- modai_admin_agent_save: Create/Update agents
15+
- modai_admin_agent_delete: Delete agents
16+
- modai_admin_agent_tool_save: Assign tool to an agent
17+
- modai_admin_agent_tool_delete: Unassign tool from an agent
18+
- modai_admin_agent_context_provider_save: Assign context provider to an agent
19+
- modai_admin_agent_context_provider_delete: Unassign context provider from an agent
20+
- modai_admin_related_agent_save: Assign agent to a tool/context provider
21+
- modai_admin_related_agent_delete: Unassign agent from a tool/context provider
22+
23+
### Client Permissions
24+
- modai_client: Use modAI
25+
- modai_client_text: Use modAI text generation
26+
- modai_client_vision: Use modAI vision
27+
- modai_client_chat_text: Use modAI chat
28+
- modai_client_chat_image: Use modAI image generation
29+
30+
## Agents
31+
Access to specific agents can be controlled via assigning one or more user groups to the specific agent. If no user group is assigned, the agent is available for everyone. Sudo users have access to every agent, no matter what users groups are specified.
32+
33+
## Image generation & Download
34+
To fully enable image generation & download for a user, user needs to have `modai_client_chat_image` permission, `file_create` permission and `create` policy on the specific media source that is configured as the target for download.

‎Writerside/topics/history.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# History Module
2+
3+
The history module provides a state management system for tracking and navigating through historical values, with support for UI synchronization and context preservation.
4+
5+
## Types
6+
7+
### Cache
8+
Represents a cache of historical values for a specific key.
9+
10+
```typescript
11+
type Cache<C = unknown> = {
12+
visible: number; // Current visible index
13+
values: string[]; // Array of historical values
14+
context: C; // Associated context data
15+
syncUI?: (data: DataOutput<C>, noStore?: boolean) => void; // UI synchronization callback
16+
};
17+
```
18+
19+
### DataOutput
20+
Represents the output data structure for history operations.
21+
22+
```typescript
23+
type DataOutput<C = unknown> = {
24+
value: string; // Current value
25+
nextStatus: boolean; // Whether next operation is available
26+
prevStatus: boolean; // Whether previous operation is available
27+
current: number; // Current position (1-based)
28+
total: number; // Total number of values
29+
context: C; // Associated context data
30+
};
31+
```
32+
33+
## API
34+
35+
### init
36+
Initializes a new history cache for a specific key.
37+
38+
#### Parameters
39+
- `key` (string): Unique identifier for the history
40+
- `syncUI` (function, optional): UI synchronization callback
41+
- `initValue` (string, optional): Initial value
42+
- `context` (C, optional): Initial context data
43+
44+
### insert
45+
Inserts a new value into the history.
46+
47+
#### Parameters
48+
- `key` (string): History key
49+
- `value` (string): Value to insert
50+
- `noStore` (boolean, optional): Whether to skip storing the value
51+
52+
### next
53+
Moves to the next value in the history.
54+
55+
#### Parameters
56+
- `key` (string): History key
57+
58+
### prev
59+
Moves to the previous value in the history.
60+
61+
#### Parameters
62+
- `key` (string): History key
63+
64+
## Usage Example
65+
66+
```typescript
67+
// Initialize history
68+
history.init('myField', (data) => {
69+
// Update UI with new value
70+
field.value = data.value;
71+
});
72+
73+
// Insert new value
74+
history.insert('myField', 'New value');
75+
76+
// Navigate history
77+
const nextValue = history.next('myField');
78+
const prevValue = history.prev('myField');
79+
```
80+
81+
## Features
82+
83+
- Value history tracking
84+
- Navigation (next/previous)
85+
- UI synchronization
86+
- Context preservation
87+
- Optional value storage
88+
- Type-safe context data

‎core/components/modai/lexicon/en/permissions.inc.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@
2020

2121
// region: Client permissions
2222
$_lang['modai.permissions.modai_client'] = 'Use modAI';
23-
$_lang['modai.permissions.modai_client_chat'] = 'Use modAI chat';
2423
$_lang['modai.permissions.modai_client_text'] = 'Use modAI text generation';
25-
$_lang['modai.permissions.modai_client_image'] = 'Use modAI image generation';
2624
$_lang['modai.permissions.modai_client_vision'] = 'Use modAI vision';
25+
$_lang['modai.permissions.modai_client_chat_text'] = 'Use modAI chat';
26+
$_lang['modai.permissions.modai_client_chat_image'] = 'Use modAI image generation';
2727
// endregion

0 commit comments

Comments
 (0)