diff --git a/README.org b/README.org
index cf50767..2cd5599 100644
--- a/README.org
+++ b/README.org
@@ -249,6 +249,7 @@ The rationale behind using ~list-buffers~ is the same as with dired. They both d
Seems to be one of the most reliable tools in the basket... mostly because
#+begin_src elisp
(defun gptel-org-tool--list-buffers (&optional arg)
+ "Return list of buffers."
(list-buffers-noselect)
(with-current-buffer "*Buffer List*"
(let ((content (buffer-string)))
@@ -277,6 +278,7 @@ Be sure to customize the function to point to your org directory, if you wish. I
#+begin_src elisp
(defun gptel-org-tools--dir (dir)
+ "Return directory listing."
(with-temp-buffer
(dired (or dir "~"))
(let ((content (buffer-string)))
@@ -299,6 +301,7 @@ Be sure to customize the function to point to your org directory, if you wish. I
Disabled for now, as it's causing some issues.
#+begin_src elisp :tangle no :results none
(defun gptel-org-tools--find-buffer-visiting (filename)
+ "Return the buffer visiting file FILENAME."
(concat
(bufferp
(find-buffer-visiting
@@ -319,6 +322,7 @@ Disabled for now, as it's causing some issues.
Continuation from above. Open a file into a buffer for processing, once it's found by dired-list.
#+begin_src elisp
(defun gptel-org-tools--open-file-inactive (file)
+ "Open FILE in a buffer."
(with-current-buffer (get-buffer-create file)
(insert-file-contents file)
(concat
@@ -338,6 +342,7 @@ Continuation from above. Open a file into a buffer for processing, once it's fou
This reads file contents,
#+begin_src elisp :tangle no
(defun gptel-org-tools--read-file-contents (file)
+ "Return contents of FILE."
(with-temp-buffer
(insert-file-contents (expand-file-name filename))
(concat
@@ -358,6 +363,7 @@ This reads file contents,
**** describe-variable
#+begin_src elisp
(defun gptel-org-tools--describe-variable (var)
+ "Return documentation for VAR."
(let ((symbol (intern var)))
(if (boundp symbol)
(prin1-to-string (symbol-value symbol))
@@ -377,6 +383,7 @@ This reads file contents,
**** describe-function
#+begin_src elisp
(defun gptel-org-tools--describe-function (fun)
+ "Return documentation for FUN."
(let ((symbol (intern fun)))
(if (fboundp symbol)
(prin1-to-string (documentation symbol 'function))
@@ -425,6 +432,7 @@ Pretty simple, does what it says on the tin. It gets all the tags from the =buff
This is not, by any means, sufficient, but I do tag people and specific events frequently enough that it helps save on the context window.
#+begin_src elisp
(defun gptel-org-tools--org-extract-tags (buffer)
+ "Return all tags from BUFFER."
(with-current-buffer buffer
(let ((tags '()))
(org-map-entries
@@ -454,6 +462,7 @@ Then we need to pull /some/ information from the buffer, without dragging the en
Therefore, headings. A reasonable amount of information, and still keeping the signal-to-noise ratio pretty decent.
#+begin_src elisp
(defun gptel-org-tools--org-extract-headings (buffer)
+ "Return all headings from BUFFER."
(if (member buffer gptel-org-tools-skip-heading-extraction)
(user-error "Buffer %s has too many headings, use org-extract-tags or org-ql-select-rifle." buffer)
(with-current-buffer buffer
@@ -489,6 +498,9 @@ Currently *not* tangled, as I'm testing breaking out each type of query into its
#+begin_src elisp :tangle no
(defun gptel-org-tools--org-ql-select (buf query)
+ "Return entries matching QUERY from BUFFER.
+
+QUERY can be any valid org-ql-select query."
(org-ql-select
(get-buffer buf)
(if (stringp query)
@@ -566,6 +578,11 @@ DATE is the date or date range to match."
Original (works but not ideal).
#+begin_src elisp :tangle no
(defun gptel-org-tools--org-ql-select-by-date (buf date)
+ "Return headings from BUFFER matching DATE.
+
+DATE must be in the form of YYYY, YYYY-MM, or YYYY-MM-DD."
+
+
(org-ql-select
(get-buffer buf)
`(heading ,date)
@@ -591,6 +608,7 @@ This is still work in progress, the idea is to have the LLM check my calendar an
It works, in principle, but I haven't been able to find a use for it yet. The real challenge is in building a context where the tools integrate with each-other in a way that makes sense. For now, this exists.
#+begin_src elisp
(defun gptel-org-tools--org-agenda-seek (days)
+ "Return the results of org-agenda-list spanning now to DAYS."
(with-temp-buffer
(org-agenda-list (or days 14))
(let ((content (buffer-string)))
@@ -616,6 +634,7 @@ The following tools are still very much WIP, and I think they're self-explanator
Retrieve the headings where the heading matches query..
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-headings (buf query)
+ "Return headings matching QUERY from BUFFER."
(org-ql-select
(get-buffer buf)
`(heading ,query)
@@ -640,6 +659,7 @@ Retrieve the headings where the heading matches query..
Retrieve all the headings where either heading or content matches query.
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-headings-rifle (buf query)
+ "Return headings of entries (body included) that match keyword QUERY from BUFFER."
(org-ql-select
(get-buffer buf)
`(rifle ,query)
@@ -664,6 +684,7 @@ Retrieve all the headings where either heading or content matches query.
This pulls all the headings (and their contents) when they match tags (without inheritance.)
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-tags-local (buf query)
+ "Return entries whose tags match QUERY in BUFFER, without inheritance."
(org-ql-select
(get-buffer buf)
`(tags-local ,query)
@@ -688,6 +709,7 @@ This pulls all the headings (and their contents) when they match tags (without i
This pulls all the local tags (without inheritance) from buffer, and returns the number of these tagged headings.
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-tags-local-count (buf query)
+ "Return count of entries tagged QUERY in BUFFER."
(length (org-ql-select
(get-buffer buf)
`(tags-local ,query)
@@ -712,6 +734,7 @@ This pulls all the local tags (without inheritance) from buffer, and returns the
This pulls all the headings (and their contents) when they match tags (with inheritance; if a parent entry has the tag, descendant entries do, too.)
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-tags (buf query)
+ "Return every entry tagged QUERY from BUFFER."
(org-ql-select
(get-buffer buf)
`(tags ,query)
@@ -735,6 +758,7 @@ This pulls all the headings (and their contents) when they match tags (with inhe
And, the "grab everything that matches" tool.
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-rifle (buf query)
+ "Return every entry matching keyword QUERY from BUFFER."
(let ((buffer (get-buffer buf)))
(if buffer
(org-ql-select
@@ -761,6 +785,8 @@ And, the "grab everything that matches" tool.
This pulls all the headings (and their contents) when they match tags (without inheritance.)
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-all-tags-local (query)
+ "Return entries whose tags match QUERY in org-agenda-files.
+ QUERY is the tag to search for."
(org-ql-select
(org-agenda-files)
`(tags-local ,query)
@@ -782,6 +808,9 @@ This pulls all the headings (and their contents) when they match tags (without i
This pulls all the headings (and their contents) when they match tags (with inheritance; if a parent entry has the tag, descendant entries do, too.)
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-all-tags (query)
+ "Return entries whose tags match QUERY,
+with inheritance, in org-agenda-files.
+ QUERY is the tag to search for."
(org-ql-select
(org-agenda-files)
`(tags ,query)
@@ -811,6 +840,8 @@ This means that /every org-mode file I have/ is part of this search.
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-all-rifle (query)
+ "Return entries containing QUERY from org-agenda-files.
+ QUERY is the keyword to search for."
(org-ql-select
(org-agenda-files)
`(rifle ,query)
@@ -831,11 +862,12 @@ This means that /every org-mode file I have/ is part of this search.
***** org-ql-select-all-regexp
#+begin_src elisp
(defun gptel-org-tools--org-ql-select-all-regexp (query)
- (let ((bound-query (format "\\b%s\\b" (regexp-quote query))))
+ "Return all entries matching regexp QUERY in org-agenda-files.
+ QUERY is a regular expression."
(org-ql-select
(org-agenda-files)
- `(regexp ,bound-query)
- :action #'gptel-org-tools--heading-body)))
+ `(regexp ,query)
+ :action #'gptel-org-tools--heading-body))
(add-to-list 'gptel-org-tools
(gptel-make-tool
@@ -848,7 +880,6 @@ This means that /every org-mode file I have/ is part of this search.
:category "org-ql"))
#+end_src
-
** End
#+begin_src elisp
(provide 'gptel-org-tools)
diff --git a/gptel-org-tools.el b/gptel-org-tools.el
index 6927152..dbb1f73 100644
--- a/gptel-org-tools.el
+++ b/gptel-org-tools.el
@@ -62,6 +62,7 @@
"---\n"))
(defun gptel-org-tool--list-buffers (&optional arg)
+ "Return list of buffers."
(list-buffers-noselect)
(with-current-buffer "*Buffer List*"
(let ((content (buffer-string)))
@@ -79,6 +80,7 @@
:category "emacs"))
(defun gptel-org-tools--dir (dir)
+ "Return directory listing."
(with-temp-buffer
(dired (or dir "~"))
(let ((content (buffer-string)))
@@ -97,6 +99,7 @@
:category "filesystem"))
(defun gptel-org-tools--open-file-inactive (file)
+ "Open FILE in a buffer."
(with-current-buffer (get-buffer-create file)
(insert-file-contents file)
(concat
@@ -112,6 +115,7 @@
:category "filesystem"))
(defun gptel-org-tools--describe-variable (var)
+ "Return documentation for VAR."
(let ((symbol (intern var)))
(if (boundp symbol)
(prin1-to-string (symbol-value symbol))
@@ -128,6 +132,7 @@
:category "emacs"))
(defun gptel-org-tools--describe-function (fun)
+ "Return documentation for FUN."
(let ((symbol (intern fun)))
(if (fboundp symbol)
(prin1-to-string (documentation symbol 'function))
@@ -145,6 +150,7 @@
:category "emacs"))
(defun gptel-org-tools--org-extract-tags (buffer)
+ "Return all tags from BUFFER."
(with-current-buffer buffer
(let ((tags '()))
(org-map-entries
@@ -167,6 +173,7 @@
:category "org-mode"))
(defun gptel-org-tools--org-extract-headings (buffer)
+ "Return all headings from BUFFER."
(if (member buffer gptel-org-tools-skip-heading-extraction)
(user-error "Buffer %s has too many headings, use org-extract-tags or org-ql-select-rifle." buffer)
(with-current-buffer buffer
@@ -216,6 +223,7 @@ DATE is the date or date range to match."
:category "org"))
(defun gptel-org-tools--org-agenda-seek (days)
+ "Return the results of org-agenda-list spanning now to DAYS."
(with-temp-buffer
(org-agenda-list (or days 14))
(let ((content (buffer-string)))
@@ -233,6 +241,7 @@ DATE is the date or date range to match."
:category "org"))
(defun gptel-org-tools--org-ql-select-headings (buf query)
+ "Return headings matching QUERY from BUFFER."
(org-ql-select
(get-buffer buf)
`(heading ,query)
@@ -253,6 +262,7 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-headings-rifle (buf query)
+ "Return headings of entries (body included) that match keyword QUERY from BUFFER."
(org-ql-select
(get-buffer buf)
`(rifle ,query)
@@ -273,6 +283,7 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-tags-local (buf query)
+ "Return entries whose tags match QUERY in BUFFER, without inheritance."
(org-ql-select
(get-buffer buf)
`(tags-local ,query)
@@ -293,6 +304,7 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-tags-local-count (buf query)
+ "Return count of entries tagged QUERY in BUFFER."
(length (org-ql-select
(get-buffer buf)
`(tags-local ,query)
@@ -313,6 +325,7 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-tags (buf query)
+ "Return every entry tagged QUERY from BUFFER."
(org-ql-select
(get-buffer buf)
`(tags ,query)
@@ -332,6 +345,7 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-rifle (buf query)
+ "Return every entry matching keyword QUERY from BUFFER."
(let ((buffer (get-buffer buf)))
(if buffer
(org-ql-select
@@ -354,6 +368,8 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-all-tags-local (query)
+ "Return entries whose tags match QUERY in org-agenda-files.
+ QUERY is the tag to search for."
(org-ql-select
(org-agenda-files)
`(tags-local ,query)
@@ -371,6 +387,9 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-all-tags (query)
+ "Return entries whose tags match QUERY,
+with inheritance, in org-agenda-files.
+ QUERY is the tag to search for."
(org-ql-select
(org-agenda-files)
`(tags ,query)
@@ -387,6 +406,8 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-all-rifle (query)
+ "Return entries containing QUERY from org-agenda-files.
+ QUERY is the keyword to search for."
(org-ql-select
(org-agenda-files)
`(rifle ,query)
@@ -403,11 +424,12 @@ DATE is the date or date range to match."
:category "org-ql"))
(defun gptel-org-tools--org-ql-select-all-regexp (query)
- (let ((bound-query (format "\\b%s\\b" (regexp-quote query))))
+ "Return all entries matching regexp QUERY in org-agenda-files.
+ QUERY is a regular expression."
(org-ql-select
(org-agenda-files)
- `(regexp ,bound-query)
- :action #'gptel-org-tools--heading-body)))
+ `(regexp ,query)
+ :action #'gptel-org-tools--heading-body))
(add-to-list 'gptel-org-tools
(gptel-make-tool