Skip to content

Commit 40ef63b

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 92082e7 commit 40ef63b

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
@@ -153,6 +153,7 @@ gptel uses Curl if available, but falls back to the built-in url-retrieve to wor
153153
- [[#why-another-llm-client][Why another LLM client?]]
154154
- [[#additional-configuration][Additional Configuration]]
155155
- [[#option-presets][Option presets]]
156+
- [[#applying-presets-to-requests-automatically][Applying presets to requests automatically]]
156157
- [[#alternatives][Alternatives]]
157158
- [[#packages-using-gptel][Packages using gptel]]
158159
- [[#acknowledgments][Acknowledgments]]
@@ -1390,6 +1391,9 @@ gptel does /not/ use any prefix or semantic/syntax element in the buffer (such a
13901391
*** Transient menu behavior
13911392
#+html: <details><summary>
13921393
**** I want to set gptel options, but only for this buffer
1394+
:PROPERTIES:
1395+
:ID: 748cbc00-0c92-4705-8839-619b2c80e566
1396+
:END:
13931397
#+html: </summary>
13941398

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

15941598
#+begin_src emacs-lisp
1595-
(gptel-make-preset 'proofreading
1599+
(gptel-make-preset 'proofreader
15961600
:description "Preset for proofreading tasks"
15971601
:backend "ChatGPT"
15981602
:model 'gpt-4.1-mini
@@ -1603,6 +1607,39 @@ Besides a couple of special keys (=:description=, =:parents= to inherit other pr
16031607

16041608
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.
16051609

1610+
**** Applying presets to requests automatically
1611+
1612+
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.]])
1613+
1614+
For example, if you have a preset named =websearch= defined which includes tools for web access and search:
1615+
#+begin_src emacs-lisp
1616+
(gptel-make-preset 'websearch
1617+
:description "Haiku with basic web search capability."
1618+
:backend "Claude"
1619+
:model 'claude-3-5-haiku-20241022
1620+
:tools '("search_web" "read_url" "get_youtube_meta"))
1621+
#+end_src
1622+
1623+
The following query is sent with this preset applied:
1624+
1625+
#+begin_quote
1626+
@websearch Are there any 13" e-ink monitors on the market? Create a
1627+
table comparing them, sourcing specs and reviews from online sources.
1628+
Also do the same for "transreflective-LCD" displays -- I'm not sure
1629+
what exactly they're called but they're comparable to e-ink.
1630+
#+end_quote
1631+
1632+
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.
1633+
1634+
The =@preset-name= cookie can be anywhere in the prompt. For example:
1635+
#+begin_quote
1636+
<long piece of text>
1637+
1638+
What do you make of the above description, @proofreader?
1639+
#+end_quote
1640+
1641+
In chat buffers this prefix will be offered as a completion and fontified, making it easy to use and spot.
1642+
16061643
** COMMENT Will you add feature X?
16071644

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

0 commit comments

Comments
 (0)