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:

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

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 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:

cargo install --path kagi-cli

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

source <(kagi-cli completion zsh)

Set an environment variable containing your API key.

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

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

You can now query:

$ kagi-cli fast-gpt 'How do I entertain my cat?'

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'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'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:

$ kagi-cli --replay -f json fast-gpt 'How do I entertain my cat?'

{
  "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'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'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:

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

Fork the workspace containing library and CLI code:

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