docs/MODELS.md

# Models Guide

Reference for all Rox AI models.

## Model Overview

Rox AI offers eight specialized models, each optimized for different use cases:

| Model | Endpoint | Best For | Max Tokens | Default Temp |
|-------|----------|----------|------------|--------------|
| **Rox Core** | `/chat` | General conversation | 4,096 | 1.0 |
| **Rox 2.1 Turbo** | `/turbo` | Fast responses | 4,096 | 0.6 |
| **Rox 3.5 Coder** | `/coder` | Code generation | 16,384 | 0.6 |
| **Rox 4.5 Turbo** | `/turbo45` | Advanced reasoning | 8,192 | 0.2 |
| **Rox 5 Ultra** | `/ultra` | Superior reasoning | 8,192 | 1.0 |
| **Rox 6 Dyno** | `/dyno` | Extended context | 16,384 | 1.0 |
| **Rox 7 Coder** | `/coder7` | Advanced coding | 16,384 | 1.0 |
| **Rox Vision Max** | `/vision` | Visual understanding | 512 | 0.2 |

---

## Rox Core

**Endpoint**: `POST /chat`

### Description
General-purpose conversational model for everyday tasks.

### Best Use Cases
- General conversation and Q&A
- Content writing and generation
- Creative tasks (stories, poems, ideas)
- Summarization and analysis
- Educational tutoring
- Customer support

### Parameters
- **Temperature**: 1.0 (balanced creativity)
- **Top P**: 1.0 (full diversity)
- **Max Tokens**: 4,096

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Explain quantum computing in simple terms"}
    ],
    "temperature": 1.0,
    "max_tokens": 512
  }'
```

### When to Choose Rox Core
- You need creative, varied responses
- Task requires nuanced understanding
- Building a general-purpose chatbot
- Content needs to be engaging and natural

---

## Rox 2.1 Turbo

**Endpoint**: `POST /turbo`

### Description
Fast model for quick responses and real-time applications.

### Best Use Cases
- Real-time chat applications
- Customer support bots
- Quick Q&A systems
- High-throughput applications
- Simple queries and commands
- Factual information retrieval

### Parameters
- **Temperature**: 0.6 (more focused)
- **Top P**: 0.7 (more consistent)
- **Max Tokens**: 4,096

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/turbo \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What are the business hours?"}
    ]
  }'
```

### When to Choose Rox 2.1 Turbo
- Speed is critical
- Need consistent, reliable answers
- Building customer support systems
- High volume of requests
- Simple, straightforward queries

---

## Rox 3.5 Coder

**Endpoint**: `POST /coder`

### Description
Code-focused model for programming tasks and technical work.

### Best Use Cases
- Code generation and completion
- Debugging and error fixing
- Algorithm design and optimization
- Technical documentation
- Code review and suggestions
- Software architecture discussions
- API integration help

### Parameters
- **Temperature**: 0.6 (precise and focused)
- **Top P**: 0.95 (balanced diversity)
- **Max Tokens**: 16,384 (extended context)
- **Special Features**: Enhanced thinking mode

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/coder \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Write a Python function to implement binary search"}
    ],
    "max_tokens": 2048
  }'
