Init repo

.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+venv/
+env/
+ENV/
+.env
+.venv/
+demo/
+
+# Environment Variables
+.env
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Project Specific
+saved_models/
+*.pt
+*.bin
+*.onnx
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Sub git
+server/
+*.ps1

Dockerfile

@@ -0,0 +1,49 @@
+# Read the doc: https://huggingface.co/docs/hub/spaces-sdks-docker
+FROM python:3.9-slim
+
+# Install system dependencies (git is required for some pip packages)
+USER root
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -m -u 1000 user
+
+# Switch to the "user" user
+USER user
+
+# Set home to the user's home directory
+ENV HOME=/home/user \
+    PATH="/home/user/.local/bin:$PATH" \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    MODELS_DIR=/home/user/app/saved_models \
+    PORT=7860
+
+# Set the working directory to the user's home directory
+WORKDIR $HOME/app
+
+# Copy the current directory contents into the container at $HOME/app setting the owner to the user
+COPY --chown=user . $HOME/app
+
+# Install requirements
+# 1. Install CPU-only torch first to save space (Free tier has no GPU)
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
+
+# 2. Install other dependencies
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+# Download NLTK data
+RUN python -m nltk.downloader punkt punkt_tab
+
+# Download/Cache Models during build
+# Ensure the models directory exists
+RUN mkdir -p $MODELS_DIR
+RUN python download_model.py
+
+# Expose port 7860
+EXPOSE 7860
+
+# Start the application using uvicorn
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

Dockerfile.local

@@ -0,0 +1,38 @@
+# Use PyTorch base image with CUDA support for GPU acceleration
+FROM pytorch/pytorch:2.1.2-cuda11.8-cudnn8-runtime
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    MODELS_DIR=/app/saved_models \
+    PORT=8000
+
+# Install system dependencies
+# git is required for installing parrot-paraphraser from github
+RUN apt-get update && apt-get install -y \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy requirements
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Download NLTK data
+RUN python -m nltk.downloader punkt punkt_tab
+
+# Copy only the downloader script
+# src/ is NOT copied (will be bind mounted by docker-compose)
+COPY download_model.py .
+
+# Run the downloader script to cache the FP16 and INT8 models
+# This script is now standalone and does not require src/
+RUN python download_model.py
+
+# Expose the port
+EXPOSE 8000
+
+# No CMD here - it is defined in docker-compose.yml

README.md

@@ -0,0 +1,16 @@
+---
+title: Parrot Paraphraser
+emoji: 🦜
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+---
+
+# Parrot Paraphraser API
+
+This is a paraphrasing API deployed on Hugging Face Spaces.
+
+## Features
+- **Paraphrasing**: Rewrites input text while preserving meaning.
+- **Language Detection**: Automatically detects and strictly enforces **English text only**. Non-English inputs are rejected to save resources.

RUN.md

