# MiniMax AI - Claude-Style Coding Assistant

[![npm version](https://img.shields.io/npm/v/@minimax-ai/minimax.svg)](https://www.npmjs.com/package/@minimax-ai/minimax)
[![License](https://img.shields.io/npm/l/@minimax-ai/minimax.svg)](https://github.com/minimax-ai/minimax-cli/blob/main/LICENSE)
[![Downloads](https://img.shields.io/npm/dm/@minimax-ai/minimax.svg)](https://www.npmjs.com/package/@minimax-ai/minimax)

A powerful Claude-style AI coding assistant powered by MiniMax AI models. Get intelligent code analysis, generation, and interactive programming assistance right from your terminal.

## 🚀 Quick Start

```bash
# Install globally via npm
npm install -g @minimax-ai/minimax

# Set your Hugging Face token
export HF_TOKEN=your_token_here

# Start using MiniMax AI
minimax --help
minimax analyze review myfile.py
minimax generate function "calculate fibonacci"
minimax chat start
```

## ✨ Features

- 🔍 **Code Analysis**: Review, explain, debug, and optimize your code
- 🛠️ **Code Generation**: Generate functions, classes, tests, and entire projects
- ✏️ **Smart Editing**: Modify and refactor code with AI assistance
- 💬 **Interactive Mode**: Chat-based coding assistance with context awareness
- 📁 **Project Intelligence**: Understand and work with entire codebases
- 🌍 **Cross-Platform**: Works on Windows, macOS, and Linux
- ⚡ **Easy Installation**: One command global installation via npm

## 📋 Prerequisites

- **Node.js 14+** (for npm installation)
- **Python 3.8+** (automatically managed)
- **Hugging Face account** with API access

## 📦 Installation

```bash
# Install globally via npm (recommended)
npm install -g @minimax-ai/minimax

# Alternative: Install locally in a project
npm install @minimax-ai/minimax
```

The installation automatically:
- ✅ Detects and validates Python 3.8+
- ✅ Creates an isolated Python environment
- ✅ Installs required Python dependencies
- ✅ Sets up the global `minimax` command

### Option 3: Production Installation

Install from PyPI (when published):

```bash
pip install minimax-client
```

## 🔑 Setup

### 1. Get Your Hugging Face Token

1. Visit [https://huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
2. Create a new token with read access
3. Set it as an environment variable:

```bash
# Linux/macOS
export HF_TOKEN='your_token_here'

# Windows (Command Prompt)
set HF_TOKEN=your_token_here

# Windows (PowerShell)
$env:HF_TOKEN='your_token_here'
```

### 2. Verify Installation

```bash
minimax --version
minimax --help
```

## Usage

### Command Line Interface

After installation, use the `minimax-client` command:

```bash
# Basic usage with defaults
minimax-client

# Custom message
minimax-client --message "Explain quantum computing in simple terms"

# Different model
minimax-client --model "MiniMaxAI/MiniMax-M1-40k" --message "Hello, world!"

# Non-streaming mode
minimax-client --no-streaming --message "What is AI?"

# Custom provider
minimax-client --provider "hf-inference-endpoints" --message "Tell me a joke"

# Show version
minimax-client --version
```

### Legacy Script

The original script is still available for backwards compatibility:

```bash
python minimax_client_legacy.py
```

## Configuration

### CLI Arguments

| Argument | Short | Default | Description |
|----------|-------|---------|-------------|
| `--model` | `-m` | `MiniMaxAI/MiniMax-M1-80k` | Model name to use |
| `--message` | `-msg` | `What is the capital of France?` | User message to send |
| `--provider` | `-p` | `auto` | Inference provider to use |
| `--no-streaming` | | `False` | Disable streaming (use regular completion) |
| `--verbose` | `-v` | `False` | Enable verbose logging |
| `--help` | `-h` | | Show help message |

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `HF_TOKEN` | Yes | Hugging Face API token |
| `MINIMAX_MODEL` | No | Default model name (overridden by CLI) |
| `MINIMAX_PROVIDER` | No | Default provider (overridden by CLI) |

### Configuration Precedence

1. **CLI Arguments** (highest priority)
2. **Environment Variables**
3. **Default Values** (lowest priority)

### Examples

```bash
# Use environment variable for model
export MINIMAX_MODEL="MiniMaxAI/MiniMax-M1-40k"
minimax-client --message "Hello!"

# Override environment with CLI
export MINIMAX_MODEL="MiniMaxAI/MiniMax-M1-40k"
minimax-client --model "MiniMaxAI/MiniMax-M1-80k" --message "Hello!"

# Complex configuration
minimax-client \
  --model "MiniMaxAI/MiniMax-M1-80k" \
  --message "Explain the theory of relativity" \
  --provider "hf-inference-endpoints" \
  --verbose
```

## Expected Output

The CLI tool will:

1. ✓ Validate environment and configuration
2. ✓ Initialize the InferenceClient with specified provider
3. 🚀 Send request to the configured model
4. 🔄 Display streaming response in real-time (if enabled)
5. ✅ Show completion status with proper logging

Example output:
```
INFO - Starting MiniMax client with model: MiniMaxAI/MiniMax-M1-80k
INFO - Environment validation successful
INFO - InferenceClient initialized successfully
INFO - Sending message: What is the capital of France?
INFO - Streaming response:
--------------------------------------------------
The capital of France is Paris. It is the largest city in France and serves as the country's political, economic, and cultural center...
--------------------------------------------------
INFO - Chat completion successful
INFO - Client operation completed successfully
```

## Package Structure

```
src/minimax_client/
├── __init__.py          # Package initialization and version info
├── main.py              # CLI entry point and orchestration
├── config.py            # Configuration management and CLI parsing
├── environment.py       # Environment variable validation
├── client.py            # InferenceClient initialization and management
└── chat.py              # Chat completion logic and streaming
```

### Key Components

1. **Configuration Management** (`config.py`): Handles CLI arguments, environment variables, and default values
2. **Environment Validation** (`environment.py`): Validates HF_TOKEN and optional .env file loading
3. **Client Management** (`client.py`): InferenceClient initialization with specific error handling
4. **Chat Processing** (`chat.py`): Streaming and non-streaming chat completions with enhanced error recovery
5. **Main Orchestrator** (`main.py`): Coordinates all components and provides CLI interface

## Error Handling

### Exit Codes

| Code | Category | Description |
|------|----------|-------------|
| 0 | Success | Operation completed successfully |
| 1 | General Error | Unspecified error occurred |
| 2 | Configuration Error | Invalid configuration or missing environment variables |
| 3 | Network Error | Network connectivity or timeout issues |
| 4 | Authentication Error | Invalid or missing API token |
| 5 | Model Error | Model-related issues (not found, gated, unavailable) |

### Specific Exception Handling

| Exception Type | Exit Code | Common Causes | Solutions |
|----------------|-----------|---------------|-----------|
| `HfHubHTTPError` | 3, 4, 5 | HTTP errors (401, 404, 429, 500) | Check token, model name, rate limits |
| `RepositoryNotFoundError` | 5 | Model doesn't exist | Verify model name spelling |
| `GatedRepoError` | 5 | Model requires access approval | Request access on Hugging Face |
| `InferenceTimeoutError` | 5 | Model temporarily unavailable | Retry later or use different model |
| `BadRequestError` | 5 | Invalid parameters | Check message format and model requirements |
| `ValueError` | 4 | Authentication issues | Verify HF_TOKEN validity |
| `requests.exceptions.*` | 3 | Network problems | Check internet connection |

## Development

### Setting Up Development Environment

```bash
# Clone the repository
git clone <repository-url>
cd MiniMax

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks (optional)
pre-commit install
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src/minimax_client

# Run specific test file
pytest tests/test_config.py

# Run with verbose output
pytest -v
```

### Project Structure

```
MiniMax/
├── src/minimax_client/      # Main package source code
├── tests/                   # Unit tests
├── pyproject.toml          # Modern Python packaging configuration
├── requirements.txt        # Runtime dependencies
├── README.md              # This documentation
├── minimax_client_legacy.py # Original script (backwards compatibility)
└── .env.example           # Example environment file
```

### Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes with proper tests
4. Run the test suite: `pytest`
5. Submit a pull request

### Code Style

- Follow PEP 8 guidelines
- Use type hints for all functions
- Add docstrings for public APIs
- Write unit tests for new functionality
- Use proper logging instead of print statements

## API Documentation

### Using as a Python Package

```python
from minimax_client.config import Configuration
from minimax_client.client import initialize_client
from minimax_client.chat import create_chat_completion

# Create configuration
config = Configuration(
    model_name="MiniMaxAI/MiniMax-M1-80k",
    user_message="Hello, world!",
    provider="auto",
    streaming=True
)

# Initialize client
client = initialize_client(config)

# Create chat completion
create_chat_completion(client, config)
```

### Configuration Class

```python
class Configuration:
    """Configuration management for MiniMax client."""
    
    def __init__(self, model_name: str = None, user_message: str = None, 
                 provider: str = None, streaming: bool = None):
        """Initialize configuration with optional overrides."""
        
    @classmethod
    def from_args(cls, args: list = None) -> 'Configuration':
        """Create configuration from command line arguments."""
        
    def validate(self) -> None:
        """Validate configuration values."""
```

## Troubleshooting

### Environment Issues

| Problem | Solution |
|---------|----------|
| `HF_TOKEN not found` | Set environment variable or create .env file |
| `Permission denied` | Check file permissions and virtual environment |
| `Module not found` | Install package with `pip install -e .` |

### Authentication Issues

| Problem | Solution |
|---------|----------|
| `401 Unauthorized` | Verify HF_TOKEN is valid and not expired |
| `403 Forbidden` | Request access to gated models |
| `Invalid token format` | Check token doesn't have extra spaces/characters |

### Model Issues

| Problem | Solution |
|---------|----------|
| `Model not found (404)` | Verify model name spelling and availability |
| `Model temporarily unavailable (503)` | Try again later or use different model |
| `Rate limit exceeded (429)` | Wait before retrying or upgrade API plan |
| `Model loading timeout` | Use smaller model or retry later |

### Network Issues

| Problem | Solution |
|---------|----------|
| `Connection timeout` | Check internet connection and firewall |
| `DNS resolution failed` | Verify DNS settings |
| `SSL certificate error` | Update certificates or check system time |

### Configuration Issues

| Problem | Solution |
|---------|----------|
| `Invalid provider` | Use 'auto', 'hf-inference-endpoints', or other valid providers |
| `Message too long` | Reduce message length or use model with larger context |
| `Invalid streaming parameter` | Use boolean values (True/False) |

### Getting Help

- **GitHub Issues**: Report bugs and request features
- **Documentation**: Check this README and inline code documentation
- **Hugging Face Forums**: Community support for model-specific issues
- **API Documentation**: Hugging Face Inference API docs

## License

This client library is provided under the MIT License. See LICENSE file for details.