convez.ai
SkillAutomaçãoAvançado
ruomuo

GraderFlow Skills

ruomuo/GraderFlow-skills

Correção automática de provas com OMR + LLM multimodal

Ver no GitHub
InicialPluginScore · de 0 a 100

Suite de automação para correção de provas com IA, combinando YOLO para reconhecimento óptico de marcas (OMR) em questões objetivas e modelos multimodais LLM para questões subjetivas. Processa lotes de imagens de provas, extrai dados de estudantes e exporta resultados com anotações e estatísticas.

Instalação

$npx convez-ai ruomuo/GraderFlow-skills

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
6
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Correção em lote de folhas de resposta com questões objetivas
  • Avaliação automática de questões abertas com IA
  • Extração e reconhecimento de dados de estudantes em provas

Veredito

Ferramenta robusta para automação de processos educacionais, bem estruturada com suporte a OMR e LLM. Requer configuração técnica considerável e conhecimento em Python, mas entrega valor real em cenários de correção em escala.

README

A tradução para o português deste README ainda está na fila.

GraderFlow Skills 📝

🎓 阅卷 Skills — AI 驱动的试卷批改工具集,可集成到 Claude Code / Trae / Cursor 等 AI Agent 中使用。AI-powered exam grading skill: YOLO-based OMR + multimodal LLM for objective & subjective questions + batch processing.

English | 中文

GraderFlow Skills is a standalone, headless runtime designed for automated exam grading. It combines a YOLO-based OMR (Optical Mark Recognition) engine for multiple-choice questions with multimodal LLM-powered grading for subjective questions — packaged as an AI Agent Skill usable in Claude Code, Trae, Cursor, or any agent platform. Also fully controllable via CLI.


✨ Features

  • 📋 Objective Grading — YOLOv5-based answer sheet detection + contour-based fill recognition. Supports multi-select questions, configurable scoring rules, and per-question option counts.
  • 🤖 Subjective Grading — LLM-powered (multimodal vision models) for open-ended questions, with structured scoring reports.
  • 👤 Student Info Recognition — Extract name and student ID from exam sheets via multimodal LLM.
  • 🔢 Barcode Recognition — Optional barcode-based student ID extraction (OpenCV + pyzbar).
  • 📊 Batch Processing — Process entire directories of exam images in one command, export to Excel/CSV with detailed statistics.
  • 🎨 Annotation — Auto-generates annotated images marking wrong answers, summaries, and per-question CSV records.
  • 🤖 AI Agent Skill — Ships with a Claude Code / Trae skill (skill/SKILL.md) for conversational grading workflows.

📦 Project Structure

graderflow-skills/
├── README.md                # ← You are here
├── skill/
│   └── SKILL.md             # AI agent skill definition
└── runtime/
    ├── config/
    │   ├── config.json              # Main configuration
    │   ├── answer_config/
    │   │   ├── objective_answer.txt  # Multiple-choice answer key
    │   │   └── subjective_answer.txt # Subjective answer key
    │   └── weights/
    │       └── best.pt              # YOLOv5 detection model
    ├── core/
    │   ├── omr/                     # OMR engine (detection, recognition, annotation)
    │   ├── subjective/              # LLM-based subjective grading
    │   └── data/                    # Student data model
    ├── test_script/
    │   └── agent_batch_marking.py   # ★ Main batch grading entry point
    ├── utils/                       # Config manager, path utils
    ├── yolo/                        # YOLOv5 inference code
    ├── prompts/                     # Reusable AI prompts
    ├── run_marking.bat              # Windows batch wrapper
    ├── run_marking.ps1              # PowerShell wrapper
    ├── requirements-runtime.txt     # Python dependencies
    └── requirements.txt

🚀 Quick Start

Prerequisites

  • Python 3.8+
  • PyTorch (CPU or CUDA)

1. Install Dependencies

pip install -r runtime/requirements-runtime.txt

