Metadata-Version: 2.4
Name: deepailab
Version: 0.2.0b1
Summary: Official Python SDK for DeepAI Lab API
Project-URL: Homepage, https://docs.deepailab.ai/sdk/python
Project-URL: Documentation, https://docs.deepailab.ai/sdk/python
Project-URL: Repository, https://github.com/deepailab/deepailab-sdk-python
Project-URL: Bug Tracker, https://github.com/deepailab/deepailab-sdk-python/issues
Project-URL: Changelog, https://github.com/deepailab/deepailab-sdk-python/blob/main/CHANGELOG.md
Author-email: DeepAI Lab <sdk@deepailab.ai>
Maintainer-email: DeepAI Lab <sdk@deepailab.ai>
License-Expression: MIT
Keywords: ai,api,deepailab,embeddings,llm,openai,python,sdk
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.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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.5.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-autodoc-typehints>=1.22.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == 'docs'
Requires-Dist: sphinx>=6.0.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: respx>=0.20.0; extra == 'test'
Description-Content-Type: text/markdown

# DeepAI Lab Python SDK

[![PyPI version](https://badge.fury.io/py/deepailab.svg)](https://badge.fury.io/py/deepailab)
[![CI](https://github.com/deepailab/deepailab-sdk-python/workflows/CI/badge.svg)](https://github.com/deepailab/deepailab-sdk-python/actions)
[![codecov](https://codecov.io/gh/deepailab/deepailab-sdk-python/branch/main/graph/badge.svg)](https://codecov.io/gh/deepailab/deepailab-sdk-python)

Official Python SDK for the DeepAI Lab API platform. Supports OpenAI-compatible endpoints, model marketplace, and enterprise features.

## 🚀 Quick Start (30 seconds)

### Installation

```bash
pip install deepailab
# or
poetry add deepailab
# or
pipenv install deepailab
```

### Basic Usage

```python
import deepailab

client = deepailab.DeepAILab(
    api_key="sk-deepailab-your-api-key-here",
    # base_url="https://api.deepailab.ai"  # Optional, defaults to production
)

# Chat completion
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "Hello, world!"}
    ],
    max_tokens=100
)

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

## 📚 Features

- ✅ **OpenAI Compatible**: Drop-in replacement for OpenAI SDK
- ✅ **Type Hints**: Full type safety with mypy support
- ✅ **Async/Await**: Native asyncio support
- ✅ **Streaming**: Server-sent events (SSE) support
- ✅ **Error Handling**: Comprehensive exception types and retry logic
- ✅ **Rate Limiting**: Built-in exponential backoff
- ✅ **Observability**: Request metrics and cost tracking
- ✅ **Multi-tenancy**: On-behalf-of (OBO) support
- ✅ **Model Marketplace**: Access to user-published models
- ✅ **Context Managers**: Automatic resource cleanup
- ✅ **Cancellation**: asyncio.CancelledError support

## 🔧 API Reference

### Chat Completions

```python
# Synchronous
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing"}
    ],
    max_tokens=500,
    temperature=0.7
)

# Asynchronous
import asyncio

async def main():
    async with deepailab.AsyncDeepAILab(api_key="your-key") as client:
        response = await client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Hello"}]
        )
        print(response.choices[0].message.content)

asyncio.run(main())
```

### Streaming

```python
# Synchronous streaming
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

# Asynchronous streaming
async def stream_example():
    async with deepailab.AsyncDeepAILab(api_key="your-key") as client:
        stream = await client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Tell me a story"}],
            stream=True
        )
        
        async for chunk in stream:
            content = chunk.choices[0].delta.content
            if content:
                print(content, end="", flush=True)
```

### Embeddings

```python
response = client.embeddings.create(
    model="text-embedding-3-large",
    input=["Hello world", "How are you?"]
)

print(response.data[0].embedding)  # [0.1, 0.2, ...]
```

### Models

```python
models = client.models.list()
for model in models.data:
    print(f"{model.id}: {model.owned_by}")
```

### Model Marketplace

```python
# Call a user-published model
result = client.model_gateway.infer(
    user_id="user123",
    model_id="my-model",
    input={"text": "Analyze this sentiment"},
    parameters={"temperature": 0.5}
)

# Batch processing
batch = client.model_gateway.batch(
    user_id="user123",
    model_id="my-model",
    input_file_id="file-abc123",
    endpoint="/v1/inference"
)

# Check model status
status = client.model_gateway.status("user123", "my-model")
print(status.status)  # 'deployed' | 'deploying' | 'failed' | 'maintenance'
```

### On-Behalf-Of (Multi-tenancy)

```python
# Make requests on behalf of end users
obo_client = client.as_user(
    user="end-user-123",
    tenant="organization-456"
)

response = obo_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)
# Usage will be attributed to end-user-123 and organization-456
```

## 🔒 Security Best Practices

### Environment Variables

```python
import os
import deepailab

# ✅ Use environment variables
client = deepailab.DeepAILab(
    api_key=os.getenv("DEEPAILAB_API_KEY")
)

# ✅ Or use a .env file with python-dotenv
from dotenv import load_dotenv
load_dotenv()

client = deepailab.DeepAILab(
    api_key=os.getenv("DEEPAILAB_API_KEY")
)
```

### Session Tokens for Web Apps

```python
# For web applications, use short-lived session tokens
def get_session_token(user_jwt: str) -> str:
    """Get a short-lived session token from your auth service."""
    # Your implementation here
    pass

client = deepailab.DeepAILab(
    api_key=get_session_token(user_jwt)  # Short-lived token
)
```

## 📊 Observability & Metrics

```python
def metrics_callback(metrics):
    print(f"Request ID: {metrics.request_id}")
    print(f"Response Time: {metrics.response_time}ms")
    print(f"Tokens Used: {metrics.usage.total_tokens}")
    print(f"Cost: {metrics.cost.amount} {metrics.cost.currency}")

client = deepailab.DeepAILab(
    api_key="your-key",
    on_metrics=metrics_callback
)
```

## 🔄 Error Handling & Retries

```python
import deepailab
from deepailab import (
    RateLimitError,
    AuthenticationError,
    TimeoutError,
    ValidationError
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}]
    )
