Skip to content

Commit ed41950

Browse files
committed
README: Describe on-the-fly preset usage
* README.org (Option presets): Add section describing on-the-fly presets via preset cookies, with examples.
1 parent bd074ea commit ed41950

File tree

1 file changed

+38
-1
lines changed

1 file changed

+38
-1
lines changed

README.org

Lines changed: 38 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,7 @@ gptel uses Curl if available, but falls back to the built-in url-retrieve to wor
151151
- [[#why-another-llm-client][Why another LLM client?]]
152152
- [[#additional-configuration][Additional Configuration]]
153153
- [[#option-presets][Option presets]]
154+
- [[#applying-presets-to-requests-automatically][Applying presets to requests automatically]]
154155
- [[#alternatives][Alternatives]]
155156
- [[#packages-using-gptel][Packages using gptel]]
156157
- [[#acknowledgments][Acknowledgments]]
@@ -1347,6 +1348,9 @@ gptel does /not/ use any prefix or semantic/syntax element in the buffer (such a
13471348
*** Transient menu behavior
13481349
#+html: <details><summary>
13491350
**** I want to set gptel options, but only for this buffer
1351+
:PROPERTIES:
1352+
:ID: 748cbc00-0c92-4705-8839-619b2c80e566
1353+
:END:
13501354
#+html: </summary>
13511355

13521356
In every menu used to set options, gptel provides a "scope" option, bound to the ~=~ key:
@@ -1549,7 +1553,7 @@ To define a preset, use the =gptel-make-preset= function, which takes a name and
15491553
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=:
15501554

15511555
#+begin_src emacs-lisp
1552-
(gptel-make-preset 'proofreading
1556+
(gptel-make-preset 'proofreader
15531557
:description "Preset for proofreading tasks"
15541558
:backend "ChatGPT"
15551559
:model 'gpt-4.1-mini
@@ -1560,6 +1564,39 @@ Besides a couple of special keys (=:description=, =:parents= to inherit other pr
15601564

15611565
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.
15621566

1567+
**** Applying presets to requests automatically
1568+
1569+
You can apply a preset to a /single/ query by including =@preset-name= in the prompt, where =preset-name= is the name of the preset. (The =oneshot= scope option in gptel's transient menus is another way to do this, [[id:748cbc00-0c92-4705-8839-619b2c80e566][see the FAQ.]])
1570+
1571+
For example, if you have a preset named =websearch= defined which includes tools for web access and search:
1572+
#+begin_src emacs-lisp
1573+
(gptel-make-preset 'websearch
1574+
:description "Haiku with basic web search capability."
1575+
:backend "Claude"
1576+
:model 'claude-3-5-haiku-20241022
1577+
:tools '("search_web" "read_url" "get_youtube_meta"))
1578+
#+end_src
1579+
1580+
The following query is sent with this preset applied:
1581+
1582+
#+begin_quote
1583+
@websearch Are there any 13" e-ink monitors on the market? Create a
1584+
table comparing them, sourcing specs and reviews from online sources.
1585+
Also do the same for "transreflective-LCD" displays -- I'm not sure
1586+
what exactly they're called but they're comparable to e-ink.
1587+
#+end_quote
1588+
1589+
This =@preset-name= cookie only applies to the final user turn of the coversation that is sent. So the presence of the cookie in past messages/turns is not significant.
1590+
1591+
The =@preset-name= cookie can be anywhere in the prompt. For example:
1592+
#+begin_quote
1593+
<long piece of text>
1594+
1595+
What do you make of the above description, @proofreader?
1596+
#+end_quote
1597+
1598+
In chat buffers this prefix will be offered as a completion and fontified, making it easy to use and spot.
1599+
15631600
** COMMENT Will you add feature X?
15641601

15651602
Maybe, I'd like to experiment a bit more first. Features added since the inception of this package include

0 commit comments

Comments
 (0)