Upload 4 files

docs/API_REFERENCE.md

@@ -35,9 +35,10 @@ All endpoints use the same request/response format.
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `messages` | Array<Message> | Yes | - | Array of conversation messages |
-| `temperature` | Float | No | 1.0 | Controls randomness (0.0 - 2.0) |
-| `top_p` | Float | No | 1.0 | Nucleus sampling parameter (0.0 - 1.0) |
-| `max_tokens` | Integer | No | 4096 | Maximum tokens in response |
+| `temperature` | Float | No | 0.7 | Controls randomness (0.0 - 2.0) |
+| `top_p` | Float | No | 0.95 | Nucleus sampling parameter (0.0 - 1.0) |
+| `max_tokens` | Integer | No | 8192 | Maximum tokens in response |
+| `stream` | Boolean | No | false | Enable streaming responses |
 
 **Message Object**:
 
@@ -58,15 +59,16 @@ All endpoints use the same request/response format.
       "content": "What is artificial intelligence?"
     }
   ],
-  "temperature": 1.0,
+  "temperature": 0.7,
   "top_p": 0.95,
-  "max_tokens": 512
+  "max_tokens": 8192,
+  "stream": false
 }
 ```
 
 #### Response
 
-**Success Response** (200 OK):
+**Standard Response** (200 OK):
 
 ```json
 {
@@ -74,6 +76,22 @@ All endpoints use the same request/response format.
 }
 ```
 
+**Streaming Response** (200 OK):
+
+When `stream: true` is set, the response is sent as Server-Sent Events:
+
+```
+data: {"content": "Artificial"}
+data: {"content": " intelligence"}
+data: {"content": " (AI)"}
+data: {"content": " refers"}
+data: {"content": " to"}
+data: {"content": "..."}
+data: [DONE]
+```
+
+Each line starts with `data: ` followed by a JSON object containing a `content` field with the next token. The stream ends with `data: [DONE]`.
+
 **Response Fields**:
 
 | Field | Type | Description |
@@ -111,7 +129,7 @@ All endpoints use the same request/response format.
 
 #### Example Usage
 
-**cURL**:
+**Standard Request (cURL)**:
 ```bash
 curl -X POST https://Rox-Turbo-API.hf.space/chat \
   -H "Content-Type: application/json" \
@@ -119,20 +137,32 @@ curl -X POST https://Rox-Turbo-API.hf.space/chat \
     "messages": [
       {"role": "user", "content": "Hello!"}
     ],
-    "temperature": 1.0,
-    "max_tokens": 512
+    "temperature": 0.7,
+    "max_tokens": 8192
   }'
 ```
 
-**JavaScript**:
+**Streaming Request (cURL)**:
+```bash
+curl -X POST https://Rox-Turbo-API.hf.space/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "Hello!"}
+    ],
+    "stream": true
+  }'
+```
+
+**Standard Request (JavaScript)**:
 ```javascript
 const response = await fetch('https://Rox-Turbo-API.hf.space/chat', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({
     messages: [{ role: 'user', content: 'Hello!' }],
-    temperature: 1.0,
-    max_tokens: 512
+    temperature: 0.7,
+    max_tokens: 8192
   })
 });
 
@@ -140,19 +170,85 @@ const data = await response.json();
 console.log(data.content);
 ```
 
-**Python**:
+**Streaming Request (JavaScript)**:
+```javascript
+const response = await fetch('https://Rox-Turbo-API.hf.space/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    messages: [{ role: 'user', content: 'Hello!' }],
+    stream: true
+  })
+});
+
+const reader = response.body.getReader();
+const decoder = new TextDecoder();
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+
+  const chunk = decoder.decode(value, { stream: true });
+  const lines = chunk.split('\n');
+
+  for (const line of lines) {
+    if (line.startsWith('data: ')) {
+      const data = line.slice(6).trim();
+      if (data === '[DONE]') break;
+
+      try {
+        const parsed = JSON.parse(data);
+        if (parsed.content) {
+          process.stdout.write(parsed.content);
+        }
+      } catch (e) {}
+    }
+  }
+}
+```
+
+**Standard Request (Python)**:
 ```python
 import requests
 
 response = requests.post('https://Rox-Turbo-API.hf.space/chat', json={
     'messages': [{'role': 'user', 'content': 'Hello!'}],
-    'temperature': 1.0,
-    'max_tokens': 512
+    'temperature': 0.7,
+    'max_tokens': 8192
 })
 
 print(response.json()['content'])
 ```
 
+**Streaming Request (Python)**:
+```python
+import requests
+import json
+
+response = requests.post(
+    'https://Rox-Turbo-API.hf.space/chat',
+    json={
+        'messages': [{'role': 'user', 'content': 'Hello!'}],
+        'stream': True
+    },
+    stream=True
+)
+
+for line in response.iter_lines():
+    if line:
+        line = line.decode('utf-8')
+        if line.startswith('data: '):
+            data = line[6:]
+            if data == '[DONE]':
+                break
+            try:
+                parsed = json.loads(data)
+                if 'content' in parsed:
+                    print(parsed['content'], end='', flush=True)
+            except json.JSONDecodeError:
+                pass
+```
+
 ---
 
 ### POST /hf/generate
@@ -313,8 +409,8 @@ Example:
 
 Maximum tokens in response.
 
-- **Range**: 1 to 8192
-- **Default**: 4096 (/chat), 8192 (/hf/generate)
+- **Range**: 1 to 32768
+- **Default**: 8192
 
 Token estimation:
 - ~1 token ≈ 4 characters
@@ -329,6 +425,41 @@ Example:
 }
 ```
 
