855 lines
33 KiB
Org Mode
855 lines
33 KiB
Org Mode
#+title: gptel-org-tools
|
|
#+author: Phil Bajsicki
|
|
#+auto_tangle: t
|
|
#+PROPERTY: header-args :elisp :tangle gptel-org-tools.el
|
|
* Intro
|
|
This is a collection of tools I wrote to help me review my life.
|
|
|
|
To that end, it's proven useful enough.
|
|
|
|
Summary:
|
|
- An explanation of each tool is below.
|
|
- The tools are tangled into =gptel-org-tools.el= from this file.
|
|
- There are no docstrings unless there are, in which case that's a mistake and I apologize.
|
|
|
|
Premise:
|
|
- LLMs are /not very smart/ and /unreliable/, but they do okay with basic text comprehension, and can generate completions/ responses which /fit the vibe/ of the request.
|
|
- LLMs can then /fit the vibe/ of the request better if there is more relevant and accurate request data in their context window.
|
|
- LLMs /lose the vibe/ when there's irrelevant (garbage) data in the context window.
|
|
|
|
Therefore (philosophy, I may change my mind later):
|
|
- Each tool has to limit the garbage data it returns as much as possible.
|
|
- Each tool has to have as little LLM-facing documentation as possible (while being enough for the LLM to understand and use the tool.) Extra words is extra garbage.
|
|
- Each tool should handle as wide an range of even remotely valid inputs from an LLM as possible.
|
|
- Different models are biased toward different outputs.
|
|
- ~user-error~ isn't addressable when a model only has 5 minutes worth of memory.
|
|
- Failure caused by LLM mis-use should be solved in such a way that failure becomes increasingly less likely.
|
|
- We never know when an LLM will respond with a string, json, s-exp, or ASCII codes (no, that last one hasn't happened yet).
|
|
- Each tool should work in harmony with other tools to form a toolbox which serves these goals.
|
|
- Avoid tool overlap.
|
|
- One tool for one task.
|
|
- Tool names are documentation.
|
|
- Argument names are documentation.
|
|
- As few arguments per tool as possible.
|
|
- Documentation strings are (ideally) for examples.
|
|
|
|
These are primarily for my own use. Please don't expect quality.
|
|
|
|
This forge is for my personal use, and as such: [[https://bajsicki.com/contact/][contact]], just in case there's questions, issues, whatnot.
|
|
|
|
* My system
|
|
I'm running LLMs exclusively locally, on the smaller side. I'm getting reasonably good results with the following set-up:
|
|
- Hardware: RX 7900XTX
|
|
- Software:
|
|
- [[https://github.com/ggml-org/llama.cpp][llama.cpp]] compiled with ROCm 6.4.
|
|
- Emacs: [[https://github.com/doomemacs/doomemacs][Doom Emacs]], [[https://github.com/karthink/gptel][gptel]], [[https://github.com/alphapapa/org-ql/][org-ql]].
|
|
|
|
** My set-up
|
|
These are the settings I use, for reproducibility.
|
|
|
|
Yes, this is somewhat odd, that I would use the deepseek option, but I have found that it handles reasoning a little bit better than gptel's openai backend.
|
|
|
|
I change models a lot, and this /just works/ for most models, even if some aren't compatible outright.
|
|
|
|
#+begin_src elisp :tangle no
|
|
(use-package! gptel)
|
|
(setq gptel-model 'llamacpp)
|
|
(setq gptel-include-reasoning t)
|
|
(setq gptel-backend (gptel-make-deepseek "llamacpp"
|
|
:host "localhost:8080"
|
|
:protocol "http"
|
|
:stream nil
|
|
:models '("llamacpp"
|
|
:capabilities (reasoning))
|
|
:request-params '(:thinking nil
|
|
:enable_thinking nil
|
|
:include_reasoning nil
|
|
:parallel_tool_calls t)))
|
|
|
|
(setf (alist-get 'org-mode gptel-prompt-prefix-alist) "@user\n")
|
|
(setf (alist-get 'org-mode gptel-response-prefix-alist) "@assistant\n")
|
|
(setq gptel-default-mode 'org-mode)
|
|
(setq gptel-use-tools t)
|
|
(setq gptel-log-level 'debug)
|
|
(setq gptel--debug t)
|
|
(require 'gptel)
|
|
#+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:
|
|
:VISIBILITY: folded
|
|
:END:
|
|
Stuff, headers, etc.
|
|
#+begin_src elisp
|
|
;;; gptel-org-tools.el --- LLM Tools for org-mode interaction. -*- lexical-binding: t; -*-
|
|
|
|
;; Copyright (C) 2025 Phil Bajsicki
|
|
|
|
;; Author: Phil Bajsicki <phil@bajsicki.com>
|
|
;; Keywords: extensions, comm, tools, matching, convenience,
|
|
;;
|
|
;; Author: Phil Bajsicki <phil@bajsicki.com>
|
|
;; Version: 0.0.2
|
|
;; Package-Requires: ((emacs "30.1") (gptel 0.9.8) (org-ql 0.9))
|
|
;; URL: https://github.com/phil/gptel-org-tools
|
|
;; SPDX-License-Identifier: GPL-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, version 3 of the License.
|
|
|
|
;; 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/>.
|
|
|
|
;; This file is NOT part of GNU Emacs.
|
|
|
|
;; This file is not part of GNU Emacs.
|
|
|
|
;;; Commentary:
|
|
|
|
;; All documentation regarding these functions is in the README.org file.
|
|
;; Repository: https://git.bajsicki.com/phil/gptel-org-tools
|
|
|
|
;;; Code:)
|
|
#+end_src
|
|
** gptel-org-tools
|
|
Collects into =gptel-org-tools= list, distinct from =gptel-tools=
|
|
#+begin_src elisp
|
|
(defvar gptel-org-tools '())
|
|
#+end_src
|
|
** Variables
|
|
If you're like me, you may have structured headings based on timestamps in your org-mode notes.
|
|
|
|
To that end, there are a few variables that may help you from blowing out the context, specifically for the ~org-extract-headings~ tool.
|
|
|
|
#+begin_src elisp
|
|
(defvar gptel-org-tools-skip-heading-extraction '())
|
|
#+end_src
|
|
|
|
Use ~setq~ in your configuration, with a list of buffer names whose headings you *never* want to extract. E.g.
|
|
|
|
#+begin_src elisp :tangle no
|
|
(setq gptel-org-tools-skip-heading-extraction '("journal.org" ".org"))
|
|
#+end_src
|
|
|
|
** Helper Functions
|
|
These abstract away some of the tool definitions.
|
|
|
|
*** Retrieve heading (line])
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--heading ()
|
|
(concat
|
|
(buffer-substring-no-properties
|
|
(line-beginning-position)
|
|
(line-end-position))
|
|
'"\n---\n"))
|
|
#+end_src
|
|
|
|
*** Retrieve heading and body (without subheadings)
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--heading-body ()
|
|
(concat
|
|
(buffer-substring-no-properties
|
|
(line-beginning-position)
|
|
(progn
|
|
(outline-next-heading)
|
|
(line-beginning-position)))
|
|
"---\n"))
|
|
#+end_src
|
|
|
|
*** Retrieve heading and subheadings (until next same-level heading)
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--heading-subtree ()
|
|
(concat
|
|
(buffer-substring-no-properties
|
|
(line-beginning-position)
|
|
(org-end-of-subtree))
|
|
"---\n"))
|
|
#+end_src
|
|
** Note on org-ql (caching)
|
|
There isn't (yet?) a good way to disable caching. This means that repeated queries will return the same output, until org-ql-cache is cleared.
|
|
|
|
See [[https://github.com/alphapapa/org-ql/issues/437][this issue]] for details.
|
|
|
|
The problem is that trying the solution given in the GitHub issue throws errors, which make LLMs freak out.
|
|
|
|
So for now, you can manually re-set the cache like so:
|
|
|
|
#+begin_src elisp :tangle no :results none
|
|
(setq org-ql-cache (make-hash-table))
|
|
#+end_src
|
|
|
|
** The tools
|
|
*** Emacs
|
|
These tools are primarily concerned with Emacs, Emacs Lisp, and files-or-buffers.
|
|
**** eval
|
|
Dangerous, but occasionally useful for pure chaos and amusement...
|
|
I would like to say. But in actuality, especially with the 'smarter' models, they can surprise with the varied approaches they have to problem-solving.
|
|
|
|
E.g. can't find the right ~org-ql-select~ query? Let's use an eldritch abomination of a regular expression while mapping over each heading in the org-mode buffer and do a /close enough/ job.
|
|
|
|
Highly not recommended, but sometimes an LLM can pull a rabbit out of pure entropy.
|
|
|
|
#+begin_src elisp :tangle no
|
|
(defun gptel-org-tools--eval (elisp)
|
|
(unless (stringp elisp) (error "elisp code must be a string"))
|
|
(with-temp-buffer
|
|
(insert (eval (read elisp)))
|
|
(buffer-string)))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--eval
|
|
:name "gptel-org-tools--eval"
|
|
:description "Execute Emacs Lisp code"
|
|
:args (list '(:name "eval"
|
|
:type string
|
|
:description "The Emacs Lisp code to evaluate."))
|
|
:category "emacs"
|
|
:confirm t))
|
|
#+end_src
|
|
|
|
**** 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 ~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
|
|
(defun gptel-org-tool--list-buffers ()
|
|
(list-buffers-noselect)
|
|
(with-temp-buffer "*Buffer List*"
|
|
(buffer-string)))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tool--list-buffers
|
|
:name "gptel-org-tool--list-buffers"
|
|
:description "Access the list of buffers open in Emacs, including file names and full paths."
|
|
:args (list '(:name "arg"
|
|
:type string
|
|
:description "Does nothing."
|
|
:optional t))
|
|
:category "emacs"))
|
|
#+end_src
|
|
|
|
**** dired
|
|
See above, same reasoning. There's very little reason to use the ~directory-files~ function for this (as in another tool I saw.) The reason is, ~directory-files~ doesn't provide nearly as much information about the items in that directory. Not even a distinction between files and directories.
|
|
|
|
~directory-files-and-attributes~ might, but I personally found its output horrendous to read, and still somehow more expensive context-wise than just plain ol' dired.
|
|
|
|
#+begin_comment
|
|
Be sure to customize the function to point to your org directory, if you wish. I find it makes a big difference. Having the argument be optional also helps when the LLM starts stumbling, as it gives it a /reset point/ so it can re-orient itself (although by that time it has usually forgotten what it was supposed to be doing...)
|
|
#+end_comment
|
|
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--dir (dir)
|
|
(with-temp-buffer
|
|
(dired (or dir "~"))
|
|
(let ((content (buffer-string)))
|
|
(kill-buffer (current-buffer))
|
|
content)))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--dir
|
|
:name "gptel-org-tools--dir"
|
|
:description "List directory contents"
|
|
:args (list '(:name "dir"
|
|
:type string
|
|
:description "Directory path"
|
|
:optional t))
|
|
:category "filesystem"))
|
|
#+end_src
|
|
|
|
**** find-buffer-visiting
|
|
Disabled for now, as it's causing some issues.
|
|
#+begin_src elisp :tangle no :results none
|
|
(defun gptel-org-tools--find-buffer-visiting (filename)
|
|
(concat
|
|
(bufferp
|
|
(find-buffer-visiting
|
|
(expand-file-name filename)))))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--find-buffer-visiting
|
|
:name "gptel-org-tools--find-buffer-visiting"
|
|
:description "Check if the file is open in a buffer. Usage (find-buffer-visiting filename)"
|
|
:args (list '(:name "filename"
|
|
:type string
|
|
:description "The filename to compare to open buffers."))
|
|
:category "org-mode"))
|
|
#+end_src
|
|
|
|
**** open-file-inactive
|
|
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)
|
|
(with-current-buffer (get-buffer-create file)
|
|
(insert-file-contents file)
|
|
(concat
|
|
(current-buffer))))
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--open-file-inactive
|
|
:name "gptel-org-tools--open-file-inactive"
|
|
:description "Open the file in a background buffer. This doesn't interfere with the user."
|
|
:args (list '(:name "file"
|
|
:type string
|
|
:description "Path to file.."))
|
|
:category "filesystem"))
|
|
#+end_src
|
|
|
|
**** read-file-contents
|
|
This reads file contents,
|
|
#+begin_src elisp :tangle no
|
|
(defun gptel-org-tools--read-file-contents (file)
|
|
(with-temp-buffer
|
|
(insert-file-contents (expand-file-name filename))
|
|
(concat
|
|
(buffer-string)
|
|
"\n---\nTool execution complete. Proceed with next step.")))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--read-file-contents
|
|
:name "gptel-org-tools--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"
|
|
:confirm t))
|
|
#+end_src
|
|
**** describe-variable
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--describe-variable (var)
|
|
(let ((symbol (intern var)))
|
|
(if (boundp symbol)
|
|
(prin1-to-string (symbol-value symbol))
|
|
(format "Variable %s is not bound." var))))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--describe-variable
|
|
:name "gptel-org-tools--describe-variable"
|
|
:description "See variable contents"
|
|
:args (list '(:name "var"
|
|
:type string
|
|
:description "Variable name"))
|
|
:category "emacs"))
|
|
#+end_src
|
|
|
|
**** describe-function
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--describe-function (fun)
|
|
(let ((symbol (intern fun)))
|
|
(if (fboundp symbol)
|
|
(prin1-to-string (documentation symbol 'function))
|
|
(format "Function %s is not defined." fun))))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--describe-function
|
|
:name "gptel-org-tools--describe-function"
|
|
:description "See function description"
|
|
:args (list '(:name "fun"
|
|
:type string
|
|
:description "Function name"
|
|
:optional t))
|
|
:category "emacs"))
|
|
#+end_src
|
|
|
|
*** Org-mode
|
|
And here we start getting into the weeds.
|
|
|
|
The core of these functions is to ensure that the LLM doesn't go astray.
|
|
|
|
It will, inevitably.
|
|
|
|
Then, the core of these functions is to ensure it can be gently prodded into doing what it's asked, instead of being "asked politely" until it complies.
|
|
|
|
We want to minimize the effect of entropy on the use of these tools. To that end, we're making /separate tools for separate purposes/.
|
|
|
|
This isn't proven, by any means, but given what little I know about LLMs, I believe it's easier for them to choose between many single-purpose tools, than from few multi-purpose tools.
|
|
|
|
Even us humans experience less cognitive load when we're given clear options up-front, instead of being given a multi-tool that we then need to learn our way around to get the job done.
|
|
|
|
With that secondary purpose in mind, the real aim of these tools is to /limit/ the information that the LLM has access to /only/ to that which is relevant. In the ideal.
|
|
|
|
In the real world, we'll still see garbage being pulled in, and the LLM being led astray by an unfortunate sentence, or an ~org-ql~ query that explodes the context.
|
|
|
|
At the same time, that will happen /significantly/ less than if we were to give it more freedom.
|
|
|
|
#+begin_comment
|
|
LLMs are not intelligent, despite claims to the contrary.
|
|
#+end_comment
|
|
|
|
**** org-extract-tags
|
|
Pretty simple, does what it says on the tin. It gets all the tags from the =buffer=. This is useful as a first line of research for the LLM, as it can then get a surface-level understanding of the contents of a file.
|
|
|
|
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)
|
|
(with-current-buffer buffer
|
|
(let ((tags '()))
|
|
(org-map-entries
|
|
(lambda ()
|
|
(let* ((components (org-heading-components))
|
|
(tag-string (car (last components))))
|
|
(when tag-string
|
|
(dolist (tag (split-string tag-string ":" t))
|
|
(push tag tags))))))
|
|
(sort (-uniq tags) #'string<))))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-extract-tags
|
|
:name "gptel-org-tools--org-extract-tags"
|
|
:description "Extract all unique tags from an org-mode buffer"
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The Org buffer to extract tags from."))
|
|
:category "org-mode"))
|
|
#+end_src
|
|
**** org-extract-headings
|
|
But what if there's no tags related to the topic?
|
|
|
|
Then we need to pull /some/ information from the buffer, without dragging the entire 500kb in and exploding the context window.
|
|
|
|
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)
|
|
(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
|
|
(org-map-entries
|
|
#'gptel-org-tools--heading
|
|
t
|
|
'file))))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-extract-headings
|
|
:name "gptel-org-tools--org-extract-headings"
|
|
:description "Extract all headings from an org-mode buffer"
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The Org buffer to extract headings from."))
|
|
:category "org-mode"))
|
|
#+end_src
|
|
|
|
**** org-ql-select
|
|
This is the big one. It works, and it's ugly, and I'm in the middle of replacing it. The tool argument descriptions do /a lot/ of lifting here, and even then the models stumble and fall on their face very often.
|
|
|
|
They also sometimes return a sexp, and sometimes a quoted string. So I had to work around that. It works... some of the time.
|
|
|
|
My current goal is to replace this monstrosity with individual functions for each of the main ~org-ql~ predicates, such that the LLMs have an easier time with the syntax, so they can just choose their desired query instead of having to both choose and properly form the syntax.
|
|
|
|
But in the interim, this works. Kind of.
|
|
|
|
#+begin_comment
|
|
Currently *not* tangled, as I'm testing breaking out each type of query into its own individual tool.
|
|
#+end_comment
|
|
|
|
|
|
#+begin_src elisp :tangle no
|
|
(defun gptel-org-tools--org-ql-select (buf query)
|
|
(org-ql-select
|
|
(get-buffer buf)
|
|
(if (stringp query)
|
|
(read query)
|
|
query)
|
|
:action #'gptel-org-tools--heading-body))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select
|
|
:name "gptel-org-tools--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"))
|
|
#+end_src
|
|
**** Somewhat working tools
|
|
***** org-ql-select-dates
|
|
My journal is a single file, with a hierarchy like so:
|
|
|
|
#+begin_src org :tangle no
|
|
,* [YYYY]
|
|
,** [YYYY-MM]
|
|
,*** [YYYY-MM-DD Day HH:MM])
|
|
#+end_src
|
|
|
|
I wanted to make sure that if I asked about a time period, the LLM would be able to pull at least roughly around the right time from my journal, without blowing out its context window.
|
|
|
|
This /kinda sorta/ works. The only time I have seen this fail is when the LLM chooses to apply it to buffers that don't follow that convention.
|
|
|
|
I doubt it'll be useful for anyone else, but it's here and fairly easy to adapt to other needs.
|
|
|
|
Notice it pulls to the end of the subtree. So for months, that's at least 28 entries in a year, and during busy months, possibly hundreds.
|
|
|
|
But, any customizations to tweak this is left to the user, as everyone has their own conventions.
|
|
|
|
|
|
Testing new version:
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--org-ql-select-by-date (buf date)
|
|
"Returns all timestamped headings matching the specified date or date range.
|
|
The date can be in the format YYYY, YYYY-MM, or YYYY-MM-DD.
|
|
|
|
BUFFER is the name of the buffer to search.
|
|
DATE is the date or date range to match."
|
|
(let* ((buffer (get-buffer buf))
|
|
(mode (buffer-local-value 'major-mode buffer)))
|
|
(if buffer
|
|
(if (eq mode 'org-mode)
|
|
(org-ql-select buffer
|
|
`(heading ,date)
|
|
:action #'gptel-org-tools--heading-subtree)
|
|
(message "Buffer '%s' isn't an org-mode buffer." buf))
|
|
(message "Buffer '%s' does not exist." buf))))
|
|
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-by-date
|
|
:name "gptel-org-tools--org-ql-select-by-date"
|
|
:description "Returns all timestamped headings matching query. Query may be: YYYY, YYYY-MM, YYYY-MM-DD."
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "Buffer name.")
|
|
'(:name "date"
|
|
:type string
|
|
:description "Date in YYYY or YYYY-MM format."))
|
|
:category "org"))
|
|
#+end_src
|
|
|
|
Original (works but not ideal).
|
|
#+begin_src elisp :tangle no
|
|
(defun gptel-org-tools--org-ql-select-by-date (buf date)
|
|
(org-ql-select
|
|
(get-buffer buf)
|
|
`(heading ,date)
|
|
:action #'gptel-org-tools--heading-subtree))
|
|
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-by-date
|
|
:name "gptel-org-tools--org-ql-select-by-date"
|
|
:description "Returns all timestamped headings matching query. Query may be: YYYY, YYYY-MM, YYYY-MM-DD. Prefer using this first when request specifies any time periods. Example: get all headings matching March 2025: \"2025-03\""
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "Buffer name.")
|
|
'(:name "date"
|
|
:type string
|
|
:description "Date in YYYY or YYYY-MM format."))
|
|
:category "org"))
|
|
#+end_src
|
|
***** org-agenda-seek
|
|
This is still work in progress, the idea is to have the LLM check my calendar and see what my plans are. I have not had time to really dig into this yet.
|
|
|
|
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)
|
|
(with-temp-buffer
|
|
(org-agenda-list (or days 14))
|
|
(let ((content (buffer-string)))
|
|
(kill-buffer (current-buffer))
|
|
content)))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-agenda-seek
|
|
:name "gptel-org-tools--org-agenda-seek"
|
|
:description "Get user's agenda (tasking) spanning X days from now. This can be used to get all agenda tasks that are due or scheduled in the next X days, or in the past X days, depending on whether the days argument is positive or negative. Example: get all agenda tasks due in the next 7 days: \"7\""
|
|
:args (list '(:name "days"
|
|
:type integer
|
|
:description "Days. Positive = future. Negative = past. Default: 14"))
|
|
:category "org"))
|
|
#+end_src
|
|
**** Completely WIP tools
|
|
The following tools are still very much WIP, and I think they're self-explanatory enough. They have /NOT/ been tested in any way, shape, form, or capacity.
|
|
|
|
(I mean, /some/ of them work... but they don't sometimes, too.)
|
|
|
|
***** org-ql-select-headings
|
|
Retrieve the headings where the heading matches query..
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--org-ql-select-headings (buf query)
|
|
(org-ql-select
|
|
(get-buffer buf)
|
|
`(heading ,query)
|
|
:action #''gptel-org-tools--heading))
|
|
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-headings
|
|
:name "gptel-org-tools--org-ql-select-headings"
|
|
:description "Retreive matching headings from buffer. Matches only a single string. Using filename fails."
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The name of the buffer. See the NAME column in ~emacs-list-buffers~.")
|
|
'(:name "query"
|
|
:type string
|
|
:description "The string to match entry headings against."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-headings-rifle
|
|
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)
|
|
(org-ql-select
|
|
(get-buffer buf)
|
|
`(rifle ,query)
|
|
:action #'gptel-org-tools--heading))
|
|
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-headings-rifle
|
|
:name "gptel-org-tools--org-ql-select-headings-rifle"
|
|
:description "Retreive headings from buffer using org-ql-select. Matches against both heading and content. Using filename fails."
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The name of the buffer. See the NAME column in ~emacs-list-buffers~.")
|
|
'(:name "query"
|
|
:type string
|
|
:description "The string to match entry headings against."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-tags-local
|
|
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)
|
|
(org-ql-select
|
|
(get-buffer buf)
|
|
`(tags-local ,query)
|
|
:action #'gptel-org-tools--heading-body))
|
|
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-tags-local
|
|
:name "gptel-org-tools--org-ql-select-tags-local"
|
|
:description "Run org-ql-select-tags-local against buffer with query. No tag inheritance."
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The name of the buffer. See the NAME column in `emacs-list-buffers`. Using filename fails.")
|
|
'(:name "query"
|
|
:type string
|
|
:description "The string match entry tags against."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-tags-local-count
|
|
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 (buf query)
|
|
(length (org-ql-select
|
|
(get-buffer buf)
|
|
`(tags-local ,query)
|
|
:action #'gptel-org-tools--heading-body)))
|
|
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-tags-local
|
|
:name "gptel-org-tools--org-ql-select-tags-local"
|
|
:description "Get count of matching tags from buffer. No tag inheritance."
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The name of the buffer. See the NAME column in `emacs-list-buffers`. Using filename fails.")
|
|
'(:name "query"
|
|
:type string
|
|
:description "The string match entry tags against."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-tags
|
|
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)
|
|
(org-ql-select
|
|
(get-buffer buf)
|
|
`(tags ,query)
|
|
:action #'gptel-org-tools--heading-body))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-tags
|
|
:name "gptel-org-tools--org-ql-select-tags"
|
|
:description "Run org-ql-select-tags against buffer with query. Supports tag inheritance."
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The name of the buffer. See the NAME column in `emacs-list-buffers`. Using filename fails.")
|
|
'(:name "query"
|
|
:type string
|
|
:description "The string to match entry headings against."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-rifle
|
|
And, the "grab everything that matches" tool.
|
|
#+begin_src elisp
|
|
(defun gptel-org-tools--org-ql-select-rifle (buf query)
|
|
(let ((buffer (get-buffer buf)))
|
|
(if buffer
|
|
(org-ql-select
|
|
buffer
|
|
`(rifle ,query)
|
|
:action #'gptel-org-tools--heading-body)
|
|
(message "Buffer '%s' does not exist." buf))))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-rifle
|
|
:name "gptel-org-tools--org-ql-select-rifle"
|
|
:description "Run org-ql-select-rifle against buffer with query."
|
|
:args (list '(:name "buffer"
|
|
:type string
|
|
:description "The name of the buffer. See the NAME column in `emacs-list-buffers`. Using filename fails.")
|
|
'(:name "query"
|
|
:type string
|
|
:description "A single string to search for."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-all-tags-local
|
|
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)
|
|
(org-ql-select
|
|
(org-agenda-files)
|
|
`(tags-local ,query)
|
|
:action #'gptel-org-tools--heading-body))
|
|
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-all-tags-local
|
|
:name "gptel-org-tools--org-ql-select-all-tags-local"
|
|
:description "Run single string query against all files in (org-agenda-files). WITHOUT tag inheritance, only directly tagged headings."
|
|
:args (list '(:name "query"
|
|
:type string
|
|
:description "A single word to scan for."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-all-tags
|
|
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)
|
|
(org-ql-select
|
|
(org-agenda-files)
|
|
`(tags ,query)
|
|
:action #'gptel-org-tools--heading-body))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-all-tags
|
|
:name "gptel-org-tools--org-ql-select-all-tags"
|
|
:description "Run single string query against all files in (org-agenda-files). WITH tag inheritance."
|
|
:args (list '(:name "query"
|
|
:type string
|
|
:description "A simple (single) string to scan for."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
***** org-ql-select-all-rifle
|
|
And for the entire =(org-agenda-files)=.
|
|
|
|
Note that I define my agenda in this way:
|
|
|
|
#+begin_src elisp :tangle no
|
|
(setq org-agenda-files (directory-files-recursively "~/enc/org/" ".org$"))
|
|
#+end_src
|
|
|
|
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)
|
|
(org-ql-select
|
|
(org-agenda-files)
|
|
`(rifle ,query)
|
|
:action #'gptel-org-tools--heading-body))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-all-rifle
|
|
:name "gptel-org-tools--org-ql-select-all-rifle"
|
|
:description "Run simple (single) string against ALL org-mode files (notes)."
|
|
:args (list '(:name "query"
|
|
:type string
|
|
:description "The string to match entry headings and content against."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
|
|
***** 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))))
|
|
(org-ql-select
|
|
(org-agenda-files)
|
|
`(regexp ,bound-query)
|
|
:action #'gptel-org-tools--heading-body)))
|
|
|
|
(add-to-list 'gptel-org-tools
|
|
(gptel-make-tool
|
|
:function #'gptel-org-tools--org-ql-select-all-regexp
|
|
:name "gptel-org-tools--org-ql-select-all-regexp"
|
|
:description "Run regexp on ALL files at once."
|
|
:args (list '(:name "query"
|
|
:type string
|
|
:description "Regexp, Emacs Lisp format. Automatically wrapped in a word boundary by the tool."))
|
|
:category "org-ql"))
|
|
#+end_src
|
|
|
|
|
|
** End
|
|
#+begin_src elisp
|
|
(provide 'gptel-org-tools)
|
|
;;; gptel-org-tools.el ends here
|
|
#+end_src
|