README_hf.md

metadata

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:

   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

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

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

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

{
  "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