@@ -0,0 +1,145 @@
+# Paraphraser API Runner's Guide
+
+This guide explains how to build, run, and interact with the Paraphraser API server using Docker.
+
+## Prerequisites
+
+- **Docker** and **Docker Compose** installed
+- **NVIDIA GPU** (optional, but recommended for performance) with NVIDIA Container Toolkit installed
+- **Git** (to clone the repository)
+
+## Quick Start
+
+1. **Clone the repository**:
+
+   ```bash
+   git clone <repository-url>
+   cd paraphraser/server
+   ```
+2. **Configuration**:
+   The server comes with a default `.env` file. You can customize it if needed:
+
+   ```ini
+   # .env
+   API_KEY=sk-sample-key
+   BATCH_SIZE=8
+   PORT=8080            # Port on your host machine
+   MODELS_DIR=saved_models
+   COMPOSE_PROJECT_NAME=paraphraser
+   ```
+3. **Start the Server**:
+   Run the following command to build and start the container in the background:
+
+   ```bash
+   docker-compose up -d --build
+   ```
+
+   *Note: The first run will take a few minutes to download the ML models and build the image.*
+4. **Verify Status**:
+   Check if the server is running and healthy:
+
+   ```bash
+   curl http://localhost:8080/health
+   ```
+
+   **Expected Output:**
+
+   ```json
+   {"status":"healthy","model_loaded":true,"device":"cuda"}
+   ```
+
+   *(If `device` says "cpu", GPU acceleration is not active.)*
+
+## Usage
+
+### Endpoint: `/paraphrase`
+
+Use this endpoint to paraphrase text. **Note: Only English text is supported.**
+
+- **URL**: `http://localhost:8080/paraphrase`
+- **Method**: `POST`
+- **Headers**:
+  - `Content-Type`: `application/json`
+  - `X-API-Key`: `sk-sample-key` (or whatever is set in your `.env`)
+
+### Sample Request (cURL)
+
+```bash
+curl -X POST http://localhost:8080/paraphrase \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: sk-sample-key" \
+  -d '{
+    "text": "The quick brown fox jumps over the lazy dog."
+  }'
+```
+
+### Sample Response
+
+```json
+{
+  "paraphrased_text": "The quick brown fox leaps over the lazy dog."
+}
+```
+
+### Error Response (Non-English Input)
+
+If the input text is not detected as English, the server returns a `422 Unprocessable Entity` error.
+
+```json
+{
+  "detail": "Only English text is supported"
+}
+```
+
+## Troubleshooting
+
+- **Server not responding immediately?**
+  The model takes 10-20 seconds to load into memory on startup. Check the logs with:
+
+  ```bash
+  docker logs -f paraphraser_api
+  ```
+- **GPU not detected?**
+  Ensure you have the NVIDIA Container Toolkit installed and your Docker daemon is configured to use it.
+
+## Stopping the Server
+
+To stop and remove the container:
+
+```bash
+
+## Deployment to Cloud (Modal)
+
+You can deploy this API to [Modal](https://modal.com) for serverless GPU inference.
+
+### Prerequisites
+1.  Create a [Modal account](https://modal.com/signup).
+2.  Install the Modal client:
+    ```bash
+    pip install modal
+    ```
+3.  Authenticate:
+    ```bash
+    modal setup
+    ```
+
+### Deploying
+Run the deployment script:
+```bash
+modal deploy modal_deploy.py
+```
+
+**Note for Windows Users:**
+If you encounter encoding errors (like `charmap codec can't encode...`), set your python encoding to UTF-8:
+- **PowerShell**: `[System.Environment]::SetEnvironmentVariable('PYTHONIOENCODING', 'utf-8', 'User')` (restart terminal after)
+- **Cmd**: `set PYTHONIOENCODING=utf-8`
+
+The command will output your live URL (e.g., `https://your-username--parrot-paraphraser-fastapi-app.modal.run`).
+
+### Testing the Cloud Endpoint
+```bash
+curl -X POST "https://your-url.modal.run/paraphrase" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: sk-sample-key" \
+  -d '{"text": "The quick brown fox jumps over the lazy dog."}'
+```

app.py

@@ -0,0 +1,58 @@
+from fastapi import FastAPI, HTTPException, Depends
+import os
+import logging
+import uvicorn
+from dotenv import load_dotenv
+
+from src.auth import get_api_key
+from src.schemas import ParaphraseRequest, ParaphraseResponse
+from src.services.paraphraser import paraphraser_service
+from src.services.language_detector import language_detector_service
+from src.middleware.request_logging import RequestLoggingMiddleware
+
+# Load environment variables
+load_dotenv()
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S"
+)
+
+app = FastAPI(title="Parrot Paraphraser API")
+app.add_middleware(RequestLoggingMiddleware)
+
+@app.on_event("startup")
+async def startup_event():
+    language_detector_service.initialize()
+    paraphraser_service.initialize()
+
+@app.get("/")
+def root():
+    return {"message": "Parrot Paraphraser API is running. Visit /docs for documentation."}
+
+@app.get("/health")
+def health_check():
+    return paraphraser_service.get_status()
+
+@app.post("/paraphrase", response_model=ParaphraseResponse)
+async def paraphrase(request: ParaphraseRequest, api_key: str = Depends(get_api_key)):
+    try:
+        # Detect language
+        lang = language_detector_service.detect_language(request.text)
+        if lang != "en":
+            raise HTTPException(status_code=422, detail="Only English text is supported")
+
+        result = paraphraser_service.paraphrase(request.text)
+        return {"paraphrased_text": result}
+    except HTTPException as he:
+        raise he
+    except RuntimeError:
+        raise HTTPException(status_code=503, detail="Model not initialized")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 8080))
+    uvicorn.run(app, host="0.0.0.0", port=port)

docker-compose.yml

