Eve library

25.1.1.6 — Minerva Quality Control Linters

Guide

Revision 1

On this page

Source: oshun/minerva/minerva/linters/ (63 files, 19,702 LOC) Analysis date: 2026-02-28 Purpose: Document linter framework, finding types, integration for @metis/linters-types


Overview#

  • Total linters: 50+ specialized linters
  • Total files: 63
  • Total LOC: 19,702
  • Framework: BaseLinter abstract class with async generator pattern
  • Integration: StatefulLinterManager for persistent generator state
  • Types: 60% programmatic, 30% LLM-based, 10% specialized analysis

Linter Framework#

BaseLinter (34 LOC)#

python
class BaseLinter(ABC):
    @abstractmethod
    async def lint(self, course: Course) -> AsyncGenerator[LinterFinding, None]:
        """Analyzes course content and yields findings."""

StatefulLinterManager (322 LOC)#

Solves critical bug: original CritiqueAgent created fresh instances per call, only accessing first finding.

Key features:

  • Persistent async generators (resume from last position)
  • Deterministic ordering (sorted by name, PlaceholderLinter & TitleQualityLinter preferred)
  • Category filtering for finding types
  • Quota/cooldown support via exclusions
  • Exhaustion tracking per linter
  • Recoverable exception handling

Methods: register_linter(), get_next_finding(), reset_linter(), exclude_linter(), get_status()

Finding Model#

Field Type Description
finding_type string e.g. "PLACEHOLDER_TEXT_FOUND"
message string Human-readable issue
description string? Detailed explanation
target_ids string[] Affected element IDs
topic_id string? Parent topic for routing
category FindingCategory 13-value enum
severity "LOW"|"MEDIUM"|"HIGH"|"CRITICAL"
linter_name string? Provenance

Linter Taxonomy#

STEM Accuracy (Domain-Specific)#

Linter LOC Type What it checks
lean_chemistry_linter 976 Analysis Chemical equations, reactions, balancing
scientific_consistency_linter 888 Analysis Cross-domain scientific consistency
lean_math_linter 866 Analysis Mathematical expressions, proofs
mathematical_accuracy_linter 743 Analysis SymPy + numeric verification (3 depth levels)
proof_pedagogy_linter 703 LLM Mathematical proof instruction quality
physics_accuracy_linter 700 Analysis Physics concepts, formulas, units
chemistry_accuracy_linter 656 Analysis Chemistry content accuracy
stem_consistency_linter 524 LLM STEM concept coherence across topics

Assessment Quality#

Linter LOC Type What it checks
quiz_quality_linter 492 LLM Overall quiz design quality
quiz_answer_accuracy_linter 468 LLM Answer correctness and explanation quality
quiz_linter 447 LLM Quiz structure and question diversity
quiz_feedback_quality_linter 271 LLM Feedback helpfulness and specificity
quiz_richness_linter 211 Programmatic Quiz coverage and variety
quiz_media_compliance_linter 101 Programmatic Media requirements in quizzes

Content & Pedagogy#

Linter LOC Type What it checks
reading_level_linter 657 Analysis Flesch-Kincaid, SMOG, Lexile readability
age_appropriateness_linter 632 Analysis COPPA compliance, grade-level content
bias_and_fairness_linter 449 LLM Implicit bias, representation, stereotypes
semantic_linter 409 LLM Semantic accuracy and coherence
fact_checking_linter 382 LLM+RAG Claim extraction + RAG verification
content_linter 330 LLM General content quality
difficulty_progression_linter 326 Programmatic Cognitive load progression
engagement_linter 325 LLM Student engagement factors
placeholder_linter 297 Programmatic Generic/stub placeholder text
terminology_linter 294 LLM Consistent terminology usage
lesson_richness_linter 279 Programmatic Example variety, section detail
learning_objective_linter 271 LLM Bloom's taxonomy alignment
title_quality_linter 242 Programmatic Descriptive, non-generic titles
pedagogical_linter 202 LLM Teaching best practices

Multimedia & Accessibility#

