stackspot-client 0.1.6

Cliente Python para a API do StackSpot

StackSpot Client Python

A Python client library for interacting with the StackSpot API. This library provides a simple and intuitive interface to authenticate, execute commands, and retrieve results from the StackSpot platform.

Features

• 🔐 Automatic authentication handling
• 🔄 Automatic token refresh
• ⚡ Retry mechanism for failed requests
• 🛡️ Comprehensive error handling
• 📦 Support for different response types
• 🧪 Type hints for better IDE support

Installation

You can install the package using pip:

pip install stackspot-client

Quick Start

import os

from dotenv import load_dotenv
from stackspot_client import StackSpotConfig, StackSpotError, QuickCommands

load_dotenv()

def main():
    # Configuração do cliente
    config = StackSpotConfig(base_url=os.getenv("base_url"),auth_url=os.getenv("auth_url"),
        client_id=os.getenv("client_id"),client_secret=os.getenv("client_secret")
    )

    try:

        command = QuickCommands(config)

        execution_id = command.execute_command(
            
         # Endpoint informed when creating the quick command
        '/v1/quick-commands/create-execution/ola-mundo-',
            ' O mundo é um moinho'
        )

        result = command.get_execution_result(execution_id)

        if result:
            print("\n📋 Resultado:")
            print("=" * 50)
            print(result['steps'][0]['step_result']['answer'])
        else:
            print("❌ Falha")

    except StackSpotError as e:
        print(f"\n❌ Erro: {str(e)}")
    except Exception as e:
        print(f"\n❌ Erro inesperado: {str(e)}")
        import traceback
        print("\nDetalhes do erro:")
        print(traceback.format_exc())

if __name__ == "__main__":
    main()

Configuration

The StackSpotConfig class accepts the following parameters:

Parameter	Type	Required	Default	Description
base_url	str	Yes	-	Base URL for the StackSpot API
client_id	str	Yes	-	Your StackSpot client ID
client_secret	str	Yes	-	Your StackSpot client secret
auth_url	str	No	https://idm.stackspot.com/stackspot-freemium/oidc/oauth/token	Authentication URL
max_retries	int	No	30	Maximum number of retries for result polling
retry_interval	int	No	5	Interval between retries in seconds
request_delay	float	No	0.0	Delay in seconds before each request

Environment Variables & .env support

You can configure the client using environment variables for improved security and flexibility. The following variables are supported:

• STACKSPOT_BASE_URL (required)
• STACKSPOT_CLIENT_ID (required)
• STACKSPOT_CLIENT_SECRET (required)
• STACKSPOT_AUTH_URL (optional)
• STACKSPOT_MAX_RETRIES (optional)
• STACKSPOT_RETRY_INTERVAL (optional)
• STACKSPOT_REQUEST_DELAY (optional)

You may use a .env file in your project root for local development:

STACKSPOT_BASE_URL=https://genai-code-buddy-api.stackspot.com
STACKSPOT_CLIENT_ID=your_client_id
STACKSPOT_CLIENT_SECRET=your_client_secret
STACKSPOT_AUTH_URL=https://idm.stackspot.com/stackspot-freemium/oidc/oauth/token
STACKSPOT_MAX_RETRIES=30
STACKSPOT_RETRY_INTERVAL=5
STACKSPOT_REQUEST_DELAY=0.0

Example: Loading from environment

from stackspot_client import StackSpotConfig, StackSpotClient

# Optionally load .env file (requires python-dotenv)
from dotenv import load_dotenv
load_dotenv()

config = StackSpotConfig.from_env()
client = StackSpotClient(config)

| client_id | str | Yes | - | Your StackSpot client ID | | client_secret | str | Yes | - | Your StackSpot client secret | | auth_url | str | No | https://idm.stackspot.com/stackspot-freemium/oidc/oauth/token | Authentication URL | | max_retries | int | No | 30 | Maximum number of retries for result polling | | retry_interval | int | No | 5 | Interval between retries in seconds |

Usage Examples

Knowledge Source Upload Examples

Below are usage examples for the upload methods available in the KnowledgeSources class:

from stackspot_client import StackSpotConfig, StackSpotClient
from stackspot_client.knowledge_sources import KnowledgeSources

# It is recommended to configure your credentials using environment variables or a .env file:
# STACKSPOT_BASE_URL, STACKSPOT_CLIENT_ID, STACKSPOT_CLIENT_SECRET, STACKSPOT_AUTH_URL (optional)
config = StackSpotConfig.from_env()

# If needed, you can override any parameter manually:
# config.base_url = 'https://another-endpoint.com'

client = StackSpotClient(config)
ks = KnowledgeSources(client)
ks_slug = 'my-ks'
file_path = '/path/to/file.pdf'

# 1. Direct file upload (without Docling processing)
ks.upload_file(file_path, ks_slug)

> **Note:** Supported files for direct upload: `.json`, `.yml`, `.yaml`, `.md`, `.txt`, `.pdf`, `.zip` (the `.zip` file must contain only the supported file types listed). Maximum size: **10MB per file**. Other formats must be processed with Docling.

# 2. Upload content extracted from a URL (processed by Docling to Markdown)
ks.upload_from_url('https://example.com/article', ks_slug)

# 3. Upload a local file processed by Docling (generates Markdown before upload)
ks.upload_file_with_docling(file_path, ks_slug)

> **Note:** When using Docling (with `upload_from_url` or `upload_file_with_docling`), a wide range of file formats is supported. For the complete list, see the [Docling Supported Formats documentation](https://docling-project.github.io/docling/usage/supported_formats/).

# Delete all files from a knowledge source
success = ks.delete_all_files("my-knowledge-source")

Response Format

The get_execution_result method returns a dictionary with the following structure:

{
    'status': 'COMPLETED',  # or 'FAILED', 'RUNNING'
    'answer': '...',       # The actual response
    'progress': {          # Optional progress information
        'status': 'COMPLETE',
        'percentage': 100
    }
}

Error Types

The library provides several error types for better error handling:

• StackSpotError: Base exception class
• AuthenticationError: Raised when authentication fails
• APIError: Raised when API calls fail

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support with the StackSpot API, please refer to the official documentation.

Changelog

0.1.4

• Environment-based configuration as default (with .env support)
• File upload validation: allowed formats and max size (10MB)
• Integration with Docling for file and URL uploads (Markdown conversion)
• Added ValidationError for input validation
• Maintainer metadata (eltonjosesouza) in setup.py
• General code and documentation cleanup

0.1.2

• Added support for Knowledge Sources management
• Implemented knowledge source creation functionality
• Added support for file uploads
• Implemented URL content upload functionality
• Added functionality to delete all files from a knowledge source

0.1.0

• Initial release
• Basic authentication and command execution
• Result polling with retry mechanism
• Comprehensive error handling