Metadata-Version: 2.4
Name: stkai
Version: 0.4.15
Summary: Python SDK for StackSpot AI - Remote Quick Commands and more
Author-email: Rafael Ponte <rponte@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/rafaelpontezup/stkai-sdk-python
Project-URL: Documentation, https://rafaelpontezup.github.io/stkai-sdk-python/
Project-URL: Repository, https://github.com/rafaelpontezup/stkai-sdk-python
Project-URL: Issues, https://github.com/rafaelpontezup/stkai-sdk-python/issues
Keywords: stackspot,ai,sdk,quick-commands,llm,agents,api client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: python-ulid>=2.2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: coverage>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: types-requests>=2.28.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.5.0; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6.0; extra == "docs"
Dynamic: license-file

# stkai

[![PyPI](https://img.shields.io/pypi/v/stkai.svg)](https://pypi.org/project/stkai/)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)

An unofficial, opinionated Python SDK for [StackSpot AI](https://ai.stackspot.com/) — 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](https://pypi.org/project/stkai/):

```bash
pip install stkai
```

## Requirements

- Python 3.12+
- [StackSpot CLI](https://docs.stackspot.com/docs/stk-cli/installation/) installed and authenticated, or client credentials for standalone auth

## Quick Start

### Remote Quick Commands

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

```python
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:

```python
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:

```python
# 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()]
```

```python
# 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](https://rafaelpontezup.github.io/stkai-sdk-python/rqc/) |
| **AI Agents** | Chat with agents, batch execution, conversations, knowledge sources | [Guide](https://rafaelpontezup.github.io/stkai-sdk-python/agents/) |
| **Batch Execution** | Process multiple requests concurrently (RQC and Agents) | [RQC](https://rafaelpontezup.github.io/stkai-sdk-python/rqc/usage/#batch-execution) · [Agents](https://rafaelpontezup.github.io/stkai-sdk-python/agents/usage/#batch-execution) |
| **Result Handlers** | Customize response processing | [Guide](https://rafaelpontezup.github.io/stkai-sdk-python/rqc/handlers/) |
| **Event Listeners** | Monitor execution lifecycle | [Guide](https://rafaelpontezup.github.io/stkai-sdk-python/rqc/listeners/) |
| **Rate Limiting** | Token Bucket and adaptive AIMD algorithms | [Guide](https://rafaelpontezup.github.io/stkai-sdk-python/rqc/rate-limiting/) |
| **Configuration** | Global config via code or environment variables | [Guide](https://rafaelpontezup.github.io/stkai-sdk-python/configuration/) |

## Documentation

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

- [Getting Started](https://rafaelpontezup.github.io/stkai-sdk-python/getting-started/)
- [RQC Guide](https://rafaelpontezup.github.io/stkai-sdk-python/rqc/)
- [Agents Guide](https://rafaelpontezup.github.io/stkai-sdk-python/agents/)
- [Configuration](https://rafaelpontezup.github.io/stkai-sdk-python/configuration/)
- [API Reference](https://rafaelpontezup.github.io/stkai-sdk-python/api/rqc/)

## Development

```bash
# 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](LICENSE) for details.
