rax-ai 1.0.0
Official Python SDK for Rax AI Platform - AI API client with chat completions, streaming, and analytics
Requires Python: >=3.7
Keywords: ai, api, sdk, rax-ai, raxcore, chat, completion, llm, machine-learning, artificial-intelligence, python, async, streaming, analytics

# 🚀 Rax AI Python SDK

[![PyPI version](https://badge.fury.io/py/rax-ai.svg)](https://pypi.org/project/rax-ai/)
[![Python](https://img.shields.io/badge/Python-3.7+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Official Python SDK for Rax AI Platform - Simple, powerful, and integrated.**

## Install

```bash
pip install rax-ai
```

## Quick Start

```python
from rax_ai import RaxAI

rax = RaxAI(api_key="your-api-key")

response = rax.chat(
    model="rax-4.0",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

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

## Features

- ✅ **Simple API** - Clean, intuitive methods
- ✅ **Python 3.7+** - Compatible with most Python versions
- ✅ **Auto Retry** - Smart error handling with exponential backoff
- ✅ **Type Hints** - Full typing support
- ✅ **Models API** - List and manage available models
- ✅ **Usage Tracking** - Monitor your API consumption
- ✅ **Streaming** - Real-time response streaming (coming soon)

## Configuration

```python
from rax_ai import RaxAI

rax = RaxAI(
    api_key="your-key",
    base_url="https://ai.raxcore.dev/api",  # default
    timeout=30  # seconds, default
)
```

## Core Methods

### Chat Completions
```python
response = rax.chat(
    model="rax-4.0",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing"}
    ],
    max_tokens=150,
    temperature=0.7,
    top_p=0.9
)

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

### Streaming Chat
```python
for chunk in rax.chat_stream(
    model="rax-4.0",
    messages=[{"role": "user", "content": "Tell me a story..."}]
):
    print(chunk, end="", flush=True)
```

### Models Management
```python
# Get available models
models = rax.get_models()
print("Available models:", [m["id"] for m in models["data"]])

# Validate API key
is_valid = rax.validate_key()
print("Key valid:", is_valid)
```

### Usage Analytics
```python
# Get current usage
usage = rax.get_usage()
print("Total requests:", usage["total_requests"])
print("Total tokens:", usage["total_tokens"])

# Get usage for date range
monthly_usage = rax.get_usage(
    start_date="2024-01-01", 
    end_date="2024-01-31"
)
print("Monthly breakdown:", monthly_usage["daily_breakdown"])
```

## Error Handling

```python
from rax_ai import RaxAI, RaxAIError

try:
    response = rax.chat(
        model="rax-4.0",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except RaxAIError as e:
    print(f"API Error: {e.message}")
    print(f"Status: {e.status_code}")
    print(f"Type: {e.error_type}")
    print(f"Details: {e.to_dict()}")
```

## Environment Variables

```bash
# .env
RAX_AI_API_KEY=your-key-here
```

```python
import os
from rax_ai import RaxAI

rax = RaxAI(api_key=os.getenv("RAX_AI_API_KEY"))
```

## Framework Integration

### FastAPI
```python
from fastapi import FastAPI
from rax_ai import RaxAI

app = FastAPI()
rax = RaxAI(api_key=os.getenv("RAX_AI_API_KEY"))

@app.post("/chat")
async def chat_endpoint(message: str):
    response = rax.chat(
        model="rax-4.0",
        messages=[{"role": "user", "content": message}]
    )
    return response
```

### Flask
```python
from flask import Flask, request, jsonify
from rax_ai import RaxAI

app = Flask(__name__)
rax = RaxAI(api_key=os.getenv("RAX_AI_API_KEY"))

@app.route("/chat", methods=["POST"])
def chat():
    message = request.json["message"]
    response = rax.chat(
        model="rax-4.0",
        messages=[{"role": "user", "content": message}]
    )
    return jsonify(response)
```

### Django
```python
# views.py
from django.http import JsonResponse
from rax_ai import RaxAI
import json

rax = RaxAI(api_key=settings.RAX_AI_API_KEY)

def chat_view(request):
    data = json.loads(request.body)
    response = rax.chat(
        model="rax-4.0",
        messages=[{"role": "user", "content": data["message"]}]
    )
    return JsonResponse(response)
```

## Advanced Usage

### Configuration Management
```python
# Get current config
config = rax.get_config()
print("Base URL:", config["base_url"])
print("Timeout:", config["timeout"])
```

### Retry Logic
- **3 automatic retries** for network errors
- **Exponential backoff** (1s, 2s, 4s delays)
- **Smart error classification** (no retry for 4xx errors)
- **Timeout handling** with configurable timeouts

## Python Version Support

- ✅ Python 3.7+
- ✅ Python 3.8+
- ✅ Python 3.9+
- ✅ Python 3.10+
- ✅ Python 3.11+
- ✅ Python 3.12+

## Get Your API Key

1. Visit [ai.raxcore.dev](https://ai.raxcore.dev)
2. Sign up or log in
3. Navigate to API Keys
4. Create a new key
5. Start building!

## Type Hints

Full type hints included for better IDE support:

```python
from rax_ai.types import ChatMessage, ChatRequest, ChatResponse

messages: List[ChatMessage] = [
    {"role": "user", "content": "Hello!"}
]

response: ChatResponse = rax.chat(
    model="rax-4.0",
    messages=messages
)
```

## Support

- 📖 [Documentation](https://ai.raxcore.dev/docs)
- 🎮 [Playground](https://ai.raxcore.dev/playground)
- 📊 [Dashboard](https://ai.raxcore.dev/dashboard)
- 🐛 [Issues](https://github.com/Raxcore-dev/rax-ai-python/issues)

---

**Built for the Rax AI Platform at [ai.raxcore.dev](https://ai.raxcore.dev)**