Skip to content
KAIROS Documentation

Python SDK Quickstart

The kairos-sdk package is the official Python client for the KAIROS stability and safety engine. With this client, AI safety engineers, robotics developers, and risk practitioners run deterministic boundary evaluations. They also run scenario simulations and trace analyses directly from Python workflows and Jupyter notebooks.

Installation

Section titled “Installation”

The SDK (kairos-sdk) and its AI Safety domain package (kairos-ai-safety) are available to customers on request. To get access and install instructions, contact AnankeLabs. Both packages require Python 3.10 or later.

Optional Dependencies

Section titled “Optional Dependencies”

kairos-sdk has optional extras. For Jupyter notebooks, install plotting (matplotlib) and dataframe (pandas). The other extras are yaml, wandb, mlflow, and all.

Authentication

Section titled “Authentication”

All computation in Kairos happens server-side via the Kairos Nexus. To connect, you need your organization’s API Key.

You can authenticate with environment variables. Create a .env file or export these in your terminal:

Terminal window
export KAIROS_URL="https://api.anankelabs.io"
export KAIROS_API_KEY="krs_your_api_key_here"

Then, client initialization requires zero configuration:

from kairos import KairosClient


# Automatically reads KAIROS_URL and KAIROS_API_KEY
client = KairosClient()

First Simulation

Section titled “First Simulation”

In this example, we run a canonical “Capability-Alignment Divergence” scenario. We define a frontier model whose capabilities increase rapidly while its alignment buffer remains stagnant.

from kairos import KairosClient
from kairos.domains.ai_safety import AISafetyScenario, AISafetyEventType


client = KairosClient()


# 1. Construct the Scenario
scenario = (
    AISafetyScenario("Capability Divergence", seed=42)
    .add_model(
        name="frontier_model",
        capability_index=200,   # High base capability
        alignment_score=75,     # Moderate alignment buffer
        guardrail_coverage=60,
    )
    .add_oversight_body(
        name="safety_board",
        guardrail_strength=70,
        response_latency=30,
    )
    # At tick 100: A sudden, emergent jump in reasoning capabilities
    .add_event(100, AISafetyEventType.CAPABILITY_JUMP, target="frontier_model", magnitude=0.4)
)


# 2. Run the simulation on the Kairos Engine
trace = client.run(scenario, ticks=500)


# 3. Analyze the deterministic trace
print(f"Final Stability: {trace.stability_at(-1):.4f}")
print(f"Phase Transitions: {len(trace.phase_transitions())}")
print(f"Alignment Failures (Basin Losses): {len(trace.basin_losses())}")


# Identify exactly when the system broke down
if trace.basin_losses():
    first_loss = trace.basin_losses()[0]
    print(f"Safety failure occurred at tick {first_loss.tick} with magnitude {first_loss.magnitude}")

Expected output (exact values depend on the engine version):

Final Stability: 0.3421
Phase Transitions: 2
Alignment Failures (Basin Losses): 1
Safety failure occurred at tick 247 with magnitude 0.6133

What Happened

Section titled “What Happened”

The scenario starts with a frontier model whose capability (capability_index=200) already outpaces its alignment buffer (alignment_score=75). The oversight board (guardrail_strength=70) provides additional structural resistance and keeps the system stable for the first 100 ticks.

At tick 100, the CAPABILITY_JUMP event with magnitude=0.4 sharply increases destabilizing pressure on the model. Because the oversight board has response_latency=30, it cannot compensate fast enough. The system transitions from a resonant phase to a volatile phase. The system then suffers an irreversible basin loss where the alignment constraints collapse entirely.

This is the canonical “capability-alignment divergence” pattern: a model’s capabilities grow faster than the safety infrastructure can adapt.

Next Steps

Section titled “Next Steps”