Skip to main content

​
Install

pip install kaireon                   # core REST client + pydantic models
pip install 'kaireon[shap]'           # + matplotlib SHAP/fairness plots
pip install 'kaireon[analytics]'      # + polars/psycopg for DecisionTrace queries

​
Quickstart

from kaireon import KaireonClient

client = KaireonClient(
    base_url="https://playground.kaireonai.com",
    api_key="...",
    tenant_id="...",
)

# Recommend
rec = client.recommend(customer_id="cust-1", channel_id="email")

# SHAP
shap = client.shap(
    decision_trace_id=rec.decision_trace_id,
    model_id="gbm-prod-v3",
    attributes={"income": 40000, "credit_score": 600},
)

# Narrative
narrative = client.narrative(
    decision_trace_id=rec.decision_trace_id,
    mode="regulator",
    language="en",
)

​
Honest scope (B-lite)

This package is the B-lite scope from the consolidated 10-week plan. It covers:
  • REST client for the data-science-facing endpoints (/recommend, /respond, /decisions/:id/shap, /decisions/:id/narrative, /fairness/evaluate).
  • A SHAP-to-matplotlib bar plot helper.
  • A fairness audit wrapper with a four-fifths-rule bar plot.
  • Three reference notebooks under platform/integrations/python/examples/.
Out of scope in V1: Streamlit dashboards, Quarto reports, full PDTools-shape submodule coverage. The KaireonAI Studio dashboards cover the analyst use case for mid-market.

​
openapi-generator-cli recipe

For languages other than Python — or for the CRUD endpoints not wrapped by the kaireon package — generate a client straight from the platform’s OpenAPI spec: 
npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate \
  -i https://playground.kaireonai.com/api/openapi.json \
  -g <python|typescript-axios|java|go|...> \
  -o ./generated-client

​
MCP SDK example (mcp-py)

from mcp import ClientSession
from mcp.client.sse import sse_client

async def list_offers():
    async with sse_client("https://playground.kaireonai.com/mcp") as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            return [t.name for t in tools.tools]
The platform exposes 110+ MCP tools at /mcp (SSE transport). Headers match the REST client (X-API-Key, X-Tenant-Id).

​
Distribution status

The package currently lives in-repo at platform/integrations/python/ while it stabilizes. Splitting into a dedicated kaireonai/kaireon-py repository and publishing the kaireon==0.1.0a1 artifact to PyPI requires operator authorization (GitHub repo creation + PyPI credentials). When that lands, the import path will be unchanged — from kaireon import KaireonClient.

​
Reading DecisionTrace from the analytics replica

Direct DB queries against decision_traces are common in offline policy replay. The analytics extra ships polars + psycopg so that pattern is one import: 
import polars as pl
import psycopg

with psycopg.connect(DSN) as conn:
    df = pl.read_database(
        "SELECT id, customer_id, scoring_results, selected_offers "
        "FROM decision_traces WHERE tenant_id = %s "
        "ORDER BY created_at DESC LIMIT 5000",
        connection=conn,
        execute_options={"parameters": [TENANT_ID]},
    )
The scoring_results JSON column has the same shape returned by /recommend (offerId, score, shapValues, etc.).