branch: externals/llm
commit 8f30feb5c1a209f7280fd468a2fe4030434a0e81
Author: Andrew Hyatt <ahy...@gmail.com>
Commit: Andrew Hyatt <ahy...@gmail.com>
README improvements, including noting the nonfree llm warning
Also, remove the somewhat duplicated section about different providers.
Require the right provider in the example setup.
---
README.org | 28 ++++++++++++++++++++--------
1 file changed, 20 insertions(+), 8 deletions(-)
diff --git a/README.org b/README.org
index b9047e8103..a4f1b1a6da 100644
--- a/README.org
+++ b/README.org
@@ -13,7 +13,9 @@ Users who use an application that uses this package should
not need to install i
#+begin_src emacs-lisp
(use-package llm-refactoring
- :init (setq llm-refactoring-provider (make-llm-openai :key my-openai-key))
+ :init
+ (require 'llm-openai)
+ (setq llm-refactoring-provider (make-llm-openai :key my-openai-key))
#+end_src
Here ~my-openai-key~ would be a variable you set up before with your Open AI
key. Or, just substitute the key itself as a string. It's important that you
remember never to check your key into a public repository such as github,
because your key must be kept private. Anyone with your key can use the API,
and you will be charged.
@@ -31,8 +33,24 @@ You can set up with ~make-llm-vertex~, with the following
parameters:
In addition to the provider, which you may want multiple of (for example, to
charge against different projects), there are customizable variables:
- ~llm-vertex-gcloud-binary~: The binary to use for generating the API key.
- ~llm-vertex-gcloud-region~: The gcloud region to use. It's good to set this
to a region near where you are for best latency. Defaults to "us-central1".
+** Fake
+This is a client that makes no call, but it just there for testing and
debugging. Mostly this is of use to programmatic clients of the llm package,
but end users can also use it to understand what will be sent to the LLMs. It
has the following parameters:
+- ~:output-to-buffer~: if non-nil, the buffer or buffer name to append the
request sent to the LLM to.
+- ~:chat-action-func~: a function that will be called to provide a string or
symbol and message cons which are used to raise an error.
+- ~:embedding-action-func~: a function that will be called to provide a vector
or symbol and message cons which are used to raise an error.
+* =llm= and the use of non-free LLMs
+The =llm= package is part of GNU Emacs by being part of GNU ELPA.
Unfortunately, the most popular LLMs in use are non-free, which is not what GNU
software should be promoting by inclusion. On the other hand, by use of the
=llm= package, the user can make sure that any client that codes against it
will work with free models that come along. It's likely that sophisticated
free LLMs will, emerge, although it's unclear right now what free software
means with respsect to LLMs. Because of [...]
+
+To build upon the example from before:
+#+begin_src emacs-lisp
+(use-package llm-refactoring
+ :init
+ (require 'llm-openai)
+ (setq llm-refactoring-provider (make-llm-openai :key my-openai-key)
+ llm-warn-on-nonfree nil)
+#+end_src
* Programmatic use
-Client applications should require the module, =llm=, and code against it.
Most functions are generic, and take a struct representing a provider as the
first argument. The client code, or the user themselves can then require the
specific module, such as =llm-openai=, and create a provider with a function
such as ~(make-llm-openai :key user-api-key)~. The client application will use
this provider to call all the generic functions.
+Client applications should require the =llm= package, and code against it.
Most functions are generic, and take a struct representing a provider as the
first argument. The client code, or the user themselves can then require the
specific module, such as =llm-openai=, and create a provider with a function
such as ~(make-llm-openai :key user-api-key)~. The client application will use
this provider to call all the generic functions.
A list of all the functions:
@@ -40,11 +58,5 @@ A list of all the functions:
- ~llm-chat-async provider prompt response-callback error-callback~: Same as
~llm-chat~, but executes in the background. Takes a ~response-callback~ which
will be called with the text response. The ~error-callback~ will be called in
case of error, with the error symbol and an error message.
- ~llm-embedding provider string~: With the user-chosen ~provider~, send a
string and get an embedding, which is a large vector of floating point values.
The embedding represents the semantic meaning of the string, and the vector can
be compared against other vectors, where smaller distances between the vectors
represent greater semantic similarity.
- ~llm-embedding-async provider string vector-callback error-callback~: Same
as ~llm-embedding~ but this is processed asynchronously. ~vector-callback~ is
called with the vector embedding, and, in case of error, ~error-callback~ is
called with the same arguments as in ~llm-chat-async~.
-
-All of the providers currently implemented.
-
-- =llm-openai=. This is the interface to Open AI's Chat GPT. The user must
set their key, and select their preferred chat and embedding model.
-- =llm-vertex=. This is the interface to Google Cloud's Vertex API. The user
needs to set their project number. In addition, to get authenticated, the user
must have logged in initially, and have a valid path in
~llm-vertex-gcloud-binary~. Users can also configure
~llm-vertex-gcloud-region~ for using a region closer to their location. It
defaults to ="us-central1"= The provider can also contain the user's chosen
embedding and chat model.
-- =llm-fake=. This is a provider that is useful for developers using this
library, to be able to understand what is being sent to the =llm= library
without actually sending anything over the wire.
* Contributions
If you are interested in creating a provider, please send a pull request, or
open a bug. This library is part of GNU ELPA, so any major provider that we
include in this module needs to be written by someone with FSF papers.
However, you can always write a module and put it on a different package
archive, such as MELPA.