Linter LOC Type What it checks
wcag_accessibility_linter 366 Analysis WCAG 2.1 AA compliance
multimedia_quality_linter 325 Programmatic Template detection, content presence
media_timestamp_alignment_linter 318 Programmatic Audio-visual sync timing
multi_modal_linter 274 Programmatic Cross-modal consistency
image_accessibility_linter 257 Programmatic Alt text, captions
media_audio_description_linter 224 Programmatic Audio description presence
media_caption_language_linter 202 Programmatic Caption quality and language
media_transcript_linter 152 Programmatic Transcript availability
diagram_data_quality_linter 105 Programmatic Diagram data integrity

Curriculum & Structure#

Linter LOC Type What it checks
concept_graph_linter 399 Analysis Ontological consistency
course_linter 379 LLM Course-level structure quality
syllabus_alignment_linter 367 LLM Alignment with curriculum standards
curriculum_editor_linter 304 Programmatic Editor compliance rules
prerequisite_linter 199 Programmatic Prerequisite validation
scaffolding_linter 174 Programmatic Learning scaffolding presence
syllabus_linter 122 Programmatic Syllabus format compliance

Policy & Compliance#

Linter LOC Type What it checks
plagiarism_license_linter 286 Analysis Content originality, licensing
ghana_policy_compliance_linter 238 Programmatic Ghana education standards
bece_format_linter 157 Programmatic BECE exam format
book_v2_compliance_linter 133 Programmatic Book format standards

Text & Language#

Linter LOC Type What it checks
clarity_linter 70 Programmatic Sentence complexity
acronym_linter 130 Programmatic Acronym definitions
citation_requirement_linter 116 Programmatic Citation presence
citation_needed_linter 54 Programmatic Missing citations

Other#

Linter LOC Type What it checks
cognitive_load_linter 153 Analysis Cognitive load estimation
code_block_linter 149 Programmatic Code example quality
ontological_validation_linter 121 Analysis Knowledge structure validity
content_balance_linter 85 Programmatic Content distribution
topic_depth_linter 92 Programmatic Topic coverage depth
graph_schema_linter 74 Programmatic Graph structure validity
rich_media_majority_linter 69 Programmatic Media presence threshold

Integration: CritiqueAgent → StatefulLinterManager#

text
CritiqueAgent
  ↓
StatefulLinterManager.register_linter(PlaceholderLinter, ...)
StatefulLinterManager.register_linter(QuizLinter, ...)
StatefulLinterManager.register_linter(...50+ more...)
  ↓
Loop:
  finding = await manager.get_next_finding(
    excluded_linters={...},     # quota exhausted
    allowed_linters=None,       # or whitelist
    target_category=None        # or filter
  )
  ↓
  if finding: route to appropriate agent for fix
  if None: all linters exhausted → done

Mathematical Verification (Deep Analysis)#

MathematicalAccuracyLinter Verification Depths#

Depth Tools What it does
QUICK Pattern matching Basic arithmetic, syntax checks
STANDARD SymPy + numeric Symbolic computation, numerical verification
DEEP + SageMath Full proof checking, advanced algebra

Domain Detection#

Arithmetic, Algebra, Calculus, Logic, Set Theory, Linear Algebra, Statistics


Features to KEEP#

  1. StatefulLinterManager — Elegant state tracking, solves critical first-finding-only bug
  2. Async generator pattern — Memory-efficient streaming of findings
  3. MathematicalAccuracyLinter — Multi-layer SymPy + numeric verification
  4. ReadingLevelLinter — Flesch-Kincaid, SMOG, Lexile formulas
  5. WCAGAccessibilityLinter — WCAG 2.1 AA compliance
  6. FactCheckingLinter — RAG-enhanced with fallback
  7. AgeAppropriatenessLinter — COPPA-aware grade-level analysis
  8. BiasAndFairnessLinter — Implicit bias detection for edtech
  9. Recoverable exception handling — Graceful degradation
  10. Deterministic ordering — Priority-based linter execution

Technical Debt to DISCARD#

  1. Ghana-hardcoded linters — Parameterize to locale config
  2. Redundant quiz linters — 6 quiz linters with overlap
  3. Lazy loading via __getattr__ — Replace with explicit registry
  4. No severity/priority system — Linters have no execution priority
  5. No composition/chaining — Can't compose linters into pipelines
  6. Hardcoded rules — Many linters embed rules in code instead of config
  7. LLM call inefficiency — Each LLM linter makes separate calls instead of batching