auto-grade

A PoC of an automatic bulk assignment grader LLM engine

Project Status

Metric	Status
Build Status
Code Coverage	- 100% Required
Code Quality
Technical Debt
Dependencies	- Deactivated, waiting for #784
Last Commit

Quick Start

1. Clone the repository

   git clone https://github.com/FumingPower3925/auto-grade.git
   cd auto-grade

2. Set up environment variables

   cp .env.example .env
   # Edit .env and add your secrets

3. Run the application

   make build  # Build Docker images
   make up     # Start the application

The API will be available at http://localhost:8080/api and the web interface at http://localhost:8080

Development Commands

All commands are available through the Makefile. Run make help to see all available commands.

Application Management

make build          # Build all Docker images
make up             # Start the application
make down           # Stop all services and remove volumes
make logs           # View application logs

Testing

make test           # Run all tests
make test-unit      # Run unit tests with 100% coverage requirement
make test-integration # Run integration tests
make test-e2e       # Run end-to-end tests with Playwright

Code Quality

make lint           # Run ruff linter with auto-fix and format
make lint-check     # Check linting without auto-fix
make type-check     # Run mypy type checking
make format         # Format code with ruff
make security       # Run security checks with bandit

Package Management

uv lock             # Update uv.lock file after changing dependencies
uv sync             # Install/update all dependencies from lock file

Testing

The project includes comprehensive testing with multiple layers:

• Unit Tests: Test individual components in isolation (tests/unit/)
  • 100% coverage required - CI will fail if coverage drops below 100%
  • Coverage is only collected from unit tests
• Integration Tests: Test component interactions (tests/integration/)
  • No coverage requirements
  • Tests API endpoints and database operations
• E2E Tests: Test complete user workflows using Playwright (tests/e2e/)
  • Browser-based testing
  • Screenshots and videos captured on failure

Test Architecture

• Parallel Execution: All test types run in parallel for faster CI
• Unit and integration tests run in dedicated Docker containers
• E2E tests run with Playwright for browser automation
• All tests are automatically run in the CI/CD pipeline
• Coverage reports are generated and uploaded to Codecov

CI/CD Pipeline Features

• Parallel test execution for faster feedback
• 100% code coverage enforcement on unit tests
• Code quality checks with mypy, ruff, and bandit
• Security scanning with Trivy and safety
• SonarCloud integration for code quality metrics
• Multi-platform Docker builds (AMD64 & ARM64)
• Artifact uploads for test results and coverage reports

Contributing

⚠️ Important Notice

This project is part of my Master's Thesis at Universitat Politècnica de Catalunya (UPC). Until the thesis is presented and defended, I cannot accept external contributions.

After the thesis presentation (expected mid-2025), all contributions will be welcome!

After Thesis Presentation

Once the thesis is complete, contributions will be welcome! Here's how to contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Ensure tests pass with 100% coverage (make test-unit)
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Development Requirements

• Python 3.13+
• Docker and Docker Compose
• UV for dependency management
• 100% test coverage for new code

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Author

Albert Bausili

• Email: albert.bausili@gmail.com
• GitHub: @FumingPower3925