# GemmaTranslate Testing Guide

Complete guide for testing the GemmaTranslate translation service on Modal.com.

---

## Prerequisites

### 1. Install Modal CLI

```bash
pip install modal
```

### 2. Configure Modal Token

You need a Modal account and token. Get your token from: https://modal.com/settings

```bash
modal token set --token-id YOUR_TOKEN_ID --token-secret YOUR_TOKEN_SECRET
```

### 3. Verify Installation

```bash
modal --help
```

---

## Quick Start - Run Translation Test

The easiest way to test the translation service:

```bash
cd /home/user/Projects/Press.zone/wordpress/wp-content/plugins/translate-press-zone/backend-app/modal-service

# Make test script executable
chmod +x test_translation.py

# Run the test
python test_translation.py
```

This will:
1. ✅ Load the Modal app
2. ✅ Check model cache status
3. ✅ Download gemmatranslate-small model (first run only, ~2-4GB)
4. ✅ Translate a 20-word test sentence
5. ✅ Display results with metrics and cost estimate
6. ✅ Validate translation quality

### Expected Output (First Run):

```
======================================================================
  GemmaTranslate Service Test
======================================================================

📋 Test Configuration:
   Text: The quick brown fox jumps over the lazy dog...
   Word count: 20
   Character count: 132
   Source language: en
   Target language: es
   Tone: neutral
   Timestamp: 2026-01-18 12:34:56

[Step 1] Loading Modal app...
✅ Modal app loaded

[Step 2] Checking model cache status...
✅ Cache check complete
   Cached models: 0
   Total cache size: 0.0 MB

   ⚠️  No models cached - first run will download model

[Step 3] Starting translation...
   This may take longer on first run (downloading model)
✅ Translation completed in 45.23s

======================================================================
  Translation Results
======================================================================

📝 Original Text:
   The quick brown fox jumps over the lazy dog...

🌐 Translated Text:
   El zorro marrón rápido salta sobre el perro perezoso...

📊 Metrics:
   Tokens used: 156
   Processing time (server): 42500ms
   Total time (with network): 45230ms
   Model: gemmatranslate
   Source language: en
   Target language: es

💰 Estimated Cost:
   Tokens: 156
   Rate: $0.001 per 1K tokens
   Estimated cost: $0.000156

[Step 4] Validating translation...
✅ Translation validation passed

======================================================================
  Test Completed Successfully! ✅
======================================================================
```

### Expected Output (Subsequent Runs):

After first run, model is cached. Translation should be much faster (5-10s):

```
[Step 2] Checking model cache status...
✅ Cache check complete
   Cached models: 1
   Total cache size: 2341.5 MB

   📦 Cached models:
      - gemmatranslate/gemmatranslate-small (2341.5 MB)

[Step 3] Starting translation...
✅ Translation completed in 7.8s
```

---

## Advanced Testing

### Test with Custom Text

Edit `test_translation.py` and modify the `TEST_TEXT` variable:

```python
TEST_TEXT = """
Your custom text here. Can be up to 5000 characters.
Test with HTML tags <strong>like this</strong>.
"""
```

### Test Different Languages

```python
SOURCE_LANG = "en"  # Change to any supported language
TARGET_LANG = "fr"  # French, German (de), Italian (it), etc.
```

### Test Different Tones

```python
TONE = "formal"  # Options: neutral, formal, casual
```

---

## Manual Testing with Modal CLI

### 1. Run Translation Function Directly

```bash
modal run gemmatranslate_service.py
```

This runs the `test_translation()` local entrypoint.

### 2. Check Model Cache

```bash
modal run gemmatranslate_service.py::check_model_cache
```

### 3. Deploy as Web Service

Deploy the service to get a persistent web endpoint:

```bash
modal deploy gemmatranslate_service.py
```

You'll get a URL like: `https://your-username--translate-gemma-translate.modal.run`

### 4. Test Web Endpoint with cURL

```bash
curl -X POST https://your-app-url/translate \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello world, this is a test.",
    "source_lang": "en",
    "target_lang": "es",
    "tone": "neutral"
  }'
```

### 5. Health Check

```bash
curl https://your-app-url/health
```

---

## Troubleshooting

### Issue: "Modal token not configured"

**Solution:**
```bash
modal token set --token-id XXX --token-secret YYY
```

Get tokens from: https://modal.com/settings

### Issue: "Model download timeout"

**Solution:** First download can take 5-10 minutes. The model is ~2.3GB. Subsequent runs load from cache in <5s.

### Issue: "GPU quota exceeded"

**Solution:** Modal free tier has GPU limits. Upgrade to paid plan or wait for quota reset.

### Issue: "CUDA out of memory"

**Solution:** Increase memory allocation in function decorator:

```python
@app.function(
    memory=20480,  # Increase to 20GB
    ...
)
```

### Issue: "Translation is empty"

**Solution:** Check logs for errors. Verify language codes are supported.

### Issue: "Volume not persisting"

**Solution:** Ensure `model_volume.commit()` is called after saving models. Check volume in Modal dashboard.

---

## Integration with Backend API

After successful testing, update the backend API configuration:

### 1. Deploy Modal Service

```bash
cd /home/user/Projects/Press.zone/wordpress/wp-content/plugins/translate-press-zone/backend-app/modal-service
modal deploy gemmatranslate_service.py
```

Copy the deployment URL (e.g., `https://username--translate-gemma-translate.modal.run`)

### 2. Update API Environment Variables

Edit `/home/user/Projects/Press.zone/wordpress/wp-content/plugins/translate-press-zone/backend-app/api/.env`:

```env
MODAL_API_URL=https://username--translate-gemma-translate.modal.run
MODAL_API_KEY=your-modal-token-here
```

### 3. Update Database Settings

In WordPress admin or via database:

```sql
UPDATE settings
SET value = 'https://username--translate-gemma-translate.modal.run'
WHERE key = 'modal_api_url';
```

### 4. Test End-to-End

From WordPress admin panel, submit a translation job and verify it calls the Modal service.

---

## Performance Benchmarks

Based on test runs:

| Metric | First Run (Download) | Cached Run |
|--------|---------------------|------------|
| Model download | 3-5 minutes | 0s (cached) |
| Model loading | 2-3 seconds | 1-2 seconds |
| Translation (20 words) | ~40-50s total | ~5-10s total |
| Tokens used | ~150-200 | ~150-200 |
| Memory usage | ~8GB | ~8GB |
| GPU | T4 (sufficient) | T4 |

### Cost Estimates

- Modal GPU T4: ~$0.00060 per minute
- 20-word translation: ~$0.005 per request (after cache)
- First run (with download): ~$0.18 (one-time only)

---

## Monitoring

### View Logs

```bash
modal app logs translate-gemma
```

### Check Volume Usage

```bash
modal volume ls
```

### View Function Metrics

Go to Modal dashboard: https://modal.com/apps

---

## Next Steps

1. ✅ Run `python test_translation.py` to verify setup
2. ✅ Test with different languages and text lengths
3. ✅ Deploy service: `modal deploy gemmatranslate_service.py`
4. ✅ Update backend API `.env` with deployment URL
5. ✅ Test end-to-end from WordPress admin panel
6. ✅ Monitor performance and costs in Modal dashboard

---

## Support

- Modal Documentation: https://modal.com/docs
- GemmaTranslate Model: https://huggingface.co/gemmatranslate
- Issues: Open issue in project repository