manual: Update

Author: karthink

doc/manual.org

@@ -67,35 +67,6 @@ gptel is a Large Language Model client for Emacs, with support for
 multiple models and backends.  It works in the spirit of Emacs,
 available at any time and uniformly in any buffer.
 
-gptel supports the following services.
-
-#+html: <div align="center">
-#+attr_texinfo: :columns .2 .7
-| LLM Backend        | Requires                   |
-|--------------------+----------------------------|
-| ChatGPT            | [[https://platform.openai.com/account/api-keys][API key]]                    |
-| Anthropic (Claude) | [[https://www.anthropic.com/api][API key]]                    |
-| Gemini             | [[https://makersuite.google.com/app/apikey][API key]]                    |
-| Ollama             | [[https://ollama.ai/][Ollama running locally]]     |
-| Llama.cpp          | [[https://github.com/ggerganov/llama.cpp/tree/master/examples/server#quick-start][Llama.cpp running locally]]  |
-| Llamafile          | [[https://github.com/Mozilla-Ocho/llamafile#quickstart][Local Llamafile server]]     |
-| GPT4All            | [[https://gpt4all.io/index.html][GPT4All running locally]]    |
-| Kagi FastGPT       | [[https://kagi.com/settings?p=api][API key]]                    |
-| Kagi Summarizer    | [[https://kagi.com/settings?p=api][API key]]                    |
-| Azure              | Deployment and API key     |
-| Groq               | [[https://console.groq.com/keys][API key]]                    |
-| Perplexity         | [[https://docs.perplexity.ai/docs/getting-started][API key]]                    |
-| OpenRouter         | [[https://openrouter.ai/keys][API key]]                    |
-| together.ai        | [[https://api.together.xyz/settings/api-keys][API key]]                    |
-| Anyscale           | [[https://docs.endpoints.anyscale.com/][API key]]                    |
-| PrivateGPT         | [[https://github.com/zylon-ai/private-gpt#-documentation][PrivateGPT running locally]] |
-| DeepSeek           | [[https://platform.deepseek.com/api_keys][API key]]                    |
-| Cerebras           | [[https://cloud.cerebras.ai/][API key]]                    |
-| Github Models      | [[https://github.com/settings/tokens][Token]]                      |
-| Novita AI          | [[https://novita.ai/model-api/product/llm-api?utm_source=github_gptel&utm_medium=github_readme&utm_campaign=link][Token]]                      |
-| xAI                | [[https://console.x.ai?utm_source=github_gptel&utm_medium=github_readme&utm_campaign=link][API key]]                    |
-#+html: </div>
-
 ** Basic concepts
 
 #+cindex: Large Language Model
@@ -218,7 +189,11 @@ some extra niceties for chat interaction.
 
 ** Chat persistence
 
-** The rewrite interface
+** TODO The rewrite interface
+
+** TODO gptel in Org mode
+
+gptel offers a few extra conveniences in Org mode.
 
 * TODO gptel's design
 
@@ -828,9 +803,12 @@ To use tools in gptel, you need
   currently include any tool specifications out of the box.
 
 *** Obtaining tools
-*** Writing tools
+*** TODO Writing tools
 :PROPERTIES:
 :CUSTOM_ID: writing-tools
+:LAST_REVIEW: [2025-09-12 Fri]
+:NEXT_REVIEW: [2025-09-12 Fri]
+:REVIEWS:  0
 :END:
 
 A gptel tool is a structure specifying an Elisp function, the format
@@ -903,6 +881,43 @@ arguments.
   subsequent requests in the same buffer.  This is primarily useful
   in chat buffers.
 
+For example, to not prompt for user confirmation when creating files
+in the current working directory but in all other directories:
+
+#+begin_src emacs-lisp
+(gptel-make-tool
+ :name \"create_file\"
+ :description \"Create a new file with the specified content\"
+ :confirm  (lambda (&rest args)
+             (cl-destructuring-bind (path filename content)
+                 args
+               (not (my-filepath-within-current-directory-p path))))
+ :function (lambda (path filename content)
+             (let ((full-path (expand-file-name filename path)))
+               (with-temp-buffer
+                 (insert content)
+                 (write-file full-path))
+               (format \"Created file %s in %s\" filename path)))
+ :args (list '(:name \"path\"
+  	             :type string
+  	             :description \"The directory where to create the file\")
+             '(:name \"filename\"
+  	             :type string
+  	             :description \"The name of the file to create\")
+             '(:name \"content\"
+  	             :type string
+  	             :description \"The content to write to the file\"))
+ :category \"filesystem\")
+
+(defun my-filepath-within-current-directory-p (filepath)
+  \"Return t if FILEPATH is within the current working directory or its subdirectories.
+  FILEPATH can be relative or absolute, and may or may not end in a slash.\"
+  (let* ((current-dir-truename (file-truename (file-name-as-directory default-directory)))
+         (filepath-truename (file-truename (expand-file-name filepath)))
+         (filepath-dir-truename (file-name-as-directory (file-name-directory filepath-truename))))
+    (string-prefix-p current-dir-truename filepath-dir-truename)))
+#+end_src
+
 **** Specifying tool arguments
 
 Tool arguments are specified in an Elisp format that mirrors the JSON
@@ -2041,13 +2056,87 @@ This is a sentence that will be filled in later.
 :REVIEWS:  0
 :END:
 
-gptel is really the combination of two libraries: the request API and the =gptel= UI.  gptel's opinionated UI -- the chat buffer, the transient menus, the presentation of tool calls and so on -- comprise one way of using gptel, but it is certainly not the only one.
+gptel is really the combination of two libraries: the request API and
+the =gptel= UI.  For convenience both are made available in a single
+Emacs package.  gptel's opinionated UI -- the chat buffer, the
+transient menus, the presentation of tool calls and so on -- comprise
+one way of using gptel, but it is certainly not the only one.
+
+Accordingly, this cookbook has two sections.  [[*Extending gptel's UI]]
+describes how to customize gptel's UIs beyond simply setting user
+options, and [[*Building applications with ~gptel-request~]] covers the
+use of gptel's API for specialized LLM interactions.
+
+** TODO Extending gptel's UI
+
+*** Improving the chat buffer experience
+
+A "chat buffer" is any text, Markdown or Org mode buffer where
+~gptel-mode~ is turned on.
+
+**** Resume chat sessions more robustly
+
+ gptel adds metadata to a chat buffer when saving it to a file.  Among
+other information, this metadata includes the model, backend and tools
+in use, as well as the response boundaries.  When opening this file,
+~gptel-mode~ is not automatically enabled, so modifying the buffer can
+cause the recorded response boundaries to go out of sync.
+
+~gptel-mode~ can be automatically enabled on opening the file by
+adding a [[info:emacs#Specifying File Variables][property-line]] at the top of the file, like
+
+#+begin_org
+# -*- eval: (gptel-mode 1) -*-
+#+end_org
+
+We can get gptel to include this line automatically as follows:
+
+#+begin_src emacs-lisp
+(defun gptel-mode-auto-enable ()
+  "Ensure that this file opens with `gptel-mode' enabled."
+  (save-excursion
+    (let ((enable-local-variables t))  ; Ensure we can modify local variables
+      (if (and (save-excursion
+                 (goto-char (point-min))
+                 (looking-at ".*-\\*-")))  ; If there's a -*- line
+        ;; First remove any existing eval, then add the new one
+        (modify-file-local-variable-prop-line
+          'eval nil 'delete))
+      ;; Always add our eval
+      (add-file-local-variable-prop-line
+        'eval '(and (fboundp 'gptel-mode) (gptel-mode 1))))))
+
+(add-hook 'gptel-save-state-hook #'gptel-mode-auto-enable)
+#+end_src
+
+Note that this will overwrite any other =eval= local variable
+specification already present on the line.
+
+**** Automatically persist chats to disk
+
+*** Extending gptel's Transient menus
+
+** TODO Building applications with ~gptel-request~
+
+The entry point to the request library is the ~gptel-request~
+function, which presents a unified way to interact with any LLM that
+gptel supports.  It can be used as a building block for custom
+commands that live in your configuration, for custom workflows, or
+even to build complex packages.
+
+If you intend to use ~gptel-request~ to write specialized LLM
+interaction commands or build a different UI, you can require only the
+=gptel-request= feature:
+
+#+begin_src emacs-lisp
+(require 'gptel-request)
+#+end_src 
 
-The entry point to the request library is the ~gptel-request~ function, which presents a unified way to interact with any LLM that gptel supports.  It can be used as a building block for custom commands that live in your configuration, custom workflows, or even to build complex packages.
+This way you avoid loading unnecessary code, such as gptel's chat buffer UI or Transient menus.
 
 By way of examples, this chapter describes how to do these things with ~gptel-request~.
 
-** Simple ~gptel-request~ commands
+*** Simple ~gptel-request~ commands
 
 gptel provides gptel-request, a lower level function, to query ChatGPT with custom behavior.  It accepts a prompt to send to the the active ~gptel-model~, along with several keyword arguments that modify what will be sent and how the response will be handled:
 
@@ -2096,7 +2185,7 @@ It is not recommended to grab the buffer contents as a string, as this will caus
 
 We can now write our first (admittedly useless) custom command: 
 
-** Building an application
+*** Building an application
 
 #+INCLUDE: ../README.org::*FAQ :minlevel 1
 #+INCLUDE: ../README.org::*Alternatives :minlevel 1