@@ -0,0 +1,24 @@
+services:
+  paraphraser-api:
+    build: .
+    container_name: paraphraser_api
+    ports:
+      - "${PORT:-8080}:8000"
+    env_file: .env
+    environment:
+      # Required for GPU access inside the container
+      - NVIDIA_VISIBLE_DEVICES=all
+    volumes:
+      - ./.env:/app/.env
+      - ./src:/app/src
+      - ./app.py:/app/app.py
+    # Explicit command ensures we run on port 8000
+    command: uvicorn app:app --host 0.0.0.0 --port 8000
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]
+    restart: unless-stopped

download_model.py

@@ -0,0 +1,82 @@
+import os
+import torch
+from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+
+# Standalone configuration to avoid dependency on src/ during Docker build
+MODEL_TAG = "prithivida/parrot_paraphraser_on_T5"
+MODELS_DIR = os.getenv("MODELS_DIR", "saved_models")
+QUANTIZED_CPU_FILENAME = "parrot_t5_int8.pt"
+QUANTIZED_GPU_FILENAME = "parrot_t5_fp16.pt"
+FASTTEXT_MODEL_URL = "https://dl.fbaipublicfiles.com/fasttext/supervised-models/lid.176.ftz"
+FASTTEXT_FILENAME = "lid.176.ftz"
+
+def ensure_models_dir():
+    if not os.path.exists(MODELS_DIR):
+        os.makedirs(MODELS_DIR)
+
+def get_model_path(filename):
+    return os.path.join(MODELS_DIR, filename)
+
+def download_and_prepare_dual_mode():
+    print("Starting model download for Dual Mode (CPU + GPU)...")
+
+    # Create directory
+    ensure_models_dir()
+
+    # Paths
+    cpu_path = get_model_path(QUANTIZED_CPU_FILENAME)
+    gpu_path = get_model_path(QUANTIZED_GPU_FILENAME)
+
+    print(f"Loading base model: {MODEL_TAG}")
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_TAG)
+    base_model = AutoModelForSeq2SeqLM.from_pretrained(MODEL_TAG)
+
+    # --- 1. Prepare GPU Version (FP16) ---
+    if not os.path.exists(gpu_path):
+        print("Creating GPU version (FP16)...")
+        # Copy model to avoid modifying the base implementation for CPU step next
+        # (Actually we can just cast to half, save, then reload or use copy)
+        # Simplest: Load, cast, save.
+        gpu_model = base_model.half()
+        print(f"Saving FP16 model to {gpu_path}...")
+        torch.save(gpu_model, gpu_path)
+    else:
+        print(f"GPU model already exists at {gpu_path}")
+
+    # --- 2. Prepare CPU Version (INT8) ---
+    if not os.path.exists(cpu_path):
+        print("Creating CPU version (INT8 Quantized)...")
+        # Reload base model to ensure clean state (fp32)
+        base_model_cpu = AutoModelForSeq2SeqLM.from_pretrained(MODEL_TAG)
+
+        print("Quantizing for CPU...")
+        quantized_model = torch.quantization.quantize_dynamic(
+            base_model_cpu, {torch.nn.Linear}, dtype=torch.qint8
+        )
+        print(f"Saving INT8 model to {cpu_path}...")
+        torch.save(quantized_model, cpu_path)
+    else:
+        print(f"CPU model already exists at {cpu_path}")
+
+    import requests
+    print("Downloading FastText language identification model...")
+    fasttext_path = get_model_path(FASTTEXT_FILENAME)
+    if not os.path.exists(fasttext_path):
+        try:
+            response = requests.get(FASTTEXT_MODEL_URL, stream=True)
+            response.raise_for_status()
+            with open(fasttext_path, 'wb') as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+            print(f"FastText model saved to {fasttext_path}")
+        except Exception as e:
+            print(f"Failed to download FastText model: {e}")
+            # Non-critical for build if we handle it gracefully later, but critical for functionality
+            raise e
+    else:
+        print(f"FastText model already exists at {fasttext_path}")
+
+    print("Dual mode models cached successfully.")
+
+if __name__ == "__main__":
+    download_and_prepare_dual_mode()

modal_deploy.py

