branch: elpa/gptel
commit 6192a171862666065e08c5c5187e8d2ff90dfc8b
Author: Karthik Chikmagalur <karthikchikmaga...@gmail.com>
Commit: Karthik Chikmagalur <karthikchikmaga...@gmail.com>
gptel: Document option presets in README, NEWS
* README.org: Explain gptel presets.
* NEWS: Mention presets.
---
NEWS | 9 +++++++++
README.org | 35 +++++++++++++++++++++++++++++++++++
2 files changed, 44 insertions(+)
diff --git a/NEWS b/NEWS
index 1fc03422f0..a3d3bf28b3 100644
--- a/NEWS
+++ b/NEWS
@@ -39,6 +39,15 @@
- Tools now run in the buffer from which the request originates.
+- You can now define "presets", which are a bundle of gptel options, such as
the
+ backend, model, system message, included tools, temperature and so on. This
+ set of options can be applied together, making it easy to switch between
+ different tasks using gptel. From gptel's transient menu, you can save the
+ current configuration as a preset or apply another one. Presets can be
+ applied globally, buffer-locally or for the next request only. To persist
+ presets across Emacs sessions, define presets in your configuration
+ using ~gptel-make-preset~.
+
** Notable Bug fixes
* 0.9.8 2025-03-13
diff --git a/README.org b/README.org
index 483ffc60a4..e22806dfad 100644
--- a/README.org
+++ b/README.org
@@ -149,6 +149,7 @@ gptel uses Curl if available, but falls back to the
built-in url-retrieve to wor
-
[[#chatgpt-i-get-the-error-http2-429-you-exceeded-your-current-quota][(ChatGPT)
I get the error "(HTTP/2 429) You exceeded your current quota"]]
- [[#why-another-llm-client][Why another LLM client?]]
- [[#additional-configuration][Additional Configuration]]
+ - [[#option-presets][Option presets]]
- [[#alternatives][Alternatives]]
- [[#packages-using-gptel][Packages using gptel]]
- [[#acknowledgments][Acknowledgments]]
@@ -1493,6 +1494,40 @@ Other Emacs clients for LLMs prescribe the format of the
interaction (a comint s
#+html: </details>
+*** Option presets
+
+If you use several LLMs for different tasks with accompanying system prompts
(instructions) and tool configurations, manually adjusting =gptel= settings
each time can become tedious. Presets are a bundle of gptel settings -- such
as the model, backend, system message, and enabled tools -- that you can switch
to at once.
+
+Once defined, presets can be applied from gptel's transient menu:
+
+#+html: <img
src="https://github.com/user-attachments/assets/e0cf6a32-d999-4138-8369-23512f5e9311";
align="center" />
+#+html: <br>
+
+To define a preset, use the =gptel-make-preset= function, which takes a name
and keyword-value pairs of settings:
+
+#+begin_src emacs-lisp
+(gptel-make-preset 'gpt4coding ;preset name, a symbol
+ :description "A preset optimized for coding tasks" ;for your reference
+ :backend "Claude" ;gptel backend or backend name
+ :model 'claude-3-7-sonnet-20250219.1
+ :system "You are an expert coding assistant. Your role is to provide
high-quality code solutions, refactorings, and explanations."
+ :tools '("read_buffer" "modify_buffer")) ;gptel tools or tool names
+#+end_src
+
+Besides a couple of special keys (=:description=, =:parents= to inherit other
presets), there is no predefined list of keys. Instead, the key =:foo=
corresponds to setting =gptel-foo= (preferred) or =gptel--foo=. So the preset
can include the value of any gptel option. For example, the following preset
sets =gptel-temperature= and =gptel-use-context=:
+
+#+begin_src emacs-lisp
+(gptel-make-preset 'proofreading
+ :description "Preset for proofreading tasks"
+ :backend "ChatGPT"
+ :model 'gpt-4.1-mini
+ :tools '("read_buffer" "spell_check" "grammar_check")
+ :temperature 0.7 ;sets gptel-temperature
+ :use-context 'system) ;sets gptel-use-context
+#+end_src
+
+Switching to a preset applies the specified settings without affecting other
settings. Depending on the scope option (~=~ in gptel's transient menu),
presets can be applied globally, buffer-locally or for the next request only.
+
** COMMENT Will you add feature X?
Maybe, I'd like to experiment a bit more first. Features added since the
inception of this package include