+### stream
+
+Enable streaming responses for real-time token delivery.
+
+- **Type**: Boolean
+- **Default**: false
+- **Values**: true or false
+
+When enabled, responses are sent as Server-Sent Events instead of a single JSON response. This allows you to display tokens as they are generated rather than waiting for the complete response.
+
+Benefits of streaming:
+- Lower perceived latency
+- Better user experience for long responses
+- Ability to cancel generation early
+- Real-time feedback
+
+Example:
+
+```json
+{
+  "messages": [{"role": "user", "content": "Write a story"}],
+  "stream": true
+}
+```
+
+Response format when streaming is enabled:
+
+```
+data: {"content": "Once"}
+data: {"content": " upon"}
+data: {"content": " a"}
+data: {"content": " time"}
+data: [DONE]
+```
+
 ---
 
 ## Error Handling
@@ -424,9 +555,10 @@ class RoxAI {
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({
         messages,
-        temperature: options.temperature || 1.0,
+        temperature: options.temperature || 0.7,
         top_p: options.top_p || 0.95,
-        max_tokens: options.max_tokens || 512
+        max_tokens: options.max_tokens || 8192,
+        stream: false
       })
     });
 
@@ -438,6 +570,53 @@ class RoxAI {
     return data.content;
   }
 
+  async chatStream(messages, onToken, options = {}) {
+    const response = await fetch(`${this.baseURL}/chat`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        messages,
+        temperature: options.temperature || 0.7,
+        top_p: options.top_p || 0.95,
+        max_tokens: options.max_tokens || 8192,
+        stream: true
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let fullContent = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const chunk = decoder.decode(value, { stream: true });
+      const lines = chunk.split('\n');
+
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6).trim();
+          if (data === '[DONE]') break;
+
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.content) {
+              fullContent += parsed.content;
+              onToken(parsed.content);
+            }
+          } catch (e) {}
+        }
+      }
+    }
+
+    return fullContent;
+  }
+
   async generate(text, options = {}) {
     const response = await fetch(`${this.baseURL}/hf/generate`, {
       method: 'POST',
@@ -457,11 +636,18 @@ class RoxAI {
   }
 }
 
-// Usage
+// Standard usage
 const rox = new RoxAI();
 const response = await rox.chat([
   { role: 'user', content: 'Hello!' }
 ]);
+console.log(response);
+
+// Streaming usage
+await rox.chatStream(
+  [{ role: 'user', content: 'Tell me a story' }],
+  (token) => process.stdout.write(token)
+);
 ```
 
 ---

docs/DEVELOPER_GUIDE.md

@@ -1,235 +1,720 @@
 # Developer Guide
 
-**API**: `https://Rox-Turbo-API.hf.space`
+Complete guide for integrating Rox AI into your applications.
 
-## Overview
+**Base URL**: `https://Rox-Turbo-API.hf.space`
 
-Rox AI provides 8 AI models through a REST API. OpenAI-compatible.
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Authentication](#authentication)
+3. [Making Requests](#making-requests)
+4. [Streaming Responses](#streaming-responses)
+5. [Model Selection](#model-selection)
+6. [Parameters](#parameters)
+7. [Conversation Management](#conversation-management)
+8. [Error Handling](#error-handling)
+9. [Best Practices](#best-practices)
+10. [Code Examples](#code-examples)
+11. [OpenAI SDK Compatibility](#openai-sdk-compatibility)
+
+---
 
 ## Quick Start
 
+Send your first request in under 30 seconds.
+
+### cURL
+
 ```bash
 curl -X POST https://Rox-Turbo-API.hf.space/chat \
   -H "Content-Type: application/json" \
-  -d '{
-    "messages": [
-      {"role": "user", "content": "Hello"}
-    ]
-  }'
+  -d '{"messages":[{"role":"user","content":"Hello"}]}'
 ```
 
-Response:
+### Python
+
+```python
+import requests
+
+response = requests.post(
+    'https://Rox-Turbo-API.hf.space/chat',
+    json={'messages': [{'role': 'user', 'content': 'Hello'}]}
+)
+print(response.json()['content'])
+```
+
+### JavaScript
+
+```javascript
+const response = await fetch('https://Rox-Turbo-API.hf.space/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    messages: [{ role: 'user', content: 'Hello' }]
+  })
+});
+const data = await response.json();
+console.log(data.content);
+```
+
+---
+
+## Authentication
+
+No API key required. All endpoints are publicly accessible.
+
+---
+
+## Making Requests
+
+### Request Format
+
+All endpoints accept POST requests with JSON body.
+
+**Required Fields:**
+- `messages`: Array of message objects
+
+**Optional Fields:**
+- `temperature`: Float (0.0 - 2.0, default: 0.7)
+- `top_p`: Float (0.0 - 1.0, default: 0.95)
+- `max_tokens`: Integer (1 - 32768, default: 8192)
+- `stream`: Boolean (default: false)
+
+### Message Object
+
 ```json
 {
-  "content": "Hello! I'm Rox Core..."
+  "role": "user" | "assistant" | "system",
+  "content": "message text"
 }
 ```
 
-## Basic Usage
+### Complete Request Example
 
-### Python
+```json
+{
+  "messages": [
+    {"role": "system", "content": "You are a helpful assistant"},
+    {"role": "user", "content": "What is AI?"}
+  ],
+  "temperature": 0.7,
+  "top_p": 0.95,
+  "max_tokens": 8192,
+  "stream": false
+}
+```
+
+### Response Format
+
+**Standard Response:**
+```json
+{
+  "content": "AI stands for Artificial Intelligence..."
+}
+```
+
+**Streaming Response:**
+```
+data: {"content": "AI"}
+data: {"content": " stands"}
+data: {"content": " for"}
+data: [DONE]
+```
+
+---
+
+## Streaming Responses
+
+Streaming provides real-time token-by-token responses for better user experience.
+
+### When to Use Streaming
+
+- Long-form content generation
+- Interactive chat applications
+- Real-time feedback requirements
+- Improved perceived performance
+
+### Python Implementation
 
 ```python
 import requests
+import json
 
-def ask_rox(message, model='chat'):
+def stream_chat(message, model='chat'):
     response = requests.post(
         f'https://Rox-Turbo-API.hf.space/{model}',
-        json={'messages': [{'role': 'user', 'content': message}]}
+        json={
+            'messages': [{'role': 'user', 'content': message}],
+            'stream': True
+        },
+        stream=True
     )
-    return response.json()['content']
-
-answer = ask_rox('What is AI?')
-print(answer)
+    
+    for line in response.iter_lines():
+        if line:
+            line = line.decode('utf-8')
+            if line.startswith('data: '):
+                data = line[6:]
+                if data == '[DONE]':
+                    break
+                try:
+                    parsed = json.loads(data)
+                    if 'content' in parsed:
+                        print(parsed['content'], end='', flush=True)
+                        yield parsed['content']
+                except json.JSONDecodeError:
+                    pass
+
+# Usage
+for token in stream_chat('Tell me a story'):
+    pass  # Tokens printed in real-time
 ```
 
-### JavaScript
+### JavaScript Implementation
 
 ```javascript
-async function askRox(message, model = 'chat') {
+async function streamChat(message, model = 'chat') {
   const response = await fetch(`https://Rox-Turbo-API.hf.space/${model}`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({
-      messages: [{ role: 'user', content: message }]
+      messages: [{ role: 'user', content: message }],
+      stream: true
     })
   });
-  return (await response.json()).content;
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let fullContent = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    const chunk = decoder.decode(value, { stream: true });
+    const lines = chunk.split('\n');
+
+    for (const line of lines) {
+      if (line.startsWith('data: ')) {
+        const data = line.slice(6).trim();
+        if (data === '[DONE]') break;
+
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.content) {
+            fullContent += parsed.content;
+            console.log(parsed.content); // Process each token
+          }
+        } catch (e) {}
+      }
+    }
+  }
+
+  return fullContent;
 }
 
-const answer = await askRox('What is AI?');
+// Usage
+await streamChat('Tell me a story');
 ```
 
-## System Prompts
+### Node.js Implementation
 
-Add custom behavior:
+```javascript
+const https = require('https');
 
-```python
-def ask_with_prompt(message, system_prompt, model='chat'):
-    response = requests.post(
-        f'https://Rox-Turbo-API.hf.space/{model}',
-        json={
-            'messages': [
-                {'role': 'system', 'content': system_prompt},
-                {'role': 'user', 'content': message}
-            ]
+function streamChat(message, model = 'chat') {
+  const data = JSON.stringify({
+    messages: [{ role: 'user', content: message }],
+    stream: true
+  });
+
+  const options = {
+    hostname: 'Rox-Turbo-API.hf.space',
+    path: `/${model}`,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Content-Length': data.length
+    }
+  };
+
+  const req = https.request(options, (res) => {
+    res.on('data', (chunk) => {
+      const lines = chunk.toString().split('\n');
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6).trim();
+          if (data === '[DONE]') return;
+          
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.content) {
+              process.stdout.write(parsed.content);
+            }
+          } catch (e) {}
         }
-    )
-    return response.json()['content']
+      }
+    });
+  });
 
-answer = ask_with_prompt(
-    'Tell me about AI',
-    'You are a pirate. Talk like a pirate.',
-    'chat'
-)
+  req.write(data);
+  req.end();
+}
+
+// Usage
+streamChat('Tell me a story');
 ```
 
-## Parameters
+---
+
+## Model Selection
 
-### Temperature
+Choose the right model for your use case.
 
-Controls randomness (0.0 = focused, 2.0 = creative):
+### Available Models
+
+| Model | Endpoint | Best For | Speed | Quality |
+|-------|----------|----------|-------|---------|
+| Rox Core | `/chat` | General conversation | Medium | High |
+| Rox 2.1 Turbo | `/turbo` | Quick responses | Fast | Good |
+| Rox 3.5 Coder | `/coder` | Code generation | Medium | High |
+| Rox 4.5 Turbo | `/turbo45` | Fast reasoning | Fast | High |
+| Rox 5 Ultra | `/ultra` | Complex tasks | Slow | Highest |
+| Rox 6 Dyno | `/dyno` | Long context | Medium | High |
+| Rox 7 Coder | `/coder7` | Advanced coding | Medium | Highest |
+| Rox Vision Max | `/vision` | Visual tasks | Medium | High |
+
+### Model Selection Guide
 
 ```python
-response = requests.post(
-    'https://Rox-Turbo-API.hf.space/chat',
-    json={
-        'messages': [{'role': 'user', 'content': 'Write a poem'}],
-        'temperature': 1.5
+def select_model(task_type):
+    models = {
+        'chat': 'chat',           # General conversation
+        'quick': 'turbo',         # Fast responses
+        'code': 'coder',          # Code generation
+        'reasoning': 'turbo45',   # Complex reasoning
+        'complex': 'ultra',       # Highest quality
+        'long': 'dyno',           # Long documents
+        'advanced_code': 'coder7',# Advanced coding
+        'vision': 'vision'        # Visual tasks
     }
-)
+    return models.get(task_type, 'chat')
+
+# Usage
+model = select_model('code')
+response = ask_rox('Write a function', model=model)
 ```
 
-### Top P
+---
+
+## Parameters
+
+### temperature
+
+Controls randomness in responses.
 
-Controls diversity (0.0 = narrow, 1.0 = diverse):
+**Range**: 0.0 to 2.0  
+**Default**: 0.7
+
+- **0.0 - 0.3**: Deterministic, focused (math, facts, code)
+- **0.4 - 0.8**: Balanced (general conversation)
+- **0.9 - 2.0**: Creative, varied (stories, brainstorming)
 
 ```python
-response = requests.post(
-    'https://Rox-Turbo-API.hf.space/chat',
-    json={
-        'messages': [{'role': 'user', 'content': 'What is 2+2?'}],
-        'temperature': 0.3,
-        'top_p': 0.7
-    }
-)
+# Factual response
+response = requests.post(url, json={
+    'messages': [{'role': 'user', 'content': 'What is 2+2?'}],
+    'temperature': 0.2
+})
+
+# Creative response
+response = requests.post(url, json={
+    'messages': [{'role': 'user', 'content': 'Write a poem'}],
+    'temperature': 1.5
+})
 ```
 
-### Max Tokens
+### top_p
+
+Controls diversity via nucleus sampling.
 
-Limits response length:
+**Range**: 0.0 to 1.0  
+**Default**: 0.95
+
+- **0.1 - 0.5**: Narrow, focused
+- **0.6 - 0.9**: Balanced
+- **0.9 - 1.0**: Diverse
 
 ```python
-response = requests.post(
-    'https://Rox-Turbo-API.hf.space/chat',
-    json={
-        'messages': [{'role': 'user', 'content': 'Brief summary'}],
-        'max_tokens': 100
-    }
-)
+response = requests.post(url, json={
+    'messages': [{'role': 'user', 'content': 'Tell me about AI'}],
+    'top_p': 0.9
+})
 ```
 
-## OpenAI SDK
+### max_tokens
 
-Use the official OpenAI SDK:
+Maximum tokens in response.
 
-### Python
+**Range**: 1 to 32768  
+**Default**: 8192
+
+Token estimation: ~1 token = 0.75 words
 
 ```python
-from openai import OpenAI
+# Short response
+response = requests.post(url, json={
+    'messages': [{'role': 'user', 'content': 'Brief summary'}],
+    'max_tokens': 100
+})
+
+# Long response
+response = requests.post(url, json={
+    'messages': [{'role': 'user', 'content': 'Detailed explanation'}],
+    'max_tokens': 4096
+})
+```
 
-client = OpenAI(
-    base_url="https://Rox-Turbo-API.hf.space",
-    api_key="not-needed"
-)
+### stream
 
-response = client.chat.completions.create(
-    model="chat",
-    messages=[{"role": "user", "content": "Hello"}]
-)
+Enable streaming responses.
 
-print(response.choices[0].message.content)
+**Type**: Boolean  
+**Default**: false
+
+```python
+response = requests.post(url, json={
+    'messages': [{'role': 'user', 'content': 'Hello'}],
+    'stream': True
+}, stream=True)
 ```
 
-### JavaScript
+---
+
+## Conversation Management
+
+### Single Turn
+
+```python
+def ask_once(question):
+    response = requests.post(
+        'https://Rox-Turbo-API.hf.space/chat',
+        json={'messages': [{'role': 'user', 'content': question}]}
+    )
+    return response.json()['content']
+```
+
+### Multi-Turn Conversation
+
+```python
+class Conversation:
+    def __init__(self, model='chat', system_prompt=None):
+        self.model = model
+        self.messages = []
+        if system_prompt:
+            self.messages.append({'role': 'system', 'content': system_prompt})
+    
+    def ask(self, message):
+        self.messages.append({'role': 'user', 'content': message})
+        
+        response = requests.post(
+            f'https://Rox-Turbo-API.hf.space/{self.model}',
+            json={'messages': self.messages}
+        )
+        
+        reply = response.json()['content']
+        self.messages.append({'role': 'assistant', 'content': reply})
+        return reply
+    
+    def clear(self):
+        system_msg = [m for m in self.messages if m['role'] == 'system']
+        self.messages = system_msg
+
+# Usage
+conv = Conversation(system_prompt='You are a helpful assistant')
+print(conv.ask('Hello'))
+print(conv.ask('What is AI?'))
+print(conv.ask('Tell me more'))
+```
+
+### JavaScript Conversation Manager
 
 ```javascript
-import OpenAI from 'openai';
+class Conversation {
+  constructor(model = 'chat', systemPrompt = null) {
+    this.model = model;
+    this.messages = [];
+    if (systemPrompt) {
+      this.messages.push({ role: 'system', content: systemPrompt });
+    }
+  }
+  
+  async ask(message) {
+    this.messages.push({ role: 'user', content: message });
+    
+    const response = await fetch(`https://Rox-Turbo-API.hf.space/${this.model}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages: this.messages })
+    });
+    
+    const data = await response.json();
+    const reply = data.content;
+    
+    this.messages.push({ role: 'assistant', content: reply });
+    return reply;
+  }
+  
+  clear() {
+    const systemMsg = this.messages.filter(m => m.role === 'system');
+    this.messages = systemMsg;
+  }
+}
 
