#+title: kagi.el README
#+author: Bram Schoenmakers
#+macro: issue [[https://codeberg.org/bram85/kagi.el/issues/$1][issue #$1]]
#+macro: pr [[https://codeberg.org/bram85/kagi.el/pulls/$1][PR #$1]]
#+begin_export html
#+end_export
* Introduction
This Emacs package provides the following functionalities from the [[https://www.kagi.com][Kagi search engine]]:
- FastGPT :: Kagi's open source LLM offering, as a shell inspired by [[https://github.com/xenodium/chatgpt-shell][xenodium's chatgpt-shell]].
- Universal Summarizer :: Summarizes texts, webpages, videos and more.
Both functions are accessed through an [[https://help.kagi.com/kagi/api/overview.html][API]]. Before a call can be made, some setup should be done on the Kagi website (see below).
[[file:img/fastgpt.png]]
* 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 [[https://kagi.com/privacy#Summarizer][Privacy Policy]].
* Installation and configuration
kagi.el is available on [[https://melpa.org/#/kagi][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 [[https://melpa.org/#/shell-maker][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:
#+begin_src elisp
(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)))))
#+end_src
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 [[https://passwordstore.org/][pass(1)]] and the password-store package that comes with it).
** Kagi API setup
1. Create a Kagi account if you haven't done so already. An account is free, and comes with 100 trial searches.
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. A single query ranges from 1 to 5 cents typically, depending on the amount of tokens processed.
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).
** Configuration settings
#+begin_src emacs-lisp :exports results :results table :colnames '("Custom variable" "Description")
(let ((rows))
(mapatoms
(lambda (symbol)
(when (and (string-match "\\_