2. Prepare Answer Keys

Edit the answer configuration files under runtime/config/answer_config/:

objective_answer.txt — one line per question:

# 题号:答案:分值:选项个数
1:A:1.0:4
2:B,C:2.0:4      # Multi-select: comma-separated answers
3:A,B,C,D:1.0:4   # Select-all

subjective_answer.txt — free-form answer reference:

1题(10.0分)
(1) 参考答案要点一 (+3)
(2) 参考答案要点二 (+7)

2题(15.0分)
...

3. Configure (Optional)

Edit runtime/config/config.json:

{
    "api_key": "sk-your-api-key-here",      // Required for subjective grading & student info
    "api_base_url": "https://api.siliconflow.cn/v1",
    "model_name": "Qwen/Qwen3-VL-30B-A3B-Instruct",
    "recognition": {
        "mode": "A",          // "A" = natural order, "B" = column-priority
        "layout": "row",      // "row" or "column"
        "group_size": 5,      // Questions per image crop
        "conf_thres": 0.75    // YOLO confidence threshold
    },
    "objective_scoring_rule": "standard"  // or "partial_penalty"
}

Note: You can leave api_key empty — objective-only grading works without any API key. The system will automatically skip subjective grading and student info recognition.

4. Run

# Grade a single exam paper
python runtime/test_script/agent_batch_marking.py \
    --input-file "E:/exams/answer_001.jpg" \
    --enable-subjective false

# Batch grade a directory
python runtime/test_script/agent_batch_marking.py \
    --input-dir "E:/exams/batch_01/" \
    --output-dir "E:/results/" \
    --recursive

# Full pipeline (objective + subjective + student info)
python runtime/test_script/agent_batch_marking.py \
    --input-dir "E:/exams/batch_01/" \
    --enable-subjective true \
    --enable-student-info true \
    --enable-barcode false

5. Using Wrapper Scripts (Windows)

.\runtime\run_marking.ps1 -InputDir "E:\exams\batch_01"
runtime\run_marking.bat "E:\exams\batch_01"

📋 CLI Reference

python runtime/test_script/agent_batch_marking.py --help
ArgumentTypeDefaultDescription
--input-filepath—Single exam image path (mutually exclusive with --input-dir)
--input-dirpath—Directory containing exam images (mutually exclusive with --input-file)
--output-dirpathinput_parent/graderflow_output/Root directory for all output artifacts
--outputpathauto-generatedSpecific output file path (.xlsx or .csv)
--recursiveflagfalseRecursively scan subdirectories for images
--enable-objectivebooltrueEnable multiple-choice grading
--enable-subjectivebooltrueEnable LLM-based subjective grading
--enable-student-infobooltrueEnable student name/ID recognition
--enable-barcodeboolfalseEnable barcode recognition

Supported image formats: .jpg, .jpeg, .png, .bmp, .webp


📤 Output Structure

All results are written to the output directory (default: <input-parent>/graderflow_output/):

graderflow_output/
├── grading_summary_20260609_111208.xlsx       # Main results (Excel)
├── grading_summary_20260609_111208_summary.json # Statistics (JSON)
├── grading_summary_20260609_111208_summary.txt  # Statistics (plain text)
├── annotated/                                  # Annotated answer sheets
│   └── answer_186_annotated.jpg               #   — wrong answers highlighted
├── originals/                                  # Original image backups
│   └── answer_186_original.jpg
├── summaries/                                  # Score summary images
│   └── answer_186_summary.jpg
├── records/                                    # Per-question CSV records
│   └── answer_186_records.csv                 #   — question-by-question breakdown
├── reports/                                    # Subjective grading reports (if enabled)
│   └── <id>+<name>+subjective.txt
└── _temp/                                      # Temporary files (safe to delete)

Excel Result Columns

