# kagi-api

Kagi API libraries and CLI written in Rust

## Using the kagi-api library

Until the library enters crates.io, you can add the following git dependency:

```toml
[dependencies]
kagi-api = { version = "0.1", git = "https://codeberg.org/synapse/kagi-api.git" }
```

```rust
use kagi_api::v0::FastGPT;

#[tokio::main]
async fn main() {
    let config = kagi_api::KagiConfig::with_api_key("api key goes here");
    let client = kagi_api::KagiClient::new(config);

    let use_cache = true;
    let answer = client
        .fastgpt("How do I entertain my cat?", use_cache)
        .await
        .expect("A valid FastGPT search result");

    // FIXME: Cannot `.render()` without kagi-cli: Remove `Render` trait's coupling from `Args`.
    serde_json::to_writer_pretty(std::io::stdout(), &answer).unwrap();
}
```

See the [`kagi-api/examples`](./kagi-api/examples/) directory for more examples.

FIXME: Examples are still unstable, port more examples here when stable.

## Using the kagi-cli binary

Install by cloning this repository, entering it, and running:

```sh
cargo install --path kagi-cli
```

Install auto-completion, possibly replacing `zsh` with `bash`, `fish`, `powershell` or `elvish`:

```sh
source <(kagi-cli completion zsh)
```

Set an environment variable containing your API key.

Setting a logdir is optional and enables record-and-replay.

```sh
KAGI_API_KEY="api key goes here"
KAGI_API_LOGDIR="."
```

You can now query:

> ```sh
> $ kagi-cli fast-gpt 'How do I entertain my cat?'
> ```
>
> ```md
> There are several ways to **entertain your cat**:
>
> **Provide toys for playing**, such as balls, feathers on strings or catnip toys. **Interactive play sessions** can also stimulate cats. [1][2]
>
> **Hide treats and food around the house in puzzle feeders** or new locations. This provides mental enrichment. [1][3][4]
>
> **Inexpensive items like cardboard boxes** or empty paper towel rolls can be entertaining for cats to bat around or hide in. [1][5][2]
>
> **Cats may enjoy watching fish tanks or nature documentaries on TV.** [6][7]
>
> - 1. Puzzle feeders 2. Hide the food in new locations 3. Put food in a kitty KONG 4. Put kibble or treats inside an egg carton 5. Teach your cat some tricks 6. Searching for food scent Games 7. Make a labyrinth out of boxes [1]
>
> - Toys that keep your indoor cat entertained. How to entertain indoor cats: Providing a wide variety of cat toys will ensure your feline is never bored. (Image credit: Getty) Most vets recommend a minimum of 15-30 minutes of play per day, which is for both exercise and bonding. [2]
>
> - 4. jan. 2021 ... 6 Ways to Keep Your Cat Entertained · 1. Add a Furry Friend. Cats are social creatures, and the majority enjoy having a companion. · 2. Prepare a... [3]
>
> - If your feline friend is food motivated, then treat based puzzles can be a fun, low maintenance way of keeping your cat entertained (and fed). [4]
>
> - To keep a bored indoor cat entertained while you&#39;re not at home, open up some of your blinds and curtains so your cat can look out the window. You can also try leaving your TV on with a nature show playing to give your cat something to watch. [5]
>
> - 3. jul. 2023 ... You don't need to fork out for expensive toys though, a simple cardboard box can keep a moggie thoroughly entertained. They also like to play... [6]
>
> - Many cats love catnip, so you can buy catnip-filled toys or give your cat loose catnip to make play time extra fun. Multi-tiered cat trees, which you can build yourself or buy at pet stores, can give your kitty something fun to romp around on when you&#39;re not home. [7]
>
> [1]: https://www.meowsnpaws.com/cat-entertainment/how-to-entertain-cat/
> [2]: https://www.petsradar.com/advice/how-to-entertain-indoor-cats-and-keep-them-stimulated
> [3]: https://rufusandcoco.com.au/blogs/blog/6-ways-to-keep-your-cat-entertained
> [4]: https://www.petsecure.com.au/pet-care/10-ways-keep-cat-entertained-youre-house/
> [5]: https://www.wikihow.com/Keep-a-Bored-Indoor-Cat-Entertained-While-You%27re-Not-at-Home
> [6]: https://www.petsradar.com/advice/is-your-cat-bored-10-tips-to-entertain-your-moggy
> [7]: https://www.wikihow.com/Have-Fun-with-Your-Cat
> ```

Replaying the same request-response, but changing the output format:

