|
| 1 | +--- |
| 2 | +title: Kai Python Client |
| 3 | +permalink: /kai/python-client/ |
| 4 | +--- |
| 5 | + |
| 6 | +* TOC |
| 7 | +{:toc} |
| 8 | + |
| 9 | +The [Kai Python Client](https://github.com/keboola/kai-client) is an official Python library for interacting with the Kai API programmatically. It provides async support, SSE streaming, a command-line interface, and comprehensive type safety through Pydantic models. |
| 10 | + |
| 11 | +## Features |
| 12 | + |
| 13 | +- **Command-line interface** for quick interactions without writing code |
| 14 | +- **Real-time streaming** — see responses as they arrive |
| 15 | +- **Conversation management** — maintain context across multiple messages |
| 16 | +- **Tool approval flows** — review and approve Kai actions programmatically |
| 17 | +- **Full API coverage** — chat, history, and feedback |
| 18 | + |
| 19 | +## Installation |
| 20 | + |
| 21 | +### Using uv (recommended) |
| 22 | + |
| 23 | +```bash |
| 24 | +uv add kai-client |
| 25 | +``` |
| 26 | + |
| 27 | +### Using pip |
| 28 | + |
| 29 | +```bash |
| 30 | +pip install kai-client |
| 31 | +``` |
| 32 | + |
| 33 | +## Prerequisites |
| 34 | + |
| 35 | +The Kai Python Client requires a [Master Token](/management/project/tokens/#master-tokens) to authenticate with the Keboola API. Standard tokens with limited permissions will not work. You can create a Master Token in your project's **Settings → API Tokens**. |
| 36 | + |
| 37 | +## Quick Start |
| 38 | + |
| 39 | +```python |
| 40 | +import asyncio |
| 41 | +from kai_client import KaiClient |
| 42 | + |
| 43 | +async def main(): |
| 44 | + # Auto-discover the Kai API URL from your Keboola stack |
| 45 | + client = await KaiClient.from_storage_api( |
| 46 | + storage_api_token="your-master-token", |
| 47 | + storage_api_url="https://connection.keboola.com" # Your stack URL |
| 48 | + ) |
| 49 | + |
| 50 | + async with client: |
| 51 | + # Start a new chat |
| 52 | + chat_id = client.new_chat_id() |
| 53 | + |
| 54 | + # Send a message and stream the response |
| 55 | + async for event in client.send_message(chat_id, "What tables do I have?"): |
| 56 | + if event.type == "text": |
| 57 | + print(event.text, end="", flush=True) |
| 58 | + elif event.type == "tool-call": |
| 59 | + print(f"\n[Calling tool: {event.tool_name}]") |
| 60 | + elif event.type == "finish": |
| 61 | + print(f"\n[Finished: {event.finish_reason}]") |
| 62 | + |
| 63 | +asyncio.run(main()) |
| 64 | +``` |
| 65 | + |
| 66 | +## Command-Line Interface |
| 67 | + |
| 68 | +The package includes a `kai` CLI for quick interactions without writing code. |
| 69 | + |
| 70 | +### Setup |
| 71 | + |
| 72 | +Set your credentials as environment variables: |
| 73 | + |
| 74 | +```bash |
| 75 | +export STORAGE_API_TOKEN="your-master-token" |
| 76 | +export STORAGE_API_URL="https://connection.keboola.com" |
| 77 | +``` |
| 78 | + |
| 79 | +### Commands |
| 80 | + |
| 81 | +```bash |
| 82 | +kai ping # Check server health |
| 83 | +kai info # Show server version and info |
| 84 | +kai chat # Start an interactive chat session |
| 85 | +kai chat -m "List my tables" # Send a single message |
| 86 | +kai chat --auto-approve -m "..." # Auto-approve tool calls |
| 87 | +kai history # View recent chat history |
| 88 | +kai get-chat <chat-id> # Get full chat details |
| 89 | +kai delete-chat <chat-id> # Delete a chat |
| 90 | +``` |
| 91 | + |
| 92 | +In interactive mode, type your messages and press Enter. Type `exit`, `quit`, or press Ctrl+C to end. |
| 93 | + |
| 94 | +**Tool approval:** When Kai calls a write tool (e.g., `update_descriptions`, `run_job`, `create_config`), the CLI pauses and asks you to approve or deny. Use `--auto-approve` to skip this prompt. |
| 95 | + |
| 96 | +For more usage examples (non-streaming chat, conversations, tool calls, tool approval, error handling), see the [client README](https://github.com/keboola/kai-client#readme). |
| 97 | + |
| 98 | +## Use Cases |
| 99 | + |
| 100 | +### Integrating Kai into Data Apps |
| 101 | + |
| 102 | +The Kai Python Client can be embedded into Keboola [Data Apps](/data-apps/) to provide AI-powered chat interfaces for your end users. |
| 103 | + |
| 104 | +**Important:** Data Apps are automatically provisioned with a Storage API token, but this built-in token is **not** a master token and is insufficient for the Kai Client. You must pass a [Master Token](/management/project/tokens/#master-tokens) explicitly — for example, via a [secret environment variable](/data-apps/python-js/#secrets) in your Data App configuration. |
| 105 | + |
| 106 | +#### Python/JS Data Apps |
| 107 | + |
| 108 | +You can integrate Kai into [Python/JS Data Apps](/data-apps/python-js/) today using the Kai Python Client directly. A dedicated plugin with ready-made patterns will be available soon to simplify the setup. |
| 109 | + |
| 110 | +#### Streamlit Data Apps |
| 111 | + |
| 112 | +The [kai-streamlit plugin](https://github.com/keboola/kai-client/tree/main/plugins/kai-streamlit) provides patterns and working code for building [Streamlit Data Apps](/data-apps/streamlit/) with an integrated Kai chat interface. It handles the async bridge between Streamlit's synchronous model and the KaiClient's async API, streaming responses into Streamlit containers, tool approval flows with interactive Approve/Deny buttons, and session state management across Streamlit reruns. |
| 113 | + |
| 114 | +To get started, install the dependencies: |
| 115 | + |
| 116 | +```bash |
| 117 | +pip install kai-client streamlit |
| 118 | +``` |
| 119 | + |
| 120 | +Then use the `run_async` bridge pattern to call KaiClient from Streamlit: |
| 121 | + |
| 122 | +```python |
| 123 | +import asyncio |
| 124 | +from kai_client import KaiClient |
| 125 | + |
| 126 | +def run_async(coro): |
| 127 | + """Run an async coroutine from sync Streamlit code.""" |
| 128 | + loop = asyncio.new_event_loop() |
| 129 | + try: |
| 130 | + return loop.run_until_complete(coro) |
| 131 | + finally: |
| 132 | + loop.close() |
| 133 | +``` |
| 134 | + |
| 135 | +See the [plugin repository](https://github.com/keboola/kai-client/tree/main/plugins/kai-streamlit) for a complete working example with streaming, tool approval, and suggested action buttons. |
| 136 | + |
| 137 | +### Kai via CLI with Claude Code |
| 138 | + |
| 139 | +The [kai-cli plugin](https://github.com/keboola/kai-client/tree/main/plugins/kai-cli) lets AI coding assistants like [Claude Code](https://claude.com/claude-code) interact with your Keboola project through the Kai CLI. Install the plugin to give Claude the ability to query data, manage configurations, run jobs, and troubleshoot issues — all through natural language in your terminal. |
| 140 | + |
| 141 | +#### Installation |
| 142 | + |
| 143 | +Download the plugin to your Claude Code plugins directory: |
| 144 | + |
| 145 | +```bash |
| 146 | +mkdir -p ~/.claude/plugins |
| 147 | + |
| 148 | +curl -L https://github.com/keboola/kai-client/archive/refs/heads/main.tar.gz | \ |
| 149 | + tar -xz --strip-components=2 -C ~/.claude/plugins kai-client-main/plugins/kai-cli |
| 150 | +``` |
| 151 | + |
| 152 | +Or clone and link for development: |
| 153 | + |
| 154 | +```bash |
| 155 | +git clone https://github.com/keboola/kai-client.git |
| 156 | +ln -s "$(pwd)/kai-client/plugins/kai-cli" ~/.claude/plugins/kai-cli |
| 157 | +``` |
| 158 | + |
| 159 | +Once installed, ask Claude to "use kai" or "help me with kai cli" to activate the skill. Claude can then run `kai chat`, `kai history`, `kai ping`, and other CLI commands on your behalf. |
| 160 | + |
| 161 | +## Resources |
| 162 | + |
| 163 | +- [GitHub Repository](https://github.com/keboola/kai-client) |
| 164 | +- [PyPI Package](https://pypi.org/project/kai-client/) |
| 165 | +- [Kai Documentation](/kai/) |
0 commit comments