ColumnDescription
原图文件Original image filename
学号Student ID (recognized)
姓名Student name (recognized)
客观题成绩Objective score
主观题成绩Subjective score
总成绩Total score
错题数Wrong answer count
空白数Blank answer count
错题列表Comma-separated wrong question numbers
空白题列表Comma-separated blank question numbers
状态success / failed
错误信息Error details if failed

🧠 How It Works

Objective Grading Pipeline

Input Image → Deskew → YOLOv5 Detection (answer areas)
    → Crop & Sort → Contour Fill Detection
    → Answer Matching → Scoring → Annotation
  1. Deskew: Projection-based image rotation correction
  2. YOLOv5 Detection: Locates answer-area bounding boxes on the sheet
  3. Crop & Sort: Extracts individual answer blocks (5 questions per block by default)
  4. Fill Detection: Contour-based filled/empty classification per option
  5. Scoring: Match against answer key with support for standard and partial-penalty rules
  6. Annotation: Generate visual feedback marking wrong answers

Subjective Grading Pipeline

Input Image → Base64 Encode → Multimodal LLM API
    → Structured Scoring → Report Generation

Student Info Recognition

Input Image → Multimodal LLM API → JSON Parse → Name + Student ID

🤖 AI Agent Integration

GraderFlow ships with a Claude Code / Trae skill at skill/SKILL.md. When loaded, AI agents can:

  • Parse natural language grading requests
  • Auto-detect and validate runtime configuration
  • Execute grading workflows with proper parameters
  • Summarize results in readable format
  • Flag anomalies for manual review

To use with Claude Code, copy the skill to your .claude/skills/ directory.


🔧 Configuration Deep-Dive

Scoring Rules

RuleBehavior
standardFull score only if exactly matching the answer key
partial_penaltyMulti-select: partial credit for partially correct answers, penalty for wrong selections

Recognition Modes

ModeSortingUse Case
ANatural sequential orderMost standard answer sheets
BColumn-priority orderColumn-based layouts

Layout

LayoutMeaning
rowEach question occupies one row (A B C D horizontally)
columnEach question occupies one column (A B C D vertically)

Supported LLM Models

Via SiliconFlow API (or any OpenAI-compatible endpoint):

  • Qwen/Qwen3-VL-30B-A3B-Instruct (recommended, cost-effective)
  • Qwen/Qwen3-VL-8B-Instruct
  • Qwen/Qwen3-VL-32B-Instruct
  • Qwen/Qwen3-VL-235B-A22B-Instruct (best quality)
  • zai-org/GLM-4.6V
  • And more — edit available_models in config.json

📊 Requirements

python >= 3.8
torch >= 1.7
opencv-python >= 4.5
pandas
openpyxl
Pillow
numpy
openai >= 1.0
pyzbar          # optional, for barcode

Full list: runtime/requirements-runtime.txt


⚠️ Limitations & Notes

  • GPU recommended for batch processing — CPU mode is functional but slower (YOLO inference on CPU ~120ms/image).
  • Subjective grading quality depends on the LLM model used. For high-stakes exams, human review is still recommended.
  • Answer sheet layout must be consistent with the YOLO model's training data. Custom layouts may require fine-tuning best.pt.
  • Student info recognition requires a multimodal LLM with vision capabilities and an internet connection (API call).
  • Barcode recognition depends on OpenCV's barcode_BarcodeDetector (OpenCV 4.8+) or pyzbar.

🤝 Contributing

Issues and pull requests are welcome. Areas that particularly need contributions:

  • YOLO model training pipeline for custom answer sheet layouts
  • Support for more answer sheet formats
  • Web UI / GUI improvements
  • Additional LLM provider integrations

📄 License

[Specify your license here — e.g., MIT, Apache 2.0, GPL]


🙏 Acknowledgements

  • Ultralytics YOLOv5 for the object detection backbone
  • SiliconFlow for multimodal LLM API access
  • OpenCV & pyzbar for image processing and barcode decoding
Ver o original no GitHub

Bom para

Relacionados