# CaDaR Quick Start Guide

Get up and running with CaDaR in 5 minutes!

## Prerequisites

- Python 3.8 or higher
- Rust toolchain (install from [rustup.rs](https://rustup.rs/))
- Git

## Installation

### Option 1: Build from Source (Recommended for Development)

```bash
# 1. Clone the repository
git clone https://github.com/Oit-Technologies/CaDaR.git
cd CaDaR

# 2. Run the build script
./build.sh dev

# 3. Verify installation
python3 -c "import cadar; print(cadar.ara2bizi('سلام', darija='Ma'))"
```

### Option 2: Manual Build

```bash
# 1. Install Maturin
pip install maturin

# 2. Build and install
maturin develop

# 3. Test
python3 -c "import cadar; print('CaDaR is installed!')"
```

## First Steps

### 1. Basic Transliteration

```python
import cadar

# Arabic to Latin
result = cadar.ara2bizi("كيفاش داير؟", darija="Ma")
print(result)  # Output: kifash dayer?

# Latin to Arabic
result = cadar.bizi2ara("salam 3likom", darija="Ma")
print(result)  # Output: سلام عليكم
```

### 2. Text Standardization

```python
import cadar

# Standardize Arabic (remove diacritics, normalize)
result = cadar.ara2ara("أنَا مِنْ المَغْرِب", darija="Ma")
print(result)  # Output: انا من المغرب

# Standardize Latin (fix repeated chars)
result = cadar.bizi2bizi("salaaaam", darija="Ma")
print(result)  # Output: salam
```

### 3. Using the CaDaR Class

```python
import cadar

# Create a processor (reusable for multiple operations)
processor = cadar.CaDaR(darija="Ma")

# Convert texts
arabic = processor.bizi2ara("wakha")
latin = processor.ara2bizi("واخا")

print(f"Processor dialect: {processor.get_dialect()}")
```

## Common Use Cases

### Transliterate User Input

```python
import cadar

def process_user_input(text):
    """Auto-detect and transliterate to Latin"""
    # Detect if Arabic or Latin
    has_arabic = any('\u0600' <= c <= '\u06FF' for c in text)

    if has_arabic:
        return cadar.ara2bizi(text, darija="Ma")
    else:
        return cadar.bizi2bizi(text, darija="Ma")  # Just standardize

user_text = input("Enter Darija text: ")
result = process_user_input(user_text)
print(f"Processed: {result}")
```

### Batch Processing

```python
import cadar

processor = cadar.CaDaR(darija="Ma")

# Process multiple texts
texts = ["سلام", "بسلامة", "شكرا", "بزاف"]
results = [processor.ara2bizi(text) for text in texts]

for original, transliterated in zip(texts, results):
    print(f"{original} → {transliterated}")
```

### Build a Chatbot with Darija Support

```python
import cadar

class DarijaBot:
    def __init__(self):
        self.processor = cadar.CaDaR(darija="Ma")

    def understand(self, user_input):
        """Convert user input to standardized Latin"""
        has_arabic = any('\u0600' <= c <= '\u06FF' for c in user_input)
        if has_arabic:
            return self.processor.ara2bizi(user_input)
        return self.processor.bizi2bizi(user_input)

    def respond(self, message, in_arabic=False):
        """Generate response in desired script"""
        if in_arabic:
            return self.processor.bizi2ara(message)
        return message

# Example usage
bot = DarijaBot()
user_says = "كيفاش داير؟"
understood = bot.understand(user_says)
print(f"User: {user_says}")
print(f"Bot understood: {understood}")

response = bot.respond("ana bkhir", in_arabic=True)
print(f"Bot responds: {response}")
```

## Running Examples

```bash
# Run the basic usage examples
python3 examples/basic_usage.py
```

## Testing

```bash
# Run Rust tests
cargo test

# Run all tests with output
cargo test -- --nocapture
```

## Building for Production

```bash
# Build an optimized release
./build.sh release

# Or manually
maturin build --release

# Install the wheel
pip install target/wheels/cadar-*.whl
```

## API Reference

### Main Functions

- `ara2bizi(text, darija="Ma")` - Convert Arabic → Latin
- `bizi2ara(text, darija="Ma")` - Convert Latin → Arabic
- `ara2ara(text, darija="Ma")` - Standardize Arabic
- `bizi2bizi(text, darija="Ma")` - Standardize Latin

### CaDaR Class

```python
processor = cadar.CaDaR(darija="Ma")
processor.ara2bizi(text)
processor.bizi2ara(text)
processor.ara2ara(text)
processor.bizi2bizi(text)
processor.get_dialect()
```

### Convenience Functions

```python
# Auto-detect and transliterate
cadar.transliterate(text, target="latin", darija="Ma")
cadar.transliterate(text, target="arabic", darija="Ma")

# Auto-detect and standardize
cadar.standardize(text, script="auto", darija="Ma")
cadar.standardize(text, script="arabic", darija="Ma")
cadar.standardize(text, script="latin", darija="Ma")
```

## Supported Dialects

Currently:
- `"Ma"` - Moroccan Darija (default)

Future support planned for Algerian, Tunisian, Libyan, and Egyptian dialects.

## Troubleshooting

### Import Error

```python
ImportError: cannot import name 'ara2bizi' from 'cadar'
```

**Solution**: Rebuild the project
```bash
maturin develop --release
```

### Rust Not Found

```
error: Rust is not installed
```

**Solution**: Install Rust
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### Maturin Not Found

```
command not found: maturin
```

**Solution**: Install Maturin
```bash
pip install maturin
```

## Next Steps

1. Read the [README.md](README.md) for detailed documentation
2. Explore [examples/basic_usage.py](examples/basic_usage.py)
3. Check out the [architecture documentation](README.md#architecture)
4. Contribute to the project!

## Getting Help

- GitHub Issues: [https://github.com/Oit-Technologies/CaDaR/issues](https://github.com/Oit-Technologies/CaDaR/issues)
- Documentation: [README.md](README.md)

Happy transliterating! 🎉
