GNU ELPA - llm

You can set up with make-llm-openai, with the following parameters:

• :key, the Open AI key that you get when you sign up to use Open AI's APIs. Remember to keep this private. This is non-optional.
• :chat-model: A model name from the list of Open AI's model names. Keep in mind some of these are not available to everyone. This is optional, and will default to a reasonable 3.5 model.
• :embedding-model: A model name from list of Open AI's embedding model names. This is optional, and will default to a reasonable model.

There are many Open AI compatible APIs and proxies of Open AI. You can set up one with make-llm-openai-compatible, with the following parameter:

• :url, the URL of leading up to the command ("embeddings" or "chat/completions"). So, for example, "https://api.openai.com/v1/" is the URL to use Open AI (although if you wanted to do that, just use make-llm-openai instead.

This is Google's AI model. You can get an API key via their page on Google AI Studio. Set this up with make-llm-gemini, with the following parameters:

• :key, the Google AI key that you get from Google AI Studio.
• :chat-model, the model name, from the [[https://ai.google.dev/models][list of models. This is optional and will default to the text Gemini model.
• :embedding-model: the model name, currently must be "embedding-001". This is optional and will default to "embedding-001".

This is mostly for those who want to use Google Cloud specifically, most users should use Gemini instead, which is easier to set up.

You can set up with make-llm-vertex, with the following parameters:

• :project: Your project number from Google Cloud that has Vertex API enabled.
• :chat-model: A model name from the list of Vertex's model names. This is optional, and will default to a reasonable model.
• :embedding-model: A model name from the list of Vertex's embedding model names. This is optional, and will default to a reasonable model.

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".

  If you haven't already, you must run the following command before using this:

  gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT_ID
  

Claude is Anthropic's large language model. It does not support embeddings. You can set it up with the following parameters:

:key: The API key you get from Claude's settings page. This is required. :chat-model: One of the Claude models. Defaults to "claude-3-opus-20240229", the most powerful model.

Ollama is a way to run large language models locally. There are many different models you can use with it. You set it up with the following parameters:

• :scheme: The scheme (http/https) for the connection to ollama. This default to "http".
• :host: The host that ollama is run on. This is optional and will default to localhost.
• :port: The port that ollama is run on. This is optional and will default to the default ollama port.
• :chat-model: The model name to use for chat. This is not optional for chat use, since there is no default.
• :embedding-model: The model name to use for embeddings. This is not optional for embedding use, since there is no default.

GPT4All is a way to run large language models locally. To use it with llm package, you must click "Enable API Server" in the settings. It does not offer embeddings or streaming functionality, though, so Ollama might be a better fit for users who are not already set up with local models. You can set it up with the following parameters:

• :host: The host that GPT4All is run on. This is optional and will default to localhost.
• :port: The port that GPT4All is run on. This is optional and will default to the default ollama port.
• :chat-model: The model name to use for chat. This is not optional for chat use, since there is no default.

llama.cpp is a way to run large language models locally. To use it with the llm package, you need to start the server (with the "–embedding" flag if you plan on using embeddings). The server must be started with a model, so it is not possible to switch models until the server is restarted to use the new model. As such, model is not a parameter to the provider, since the model choice is already set once the server starts.

Llama.cpp does not have native chat interfaces, so is not as good at multi-round conversations as other solutions such as Ollama. It will perform better at single-responses. However, it does support Open AI's request format for models that are good at conversation. If you are using one of those models, you should probably use the Open AI Compatible provider instead to connect to Llama CPP.

The parameters default to optional values, so mostly users should just be creating a model with (make-llm-llamacpp). The parameters are:

• :scheme: The scheme (http/https) for the connection to llama.cpp. This default to "http".
• :host: The host that llama.cpp server is run on. This is optional and will default to localhost.
• :port: The port that llama.cpp server is run on. This is optional and will default to 8080, the default llama.cpp port.

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-chat provider prompt: With user-chosen provider , and a llm-chat-prompt structure (containing context, examples, interactions, and parameters such as temperature and max tokens), send that prompt to the LLM and wait for the string output.
• 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-chat-streaming provider prompt partial-callback response-callback error-callback: Similar to llm-chat-async, but request a streaming response. As the response is built up, partial-callback is called with the all the text retrieved up to the current point. Finally, reponse-callback is called with the complete text.
• 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.
• llm-count-tokens provider string: Count how many tokens are in string. This may vary by provider, because some provideres implement an API for this, but typically is always about the same. This gives an estimate if the provider has no API support.
• llm-cancel-request request Cancels the given request, if possible. The request object is the return value of async and streaming functions.
• llm-name provider. Provides a short name of the model or provider, suitable for showing to users.

• llm-chat-token-limit. Gets the token limit for the chat model. This isn't possible for some backends like llama.cpp, in which the model isn't selected or known by this library.

  And the following helper functions:

  • llm-make-simple-chat-prompt text: For the common case of just wanting a simple text prompt without the richness that llm-chat-prompt struct provides, use this to turn a string into a llm-chat-prompt that can be passed to the main functions above.
  • llm-chat-prompt-to-text prompt: Somewhat opposite of the above, from a prompt, return a string representation. This is not usually suitable for passing to LLMs, but for debugging purposes.
  • llm-chat-streaming-to-point provider prompt buffer point finish-callback: Same basic arguments as llm-chat-streaming, but will stream to point in buffer.
  • llm-chat-prompt-append-response prompt response role: Append a new response (from the user, usually) to the prompt. The role is optional, and defaults to 'user.

Interactions with the llm package can be logged by setting llm-log to a non-nil value. This should be done only when developing. The log can be found in the *llm log* buffer.

Conversations can take place by repeatedly calling llm-chat and its variants. For a conversation, the entire prompt must be a variable, because the llm-chat-prompt-interactions slot will be getting changed by the chat functions to store the conversation. For some providers, this will store the history directly in llm-chat-prompt-interactions, but for others (such as ollama), the conversation history is opaque. For that reason, the correct way to handle a conversation is to repeatedly call llm-chat or variants, and after each time, add the new user text with llm-chat-prompt-append-response. The following is an example:

(defvar-local llm-chat-streaming-prompt nil)
(defun start-or-continue-conversation (text)
  "Called when the user has input TEXT as the next input."
  (if llm-chat-streaming-prompt
      (llm-chat-prompt-append-response llm-chat-streaming-prompt text)
    (setq llm-chat-streaming-prompt (llm-make-simple-chat-prompt text))
    (llm-chat-streaming-to-point provider llm-chat-streaming-prompt (current-buffer) (point-max) (lambda ()))))

The interactions in a prompt may be modified by conversation or by the conversion of the context and examples to what the LLM understands. Different providers require different things from the interactions. Some can handle system prompts, some cannot. Some may have richer APIs for examples and context, some not. Do not attempt to read or manipulate llm-chat-prompt-interactions after initially setting it up for the first time, because you are likely to make changes that only work for some providers.

Note: function calling functionality is currently alpha quality. If you want to use function calling, please watch the llm discussions for any announcements about changes.

Function calling is a way to give the LLM a list of functions it can call, and have it call the functions for you. The standard interaction has the following steps:

1. The client sends the LLM a prompt with functions it can call.
2. The LLM may return which functions to execute, and with what arguments, or text as normal.
3. If the LLM has decided to call one or more functions, those functions should be called, and their results sent back to the LLM.
4. The LLM will return with a text response based on the initial prompt and the results of the function calling.
5. The client can now can continue the conversation.

This basic structure is useful because it can guarantee a well-structured output (if the LLM does decide to call the function). Not every LLM can handle function calling, and those that do not will ignore the functions entirely. The function llm-capabilities will return a list with function-calls in it if the LLM supports function calls. Right now only Gemini, Vertex and Open AI support function calling. Ollama should get function calling soon. However, even for LLMs that handle function calling, there is a fair bit of difference in the capabilities. Right now, it is possible to write function calls that succeed in Open AI but cause errors in Gemini, because Gemini does not appear to handle functions 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 llm-function-call slot in the prompt. This is a list of llm-function-call structs, which takes a function, a name, a description, and a list of llm-function-arg structs. The docstrings give an explanation of the format.

The various chat APIs will execute the functions defined in llm-function-call with the arguments supplied by the LLM. Instead of returning (or passing to a callback) a string, instead an alist will be returned of function names and return values.

The client must then send this back to the LLM, to get a textual response from the LLM based on the results of the function call. These have already been added to the prompt, so the client only has to call the LLM again. Gemini and Vertex require this extra call to the LLM, but Open AI does not.

Be aware that there is no gaurantee that the function will be called correctly. While the LLMs mostly get this right, they are trained on Javascript functions, so imitating Javascript names is recommended. So, "write_email" is a better name for a function than "write-email".

Examples can be found in llm-tester. There is also a function call to generate function calls from existing elisp functions in utilities/elisp-to-function-call.el.