How ikora128/nmle-rta works
Based on our analysis of the provided file structure and README, the project is a full-stack system specifically designed for processing National Medical License Examination questions. Its main purpose is to take scanned exam papers—perform OCR extraction, text cleaning, JSON conversion, and then leverage several AI/LLM models (e.g., gpt-4o, claude, o1, and deepseek) to generate answers. Finally, the output is aggregated and can be converted into CSV format for further review.
Main Components Identification
• OCR / PDF Processing Module: Represent the components such as “pdf2txt.py” which extract text from PDFs (the main input files are stored under the data directory). Also include “cleaning_ocr_txt.py” which refines the raw OCR output.
• JSON & Text Processing Module: Indicate how the cleaned text is then transformed into structured JSON using “txt2json.py.”
• AI/LLM Solver Module: Show the core answer generation system using “main.py”, “llm_solver.py”, and “process_llm_output.py”. This part wraps and coordinates multiple AI models (o1, gpt-4o, o3-mini, claude, gemini, deepseek).
• Output Management Module: Illustrate how the output is stored. This includes JSON results in “answer/json” and raw outputs in “answer/raw”. Also include the conversion tools (“json_to_csv_converter.py” and “convert_json_to_csv.py”) to produce CSV files.
• Supporting Utilities and Scripts: Include directories like “scripts” (e.g., extract_question_info.py, structured_and_solve.py, test_model_parameters.py) that support the overall flow.
• Data & Assets: Model storage of input resource files like exam PDFs (data/), images (images/), and fonts (fonts/).
Relationships and Data/Control Flow
• Move to the cleaning and reformatting stage (“cleaning_ocr_txt.py”) converting OCR text to a standardized exam question format.
• Next, the conversion from cleaned text to structured JSON using “txt2json.py” provides a bridge to automated AI-powered analysis.
• If the questions include images, outline an additional branch that processes image files from the “images” directory and maps them to the appropriate question identifiers.
Architectural Patterns and Design Principles
• The project follows a modular, multi-stage pipeline architecture (OCR → text cleaning → JSON conversion → AI answer generation → results aggregation).
• There is a clear separation between data ingestion/processing and AI/model orchestration, which is essential for maintainability and extension.
• Since multiple AI models are deployed, the design encourages flexibility, allowing new models to be added or existing ones replaced without affecting the rest of the pipeline.
Relevant Technologies and Tools
• Python (core language for the scripts)
• uv (package manager) for dependency synchronization and script execution
• API integrations for various AI models (e.g., OpenAI, Anthropic, DeepSeek, Gemini, Azure Document Intelligence)
• Tailwind, Next.js, and TypeScript configuration files within the “nmle-checker” subdirectory suggest a separate front-end or administrative component.
Elements
• A block for “Data Ingestion and OCR” containing pdf2txt.py, cleaning_ocr_txt.py, and input/output directories (data/, output/).
• A block for “Question Structuring” that houses txt2json.py and its flow.
• A block for “AI Answer Generation” representing main.py, llm_solver.py, process_llm_output.py. Connect these with annotations noting the use of multiple AI models (list them out).
• A block for “Result Aggregation and Conversion” showing json_to_csv_converter.py, convert_json_to_csv.py, and the answer storage directories.
• A separate or connected block for “Front-End / Dashboard” (nmle-checker) illustrating files hosted under a Next.js structure (src/app, public, etc.).