README_hf.md

---
title: CSS Essay Grader API
emoji: 🎓
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# 🎓 CSS Essay Grader API

A comprehensive FastAPI application for processing and grading essays with OCR text extraction and AI-powered feedback, deployed on Hugging Face Spaces.

## 🚀 Features

- **OCR Text Extraction**: Extract text from images and PDFs using Google Cloud Vision API
- **Essay Analysis**: AI-powered essay evaluation with detailed feedback
- **Grammar & Structure Analysis**: Comprehensive analysis of grammar, vocabulary, and sentence structure
- **PDF Processing**: Support for PDF file uploads and processing
- **Bulk File Upload**: Process multiple files simultaneously
- **Interactive API Documentation**: Auto-generated Swagger/OpenAPI documentation

## 🛠️ API Endpoints

### Core Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/` | Welcome page with API overview |
| `GET` | `/health` | Health check endpoint |
| `GET` | `/docs` | Interactive API documentation |
| `GET` | `/spaces-info` | Hugging Face Spaces information |

### File Processing

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/upload` | Upload and process a single file (image or PDF) |
| `POST` | `/api/upload/bulk` | Upload and process multiple files (max 10) |

### Essay Analysis

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/essay-analysis` | Generate comprehensive essay analysis with AI feedback |
| `POST` | `/api/feedback` | Generate feedback for essay text |
| `POST` | `/api/verify` | Verify and analyze text quality |

### File Downloads

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/download-pdf/{pdf_path}` | Download generated PDF files |

## 📋 Requirements

### System Dependencies
- Python 3.10+
- Poppler-utils (for PDF processing)
- OpenCV dependencies

### Python Dependencies
- FastAPI
- Uvicorn
- OpenAI
- Google Cloud Vision
- PDF2Image
- OpenCV
- ReportLab
- And more (see `requirements_hf.txt`)

## 🐳 Docker Deployment

This application is configured for deployment on Hugging Face Spaces using Docker.

### Key Configuration
- **Port**: 7860 (required for Hugging Face Spaces)
- **Framework**: FastAPI
- **Container**: Python 3.10-slim with system dependencies

### Environment Variables
- `OPENAI_API_KEY`: Your OpenAI API key
- `GOOGLE_CLOUD_CREDENTIALS`: Google Cloud Vision credentials (JSON)

## 🚀 Quick Start

1. **Clone the repository**:
   ```bash
   git clone https://huggingface.co/spaces/your-username/css-essay-grader
   cd css-essay-grader
   ```

2. **Set up environment variables**:
   - Add your OpenAI API key
   - Configure Google Cloud Vision credentials

3. **Deploy to Hugging Face Spaces**:
   - Push to your Hugging Face Space repository
   - The application will automatically build and deploy

4. **Access the API**:
   - Main application: `https://your-username-css-essay-grader.hf.space`
   - API documentation: `https://your-username-css-essay-grader.hf.space/docs`
   - Health check: `https://your-username-css-essay-grader.hf.space/health`

## 📖 Usage Examples

### Upload and Process a Single File
```bash
curl -X POST "https://your-username-css-essay-grader.hf.space/api/upload" \
  -H "accept: application/json" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@your_essay.pdf"
```

### Analyze Essay Text
```bash
curl -X POST "https://your-username-css-essay-grader.hf.space/api/essay-analysis" \
  -H "accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "essay_text=Your essay text here..."
```

### Health Check
```bash
curl "https://your-username-css-essay-grader.hf.space/health"
```

## 🔧 Configuration

### API Keys Setup
1. **OpenAI API Key**: Required for essay analysis and feedback generation
2. **Google Cloud Vision**: Required for OCR text extraction

### File Size Limits
- Maximum file size: 50MB per file
- Maximum 10 files for bulk upload
- Text length limit: 50,000 characters

## 📊 Response Format

### Essay Analysis Response
```json
{
  "originalEssayWordCount": 500,
  "reWrittenEssayWordCount": 520,
  "originalEssay": "Original essay text...",
  "reWrittenEssay": "Improved essay text...",
  "overallEssayEvaluationScore": 85,
  "evaluationAndScoring": [
    {
      "label": "Grammar & Punctuation",
      "score": 90,
      "issuesCount": 2,
      "issuesList": [...]
    }
  ],
  "essayStructure": [...]
}
```

## 🛡️ Security

- CORS enabled for all origins
- File type validation
- Input sanitization
- Error handling and logging

## 📝 License

This project is licensed under the MIT License.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## 📞 Support

For issues and questions:
- Check the API documentation at `/docs`
- Review the health check at `/health`
- Open an issue on the repository

## 🔄 Updates

The application automatically updates when you push changes to the Hugging Face Space repository.

---

**Built with ❤️ using FastAPI and deployed on Hugging Face Spaces**