```

### When to Choose Rox 3.5 Coder
- Working with code in any language
- Need detailed technical explanations
- Debugging complex issues
- Designing algorithms or systems
- Writing technical documentation
- Need extended context (up to 16K tokens)

---

## Comparison Matrix

### Performance Characteristics

| Feature | Rox Core | Rox 2.1 Turbo | Rox 3.5 Coder | Rox 4.5 Turbo | Rox 5 Ultra | Rox 6 Dyno | Rox 7 Coder | Rox Vision |
|---------|----------|---------------|---------------|---------------|-------------|------------|-------------|------------|
| **Speed** | Medium | Fast | Medium | Fast | Medium | Medium | Medium | Fast |
| **Creativity** | High | Medium | Low | Low | High | High | Medium | Low |
| **Consistency** | Medium | High | High | Very High | High | Medium | High | Very High |
| **Code Quality** | Good | Good | Excellent | Good | Excellent | Good | Superior | N/A |
| **Context Length** | 4K | 4K | 16K | 8K | 8K | 16K | 16K | 512 |
| **Thinking Mode** | No | No | Yes | Yes | Yes | Yes | Yes | No |
| **Reasoning** | Basic | Basic | Advanced | Very Advanced | Superior | Advanced | Superior | Basic |

### Use Case Recommendations

| Task | Recommended Model | Why |
|------|------------------|-----|
| Write a blog post | Rox Core | Creative, engaging content |
| Answer "What is X?" | Rox 2.1 Turbo | Fast, factual response |
| Debug Python code | Rox 3.5 Coder | Code specialist |
| Customer support | Rox 2.1 Turbo | Quick, consistent answers |
| Write a story | Rox Core | Creative and varied |
| Explain algorithm | Rox 3.5 Coder | Technical depth |
| Translate text | Rox 2.1 Turbo | Fast and accurate |
| Design API | Rox 3.5 Coder | Technical expertise |
| Brainstorm ideas | Rox Core | Creative thinking |
| Code review | Rox 3.5 Coder | Code understanding |
| Complex reasoning | Rox 4.5 Turbo | Advanced thinking |
| Research analysis | Rox 5 Ultra | Superior reasoning |
| System architecture | Rox 5 Ultra | Complex design |
| Long documents | Rox 6 Dyno | Extended context |
| Large codebase | Rox 7 Coder | Advanced coding |
| Image analysis | Rox Vision Max | Visual understanding |

---

## Model Selection Guide

### Decision Tree

```
Need to work with code?
├─ Yes
│  ├─ Simple/medium tasks? → Rox 3.5 Coder
│  └─ Complex/large-scale? → Rox 7 Coder
└─ No
   ├─ Need advanced reasoning?
   │  ├─ Yes
   │  │  ├─ Need highest quality? → Rox 5 Ultra
   │  │  └─ Need speed? → Rox 4.5 Turbo
   │  └─ No
   │     ├─ Long documents? → Rox 6 Dyno
   │     ├─ Visual tasks? → Rox Vision Max
   │     ├─ Need fast responses? → Rox 2.1 Turbo
   │     └─ Need creative output? → Rox Core
```

### Quick Selection Tips

**Choose Rox Core when:**
- Default choice for most tasks
- Need creative, engaging responses
- Building general chatbots
- Content generation projects

**Choose Rox 2.1 Turbo when:**
- Speed matters most
- Need consistent answers
- High request volume
- Simple Q&A systems

**Choose Rox 3.5 Coder when:**
- Any coding task
- Technical documentation
- Algorithm design
- Need extended context

**Choose Rox 6 Dyno when:**
- Processing long documents
- Extended context needed
- Multi-document analysis
- Long conversations

**Choose Rox 7 Coder when:**
- Most complex coding tasks
- Large-scale projects
- System architecture
- Advanced algorithms

**Choose Rox Vision Max when:**
- Visual understanding
- Image analysis
- Multimodal tasks

---

## Advanced Usage

### Switching Models Dynamically

```javascript
class RoxAI {
  constructor(baseUrl = 'https://Rox-Turbo-API.hf.space') {
    this.baseUrl = baseUrl;
  }

