🦋 KIRHA • 📚 Documentation • 🔑 Get an API key

KIRHA SDK

Python SDK for the KIRHA Search and Tools APIs.

Installation

pip install kirha
# or
uv add kirha
# or
poetry add kirha

Requires Python 3.10 or later.

Quick Start

from kirha import Kirha

kirha = Kirha()

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

print(result.data)

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

Examples

Summarization

kirha = Kirha(api_key="your-api-key")

result = kirha.search("Summarize latest NVIDIA earning calls", summarization=True)

print(result.summary)

Summarization with instruction

kirha = Kirha(api_key="your-api-key")

result = kirha.search(
    "List top 10 stablecoins yield on Ethereum",
    summarization={
        "instruction": "Format the response as a table with columns: Stablecoin, Protocol, APY",
    },
)

print(result.summary)

Plan mode

Review the steps and the estimated cost before running the query, yourself or with an agent. Planning charges nothing until the plan runs.

kirha = Kirha(api_key="your-api-key")

plan = kirha.plan(
    "Find engineers working at companies behind the latest patents in Machine Learning",
)

print(plan.steps)
print(plan.usage)

result = plan.execute()
print(result.data)

A plan expires 5 minutes after it is created. To run it from another process, after an approval step for example, call kirha.execute_plan(plan_id).

Direct tool calling

tools = kirha.tools(focus="crypto")
print([tool.name for tool in tools])

result = kirha.execute_tool("coingecko_searchCoin", {"query": "avax", "limit": 1})
print(result.output)

Async

import asyncio

from kirha import AsyncKirha


async def main() -> None:
    async with AsyncKirha() as kirha:
        result = await kirha.search("What does the boxed warning on Ozempic say?")
        print(result.data)


asyncio.run(main())

AsyncKirha has the same methods as Kirha, as coroutines. Both clients keep a connection pool open, so close them with close() or use them as context managers.

Documentation

• Search API - Full API reference
• Examples - Runnable scripts

Errors

AuthenticationError and RateLimitError extend ApiError.

Development

uv sync
uv run pytest

uv run pytest -m integration runs the tests against the live API with your KIRHA_API_KEY. They spend credits.

Releasing

1. Bump version in pyproject.toml (for example uv version 0.2.0) and merge it to main.
2. Create a GitHub release with a tag matching that version, prefixed with v (for example v0.2.0).

Publishing the release runs the publish workflow, which checks that the tag matches the package version, runs the tests, builds the package and uploads it to PyPI through trusted publishing. No PyPI token is stored in the repository.

License

MIT