-const client = new OpenAI({
-  baseURL: 'https://Rox-Turbo-API.hf.space',
-  apiKey: 'not-needed'
-});
+// Usage
+const conv = new Conversation('chat', 'You are a helpful assistant');
+console.log(await conv.ask('Hello'));
+console.log(await conv.ask('What is AI?'));
+```
 
-const response = await client.chat.completions.create({
-  model: 'chat',
-  messages: [{ role: 'user', content: 'Hello' }]
-});
+### System Prompts
 
-console.log(response.choices[0].message.content);
+System prompts define the assistant's behavior.
+
+```python
+def ask_with_personality(message, personality):
+    system_prompts = {
+        'professional': 'You are a professional business consultant.',
+        'casual': 'You are a friendly, casual assistant.',
+        'technical': 'You are a technical expert. Be precise and detailed.',
+        'creative': 'You are a creative writer. Be imaginative and expressive.'
+    }
+    
+    messages = [
+        {'role': 'system', 'content': system_prompts.get(personality, '')},
+        {'role': 'user', 'content': message}
+    ]
+    
+    response = requests.post(
+        'https://Rox-Turbo-API.hf.space/chat',
+        json={'messages': messages}
+    )
+    return response.json()['content']
+
+# Usage
+answer = ask_with_personality('Explain AI', 'technical')
 ```
 
-## Model Selection
+---
+
+## Error Handling
+
+### Basic Error Handling
 
 ```python
