nucleardog/kagi

Use the Kagi API

v1.0.0 2025-04-04 23:55 UTC

Requires

• php: ^8.4
• php-http/discovery: ^1.20
• psr/http-client-implementation: ^1.0
• psr/http-factory-implementation: ^1.0

Requires (Dev)

• guzzlehttp/guzzle: ^7.9
• guzzlehttp/psr7: ^2.7

Apache-2.0

• Adam Pippin

README

A PHP SDK for Kagi's API

Setup

Installation

composer require nucleardog/kagi

Kagi

You will need an API token and your account funded for API usage.

See Kagi's API documentation for steps on generating a token.

Please note:

• You will accrue charges for all API usage.
• In particular, note that summarizing with the MURIEL engine costs $1/request.
• The Search API is currently in beta and only available by contacting Kagi.

Laravel

Configuration

A default configuration is provided that will work out of the box if you set the KAGI_TOKEN environment variable to your API token.

If you would like to customize this, set up multiple connections for different API tokens, etc, you can customize this by publishing the configuration from this package with artisan vendor:publish.

Client

You can access the client through the provided facade and begin calling methods directly:

<?php

use Nucleardog\Kagi\Support\Facades\Kagi;

$response = Kagi::search(...);

$response = Kagi::connection('my-other-connection')->search(...);

Other or No Framework

Client

Create a client via the KagiFactory class, passing your token in:

<?php

use Nucleardog\Kagi\KagiFactory;

$factory = new KagiFactory();
$client = $factory->build([
	'token' => 'your-api-token',
]);

$response = $client->search(...);

Usage

FastGPT

FastGPT is a Kagi service using powerful LLMs to answer user queries running a full search engine underneath. Think ChatGPT, but on steroids and faster!

Documentation

<?php
$response = $client->fastGpt('How far away is the moon?');

// You can print the plain text of the response:
echo $response;

// You can print the response, customizing the formatting of the references:
echo $response->format('(see #{index}');
echo $response->format('(from {url})');
echo $response->format(fn($token) => sprintf('(from %s)', parse_url($token->url, \PHP_URL_HOST)));

// You can separately fetch the references:
foreach ($response->references() as $reference) {
	echo sprintf(
		'%d: %s',
		$reference->index,
		$reference->title,
	);
}

// You can also loop the combined text and reference tokens:
foreach ($response as $token) {
	if ($token instanceof \Nucleardog\Kagi\Responses\FastGptText) {
		echo $token->text;
	} else if ($token instanceof \Nucleardog\Kagi\Responses\FastGptReference) {
		echo '['.$token->index.']';
	}
}

Enrich

The enrichment APIs are a collection of indexes that can be used to supplement other products with more novel and interesting content from around the web.

Enrichment APIs allow anyone to get Kagi's unique results, namely the Teclis index (web results) and TinyGem index (news) results.

They are best used for finding non-commercial websites and "small web" discussions surrounding a particular topic. The news enrichment API offers interesting discussions and news worth reading from typically non-mainstream sources.

They are not "general" search indexes that can answer any type of query but rather these results are our 'secret sauce' and what makes Kagi results unique and interesting and are best used in combination with a general results index.

Documentation

<?php

// The enrichment API offers two kinds of results:
$response = $client->enrichWeb('my search query');
$response = $client->enrichNews('election');

// The results can be accessed by iterating over the response.
foreach ($response as $result) {
	echo $result->title;
	echo $result->url;
	echo $result->snippet ?? '<no description provided>';
}

Search

The Search API gives programmable access to Kagi's premium search results.

[!NOTE] Beta This is a beta API and only available by contacting Kagi.

Documentation

<?php

// Fetch search results
$response = $client->search('my search query');

// The results can be accessed by iterating over the response.
foreach ($response as $result) {
	echo $result->title;
	echo $result->url;
	echo $result->snippet ?? '<no description provided>';
}

// You can also fetch "related search terms" provided by Kagi:
foreach ($response->related() as $term) {
	echo 'Related: '.$term;
}

Universal Summarizer

The Universal Summarizer is an API using powerful LLMs to summarize any content, of almost any format, with unlimited token length!

Documentation

<?php

// You can summarize text
$response = $client->summarizeText('My text');
// ... or URLs
$response = $client->summarizeUrl('https://en.wikipedia.org/wiki/Cuvette');
// (Kagi's API supports files as well, but those aren't implemented right now.)

// A builder object is returned, and the call is only made on casting to string.
$summarizedText = (string)$response;

// This allows you to make further customizations to the summarization query first:
$summarizedText = (string)$client->summarizeUrl('https://en.wikipedia.org/wiki/Cuvette')
	->withModel(\Nucleardog\Kagi\Summarizer\Model::AGNES)
	->withType(\Nucleardog\Kagi\Summarizer\Type::TAKEAWAY)
	->withLanguage(\Nucleardog\Kagi\Summarizer\Language::ENGLISH)
	->withCache(false);

echo $summarizedText;

Tests

Phpunit is included in a separate composer file and must be explicitly installed:

$ cd tools/phpunit/
$ composer install

Once installed, the tests can be run from the root package folder with:

$ composer test

Legal

Copyright 2024 Adam Pippin [e-mail]

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.