Metadata-Version: 2.4
Name: luxur-ai
Version: 3.1.0
Summary: Python SDK for LuxurAI — 322 Neural Voice Models, LLM Streaming, Unified History, Chat & Code
Home-page: https://luxurai.in
Author: NexInova
Author-email: NexInova <dev@luxurai.in>
License: MIT
Project-URL: Homepage, https://luxurai.in
Project-URL: Documentation, https://luxurai.in/docs
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.20.0
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 🌌 3.1.0 LuxurAI SDK (Python)

Welcome to the official **3.1.0 LuxurAI SDK** for Python — India's premier, enterprise-grade AI client library. Built with persistent HTTP connection pooling (`httpx`), native asynchronous support (`AsyncLuxurAI`), strongly-typed models with dual dot/subscript access, real-time SSE token streaming, zero-dependency audio playback, smart account state management, and 322 neural voice models across 140+ languages.

---

## 🚀 Installation

Install via pip or in editable developer mode:

```bash
pip install luxur-ai
# Or local development mode:
cd luxurai-sdk && pip install -e .
```

---

## ⚡ Quickstart: Synchronous & Asynchronous

```python
from luxurai import LuxurAI, AsyncLuxurAI

# 1. Synchronous Client (Context Managed with Connection Pooling)
with LuxurAI(api_key="lxr_v1_...") as client:
    # Strongly-typed responses with dot-notation
    plan = client.chat.orchestrate("Design a real-time analytics pipeline")
    print(plan.response_to_user)
    print(f"Cost: {plan.lc_cost} LC | Remaining: {plan.balance_lc} LC")

    # Smart Auto-Preloaded Profile
    print(f"User Rank: {client.me.rank} | Balance: {client.me.balance} LC")
```

### Async / Await Support:
```python
import asyncio
from luxurai import AsyncLuxurAI

async def main():
    async with AsyncLuxurAI(api_key="lxr_v1_...") as client:
        # Real-time SSE token streaming
        async for chunk in client.stream.chat_async("Explain quantum computing"):
            if chunk.get("type") == "token":
                print(chunk["text"], end="", flush=True)

asyncio.run(main())
```

---

### 2. Neural Voice Synthesis (`luxurai.voice`)
Powered by 322 LuxurAI Neural Voices across 142 regional accents with sub-second latency:

```python
# 🎙️ Generate high-fidelity neural speech
audio = luxurai.voice.speak(
    text="नमस्ते! लक्ज़र एआई में आपका स्वागत है।",
    gender="female",      # "female" | "male"
    lang="hi",            # "hi", "en", "es", "ja", or "auto"
    speed=1.0,            # 0.5 to 2.0
    save_to="welcome.mp3" # Save directly to file
)

print(f"Model used: {audio.model_used}")
print(f"Permanent Hugging Face URL: {audio.audio_url}")
```

#### Direct Speaker Playback (`.play`)
Play audio through your speakers with zero external audio dependencies:
```python
# Plays directly through the speaker
luxurai.voice.play("Hello world! Welcome to LuxurAI voice engine.", gender="female")
```

---

### 3. Real-Time LLM Token Streaming (`type="chunk"`)
When generating text with an LLM token-by-token, use `type="chunk"` to stream speech without waiting for the full response:
- Buffers words on your local device until punctuation (`.`, `!`, `?`, `,`, `;`, `\n`).
- Sends each sentence chunk to the server immediately.
- Auto-plays the returned audio chunk through the speakers on arrival while continuing the LLM generation loop!

```python
# ⚡ Instant voice playback from an LLM token stream
def get_llm_stream():
    words = ["Hello", " there!", " Welcome", " to", " the", " future", " of", " voice", " AI."]
    for w in words:
        yield w

# Auto-chunks by punctuation and plays each sentence chunk seamlessly:
luxurai.voice.play(
    stream=get_llm_stream(),
    type="chunk",
    gender="female",
    lang="auto"
)
```

---

### 4. Browse the 322 Neural Voice Models
Search and inspect all available neural voice models across 140+ language locales:

```python
# Filter by language or gender
hindi_voices = luxurai.voice.list_voices(lang="hi", gender="female")
for v in hindi_voices:
    print(v["ShortName"], v["Gender"], v["LocaleName"])
```

---

### 5. Unified Generation History (`luxurai.history`)
Inspect past voice generations, chat sessions, and code generations:

```python
# List recent generations
history = luxurai.history.list(type="voice", limit=20)

for item in history.get("history", []):
    print(item["id"], item["created_at"], item["text"], item.get("audio_url"))

# Get specific generation details
item = luxurai.history.get("gen_123456")
```

---

### 6. Privacy & Ghost Mode (`store_voice=False`)
By default, voice generations made with an API key are safely backed up to the Hugging Face 8.3 TB dataset and your user history. To opt out for complete privacy:

```python
# Does NOT save to Hugging Face or history
audio = luxurai.voice.speak(
    text="Confidential audio synthesis",
    gender="male",
    store_voice=False
)
```

---

### 7. Smart Chat & Orchestration
Communicate with **Luxur**, the senior-dev brain of the platform:

```python
# 🧠 Smart chatbot routing & orchestration
reply = luxurai.chat.orchestrate(
    message="Write a clean binary search in Python",
    complexity="low"
)

print(reply["response_to_user"])
```

---

### 8. Code Generation
Direct structural code synthesis:

```python
# 💻 Code synthesis
code = luxurai.code.generate(
    prompt="A FastAPI middleware to validate JWT session tokens",
    language="python"
)
print(code["code"])
```

---

### 9. Rate Limits
All developer API keys are protected by multi-tier rate limiting:
- **Daily Quota:** 300 requests / day (Free tier)
- **Minute Limit:** 13 requests / minute
- **Burst Limit:** 2 requests / second
