How cphos/ai_scoring works
CPHOS AI is a command-line handwritten physics-answer transcription and grading system. Its principal workflow accepts answer images or PDFs and a TeX rubric, then runs a mode-specific pipeline: recognize transcribes handwriting, judge parses the rubric and scores a transcription, while direct scores images without an intermediate transcription. Results are rendered as Markdown; batch modes also summarize per-file outcomes. The README documents these capabilities, while sampled handlers confirm pipeline dispatch and model calls; unsampled subsystem wiring is shown only where documented.
Main entry points: handlers.py Stage Handlers · pipeline.py Mode Pipeline · openrouter.py OpenRouter Client · cli.py Command Router
Components 24
CLI and Pipeline
- Command Router
src/app/cli.py - Mode Pipeline
src/pipeline/pipeline.py - Stage Handlers
src/pipeline/handlers.py - Pipeline Context
src/pipeline/context.py - Mode Transitions
src/pipeline/states.py
Recognition
- Recognition Service
src/recognize/service.py - Image/PDF Loading
src/recognize/input_processing.py - Transcription Prompt
src/recognize/prompt_builder.py - Recognition Template
src/prompts/recognize.yaml - Transcription Result
src/recognize/output.py
Rubric and Grading
- Grading Service
src/judge/service.py - Rubric Parser
src/judge/answer_parser.py - Scoring Rubric
src/judge/types.py - Scoring Prompt
src/judge/prompt_builder.py - Judge Template
src/prompts/judge.yaml - Score Response Parser
src/judge/response_parser.py - Scoring Result
src/judge/output.py
Model Services
- Model Settings
src/config/settings.py - OpenRouter Client
src/client/openrouter.py
Other components
- CLI User
- Answer Images/PDFs
- TeX Answer Key
- OpenRouter API
- Markdown Results
Connections 27
- CLI User → Command Router: invokes
- Command Router → Recognition Service: dispatches
- Command Router → Grading Service: dispatches
- Recognition Service → Mode Pipeline: runs mode
- Grading Service → Mode Pipeline: runs mode
- Mode Pipeline → Stage Handlers: dispatches stages
- Mode Pipeline → Mode Transitions: selects transitions
- Mode Pipeline → Pipeline Context: updates state
- Answer Images/PDFs → Image/PDF Loading: supplies files
- Stage Handlers → Image/PDF Loading: loads inputs
- Stage Handlers → Transcription Prompt: builds prompt
- Recognition Template → Transcription Prompt: provides template
- Stage Handlers → OpenRouter Client: requests transcription
- Stage Handlers → Rubric Parser: parses rubric
- TeX Answer Key → Rubric Parser: supplies TeX
- Rubric Parser → Scoring Rubric: produces rubric
- Stage Handlers → Scoring Prompt: builds scoring prompt
- Judge Template → Scoring Prompt: provides template
- Stage Handlers → OpenRouter Client: requests scoring
- OpenRouter Client → Model Settings: uses configuration
- OpenRouter Client → OpenRouter API: sends requests
- OpenRouter API → OpenRouter Client: returns responses
- Stage Handlers → Score Response Parser: parses scores
- Stage Handlers → Transcription Result: creates transcription
- Stage Handlers → Scoring Result: creates scores
- Recognition Service → Markdown Results: renders transcription
- Grading Service → Markdown Results: renders scores