Rename llm-tool-functions to llm-tool, fixes to elisp-to-tool

NEWS.org

@@ -1,3 +1,5 @@
+* Version 0.22.0
+- Change ~llm-tool-function~ to ~llm-tool~, change ~make-llm-tool-function~ to take any arguments.
 * Version 0.21.0
 - Incompatible change to function calling, which is now tool use, affecting arguments and methods.
 - Support image understanding in Claude

README.org

@@ -205,13 +205,13 @@ Tool use is a way to give the LLM a list of functions it can call, and have it c
 
 This basic structure is useful because it can guarantee a well-structured output (if the LLM does decide to use the tool). *Not every LLM can handle tool use, and those that do not will ignore the tools entirely*. The function =llm-capabilities= will return a list with =tool-use= in it if the LLM supports tool use. Right now only Gemini, Vertex, Claude, and Open AI support tool use.  However, even for LLMs that handle tool use, there is sometimes a difference in the capabilities. Right now, it is possible to write tools that succeed in Open AI but cause errors in Gemini, because Gemini does not appear to handle tools that have types that contain other types.  So client programs are advised for right now to keep function to simple types.
 
-The way to call functions is to attach a list of functions to the =tools= slot in the prompt. This is a list of =llm-tool-function= structs, which is a tool that is an elisp function, with a name, a description, and a list of arguments. The docstrings give an explanation of the format.  An example is:
+The way to call functions is to attach a list of functions to the =tools= slot in the prompt. This is a list of =llm-tool= structs, which is a tool that is an elisp function, with a name, a description, and a list of arguments. The docstrings give an explanation of the format.  An example is:
 
 #+begin_src emacs-lisp
 (llm-chat-async my-llm-provider (llm-make-chat-prompt
    "What is the capital of France?"
    :tools
-   (list (llm-make-tool-function
+   (list (llm-make-tool
           :function (lambda (callback result)
                       ;; In this example function the assumption is that the
                       ;; callback will be called after processing the result is

llm-claude.el

@@ -45,10 +45,10 @@
 
 (defun llm-claude--tool-call (tool)
   "A Claude version of a function spec for TOOL."
-  `(:name ,(llm-tool-function-name tool)
-          :description ,(llm-tool-function-description tool)
+  `(:name ,(llm-tool-name tool)
+          :description ,(llm-tool-description tool)
           :input_schema ,(llm-provider-utils-openai-arguments
-                          (llm-tool-function-args tool))))
+                          (llm-tool-args tool))))
 
 (cl-defmethod llm-provider-chat-request ((provider llm-claude) prompt stream)
   (let ((request

llm-provider-utils.el

@@ -593,18 +593,18 @@ Each plist has the structure:
 
 ;; The Open AI tool spec follows the JSON schema spec.  See
 ;; https://json-schema.org/understanding-json-schema.
-(cl-defmethod llm-provider-utils-openai-tool-spec ((tool llm-tool-function))
+(cl-defmethod llm-provider-utils-openai-tool-spec ((tool llm-tool))
   "Convert TOOL to an Open AI function spec.
 Open AI's function spec is a standard way to do this, and will be
 applicable to many endpoints.
 
 This returns a JSON object (a list that can be converted to JSON)."
   `(:type "function"
           :function
-          (:name ,(llm-tool-function-name tool)
-                 :description ,(llm-tool-function-description tool)
+          (:name ,(llm-tool-name tool)
+                 :description ,(llm-tool-description tool)
                  :parameters ,(llm-provider-utils-openai-arguments
-                               (llm-tool-function-args tool)))))
+                               (llm-tool-args tool)))))
 
 (defun llm-provider-utils-openai-collect-streaming-tool-uses (data)
   "Read Open AI compatible streaming output DATA to collect tool-uses."
@@ -721,9 +721,9 @@ have returned results."
      (let* ((name (llm-provider-utils-tool-use-name tool-use))
             (arguments (llm-provider-utils-tool-use-args tool-use))
             (tool (seq-find
-                   (lambda (f) (equal name (llm-tool-function-name f)))
+                   (lambda (f) (equal name (llm-tool-name f)))
                    (llm-chat-prompt-tools prompt)))
-            (call-args (cl-loop for arg in (llm-tool-function-args tool)
+            (call-args (cl-loop for arg in (llm-tool-args tool)
                                 collect (cdr (seq-find (lambda (a)
                                                          (eq (intern (plist-get arg :name))
                                                              (car a)))
@@ -741,10 +741,10 @@ have returned results."
                           (llm-provider-utils-populate-tool-uses
                            provider prompt results)
                           (funcall success-callback tool-use-and-results)))))
-       (if (llm-tool-function-async tool)
-           (apply (llm-tool-function-function tool)
+       (if (llm-tool-async tool)
+           (apply (llm-tool-function tool)
                   (append (list end-func) call-args))
-         (funcall end-func (apply (llm-tool-function-function tool) call-args)))))))
+         (funcall end-func (apply (llm-tool-function tool) call-args)))))))
 
 
 ;; This is a useful method for getting out of the request buffer when it's time

llm-test.el

@@ -206,7 +206,7 @@
     (:name "Request with tools"
            :prompt (lambda () (llm-make-chat-prompt
                                "Hello world"
-                               :tools (list (llm-make-tool-function
+                               :tools (list (llm-make-tool
                                              :name "func"
                                              :description "desc"
                                              :args '((:name "arg1" :description "desc1" :type string)

llm-tester.el

@@ -250,7 +250,7 @@ for, and you need to provide the most likely function you know
 of by calling the `describe_function' function."
    :temperature 0.1
    :tools
-   (list (llm-make-tool-function
+   (list (llm-make-tool
           :function (lambda (f) f)
           :name "describe_function"
           :description "Takes an elisp function name and shows the user the functions and their descriptions."

llm-vertex.el

@@ -226,10 +226,10 @@ the key must be regenerated every hour."
        [(:function_declarations
          ,(vconcat (mapcar
                     (lambda (tool)
-                      `(:name ,(llm-tool-function-name tool)
-                              :description ,(llm-tool-function-description tool)
+                      `(:name ,(llm-tool-name tool)
+                              :description ,(llm-tool-description tool)
                               :parameters ,(llm-provider-utils-openai-arguments
-                                            (llm-tool-function-args tool))))
+                                            (llm-tool-args tool))))
                     (llm-chat-prompt-tools prompt))))]))
    (llm-vertex--chat-parameters prompt)))
 

llm.el

@@ -5,7 +5,7 @@
 ;; Author: Andrew Hyatt <[email protected]>
 ;; Homepage: https://github.com/ahyatt/llm
 ;; Package-Requires: ((emacs "28.1") (plz "0.8") (plz-event-source "0.1.1") (plz-media-type "0.2.1"))
-;; Package-Version: 0.21.0
+;; Package-Version: 0.22.0
 ;; SPDX-License-Identifier: GPL-3.0-or-later
 ;;
 ;; This program is free software; you can redistribute it and/or
@@ -96,9 +96,8 @@ TOOL-NAME is the name of the tool.  This is required.
 RESULT is the result of the tool use.  This is required."
   call-id tool-name result)
 
-(cl-defstruct (llm-tool-function (:constructor llm-make-tool-function))
-  "This is a struct to represent a single function tool available to the
-LLM.
+(cl-defstruct llm-tool
+  "This is a struct for a single tool available to the LLM.
 
 All fields are required.
 
@@ -223,6 +222,14 @@ This is deprecated, and you should use `llm-make-chat-prompt'
 instead."
   (llm-make-chat-prompt text))
 
+(cl-defun llm-make-tool (&key function name description args async &allow-other-keys)
+  "Create a `llm-tool' struct with FUNCTION, NAME, DESCRIPTION, ARGS, and ASYNC."
+  (make-llm-tool :function function
+                 :name name
+                 :description description
+                 :args args
+                 :async async))
+
 (cl-defun llm-make-chat-prompt (content &key context examples tools
                                         temperature max-tokens response-format
                                         non-standard-params)
@@ -257,7 +264,7 @@ to the chat as a whole.  This is optional.
 EXAMPLES is a list of conses, where the car is an example
 inputs, and cdr is the corresponding example outputs.  This is optional.
 
-TOOLS is a list of `llm-tool-use' structs.  These may be
+TOOLS is a list of `llm-tool' structs.  These may be
 called IF the LLM supports them.  If the LLM does not support
 them, a `not-implemented' signal will be thrown.  This is
 optional.  When this is given, the LLM will either call the

utilities/elisp-to-tool.el

@@ -40,11 +40,12 @@
                           :name
                           "switch_to_buffer"
                           :args
-                          '((:name "buffer_or_name" :type "string" :description "A buffer, a string (buffer name), or nil. If nil, switch to the buffer returned by 'other_buffer'." :required t) (:name "norecord" :type "boolean" :description "If non-nil, do not put the buffer at the front of the buffer list, and do not make the window displaying it the most recently selected one." :required t) (:name "force_same_window" :type "boolean" :description "If non-nil, the buffer must be displayed in the selected window when called non-interactively; if impossible, signal an error rather than calling 'pop_to_buffer'." :required t))
+                          '((:name "buffer_or_name" :type string :description "A buffer, a string (buffer name), or nil. If a string that doesn't identify an existing buffer, create a buffer with that name. If nil, switch to the buffer returned by 'other_buffer'." :required t) (:name "norecord" :type boolean :description "If non-nil, do not put the buffer at the front of the buffer list, and do not make the window displaying it the most recently selected one." :required t) (:name "force_same_window" :type boolean :description "If non-nil, the buffer must be displayed in the selected window when called non-interactively; if impossible, signal an error rather than calling 'pop_to_buffer'." :required t))
                           :description
-                          "Display buffer BUFFER_OR_NAME in the selected window. If the selected window cannot display the specified buffer because it is a minibuffer window or strongly dedicated to another buffer, call 'pop_to_buffer' to select the buffer in another window. Returns the buffer switched to."
+                          "Display buffer BUFFER_OR_NAME in the selected window. WARNING: This is NOT the way to work on another buffer temporarily within a Lisp program! Use 'set_buffer' instead. That avoids messing with the 'window_buffer' correspondences. If the selected window cannot display the specified buffer because it is a minibuffer window or strongly dedicated to another buffer, call 'pop_to_buffer' to select the buffer in another window. In interactive use, if the selected window is strongly dedicated to its buffer, the value of the option 'switch_to_buffer_in_dedicated_window' specifies how to proceed. Return the buffer switched to."
                           :async
-                          nil))
+                          nil)
+  )
 
 ;; A demonstration of the resulting function call in action.
 (defun elisp-to-tool-llm-switch-buffer (instructions)
@@ -115,7 +116,7 @@ Documentation strings should start with uppercase and end with a period."
                                               (list
                                                :name (downcase (elisp-to-tool-el-to-js-name
                                                                 (assoc-default 'name arg)))
-                                               :type (assoc-default 'type arg)
+                                               :type (intern (assoc-default 'type arg))
                                                :description (assoc-default 'description arg))
                                               (if (assoc-default 'required arg)
                                                   (list :required t))))
@@ -125,23 +126,23 @@ Documentation strings should start with uppercase and end with a period."
                        :name "elisp-to-tool-info"
                        :description "The function to create a OpenAI-compatible tool use spec, given the arguments and their documentation.  Some of the aspects of the tool can be automatically retrieved, so this function is supplying the parts that cannot be automatically retrieved."
                        :args '((:name "args"
-                                      :type "array"
-                                      :items (:type "object"
+                                      :type array
+                                      :items (:type object
                                                     :properties (:name
-                                                                 (:type "string"
+                                                                 (:type string
                                                                         :description "The name of the argument")
                                                                  :type
-                                                                 (:type "string"
+                                                                 (:type string
                                                                         :enum ["string""number" "integer" "boolean"]
                                                                         :description "The type of the argument.  It could be 'string', 'number', 'integer', 'boolean', or the more special forms.")
                                                                  :description
-                                                                 (:type "string"
+                                                                 (:type string
                                                                         :description "The description of the argument")
                                                                  :required
-                                                                 (:type "boolean"
+                                                                 (:type boolean
                                                                         :description "Whether the argument is required or not"))))
                                (:name "description"
-                                      :type "string"
+                                      :type string
                                       :description "The documentation of the function to transform.")))))
                     (lambda (result) (message "Result: %S" result))
                     (lambda (_ msg) (error msg)))))