Both functions are accessed through Kagi's [[https://help.kagi.com/kagi/api/overview.html][APIs]]. Before a call can be made, some setup should be done on the Kagi website (see below).
- =kagi-fastgpt-shell= :: Opens a shell buffer in a new window where prompts can be typed. This Kagi FastGPT typically returns output based on actual search results. When point is on one of the listed URLs, press =C-c RET= to open it.
- =kagi-fastgpt-prompt= :: Enter a prompt in the minibuffer and show the result in a separate buffer. With a universal prefix (=C-u=), the result is inserted at point. This function can also be used from Lisp code.
The API token can be supplied directly as a string, but you could write a lambda to retrieve the token from a more secure location (e.g. with the combination of [[https://passwordstore.org/][pass(1)]] and the /password-store/ package that comes with it).
2. In [[https://kagi.com/settings?p=billing_api][your account settings]], put a balance for the API part (note that this is a separate balance than the subscription). The recommendation is to start with a one-time charge of $5. Check the pricing for the [[https://help.kagi.com/kagi/api/fastgpt.html#pricing][FastGPT API]] and the [[https://help.kagi.com/kagi/api/summarizer.html#pricing][Summarizer API]] for the actual costs.
3. In [[https://kagi.com/settings?p=api][the API portal]], create an API token. Put the result in ~kagi-api-token~ (or write a function to access it securely).
The code to generate the table of configuration items was inspired by an idea of [[https://xenodium.com/generating-elisp-org-docs/][Álvaro Ramírez]] (a.k.a. xenodium).
kagi.el comes with a macro to define your own prompts easily: =define-kagi-fastgpt-prompt=. When the prompt contains the placeholder =%s=, it will be replaced with the region or an interactively used word.
An example usage of this macro comes by default with this package:
The first argument is the name of the command that will be defined. The second argument the prompt that will be sent. The third argument is optional and gives your prompt a user-visible name. It will be shown when calling =kagi-fastgpt-prompt= interactively.
The defined prompt becomes a typical Emacs command that takes one argument to fill the placeholder. You could bind the prompt command to a key, use it to integrate with Embark (see below) or to list all your prompts with a Hydra.
Press =C-c C-c= (=org-babel-execute-src-block=) inside this block to obtain the result below the prompt. By default, the responses are cached in your document; the same prompt text won't trigger a second API request. Use the header argument =:cache no= to refresh the response for each block execution.
The kagi.el package can be integrated with [[https://github.com/oantolin/embark][Embark]]. Use it to easily summarize, translate or proofread a buffer, region or a URL. It can also be used to call your custom prompts with =define-kagi-fastgpt-prompt=.
In order to be consistent with all keymaps, and to avoid clashes, the functionality is behind the /K/ prefix key. For example, press /K s/ to invoke the summarize functionality.
Since the FastGPT shell inherits from =comint-mode= indirectly, many key bindings are also inherited. Enter the =help= command in the shell to get more info, or run =describe-keymap= on =fastgpt-shell-mode-map=.
One of those bindings is =C-c C-o=, which flushes the last output. However, this binding is used in =org-mode= to open a URL an point. Typical FastGPT results include URLs, so one may be tempted to type =C-c C-o= to browse the URL, only to have the output erased (which you can undo, actually).
If you recognize this confusion, you may want to add the following line to your configuration file to shadow the =comint-mode= binding with something more appropriate:
kagi.el comes with some unit tests, written with [[https://github.com/jorgenschaefer/emacs-buttercup/][buttercup]] and can be executed in a controlled [[https://github.com/cask/cask/][Cask]] environment:
1.=git clone https://github.com/cask/cask/=
2.=make -C cask install=
3. Run =cask= in the kagi.el directory to setup the environment.
4. Run the tests with =cask exec buttercup -L .=
There's also a [[https://github.com/casey/just][justfile]] which allows you to execute =just test= to compile the Emacs Lisp source and run the unit tests afterwards in one go.
- Show a welcome message when starting the FastGPT shell (=kagi-fastgpt-shell=). This can be customized with =kagi-fastgpt-welcome-function=, a variable with a function that returns a welcome string.
- =kagi-summarize= has a =no-cache= parameter to opt out from caching at Kagi's side.
- =kagi-summarize-buffer= and =kagi-summarize-region= also have a =no-cache= parameter which can be toggled interactively when called with the universal prefix.
- Some variables were renamed for consistency. The impact is considered low given the infancy of the package, and API URLs are typically not modified anyway.
- Add boolean variable =kagi-stubbed-responses= to enable stubbed responses, to replace actual API calls. Since calls are metered, it's more economic to use stubbed responses for development / debugging purposes.