kamiwaza-sdk 0.9.0

Python client library for the Kamiwaza AI Platform

Kamiwaza Python SDK

Python client library for interacting with the Kamiwaza AI Platform. This SDK provides a type-safe interface to all Kamiwaza API endpoints with built-in authentication, error handling, and resource management.

Installation

pip install kamiwaza-sdk

Naming note: Install the package as kamiwaza-sdk, but import it as kamiwaza_sdk. A deprecated kamiwaza_client alias remains for older snippets, though new code should prefer kamiwaza_sdk.

Version compatibility: This SDK (version 0.5.1+) is incompatible with Kamiwaza versions before 0.5.1. Please ensure you're using the latest version of Kamiwaza.

Python SDK Usage

from kamiwaza_sdk import KamiwazaClient
from kamiwaza_sdk.authentication import UserPasswordAuthenticator
from kamiwaza_sdk.schemas.auth import PATCreate

client = KamiwazaClient("https://localhost/api")

# Option 1 (recommended): Personal Access Token
# export KAMIWAZA_API_KEY=<your-pat>
# client automatically loads the token and reuses it for every request.

# Option 2: bootstrap with username/password to mint a PAT
client.authenticator = UserPasswordAuthenticator("admin", "kamiwaza", client.auth)
pat = client.auth.create_pat(PATCreate(name="local-bootstrap")).token
print("Save this token:", pat)

Examples

The /examples directory contains Jupyter notebooks demonstrating various use cases:

1. Model Download and Deployment - A comprehensive guide to searching, downloading, deploying, and using models with the Kamiwaza SDK
2. Quick Model Deployment - Streamlined approach to download and deploy models using a single function
3. Model Evaluation - How to evaluate and benchmark multiple language models for performance comparison using the streamlined download_and_deploy_model function
4. Structured Output - Using Kamiwaza's OpenAI-compatible interface to generate structured outputs with specific JSON schemas
5. Function Calling - Demonstrates how to use function calling (tools) with Kamiwaza's OpenAI-compatible API
6. Web Agent - Build an AI agent that can browse and interact with web pages
7. RAG Demo - Retrieval Augmented Generation using Kamiwaza's vector database and embedding services
8. App Garden and Tool Shed - Deploy containerized applications and MCP Tool servers

More examples coming soon!

Service Overview

Service	Description	Documentation
client.models	Model management	Models Service
client.serving	Model deployment	Serving Service
client.vectordb	Vector database	VectorDB Service
client.catalog	Data management	Catalog Service
client.embedding	Text processing	Embedding Service
client.retrieval	Search	Retrieval Service
client.cluster	Infrastructure	Cluster Service
client.lab	Lab environments	Lab Service
client.auth	Security	Auth Service
client.authz	Authorization tuples/checks	AuthZ Service
client.activity	Monitoring	Activity Service
client.openai	OpenAI API compatible	OpenAI Service
client.apps	App deployment	App Service
client.tools	Tool servers (MCP)	Tool Service
client.ingestion	Data ingestion	Ingestion Service

Auth / User Management (0.9.0)

• Base URL rule: set base_url=https://<host> (no /auth suffix). Quick preflight: GET {base_url}/auth/ping → 200. If you include /auth, calls will double-prefix and fail.
• Admin-only: creating/resetting users requires an admin bearer.
• Auth-on semantics: create_local_user provisions Keycloak so the user can authenticate; reset_user_password updates Keycloak only (Keycloak is authoritative). Auth-off updates the local hash only.
• Roles caveat: requested realm roles must exist; otherwise create will 500 + rollback. Omit roles or use known-good roles.
• Self-signed TLS: set --verify-ssl false (or verify_ssl=False) when needed.
• A runnable smoke script lives at scripts/fed_user_smoke.py (see script usage inside).

Integration Tests

The tests/integration suite spins up a MinIO fixture via Docker Compose and exercises the ingestion → catalog flow using the SDK. Run it with:

pytest -m integration

Note: Retrieval checks are currently marked xfail because the live deployment returns HTTP 500 while Ray-backed transport is being stabilised.

The Kamiwaza SDK is actively being developed with new features, examples, and documentation being added regularly. Stay tuned for updates including additional example notebooks, enhanced documentation, and expanded functionality across all services.