docs: describe new settings structure and streaming

Author: theboxer

Writerside/m.tree

@@ -13,4 +13,4 @@
     </toc-element>
     <toc-element topic="Usage.md"/>
     <toc-element topic="Cost.md"/>
-</instance-profile>
+</instance-profile>

Writerside/topics/Configuration_Overview.md

@@ -13,17 +13,39 @@ If you have text, textarea, image or image+ Template Variables you wish to use w
 - **text inputs** – modAI uses the base prompt and model and directly inputs the content into the field
 - **textarea inputs** – handled the same as text inputs
 - **richtext inputs** – handled the same as a textarea input, but you must manually copy/paste the output into the textarea
-- **image inputs** – modAI uses the default image model and sizes and creates the imaegs in the `assets/ai` directory
+- **image inputs** – modAI uses the default image model and sizes and creates the images in the `assets/ai` directory
 - **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
 
 
 ### Configuring Field Prompts
 
-Customize the base prompts and configurations in the `global`, `image`, `resources` and `vision` areas in the system settings as needed. The `modai.global.base.prompt` prepends the base to ever other text or textarea prompt, but it does not for image or vision model prompts.
+Customize the base prompts and configurations in the `global`, `image`, `resources` and `vision` areas in the system settings as needed. The `modai.global.text.base_prompt` prepends the base to ever other text or textarea prompt, but it does not for image or vision model prompts.
 
 ## Settings Format
 
-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.).
+Settings use the following naming convention: `{namespace}.{field}.{type}.{setting}`. 
+- Where `namespace` by default is `modai`, but other extras can pass their own to override default settings from their extra.
+- Field in the core modAI can be `res.pagetitle`, `res.longtitle`, `res.introtext`, `res.description`, `res.content` and `tv.tv_name` (for any text/image/image+ TV), but Extras can pass whatever make sense for them (for example TinyMCE RTE will pass `ta` for the content RTE instance). The field can also be `global` which is a fallback for any setting.
+- Type can be one of `text`/`image`/`vision` to denote this setting will get only applied to AI interaction from the specific category
+- Setting is a target setting name like `model`, `temperature`, `quality`
+
+All settings drill down from the most specific to the global one, few examples (resolves top to bottom):
+```
+modai.res.content.text.model
+modai.global.text.model
+```
+
+```
+modai.tv.poster.image.model
+modai.global.image.model
+```
+
+```
+tinymcerte.modai.ta.text.model
+tinymcerte.modai.global.text.model
+modai.ta.text.model
+modai.global.text.model
+```
 
 The `setting` for text or textarea inputs can contain several options below which will override the default settings from the `global` area:
 
@@ -36,18 +58,33 @@ Image and Image+ fields do not prepend their prompts with the base prompt. Image
 - **model** – defaults to `dall-e-3`
 - **quality** – defaults to `standard`
 - **size** – defaults to `1792x1024`
+- **style** – defaults to `vivid`
 
-Image+ fields can use Vision models to describe an imgage for the alt content found in the `vision` area:
+Image+ fields can use Vision models to describe an image for the alt content found in the `vision` area:
 
 - **vision.model** – defaults to `gpt-4o-mini`
 
+### Custom Options
+If needed, cutom options can be supplied to the AI service by either using the `global` variant of the setting for specific type, for example `modai.global.text.custom_options` and setting it to a JSON object with desired properties, or by using a setting for a specific field like `modai.res.content.text.custom_options`.
+
 ### Overriding Global Defaults
 
 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:
 
 - `modai.api.claude.key` → `{your API key}`
-- `modai.res.introtext.model` → `claude-3-5-haiku-20241022`
-- `modai.res.introtext.temperature` → `0.9`
+- `modai.res.introtext.text.model` → `claude-3-5-haiku-20241022`
+- `modai.res.introtext.text.temperature` → `0.9`
+
+## Streaming
+
+If you'd like to stream the AI response into the UI (see the incrementally generated response), you can do so by enabling `modai.global.text.stream` and/or `modai.global.vision.stream` (as always, you can enable this also for only specific fields).
+
+<warning id="warn-streaming">
+    Currently streaming only works when the request is executed on client ("modai.api.execute_on_server" is set to "false").
+</warning>
+
+
+
 
 <seealso>
     <category ref="related">

Writerside/topics/Supported-Providers.md

@@ -34,6 +34,10 @@ To change a prompt to use Google Gemini, set its corresponding model setting, e.
 
 ## Claude (Anthropic)
 
+<warning id="claude-server-only">
+    At this moment Claude can only work serverside. Setting either "modai.api.execute_on_server" or "modai.api.claude.execute_on_server" to "true".
+</warning>
+
 Claude currently only supports text generation. Add a valide API key to the `modai.api.claude.key` to use Claude.
 
 - **text generation** - https://docs.anthropic.com/en/docs/about-claude/models