AGENTS.md

# AGENTS.md — LibreTranslate Kabyle Space

## Overview
This Hugging Face Space hosts a LibreTranslate instance dedicated to **Kabyle (kab)** language translation.
It provides a self-hosted translation API with multiple experimental Kabyle language models.

## Space Details
- **URL**: https://huggingface.co/spaces/boffire/libreTranslate_kabyle
- **Runtime**: Docker Space (LibreTranslate)
- **Focus**: Kabyle language translation models only

## API Endpoints

The LibreTranslate API is exposed at the Space's runtime URL:
```
https://boffire-libretranslate-kabyle.hf.space
```

### Key Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/translate` | POST | Translate text between languages |
| `/detect` | POST | Detect the language of given text |
| `/languages` | GET | List supported languages |
| `/suggest` | POST | Submit a translation suggestion |

### Authentication
- **Public access**: The API is publicly accessible when the Space is running
- **HF Token**: For private Spaces or higher rate limits, pass `Authorization: Bearer $HF_TOKEN`

### Example: Translate Text
```bash
curl -X POST https://boffire-libretranslate-kabyle.hf.space/translate \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Azul, amek i tettiliḍ?",
    "source": "kab",
    "target": "en"
  }'
```

### Example: Detect Language
```bash
curl -X POST https://boffire-libretranslate-kabyle.hf.space/detect \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Azul, amek i tettiliḍ?"
  }'
```

### Example: List Languages
```bash
curl https://boffire-libretranslate-kabyle.hf.space/languages
```

## Kabyle Translation Models

| Code | Name | Directionality |
|------|------|----------------|
| `kab` | Kabyle | **Bidirectional** with English: `en↔kab` |
| `kab_os` | Kabyle (OS) | **One-way only**: `en→kab_os` |
| `kab_comp` | Kabyle (Tasenselkimt) | **One-way only**: `en→kab_comp` |
| `kab_comp2` | Kabyle (TSSLKMT51000) | **One-way only**: `en→kab_comp2` |
| `kab_num` | Kabyle (num40000) | **One-way only**: `en→kab_num` |
| `kab_kab` | Kabyle 48500 (19082025) | **One-way only**: `en→kab_kab` |

### Directionality Rules

- **Standard Kabyle (`kab`)**: Full bidirectional support with English.
  - `en→kab` ✓ (English to Kabyle)
  - `kab→en` ✓ (Kabyle to English)

- **Alternative Kabyle Models**: English can translate **into** these models, but they **cannot** translate back to English.
  - `en→kab_os` ✓ | `kab_os→en` ✗
  - `en→kab_comp` ✓ | `kab_comp→en` ✗
  - `en→kab_comp2` ✓ | `kab_comp2→en` ✗
  - `en→kab_num` ✓ | `kab_num→en` ✗
  - `en→kab_kab` ✓ | `kab_kab→en` ✗

## Important Notes
- The Space may go to sleep after inactivity (cold start ~30s)
- Suggestions are stored in the dataset `boffire/libretranslate-en-kab-suggestions`
- Language code `kab` refers to the standard bidirectional Kabyle model
- All alternative models (`kab_os`, `kab_comp`, `kab_comp2`, `kab_num`, `kab_kab`) are **English-to-Kabyle only**