API_DOCUMENTATION.md

# 📡 وثائق API - Whisper Text Processor

دليل شامل لاستخدام API معالج النصوص المتكامل

## 🌐 معلومات عامة

### Base URL
```
https://YOUR_USERNAME-whisper-text-processor.hf.space
```

### Content-Type
```
application/json
```

### Authentication
لا يتطلب API مصادقة حالياً (قد يتغير في المستقبل)

## 📋 نقاط النهاية (Endpoints)

### 1. فحص حالة الخادم

#### `GET /health`

فحص حالة الخادم والتأكد من أن جميع المكونات تعمل بشكل صحيح.

**المعاملات:** لا توجد

**الاستجابة:**
```json
{
  "status": "healthy",
  "message": "خادم معالج النصوص يعمل بشكل طبيعي",
  "processor_loaded": true
}
```

**مثال:**
```bash
curl -X GET "https://your-space.hf.space/health"
```

---

### 2. تصحيح النصوص

#### `POST /correct-text`

تصحيح النص المدخل باستخدام قاموس مرجعي مبني من النصوص المرجعية.

**المعاملات:**
```json
{
  "text": "string",              // النص المراد تصحيحه (مطلوب)
  "reference_texts": ["string"], // قائمة النصوص المرجعية (مطلوب)
  "max_distance": 3,           // أقصى مسافة للتصحيح (اختياري)
  "threshold_freq": 1          // الحد الأدنى لتكرار الكلمة (اختياري)
}
```

**الاستجابة:**
```json
{
  "success": true,
  "message": "تم تصحيح النص بنجاح",
  "data": {
    "original_text": "يحتاز غشاء الطبل",
    "corrected_text": "يهتز غشاء الطبل",
    "corrections": [
      {
        "original": "يحتاز",
        "corrected": "يهتز",
        "frequency": 4,
        "distance": 2
      }
    ],
    "corrections_count": 1
  }
}
```

**مثال:**
```bash
curl -X POST "https://your-space.hf.space/correct-text" \
     -H "Content-Type: application/json" \
     -d '{
       "text": "يحتاز غشاء الطبل تنتقل عظيمات السماء",
       "reference_texts": [
         "يهتز غشاء الطبل تنتقل عظيمات السمع الاهتزازات",
         "يهتز غشاء النافذة البيضية يهتز اللمف الخارجي"
       ],
       "max_distance": 3,
       "threshold_freq": 1
     }'
```

---

### 3. مقارنة النصوص

#### `POST /compare-texts`

مقارنة نصين وحساب معدلات الخطأ مع إظهار الاختلافات بصرياً.

**المعاملات:**
```json
{
  "reference_text": "string",    // النص المرجعي (مطلوب)
  "transcribed_text": "string"   // النص المستخرج (مطلوب)
}
```

**الاستجابة:**
```json
{
  "success": true,
  "message": "تم مقارنة النصوص بنجاح",
  "data": {
    "wer": 0.3,
    "cer": 0.076,
    "wer_percentage": "30.00%",
    "cer_percentage": "7.69%",
    "html_diff": "<span>HTML مع الاختلافات المظللة</span>",
    "reference_words": 10,
    "transcribed_words": 10,
    "word_differences": 0
  }
}
```

**مثال:**
```bash
curl -X POST "https://your-space.hf.space/compare-texts" \
     -H "Content-Type: application/json" \
     -d '{
       "reference_text": "يهتز غشاء الطبل تنتقل عظيمات السمع",
       "transcribed_text": "يحتاز غشاء الطبل تنتقل عظيمات السماء"
     }'
```

---

### 4. معالجة الملفات الصوتية

#### `POST /process-audio`

معالجة شاملة للملف الصوتي تتضمن تحويل الصوت إلى نص، التصحيح، والمقارنة.

**المعاملات (multipart/form-data):**
- `audio_file`: ملف صوتي (مطلوب)
- `reference_text`: النص المرجعي (مطلوب)
- `reference_texts`: نصوص مرجعية إضافية كـ JSON string (اختياري)
- `max_distance`: أقصى مسافة للتصحيح (اختياري، افتراضي: 3)
- `threshold_freq`: الحد الأدنى لتكرار الكلمة (اختياري، افتراضي: 1)

**الاستجابة:**
```json
{
  "success": true,
  "message": "تم معالجة الملف الصوتي بنجاح",
  "data": {
    "audio_path": "/path/to/audio.wav",
    "reference_text": "النص المرجعي",
    "original_transcription": "النص المستخرج الأصلي",
    "corrected_transcription": "النص المصحح",
    "corrections": [...],
    "original_metrics": {
      "wer": 0.15,
      "cer": 0.08,
      "wer_percentage": "15.00%",
      "cer_percentage": "8.00%"
    },
    "corrected_metrics": {
      "wer": 0.0,
      "cer": 0.0,
      "wer_percentage": "0.00%",
      "cer_percentage": "0.00%"
    },
    "improvement": {
      "wer_improvement": 0.15,
      "cer_improvement": 0.08
    },
    "timestamps": [...]
  }
}
```

**مثال:**
```bash
curl -X POST "https://your-space.hf.space/process-audio" \
     -F "audio_file=@audio.wav" \
     -F "reference_text=يهتز غشاء الطبل تنتقل عظيمات السمع" \
     -F "reference_texts=[\"نص إضافي 1\", \"نص إضافي 2\"]" \
     -F "max_distance=3" \
     -F "threshold_freq=1"
```

