Skip to content

Getting Started

This guide will help you install and configure the stkai SDK for Python.

Installation

Install the SDK from PyPI:

pip install stkai

For development (includes testing and linting tools):

pip install stkai[dev]

Requirements

  • Python 3.12+
  • One of the following authentication methods:
    • StackSpot CLI (oscli) installed and authenticated (recommended)
    • Client Credentials for standalone authentication

Authentication

The SDK supports two authentication modes:

If you have the StackSpot CLI installed and authenticated, the SDK will automatically use it for authentication.

Setup:

# Install StackSpot CLI
curl -fsSL https://stk.stackspot.com/install.sh | bash

# Authenticate
stk login

Usage in your code:

from stkai import RemoteQuickCommand, RqcRequest

rqc = RemoteQuickCommand(slug_name="my-quick-command")
response = rqc.execute(RqcRequest(payload={"input": "data"}))

Important: Execute via CLI

For CLI mode to work, your code must be executed through StackSpot CLI commands, such as:

# Run a StackSpot Action
stk run action my-action

# Run a StackSpot Workflow
stk run workflow my-workflow

Running your script directly with python my_script.py will not enable CLI mode, even if you're logged in. See CLI Detection for more details.

Option 2: Standalone Authentication

For environments without StackSpot CLI (CI/CD, serverless, containers), use client credentials:

from stkai import STKAI, RemoteQuickCommand, RqcRequest

# Configure authentication
STKAI.configure(
    auth={
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
    }
)

# Use the SDK
rqc = RemoteQuickCommand(slug_name="my-quick-command")
response = rqc.execute(RqcRequest(payload={"input": "data"}))

Or via environment variables:

export STKAI_AUTH_CLIENT_ID="your-client-id"
export STKAI_AUTH_CLIENT_SECRET="your-client-secret"

Quick Start Examples

Remote Quick Commands

Execute an AI-powered Quick Command:

from stkai import RemoteQuickCommand, RqcRequest

# Create a client
rqc = RemoteQuickCommand(slug_name="analyze-code")

# Execute a single request
response = rqc.execute(
    request=RqcRequest(
        payload={"code": "def hello(): print('world')"},
        id="my-request-id",  # Optional: auto-generated if not provided
    )
)

# Check the result
if response.is_completed():
    print(f"Analysis: {response.result}")
else:
    print(f"Error: {response.error_with_details()}")

AI Agents

Chat with an AI Agent:

from stkai import Agent, ChatRequest

# Create an Agent client
agent = Agent(agent_id="my-assistant")

# Send a message
response = agent.chat(
    request=ChatRequest(user_prompt="Explain dependency injection")
)

# Check the response
if response.is_success():
    print(f"Agent: {response.result}")
    if response.tokens:
        print(f"Tokens used: {response.tokens.total}")
else:
    print(response.error_with_details())

Batch Processing

Both RQC and Agent support concurrent batch execution:

RQC Batch

from stkai import RemoteQuickCommand, RqcRequest

rqc = RemoteQuickCommand(slug_name="analyze-code")

# Prepare multiple requests
files = [
    {"name": "main.py", "code": "..."},
    {"name": "utils.py", "code": "..."},
    {"name": "models.py", "code": "..."},
]

requests = [
    RqcRequest(payload=f, id=f["name"])
    for f in files
]

# Execute all concurrently
responses = rqc.execute_many(requests)

# Process results
for resp in responses:
    if resp.is_completed():
        print(f"{resp.request.id}: {resp.result}")

Agent Batch

from stkai import Agent, ChatRequest

agent = Agent(agent_id="code-assistant")

prompts = [
    "What is dependency injection?",
    "Explain the Strategy pattern",
    "What is CQRS?",
]

# Execute all concurrently
responses = agent.chat_many(
    request_list=[ChatRequest(user_prompt=p) for p in prompts]
)

# Process results
for resp in responses:
    if resp.is_success():
        print(f"Result: {resp.result[:80]}...")

Next Steps