API_DOCUMENTATION.md

🔌 Bilingual Text Summarization REST API

Developer & Integration Guide for Frontend / Backend Engineers

API Version: 1.0.0
Base URL: http://localhost:8000 (or http://127.0.0.1:8000)
Swagger Interactive Docs: http://localhost:8000/docs
ReDoc Clean Reference: http://localhost:8000/redoc
Postman Collection File: api/postman_collection.json
Postman Environment File: api/postman_environment.json

---

1. Quick Start & Server Launch

Step 1: Install Dependencies

pip install -r requirements.txt
# Ensure fastapi, uvicorn, python-multipart are installed
pip install fastapi uvicorn python-multipart

Step 2: Start the FastAPI Server

python run_api.py

Or directly using Uvicorn:

uvicorn api.server:app --host 0.0.0.0 --port 8000 --reload

---

2. Postman Quick Import

1. Open Postman.
2. Click Import in the top-left corner.
3. Select or drag-and-drop:
   • api/postman_collection.json
   • api/postman_environment.json
4. Select the environment "Bilingual Summarization API (Local Environment)" in the top-right environment selector.
5. All requests are ready to run with pre-configured headers, bodies, and automated test assertions!

---

3. Endpoints Reference

3.1 System & Health

GET /api/v1/health

Checks server health, GPU/CUDA hardware acceleration, and loaded deep learning checkpoints.

• Response 200 OK:

{
  "status": "healthy",
  "version": "1.0.0",
  "device": "cpu",
  "cuda_available": false,
  "loaded_checkpoints": {
    "seq2seq_arabic": true,
    "seq2seq_english": true,
    "rich_seq2seq_ar": true,
    "rich_seq2seq_en": true
  }
}

---

GET /api/v1/models

Returns list of available summarization algorithms, paradigms, and checkpoint states.

• Response 200 OK:

{
  "total_models": 5,
  "models": [
    {
      "id": "textrank",
      "name": "TextRank",
      "paradigm": "extractive",
      "supported_languages": ["ar", "en"],
      "description": "Graph-based PageRank sentence centrality algorithm computing lexical and TF-IDF similarity graphs."
    },
    {
      "id": "lsa",
      "name": "Latent Semantic Analysis (LSA)",
      "paradigm": "extractive",
      "supported_languages": ["ar", "en"],
      "description": "Singular Value Decomposition (SVD) identifying latent semantic concepts."
    },
    {
      "id": "hybrid",
      "name": "Hybrid Multi-Feature Scorer",
      "paradigm": "extractive",
      "supported_languages": ["ar", "en"],
      "description": "Composite scorer linearly weighting graph centrality, positional bias, and length penalty."
    },
    {
      "id": "seq2seq",
      "name": "Seq2Seq with Bahdanau Attention",
      "paradigm": "abstractive",
      "supported_languages": ["ar", "en"],
      "description": "Deep Bi-GRU Encoder-Decoder network with additive attention and Beam Search.",
      "checkpoint_available": true
    }
  ]
}

---

3.2 NLP Core & Preprocessing

POST /api/v1/detect-language

Detects language (ar, en, or unknown) and script distribution with confidence score.

• Request Body:

{
  "text": "اعلنت وكالة ناسا الفضائية عن خطط طموحة للعودة الى سطح القمر."
}

• Response 200 OK:

{
  "detected_language": "ar",
  "language_name": "Arabic",
  "confidence": 0.98,
  "script_breakdown": {
    "arabic": 0.95,
    "latin": 0.05,
    "other": 0.0
  }
}

---

POST /api/v1/tokenize

Performs Arabic normalization (Tashkeel stripping, Alef unification), sentence boundary detection, and tokenization.

• Request Body:

{
  "text": "الذكاءُ الاصطناعيُّ يُحدِث ثورةً في معالجة اللغات! هل يمكن تلخيص النصوص؟ نعم.",
  "lang": "ar",
  "remove_stopwords": false,
  "stem": false
}

• Response 200 OK:

{
  "detected_language": "ar",
  "sentence_count": 3,
  "word_count": 13,
  "sentences": [
    "الذكاء الاصطناعي يحدث ثورة في معالجة اللغات!",
    "هل يمكن تلخيص النصوص؟",
    "نعم."
  ],
  "tokens": ["الذكاء", "الاصطناعي", "يحدث", "ثورة", "في", "معالجة", "اللغات", "هل", "يمكن", "تلخيص", "النصوص", "نعم"],
  "normalized_text": "الذكاء الاصطناعي يحدث ثورة في معالجة اللغات! هل يمكن تلخيص النصوص؟ نعم."
}

---

3.3 Text Summarization

POST /api/v1/summarize

Main summarization endpoint supporting all Extractive and Abstractive algorithms.

