Skip to content

Move presets docs to own page #1268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
esimkowitz merged 3 commits into from
Nov 12, 2024
Merged

Move presets docs to own page #1268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6b66e8b
Move presets to its own page
esimkowitz Nov 12, 2024
3f3ab14
add required and optional
esimkowitz Nov 12, 2024
8755a9f
Merge branch 'main' into evan/presets-page
esimkowitz Nov 12, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 0 additions & 97 deletions docs/docs/config.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,100 +174,3 @@ wsh editconfig termthemes.json
| background | CSS color | | | background color (default when no color code is applied), must have alpha channel (#rrggbbaa) if you want the terminal to be transparent |
| cursorAccent | CSS color | | | color for cursor |
| selectionBackground | CSS color | | | background color for selected text |

## Presets

Presets can be used to apply multiple setting overrides to either a tab or a block. They are currently supported in two scenarios: tab backgrounds and AI models.

You can set presets either by placing them in `~/.config/waveterm/presets.json` or by placing them in a JSON file in the `~/.config/waveterm/presets/` directory. All presets will be aggregated regardless of which file they're placed in so you can use the `presets` directory to organize them as you see fit.

### File format

Presets follow the following format:

```json
{
...
"<preset-type>@<preset-key>": {
"display:name": "<Preset name>",
"display:order": "<number>", // optional
"<overridden-config-key-1>": "<overridden-config-value-1>"
...
}
}
```

A complete example of a preset for a tab background is the following:

```json
{
"bg@rainbow": {
"display:name": "Rainbow",
"display:order": 2.1,
"bg:*": true,
"bg": "linear-gradient( 226.4deg, rgba(255,26,1,1) 28.9%, rgba(254,155,1,1) 33%, rgba(255,241,0,1) 48.6%, rgba(34,218,1,1) 65.3%, rgba(0,141,254,1) 80.6%, rgba(113,63,254,1) 100.1% )",
"bg:opacity": 0.3
}
}
```

A complete example of a preset for an AI model is the following:

```json
{
"ai@wave": {
"display:name": "Ollama - llama3.1",
"display:order": 0,
"ai:baseurl": "http://localhost:11434",
"ai:model": "llama3.1:latest"
}
}
```

### Preset type

The type of the preset determines where it can be discovered in the app. Currently, the two types that will be discovered in the app are `bg` and `ai`.

`bg` will be served in the "Backgrounds" submenu of the Tab context menu (which can be found by right-clicking on a tab).

![screenshot showing the default options in the backgrounds submenu of the tab context menu](./img/backgrounds-menu.png)

`ai` will be served in the models dropdown in the block header of the "Wave AI" widget.

![screenshot showing the default options in the models dropdown in the block header of the "Wave AI" widget](./img/waveai-model-dropdown.png)

### Available configuration keys

The following configuration keys are available for use in presets:

#### AI configurations:

| Key Name | Type | Function |
| ------------- | ------ | -------------------------------------------------------------------------------- |
| ai:preset | string | the default AI preset to use |
| ai:baseurl | string | Set the AI Base Url (must be OpenAI compatible) |
| ai:apitoken | string | your AI api token |
| ai:apitype | string | defaults to "open_ai", but can also set to "azure" for special Azure AI handling |
| ai:name | string | string to display in the Wave AI block header |
| ai:model | string | model name to pass to API |
| ai:apiversion | string | for Azure AI only (when apitype is "azure", this will default to "2023-05-15") |
| ai:orgid | string | |
| ai:maxtokens | int | max tokens to pass to API |
| ai:timeoutms | int | timeout (in milliseconds) for AI calls |

#### Background configurations:

| Key Name | Type | Function |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| bg:opacity | float | the opacity of the background |
| bg:blendmode | string | the [blend mode](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode) of the background |
| bg:bordercolor | string | the color of the border |
| bg:activebordercolor | string | the color of the border when a block is active |

#### Clear key

Configs in a preset are applied in order to override the default config values, which will persist for the remainder of the tab or block's lifetime. Setting `bg:*` or `ai:*` to `"true"` will clear the values of any previously overridden Background or AI configurations, respectively, setting them back to their defaults.

#### Unset a default value

To unset a default value in a preset, add an override that sets it to an empty string, like `""`.
107 changes: 107 additions & 0 deletions docs/docs/presets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
---
sidebar_position: 3
id: "presets"
title: "Presets"
---

Presets can be used to apply multiple setting overrides at once to either a tab or a block. They are currently supported in two scenarios: tab backgrounds and AI models.

You can set presets either by placing them in `~/.config/waveterm/presets.json` or by placing them in a JSON file in the `~/.config/waveterm/presets/` directory. All presets will be aggregated regardless of which file they're placed in so you can use the `presets` directory to organize them as you see fit.

### File format

Presets follow the following format:

```json
{
...
"<preset-type>@<preset-key>": {
"display:name": "<Preset name>",
"display:order": "<number>", // optional
"<overridden-config-key-1>": "<overridden-config-value-1>"
...
}
}
```

A complete example of a preset for a tab background is the following:

```json
{
"bg@rainbow": {
"display:name": "Rainbow",
"display:order": 2.1,
"bg:*": true,
"bg": "linear-gradient( 226.4deg, rgba(255,26,1,1) 28.9%, rgba(254,155,1,1) 33%, rgba(255,241,0,1) 48.6%, rgba(34,218,1,1) 65.3%, rgba(0,141,254,1) 80.6%, rgba(113,63,254,1) 100.1% )",
"bg:opacity": 0.3
}
}
```

A complete example of a preset for an AI model is the following:

```json
{
"ai@wave": {
"display:name": "Ollama - llama3.1",
"display:order": 0,
"ai:baseurl": "http://localhost:11434",
"ai:model": "llama3.1:latest"
}
}
```

### Preset type

The type of the preset determines where it can be discovered in the app. Currently, the two types that will be discovered in the app are `bg` and `ai`.

`bg` will be served in the "Backgrounds" submenu of the Tab context menu (which can be found by right-clicking on a tab).

![screenshot showing the default options in the backgrounds submenu of the tab context menu](./img/backgrounds-menu.png)

`ai` will be served in the models dropdown in the block header of the "Wave AI" widget.

![screenshot showing the default options in the models dropdown in the block header of the "Wave AI" widget](./img/waveai-model-dropdown.png)

### Available configuration keys

The following configuration keys are available for use in presets:

#### Common keys

| Key Name | Type | Function |
| ------------- | ------ | ---------------------------------------------------------------------- |
| display:name | string | the name to use when displaying the preset in a menu (required) |
| display:order | float | the order in which the preset should be displayed in a menu (optional) |

#### AI configurations

| Key Name | Type | Function |
| ------------- | ------ | -------------------------------------------------------------------------------- |
| ai:preset | string | the default AI preset to use |
| ai:baseurl | string | Set the AI Base Url (must be OpenAI compatible) |
| ai:apitoken | string | your AI api token |
| ai:apitype | string | defaults to "open_ai", but can also set to "azure" for special Azure AI handling |
| ai:name | string | string to display in the Wave AI block header |
| ai:model | string | model name to pass to API |
| ai:apiversion | string | for Azure AI only (when apitype is "azure", this will default to "2023-05-15") |
| ai:orgid | string | |
| ai:maxtokens | int | max tokens to pass to API |
| ai:timeoutms | int | timeout (in milliseconds) for AI calls |

#### Background configurations

| Key Name | Type | Function |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| bg:opacity | float | the opacity of the background |
| bg:blendmode | string | the [blend mode](https://developer.mozilla.org/en-US/docs/Web/CSS/blend-mode) of the background |
| bg:bordercolor | string | the color of the border |
| bg:activebordercolor | string | the color of the border when a block is active |

#### Clear key

Configs in a preset are applied in order to override the default config values, which will persist for the remainder of the tab or block's lifetime. Setting `bg:*` or `ai:*` to `"true"` will clear the values of any previously overridden Background or AI configurations, respectively, setting them back to their defaults.

#### Unset a default value

To unset a default value in a preset, add an override that sets it to an empty string, like `""`.