kirha 0.1.0__tar.gz

kirha-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kirha-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: kirha
+Version: 0.1.0
+Summary: Official Python SDK for the Kirha Search and Tools API
+Keywords: kirha,search,ai,api,sdk
+Author: Kirha
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Dist: httpx>=0.27,<1
+Requires-Python: >=3.10
+Project-URL: Homepage, https://kirha.com
+Project-URL: Documentation, https://docs.kirha.com
+Project-URL: Repository, https://github.com/kirha-ai/kirha-sdk-python
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kirha-ai/kirha-sdk-python/main/assets/banner.png" alt="KIRHA SDK" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/kirha/"><img src="https://img.shields.io/pypi/v/kirha" alt="PyPI version" /></a>
+  <a href="https://github.com/kirha-ai/kirha-sdk-python/actions/workflows/ci.yml"><img src="https://github.com/kirha-ai/kirha-sdk-python/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://pypi.org/project/kirha/"><img src="https://img.shields.io/pypi/pyversions/kirha" alt="Python versions" /></a>
+</p>
+
+<p align="center">
+  <a href="https://kirha.com"><b>🦋 KIRHA</b></a> •
+  <a href="https://docs.kirha.com"><b>📚 Documentation</b></a> •
+  <a href="https://app.kirha.com/auth/register"><b>🔑 Get an API key</b></a>
+</p>
+
+# KIRHA SDK
+
+Python SDK for the KIRHA Search and Tools APIs.
+
+## Installation
+
+```bash
+pip install kirha
+# or
+uv add kirha
+# or
+poetry add kirha
+```
+
+Requires Python 3.10 or later.
+
+## Quick Start
+
+```python
+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
+
+```python
+kirha = Kirha(api_key="your-api-key")
+
+result = kirha.search("Summarize latest NVIDIA earning calls", summarization=True)
+
+print(result.summary)
+```
+
+### Summarization with instruction
+
+```python
+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.
+
+```python
+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
+
+```python
+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
+
+```python
+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](https://github.com/kirha-ai/kirha-sdk-python/blob/main/docs/search-api.md) - Full API reference
+- [Examples](https://github.com/kirha-ai/kirha-sdk-python/tree/main/examples) - Runnable scripts
+
+## Errors
+
+| Error | Description |
+|-------|-------------|
+| `KirhaError` | Base error class |
+| `ConfigurationError` | No API key passed and `KIRHA_API_KEY` not set |
+| `ApiError` | API returned an error, with `status_code`, `code` and `details` |
+| `AuthenticationError` | Invalid or missing API key (401) |
+| `RateLimitError` | Rate limit exceeded (429), with `retry_after` in seconds |
+| `PlanExpiredError` | Plan expired (5 minute limit) |
+| `NetworkError` | Network/connection failure or timeout |
+
+`AuthenticationError` and `RateLimitError` extend `ApiError`.
+
+## Development
+
+```bash
+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](https://github.com/kirha-ai/kirha-sdk-python/actions/workflows/publish.yml), which checks that the tag matches the package version, runs the tests, builds the package and uploads it to [PyPI](https://pypi.org/project/kirha/) through trusted publishing. No PyPI token is stored in the repository.
+
+## License
+
+MIT

kirha-0.1.0/README.md

@@ -0,0 +1,160 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/kirha-ai/kirha-sdk-python/main/assets/banner.png" alt="KIRHA SDK" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/kirha/"><img src="https://img.shields.io/pypi/v/kirha" alt="PyPI version" /></a>
+  <a href="https://github.com/kirha-ai/kirha-sdk-python/actions/workflows/ci.yml"><img src="https://github.com/kirha-ai/kirha-sdk-python/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://pypi.org/project/kirha/"><img src="https://img.shields.io/pypi/pyversions/kirha" alt="Python versions" /></a>
+</p>
+
+<p align="center">
+  <a href="https://kirha.com"><b>🦋 KIRHA</b></a> •
+  <a href="https://docs.kirha.com"><b>📚 Documentation</b></a> •
+  <a href="https://app.kirha.com/auth/register"><b>🔑 Get an API key</b></a>
+</p>
+
+# KIRHA SDK
+
+Python SDK for the KIRHA Search and Tools APIs.
+
+## Installation
+
+```bash
+pip install kirha
+# or
+uv add kirha
+# or
+poetry add kirha
+```
+
+Requires Python 3.10 or later.
+
+## Quick Start
+
+```python
+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
+
+```python
+kirha = Kirha(api_key="your-api-key")
+
+result = kirha.search("Summarize latest NVIDIA earning calls", summarization=True)
+
+print(result.summary)
+```
+
+### Summarization with instruction
+
+```python
+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.
+
+```python
+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
+
+```python
+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
+
+```python
+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](https://github.com/kirha-ai/kirha-sdk-python/blob/main/docs/search-api.md) - Full API reference
+- [Examples](https://github.com/kirha-ai/kirha-sdk-python/tree/main/examples) - Runnable scripts
+
+## Errors
+
+| Error | Description |
+|-------|-------------|
+| `KirhaError` | Base error class |
+| `ConfigurationError` | No API key passed and `KIRHA_API_KEY` not set |
+| `ApiError` | API returned an error, with `status_code`, `code` and `details` |
+| `AuthenticationError` | Invalid or missing API key (401) |
+| `RateLimitError` | Rate limit exceeded (429), with `retry_after` in seconds |
+| `PlanExpiredError` | Plan expired (5 minute limit) |
+| `NetworkError` | Network/connection failure or timeout |
+
+`AuthenticationError` and `RateLimitError` extend `ApiError`.
+
+## Development
+
+```bash
+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](https://github.com/kirha-ai/kirha-sdk-python/actions/workflows/publish.yml), which checks that the tag matches the package version, runs the tests, builds the package and uploads it to [PyPI](https://pypi.org/project/kirha/) through trusted publishing. No PyPI token is stored in the repository.
+
+## License
+
+MIT

kirha-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "kirha"
+version = "0.1.0"
+description = "Official Python SDK for the Kirha Search and Tools API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1"]
+keywords = [
+    "kirha",
+    "search",
+    "ai",
+    "api",
+    "sdk",
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "Kirha"
+
+[project.urls]
+Homepage = "https://kirha.com"
+Documentation = "https://docs.kirha.com"
+Repository = "https://github.com/kirha-ai/kirha-sdk-python"
+
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.4.0",
+    "pytest>=9.1.1",
+    "respx>=0.23.1",
+    "ruff>=0.17.0",
+]
+
+[tool.mypy]
+strict = true
+files = [
+    "src",
+    "tests",
+    "examples",
+]
+
+[tool.pytest]
+addopts = [
+    "-m",
+    "not integration",
+]
+markers = ["integration: calls the live Kirha API, needs KIRHA_API_KEY"]

