zaguan-sdk 0.1.0

Official Python SDK for Zaguan CoreX

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

pip install zaguan-sdk

Quick Start

Synchronous Usage

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

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 directory:

• SDK Design Overview
• Python Implementation Notes
• Complete Examples
• Core Types
• HTTP Contract
• Testing and Versioning

Development

Installation

pip install -r requirements.txt

Running Tests

python -m pytest tests/ -v

License

Apache License 2.0