|
1 | 1 | # modAI |
2 | 2 | A generative AI Extra for MODX Revolution 3.0 and later. It’s perfect for creating content quickly or speeding up optimizing SEO-related content including page titles, meta titles, meta descriptions, page summaries, and images/alt text (finally, an easy-button for Open Graph sharing images or hero sections). |
3 | 3 |
|
4 | | -The modAI Plugin adds a sparkle button (✦) next to fields or labels in back-end Manager for MODX Revolution. When clicked, it: |
5 | | - |
6 | | -1. uses field-specific prompts for the type of content being created, |
7 | | -2. uses a supported AI model API to create said content, and |
8 | | -3. dumps the result directly into the appropriate field or a textarea that you can copy/paste from (e.g., for longer format articles going into the Content field). |
9 | | - |
10 | | -## Requirements |
11 | | - |
12 | | -- MODX Revolution 3.x |
13 | | -- A ChatGPT API key from https://platform.openai.com/api-keys, Google Gemini API key from https://ai.google.dev/gemini-api/docs/api-key or Anthropic Claude API key from https://console.anthropic.com/settings/keys |
14 | | -- Pre-paid credits for API calls for ChatGPT if using—this is different than the $20/month ChatGPT Pro subscription |
15 | | - |
16 | | -**Note:** image and vision support is currently only supported with the ChatGPT APIs. Claude and Gemini only support text generation. |
17 | | - |
18 | | -MODX’s modAI Extra works with the following Extras if installed: |
19 | | - |
20 | | -- **image+** – for things like Open Graph sharing previews or hero section images with robust output templating, resizing, cropping and format conversions in conjunction with **pThumb** https://extras.modx.com/package/imageplustvinput |
21 | | -- **SEO Suite+** – for managing and previewing SEO-related information for your sites https://extras.modx.com/package/seosuite |
22 | | - |
23 | | -## Configuration |
24 | | - |
25 | | -After installing modAI, update the `modai.chatgpt.key` with your ChatGPT API key and/or the `modai.gemini.key` as appropriate. (Filter by the `modai` namespace to make finding it easier.) |
26 | | - |
27 | | -The default fields modAI enables in the `modai.res.fields` setting are longtitle, description, introtext/summary, and content. Attach modAI to other default fields in this setting. |
28 | | - |
29 | | -If you have text, textarea, image or image+ Template Variables you wish to use with modAI, add their TV names to the `modai.tvs` setting (without a `tv.` prefix). |
30 | | - |
31 | | -Customize the base prompts and configurations in the `global`, `image`, `prompt` and `vision` areas of the `modai` namespace in the system settings as needed. The `modai.prompt.base` is roughly equated to a light version of ChatGPT’s custom instructions: it prepends the base prompt to ever other text or textarea prompt, but it does not for image or vision model prompts. |
32 | | - |
33 | | -Settings use the following naming convention: `modai.{res||tv}.{field/tv-name}.{setting}` where `{res||tv}` denotes a default MODX Revolution field or a custom Template Variable (TV) and `field/tv-name` is its actual name (e.g., pagetitle, longtitle, fancy-image-tv, etc.). |
34 | | - |
35 | | -The `setting` for text or textarea inputs can contain several options below which will override the default settings from the `global` area: |
36 | | - |
37 | | -- **model** – for text or textarea, modAI defaults to use `gpt-4o` |
38 | | -- **temperature** – defaults to `0.7`, increase this to 1 for more “creative” results or 0 for highly predictable ones |
39 | | -- **max_tokens** – defaults to `2048` |
40 | | - |
41 | | -Image and Image+ fields do not prepend their prompts with the base prompt. Image/Image+ setting defaults in the `image` area include: |
42 | | - |
43 | | -- **model** – defaults to `dall-e-3` |
44 | | -- **quality** – defaults to `standard` |
45 | | -- **size** – defaults to `1792x1024` |
46 | | - |
47 | | -Image+ fields can use Vision models to describe an imgage for the alt content found in the `vision` area: |
48 | | - |
49 | | -- **vision.model** – defaults to `gpt-4o-mini` |
50 | | - |
51 | | -### Supported Providers |
52 | | - |
53 | | -#### ChatGPT (OpenAI) |
54 | | - |
55 | | -ChatGPT is the default model assumed. Fill out the `modai.api.chatgpt.key` and adjust any models as desired. |
56 | | - |
57 | | -- **text generation** – https://platform.openai.com/docs/guides/text-generation |
58 | | -- **image to text** – https://platform.openai.com/docs/guides/vision |
59 | | -- **DALL-E image creation** – https://platform.openai.com/docs/guides/images |
60 | | - |
61 | | -#### Google Gemini |
62 | | - |
63 | | -Add a valide API key to the `modai.api.gemini.key` to use Google Gemini. |
64 | | - |
65 | | -For details on current Gemini models supported, consult their documentation: |
66 | | - |
67 | | -- **text generation** - https://ai.google.dev/gemini-api/docs/models/gemini |
68 | | -- **image to text** – https://ai.google.dev/gemini-api/docs/vision |
69 | | -- **image generation** – https://ai.google.dev/gemini-api/docs/imagen |
70 | | - |
71 | | -To change a prompt to use Google Gemini, set its corresponding model setting, e.g: |
72 | | - |
73 | | -- `global.global.model` → `gemini-2.0-flash` |
74 | | - |
75 | | -#### Claude (Anthropic) |
76 | | - |
77 | | -Claude currently only supports text generation. Add a valide API key to the `modai.api.claude.key` to use Claude. |
78 | | - |
79 | | -- **text generation** - https://docs.anthropic.com/en/docs/about-claude/models |
80 | | - |
81 | | -To change a prompt to use Claude, set its corresponding model setting, e.g: |
82 | | - |
83 | | -- `global.global.model` → `claude-3-5-haiku-latest` |
84 | | - |
85 | | - |
86 | | -#### Custom Services/Models |
87 | | - |
88 | | -Some services like [Open WebUI](https://docs.openwebui.com) provide a wrapper for multiple models. To use a custom model via these services you need to fill out the `modai.api.custom.url`, `modai.api.custom.key` and optionally the `modai.custom.compatibility`, which tells the model what API emulation to use (almost alway leave this as openai). |
89 | | - |
90 | | -To use the custom service, set the following fields: |
91 | | - |
92 | | -- `modai.api.custom.url` → `{your custom URL}` |
93 | | -- `modai.api.custom.key` → `{your API key}` |
94 | | - |
95 | | -Then, you for each model you want to use, set the corresponding "model" field with the prefix "custom_" followed by the model name, e.g: |
96 | | - |
97 | | -- `modai.global.model` → `custom_llama3.1:8b` |
98 | | - |
99 | | - |
100 | | -### Adding modAI to other fields and Template Variables (TVs) |
101 | | - |
102 | | -The modAI plugin can attach to most default fields (e.g. pagetitle, menutitle) and any TV with a text, textarea, image or image+ TV input in the `modai.res.fields` and `modai.tvs` settings. The field types are handled individually as follows: |
103 | | - |
104 | | -- **text inputs** – modAI uses the base prompt and model and directly inputs the content into the field |
105 | | -- **textarea inputs** – handled the same as text inputs |
106 | | -- **richtext inputs** – handled the same as a textarea input, but you must manually copy/paste the output into the textarea |
107 | | -- **image inputs** – modAI uses the default image model and sizes and creates the imaegs in the `assets/ai` directory |
108 | | -- **image+ TVs** – handled the same as image inputs, with the addition of being able to use the Vision model for creating alt tag captions from generated images |
109 | | - |
110 | | -### Overriding Global Defaults |
111 | | - |
112 | | -Each field that you attach modAI to can have settings overrides. This means that you can mix and match which models are used for specific fields, allowing you to optimize for cost or quality depending on your application. For example to use Claude Haiku to generate a (very) creative summary for the `[[*introtext]]` field, you would update/create the following settings: |
113 | | - |
114 | | -- `modai.api.claude.key` → `{your API key}` |
115 | | -- `modai.res.introtext.model` → `claude-3-5-haiku-20241022` |
116 | | -- `modai.res.introtext.temperature` → `0.9` |
117 | | - |
118 | | -If you have a blank field option, it will remove the global defaults from being used. |
119 | | - |
120 | | -For a list of valid modesl for OpenAI’s ChatGPT, see https://platform.openai.com/docs/models |
121 | | - |
122 | | -For a list of valid models for Google Gemini, see https://ai.google.dev/gemini-api/docs/models/gemini |
123 | | - |
124 | | -For a list of valid models for Anthropic’s Claude, see https://docs.anthropic.com/en/docs/about-claude/models |
125 | | - |
126 | | - |
127 | | -## Usage |
128 | | - |
129 | | -Wherever you see a field or a label with a “sparkle button” (✦) next to it, click it to use the chatGPT api to create content in those fields based on the system settings prompts/configurations. By default, it automatically creates sparkle buttons for several fields as outlined below. Delete the prompt settings to remove modAI’s sparkle buttons and the generative AI content creation for those fields: |
130 | | - |
131 | | -- **longtitle** – often used for the SEO Meta Title manually or with SEO Suite (should be ~70 characters) |
132 | | -- **description** – often used for the SEO Meta Description manually or with SEO Suite (should be ~155 characters) |
133 | | -- **introtext** – aka Summary, this is set to summarize the page content—useful for news/blog landing pages or as a base to generate images or image+ images from (make sure to save first so it has content to pull from) |
134 | | -- **content** – a freeform prompt box allows you to give instructions on the type of content to generate |
135 | | - |
136 | | -If you’re not happy with what modAI generates, click the sparkle button or generate buttons again to generate another variation. You can then use the prev/next navigation buttons to go between the options. When you save, it keeps the option shown and discards the rest. |
137 | | - |
138 | | -## Costs |
139 | | - |
140 | | -**OpenAI API credits must be purchased for this Extra to work with Image models.** Find costs for the various models at https://openai.com/api/pricing/. |
141 | | - |
142 | | -Google Gemini offeres a variety of free options with limits. Image generation requires payments: https://ai.google.dev/pricing |
143 | | - |
144 | | -Anthropic’s API pricing is here: https://www.anthropic.com/pricing#anthropic-api |
145 | | - |
146 | | -To learn more about maanging cost, make sure to use the most optimal models for the type of content you expect your prompts to generate. For example, [1000 tokes is roughly equal to 750 words](https://platform.openai.com/docs/guides/production-best-practices#text-generation); make sure the [model you choose](https://platform.openai.com/docs/guides/model-selection) is the right one for the job at hand. |
| 4 | +Read the [documentation](https://modxcms.github.io/modai/). |
0 commit comments