> ```sh
> $ kagi-cli --replay -f json fast-gpt 'How do I entertain my cat?'
> ```
>
> ```json
> {
>   "meta": {
>     "id": "64872161-cae7-4ee0-a7b7-096f821bae75",
>     "node": "europe-west4",
>     "ms": 7512,
>     "api_balance": 0.0
>   },
>   "data": {
>     "output": "\nThere are several ways to **entertain your cat**:\n\n**Provide toys for playing**, such as balls, feathers on strings or catnip toys. **Interactive play sessions** can also stimulate cats. [1][2]\n\n**Hide treats and food around the house in puzzle feeders** or new locations. This provides mental enrichment. [1][3][4] \n\n**Inexpensive items like cardboard boxes** or empty paper towel rolls can be entertaining for cats to bat around or hide in. [1][5][2]\n\n**Cats may enjoy watching fish tanks or nature documentaries on TV.** [6][7]",
>     "tokens": 5921,
>     "references": [
>       {
>         "title": "50 Ways to Entertain Your Cat (+ Free PDF Printable)",
>         "snippet": "1. Puzzle feeders 2. Hide the food in new locations 3. Put food in a kitty KONG 4. Put kibble or treats inside an egg carton 5. Teach your cat some tricks 6. Searching for food scent Games 7. Make a labyrinth out of boxes",
>         "url": "https://www.meowsnpaws.com/cat-entertainment/how-to-entertain-cat/"
>       },
>       {
>         "title": "How to entertain indoor cats | PetsRadar",
>         "snippet": "Toys that keep your indoor cat entertained. How to entertain indoor cats: Providing a wide variety of cat toys will ensure your feline is never bored. (Image credit: Getty) Most vets recommend a minimum of 15-30 minutes of play per day, which is for both exercise and bonding.",
>         "url": "https://www.petsradar.com/advice/how-to-entertain-indoor-cats-and-keep-them-stimulated"
>       },
>       {
>         "title": "6 Ways to Keep Your Cat Entertained – Rufus & Coco Australia",
>         "snippet": "4. jan. 2021 ... 6 Ways to Keep Your Cat Entertained · 1. Add a Furry Friend. Cats are social creatures, and the majority enjoy having a companion. · 2. Prepare a...",
>         "url": "https://rufusandcoco.com.au/blogs/blog/6-ways-to-keep-your-cat-entertained"
>       },
>       {
>         "title": "10 Ways to Keep Your Cat Entertained While You're Out of the House",
>         "snippet": "If your feline friend is food motivated, then treat based puzzles can be a fun, low maintenance way of keeping your cat entertained (and fed).",
>         "url": "https://www.petsecure.com.au/pet-care/10-ways-keep-cat-entertained-youre-house/"
>       },
>       {
>         "title": "3 Ways to Keep a Bored Indoor Cat Entertained While You're ... - wikiHow",
>         "snippet": "To keep a bored indoor cat entertained while you&#39;re not at home, open up some of your blinds and curtains so your cat can look out the window. You can also try leaving your TV on with a nature show playing to give your cat something to watch.",
>         "url": "https://www.wikihow.com/Keep-a-Bored-Indoor-Cat-Entertained-While-You%27re-Not-at-Home"
>       },
>       {
>         "title": "Is your cat bored? | PetsRadar",
>         "snippet": "3. jul. 2023 ... You don't need to fork out for expensive toys though, a simple cardboard box can keep a moggie thoroughly entertained. They also like to play...",
>         "url": "https://www.petsradar.com/advice/is-your-cat-bored-10-tips-to-entertain-your-moggy"
>       },
>       {
>         "title": "How to Have Fun with Your Cat (with Pictures) - wikiHow",
>         "snippet": "Many cats love catnip, so you can buy catnip-filled toys or give your cat loose catnip to make play time extra fun. Multi-tiered cat trees, which you can build yourself or buy at pet stores, can give your kitty something fun to romp around on when you&#39;re not home.",
>         "url": "https://www.wikihow.com/Have-Fun-with-Your-Cat"
>       }
>     ]
>   }
> }
> ```

FIXME: Improve `cargo install kagi-cli` installation instructions when crate lands on crates.io.

FIXME: Provide examples as Rustdoc and export them here programmatically (one source, testable).

## Contributing

To contribute, install the Rust toolchain, e.g. using [rustup][rustup]:

```sh
curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
```

[rustup]: https://rustup.rs/

Fork the workspace containing library and CLI code:

```
git clone https://codeberg.org/synapse/kagi-api.git
```