---

### 5. إنشاء تقرير HTML

#### `POST /generate-report`

إنشاء تقرير HTML شامل يحتوي على جميع نتائج المعالجة مع تصميم تفاعلي.

**المعاملات (multipart/form-data):**
- `audio_file`: ملف صوتي (مطلوب)
- `reference_text`: النص المرجعي (مطلوب)
- `reference_texts`: نصوص مرجعية إضافية كـ JSON string (اختياري)

**الاستجابة:**
```html
<!DOCTYPE html>
<html dir="rtl" lang="ar">
<head>
    <meta charset="UTF-8">
    <title>تقرير معالجة النصوص</title>
    <!-- CSS styles -->
</head>
<body>
    <!-- تقرير HTML كامل مع النتائج والإحصائيات -->
</body>
</html>
```

**مثال:**
```bash
curl -X POST "https://your-space.hf.space/generate-report" \
     -F "audio_file=@audio.wav" \
     -F "reference_text=يهتز غشاء الطبل" \
     -o report.html
```

---

## 🔧 أكواد الاستجابة

### نجح الطلب
- `200 OK`: تم تنفيذ الطلب بنجاح

### أخطاء العميل
- `400 Bad Request`: معاملات غير صحيحة أو مفقودة
- `422 Unprocessable Entity`: بيانات غير صالحة

### أخطاء الخادم
- `500 Internal Server Error`: خطأ في الخادم أو المعالج

## 📝 أمثلة متقدمة

### 1. معالجة متعددة اللغات
```python
import requests

# تصحيح نص عربي
response = requests.post(
    "https://your-space.hf.space/correct-text",
    json={
        "text": "السلام عليكم ورحمة الله وبركاته",
        "reference_texts": ["السلام عليكم ورحمة الله وبركاته"]
    }
)
```

### 2. معالجة دفعية
```python
import asyncio
import aiohttp

async def process_multiple_texts(texts, reference_texts):
    async with aiohttp.ClientSession() as session:
        tasks = []
        for text in texts:
            task = session.post(
                "https://your-space.hf.space/correct-text",
                json={
                    "text": text,
                    "reference_texts": reference_texts
                }
            )
            tasks.append(task)
        
        responses = await asyncio.gather(*tasks)
        return [await r.json() for r in responses]
```

### 3. تحليل الأداء
```python
import time
import requests

def benchmark_api():
    start_time = time.time()
    
    response = requests.post(
        "https://your-space.hf.space/compare-texts",
        json={
            "reference_text": "نص طويل للاختبار...",
            "transcribed_text": "نص طويل مع أخطاء..."
        }
    )
    
    end_time = time.time()
    processing_time = end_time - start_time
    
    print(f"وقت المعالجة: {processing_time:.2f} ثانية")
    return response.json()
```

## 🛡️ أفضل الممارسات

### 1. إدارة الأخطاء
```python
import requests
from requests.exceptions import RequestException

def safe_api_call(url, data):
    try:
        response = requests.post(url, json=data, timeout=30)
        response.raise_for_status()
        return response.json()
    except RequestException as e:
        print(f"خطأ في API: {e}")
        return None
```

### 2. تحسين الأداء
```python
# استخدام session للطلبات المتعددة
session = requests.Session()
session.headers.update({"Content-Type": "application/json"})

# إعادة استخدام الاتصال
for text in texts:
    response = session.post(url, json={"text": text, ...})
```

### 3. التعامل مع الملفات الكبيرة
```python
# رفع ملفات صوتية كبيرة
with open("large_audio.wav", "rb") as f:
    files = {"audio_file": f}
    data = {"reference_text": "النص المرجعي"}
    
    response = requests.post(
        "https://your-space.hf.space/process-audio",
        files=files,
        data=data,
        timeout=300  # مهلة أطول للملفات الكبيرة
    )
```

## 🔍 استكشاف الأخطاء

### أخطاء شائعة وحلولها

#### 1. خطأ 400 - Bad Request
```json
{
  "detail": "يجب أن يكون الملف من نوع صوتي"
}
```
**الحل:** تأكد من أن الملف المرفوع هو ملف صوتي صالح (.wav, .mp3, .m4a, إلخ)

#### 2. خطأ 500 - Internal Server Error
```json
{
  "detail": "معالج النصوص غير متاح"
}
```
**الحل:** الخادم قيد التحميل أو إعادة التشغيل، حاول مرة أخرى بعد دقائق

#### 3. خطأ Timeout
**الحل:** زيادة مهلة الطلب أو تقليل حجم الملف الصوتي

## 📊 حدود الاستخدام

### الحدود الحالية
- **حجم الملف الصوتي**: حتى 25 MB
- **طول النص**: حتى 10,000 حرف
- **عدد النصوص المرجعية**: حتى 50 نص
- **معدل الطلبات**: 100 طلب/دقيقة

### نصائح للتحسين
- استخدم ملفات صوتية مضغوطة
- قسم النصوص الطويلة إلى أجزاء
- استخدم التخزين المؤقت للنتائج المتكررة

---

**ملاحظة:** هذه الوثائق قابلة للتحديث. راجع الإصدار الأحدث على GitHub.