Function: `gptel-make-preset`

gptel-make-preset is a natively compiled function defined in gptel.el.

Signature

(gptel-make-preset NAME &rest KEYS)

Documentation

Define a gptel preset with NAME.

A preset is a combination of gptel options intended to be applied and used together. Presets can make it less tedious to change gptel settings on the fly.

Typically this will include a model, backend, system message and perhaps some tools, but any set of gptel options can be set this way.

NAME must be a symbol. KEYS is a plist corresponding to the options being set. All KEYS are optional.

Recognized keys:

DESCRIPTION is a description of the preset, used when selecting a preset.

PARENTS is a preset name (or list of preset names) to apply before this one.

PRE and POST are functions to run before and after the preset is applied. They take no arguments.

BACKEND is the gptel-backend to set, or its name (like "ChatGPT").

MODEL is the gptel-model, a symbol.

SYSTEM is the directive. It can be
- the system message (a string),
- a list of strings (a conversation template)
- or a function (dynamic system message).
- It can also be a symbol naming a directive in gptel-directives.

TOOLS is a list of gptel tools or tool names, like
'("read_url" "read_buffer" ...)

Recognized keys are not limited to the above. Any other key (like
:foo) corresponds to the value of either gptel-foo (preferred) or
gptel--foo.
- So TOOLS corresponds to option gptel-tools,
- CONFIRM-TOOL-CALLS to gptel-confirm-tool-calls,
- TEMPERATURE to gptel-temperature and so on.
See gptel's customization options for all available settings.

Specifying the value of a key will set the corresponding gptel option to it. For example,

  (gptel-make-preset 'websearch
    :tools '("search_web" "read_url")
    :system "Use the provided tools to search the web
              for up-to-date information")

will replace the currently active option gptel-tools and the system message.

Alternatively,

- You can require that the value be appended or prepended to the
  existing value instead of replacing it. This can be done by
  specifying the value as a plist instead with the keys :prepend or
  :append.

  (gptel-make-preset 'websearch
    :tools '(:append ("search_web" "read_url"))
    :system '(:prepend "Use the provided tools to search the web
                        for up-to-date information."))

- You can dynamically compute the value for a key at the time the preset
is applied with :eval or :function. This is mostly useful when
using presets in the prompt, as @preset-name.

An :eval form is evaluated when the preset is applied:

  (gptel-make-preset 'visible-buffers
    :description "Include the full text of all buffers visible in the
                 frame."
    :context '(:eval (mapcar #'window-buffer (window-list))))
    ▲ ▲
    │ ╰╴evaluated when preset is applied
    ╰╴sets gptel-context

:function should take the current value of the key as an input and
return the new value. Here we combine it with :append in the plist.

  (gptel-make-preset 'github-read-only
    :description "Provide read-only GitHub tools"
    :pre (lambda () (gptel-mcp-connect '("github") 'sync))
    :tools
    '( :append ("mcp-github") ;Adds all github MCP tools
       :function (lambda (tools)
                   (cl-delete-if ;Remove "write" access to GitHub
                    (lambda (tool)
                      (string-match-p "create_" (gptel-tool-name tool)))
                    tools))))

NOTE: :eval and :function are evaluated in a temporary buffer, and
not the buffer from which the request is sent.

Source Code

;; Defined in /nix/store/q3r7g81pvghw7a523kjk2k2zih3pfk8z-emacs-packages-deps/share/emacs/site-lisp/elpa/gptel-20261002.545/gptel.el
(defun gptel-make-preset (name &rest keys)
  "Define a gptel preset with NAME.

A preset is a combination of gptel options intended to be applied and
used together.  Presets can make it less tedious to change gptel
settings on the fly.

Typically this will include a model, backend, system message and perhaps
some tools, but any set of gptel options can be set this way.

NAME must be a symbol.  KEYS is a plist corresponding to the options
being set.  All KEYS are optional.

Recognized keys:

DESCRIPTION is a description of the preset, used when selecting a
preset.

PARENTS is a preset name (or list of preset names) to apply before this
one.

PRE and POST are functions to run before and after the preset is
applied.  They take no arguments.

BACKEND is the `gptel-backend' to set, or its name (like \"ChatGPT\").

MODEL is the `gptel-model', a symbol.

SYSTEM is the directive.  It can be
- the system message (a string),
- a list of strings (a conversation template)
- or a function (dynamic system message).
- It can also be a symbol naming a directive in `gptel-directives'.

TOOLS is a list of gptel tools or tool names, like
\\='(\"read_url\" \"read_buffer\" ...)

Recognized keys are not limited to the above.  Any other key (like
`:foo') corresponds to the value of either `gptel-foo' (preferred) or
`gptel--foo'.
- So TOOLS corresponds to option `gptel-tools',
- CONFIRM-TOOL-CALLS to `gptel-confirm-tool-calls',
- TEMPERATURE to `gptel-temperature' and so on.
See gptel's customization options for all available settings.

Specifying the value of a key will set the corresponding gptel option to
it.  For example,

  (gptel-make-preset \\='websearch
    :tools \\='(\"search_web\" \"read_url\")
    :system \"Use the provided tools to search the web
              for up-to-date information\")

will replace the currently active option `gptel-tools' and the system
message.

Alternatively,

- You can require that the value be appended or prepended to the
  existing value instead of replacing it.  This can be done by
  specifying the value as a plist instead with the keys `:prepend' or
  `:append'.

  (gptel-make-preset \\='websearch
    :tools  \\='(:append (\"search_web\" \"read_url\"))
    :system \\='(:prepend \"Use the provided tools to search the web
                        for up-to-date information.\"))

- You can dynamically compute the value for a key at the time the preset
  is applied with `:eval' or `:function'.  This is mostly useful when
  using presets in the prompt, as @preset-name.

  An `:eval' form is evaluated when the preset is applied:

  (gptel-make-preset \\='visible-buffers
    :description \"Include the full text of all buffers visible in the
                 frame.\"
    :context \\='(:eval (mapcar #\\='window-buffer (window-list))))
    ▲                ▲
    │                ╰╴evaluated when preset is applied
    ╰╴sets `gptel-context'

  `:function' should take the current value of the key as an input and
  return the new value.  Here we combine it with `:append' in the plist.

  (gptel-make-preset \\='github-read-only
    :description \"Provide read-only GitHub tools\"
    :pre (lambda () (gptel-mcp-connect \\='(\"github\") \\='sync))
    :tools
    \\='( :append (\"mcp-github\")       ;Adds all github MCP tools
       :function (lambda (tools)
                   (cl-delete-if    ;Remove \"write\" access to GitHub
                    (lambda (tool)
                      (string-match-p \"create_\" (gptel-tool-name tool)))
                    tools))))

  NOTE: `:eval' and `:function' are evaluated in a temporary buffer, and
  not the buffer from which the request is sent."
  (declare (indent 1))
  (if-let* ((p (assoc name gptel--known-presets)))
      (setcdr p keys)
    (setq gptel--known-presets          ;Add at end of presets for menu ordering
          (nconc gptel--known-presets (list (cons name keys))))))

Function: gptel-make-preset

Signature

Documentation

Source Code

Function: `gptel-make-preset`