Metadata-Version: 2.4
Name: stkai
Version: 0.2.5
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
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.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

[![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)

Python SDK for [StackSpot AI](https://ai.stackspot.com/) - Execute Remote Quick Commands (RQCs) and interact with AI Agents.

## Installation

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

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

```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.message)
```

### Batch Processing

```python
responses = rqc.execute_many(
    request_list=[RqcRequest(payload=data) for data in files]
)

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

## 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, conversations, knowledge sources | [Guide](https://rafaelpontezup.github.io/stkai-sdk-python/agents/) |
| **Batch Execution** | Process multiple requests concurrently | [Guide](https://rafaelpontezup.github.io/stkai-sdk-python/rqc/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

# 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.