kirha-0.1.0/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[project]
+name = "kirha"
+version = "0.1.0"
+description = "Official Python SDK for the Kirha Search and Tools API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kirha" }]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1"]
+keywords = ["kirha", "search", "ai", "api", "sdk"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://kirha.com"
+Documentation = "https://docs.kirha.com"
+Repository = "https://github.com/kirha-ai/kirha-sdk-python"
+
+[build-system]
+requires = ["uv_build>=0.13.0,<0.14"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["mypy>=2.4.0", "pytest>=9.1.1", "respx>=0.23.1", "ruff>=0.17.0"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests", "examples"]
+
+[tool.pytest]
+addopts = ["-m", "not integration"]
+markers = ["integration: calls the live Kirha API, needs KIRHA_API_KEY"]

kirha-0.1.0/src/kirha/__init__.py

@@ -0,0 +1,44 @@
+from ._client import AsyncKirha, AsyncPlan, Kirha, Plan
+from ._errors import (
+    ApiError,
+    AuthenticationError,
+    ConfigurationError,
+    KirhaError,
+    NetworkError,
+    PlanExpiredError,
+    RateLimitError,
+)
+from ._models import (
+    Account,
+    Planning,
+    PlanningRuntime,
+    PlanStep,
+    SearchResult,
+    Summarization,
+    Tool,
+    ToolExecutionResult,
+    Usage,
+)
+
+__all__ = [
+    "Account",
+    "ApiError",
+    "AsyncKirha",
+    "AsyncPlan",
+    "AuthenticationError",
+    "ConfigurationError",
+    "Kirha",
+    "KirhaError",
+    "NetworkError",
+    "Plan",
+    "PlanExpiredError",
+    "PlanStep",
+    "Planning",
+    "PlanningRuntime",
+    "RateLimitError",
+    "SearchResult",
+    "Summarization",
+    "Tool",
+    "ToolExecutionResult",
+    "Usage",
+]

kirha-0.1.0/src/kirha/_client.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeVar
+
+import httpx
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+from ._errors import (
+    ApiError,
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    PlanExpiredError,
+    RateLimitError,
+)
+from ._models import (
+    Account,
+    PlanningRuntime,
+    PlanStep,
+    SearchResult,
+    Summarization,
+    Tool,
+    ToolExecutionResult,
+    Usage,
+    parse_plan,
+    parse_search_result,
+    parse_tool_execution_result,
+    parse_tools,
+)
+
+BASE_URL = "https://api.kirha.com"
+DEFAULT_TIMEOUT = 120.0
+PLAN_EXPIRED_CODE = "CONVERSATION_TURN_TIMEOUT"
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, kw_only=True)
+class _PlanFields:
+    id: str
+    query: str
+    focus: str | None
+    status: str
+    steps: list[PlanStep]
+    usage: Usage
+    account: Account
+    reason: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class Plan(_PlanFields):
+    _client: Kirha = field(repr=False, compare=False)
+    _summarization: bool | Summarization | None = field(
+        default=None, repr=False, compare=False
+    )
+
+    def execute(
+        self,
+        *,
+        summarization: bool | Summarization | None = None,
+        include_data: bool | None = None,
+        include_planning: bool | None = None,
+    ) -> SearchResult:
+        if summarization is None:
+            summarization = self._summarization
+        return self._client.execute_plan(
+            self.id,
+            summarization=summarization,
+            include_data=include_data,
+            include_planning=include_planning,
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class AsyncPlan(_PlanFields):
+    _client: AsyncKirha = field(repr=False, compare=False)
+    _summarization: bool | Summarization | None = field(
+        default=None, repr=False, compare=False
+    )
+
+    async def execute(
+        self,
+        *,
+        summarization: bool | Summarization | None = None,
+        include_data: bool | None = None,
+        include_planning: bool | None = None,
+    ) -> SearchResult:
+        if summarization is None:
+            summarization = self._summarization
+        return await self._client.execute_plan(
+            self.id,
+            summarization=summarization,
+            include_data=include_data,
+            include_planning=include_planning,
+        )
+
+
+class _BaseClient:
+    def __init__(
+        self,
+        api_key: str | None,
+        focus: str | None,
+        summarization: bool | Summarization | None,
+    ) -> None:
+        api_key = api_key or os.environ.get("KIRHA_API_KEY")
+        if not api_key:
+            raise ConfigurationError(
+                "api_key is required: pass it or set KIRHA_API_KEY"
+            )
+        self._headers = {"Authorization": f"Bearer {api_key}"}
+        self._focus = focus
+        self._summarization = summarization
+
+    def _search_body(
+        self,
+        query: str,
+        focus: str | None,
+        summarization: bool | Summarization | None,
+        include_data: bool | None,
+        include_planning: bool | None,
+        planning_runtime: PlanningRuntime | None,
+    ) -> dict[str, Any]:
+        return _compact(
+            query=query,
+            focus=self._resolve_focus(focus),
+            summarization=self._summarization_body(summarization),
+            include_raw_data=include_data,
+            include_planning=include_planning,
+            planning_runtime=planning_runtime,
+        )
+
+    def _plan_body(
+        self, query: str, focus: str | None, planning_runtime: PlanningRuntime | None
+    ) -> dict[str, Any]:
+        return _compact(
+            query=query,
+            focus=self._resolve_focus(focus),
+            planning_runtime=planning_runtime,
+        )
+
+    def _run_body(
+        self,
+        plan_id: str,
+        summarization: bool | Summarization | None,
+        include_data: bool | None,
+        include_planning: bool | None,
+    ) -> dict[str, Any]:
+        return _compact(
+            id=plan_id,
+            summarization=self._summarization_body(summarization),
+            include_raw_data=include_data,
+            include_planning=include_planning,
+        )
+
+    def _resolve_focus(self, focus: str | None) -> str | None:
+        return (self._focus if focus is None else focus) or None
+
+    def _summarization_body(
+        self, summarization: bool | Summarization | None
+    ) -> dict[str, Any] | None:
+        value = self._summarization if summarization is None else summarization
+        if isinstance(value, dict):
+            return _compact(enable=True, instruction=value.get("instruction"))
+        return {"enable": True} if value else None
+
+
+class Kirha(_BaseClient):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        focus: str | None = None,
+        summarization: bool | Summarization | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        super().__init__(api_key, focus, summarization)
+        self._http = httpx.Client(
+            base_url=BASE_URL, headers=self._headers, timeout=timeout
+        )
+
+    def search(
+        self,
+        query: str,
+        *,
+        focus: str | None = None,
+        summarization: bool | Summarization | None = None,
+        include_data: bool | None = None,
+        include_planning: bool | None = None,
+        planning_runtime: PlanningRuntime | None = None,
+    ) -> SearchResult:
+        body = self._search_body(
+            query,
+            focus,
+            summarization,
+            include_data,
+            include_planning,
+            planning_runtime,
+        )
+        return self._request("POST", "/search/v1", parse_search_result, json=body)
+
+    def plan(
+        self,
+        query: str,
+        *,
+        focus: str | None = None,
+        summarization: bool | Summarization | None = None,
+        planning_runtime: PlanningRuntime | None = None,
+    ) -> Plan:
+        body = self._plan_body(query, focus, planning_runtime)
+        fields = self._request("POST", "/search/v1/plan", parse_plan, json=body)
+        return Plan(
+            **fields,
+            query=query,
+            focus=body.get("focus"),
+            _client=self,
+            _summarization=summarization,
+        )
+
+    def execute_plan(
+        self,
+        plan_id: str,
+        *,
+        summarization: bool | Summarization | None = None,
+        include_data: bool | None = None,
+        include_planning: bool | None = None,
+    ) -> SearchResult:
+        body = self._run_body(plan_id, summarization, include_data, include_planning)
+        try:
+            return self._request(
+                "POST", "/search/v1/plan/run", parse_search_result, json=body
+            )
+        except ApiError as error:
+            if error.code == PLAN_EXPIRED_CODE:
+                raise PlanExpiredError(plan_id) from error
+            raise
+
+    def tools(self, *, focus: str) -> list[Tool]:
+        return self._request(
+            "GET", "/tools/v1", parse_tools, params={"vertical_id": focus}
+        )
+
+    def execute_tool(
+        self, tool_name: str, input: dict[str, Any] | None = None
+    ) -> ToolExecutionResult:
+        body = {"tool_name": tool_name, "input": input or {}}
+        return self._request(
+            "POST", "/tools/v1/execute", parse_tool_execution_result, json=body
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def _request(
+        self, method: str, path: str, parse: Callable[[Any], T], **kwargs: Any
+    ) -> T:
+        try:
+            response = self._http.request(method, path, **kwargs)
+        except httpx.TransportError as error:
+            raise NetworkError(
+                f"Request to {BASE_URL}{path} failed: {error!r}"
+            ) from error
+        return _handle(response, parse)
+
+
+class AsyncKirha(_BaseClient):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        focus: str | None = None,
+        summarization: bool | Summarization | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        super().__init__(api_key, focus, summarization)
+        self._http = httpx.AsyncClient(
+            base_url=BASE_URL, headers=self._headers, timeout=timeout
+        )
+
+    async def search(
+        self,
+        query: str,
+        *,
+        focus: str | None = None,
+        summarization: bool | Summarization | None = None,
+        include_data: bool | None = None,
+        include_planning: bool | None = None,
+        planning_runtime: PlanningRuntime | None = None,
+    ) -> SearchResult:
+        body = self._search_body(
+            query,
+            focus,
+            summarization,
+            include_data,
+            include_planning,
+            planning_runtime,
+        )
+        return await self._request("POST", "/search/v1", parse_search_result, json=body)
+
+    async def plan(
+        self,
+        query: str,
+        *,
+        focus: str | None = None,
+        summarization: bool | Summarization | None = None,
+        planning_runtime: PlanningRuntime | None = None,
+    ) -> AsyncPlan:
+        body = self._plan_body(query, focus, planning_runtime)
+        fields = await self._request("POST", "/search/v1/plan", parse_plan, json=body)
+        return AsyncPlan(
+            **fields,
+            query=query,
+            focus=body.get("focus"),
+            _client=self,
+            _summarization=summarization,
+        )
+
+    async def execute_plan(
+        self,
+        plan_id: str,
+        *,
+        summarization: bool | Summarization | None = None,
+        include_data: bool | None = None,
+        include_planning: bool | None = None,
+    ) -> SearchResult:
+        body = self._run_body(plan_id, summarization, include_data, include_planning)
+        try:
+            return await self._request(
+                "POST", "/search/v1/plan/run", parse_search_result, json=body
+            )
+        except ApiError as error:
+            if error.code == PLAN_EXPIRED_CODE:
+                raise PlanExpiredError(plan_id) from error
+            raise
+
+    async def tools(self, *, focus: str) -> list[Tool]:
+        return await self._request(
+            "GET", "/tools/v1", parse_tools, params={"vertical_id": focus}
+        )
+
+    async def execute_tool(
+        self, tool_name: str, input: dict[str, Any] | None = None
+    ) -> ToolExecutionResult:
+        body = {"tool_name": tool_name, "input": input or {}}
+        return await self._request(
+            "POST", "/tools/v1/execute", parse_tool_execution_result, json=body
+        )
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def _request(
+        self, method: str, path: str, parse: Callable[[Any], T], **kwargs: Any
+    ) -> T:
+        try:
+            response = await self._http.request(method, path, **kwargs)
+        except httpx.TransportError as error:
+            raise NetworkError(
+                f"Request to {BASE_URL}{path} failed: {error!r}"
+            ) from error
+        return _handle(response, parse)
+
+
+def _compact(**fields: Any) -> dict[str, Any]:
+    return {key: value for key, value in fields.items() if value is not None}
+
+
+def _handle(response: httpx.Response, parse: Callable[[Any], T]) -> T:
+    if not response.is_success:
+        raise _api_error(response)
+    try:
+        return parse(response.json())
+    except (ValueError, KeyError, TypeError, AttributeError) as error:
+        raise ApiError(
+            "Unexpected response from the Kirha API",
+            response.status_code,
+            "invalid_response",
+            response.text,
+        ) from error
+
+
+def _api_error(response: httpx.Response) -> ApiError:
+    status = response.status_code
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+
+    nested = body.get("error") if isinstance(body, dict) else None
+    if isinstance(nested, dict) and "message" in nested:
+        message = nested["message"]
+        code = nested.get("code", "unknown_error")
+        details = nested.get("details")
+    elif isinstance(body, dict) and "reason" in body:
+        message, code, details = body["reason"], body.get("type", "unknown_error"), None
+    else:
+        message = f"HTTP {status}: {response.reason_phrase}"
+        code, details = "unknown_error", body
+
+    if status == 401:
+        return AuthenticationError(message, status, code, details)
+    if status == 429:
+        retry_after = response.headers.get("Retry-After", "")
+        return RateLimitError(
+            message,
+            status,
+            code,
+            details,
+            int(retry_after) if retry_after.isdigit() else None,
+        )
+    return ApiError(message, status, code, details)

kirha-0.1.0/src/kirha/_errors.py

@@ -0,0 +1,46 @@
+from typing import Any
+
+
+class KirhaError(Exception):
+    pass
+
+
+class ConfigurationError(KirhaError):
+    pass
+
+
+class ApiError(KirhaError):
+    def __init__(
+        self, message: str, status_code: int, code: str, details: Any = None
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+
+
+class AuthenticationError(ApiError):
+    pass
+
+
+class RateLimitError(ApiError):
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        code: str,
+        details: Any = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message, status_code, code, details)
+        self.retry_after = retry_after
+
+
+class PlanExpiredError(KirhaError):
+    def __init__(self, plan_id: str) -> None:
+        super().__init__(f"Plan {plan_id} has expired (plans are valid for 5 minutes)")
+        self.plan_id = plan_id
+
+
+class NetworkError(KirhaError):
+    pass

kirha-0.1.0/src/kirha/_models.py

@@ -0,0 +1,137 @@
+from dataclasses import dataclass, field
+from typing import Any, Literal, TypedDict
+
+PlanningRuntime = Literal["standard", "fast"]
+
+
+class Summarization(TypedDict, total=False):
+    instruction: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Usage:
+    estimated: float
+    consumed: float
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Account:
+    balance: float
+    balance_timestamp: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PlanStep:
+    id: str
+    status: str
+    tool_name: str
+    parameters: dict[str, Any]
+    reasoning: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Planning:
+    status: str
+    steps: list[PlanStep]
+    reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SearchResult:
+    id: str
+    usage: Usage
+    account: Account
+    summary: str | None = None
+    data: list[dict[str, Any]] | None = None
+    planning: Planning | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Tool:
+    id: str
+    name: str
+    description: str
+    input_schema: dict[str, Any] = field(default_factory=dict)
+    output_schema: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ToolExecutionResult:
+    tool_name: str
+    output: Any
+    is_error: bool
+    usage: Usage
+    error_message: str | None = None
+
+
+def parse_usage(data: Any) -> Usage:
+    return Usage(estimated=data["estimated"], consumed=data["consumed"])
+
+
+def parse_account(data: Any) -> Account:
+    return Account(balance=data["balance"], balance_timestamp=data["balance_timestamp"])
+
+
+def parse_steps(data: Any) -> list[PlanStep]:
+    return [
+        PlanStep(
+            id=step["id"],
+            status=step["status"],
+            tool_name=step["tool_name"],
+            parameters=step["parameters"],
+            reasoning=step.get("reasoning"),
+        )
+        for step in data
+    ]
+
+
+def parse_search_result(data: Any) -> SearchResult:
+    planning = data.get("planning")
+    return SearchResult(
+        id=data["id"],
+        usage=parse_usage(data["usage"]),
+        account=parse_account(data["account"]),
+        summary=data.get("summary"),
+        data=data.get("raw_data"),
+        planning=Planning(
+            status=planning["status"],
+            steps=parse_steps(planning["steps"]),
+            reason=planning.get("reason"),
+        )
+        if planning
+        else None,
+    )
+
+
+def parse_plan(data: Any) -> dict[str, Any]:
+    return {
+        "id": data["id"],
+        "status": data["status"],
+        "steps": parse_steps(data["steps"]),
+        "usage": parse_usage(data["usage"]),
+        "account": parse_account(data["account"]),
+        "reason": data.get("reason"),
+    }
+
+
+def parse_tools(data: Any) -> list[Tool]:
+    return [
+        Tool(
+            id=tool["id"],
+            name=tool["name"],
+            description=tool["description"],
+            input_schema=tool.get("input_schema") or {},
+            output_schema=tool.get("output_schema") or {},
+        )
+        for tool in data
+    ]
+
+
+def parse_tool_execution_result(data: Any) -> ToolExecutionResult:
+    return ToolExecutionResult(
+        tool_name=data["tool_name"],
+        output=data["output"],
+        is_error=data["is_error"],
+        usage=parse_usage(data["usage"]),
+        error_message=data.get("error_message"),
+    )