# SECRET AI SDK

## Secret AI SDK

[![PyPI version](https://img.shields.io/pypi/v/secret-ai-sdk.svg)](https://pypi.org/project/secret-ai-sdk/) [![Python versions](https://img.shields.io/pypi/pyversions/secret-ai-sdk.svg)](https://pypi.org/project/secret-ai-sdk/) [![License](https://img.shields.io/github/license/scrtlabs/secret-ai-sdk.svg)](https://opensource.org/licenses/MIT)

The Secret AI SDK provides a comprehensive Python interface for accessing Secret Network's confidential AI models, including text generation, speech-to-text (STT), and text-to-speech (TTS) capabilities. Built with enterprise-grade reliability and privacy-preserving features.

### Overview

The Secret AI SDK is a Python library that enables secure, private access to Secret Network's confidential AI infrastructure. The SDK provides intuitive APIs for text-based language models, voice processing, and multimodal AI capabilities while ensuring all computations remain confidential through Secret's privacy-preserving technology.

### Core Features

#### AI Capabilities

* **Text Generation**: Access to Secret Confidential AI language models with streaming support
* **Voice Processing**: Unified STT and TTS functionality through the VoiceSecret class
* **Multimodal Support**: Handle text, audio, and voice interactions seamlessly
* **Ollama API Compatibility**: Full support for OpenAI-compatible endpoints

#### Enterprise-Grade Reliability

* **Enhanced Error Handling**: Comprehensive exception hierarchy with detailed error context
* **Automatic Retry Logic**: Configurable exponential backoff for network resilience
* **Timeout Management**: Customizable request and connection timeout controls
* **Response Validation**: Built-in validation for API response integrity
* **Concurrency Support**: Handle multiple concurrent requests efficiently

#### Developer Experience

* **Clean Pythonic Interface**: Intuitive APIs following Python best practices
* **Flexible Authentication**: API key-based authentication with environment variable support
* **Comprehensive Logging**: Detailed logging for debugging and monitoring
* **Context Manager Support**: Proper resource management with context managers

### Architecture

#### Core Components

The SDK consists of several key modules:

* **`secret.py`**: Main client for accessing Secret Network smart contracts
* **`secret_ai.py`**: Chat interface built on LangChain for text generation
* **`voice_secret.py`**: Unified voice processing (STT/TTS) interface
* **`_enhanced_client.py`**: Enhanced clients with retry logic and error handling
* **`_config.py`**: Configuration management and environment variables
* **`secret_ai_ex.py`**: Custom exception classes for comprehensive error handling
* **`_retry.py`**: Retry logic with exponential backoff

#### SDK Structure

```
secret_ai_sdk/
├── secret.py              # Main Secret Network client
├── secret_ai.py           # LangChain-based chat interface  
├── voice_secret.py        # Voice processing (STT/TTS)
├── _enhanced_client.py    # Enhanced clients with retry logic
├── _client.py             # Basic client implementations
├── _config.py             # Configuration and constants
├── _retry.py              # Retry logic and utilities
└── secret_ai_ex.py        # Custom exceptions
```

### Quick Start

#### Text Generation with ChatSecret

```python
from secret_ai_sdk.secret_ai import ChatSecret
from secret_ai_sdk.secret import Secret

# Initialize the Secret client
secret_client = Secret()

# Get available models from smart contracts
models = secret_client.get_models()
print(f"Available models: {models}")

# Get service URLs for your chosen model
urls = secret_client.get_urls(model=models[0])
print(f"Available URLs: {urls}")

# Create the AI client
secret_ai_llm = ChatSecret(
    base_url=urls[0],
    model=models[0],
    temperature=0.7
)

# Generate text
messages = [
    ("system", "You are a helpful assistant."),
    ("human", "Explain quantum computing in simple terms.")
]

response = secret_ai_llm.invoke(messages, stream=False)
print(response.content)
```

#### Voice Processing with VoiceSecret

```python
from secret_ai_sdk.voice_secret import VoiceSecret
from secret_ai_sdk.secret import Secret

# Get voice service URLs from smart contracts
secret_client = Secret()
models = secret_client.get_models()

# Check for required voice models
if 'stt-whisper' not in models:
    raise ValueError("STT Whisper model not available")
if 'tts-kokoro' not in models:
    raise ValueError("TTS Kokoro model not available")

# Get service URLs
stt_url = secret_client.get_urls(model='stt-whisper')
tts_url = secret_client.get_urls(model='tts-kokoro')

# if it's a list, take the first element
if isinstance(stt_url, list): stt_url = stt_url[0]
if isinstance(tts_url, list): tts_url = tts_url[0]

# Initialize VoiceSecret with service URLs
voice_client = VoiceSecret(
    stt_url=stt_url,
    tts_url=tts_url
)

# Speech-to-Text: Transcribe audio
transcription = voice_client.transcribe_audio("path/to/audio.wav")
print(f"Transcription: {transcription['text']}")

# Text-to-Speech: Generate speech
audio_data = voice_client.synthesize_speech(
    text="Hello, this is Secret AI speaking!",
    model="tts-1",
    voice="af_alloy",
    response_format="mp3"
)

# Save the generated audio
voice_client.save_audio(audio_data, "output/speech.mp3")
```

#### Network Configuration

For custom Secret Network node configuration:

```python
from secret_ai_sdk.secret import Secret

# Option 1: Direct configuration
secret_client = Secret(
    chain_id='secret-4',
    node_url='https://your-custom-lcd-node.com'
)

# Option 2: Environment variable
# export SECRET_NODE_URL='https://your-custom-lcd-node.com'
secret_client = Secret()
```

### Error Handling & Debugging

#### Exception Hierarchy

```python
SecretAIError                    # Base exception
├── SecretAIAPIKeyMissingError   # Missing API key
├── SecretAIInvalidInputError    # Invalid input parameters
├── SecretAINetworkError         # Network-related errors
│   ├── SecretAITimeoutError     # Request timeouts
│   ├── SecretAIConnectionError  # Connection failures
│   └── SecretAIRetryExhaustedError  # All retries failed
├── SecretAIResponseError        # Invalid/malformed responses
└── SecretAINotImplementedError  # Unimplemented features
```

#### Logging Configuration

Enable detailed logging for debugging:

```python
import logging

# Configure SDK logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('secret_ai_sdk')
logger.setLevel(logging.DEBUG)

# Set via environment variable
import os
os.environ['SECRET_SDK_LOG_LEVEL'] = 'debug'
```

#### Retry Logic Details

The SDK implements intelligent retry logic with exponential backoff:

* **Retryable Errors**: Network timeouts, connection errors, temporary server errors
* **Non-Retryable Errors**: Authentication failures, invalid input, permanent server errors
* **Backoff Strategy**: Exponential with jitter to prevent thundering herd
* **Configuration**: All retry parameters are configurable via environment variables

### Examples Repository

For additional examples and use cases, refer to the provided example files:

* **`example.py`**: Comprehensive streaming implementation with custom handlers
* **`voice_example.py`**: Voice processing examples with health checks and error handling
* **`test_secret_ai.py`**: Basic connectivity and functionality tests

#### Contributing

Contributions are welcome! Please submit pull requests to the [GitHub repository](https://github.com/scrtlabs/secret-ai-sdk).

### License

The Secret AI SDK is licensed under the [MIT License](https://opensource.org/licenses/MIT).

***

*This documentation covers version 0.1.5 of the Secret AI SDK. For the latest updates and features, please check the* [*PyPI package page*](https://pypi.org/project/secret-ai-sdk/)*.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.scrt.network/secret-network-documentation/secret-ai/sdk/setting-up-your-environment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.