stkai 0.4.18

Python SDK for StackSpot AI - Remote Quick Commands and more

stkai

An unofficial, opinionated Python SDK for StackSpot AI — Execute Remote Quick Commands (RQCs) and interact with AI Agents with built-in resilience.

Note: This is a community-driven SDK, not officially maintained by StackSpot. It was built to fill gaps we encountered in real-world projects — such as retries, rate limiting, and batch execution — that the platform's API alone doesn't provide out of the box.

Design Principles

This SDK is opinionated by design. It prioritizes:

• Reliability over latency — Built-in retries, rate limiting, and fault tolerance mechanisms
• Predictability over throughput — Synchronous, blocking API for straightforward debugging and reasoning
• Pragmatism over flexibility — Simple, direct API with well-designed extension points
• Convention over configuration — Sensible defaults and seamless StackSpot CLI integration

Installation

Install from PyPI:

pip install stkai

Requirements

• Python 3.12+
• StackSpot CLI installed and authenticated, or client credentials for standalone auth

Quick Start

Remote Quick Commands

Execute LLM-powered quick commands with automatic polling and retries:

from stkai import RemoteQuickCommand, RqcRequest

rqc = RemoteQuickCommand(slug_name="my-quick-command")
response = rqc.execute(
    request=RqcRequest(payload={"code": "def hello(): pass"})
)

if response.is_completed():
    print(response.result)
else:
    print(response.error_with_details())

AI Agents

Chat with StackSpot AI Agents for conversational AI capabilities:

from stkai import Agent, ChatRequest

agent = Agent(agent_id="my-agent-slug")
response = agent.chat(
    request=ChatRequest(user_prompt="What is SOLID?")
)

if response.is_success():
    print(response.result)
else:
    print(response.error_with_details())

Batch Processing

Process multiple requests concurrently with thread pool execution:

# RQC batch
responses = rqc.execute_many(
    request_list=[RqcRequest(payload=data) for data in files]
)

completed = [r for r in responses if r.is_completed()]

# Agent batch
responses = agent.chat_many(
    request_list=[ChatRequest(user_prompt=p) for p in prompts]
)

successful = [r for r in responses if r.is_success()]

Features

Feature	Description	Docs
Remote Quick Commands	Execute AI commands with polling and retries	Guide
AI Agents	Chat with agents, batch execution, conversations, knowledge sources	Guide
Batch Execution	Process multiple requests concurrently (RQC and Agents)	RQC · Agents
Result Handlers	Customize response processing	Guide
Event Listeners	Monitor execution lifecycle	Guide
Rate Limiting	Token Bucket and adaptive AIMD algorithms	Guide
Configuration	Global config via code or environment variables	Guide

Documentation

Full documentation available at: https://rafaelpontezup.github.io/stkai-sdk-python/

• Getting Started
• RQC Guide
• Agents Guide
• Configuration
• API Reference

Development

# Clone and setup
git clone https://github.com/rafaelpontezup/stkai-sdk.git
cd stkai-sdk
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=term-missing

# Lint and type check
ruff check src tests
mypy src

# Build docs locally
pip install -e ".[docs]"
mkdocs serve

License

Apache License 2.0 - see LICENSE for details.