  async chat(message, model = 'chat') {
    const endpoints = {
      core: 'chat',
      turbo: 'turbo',
      coder: 'coder'
    };

    const endpoint = endpoints[model] || model;

    const response = await fetch(`${this.baseUrl}/${endpoint}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        messages: [{ role: 'user', content: message }]
      })
    });

    return (await response.json()).content;
  }
}

// Usage
const rox = new RoxAI();

// Use different models for different tasks
const story = await rox.chat('Write a short story', 'core');
const answer = await rox.chat('What is 2+2?', 'turbo');
const code = await rox.chat('Write a sorting function', 'coder');
```

### Model-Specific Optimization

```python
import requests

class RoxClient:
    def __init__(self, base_url="https://Rox-Turbo-API.hf.space"):
        self.base_url = base_url
    
    def ask_core(self, message, creative=True):
        """Use Rox Core with creativity control"""
        return self._request('chat', message, 
                           temperature=1.2 if creative else 0.8)
    
    def ask_turbo(self, message):
        """Use Rox Turbo for fast responses"""
        return self._request('turbo', message, max_tokens=256)
    
    def ask_coder(self, message, extended=False):
        """Use Rox Coder with optional extended context"""
        return self._request('coder', message,
                           max_tokens=8192 if extended else 2048)
    
    def _request(self, endpoint, message, **kwargs):
        response = requests.post(
            f"{self.base_url}/{endpoint}",
            json={
                "messages": [{"role": "user", "content": message}],
                **kwargs
            }
        )
        return response.json()["content"]
```

---

## Cost and Performance Optimization

### Tips for Each Model

**Rox Core:**
- Use for tasks requiring creativity
- Adjust temperature based on needs
- Consider caching common queries

**Rox 2.1 Turbo:**
- Best cost-performance ratio
- Use for high-volume applications
- Lower max_tokens for even faster responses

**Rox 3.5 Coder:**
- Use only for code-related tasks
- Leverage extended context when needed
- Cache code snippets and patterns

---

## API Compatibility

All three models use the same request/response format:

**Request:**
```json
{
  "messages": [
    {"role": "user", "content": "Your message"}
  ],
  "temperature": 1.0,
  "top_p": 0.95,
  "max_tokens": 512
}
```

**Response:**
```json
{
  "content": "Model response"
}
```

This makes it easy to switch between models without changing your code!

---



---

---

Built by Mohammad Faiz


## Rox 4.5 Turbo

**Endpoint**: `POST /turbo45`

### Description
Reasoning model for complex problem-solving with fast responses.

### Best Use Cases
- Complex problem solving
- Advanced reasoning tasks
- Scientific explanations
- Mathematical problems
- Strategic planning
- Analysis and insights

### Parameters
- **Temperature**: 0.2 (highly focused)
- **Top P**: 0.7 (consistent)
- **Max Tokens**: 8,192
- **Special Features**: Enhanced reasoning mode

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/turbo45 \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Explain the theory of relativity"}
    ],
    "max_tokens": 2048
  }'
```

### When to Choose Rox 4.5 Turbo
- Need advanced reasoning
- Complex problem solving
- Scientific or technical explanations
- Fast responses with deep thinking

---

## Rox 5 Ultra

**Endpoint**: `POST /ultra`

### Description
Advanced model for complex reasoning and high-quality output.

### Best Use Cases
- Most complex problem solving
- Research and analysis
- Advanced technical tasks
- Strategic decision making
- Complex code architecture
- Multi-step reasoning

### Parameters
- **Temperature**: 1.0 (balanced)
- **Top P**: 0.95 (high diversity)
- **Max Tokens**: 8,192
- **Special Features**: Superior reasoning mode

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/ultra \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Design a scalable microservices architecture"}
    ],
    "max_tokens": 4096
  }'
```

### When to Choose Rox 5 Ultra
- Most complex tasks
- Need highest quality output
- Multi-step reasoning required
- Research and deep analysis

---

## Rox 6 Dyno

**Endpoint**: `POST /dyno`

### Description
Extended context model for long documents and conversations.

### Best Use Cases
- Long document analysis
- Extended conversations
- Document summarization
- Research paper analysis
- Multi-document synthesis

### Parameters
- **Temperature**: 1.0 (balanced)
- **Top P**: 1.0 (full diversity)
- **Max Tokens**: 16,384 (extended context)
- **Special Features**: Dynamic thinking mode

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/dyno \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Analyze this 20-page document..."}
    ],
    "max_tokens": 8192
  }'
```

### When to Choose Rox 6 Dyno
- Processing long documents
- Need extended context window
- Multi-document analysis
- Long-form content generation

---

## Rox 7 Coder

**Endpoint**: `POST /coder7`

### Description
Advanced coding model for complex programming tasks.

### Best Use Cases
- Complex algorithm design
- Large-scale code generation
- Advanced debugging
- System architecture
- Code refactoring
- Multi-file code analysis

### Parameters
- **Temperature**: 1.0 (balanced)
- **Top P**: 1.0 (full diversity)
- **Max Tokens**: 16,384 (extended context)
- **Special Features**: Advanced thinking mode for code

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/coder7 \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Build a distributed caching system"}
    ],
    "max_tokens": 8192
  }'
```

### When to Choose Rox 7 Coder
- Most complex coding tasks
- Large-scale projects
- System design and architecture
- Advanced algorithms

---

## Rox Vision Max

**Endpoint**: `POST /vision`

### Description
Visual model for image analysis and multimodal tasks.

### Best Use Cases
- Image analysis
- Visual understanding
- Multimodal tasks
- Image description
- Visual Q&A

### Parameters
- **Temperature**: 0.2 (highly focused)
- **Top P**: 0.7 (consistent)
- **Max Tokens**: 512

### Example Request
```bash
curl -X POST https://Rox-Turbo-API.hf.space/vision \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Describe this image"}
    ],
    "max_tokens": 256
  }'
```

### When to Choose Rox Vision Max
- Visual understanding tasks
- Image analysis
- Multimodal applications

---