Getting Started

Installation

pip install mathipy

With optional dependencies:

# Readability analysis (textstat, nltk)
pip install mathipy[nlp]

# Visual analysis (opencv, pillow)
pip install mathipy[vision]

# OCR via vision LLMs (httpx)
pip install mathipy[ocr]

# Document parsing (python-docx, pdfplumber)
pip install mathipy[documents]

# All features
pip install mathipy[all]

From GitHub:

pip install git+https://github.com/mshin77/mathipy.git[all]

Basic Usage

Readability Analysis

from mathipy import ReadabilityAnalyzer

analyzer = ReadabilityAnalyzer()
result = analyzer.analyze("Solve for x: 2x + 5 = 15. What is the value of x?")

print(f"Grade Level: {result['flesch_kincaid_grade']:.1f}")
print(f"Reading Ease: {result['flesch_reading_ease']:.1f}")

Math Content Analysis

from mathipy import MathContentAnalyzer

analyzer = MathContentAnalyzer()
result = analyzer.analyze("Solve 2x + 5 = 15 for x")

print(f"Domain: {result['domain_classification']['primary']}")
print(f"Math density: {result['math_density']:.2f}")

Cognitive Load Estimation

from mathipy import CognitiveLoadEstimator

estimator = CognitiveLoadEstimator()
result = estimator.estimate("Solve 2x + 5 = 15 for x")

print(f"Element density: {result['element_density']:.2f}")
print(f"Operations: {result['operation_count']}")

Visual Feature Extraction

from mathipy import VisualFeatureExtractor

extractor = VisualFeatureExtractor()
features = extractor.extract("math_problem.png")

print(f"Edge ratio: {features['complexity_score']['edge_ratio']:.3f}")
print(f"Shapes found: {features['structural_elements']['total_shapes']}")

Multimodal OCR

Requires a GEMINI_API_KEY or OPENAI_API_KEY in your .env file.

from mathipy import MultimodalOCR

ocr = MultimodalOCR(provider="gemini")
result = ocr.extract("math_problem.png")

print(result["full_text"])
print(result["math_expressions"])

Visual Model Classification

Assigns each image one flag per representation type, a primary type, and an instructional function label. Requires the same API key as OCR.

OCR and classification transmit image data to the configured provider; every other analyzer runs locally. Before sending secure or restricted assessment content, read the Data Handling section of the API Reference — free and paid API tiers carry different terms about whether submitted content is retained and used for model training.

from mathipy import VisualModelClassifier

classifier = VisualModelClassifier(provider="gemini")
result = classifier.classify("math_problem.png")

print(result["primary"])   # e.g. "circle_graph"
print(result["function"])  # "essential", "representational", or "decorative"

Twenty-six types is more granularity than most models can absorb, and several types are rare in any single corpus. Collapse them into six representation families for analysis while keeping the per-type flags for description:

from mathipy import flags_by_group

print(flags_by_group(result))
# {'visual_group_data_display': 1, 'visual_group_geometric': 0, ...}

Repeated calls can be merged to reduce single-call variability. Flags merge by majority, the primary type and function label by mode:

result = classifier.classify("math_problem.png", votes=3)

Pass the item’s text so the function judgment can compare the image against it; without it, essential vs representational is reliable only when the image shows the complete item:

result = classifier.classify("math_problem.png", item_text="A store sells...")

The decision rule behind every type label is available as a dictionary — the classifier prompt and any human coding of the same images can share it:

from mathipy import visual_model_definitions

Certificate Errors on Vision Calls

Antivirus HTTPS scanning and corporate proxies intercept TLS and re-sign traffic with a root certificate that Python’s bundled certificate list does not carry, producing CERTIFICATE_VERIFY_FAILED on the first OCR or classification call. Point Python at the operating system’s certificate store instead:

pip install truststore

import truststore
truststore.inject_into_ssl()

Call inject_into_ssl() once at program start, before creating any client. Certificates are still fully verified; only the source of the trusted roots changes.