-# General conversation
-ask_rox('Tell me about AI', model='chat')
+def safe_request(message, model='chat'):
+    try:
+        response = requests.post(
+            f'https://Rox-Turbo-API.hf.space/{model}',
+            json={'messages': [{'role': 'user', 'content': message}]},
+            timeout=30
+        )
+        response.raise_for_status()
+        return response.json()['content']
+    except requests.exceptions.Timeout:
+        return "Request timed out. Please try again."
+    except requests.exceptions.HTTPError as e:
+        return f"HTTP error: {e.response.status_code}"
+    except requests.exceptions.RequestException as e:
+        return f"Request failed: {str(e)}"
+    except KeyError:
+        return "Invalid response format"
+```
 
-# Fast response
-ask_rox('What is 2+2?', model='turbo')
+### Advanced Error Handling with Retry
 
-# Code generation
-ask_rox('Write a Python function', model='coder')
+```python
+import time
 
-# Advanced reasoning
-ask_rox('Explain quantum physics', model='turbo45')
+def request_with_retry(message, model='chat', max_retries=3):
+    for attempt in range(max_retries):
+        try:
+            response = requests.post(
+                f'https://Rox-Turbo-API.hf.space/{model}',
+                json={'messages': [{'role': 'user', 'content': message}]},
+                timeout=30
+            )
+            response.raise_for_status()
+            return response.json()['content']
+        except requests.exceptions.RequestException as e:
+            if attempt == max_retries - 1:
+                raise
+            wait_time = 2 ** attempt  # Exponential backoff
+            time.sleep(wait_time)
+```
 
-# Complex tasks
-ask_rox('Design a system', model='ultra')
+### JavaScript Error Handling
 
-# Long documents
-ask_rox('Analyze this document...', model='dyno')
+```javascript
+async function safeRequest(message, model = 'chat') {
+  try {
+    const response = await fetch(`https://Rox-Turbo-API.hf.space/${model}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        messages: [{ role: 'user', content: message }]
+      })
+    });
 
-# Advanced coding
-ask_rox('Build an algorithm', model='coder7')
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
 
-# Visual tasks
-ask_rox('Describe this image', model='vision')
+    const data = await response.json();
+    return data.content;
+  } catch (error) {
+    console.error('Request failed:', error);
+    throw error;
+  }
+}
 ```
 
-## Conversation History
+---
+
+## Best Practices
+
+### 1. Use Appropriate Models
+
+Choose models based on your needs:
+- Use `turbo` for simple, fast responses
+- Use `coder` for code-related tasks
+- Use `ultra` for complex reasoning
+- Use `dyno` for long documents
 
-Maintain context:
+### 2. Optimize Parameters
 
 ```python
-conversation = [
-    {'role': 'user', 'content': 'My name is Alice'},
-    {'role': 'assistant', 'content': 'Nice to meet you, Alice!'},
-    {'role': 'user', 'content': 'What is my name?'}
-]
+# For factual questions
+params = {'temperature': 0.2, 'max_tokens': 500}
 
-response = requests.post(
-    'https://Rox-Turbo-API.hf.space/chat',
-    json={'messages': conversation}
-)
+# For creative tasks
+params = {'temperature': 1.2, 'max_tokens': 2000}
 
-print(response.json()['content'])  # "Your name is Alice"
+# For code generation
+params = {'temperature': 0.3, 'max_tokens': 4096}
 ```
 
-## Chatbot Example
+### 3. Manage Context Length
 
-### Python
+```python
+def trim_conversation(messages, max_messages=10):
+    """Keep only recent messages to manage context"""
+    system_msgs = [m for m in messages if m['role'] == 'system']
+    other_msgs = [m for m in messages if m['role'] != 'system']
+    return system_msgs + other_msgs[-max_messages:]
+```
+
+### 4. Implement Caching
 
 ```python
+from functools import lru_cache
+import hashlib
+
+@lru_cache(maxsize=100)
+def cached_request(message_hash, model):
+    # Actual request implementation
+    pass
+
+def ask_with_cache(message, model='chat'):
+    message_hash = hashlib.md5(message.encode()).hexdigest()
+    return cached_request(message_hash, model)
+```
+
+### 5. Rate Limiting
+
+```python
+import time
+from collections import deque
+
+class RateLimiter:
+    def __init__(self, max_requests=10, time_window=60):
+        self.max_requests = max_requests
+        self.time_window = time_window
+        self.requests = deque()
+    
+    def wait_if_needed(self):
+        now = time.time()
+        
+        # Remove old requests
+        while self.requests and now - self.requests[0] > self.time_window:
+            self.requests.popleft()
+        
+        # Wait if at limit
+        if len(self.requests) >= self.max_requests:
+            sleep_time = self.time_window - (now - self.requests[0])
+            if sleep_time > 0:
+                time.sleep(sleep_time)
+        
+        self.requests.append(now)
+
+limiter = RateLimiter(10, 60)
+
+def rate_limited_request(message):
+    limiter.wait_if_needed()
+    return ask_rox(message)
+```
+
+### 6. Streaming for Long Responses
+
+Use streaming for responses over 500 tokens to improve user experience.
+
+### 7. Error Recovery
+
+```python
+def robust_request(message, model='chat'):
+    fallback_models = ['chat', 'turbo', 'coder']
+    
+    for fallback_model in fallback_models:
+        try:
+            return request_with_retry(message, fallback_model)
+        except Exception as e:
+            if fallback_model == fallback_models[-1]:
+                raise
+            continue
+```
+
+---
+
+## Code Examples
+
+### Complete Chatbot (Python)
+
+```python
+import requests
+import json
+
 class RoxChatbot:
-    def __init__(self, model='chat'):
+    def __init__(self, model='chat', system_prompt=None):
         self.model = model
-        self.conversation = []
         self.base_url = 'https://Rox-Turbo-API.hf.space'
+        self.conversation = []
+        
+        if system_prompt:
+            self.conversation.append({
+                'role': 'system',
+                'content': system_prompt
+            })
     
-    def chat(self, message):
+    def chat(self, message, stream=False):
         self.conversation.append({'role': 'user', 'content': message})
         
+        if stream:
+            return self._stream_chat()
+        else:
+            return self._standard_chat()
+    
+    def _standard_chat(self):
         response = requests.post(
             f'{self.base_url}/{self.model}',
             json={'messages': self.conversation}
@@ -239,28 +724,69 @@ class RoxChatbot:
         self.conversation.append({'role': 'assistant', 'content': reply})
         return reply
     
+    def _stream_chat(self):
+        response = requests.post(
+            f'{self.base_url}/{self.model}',
+            json={'messages': self.conversation, 'stream': True},
+            stream=True
+        )
+        
+        full_content = ''
+        for line in response.iter_lines():
+            if line:
+                line = line.decode('utf-8')
+                if line.startswith('data: '):
+                    data = line[6:]
+                    if data == '[DONE]':
+                        break
+                    try:
+                        parsed = json.loads(data)
+                        if 'content' in parsed:
+                            full_content += parsed['content']
+                            print(parsed['content'], end='', flush=True)
+                    except json.JSONDecodeError:
+                        pass
+        
+        print()  # New line after streaming
+        self.conversation.append({'role': 'assistant', 'content': full_content})
+        return full_content
+    
     def clear(self):
-        self.conversation = []
+        system_msgs = [m for m in self.conversation if m['role'] == 'system']
+        self.conversation = system_msgs
 
-bot = RoxChatbot()
+# Usage
+bot = RoxChatbot(system_prompt='You are a helpful assistant')
 print(bot.chat('Hello'))
 print(bot.chat('What is AI?'))
-print(bot.chat('Tell me more'))
+bot.chat('Tell me a story', stream=True)
 ```
 
-### JavaScript
+### Complete Chatbot (JavaScript)
 
 ```javascript
 class RoxChatbot {
-  constructor(model = 'chat') {
+  constructor(model = 'chat', systemPrompt = null) {
     this.model = model;
-    this.conversation = [];
     this.baseUrl = 'https://Rox-Turbo-API.hf.space';
+    this.conversation = [];
+    
+    if (systemPrompt) {
+      this.conversation.push({ role: 'system', content: systemPrompt });
+    }
   }
   
-  async chat(message) {
+  async chat(message, stream = false) {
     this.conversation.push({ role: 'user', content: message });
     
+    if (stream) {
+      return await this._streamChat();
+    } else {
+      return await this._standardChat();
+    }
+  }
+  
+  async _standardChat() {
     const response = await fetch(`${this.baseUrl}/${this.model}`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -274,108 +800,134 @@ class RoxChatbot {
     return reply;
   }
   
+  async _streamChat() {
+    const response = await fetch(`${this.baseUrl}/${this.model}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        messages: this.conversation,
+        stream: true
+      })
+    });
+    
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let fullContent = '';
+    
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      
+      const chunk = decoder.decode(value, { stream: true });
+      const lines = chunk.split('\n');
+      
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6).trim();
+          if (data === '[DONE]') break;
+          
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed.content) {
+              fullContent += parsed.content;
+              process.stdout.write(parsed.content);
+            }
+          } catch (e) {}
+        }
+      }
+    }
+    
+    console.log();
+    this.conversation.push({ role: 'assistant', content: fullContent });
+    return fullContent;
+  }
+  
   clear() {
-    this.conversation = [];
+    const systemMsgs = this.conversation.filter(m => m.role === 'system');
+    this.conversation = systemMsgs;
   }
 }
 
