Metadata-Version: 2.4
Name: venice-sdk
Version: 0.3.3
Summary: Comprehensive Python SDK for Venice AI - Advanced LLM, Image Generation, Audio Synthesis, and AI Assistant APIs with Full Swagger Specification Support
Project-URL: Homepage, https://github.com/actuallyrizzn/Venice-AI-SDK
Project-URL: Documentation, https://github.com/actuallyrizzn/Venice-AI-SDK#readme
Project-URL: Repository, https://github.com/actuallyrizzn/Venice-AI-SDK.git
Project-URL: Issues, https://github.com/actuallyrizzn/Venice-AI-SDK/issues
Project-URL: Changelog, https://github.com/actuallyrizzn/Venice-AI-SDK/blob/main/CHANGELOG.md
Author-email: Mark Rizzn Hopkins <guesswho@rizzn.com>
License: Dual License: GNU Affero General Public License v3.0 and Creative Commons Attribution-ShareAlike 4.0 International
License-File: LICENSE
Keywords: ai,ai-assistant,api-client,artificial-intelligence,async,audio-synthesis,chatbot,chatgpt,claude,dall-e,documentation,embeddings,error-handling,examples,function-calling,gpt,http-client,image-generation,llama,llm,machine-learning,openai,openapi,pagination,production-ready,python,rate-limiting,rest-api,sdk,semantic-search,streaming,swagger,text-generation,text-to-speech,tutorials,type-hints,vector-search,venice-ai,whisper
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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 :: Communications :: Chat
Classifier: Topic :: Education
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Office/Business
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.8
Requires-Dist: psutil<6.0.0,>=5.9.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: requests<3.0.0,>=2.31.0
Requires-Dist: tiktoken<1.0.0,>=0.5.0
Requires-Dist: typing-extensions<5.0.0,>=4.5.0
Provides-Extra: dev
Requires-Dist: black<24.0.0,>=23.0.0; extra == 'dev'
Requires-Dist: mypy<2.0.0,>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock<4.0.0,>=3.12.0; extra == 'dev'
Requires-Dist: pytest<8.0.0,>=7.0.0; extra == 'dev'
Requires-Dist: ruff<1.0.0,>=0.1.0; extra == 'dev'
Requires-Dist: types-requests<3.0.0,>=2.31.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10.0.0,>=9.0.0; extra == 'docs'
Requires-Dist: mkdocs<2.0.0,>=1.4.0; extra == 'docs'
Requires-Dist: mkdocstrings<1.0.0,>=0.22.0; extra == 'docs'
Provides-Extra: publish
Requires-Dist: build<2.0.0,>=0.10.0; extra == 'publish'
Requires-Dist: twine<5.0.0,>=4.0.0; extra == 'publish'
Description-Content-Type: text/markdown

# Venice AI Python SDK
http://venice.ai

A comprehensive Python SDK for the Venice AI API, providing complete access to all Venice AI services including chat completions, image generation, audio synthesis, character management, and more.

