9.3 KiB
kagi.el README
Introduction
This Emacs package provides the following functionalities from the Kagi search engine:
- FastGPT
- Kagi's open source LLM offering, as a shell inspired by xenodium's chatgpt-shell.
- Universal Summarizer
- Summarizes texts, webpages, videos and more.
Both functions are accessed through an API. Before a call can be made, some setup should be done on the Kagi website (see below).
Commands and functions
FastGPT
The FastGPT functionality has only one command: kagi-fastgpt-shell
. This opens a shell buffer in a new window where prompts can be typed. 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.
Universal Summarizer
-
kagi-summarize-buffer
- Summarizes the content of a buffer and displays it in a separate buffer.
-
kagi-summarize-region
- Similarly, the text inside the region is summarized and shown in a separate buffer.
-
kagi-summarize-url
- Prompts for a URL of which a summary is composed and displayed.
-
kagi-summarize
- Function to retrieve a summary from a text or URL, to be used from Lisp code.
Note that texts submitted to Kagi are subject to their Privacy Policy.
Installation and configuration
kagi.el is available on MELPA.
To install from Git, clone with:
git clone https://codeberg.org/bram85/kagi.el.git /path/to/kagi.el
Note that kagi.el has a dependency on the shell-maker package, which is available on MELPA.
You way want to load and configure the package with use-package
, for example put the following in your Emacs init file:
(use-package kagi
:commands
kagi-fastgpt-shell
kagi-summarize-buffer
kagi-summarize-region
kagi-summarize-url
:ensure t
:custom
(kagi-api-token "ABCDEF")
;; or use a function, e.g. with the password-store package:
(kagi-api-token (lambda () (password-store-get "Kagi/API")))
;; summarizer settings
(kagi-summarizer-engine "cecil")
(kagi-summarize-default-language "EN")
(kagi-summarize-cache t)
:custom-face
;; kagi-code defaults to fixed-pitch, but can be overridden as
;; follows:
(kagi-code ((t (:inherit org-verbatim)))))
The 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 pass(1) and the password-store package that comes with it).
Kagi API setup
- Create a Kagi account if you haven't done so already. An account is free, and comes with 100 trial searches.
- In 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. A single query ranges from 1 to 5 cents typically, depending on the amount of tokens processed.
- In the API portal, create an API token. Put the result in
kagi-api-token
(or write a function to access it securely).
Configuration settings
Custom variable | Description |
---|---|
kagi-api-token | The Kagi API token. |
kagi-fastgpt-api-url | The Kagi FastGPT API entry point. |
kagi-stubbed-responses | Whether the package should return a stubbed response. |
kagi-summarizer-api-url | The Kagi Summarizer API entry point. |
kagi-summarizer-cache | Determines whether the Summarizer should cache results. |
kagi-summarizer-default-language | Default target language of the summary. |
kagi-summarizer-engine | Which summary engine to use. |
Examples of custom functions
By overriding a variable with a let
construct you can (temporarily) deviate from the default / configured value. A few examples are shown below:
Language override
To obtain a Dutch summary of a video you may want to define the following function:
(defun my/kagi/dutch-summary (text-or-url)
"Obtain a Dutch summary for the given TEXT-OR-URL."
(let ((kagi-summarize-default-language "NL"))
(kagi-summarize text-or-url)))
Caching override
The Summarizer API comes with the following note:
For handling sensitive information and documents, we recommend setting the 'cache' API parameter to False. In this way, the document will "flow through" our infrastructure and will not be retained anywhere after processing.
In a similar fashion as above, you could define a function that disables caching temporarily (while having it enabled by default).
(defun my/kagi/sensitive-summary (text)
"Summarize the current TEXT with caching disabled.")
(let ((kagi-summarizer-cache nil))
(kagi-summarize text))
Embark integration
The kagi.el package can be integrated with Embark, to easily summarize a buffer, region or an URL. In order to be consistent with all keymaps, and to avoid clashes, the functionality is behind the K prefix key. Press K s to trigger the summarize functionality.
Add the following to your configuration to trigger summary functionality with key K s:
(defmacro embark-kagi-map (name function)
"Macro for defining a keymap for accessing Kagi functionality through Embark."
`(defvar-keymap ,name
:doc "Keymap for accessing Kagi functionality with Embark."
:parent nil
"s" #',function))
(embark-kagi-map embark-kagi-buffer-map kagi-summarize-buffer)
(keymap-set embark-buffer-map "K" embark-kagi-buffer-map)
(embark-kagi-map embark-kagi-region-map kagi-summarize-region)
(keymap-set embark-region-map "K" embark-kagi-region-map)
(embark-kagi-map embark-kagi-url-map kagi-summarize-url)
(keymap-set embark-url-map "K" embark-kagi-url-map)
Key bindings
Since the FastGPT shell inherits from comint-mode
indirectly, many key bindings are also inherited. 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.
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:
(keymap-set fastgpt-shell-mode-map "C-c C-o" #'browse-url-at-point)
Changelog
0.2pre
Breaking changes
-
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.
Old name New name kagi-api-fastgpt-url
kagi-fastgpt-api-url
kagi-api-summarizer-url
kagi-summarizer-api-url
kagi-summarize-default-language
kagi-summarizer-default-language
Fixes
- Fix bug when summarized text contains an URL ( )
0.1
Initial release.
References
- Kagi FastGPT API
- Kagi Universal Summarizer API
- xenodium's chatgpt-shell, which also provides shell-maker required by the FastGPT shell.