Python SDK

# pip
pip install kairos-sdk

# uv
uv add kairos-sdk

# poetry
poetry add kairos-sdk

# pipenv
pipenv install kairos-sdk

from kairos import Kairos

# Initialize the client
kairos = Kairos(api_key="your_api_key")

# List tasks
result = kairos.tasks.list(status="in_progress", limit=10)

print(f"Found {result.pagination.total} tasks")
for task in result.data:
    print(f"- {task.title} ({task.status})")

import asyncio
from kairos import AsyncKairos

async def main():
    # Initialize async client
    kairos = AsyncKairos(api_key="your_api_key")

    # Make async requests
    result = await kairos.tasks.list(status="in_progress")

    for task in result.data:
        print(f"- {task.title}")

    # Don't forget to close the client
    await kairos.close()

# Or use as async context manager
async def main_with_context():
    async with AsyncKairos(api_key="your_api_key") as kairos:
        result = await kairos.tasks.list()
        print(result.data)

asyncio.run(main())

import os
from kairos import Kairos

kairos = Kairos(
    # Required: Your API key (use environment variable)
    api_key=os.environ["KAIROS_API_KEY"],

    # Optional: Custom base URL
    base_url="https://gateway.thekairos.app/v1",

    # Optional: Request timeout in seconds
    timeout=30.0,

    # Optional: Retry configuration
    max_retries=3,
    retry_delay=1.0,
)

# List tasks with filters
result = kairos.tasks.list(
    status="in_progress",
    priority="high",
    assigned_to="user-id",
    goal_id="goal-id",
    page=1,
    limit=50,
    sort_by="due_date",
    sort_order="asc",
)

# Get a single task
task = kairos.tasks.get("task-id")
print(task.title, task.status)

# Create a task
new_task = kairos.tasks.create(
    title="Implement new feature",
    description="Add user authentication",
    goal_id="goal-id",
    priority="high",
    due_date="2024-01-15",
    story_points=5,
)

# Update a task
updated_task = kairos.tasks.update(
    "task-id",
    status="completed",
    actual_hours=6,
)

# Delete a task
kairos.tasks.delete("task-id")

# List goals
result = kairos.goals.list(
    status="in_progress",
    include_tasks=True,
)

# Get a goal with tasks
goal = kairos.goals.get(
    "goal-id",
    include_tasks=True,
    include_comments=True,
)

print(f"Goal: {goal.title}")
print(f"Progress: {goal.progress}%")

if goal.tasks:
    for task in goal.tasks:
        print(f"  - {task.title}")

# Get team info
team = kairos.team.get()
print(f"Team: {team.name}")

# List team members (team_id required)
result = kairos.team.list_members(team.id)

for member in result.data:
    print(f"{member.name} ({member.role})")

# List documents
result = kairos.documents.list(
    doc_type="page",
    visibility="team",
)

# Get document with content
doc = kairos.documents.get(
    "doc-id",
    include_content=True,
    include_children=True,
)

print(doc.title)
print(doc.plain_text)  # Plain text content

from kairos import Kairos
from kairos.exceptions import (
    KairosError,
    KairosAuthError,
    KairosNotFoundError,
    KairosValidationError,
    KairosRateLimitError,
)
import time

try:
    task = kairos.tasks.get("invalid-id")
except KairosNotFoundError:
    print("Task not found")
except KairosValidationError as e:
    print(f"Validation error: {e.message}")
except KairosRateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after} seconds")
    time.sleep(e.retry_after)
except KairosAuthError:
    print("Authentication failed")
except KairosError as e:
    print(f"API error: {e.code} - {e.message}")

from kairos import Kairos
from kairos.types import (
    Task,
    Goal,
    Comment,
    Team,
    TeamMember,
    Document,
    TaskStatus,
    TaskPriority,
    PaginatedResponse,
)

kairos = Kairos(api_key="...")

# All methods return typed models
task: Task = kairos.tasks.get("id")
result: PaginatedResponse[Task] = kairos.tasks.list()

# Access typed attributes
print(task.title)  # str
print(task.status)  # TaskStatus enum
print(task.due_date)  # Optional[date]

# settings.py
KAIROS_API_KEY = os.environ.get("KAIROS_API_KEY")

# views.py
from django.conf import settings
from kairos import Kairos

kairos = Kairos(api_key=settings.KAIROS_API_KEY)

def tasks_view(request):
    result = kairos.tasks.list(status="in_progress")
    return render(request, "tasks.html", {"tasks": result.data})

from fastapi import FastAPI, Depends
from kairos import AsyncKairos

app = FastAPI()

async def get_kairos():
    async with AsyncKairos() as client:
        yield client

@app.get("/tasks")
async def get_tasks(kairos: AsyncKairos = Depends(get_kairos)):
    result = await kairos.tasks.list()
    return result.data