kirha logo

KIRHA SDKs

KIRHA has an official SDK for TypeScript and one for Python, both published as kirha. They handle authentication, tool planning, provider orchestration, and response parsing so you can focus on building your agent logic.

With either SDK you can:

  • Search across premium data providers with a single natural language query
  • Plan and execute workflows where you review providers and costs before running the query
  • Execute tools directly to give your agent access to the data providers without KIRHA's planning
  • Run the planner locally to plan queries on your own machine (TypeScript only)

Installation

npm install kirha
pnpm add kirha
yarn add kirha
bun add kirha
pip install kirha
uv add kirha
poetry add kirha

Requires Python 3.10 or later.

Setup

Initialize the client with your API key:

import { Kirha } from "kirha";

const kirha = new Kirha({ apiKey: process.env.KIRHA_API_KEY });
from kirha import Kirha

kirha = Kirha()

Kirha() reads your API key from the KIRHA_API_KEY environment variable. Pass api_key="..." to set it in code.

For asyncio, AsyncKirha has the same methods as coroutines:

from kirha import AsyncKirha

async with AsyncKirha() as kirha:
    result = await kirha.search("What does the boxed warning on Ozempic say?")

Run your first query

import { Kirha } from "kirha";

const kirha = new Kirha({ apiKey: process.env.KIRHA_API_KEY });

const result = await kirha.search("What does the boxed warning on Ozempic say?"); 
console.log(result.data); 
from kirha import Kirha

kirha = Kirha()

result = kirha.search("What does the boxed warning on Ozempic say?")  
print(result.data)  

KIRHA picks the providers across every vertical. To restrict a search to one vertical, pass focus, in the constructor or per query:

const result = await kirha.search("List top 10 stablecoins yield on Ethereum", {
  focus: "crypto", 
});
result = kirha.search(
    "List top 10 stablecoins yield on Ethereum",
    focus="crypto",  
)

Error handling

All errors extend the base KirhaError class:

ErrorDescription
ConfigurationErrorInvalid client configuration (missing API key, missing planner URL)
AuthenticationErrorInvalid or missing API key
RateLimitErrorRate limit exceeded (20 requests/min)
ValidationErrorInvalid request parameters
PlanExpiredErrorPlan executed more than 5 minutes after it was created
ApiErrorServer-side error
NetworkErrorConnection or timeout failure
ErrorDescription
ConfigurationErrorInvalid client configuration (missing API key)
AuthenticationErrorInvalid or missing API key
RateLimitErrorRate limit exceeded (20 requests/min)
PlanExpiredErrorPlan executed more than 5 minutes after it was created
ApiErrorServer-side error
NetworkErrorConnection or timeout failure

Rate limits

All API requests are rate-limited to 20 requests per minute per API key. Plans are valid for 5 minutes after creation. If you need a higher quota, feel free to reach out with your use case at developers@kirha.com.

Next steps

On this page