#+title: kagi.el README
#+author: Bram Schoenmakers

* 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 [[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]].

* 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~.

* Commands

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

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

* Installation and configuration

kagi.el is not on MELPA (yet?), so for now only Git access is possible.

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 nil
    :load-path "/path/to/kagi.el"
    :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-api-summarizer-engine "cecil")
    (kagi-api-summarize-default-language "EN"))
#+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. [[https://passwordstore.org/][pass(1)]]).

* References

- [[https://help.kagi.com/kagi/api/fastgpt.html][Kagi FastGPT API]]
- [[https://help.kagi.com/kagi/api/summarizer.html][Kagi Universal Summarizer API]]
- [[https://github.com/xenodium/chatgpt-shell][xenodium's chatgpt-shell]], which also provides shell-maker required by the FastGPT shell.