llm-tools.el

llm-tools.el (17835B)

---

 ;; llm-tools.el --- Opinionated tools for use by an LLM  -*- lexical-binding: t; -*-
 
 ;; Copyright (C) 2026 Vineet K
 
 ;; Author: Vineet K <git@vineetk.net>
 ;; Version: 1.0
 ;; Keywords: llm, gptel
 ;; Package-Requires: ((emacs "28.1") (gptel "0.9.6") (magit "3.3.0"))
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
 ;; the Free Software Foundation, either version 3 of the License, or
 ;; (at your option) any later version.
 
 ;; This program is distributed in the hope that it will be useful,
 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 ;; GNU General Public License for more details.
 
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
 
 ;; This package provides a set of opinionated tools for use by an LLM via GPTel.
 ;; It includes tools for file operations, web search, and bash execution.
 
 ;;; Code:
 
 (require 'cl-lib)
 (require 'magit)
 
 (defgroup llm-tools nil
   "Opinionated tools for use by an LLM."
   :group 'convenience)
 
 (require 'llm-tools-hl)
 (require 'llm-tools-web)
 
 ;; read_file (hl-file-read)
 (gptel-make-tool
  :name "read_file"
  :function (lambda (file beg end only-anchors? as-list?)
 	     (json-encode-string (llm-tools--hl-file-read
 				  file beg end only-anchors? as-list?)))
  :description "\
 Read a file (or a range of lines) and return its contents in hashline
 format. Each line is represented as LINE_NUMBER HASH|CONTENT, where
 LINE_NUMBER is the 1-based line number, HASH is a 2-character
 content-derived bigram, and CONTENT is the verbatim line text. Example
 output:
 
 1aa|const char *TITLE = \"Mr\";
 2ab|void greet(char *name) {
 3cd|	return name;
 
 The LINE_NUMBER and HASH together form an anchor (e.g., 1aa, 2ab) that
 uniquely identifies a line by position and content. Copy anchors
 verbatim from the output when referencing lines in edit operations. Do
 not fabricate or modify hashes. Call this tool before editing any file
 to obtain current content and valid anchors. Re-call if anchors no
 longer match after external changes.
 
 Use optional BEG and END arguments to read only a specific range of
 lines (1-based, inclusive). Use ONLY_ANCHORS to retrieve just the line
 anchors without content. Use AS_LIST to receive output as a list rather
 than a newline-delimited string."
  :args '((:name "file"
 		:type string
 		:description "\
 Path to the file to read, relative to the working directory.")
 	 (:name "beg"
 		:type integer
 		:description "\
 Optional 1-based line number (inclusive) to start reading from. Omit to
 read from the beginning."
 		:optional t)
 	 (:name "end"
 		:type integer
 		:description "\
 Optional 1-based line number (inclusive) to stop reading at. Omit to
 read to the end."
 		:optional t)
 	 (:name "only_anchors"
 		:type boolean
 		:description "\
 Optional boolean. When true, returns only the anchor (line number +
 hash) without the content portion after the pipe."
 		:optional t)
 	 (:name "as_list"
 		:type boolean
 		:description "\
 Optional boolean. When true, returns each hashline as a list element
 instead of a single newline-delimited string."
 		:optional t))
  :async nil
  :confirm nil
  :include t)
 
 ;; write_file (write-region)
 (gptel-make-tool
  :name "write_file"
  :function (lambda (file contents)
 	     (write-region contents nil file))
  :description "\
 Overwrite an entire file with new contents. This is a destructive
 operation that replaces all existing content. Use this tool for:
 
 - Creating new files from scratch
 - Completely replacing small files where the new content is the
   intended final state
 - Writing generated output, configuration files, or test fixtures
 
 Do NOT use this for partial edits, appending, or modifying existing
 files. Use `edit_file` instead for surgical changes to existing
 content. Always call `read_file` first if the file already exists to
 preserve content you intend to keep. This tool requires user
 confirmation before executing."
  :args '((:name "file"
 		:type string
 		:description "Path to the file to write to, relative to the working directory.")
 	 (:name "contents"
 		:type string
 		:description "\
 Full file contents to write. This will replace all existing
 content. Include newlines and indentation as they should appear in the
 final file."))
  :async nil
  :confirm t
  :include t)
 
 ;; edit_file (hl-edit)
 (gptel-make-tool
  :name "edit_file"
  :function #'llm-tools--hl-edit
  :description "\
 Edit an existing file surgically using the hashline patch
 format. Call `read_file` first to obtain current content and valid
 line anchors. Use `write_file` instead for creating new files or
 completely replacing content. Returns a success message if the patch
 applied, or an error string describing what went wrong (structural
 issues or stale anchors)."
  :args '((:name "patch"
 		:type string
 		:description "\
 A hashline patch string containing one or more file sections. Each
 section begins with `@@ PATH` on its own line, followed by operations
 that reference lines by their anchor (line number + 2-character hash,
 e.g. `5ff`). Copy anchors verbatim from `read_file` output; never
 fabricate or modify them.
 
 CRITICAL: This is NOT a unified diff. Do NOT use `---`, `+++`, `@@ -1,3
 +1,4 @@`, `-old`, `+new`, or any unified diff syntax. The header is
 `@@ PATH`; operations use `<`, `+`, `-`, `=`. This format is purely
 textual -- the tool has NO awareness of language, indentation,
 brackets, fences, or table widths. You must emit valid syntax in
 replacements and insertions.
 
 Operations:
   + ANCHOR    Insert lines AFTER the anchored line (or `EOF` to append)
   < ANCHOR    Insert lines BEFORE the anchored line (or `BOF` to prepend)
   - A..B      Delete the inclusive line range A through B
   = A..B      Replace the inclusive range A through B with payload lines
 
 Payload lines follow the operation line and must start with `~`
 immediately followed by content -- no space after `~`. Every character
 after `~` is verbatim file content. Op lines carry no content:
 
 WRONG: + 5pg some code
 RIGHT:
 + 5pg
 ~some code
 
 One operation can have many payload lines. To insert N consecutive
 lines, write ONE op followed by N `~` lines:
 
 WRONG (one op per line, with fabricated anchors):
   + 5pg
   ~first new line
   + 6xx     <- FABRICATED
   ~second new line
 
 RIGHT (one op, many payload lines):
   + 5pg
   ~first new line
   ~second new line
 
 Rules:
 - Payload is ONLY what is NEW relative to your range. Do not repeat
   existing lines or duplicate nearby content.
 - Anchors reference the file as last read via `read_file`. Do not shift
   line numbers for prior operations in the same patch.
 - Prefer narrow operations (`+`, `-`) over wide replacements (`=`).
   Two narrow ops beat one wide `=`.
 - When editing a multiline construct, widen to the whole construct
   rather than bisecting it.
 - `= A..B` deletes the range; payload is what is written. Before using
   `=`, mentally delete A..B. If that splits an unclosed brace or
   orphans a closer, you are bisecting a construct -- widen the range.
 - Every payload line must start with `~`. Raw content without `~` is
   invalid.
 - Comments (lines starting with `#`) and blank lines are ignored.
 
 Examples:
 
 Replace a single line:
 @@ greeting.el
 = 2in..2in
 ~(defconst greeting-title \"Mrs\")
 
 Replace a multiline block (widen to self-contained boundary):
 @@ greeting.el
 = 4ei..7be
 ~  (concat
 ~    greeting-title
 ~    (or (string-trim name) \"guest\"))
 ~  )
 
 Insert after:
 @@ greeting.el
 + 4ei
 ~    greeting-title
 
 Insert before:
 @@ greeting.el
 < 5ff
 ~    greeting-title
 
 Append to end of file:
 @@ greeting.el
 + EOF
 ~(provide 'greeting)
 
 Prepend to beginning of file:
 @@ greeting.el
 < BOF
 ~;; greeting.el -- utilities
 
 Delete a single line:
 @@ greeting.el
 - 5ff..5ff
 
 Blank a line (replace with empty):
 @@ greeting.el
 = 5ff..5ff
 
 Multiple operations in one section:
 @@ greeting.el
 + 1vx
 ~(defconst DEBUG nil)
 - 5ff..5ff
 
 Multiple files in one patch:
 @@ a.el
 + 1vx
 ~(require 'b)
 @@ b.el
 = 2in..2in
 ~(defconst VALUE 42)
 
 Insert multiple lines with one op:
 @@ greeting.el
 + 1vx
 ~(defconst GREETING \"Hello\")
 ~(defconst FAREWELL \"Goodbye\")
 
 Replace one line with multiple lines:
 @@ greeting.el
 = 1vx..1vx
 ~(defconst TITLE \"Dr\")
 ~(defconst SUBTITLE \"Assistant\")"))
  :async nil
  :confirm t
  :include t)
 
 ;; bash (make-process, taken from gptel-agent)
 (defun llm-tools--execute-bash (callback command)
   "Execute COMMAND asynchronously in bash and call CALLBACK with output.
 
 CALLBACK is called with the command output string when the process finishes.
 COMMAND is the bash command string to execute."
   (let* ((output-buffer (generate-new-buffer " *llm-tools-bash*"))
          (proc (make-process
                 :name "llm-tools-bash"
                 :buffer output-buffer
                 :command (list "bash" "-c" command)
                 :connection-type 'pipe
                 :sentinel
                 (lambda (process _event)
                   (when (memq (process-status process) '(exit signal))
                     (let* ((exit-code (process-exit-status process))
                            (output (with-current-buffer (process-buffer process)
 				     (buffer-string))))
 		      (kill-buffer (process-buffer process))
 		      (funcall callback
 			       (if (zerop exit-code)
                                    output
                                  (format "Command failed with exit code %d:\nSTDOUT+STDERR:\n%s"
                                          exit-code output)))))))))
     proc))
 
 (defun llm-tools--bash-confirm-p (command)
     (let ((destructive
          '("\\brm\\b"
            "\\bdd\\b"
            "\\bshred\\b"
            "\\btruncate\\b"
            "\\bmkfs\\b"
            "\\bsudo\\b"
            "\\bdoas\\b"
 	   "[^>]>[^>&0-9]" ; any singular > that isn't >> nor file-descriptor redirect
 	   "\\$("
 	   "`"
            "|[ \t]*\\bsh\\b"
            "|[ \t]*\\bbash\\b")))
     (cl-some (lambda (regexp)
 	       (string-match-p regexp command))
 	     destructive)))
 
 (gptel-make-tool
  :name "bash"
  :function #'llm-tools--execute-bash
  :description "Execute Bash commands.
 
 This tool provides access to a Bash shell with GNU coreutils (or
 equivalents) available. Use this to inspect system state, run builds,
 tests or other development or system administration tasks.
 
 Use the dedicated tools for file operations, searching, and code
 navigation instead of shell commands.
 
 - For file contents: use `read_file` or `web_fetch`
 - For file discovery/metadata: use `find_files`
 - For searching text in files: use `grep`
 - For editing files: use `edit_file` or `write_file`
 
 Bash should be a last resort, used only when no other tool fits the task.
 
 - Quote file paths with spaces using double quotes.
 - Chain dependent commands with && (or ; if failures are OK)
 - Use absolute paths instead of cd when possible
 - For parallel commands, make multiple `bash` calls in one message
 - Run tests, check your work or otherwise close the loop to verify changes you make.
 
 EXAMPLES:
 - Check file type: 'file document.pdf'
 - Count lines: 'wc -l *.txt'
 
 The command will be executed in the current working directory. Output is
 returned as a string. Long outputs should be filtered/limited using pipes."
  :args '((:name "command"
 		:type string
 		:description "The Bash command to execute.\
 Can include pipes and standard shell operators.
 Example: 'ls -la | head -20' or 'grep -i error app.log | tail -50'"))
  :confirm #'llm-tools--bash-confirm-p
  :include t
  :async t)
 
 ;; find_files (directory-files-recursively)
 (gptel-make-tool
  :name "find_files"
  :function (lambda (dir &optional regexp)
 	     (let ((git-dir (concat (file-name-as-directory dir) ".git")))
 	       (delq nil (mapcar (lambda (f)
 				   (unless (string-prefix-p git-dir f) f))
 				 (directory-files-recursively dir (or regexp ""))))))
  :description "\
 Recursively find all files in a given directory, excluding files within
 .git directories. Returns a list of absolute file paths. Optionally
 accepts a pattern to filter file names (e.g., '*.el' for Emacs Lisp
 files). Use this to discover files in a project directory before reading
 or editing them."
  :args '((:name "directory"
 		:type string
 		:description "Path to the directory to be read, relative to the working directory.")
 	 (:name "regexp"
 		:type string
 		:description "Optional regular expression pattern to search for, uses extended regex syntax."
 		:optional t))
  :async nil
  :confirm nil
  :include t)
 
 ;; grep (just grep (or git grep) :D)
 (defun llm-tools--grep (regexp &optional glob path)
   (with-temp-buffer
     (if (magit-gitdir)
 	(let ((pathspec (cond
 			 ((and path glob)
 			  (concat (directory-file-name path) "/" glob))
 			 (glob glob)
 			 (path path)
 			 (t "."))))
 	  (call-process "git" nil t nil
 			"grep" "-rnEH"
 			regexp "--" pathspec))
       (apply #'call-process
 	     (append
 	      '("grep" nil t nil)
 	      (delq nil
 		    `("-rnEH"
 		      ,(if glob (concat "--include=" glob))
 		      ,regexp
 		      ,(or path "."))))))
     (buffer-string)))
 
 (gptel-make-tool
  :name "grep"
  :function (lambda (regexp &optional glob path)
 	     (llm-tools--grep regexp glob path))
  :description "\
 Recursively search for lines matching a regexp pattern in files under a
 given path. Uses `git grep` when inside a Git repository, otherwise falls
 back to GNU grep. Both are invoked with flags -rnEH (recursive, line
 numbers, extended regexp, always show filename). When using `git grep`,
 only tracked files are searched. Returns raw output with one match per
 line in the format FILE:LINE:CONTENT. Use this tool to find code
 patterns, locate function definitions, search for strings, or identify
 files containing specific text before reading them. For simple file name
 discovery, use `find_files` instead. For reading file contents, use
 `read_file`. The path argument is relative to the working directory;
 omit it to search from the current directory."
  :args '((:name "regexp"
 		:type string
 		:description "\
 Regular expression pattern to search for. Uses GNU grep extended syntax.")
 	 (:name "glob"
 		:type string
 		:description "\
 Optional restricts search to files matching the glob
 pattern. (e.g. \"*.el\", \"*.org\", \"*.c\")"
 		:optional t)
 	 (:name "path"
 		:type string
 		:description "\
 Optional file or directory path to search within, relative to the
 working directory. Defaults to current directory if omitted."
 		:optional t))
  :async nil
  :confirm nil
  :include t)
 
 ;; web_search (taken wholesale from gptel-agent)
 (gptel-make-tool
  :name "web_search"
  :function #'llm-tools--web-search-eww
  :description "Search the web for the first five results to a query.  The query can be an arbitrary string.  Returns the top five results from the search engine as a list of plists.  Each object has the keys `:url` and `:excerpt` for the corresponding search result.
 
 This tool uses the Emacs web browser (eww) with its default search engine to perform searches. No API key is required.
 
 If required, consider using the url as the input to the `Read` tool to get the contents of the url.  Note that this might not work as the `Read` tool does not handle javascript-enabled pages."
  :args '((:name "query"
                 :type string
                 :description "The natural language search query, can be multiple words.")
          (:name "count"
                 :type integer
                 :description "Number of results to return (default 5)"
                 :optional t))
  :include t
  :async t
  :confirm nil)
 
 ;; fetch_url (use gptel-agent's one as a base, but adds mime handling like PDFs and images)
 ; TODO add mime handling for documents and images
 (gptel-make-tool
  :name "web_fetch"
  :function #'llm-tools--read-url
  :description "Fetch and read the contents of a URL.
 
 - Returns the text of the URL (not HTML) formatted for reading.
 - Request times out after 30 seconds."
  :args '(( :name "url"
            :type string
            :description "The URL to read"))
  :async t
  :confirm nil
  :include t)
 
 ;;;; Preview Functions
 (defun llm-tools--preview-teardown (ov)
   "Delete region covered by overlay OV and remove the overlay."
   (when (overlayp ov)
     (with-current-buffer (overlay-buffer ov)
       (let ((inhibit-read-only t))
         (delete-region (overlay-start ov) (overlay-end ov)))
       (delete-overlay ov))))
 
 (defun llm-tools--make-preview-setup (formatter)
   "Return a preview setup function that calls FORMATTER with ARG-VALUES.
 FORMATTER is a function (ARG-VALUES) that inserts the preview text."
   (lambda (arg-values _info)
     (let ((from (point)))
       (funcall formatter arg-values)
       (make-overlay from (point)))))
 
 (defun llm-tools--format-bash-preview (arg-values)
   (let ((command (car arg-values)))
     (insert "("
             (propertize "bash" 'font-lock-face 'font-lock-keyword-face)
             " " command ")\n")))
 
 (defun llm-tools--format-edit-file-preview (arg-values)
   (let ((patch (car arg-values)))
     (insert "("
             (propertize "edit_file" 'font-lock-face 'font-lock-keyword-face)
             ")\n" patch "\n")))
 
 (defun llm-tools--format-write-file-preview (arg-values)
   (let ((file (car arg-values))
         (contents (cadr arg-values)))
     (insert "("
             (propertize "write_file" 'font-lock-face 'font-lock-keyword-face)
             " " (prin1-to-string file) ")\n" contents "\n")))
 
 (dolist (tool '(("bash" llm-tools--format-bash-preview)
                 ("edit_file" llm-tools--format-edit-file-preview)
                 ("write_file" llm-tools--format-write-file-preview)))
   (setf (alist-get (car tool)
 		   gptel--tool-preview-alist
 		   nil
 		   nil
 		   #'equal)
         (list (llm-tools--make-preview-setup (cadr tool))
 	      #'llm-tools--preview-teardown)))
 
 (provide 'llm-tools)