Metadata-Version: 2.4
Name: secret-ai-sdk
Version: 0.1.6
Summary: Secret AI Confidential VM SDK - Python interface for Secret Network's confidential AI models
Author-email: Alex H <alexh@scrtlabs.com>
License: MIT License
        
        Copyright (c) 2024 ScrtLabs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/scrtlabs/secret-ai-sdk
Project-URL: Documentation, https://docs.scrt.network/secret-network-documentation/secret-ai/sdk
Project-URL: Repository, https://github.com/scrtlabs/secret-ai-sdk
Project-URL: Bug Reports, https://github.com/scrtlabs/secret-ai-sdk/issues
Project-URL: Secret Network, https://scrt.network
Keywords: secret-network,ai,confidential-computing,llm,privacy,blockchain,tts,stt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohappyeyeballs>=2.4.0
Requires-Dist: aiohttp>=3.11.0
Requires-Dist: aiosignal>=1.3.0
Requires-Dist: annotated-types>=0.7.0
Requires-Dist: anyio>=4.7.0
Requires-Dist: attrs>=20.3.0
Requires-Dist: bech32>=1.2.0
Requires-Dist: betterproto>=2.0.0b5
Requires-Dist: bip32utils>=0.3.post4
Requires-Dist: boltons>=21.0.0
Requires-Dist: certifi>=2024.12.14
Requires-Dist: cffi>=1.17.0
Requires-Dist: charset-normalizer>=3.4.0
Requires-Dist: cryptography>=44.0.0
Requires-Dist: ecdsa>=0.16.0
Requires-Dist: frozenlist>=1.5.0
Requires-Dist: furl>=2.1.0
Requires-Dist: greenlet>=3.1.0
Requires-Dist: grpclib>=0.4.0
Requires-Dist: h11>=0.14.0
Requires-Dist: h2>=4.1.0
Requires-Dist: hpack>=4.0.0
Requires-Dist: httpcore>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: hyperframe>=6.0.0
Requires-Dist: idna>=3.10
Requires-Dist: jsonpatch>=1.33
Requires-Dist: jsonpointer>=3.0.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langchain-ollama>=0.2.0
Requires-Dist: langchain-text-splitters>=0.3.0
Requires-Dist: langsmith>=0.2.0
Requires-Dist: miscreant>=0.3.0
Requires-Dist: mnemonic>=0.19
Requires-Dist: multidict>=6.1.0
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: numpy>=2.0.0
Requires-Dist: ollama>=0.4.0
Requires-Dist: orderedmultidict>=1.0.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: packaging>=24.0
Requires-Dist: propcache>=0.2.0
Requires-Dist: protobuf>=3.20.0
Requires-Dist: pycparser>=2.22
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydantic-core>=2.27.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: secret-sdk>=1.8.1
Requires-Dist: setuptools>=75.0.0
Requires-Dist: six>=1.17.0
Requires-Dist: sniffio>=1.3.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: typing-extensions>=4.12.0
Requires-Dist: urllib3>=2.2.0
Requires-Dist: wheel>=0.44.0
Requires-Dist: wrapt>=1.17.0
Requires-Dist: yarl>=1.18.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

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

## Features

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

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

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

## Requirements

`secret-ai-sdk` has dependencies specified in the `pyproject.toml` file, with one external dependency:

- You may need to install `secret-sdk` separately:
  ```bash
  pip install 'secret-sdk>=1.8.1'
  ```

## Installation

To install the Secret AI SDK:

```bash
pip install secret-ai-sdk
```

## Usage

### Text Generation

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

# Initialize the Secret client
secret_client = Secret()

# Get all models registered with the smart contracts
models = secret_client.get_models()

# For your chosen model, get a list of LLM instance URLs
urls = secret_client.get_urls(model=models[0])

# Create the AI client with specific parameters
secret_ai_llm = ChatSecret(
    base_url=urls[0],  # Choose a specific URL
    model=models[0],    # Your selected model
    temperature=1.0
)

# Define your messages
messages = [
    ("system", "You are a helpful assistant that translates English to French."),
    ("human", "I love programming."),
]

# Invoke the LLM (with streaming disabled)
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

# First, query smart contract to get available models and service URLs
secret_client = Secret()
models = secret_client.get_models()

# Check if required models are available
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 from smart contract for each model
stt_url = secret_client.get_urls(model='stt-whisper')
if stt_url is None:
    raise ValueError("STT url not available")
tts_url = secret_client.get_urls(model='tts-kokoro')
if tts_url is None:
    raise ValueError("TTS url not available")

# Initialize VoiceSecret client with smart contract URLs
voice_client = VoiceSecret(
    stt_url=stt_url,
    tts_url=tts_url,
    api_key="your_api_key"  # Optional, reads from SECRET_AI_API_KEY env var
)

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

