branch: elpa/gptel
commit 656b89c6330910e22ebe724ba5fe542ed697dc6a
Author: Karthik Chikmagalur <[email protected]>
Commit: Karthik Chikmagalur <[email protected]>
gptel: Linting and documentation fixes
Linting and documentation pass. checkdoc can be fussy.
* gptel-org.el (gptel-org-ignore-elements):
(gptel-org--link-regex):
(gptel-org--strip-elements):
(gptel-org--annotate-links):
* gptel-request.el (gptel-cache):
(gptel--link-type-cache):
(gptel-markdown--link-regex):
(gptel-use-tools):
(gptel--known-tools):
(gptel-make-tool):
(gptel--parse-tool-results):
(gptel-request--transitions):
(gptel--parse-list):
(gptel-curl--get-args):
* gptel-transient.el (gptel--set-with-scope):
(gptel--read-with-prefix-help):
(gptel--read-with-prefix):
(gptel--tools-init-value):
(gptel--switches):
(transient-infix-read):
(gptel--scope):
(transient-format-value):
(gptel--setup-directive-menu):
(gptel--infix-num-messages-to-send):
(gptel--infix-max-tokens):
* gptel.el (gptel-markdown--annotate-links):
(gptel--handle-error):
(gptel-with-preset):
(gptel--transform-apply-preset):
(gptel--save-preset):
(gptel--apply-preset):
(gptel--preset-syms):
(gptel--previous-variant):
(gptel--next-variant):
---
gptel-org.el | 10 ++++------
gptel-request.el | 35 ++++++++++++++++++-----------------
gptel-transient.el | 29 ++++++++++++++---------------
gptel.el | 37 ++++++++++++++++++++-----------------
4 files changed, 56 insertions(+), 55 deletions(-)
diff --git a/gptel-org.el b/gptel-org.el
index b1dd5f356bd..4b71a85cc2b 100644
--- a/gptel-org.el
+++ b/gptel-org.el
@@ -155,8 +155,7 @@ This makes it feasible to have multiple conversation
branches."
:group 'gptel)
(defcustom gptel-org-ignore-elements '(property-drawer)
- "List of Org elements that should be stripped from the prompt
-before sending it.
+ "Types of Org elements to be stripped from the prompt before sending.
By default gptel will remove Org property drawers from the
prompt. For the full list of available elements, please see
@@ -192,7 +191,7 @@ on a line by themselves, separated from surrounding text."
(defconst gptel-org--link-regex
(concat "\\(?:" org-link-bracket-re "\\|" org-link-angle-re "\\)")
- "Link regex for gptel-mode in Org mode.")
+ "Link regex for `gptel-mode' in Org mode.")
;;; Setting context and creating queries
@@ -301,8 +300,7 @@ depend on the value of `gptel-org-branching-context', which
see."
(current-buffer))))))
(defun gptel-org--strip-elements ()
- "Remove all elements in `gptel-org-ignore-elements' from the
-prompt."
+ "Remove all elements in `gptel-org-ignore-elements' from the prompt."
(let ((major-mode 'org-mode) element-markers)
(if (equal '(property-drawer) gptel-org-ignore-elements)
(save-excursion
@@ -465,7 +463,7 @@ for inclusion into the user prompt for the gptel request."
(nreverse parts)))
(defun gptel-org--annotate-links (beg end)
- "Annotate Org links whose sources are eligible to be sent with `gptel-send.'
+ "Annotate Org links whose sources will be sent with `gptel-send'.
Search between BEG and END."
(when gptel-track-media
diff --git a/gptel-request.el b/gptel-request.el
index 3d059e05306..95bab552c7f 100644
--- a/gptel-request.el
+++ b/gptel-request.el
@@ -347,7 +347,7 @@ behavior of other backends.
This variable controls which parts of the query will be cached,
and can be the symbols t or nil to cache everything or nothing
-respectively. It can also be a list of symbols:
+respectively. It can also be a list of symbols:
- message: Cache conversation messages
- system: Cache the system message
@@ -798,9 +798,11 @@ See `gptel-backend'."
"Arguments always passed to Curl for gptel queries.")
(defvar gptel--link-type-cache nil
- "Cache of checks for binary files. Each alist entry maps an absolute
-file path to a cons cell of the form (t . binaryp), where binaryp is
-non-nil if the file is binary-encoded.")
+ "Cache of checks for binary files.
+
+Each alist entry maps an absolute file path to a cons cell of the
+form (t . binaryp), where binaryp is non-nil if the file is
+binary-encoded.")
;; The following is derived from:
;;
@@ -810,7 +812,7 @@ non-nil if the file is binary-encoded.")
;; guaranteed to be available, we have to hardcode it.
(defconst gptel-markdown--link-regex
"\\(?:\\(?1:!\\)?\\(?2:\\[\\)\\(?3:\\^?\\(?:\\\\\\]\\|[^]]\\)*\\|\\)\\(?4:\\]\\)\\(?5:(\\)\\s-*\\(?6:[^)]*?\\)\\(?:\\s-+\\(?7:\"[^\"]*\"\\)\\)?\\s-*\\(?8:)\\)\\|\\(<\\)\\([a-z][a-z0-9.+-]\\{1,31\\}:[^]
\n
<>,;()]+\\)\\(>\\)\\)"
- "Link regex for gptel-mode in Markdown mode.")
+ "Link regex for `gptel-mode' in Markdown mode.")
;;; Utility functions
@@ -1260,9 +1262,9 @@ Tools are capabilities provided by you to the LLM as
functions an
LLM can choose to call. gptel runs the function call on your
machine.
-If set to t, any tools selected in `gptel-tools' will be made
-available to the LLM. This is the default. It has no effect if
-no tools are selected.
+If set to t, any tools selected in variable `gptel-tools' will be made
+available to the LLM. This is the default. It has no effect if no
+tools are selected.
If set to force, gptel will try to force the LLM to call one or
more of the provided tools. Support for this feature depends on
@@ -1373,7 +1375,7 @@ assigned a category when it is created, with a category of
This is a two-level alist mapping categories and tool names to
the tool itself. It is used as a global register of available
-tools and in gptel's UI, see `gptel-tools'.
+tools and in gptel's UI, see variable `gptel-tools'.
In this example structure, cat-tool and the rest are cl-structs
of type `gptel-tool':
@@ -1413,7 +1415,7 @@ returned."
"Make a gptel tool for LLM use.
The following keyword arguments are available, of which the first
-four are required.
+four SLOTS are required.
NAME: The name of the tool, recommended to be in Javascript style snake_case.
@@ -1547,7 +1549,7 @@ implementation, used by OpenAI-compatible APIs and
Ollama."
(ensure-list tools))))
(cl-defgeneric gptel--parse-tool-results (backend results)
- "Return a BACKEND-appropriate prompt containing tool call RESULTS.
+ "Return a BACKEND appropriate prompt containing tool call RESULTS.
This will be injected into the messages list in the prompt to
send to the LLM.")
@@ -1586,10 +1588,10 @@ OpenAI-compatible and Ollama message formats."
Each entry is a list whose car is a request state (any symbol)
and whose cdr is an alist listing possible next states. Each key
-is either a predicate function or `t'. When `gptel--fsm-next' is
+is either a predicate function or t. When `gptel--fsm-next' is
called, the predicates are called in the order they appear here
to find the next state. Each predicate is called with the state
-machine's INFO, see `gptel-fsm'. A predicate of `t' is
+machine's INFO, see `gptel-fsm'. A predicate of t is
considered a success and acts as a default.")
(defvar gptel-request--handlers
@@ -2204,8 +2206,7 @@ lists with explicit roles (prompt/response/tool). See
the documentation of
'gptel `(tool . ,(plist-get call :id)))))))))
(cl-defgeneric gptel--parse-list (backend prompt-list)
- "Parse PROMPT-LIST and return a list of prompts suitable for
-BACKEND.
+ "Parse PROMPT-LIST and return a list of prompts for BACKEND.
PROMPT-LIST is interpreted as a conversation, i.e. an alternating
series of user prompts and LLM responses. The returned structure
@@ -2495,7 +2496,7 @@ See `gptel-curl--get-response' for its contents.")
(defun gptel-curl--get-args (info token)
"Produce list of arguments for calling Curl.
-REQUEST-DATA is the data to send, TOKEN is a unique identifier."
+INFO contains the request data, TOKEN is a unique identifier."
(let* ((data (plist-get info :data))
;; We have to let-bind the following two variables since their dynamic
;; values are used for key lookup and url resoloution
@@ -2867,4 +2868,4 @@ PROC-INFO is a plist with contextual information."
"Could not parse HTTP response.")))))
(provide 'gptel-request)
-;;; gptel-curl.el ends here
+;;; gptel-request.el ends here
diff --git a/gptel-transient.el b/gptel-transient.el
index ef5f905794f..fbc21915150 100644
--- a/gptel-transient.el
+++ b/gptel-transient.el
@@ -50,10 +50,10 @@
Affects the system message too.")
(defun gptel--set-with-scope (sym value &optional scope)
- "Set SYMBOL's symbol-value to VALUE with SCOPE.
+ "Set SYM's symbol value to VALUE with SCOPE.
If SCOPE is t, set it buffer-locally.
-If SCOPE is 1, reset it after the next gptel-request. (oneshot)
+If SCOPE is 1, reset it after the next gptel request. (oneshot)
Otherwise, clear any buffer-local value and set its default
global value."
(pcase scope
@@ -165,7 +165,7 @@ Meant to be called when `gptel-menu' is active."
(propertize "/" 'face 'default)
(propertize "M-p" 'face 'help-key-binding)
(propertize ": next/previous" 'face 'default))
- "Help string ;TODO: ")
+ "Help string (TODO).")
(defun gptel--read-with-prefix (prefix)
"Show string PREFIX in the minibuffer after the minibuffer prompt.
@@ -173,7 +173,7 @@ Meant to be called when `gptel-menu' is active."
PREFIX is shown in an overlay. Repeated calls to this function
will toggle its visibility state."
(unless (minibufferp)
- (user-error "This command is intended to be used in the minibuffer."))
+ (user-error "This command is intended to be used in the minibuffer"))
(let* ((update
(lambda (ov s)
(overlay-put
@@ -318,7 +318,7 @@ Handle formatting for system messages when the active
"[No system message set]")))
(defun gptel--tools-init-value (obj)
- "Set the initial state of a tool OBJ in `gptel-tools'.
+ "Set the initial state of a tool OBJ in variable `gptel-tools'.
OBJ is a tool-infix of type `gptel--switch'."
(when-let* ((name (car (member (oref obj argument)
@@ -657,10 +657,10 @@ Their own value is ignored")
(defclass gptel--switches (gptel-lisp-variable)
((display-if-true :initarg :display-if-true :initform "True")
(display-if-false :initarg :display-if-false :initform "False"))
- "Boolean lisp variable class for gptel-transient.")
+ "Boolean Lisp variable class for gptel-transient.")
(cl-defmethod transient-infix-read ((obj gptel--switches))
- "Cycle through the mutually exclusive switches."
+ "Cycle through the mutually exclusive switches for OBJ."
(not (oref obj value)))
(cl-defmethod transient-format-value ((obj gptel--switches))
@@ -679,12 +679,12 @@ Their own value is ignored")
(defclass gptel--scope (gptel--switches)
((display-if-true :initarg :display-if-true :initform "buffer")
(display-if-false :initarg :display-if-false :initform "global"))
- "Singleton lisp variable class for `gptel--set-buffer-locally'.
+ "Singleton Lisp variable class for `gptel--set-buffer-locally'.
This is used only for setting this variable via `gptel-menu'.")
(cl-defmethod transient-infix-read ((obj gptel--scope))
- "Cycle through the mutually exclusive switches."
+ "Cycle through the mutually exclusive switches for OBJ."
(with-slots (value) obj
(pcase value
('t (message "Parameters will be set for the next request only"))
@@ -749,7 +749,7 @@ This is used only for setting this variable via
`gptel-menu'.")
(cl-defmethod transient-format-value ((obj gptel-option-overlaid))
"Set up the in-buffer overlay for additional directive, a string.
-Also format its value in the Transient menu."
+Also format the value of OBJ in the transient menu."
(let ((value (oref obj value))
(ov (oref obj overlay))
(argument (oref obj argument)))
@@ -930,8 +930,7 @@ Also format its value in the Transient menu."
;; ** Prefix for setting the system prompt.
(defun gptel--setup-directive-menu (sym msg &optional external)
- "Return a list of transient infix definitions for setting gptel
-directives.
+ "Return a list of infix definitions for setting gptel directives.
SYM is the symbol whose value is set to the selected directive..
MSG is the meaning of symbol, used when messaging.
@@ -1223,8 +1222,8 @@ value of `gptel-use-context', set from here."
"Number of recent messages to send with each exchange.
By default, the full conversation history is sent with every new
-prompt. This retains the full context of the conversation, but
-can be expensive in token size. Set how many recent messages to
+prompt. This retains the full context of the conversation, but
+can be expensive in token size. Set how many recent messages to
include."
:description "previous responses"
:class 'gptel-lisp-variable
@@ -1239,7 +1238,7 @@ include."
(transient-define-infix gptel--infix-max-tokens ()
"Max tokens per response.
-This is roughly the number of words in the response. 100-300 is a
+This is roughly the number of words in the response. 100-300 is a
reasonable range for short answers, 400 or more for longer
responses."
:description "Response length (tokens)"
diff --git a/gptel.el b/gptel.el
index bdc526deb47..e1d26634ff3 100644
--- a/gptel.el
+++ b/gptel.el
@@ -668,7 +668,7 @@ which see for BEG, END and PRE."
beg end `(gptel ,val front-sticky (gptel))))))
(defun gptel-markdown--annotate-links (beg end)
- "Annotate Markdown links whose sources are eligible to be sent with
`gptel-send.'
+ "Annotate Markdown links whose sources will be sent with `gptel-send'.
Search between BEG and END."
(when gptel-track-media
@@ -1164,9 +1164,9 @@ No state transition here since that's handled by the
process sentinels."
(marker-position start-marker) (marker-position tracking-marker))))))
(defun gptel--handle-error (fsm)
- "Check for errors in request state FSM perform UI updates.
+ "Check for errors in request state FSM.
-Run post-response hooks."
+Perform UI updates and run post-response hooks."
(when-let* ((info (gptel-fsm-info fsm))
(error-data (plist-get info :error))
(http-msg (plist-get info :status))
@@ -1908,10 +1908,10 @@ Alternatively,
(gptel-make-preset \\='visible-buffers
:description \"Include the full text of all buffers visible in the
frame.\"
- :context \\='(:eval ;sets `gptel-context'
- (mapcar #\\='window-buffer
- (delq (unless (minibufferp) (selected-window))
- (window-list)))))
+ :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.
@@ -1922,10 +1922,13 @@ Alternatively,
:tools
\\='( :append (\"mcp-github\") ;Adds all github MCP tools
:function (lambda (tools)
- (cl-delete-if ;Remove non-query tools from list
+ (cl-delete-if ;Remove \"write\" access to GitHub
(lambda (tool)
(string-match-p \"create_\" (gptel-tool-name tool)))
- tools))))"
+ 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)
@@ -1941,7 +1944,7 @@ Alternatively,
NAME must be a symbol. DESCRIPTION is added if provided. In addition
to registering the preset, elisp code to do the same is copied to the
-kill-ring."
+`kill-ring'."
(interactive
(list (intern (completing-read "Save gptel settings to (existing or new)
preset: "
gptel--known-presets))
@@ -1984,7 +1987,7 @@ defaults to `set', and can be set to a different function
to (for
example) apply the preset buffer-locally."
(when (memq (type-of preset) '(string symbol))
(let ((spec (or (gptel-get-preset preset)
- (user-error "gptel preset \"%s\": Cannot find preset."
+ (user-error "gptel preset \"%s\": Cannot find preset"
preset))))
(setq preset spec)))
(unless setter (setq setter #'set))
@@ -2004,7 +2007,7 @@ example) apply the preset buffer-locally."
;; TODO(modify-list): Catch other incompatible combinations
(and (or (plist-member val :append) (plist-member val :prepend))
(not (stringp (symbol-value sym)))
- (user-error "Composing non-string system messages is not
implemented."))
+ (user-error "Composing non-string system messages is not
implemented"))
(setq val (gptel--modify-value (symbol-value sym) val)))
(if (and (symbolp val) (not (functionp val)))
(if-let* ((directive (alist-get val gptel-directives)))
@@ -2016,7 +2019,7 @@ example) apply the preset buffer-locally."
(gptel-backend val)
(string (gptel-get-backend val))))
(unless val
- (user-error "gptel preset: Cannot find backend %s." val))
+ (user-error "gptel preset: Cannot find backend %s" val))
(funcall setter 'gptel-backend val))
(:tools ;TEMP Confirm this `:append' convention
(setq val (gptel--modify-value gptel-tools val))
@@ -2028,7 +2031,7 @@ example) apply the preset buffer-locally."
(string (ignore-errors
(gptel-get-tool tool-name))))
do (unless tool
- (user-error "gptel preset: Cannot find tool
%s." val))
+ (user-error "gptel preset: Cannot find tool %s"
val))
collect tool))))
(funcall setter 'gptel-tools (cl-delete-duplicates tools :test
#'eq))))
((and (let sym (or (intern-soft
@@ -2052,7 +2055,7 @@ PRESET is the name of a preset, or a spec (plist) of the
form
(:KEY1 VAL1 :KEY2 VAL2 ...)."
(when (memq (type-of preset) '(string symbol))
(let ((spec (or (gptel-get-preset preset)
- (user-error "gptel preset \"%s\": Cannot find preset."
+ (user-error "gptel preset \"%s\": Cannot find preset"
preset))))
(setq preset spec)))
(let* ((index preset)
@@ -2258,7 +2261,7 @@ context for the ediff session."
(goto-char beg) (push-mark) (goto-char end) (activate-mark)))
(defun gptel--previous-variant (&optional arg)
- "Switch to previous gptel-response at this point, if it exists."
+ "Switch to ARG previous gptel-response at this point, if it exists."
(interactive "p")
(pcase-let* ((`(,beg . ,end) (gptel--get-response-bounds))
(history (get-char-property (point) 'gptel-history))
@@ -2284,7 +2287,7 @@ context for the ediff session."
(pulse-momentary-highlight-region beg (+ beg (length alt-response)))))
(defun gptel--next-variant (&optional arg)
- "Switch to next gptel-response at this point, if it exists."
+ "Switch to ARG next gptel-response at this point, if it exists."
(interactive "p")
(gptel--previous-variant (- arg)))