-const bot = new RoxChatbot();
+// Usage
+const bot = new RoxChatbot('chat', 'You are a helpful assistant');
 console.log(await bot.chat('Hello'));
 console.log(await bot.chat('What is AI?'));
+await bot.chat('Tell me a story', true);
 ```
 
-## Error Handling
+---
 
-```python
-def safe_ask(message, model='chat'):
-    try:
-        response = requests.post(
-            f'https://Rox-Turbo-API.hf.space/{model}',
-            json={'messages': [{'role': 'user', 'content': message}]},
-            timeout=30
-        )
-        response.raise_for_status()
-        return response.json()['content']
-    except requests.exceptions.Timeout:
-        return "Request timed out"
-    except requests.exceptions.RequestException as e:
-        return f"Error: {str(e)}"
-```
+## OpenAI SDK Compatibility
+
+Rox AI is compatible with the OpenAI SDK.
 
-## Rate Limiting
+### Python with OpenAI SDK
 
 ```python
-import time
+from openai import OpenAI
 
-class RateLimiter:
-    def __init__(self, max_requests=10, time_window=60):
-        self.max_requests = max_requests
-        self.time_window = time_window
-        self.requests = []
-    
-    def can_request(self):
-        now = time.time()
-        self.requests = [r for r in self.requests if now - r < self.time_window]
-        return len(self.requests) < self.max_requests
-    
-    def record_request(self):
-        self.requests.append(time.time())
+client = OpenAI(
+    base_url="https://Rox-Turbo-API.hf.space",
+    api_key="not-needed"  # No API key required
+)
 