[![PyPI version](https://badge.fury.io/py/venice-sdk.svg)](https://badge.fury.io/py/venice-sdk)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: AGPLv3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![License: CC BY-SA 4.0](https://img.shields.io/badge/License-CC%20BY--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
[![Tests](https://img.shields.io/badge/tests-876%20passing-brightgreen.svg)](https://github.com/actuallyrizzn/Venice-AI-SDK)

## ✨ Features

### 🤖 Core AI Services
- 💬 **Chat Completions** - Advanced LLM text generation with streaming
- 🧠 **Models** - Complete model management and discovery
- 🔗 **Embeddings** - Vector generation and semantic search
- 🎭 **Characters** - AI persona and character management

### 🎨 Image Processing
- 🖼️ **Image Generation** - Create images from text descriptions
- ✏️ **Image Editing** - Edit existing images with AI
- 🔍 **Image Upscaling** - Enhance image resolution and quality
- 🎨 **Image Styles** - Access to artistic style presets
- 📱 **Data URL Support** - Handle base64-encoded images seamlessly

### 🎵 Audio Services
- 🔊 **Text-to-Speech** - Convert text to natural-sounding speech
- 🎤 **Multiple Voices** - Choose from various voice options
- 📁 **Audio Formats** - Support for MP3, WAV, AAC, and more

### 🎬 Video Generation
- 🎥 **Text-to-Video** - Generate videos from text descriptions
- 🖼️ **Image-to-Video** - Animate static images into video clips
- 💰 **Price Quotes** - Get cost estimates before generation
- ⏱️ **Async Processing** - Queue jobs and track progress
- 📥 **Video Download** - Easy video file download and management

### 🔧 Account Management
- 🔑 **API Key Management** - Create, list, and delete API keys
- 🌐 **Web3 Integration** - Generate Web3-compatible keys
- 📊 **Usage Tracking** - Monitor API usage and billing
- ⚡ **Rate Limiting** - Built-in rate limit management
- 👑 **Admin Features** - Full administrative access with admin API keys

### 🚀 Advanced Features
- 🌊 **Streaming** - Real-time response streaming with SSE support
- 🛠️ **Function Calling** - Tool and function integration
- 🔍 **Web Search** - Integrated web search capabilities
- 📈 **Model Analytics** - Advanced model traits and compatibility
- ⚡ **Error Handling** - Comprehensive error handling with retries
- 📝 **Type Safety** - Full type hints and documentation
- 🔄 **OpenAI Compatibility** - Drop-in replacement for OpenAI SDK
- ✅ **Robust Testing** - 1069 tests with 100% pass rate

## Installation

```bash
pip install venice-sdk
```

## Quick Start

```python
from venice_sdk import VeniceClient, create_client

# Initialize the client (loads from VENICE_API_KEY env var)
client = VeniceClient()

# Or create with explicit API key
# client = create_client(api_key="your-api-key")

# Chat completions
response = client.chat.complete(
    messages=[
        {"role": "user", "content": "Hello! What can you help me with?"}
    ],
    model="llama-3.3-70b",
    temperature=0.7,
    max_completion_tokens=500
)
print(response.choices[0].message.content)

# Image generation
image = client.images.generate(
    prompt="A serene mountain landscape at sunset",
    model="dall-e-3"
)
image.save("mountain.png")

# Text-to-speech
audio = client.audio.speech(
    input_text="Hello from Venice AI!",
    voice="alloy"
)
audio.save("hello.mp3")

# Generate embeddings
embeddings = client.embeddings.generate([
    "The quick brown fox jumps over the lazy dog",
    "A fast brown fox leaps over a sleepy dog"
])
similarity = embeddings[0].cosine_similarity(embeddings[1])
print(f"Similarity: {similarity}")

# Video generation
job = client.video.queue(
    model="kling-2.6-pro-text-to-video",
    prompt="A serene sunset over a calm ocean",
    duration=5,
    aspect_ratio="16:9"
)
completed_job = client.video.wait_for_completion(job.job_id)
if completed_job.is_completed():
    completed_job.download("video.mp4")

# List available characters
characters = client.characters.list()
for char in characters[:3]:
    print(f"- {char.name}: {char.description}")

# Check account usage
usage = client.billing.get_usage()
print(f"Credits remaining: {usage.credits_remaining}")

# Advanced usage with pagination
from datetime import datetime, timedelta

end_date = datetime.now()
start_date = end_date - timedelta(days=30)

usage = client.billing.get_usage(
    currency="USD",
    start_date=start_date,
    end_date=end_date,
    limit=50,
    page=1,
    sort_order="desc"
)

# Access pagination info
if usage.pagination:
    print(f"Page {usage.pagination['page']} of {usage.pagination['totalPages']}")
    print(f"Total records: {usage.pagination['total']}")
```

## 📚 Examples

### Image Processing
```python
# Generate an image
image = client.images.generate(
    prompt="A futuristic cityscape at night",
    model="dall-e-3",
    size="1024x1024",
    quality="hd"
)

# Edit an existing image
edited = client.image_edit.edit(
    image="path/to/image.png",
    prompt="Add a rainbow in the sky",
    model="dall-e-2-edit"
)

# Upscale an image
upscaled = client.image_upscale.upscale(
    image="path/to/small_image.png",
    scale=2
)

# List available styles
styles = client.image_styles.list_styles()
for style in styles:
    print(f"{style.name}: {style.description}")
```

### Audio Synthesis
```python
# Convert text to speech
audio = client.audio.speech(
    input_text="Hello, this is a test of the Venice AI text-to-speech system.",
    voice="alloy",
    response_format="mp3",
    speed=1.0
)

# Save to file
audio.save("speech.mp3")

# List available voices
voices = client.audio.get_voices()
for voice in voices:
    print(f"{voice.name}: {voice.description}")

# Batch processing
from venice_sdk import AudioBatchProcessor
processor = AudioBatchProcessor(client.audio)
texts = ["Hello", "World", "Venice AI"]
saved_files = processor.process_batch(texts, "output_dir/")
```

### Character Management
```python
# List all characters
characters = client.characters.list()

# Search for specific characters
assistants = client.characters.search("assistant")

# Get a specific character
venice_char = client.characters.get("venice")

# Use character in chat
response = client.chat.complete(
    messages=[{"role": "user", "content": "Tell me about yourself"}],
    model="llama-3.3-70b",
    venice_parameters={"character_slug": "venice"}
)
```

### Embeddings and Semantic Search
```python
# Generate embeddings
embeddings = client.embeddings.generate([
    "Machine learning is fascinating",
    "AI will change the world",
    "The weather is nice today"
])

# Calculate similarity
similarity = embeddings[0].cosine_similarity(embeddings[1])
print(f"Similarity: {similarity}")

# Semantic search
from venice_sdk import SemanticSearch
search = SemanticSearch(client.embeddings)
search.add_documents([
    "Python is a programming language",
    "Machine learning uses algorithms",
    "The sky is blue"
])

results = search.search("programming", top_k=2)
for result in results:
    print(f"{result['similarity']:.3f}: {result['document']}")
```

### Video Generation
```python
# Text-to-video generation
job = client.video.queue(
    model="kling-2.6-pro-text-to-video",
    prompt="A cat playing with a ball of yarn in slow motion",
    duration=5,
    aspect_ratio="16:9",
    resolution="1080p"
)

# Wait for completion with progress tracking
def track_progress(job):
    print(f"Status: {job.status} - {job.progress}%")

completed_job = client.video.wait_for_completion(
    job.job_id,
    poll_interval=5,
    callback=track_progress
)

if completed_job.is_completed():
    completed_job.download("cat_video.mp4")

# Get price quote before generating
quote = client.video.quote(
    model="kling-2.6-pro-text-to-video",
    prompt="A beautiful sunset",
    duration=10,
    resolution="1080p"
)
print(f"Estimated cost: ${quote.estimated_cost} {quote.currency}")

# Image-to-video animation
image = client.images.generate(
    prompt="A serene mountain landscape",
    model="dall-e-3"
)

animated_job = client.video.queue(
    model="kling-2.6-pro-image-to-video",
    image=image.url,
    prompt="Animate with gentle movement",
    duration=5
)

completed_animated = client.video.wait_for_completion(animated_job.job_id)
if completed_animated.is_completed():
    completed_animated.download("animated_landscape.mp4")
```

### Account Management
```python
# Get account usage
usage = client.billing.get_usage()
print(f"Total usage: {usage.total_usage}")
print(f"Credits remaining: {usage.credits_remaining}")

# Check rate limits
limits = client.api_keys.get_rate_limits()
print(f"Requests per minute: {limits.requests_per_minute}")

# Generate Web3 API key
web3_key = client.api_keys.generate_web3_key(
    name="Web3 Integration",
    description="For blockchain applications"
)
print(f"Web3 Key: {web3_key.api_key}")

# Get account summary
summary = client.get_account_summary()
print(f"Account Summary: {summary}")
```

### Admin API Key Management
```python
# List all API keys
api_keys = client.api_keys.list()
for key in api_keys:
    print(f"Key: {key.name} ({key.id})")
    print(f"  Type: {key.permissions.get('type', 'Unknown')}")
    print(f"  Created: {key.created_at}")

# Create a new API key
new_key = client.api_keys.create(
    name="My New Key",
    permissions=["read", "write"]
)
print(f"Created key: {new_key.id}")

# Get specific API key details
key_details = client.api_keys.get(new_key.id)
print(f"Key details: {key_details}")

# Delete an API key
success = client.api_keys.delete(new_key.id)
print(f"Key deleted: {success}")

# Get comprehensive billing information
billing_summary = client.billing.get_billing_summary()
print(f"Billing Summary: {billing_summary}")

# Get detailed usage by model
model_usage = client.billing.get_usage_by_model()
for model, usage in model_usage.items():
    print(f"{model}: {usage.requests} requests, {usage.tokens} tokens")
```

### Advanced Model Features
```python
# Get model traits
traits = client.models_traits.get_traits()
for model_id, model_traits in traits.items():
    print(f"{model_id}:")
    print(f"  Function calling: {model_traits.supports_function_calling()}")
    print(f"  Web search: {model_traits.supports_web_search()}")

# Get compatibility mapping
mapping = client.models_compatibility.get_mapping()
venice_model = mapping.get_venice_model("gpt-3.5-turbo")
print(f"OpenAI gpt-3.5-turbo maps to: {venice_model}")

# Find models by capability
function_models = client.models_traits.find_models_by_capability("function_calling")
print(f"Models with function calling: {function_models}")
```

## CLI Usage

The SDK includes a command-line interface for managing your API credentials:

```bash
# Set your API key
venice auth your-api-key-here

# Check authentication status
venice status
```

### Advanced Chat Parameters

```python
# Advanced parameter control
response = client.chat.complete(
    messages=[{"role": "user", "content": "Write a creative story"}],
    model="llama-3.3-70b",
    temperature=1.2,
    frequency_penalty=0.3,
    presence_penalty=-0.1,
    repetition_penalty=1.1,
    max_completion_tokens=500,
    n=3,  # Generate 3 different responses
    seed=42,  # For reproducible results
    stop=["END", "STOP"]  # Stop sequences
)

# Dynamic temperature scaling
response = client.chat.complete(
    messages=[{"role": "user", "content": "Write a poem"}],
    model="llama-3.3-70b",
    min_temp=0.5,
    max_temp=1.5,
    logprobs=True,
    top_logprobs=3
)
```

### Streaming Chat

```python
# Stream chat responses in real-time
for chunk in client.chat.complete_stream(
    messages=[{"role": "user", "content": "Tell me a story about a robot"}],
    model="llama-3.3-70b"
):
    print(chunk, end="", flush=True)

# Or use the streaming method directly
response = client.chat.complete(
    messages=[{"role": "user", "content": "Hello!"}],
    model="llama-3.3-70b",
    stream=True,
    stream_options={"include_usage": True}
)

for chunk in response:
    if chunk.get("choices") and chunk["choices"][0].get("delta", {}).get("content"):
        print(chunk["choices"][0]["delta"]["content"], end="", flush=True)
```

### Function Calling

```python
# Define tools
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA"
                    }
                },
                "required": ["location"]
            }
        }
    }
]

# Use tools in chat
response = chat.complete(
    messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
    model="llama-3.3-70b",
    tools=tools
)
```

### Error Handling

```python
from venice_sdk.errors import VeniceAPIError, RateLimitError, UnauthorizedError

try:
    response = chat.complete(...)
except RateLimitError:
    print("Rate limit exceeded. Please try again later.")
except UnauthorizedError:
    print("Authentication failed. Please check your API key.")
except VeniceAPIError as e:
    print(f"API error: {e}")
```

## 🆕 What's New in v0.2.0

### Major Improvements
- **🔑 Admin API Key Management**: Full support for creating, listing, and deleting API keys
- **📊 Enhanced Billing**: Comprehensive usage tracking and rate limiting
- **🌊 Improved Streaming**: Better Server-Sent Events (SSE) support for real-time responses
- **🖼️ Image Enhancements**: Data URL support and improved file handling
- **✅ Robust Testing**: 1069 tests with 100% pass rate
- **🛡️ Better Error Handling**: More descriptive error messages and validation

### API Response Alignment
- Fixed all data structure mismatches with the actual Venice AI API
- Updated capability mapping to use correct API names
- Aligned all data classes with real API response formats

### Performance & Reliability
- Improved timeout handling and retry logic
- Enhanced test isolation to prevent interference
- Better environment variable management
- Comprehensive input validation

## Configuration

The SDK can be configured in several ways:

1. Environment variables:
   ```bash
   export VENICE_API_KEY="your-api-key"
   export VENICE_BASE_URL="https://api.venice.ai/api/v1"
   ```

2. `.env` file:
   ```env
   VENICE_API_KEY=your-api-key
   VENICE_BASE_URL=https://api.venice.ai/api/v1
   ```

3. Direct initialization:
   ```python
   client = VeniceClient(
       api_key="your-api-key",
       base_url="https://api.venice.ai/api/v1"
   )
   ```

## Development

1. Clone the repository
2. Install development dependencies:
   ```bash
   pip install -e ".[dev]"
   ```
3. Set up your environment variables in `.env`:
   ```env
   VENICE_API_KEY=your-api-key-here
   ```
4. Run tests:
   ```bash
   # Run all tests
   pytest
   
   # Run only live tests (requires API key)
   pytest tests/live/
   
   # Run specific test categories
   pytest tests/unit/
   pytest tests/integration/
   pytest tests/e2e/
   ```

### Test Coverage

The SDK includes a comprehensive test suite with:
- **1069 tests** covering all functionality
- **100% pass rate** with robust error handling
- **Live API tests** for real-world validation
- **Unit tests** for isolated component testing
- **Integration tests** for cross-module functionality
- **E2E tests** for complete workflow validation

### Documentation

To build the documentation:

```bash
pip install -e ".[docs]"
mkdocs serve
```

## License

This project uses a dual license structure:

- **Code/Software**: GNU Affero General Public License v3.0 (AGPLv3) - Strong copyleft protection, requires source code availability for network services
- **Documentation/Examples**: Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA) - Attribution required, derivative works must use same license

The Python SDK code is licensed under AGPLv3, while all documentation and examples are licensed under CC-BY-SA 4.0.

## Contributing

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