@@ -0,0 +1,47 @@
+import modal
+import os
+import sys
+
+# Define the image with all dependencies and baked-in models
+image = (
+    modal.Image.debian_slim(python_version="3.10")
+    .apt_install("git")
+    .pip_install(
+        "torch",
+        "transformers==4.38.2",
+        "sentencepiece==0.1.99",
+        "protobuf==3.20.3",
+        "git+https://github.com/PrithivirajDamodaran/Parrot_Paraphraser.git",
+        "python-dotenv==1.0.1",
+        "fastapi==0.110.0",
+        "uvicorn==0.27.1",
+        "nltk"
+    )
+    .run_commands("python -m nltk.downloader punkt punkt_tab")
+    .workdir("/root")
+    # Copy the model download script
+    .add_local_file("download_model.py", "/root/download_model.py", copy=True)
+    # Download and cache models during the build phase
+    .run_commands("python download_model.py")
+    # Copy the source code
+    .add_local_dir("src", "/root/src")
+    .add_local_file("app.py", "/root/app.py")
+)
+
+app = modal.App("parrot-paraphraser")
+
+@app.function(
+    image=image,
+    gpu="any",  # Request any available GPU
+    scaledown_window=300,  # Keep container warm for 5 minutes
+    timeout=600,
+    secrets=[modal.Secret.from_dotenv()],
+)
+@modal.asgi_app()
+def fastapi_app():
+    # Ensure /root is in the python path so imports work correctly
+    sys.path.append("/root")
+
+    # Import the FastAPI app from app.py
+    from app import app as web_app
+    return web_app

requirements.txt

@@ -0,0 +1,12 @@
+# torch  # Recommended: Install PyTorch with GPU support manually for better performance (see https://pytorch.org/get-started/locally/)
+transformers==4.38.2
+sentencepiece==0.1.99
+protobuf==3.20.3
+git+https://github.com/PrithivirajDamodaran/Parrot_Paraphraser.git
+python-dotenv==1.0.1
+fastapi==0.104.1
+uvicorn==0.24.0
+nltk==3.9.1
+fasttext-wheel==0.9.2
+requests==2.31.0
+numpy==1.26.4

src/auth.py

@@ -0,0 +1,24 @@
+from fastapi import Security, HTTPException, status
+from fastapi.security import APIKeyHeader
+from .config import Config
+
+API_KEY_NAME = "X-API-Key"
+api_key_header = APIKeyHeader(name=API_KEY_NAME, auto_error=False)
+
+def get_api_key(api_key_header: str = Security(api_key_header)):
+    expected_api_key = Config.API_KEY
+
+    # If no API key is set in env, fail safe
+    if not expected_api_key:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Server API Key not configured"
+        )
+
+    if api_key_header == expected_api_key:
+        return api_key_header
+
+    raise HTTPException(
+        status_code=status.HTTP_403_FORBIDDEN,
+        detail="Could not validate credentials"
+    )

src/config.py

@@ -0,0 +1,29 @@
+import os
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+class Config:
+    # Directory where models are stored/cached
+    MODELS_DIR = os.getenv("MODELS_DIR", "saved_models")
+
+    # Inference batch size
+    BATCH_SIZE = int(os.getenv("BATCH_SIZE", "8"))
+
+    # API Key
+    API_KEY = os.getenv("API_KEY")
+
+    # FastText Model
+    FASTTEXT_FILENAME = "lid.176.ftz"
+
+    @staticmethod
+    def get_model_path(filename: str) -> str:
+        """Helper to get full path for a model file."""
+        return os.path.join(Config.MODELS_DIR, filename)
+
+    @staticmethod
+    def ensure_models_dir():
+        """Ensures the models directory exists."""
+        if not os.path.exists(Config.MODELS_DIR):
+            os.makedirs(Config.MODELS_DIR)

src/interface.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+class ParaphrasingModel(ABC):
+    """
+    Abstract base class for paraphrasing models (e.g., T5, GPT).
+    """
+    @abstractmethod
+    def paraphrase(self, text: str) -> str:
+        """Paraphrase the given text."""
+        pass
+
+    def paraphrase_batch(self, texts: List[str]) -> List[str]:
+        """
+        Paraphrase a list of texts.
+        Default implementation loops, but subclasses should override for GPU batching.
+        """
+        return [self.paraphrase(text) for text in texts]
+
+class TextProcessingMode(ABC):
+    """
+    Abstract base class for text processing modes (Strategy Pattern).
+    Defines HOW the text is broken down and processed (e.g., by paragraph, random sentences).
+    """
+    @abstractmethod
+    def process(self, text: str, paraphraser: ParaphrasingModel) -> str:
+        """
+        Process a block of text using the provided paraphraser.
+        """
+        pass

src/middleware/request_logging.py