-limiter = RateLimiter(10, 60)
+# Standard request
+response = client.chat.completions.create(
+    model="chat",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+print(response.choices[0].message.content)
 
-def ask_with_limit(message):
-    if not limiter.can_request():
-        return "Rate limit exceeded"
-    limiter.record_request()
-    return ask_rox(message)
+# Streaming request
+stream = client.chat.completions.create(
+    model="chat",
+    messages=[{"role": "user", "content": "Tell me a story"}],
+    stream=True
+)
+
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end='', flush=True)
 ```
 
-## Caching
+### JavaScript with OpenAI SDK
 
-```python
-from functools import lru_cache
+```javascript
+import OpenAI from 'openai';
 
-@lru_cache(maxsize=100)
-def cached_ask(message, model='chat'):
-    response = requests.post(
-        f'https://Rox-Turbo-API.hf.space/{model}',
-        json={'messages': [{'role': 'user', 'content': message}]}
-    )
-    return response.json()['content']
+const client = new OpenAI({
+  baseURL: 'https://Rox-Turbo-API.hf.space',
+  apiKey: 'not-needed'
+});
+
+// Standard request
+const response = await client.chat.completions.create({
+  model: 'chat',
+  messages: [{ role: 'user', content: 'Hello' }]
+});
+console.log(response.choices[0].message.content);
+
+// Streaming request
+const stream = await client.chat.completions.create({
+  model: 'chat',
+  messages: [{ role: 'user', content: 'Tell me a story' }],
+  stream: true
+});
 
-answer1 = cached_ask('What is AI?')  # API call
-answer2 = cached_ask('What is AI?')  # Cached
+for await (const chunk of stream) {
+  if (chunk.choices[0]?.delta?.content) {
+    process.stdout.write(chunk.choices[0].delta.content);
+  }
+}
 ```
 
