From 5c39f9348d0a1dc56c30cbb0f0dbf84146ef06fc Mon Sep 17 00:00:00 2001
From: Phil Bajsicki <phil@bajsicki.com>
Date: Tue, 15 Apr 2025 23:34:46 +0200
Subject: [PATCH] Add usage, minor fixes
---
README.org | 39 ++++++++++++++++++++++++++++++++++-----
gptel-org-tools.el | 42 +-----------------------------------------
2 files changed, 35 insertions(+), 46 deletions(-)
diff --git a/README.org b/README.org
index 25a3680..1e87390 100644
--- a/README.org
+++ b/README.org
@@ -77,6 +77,34 @@ I change models a lot, and this /just works/ for most models, even if some aren'
#+end_src
With that out of the way, let's get to the tools.
+* Usage options:
+I only use Doom Emacs, so here's how I do it.
+
+packages.el:
+#+begin_src elisp :tangle no
+(package! gptel-org-tools
+ :recipe (:host nil
+ :repo "https://git.bajsicki.com/phil/gptel-org-tools"))
+#+end_src
+
+config.el:
+#+begin_src elisp :tangle no
+(require 'gptel-org-tools)
+(setq gptel-tools gptel-org-tools)
+#+end_src
+
+This /will/ overwrite any other tools you have defined before this call takes place.
+
+If you want to just append them to your existing tool list:
+
+config.el:
+#+begin_src elisp :tangle no
+(require 'gptel-org-tools)
+(mapcar (lambda (tool) (cl-pushnew tool gptel-tools)) gptel-org-tools)
+#+end_src
+
+
+
* Code
** Preamble
:PROPERTIES:
@@ -158,7 +186,7 @@ Highly not recommended, but sometimes an LLM can pull a rabbit out of pure entro
**** list-buffers
I wanted the assistant to have an easier time finding my files and buffers, and this has proven to be a great choice. I have yet to manage to get rid of the =:args=, but having them optional/ do nothing works well enough.
-The rationale behind using ~ibuffer~ is the same as with dired. They both display a lot of data, densely. So instead of trying to use some workaround with ~buffer-file-name~ or other functions, I'd rather just grab a 'text capture' of the same UI I'm looking at, and call it a day.
+The rationale behind using ~list-buffers~ is the same as with dired. They both display a lot of data, densely. So instead of trying to use some workaround with ~buffer-file-name~ or other functions, I'd rather just grab a 'text capture' of the same UI I'm looking at, and call it a day.
Seems to be one of the most reliable tools in the basket... mostly because
#+begin_src elisp
@@ -166,7 +194,7 @@ Seems to be one of the most reliable tools in the basket... mostly because
(gptel-make-tool
:function (lambda (arg)
(with-temp-buffer
- (ibuffer)
+ (list-buffers)
(let ((content (buffer-string)))
(kill-buffer (current-buffer))
content)))
@@ -237,7 +265,7 @@ Continuation from above. Open a file into a buffer for processing, once it's fou
**** read-file-contents
This reads file contents,
-#+begin_src elisp
+#+begin_src elisp :tangle no
(add-to-list 'gptel-org-tools
(gptel-make-tool
:function (lambda (filename)
@@ -249,7 +277,8 @@ This reads file contents,
:args (list '(:name "filename"
:type string
:description "The filename to read."))
- :category "org-mode"))
+ :category "org-mode"
+ :confirm t))
#+end_src
**** describe-variable
#+begin_src elisp
@@ -379,7 +408,7 @@ Currently *not* tangled, as I'm testing breaking out each type of query into its
#+end_comment
-#+begin_src elisp
+#+begin_src elisp :tangle no
(defun gptel-org-tools--org-ql-select (buf query)
(org-ql-select
(get-buffer buf)
diff --git a/gptel-org-tools.el b/gptel-org-tools.el
index 704a59d..8dc6db8 100644
--- a/gptel-org-tools.el
+++ b/gptel-org-tools.el
@@ -40,7 +40,7 @@
(gptel-make-tool
:function (lambda (arg)
(with-temp-buffer
- (ibuffer)
+ (list-buffers)
(let ((content (buffer-string)))
(kill-buffer (current-buffer))
content)))
@@ -92,19 +92,6 @@
:description "Path to file.."))
:category "filesystem"))
-(add-to-list 'gptel-org-tools
- (gptel-make-tool
- :function (lambda (filename)
- (with-temp-buffer
- (insert-file-contents (expand-file-name filename))
- (buffer-string)))
- :name "read-file-contents"
- :description "Read and return the contents of a specified file."
- :args (list '(:name "filename"
- :type string
- :description "The filename to read."))
- :category "org-mode"))
-
(add-to-list 'gptel-org-tools
(gptel-make-tool
:function (lambda (var)
@@ -175,33 +162,6 @@
:description "The Org buffer to extract headings from."))
:category "org-mode"))
-(defun gptel-org-tools--org-ql-select (buf query)
- (org-ql-select
- (get-buffer buf)
- (if (stringp query)
- (read query)
- query)
- :action #'(lambda ()
- (concat
- (buffer-substring-no-properties
- (line-beginning-position)
- (progn
- (outline-next-heading)
- (line-beginning-position)))))))
-
-(add-to-list 'gptel-org-tools
- (gptel-make-tool
- :function #'gptel-org-tools--org-ql-select
- :name "org-ql-select"
- :description "Run org-ql-select against buffer with query. Using filename fails."
- :args (list '(:name "buffer"
- :type string
- :description "The name of the buffer. Can be multiple buffers. See the NAME column in `emacs-list-buffers`.")
- '(:name "query"
- :type string
- :description "The query to pass into org-ql-select. See org-ql documentation for syntax. Usually `(tags \"tag1\" \"tag2\")` is sufficient. Possible predicates: `tags` (finds both local and inherited tags), `tags-local` (finds only local tags), `rifle` (matches against both heading and body text). This is a sexp, not a string."))
- :category "org"))
-
(defun gptel-org-tools--org-ql-select-dates (buf date)
(org-ql-select
(get-buffer buf)