Metadata-Version: 2.4
Name: zaguan-sdk
Version: 0.1.0
Summary: Official Python SDK for Zaguan CoreX
Author-email: Zaguan AI <support@zaguanai.com>
License: Apache-2.0
Project-URL: Homepage, https://zaguanai.com
Project-URL: Repository, https://github.com/ZaguanLabs/zaguan-sdk-python
Project-URL: Documentation, https://zaguanai.com/docs
Project-URL: API, https://api.zaguanai.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.23.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: respx>=0.20.0; extra == "test"
Dynamic: license-file

# zaguan-sdk-python
Official Zaguán SDK for Python

## Overview

The official Python SDK for Zaguán CoreX - an enterprise-grade AI gateway that provides unified access to 15+ AI providers and 500+ models through a single, OpenAI-compatible API.

## Installation

```bash
pip install zaguan-sdk
```

## Quick Start

### Synchronous Usage

```python
from zaguan_sdk import ZaguanClient, ChatRequest, Message

# Initialize client
client = ZaguanClient(
    base_url="https://api.zaguanai.com",
    api_key="your-api-key"
)

# Create chat request
request = ChatRequest(
    model="openai/gpt-4o-mini",
    messages=[
        Message(role="user", content="Hello! How are you?")
    ]
)

# Make request
response = client.chat(request)

# Print response
print(response.choices[0].message.content)
```

### Asynchronous Usage

```python
import asyncio
from zaguan_sdk import AsyncZaguanClient, ChatRequest, Message

async def main():
    # Initialize client
    client = AsyncZaguanClient(
        base_url="https://api.zaguanai.com",
        api_key="your-api-key"
    )

    # Create chat request
    request = ChatRequest(
        model="openai/gpt-4o-mini",
        messages=[
            Message(role="user", content="Hello! How are you?")
        ]
    )

    # Make request
    response = await client.chat(request)

    # Print response
    print(response.choices[0].message.content)

asyncio.run(main())
```

## Features

- **Synchronous and Asynchronous Clients**: Support for both sync and async usage patterns
- **OpenAI Compatibility**: Drop-in replacement for OpenAI SDK with additional features
- **Multi-Provider Support**: Access to 15+ AI providers through a single API
- **Streaming Support**: Real-time response streaming with cancellation support
- **Error Handling**: Comprehensive error handling with specific exception types
- **Type Safety**: Full type hints and Pydantic models for all API objects
- **Credits Management**: Access to credits balance, history, and statistics
- **Embeddings**: Create embeddings for semantic search and RAG
- **Audio**: Transcription, translation, and text-to-speech (Whisper, TTS)
- **Images**: Generation, editing, and variations (DALL-E)
- **Moderations**: Content safety and policy compliance checking

### Supported Endpoints

✅ Chat Completions (streaming & non-streaming)  
✅ Models & Capabilities  
✅ Credits Management  
✅ Embeddings  
✅ Audio (Transcription, Translation, Speech)  
✅ Images (Generation, Editing, Variations)  
✅ Content Moderation  

**100% coverage of major OpenAI-compatible endpoints**

## Documentation

For detailed documentation, see the files in the [docs/SDK](docs/SDK) directory:

- [SDK Design Overview](docs/SDK/SDK_DESIGN_OVERVIEW.md)
- [Python Implementation Notes](docs/SDK/SDK_PYTHON_IMPLEMENTATION_NOTES.md)
- [Complete Examples](docs/SDK/SDK_EXAMPLES.md)
- [Core Types](docs/SDK/SDK_CORE_TYPES.md)
- [HTTP Contract](docs/SDK/SDK_HTTP_CONTRACT.md)
- [Testing and Versioning](docs/SDK/SDK_TESTING_AND_VERSIONING.md)

## Development

### Installation

```bash
pip install -r requirements.txt
```

### Running Tests

```bash
python -m pytest tests/ -v
```

## License

Apache License 2.0