# Text-to-Speech: Generate speech from text
audio_data = voice_client.synthesize_speech(
    text="Hello, this is a test of the Secret AI TTS system.",
    model="tts-1",
    voice="af_alloy",
    response_format="mp3"
)

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

# Use as context manager for automatic cleanup
with VoiceSecret() as voice:
    # Get available voices and models
    voices = voice.get_available_voices()
    models = voice.get_available_models()
    
    # Health checks
    stt_health = voice.check_stt_health()
    tts_health = voice.check_tts_health()
```

### Enhanced Client with Retry Logic

```python
from secret_ai_sdk._enhanced_client import EnhancedSecretAIClient

# Create enhanced client with automatic retry and error handling
client = EnhancedSecretAIClient(
    host="https://your-ai-endpoint.com",
    api_key="your_api_key",
    timeout=30.0,
    max_retries=3,
    retry_delay=1.0,
    retry_backoff=2.0
)

# Generate with automatic retry on failures
response = client.generate(
    model="your-model",
    prompt="Write a short story about AI.",
    stream=False
)
```

## Configuration

### API Key Authentication

To use the Secret AI SDK, you need your own Secret AI API Key. Visit SecreAI Development portal: [https://aidev.scrtlabs.com/](https://aidev.scrtlabs.com/).

Set your API key as an environment variable:

```bash
export SECRET_AI_API_KEY='YOUR_API_KEY'
```

### Environment Variables

The SDK supports various environment variables for configuration:

```bash
# Authentication
export SECRET_AI_API_KEY='your_api_key'

# Network Configuration
export SECRET_NODE_URL='your_lcd_node_url'

# Timeout Settings (seconds)
export SECRET_AI_REQUEST_TIMEOUT='30.0'
export SECRET_AI_CONNECT_TIMEOUT='10.0'

# Retry Configuration
export SECRET_AI_MAX_RETRIES='3'
export SECRET_AI_RETRY_DELAY='1.0'
export SECRET_AI_RETRY_BACKOFF='2.0'
export SECRET_AI_MAX_RETRY_DELAY='60.0'
```

### Node URL Configuration

If you experience issues with the default node URL, you can manually specify one:

```python
from secret_ai_sdk.secret import Secret

# Option 1: Directly in code
secret_client = Secret(chain_id='secret-4', node_url='YOUR_LCD_NODE_URL')

# Option 2: Using an environment variable
# export SECRET_NODE_URL='YOUR_LCD_NODE_URL'
```

For available endpoints and LCD nodes, see the [Secret Network Documentation](https://docs.scrt.network/secret-network-documentation/development/resources-api-contract-addresses/connecting-to-the-network/testnet-pulsar-3).

## Advanced Features

### Error Handling

The SDK provides comprehensive error handling with specific exception types:

```python
from secret_ai_sdk.secret_ai_ex import (
    SecretAIAPIKeyMissingError,
    SecretAIConnectionError, 
    SecretAITimeoutError,
    SecretAIRetryExhaustedError,
    SecretAIResponseError
)

try:
    response = client.generate(model="test", prompt="Hello")
except SecretAITimeoutError as e:
    print(f"Request timed out after {e.timeout} seconds")
except SecretAIConnectionError as e:
    print(f"Failed to connect to {e.host}: {e.original_error}")
except SecretAIRetryExhaustedError as e:
    print(f"All {e.attempts} retry attempts failed: {e.last_error}")
```

### Streaming Responses

Both text generation and TTS support streaming for real-time processing:

```python
# Streaming text generation
for chunk in secret_ai_llm.stream(messages):
    print(chunk.content, end="", flush=True)

# Streaming TTS
audio_data = voice_client.synthesize_speech_streaming(
    text="Long text to be synthesized...",
    model="tts-1"
)
```

### Custom Retry Configuration

Configure retry behavior per client instance:

```python
from secret_ai_sdk._enhanced_client import EnhancedSecretAIClient

client = EnhancedSecretAIClient(
    host="https://ai-endpoint.com",
    max_retries=5,           # Retry up to 5 times
    retry_delay=2.0,         # Start with 2 second delay
    retry_backoff=1.5,       # Increase delay by 1.5x each retry
    timeout=45.0,            # 45 second request timeout
    validate_responses=True   # Validate response format
)
```

## Examples

For comprehensive examples including streaming implementation, refer to the `example.py` and `voice_example.py` files provided in the package.

## API Documentation

For comprehensive API documentation, please visit our [official documentation](https://docs.scrt.network/secret-network-documentation/secret-ai/sdk).

## License

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

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

If you encounter any issues or have questions, please [open an issue](https://github.com/scrtlabs/secret-ai-sdk/issues) on our GitHub repository.