except RateLimitError as e:
    print(f"Rate limited. Retry after: {e.retry_after}")
except AuthenticationError:
    print("Invalid API key")
except TimeoutError:
    print("Request timed out")
except ValidationError as e:
    print(f"Validation error: {e.message}")
except deepailab.DeepAILabError as e:
    print(f"Other error: {e}")
```

## 🔧 Configuration

```python
client = deepailab.DeepAILab(
    api_key="your-key",
    base_url="https://api.deepailab.ai",  # Custom base URL
    timeout=30.0,  # Request timeout in seconds
    max_retries=3,  # Maximum retry attempts
    default_headers={"User-Agent": "MyApp/1.0"},  # Custom headers
    debug=True  # Enable debug logging
)
```

## 🧪 Testing

```python
# Use the test client for unit tests
from deepailab.testing import MockDeepAILab

def test_chat_completion():
    client = MockDeepAILab()
    client.mock_response("chat.completions.create", {
        "choices": [{"message": {"content": "Hello!"}}]
    })
    
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hi"}]
    )
    
    assert response.choices[0].message.content == "Hello!"
```

## 📖 More Examples

- [Synchronous Example](./examples/sync.py)
- [Asynchronous Example](./examples/async.py)
- [Streaming Example](./examples/streaming.py)
- [Model Marketplace Example](./examples/marketplace.py)
- [On-Behalf-Of Example](./examples/obo.py)
- [Django Integration](./examples/django_integration.py)
- [FastAPI Integration](./examples/fastapi_integration.py)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](./LICENSE) for details.

## 🆘 Support

- 📚 [Documentation](https://docs.deepailab.ai/sdk/python)
- 🐛 [Bug Reports](https://github.com/deepailab/deepailab-sdk-python/issues)
- 💬 [Discord Community](https://discord.gg/deepailab)
- 📧 [Email Support](mailto:sdk@deepailab.ai)