• Request Parameters:

  • text (string, required): Raw source document text.
  • mode (string, default: "extractive"): "extractive", "abstractive", or "hybrid".
  • method (string, default: "textrank"): "textrank", "lsa", "hybrid", "seq2seq", "transformer".
  • lang (string, default: "auto"): "auto", "ar", or "en".
  • sentences (int, default: 3): Number of target sentences (for extractive).
  • ratio (float, optional): Target compression ratio between 0.05 and 0.95.
  • beam_width (int, default: 3): Beam search width for Seq2Seq decoding (1 to 8).
  • reference_summary (string, optional): Gold-standard reference summary to automatically compute ROUGE & BLEU scores.

• Example 1: Arabic Abstractive (Seq2Seq):

{
  "text": "اعلنت وكالة ناسا الفضائية الامريكية عن خطط طموحة للعودة الى سطح القمر في اطار برنامج ارتيميس حيث ستشمل البعثة اول امراة واول شخص من ذوي البشرة الداكنة يمشيان على سطح القمر ومن المقرر ان تنطلق البعثة قبل نهاية عام الفين وخمسة وعشرين.",
  "mode": "abstractive",
  "method": "seq2seq",
  "lang": "ar",
  "beam_width": 3,
  "reference_summary": "ناسا تعلن خطط العودة للقمر عبر برنامج ارتيميس الذي سيضم اول امراة واول شخص من ذوي البشرة الداكنة قبل نهاية 2025"
}

• Response 200 OK:

{
  "status": "success",
  "detected_language": "ar",
  "mode": "abstractive",
  "method": "seq2seq",
  "summary": "ناسا تعلن خطط العوده للقمر عبر برنامج ارتيميس الذي سيضم اول امراه واول شخص من ذوي البشره الداكنه قبل نهايه 2025",
  "latency_ms": 32.4,
  "metrics": {
    "original_words": 37,
    "summary_words": 21,
    "compression_ratio": 0.567,
    "reduction_percentage": 43.3,
    "type_token_ratio": 0.952,
    "rouge_1_f1": 0.952,
    "rouge_2_f1": 0.850,
    "rouge_l_f1": 0.952,
    "bleu_1": 0.952,
    "bleu_2": 0.850,
    "bleu_cumulative": 0.784
  },
  "selected_indices": null,
  "sentence_scores": null,
  "note": null
}

---

POST /api/v1/summarize/file (Multipart Form Data)

Accepts uploaded document files (.pdf, .docx, .txt) and returns the generated summary.

• Request multipart/form-data:

  • file: Binary file upload (application/pdf, text/plain, application/vnd.openxmlformats-officedocument.wordprocessingml.document).
  • mode: "extractive" / "abstractive".
  • method: "hybrid" / "textrank" / "lsa" / "seq2seq".
  • lang: "auto" / "ar" / "en".
  • sentences: 3.

• cURL Example:

curl -X POST "http://localhost:8000/api/v1/summarize/file" \
  -H "accept: application/json" \
  -F "file=@document.pdf" \
  -F "mode=extractive" \
  -F "method=hybrid" \
  -F "sentences=3"

---

3.4 Evaluation & Metrics

POST /api/v1/evaluate

Calculates comprehensive evaluation metrics between an original text, a generated summary, and an optional reference summary.

• Request Body:

{
  "original_text": "Global semiconductor shortages are easing according to the latest industry report with chip inventories returning to normal.",
  "generated_summary": "Semiconductor shortage eases as chip inventories return to normal levels.",
  "reference_summary": "Global chip shortage easing with inventories normalizing across industry.",
  "lang": "en"
}

• Response 200 OK:

{
  "language": "en",
  "compression_ratio": 0.625,
  "reduction_percentage": 37.5,
  "original_words": 16,
  "summary_words": 10,
  "type_token_ratio": 1.0,
  "rouge_1": {
    "precision": 0.50,
    "recall": 0.55,
    "f1": 0.526
  },
  "rouge_2": {
    "precision": 0.22,
    "recall": 0.25,
    "f1": 0.235
  },
  "rouge_l": {
    "precision": 0.50,
    "recall": 0.55,
    "f1": 0.526
  },
  "bleu_1": 0.50,
  "bleu_2": 0.22,
  "bleu_3": 0.12,
  "bleu_4": 0.05,
  "bleu_cumulative": 0.18
}

---

4. Frontend Integration Examples

React / Next.js / Fetch API Example:

async function generateSummary(inputText, algorithm = 'seq2seq') {
  try {
    const response = await fetch('http://localhost:8000/api/v1/summarize', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        text: inputText,
        mode: algorithm === 'seq2seq' ? 'abstractive' : 'extractive',
        method: algorithm,
        lang: 'auto',
        beam_width: 3
      }),
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const data = await response.json();
    console.log('Summary:', data.summary);
    console.log('Reduction:', data.metrics.reduction_percentage + '%');
    return data;
  } catch (error) {
    console.error('Failed to generate summary:', error);
  }
}

Python Requests Example:

import requests

url = "http://localhost:8000/api/v1/summarize"
payload = {
    "text": "شهدت الاسواق العالمية تراجعا حادا في اسعار النفط الخام بعد قرار منظمة اوبك زيادة الانتاج.",
    "mode": "extractive",
    "method": "textrank",
    "sentences": 1
}
res = requests.post(url, json=payload)
print(res.json()["summary"])