README.md

---
title: Rawi Review API
emoji: 📝
colorFrom: indigo
colorTo: blue
sdk: docker
sdk_version: "3.10"
app_file: app.py
pinned: false
license: mit
---

# Rawi Review API

This API provides literary evaluation services for Arabic stories, offering detailed critiques based on essential literary criteria.

## API Endpoints

### GET /
Returns a welcome message.

### POST /review-story/
Accepts a PDF file containing a story and returns a detailed literary evaluation.

**Request:**
- `file`: PDF file (required)

**Response:**
```json
{
  "evaluation": "Detailed evaluation in Arabic...",
  "fixed_story": null
}
```

### POST /review-story-text/
Accepts story text directly and returns a detailed literary evaluation.

**Request:**
```json
{
  "text": "Your story text here..."
}
```

**Response:**
```json
{
  "evaluation": "Detailed evaluation in Arabic...",
  "fixed_story": null
}
```

## Environment Variables

- `DEEPSEEK_API_KEY`: API key for DeepSeek AI (optional - will use mock responses if not provided)
- `PORT`: Port to run the service on (default: 7860)

## Evaluation Criteria

Stories are evaluated based on 8 literary criteria:

1. Unity of event
2. Limited and defined characters
3. Focus on a decisive moment
4. Conciseness and economy of language
5. Unity of time and place
6. Well-structured plot
7. Impactful ending
8. Clear message or theme

Each criterion is scored out of 10, with a final score out of 80.

## Deployment

This service is ready to be deployed on Hugging Face Spaces using the included Dockerfile.

### Running Locally

```bash
pip install -r requirements.txt
uvicorn app:app --reload
```

### Using Docker

```bash
docker build -t rawi-review-api .
docker run -p 7860:7860 -e DEEPSEEK_API_KEY=your_api_key rawi-review-api
```