majmu 0.1.1
A Python library for chat completions using multiple LLMs with just single API
License: MIT
Requires Python: >=3.7
Keywords: chat, completion, ai, llm, api, litellm

# Majmu 🚀

A Python library for chat completions using using multiple LLMs with just single API. Majmu provides a simple and elegant interface to interact with the LiteLLM chat completions endpoint.

## Features

- 🎯 Simple and intuitive API
- 🔐 Built-in authentication handling
- 🔄 Automatic retry logic with exponential backoff
- 📝 Type hints for better development experience
- 🛡️ Comprehensive error handling
- 🧪 Well-tested and reliable
- 📖 Full documentation

## Installation

Install Majmu using pip:

```bash
pip install majmu
```

For development features:

```bash
pip install majmu[dev]
```

## Quick Start

```python
from majmu import MajmuClient, ChatMessage

# Initialize the client
client = MajmuClient(api_key="your-api-key-here")

# Create a simple chat completion
messages = [
    ChatMessage(role="user", content="Hello, how are you?")
]

completion = client.chat_completion(
    model="mistral-small-latest",
    messages=messages,
    max_tokens=100
)

print(completion.content)  # Access the response content easily
```

## Advanced Usage

### Using Dictionary Format

```python
# You can also use dictionaries for messages
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain quantum computing in simple terms."}
]

completion = client.chat_completion(
    model="mistral-small-latest",
    messages=messages,
    max_tokens=150
)
```

### Context Manager

```python
# Use as a context manager for automatic resource cleanup
with MajmuClient(api_key="your-api-key") as client:
    completion = client.chat_completion(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(completion.content)
```

### Custom Configuration

```python
client = MajmuClient(
    api_key="your-api-key",
    base_url="https://custom-endpoint.com/v1",  # Custom endpoint
    timeout=60,  # Custom timeout
    max_retries=5  # Custom retry count
)
```

### Accessing Detailed Response

```python
completion = client.chat_completion(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Hello!"}]
)

# Access various parts of the response
print(f"Model used: {completion.model}")
print(f"Completion ID: {completion.id}")
print(f"Total tokens: {completion.usage.total_tokens}")
print(f"Finish reason: {completion.choices[0].finish_reason}")

# Convert to dictionary if needed
response_dict = completion.to_dict()
```

## API Reference

### MajmuClient

The main client class for interacting with the API.

#### Parameters

- `api_key` (str): Your API key for authentication
- `base_url` (str, optional): Custom base URL (default: "https://litellm.maatier.com/v1")
- `timeout` (int, optional): Request timeout in seconds (default: 30)
- `max_retries` (int, optional): Maximum retry attempts (default: 3)
- `session` (requests.Session, optional): Custom requests session

#### Methods

##### `chat_completion(model, messages, max_tokens=100, **kwargs)`

Create a chat completion.

**Parameters:**
- `model` (str): The model to use for completion
- `messages` (List[ChatMessage | dict]): List of conversation messages
- `max_tokens` (int, optional): Maximum tokens to generate (default: 100)
- `**kwargs`: Additional parameters for the API

**Returns:**
- `ChatCompletion`: The completion response

### Models

#### ChatMessage

Represents a chat message.

```python
message = ChatMessage(role="user", content="Hello!")
```

#### ChatCompletion

Represents the API response with methods and properties:

- `content`: Quick access to the first choice's content
- `to_dict()`: Convert to dictionary
- `choices`: List of completion choices
- `usage`: Token usage information

## Error Handling

Majmu provides specific exception types for different error scenarios:

```python
from majmu import MajmuClient
from majmu.exceptions import AuthenticationError, RateLimitError, APIError

try:
    client = MajmuClient(api_key="invalid-key")
    completion = client.chat_completion(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit exceeded, please try again later")
except APIError as e:
    print(f"API error: {e}")
```

## Supported Models

The library supports any model available through the LiteLLM endpoint. Popular options include:

- `mistral-small-latest`
- `mistral-medium-latest`
- `mistral-large-latest`
- And many others...

Check your API provider's documentation for the full list of available models.

## Development

### Setting Up Development Environment

```bash
# Clone the repository
git clone https://github.com/amarzook/majmu-library.git
cd majmu

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

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

# Install pre-commit hooks
pre-commit install
```

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=majmu

# Run specific test file
pytest tests/test_client.py
```

### Code Formatting

```bash
# Format code with black
black majmu/ tests/

# Check with flake8
flake8 majmu/ tests/

# Type checking with mypy
mypy majmu/
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for your changes
5. Ensure all tests pass
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

### v0.1.0 (2025-08-16

- Initial release
- Basic chat completion functionality
- Authentication support
- Error handling
- Type hints and documentation

## Support

If you encounter any issues or have questions:

1. Check the [documentation](https://github.com/amarzook/majmu-library/blob/master/README.md)
2. Search [existing issues](https://github.com/amarzook/majmu-library/issues)
3. Create a [new issue](https://github.com/amarzook/majmu-library/issues/new)

## Acknowledgments

- Thanks to the LiteLLM team for providing the API endpoint
- Inspired by the OpenAI Python library design
- Built with ❤️ for the Python community