@@ -0,0 +1,34 @@
+"""Request logging middleware for timing."""
+import time
+import logging
+from typing import Callable
+
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """Middleware to log request processing time."""
+    
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process request with timing."""
+        start_time = time.time()
+        
+        # Log incoming request
+        logger.info(f"Incoming request: {request.method} {request.url}")
+        
+        # Process request
+        response = await call_next(request)
+        
+        # Calculate processing time
+        process_time = time.time() - start_time
+        
+        # Log processing time
+        logger.info(f"Request processed in {process_time:.4f}s - {request.method} {request.url} - Status: {response.status_code}")
+        
+        # Add processing time to response headers
+        response.headers["X-Process-Time"] = str(process_time)
+        
+        return response

src/models/parrot_model.py

@@ -0,0 +1,203 @@
+import torch
+import warnings
+import os
+from typing import Optional, List, Tuple
+from transformers import AutoTokenizer, AutoModelForSeq2SeqLM
+from ..interface import ParaphrasingModel
+from ..config import Config
+from ..modes.generation import GenerationModeFactory
+from parrot import Parrot
+from parrot.filters import Adequacy, Fluency, Diversity
+
+class ParrotModel(ParaphrasingModel):
+    """
+    Concrete implementation of ParaphrasingModel using the Parrot library.
+    Adapts the prithivida/parrot_paraphraser_on_T5 model.
+    Supports INT8 quantization on CPU for faster loading.
+    """
+
+    MODEL_TAG = "prithivida/parrot_paraphraser_on_T5"
+    QUANTIZED_CPU_FILENAME = "parrot_t5_int8.pt"
+    QUANTIZED_GPU_FILENAME = "parrot_t5_fp16.pt"
+
+    def __init__(self, use_gpu: Optional[bool] = None):
+        if use_gpu is not None:
+            self.use_gpu = use_gpu
+        else:
+            self.use_gpu = torch.cuda.is_available()
+
+        # Filter warnings as in the original script
+        warnings.filterwarnings("ignore")
+        self.parrot_model = self._load_model()
+
+    def _load_model(self) -> Parrot:
+        device = "cuda" if self.use_gpu else "cpu"
+        print(f"Loading Parrot model ({self.MODEL_TAG}) on {device}...")
+
+        # Create models directory if it doesn't exist
+        Config.ensure_models_dir()
+
+        quantized_path = Config.get_model_path(self.QUANTIZED_CPU_FILENAME)
+        gpu_path = Config.get_model_path(self.QUANTIZED_GPU_FILENAME)
+
+        tokenizer = None
+        model = None
+
+        # Try to load GPU model if on CUDA
+        if device == "cuda" and os.path.exists(gpu_path):
+            print(f"Loading GPU Parrot model from {gpu_path}...")
+            try:
+                tokenizer = AutoTokenizer.from_pretrained(self.MODEL_TAG)
+                model = torch.load(gpu_path)
+                model.to(device)
+                model.eval()
+                print("GPU Parrot model loaded successfully.")
+            except Exception as e:
+                print(f"Failed to load GPU model: {e}. Falling back to standard load.")
+
+        # Try to load quantized model if on CPU
+        if device == "cpu" and os.path.exists(quantized_path) and model is None:
+            print(f"Loading quantized Parrot model from {quantized_path}...")
+            try:
+                tokenizer = AutoTokenizer.from_pretrained(self.MODEL_TAG)
+                model = torch.load(quantized_path)
+                model.eval()
+                print("Quantized Parrot model loaded successfully.")
+            except Exception as e:
+                print(f"Failed to load quantized model: {e}. Falling back to standard load.")
+
+        if model is None:
+            tokenizer = AutoTokenizer.from_pretrained(self.MODEL_TAG)
+            model = AutoModelForSeq2SeqLM.from_pretrained(self.MODEL_TAG).to(device)
+
+            # Quantize and save if on CPU
+            if device == "cpu":
+                print("Quantizing Parrot model to INT8...")
+                model = torch.quantization.quantize_dynamic(
+                    model, {torch.nn.Linear}, dtype=torch.qint8
+                )
+                print(f"Saving quantized Parrot model to {quantized_path}...")
+                torch.save(model, quantized_path)
+
+            # Save FP16 model if on GPU
+            elif device == "cuda":
+                print("Converting Parrot model to FP16 for GPU...")
+                model = model.half()
+                print(f"Saving GPU Parrot model to {gpu_path}...")
+                torch.save(model, gpu_path)
+
+        # Manually construct Parrot instance to bypass its __init__ (which loads model again)
+        parrot_instance = Parrot.__new__(Parrot)
+        parrot_instance.tokenizer = tokenizer
+        parrot_instance.model = model
+        parrot_instance.device = device
+
+        # Manually initialize the scoring attributes that would have been set in __init__
+        parrot_instance.adequacy_score = Adequacy()
+        parrot_instance.fluency_score = Fluency()
+        parrot_instance.diversity_score = Diversity()
+
+        return parrot_instance
+
+    def paraphrase(self, text: str) -> str:
+        """
+        Paraphrases text using the Parrot model.
+        Returns the highest scored paraphrase or original text if none found.
+        """
+        text = text.strip()
+        if not text:
+            return ""
+
+        # Avoid processing code blocks or very short noise
+        if text.startswith("```") or len(text) < 3:
+            return text
+
+        try:
+            # We bypass parrot.augment to use uniform GenerationModes
+            # This ensures Perplexity, Anti-Tell, etc. work consistently.
+            input_ids = self.parrot_model.tokenizer(
+                text,
+                return_tensors="pt",
+                truncation=True,
+                max_length=512
+            ).input_ids.to(self.parrot_model.device)
+
+            # Use "hybrid" as placeholder, factory returns HybridMode regardless
+            mode = GenerationModeFactory.get_mode("hybrid")
+            generate_kwargs = mode.get_config(self.parrot_model.tokenizer)
+
+            outputs = self.parrot_model.model.generate(
+                input_ids,
+                **generate_kwargs
+            )
+
+            res = self.parrot_model.tokenizer.batch_decode(outputs, skip_special_tokens=True)
+            return res[0] if res else text
+
+        except Exception as e:
+            print(f"Error during Parrot inference: {e}")
+            return text
+
+    def paraphrase_batch(self, texts: List[str]) -> List[str]:
+        """
+        True batch implementation bypassing the slow parrot.augment loop.
+        Processes in chunks of Config.BATCH_SIZE.
+        """
+        results = [""] * len(texts)
+
+        # 1. Prepare valid inputs
+        valid_items = []
+        for i, text in enumerate(texts):
+            text = text.strip()
+            if text and not text.startswith("```") and len(text) >= 3:
+                valid_items.append((i, text))
+            else:
+                results[i] = text
+
+        if not valid_items:
+            return results
+
+        # 2. Process in chunks
+        batch_size = Config.BATCH_SIZE
+
+        for i in range(0, len(valid_items), batch_size):
+            chunk = valid_items[i : i + batch_size]
+            chunk_indices = [item[0] for item in chunk]
+            chunk_texts = [item[1] for item in chunk]
+
+            # Tokenize chunk
+            inputs = self.parrot_model.tokenizer(
+                chunk_texts,
+                padding=True,
+                truncation=True,
+                return_tensors="pt"
+            ).to(self.parrot_model.device)
+
+            # Generate chunk on GPU
+            try:
+                # Use "hybrid" as placeholder
+                mode = GenerationModeFactory.get_mode("hybrid")
+                generate_kwargs = mode.get_config(self.parrot_model.tokenizer)
+
+                outputs = self.parrot_model.model.generate(
+                    **inputs,
+                    **generate_kwargs
+                )
+
+                # Decode chunk
+                generated_texts = self.parrot_model.tokenizer.batch_decode(
+                    outputs,
+                    skip_special_tokens=True
+                )
+
+                # Map back to results
+                for idx, gen_text in zip(chunk_indices, generated_texts):
+                    results[idx] = gen_text
+
+            except Exception as e:
+                print(f"Batch inference failed for chunk {i}: {e}")
+                # Fallback to original text
+                for idx, text in zip(chunk_indices, chunk_texts):
+                    results[idx] = text
+
+        return results

src/modes/generation/__init__.py

@@ -0,0 +1,2 @@
+from .factory import GenerationModeFactory
+from .generation_interface import GenerationMode

src/modes/generation/factory.py

@@ -0,0 +1,11 @@
+from typing import Optional
+from .generation_interface import GenerationMode
+from .hybrid import HybridMode
+
+class GenerationModeFactory:
+    @staticmethod
+    def get_mode(mode_name: str) -> GenerationMode:
+        # For this optimized server, we always return HybridMode
+        # regardless of the requested string, or we could strict check it.
+        # Given the requirements, defaulting to Hybrid is safest/cleanest.
+        return HybridMode()

src/modes/generation/generation_interface.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+from transformers import PreTrainedTokenizer
+
+class GenerationMode(ABC):
+    """
+    Abstract base class for T5 generation modes.
+    """
+    @abstractmethod
+    def get_config(self, tokenizer: Optional[PreTrainedTokenizer] = None) -> Dict[str, Any]:
+        """
+        Returns the generate() kwargs for this mode.
+        """
+        pass

src/modes/generation/hybrid.py

@@ -0,0 +1,51 @@
+from typing import Dict, Any, Optional
+from transformers import PreTrainedTokenizer
+from .generation_interface import GenerationMode
+
+class HybridMode(GenerationMode):
+    """
+    Hybrid Mode: Balances Readability and Evasion.
+
+    1. Vocabulary: Bans ONLY specific 'AI fingerprint' nouns/verbs, keeping functional glue words.
+    2. Sampling: Uses Nucleus Sampling (top_p) for natural variance.
+    3. Brevity: Mild length penalty to avoid AI rambling.
+    """
+
+    # A much stricter, curated list than Anti-Tell.
+    # We allow functional words ("ensure", "enable") but ban obvious AI-isms.
+    AI_FINGERPRINTS = [
+        # The absolute worst offenders (immediate AI tells)
+        "delve", "embark", "game-changer", "landscape", "realm", "tapestry",
+        "testament", "underscore", "harness", "leverage", "demystify",
+        "plethora", "myriad", "beacon", "symphony", "nuance",
+        "paramount", "pivotal", "intricate", "meticulous"
+    ]
+
+    def get_config(self, tokenizer: Optional[PreTrainedTokenizer] = None) -> Dict[str, Any]:
+        config = {
+            "max_length": 1024,
+            "early_stopping": True,
+            "do_sample": True,          # Enable sampling for evasion
+            "top_p": 0.95,              # Relaxed: Allow broader vocabulary (typos, slang, "messy" human text)
+            "top_k": 60,                # Keep decent variety
+            "temperature": 0.96,        # High variance: Encourages unexpected phrasing (like "How are you kidding?")
+            "repetition_penalty": 1.1,  # Lower penalty: Allow natural conversational repetition
+            "length_penalty": 1.0,      # Neutral: Don't force brevity. Allow sentence merging/rambling.
+            "num_return_sequences": 1
+        }
+
+        if tokenizer:
+            bad_ids = []
+            for word in self.AI_FINGERPRINTS:
+                # Encode word alone
+                ids_1 = tokenizer.encode(word, add_special_tokens=False)
+                # Encode word with leading space (common in T5)
+                ids_2 = tokenizer.encode(" " + word, add_special_tokens=False)
+
+                if ids_1: bad_ids.append(ids_1)
+                if ids_2: bad_ids.append(ids_2)
+
+            if bad_ids:
+                config["bad_words_ids"] = bad_ids
+
+        return config

src/modes/processing/burstiness.py

@@ -0,0 +1,58 @@
+import random
+import nltk
+from src.interface import TextProcessingMode, ParaphrasingModel
+
+# Ensure nltk resources are available
+try:
+    nltk.data.find('tokenizers/punkt')
+except LookupError:
+    nltk.download('punkt')
+
+class BurstinessMode(TextProcessingMode):
+    """
+    Groups sentences into variable-sized chunks (1-3 sentences) to create
+    rhythmic variation (burstiness) in the output.
+    """
+    def __init__(self, min_chunk: int = 1, max_chunk: int = 3):
+        self.min_chunk = min_chunk
+        self.max_chunk = max_chunk
+
+    def process(self, text: str, paraphraser: ParaphrasingModel) -> str:
+        # Respect paragraph structure to maintain markdown formatting
+        paragraphs = text.split('\n')
+        processed_paragraphs = []
+
+        for p in paragraphs:
+            if not p.strip():
+                processed_paragraphs.append(p)
+                continue
+
+            processed_paragraphs.append(self._process_paragraph_chunks(p, paraphraser))
+
+        return '\n'.join(processed_paragraphs)
+
+    def _process_paragraph_chunks(self, paragraph: str, paraphraser: ParaphrasingModel) -> str:
+        sentences = nltk.sent_tokenize(paragraph)
+        if not sentences:
+            return paragraph
+
+        chunks = []
+        i = 0
+        while i < len(sentences):
+            # Determine chunk size randomly
+            chunk_size = random.randint(self.min_chunk, self.max_chunk)
+
+            # Slice the sentences for this chunk
+            chunk_sentences = sentences[i : i + chunk_size]
+
+            # Join them to form a single text block
+            chunk_text = " ".join(chunk_sentences)
+            chunks.append(chunk_text)
+
+            i += chunk_size
+
+        # Process all chunks in a batch
+        processed_chunks = paraphraser.paraphrase_batch(chunks)
+
+        # Join chunks back together
+        return " ".join(processed_chunks)

src/schemas.py

@@ -0,0 +1,7 @@
+from pydantic import BaseModel
+
+class ParaphraseRequest(BaseModel):
+    text: str
+
+class ParaphraseResponse(BaseModel):
+    paraphrased_text: str

src/services/language_detector.py

@@ -0,0 +1,62 @@
+import fasttext
+import os
+import logging
+from src.config import Config
+
+logger = logging.getLogger(__name__)
+
+class LanguageDetectorService:
+    def __init__(self):
+        self.model = None
+        self._initialized = False
+
+    def initialize(self):
+        """Initialize the FastText model."""
+        if self._initialized:
+            return
+
+        model_path = Config.get_model_path(Config.FASTTEXT_FILENAME)
+        if not os.path.exists(model_path):
+            logger.error(f"FastText model not found at {model_path}")
+            # If model is missing, we can't function properly.
+            # In production, this should probably prevent startup or fail gracefully.
+            raise RuntimeError(f"FastText model not found at {model_path}")
+
+        try:
+            logger.info(f"Loading FastText model from {model_path}...")
+            # Supress fasttext warning on load if possible, but it usually prints to C++ stdout
+            self.model = fasttext.load_model(model_path)
+            self._initialized = True
+            logger.info("LanguageDetectorService initialized successfully.")
+        except Exception as e:
+            logger.error(f"Failed to load FastText model: {e}")
+            raise RuntimeError(f"Failed to load FastText model: {e}")
+
+    def detect_language(self, text: str) -> str:
+        """
+        Detects the language of the provided text.
+        Returns the ISO 639-1 language code (e.g., 'en', 'fr').
+        """
+        if not self._initialized or self.model is None:
+             raise RuntimeError("LanguageDetectorService not initialized")
+
+        if not text or not text.strip():
+            return "unknown"
+
+        # fasttext expects a single line for prediction
+        clean_text = text.replace("\n", " ")
+
+        try:
+            # predict returns a tuple: (['__label__en'], array([0.98...]))
+            labels, _ = self.model.predict(clean_text)
+            if labels:
+                # Extract language code from '__label__en'
+                lang_code = labels[0].replace("__label__", "")
+                return lang_code
+            return "unknown"
+        except Exception as e:
+            logger.error(f"Error detecting language: {e}")
+            return "unknown"
+
+# Global instance
+language_detector_service = LanguageDetectorService()

src/services/paraphraser.py

@@ -0,0 +1,46 @@
+from src.models.parrot_model import ParrotModel
+from src.modes.processing.burstiness import BurstinessMode
+from src.config import Config
+
+class ParaphraserService:
+    def __init__(self):
+        self.model = None
+        self.burstiness_mode = None
+        self._initialized = False
+
+    def initialize(self):
+        """Initialize the model and processing modes."""
+        if self._initialized:
+            return
+
+        # Configure for Hybrid mode
+        Config.GENERATION_MODE = "hybrid"
+
+        print("Initializing Parrot Model...")
+        # use_gpu=None triggers auto-detection in ParrotModel class
+        self.model = ParrotModel(use_gpu=None)
+
+        print("Initializing Burstiness Mode...")
+        self.burstiness_mode = BurstinessMode(min_chunk=1, max_chunk=3)
+        self._initialized = True
+        print("Service initialization complete.")
+
+    def get_status(self):
+        """Return the health status of the service."""
+        if self.model is not None:
+             return {
+                "status": "healthy",
+                "model_loaded": True,
+                "device": "cuda" if self.model.use_gpu else "cpu"
+            }
+        return {"status": "starting", "model_loaded": False}
+
+    def paraphrase(self, text: str) -> str:
+        """Process the text using the configured mode and model."""
+        if not self._initialized or self.model is None or self.burstiness_mode is None:
+             raise RuntimeError("Service not initialized")
+
+        return self.burstiness_mode.process(text, self.model)
+
+# Global instance
+paraphraser_service = ParaphraserService()