-## Reference
+---
 
-```python
-# Basic request
-requests.post('https://Rox-Turbo-API.hf.space/chat', 
-              json={'messages': [{'role': 'user', 'content': 'Hello'}]})
-
-# With parameters
-requests.post('https://Rox-Turbo-API.hf.space/chat',
-              json={'messages': [...], 'temperature': 0.7, 'max_tokens': 500})
-
-# With system prompt
-requests.post('https://Rox-Turbo-API.hf.space/chat',
-              json={'messages': [
-                  {'role': 'system', 'content': 'You are helpful'},
-                  {'role': 'user', 'content': 'Hello'}
-              ]})
-```
-
-## Endpoints
-
-- `/chat` - Rox Core
-- `/turbo` - Rox 2.1 Turbo
-- `/coder` - Rox 3.5 Coder
-- `/turbo45` - Rox 4.5 Turbo
-- `/ultra` - Rox 5 Ultra
-- `/dyno` - Rox 6 Dyno
-- `/coder7` - Rox 7 Coder
-- `/vision` - Rox Vision Max
+## Additional Resources
+
+- [API Reference](API_REFERENCE.md) - Complete API documentation
+- [Code Examples](CODE.md) - Ready-to-use code snippets
+- [Model Guide](MODELS.md) - Detailed model information
 
 ---