Classification API Reference

The classification system provides one canonical image classifier plus specialized LaTeX, diagram, taxonomy, and difficulty classifiers.

System Overview

The classification pipeline supports multiple input modalities:

Image → Question Classifier
LaTeX → LaTeX Classifier
Diagram descriptions → Diagram Classifier

Problem generation and combination live under agents.content_generation; they are not classification agents.

Key Features

✅ Multiple input modalities
✅ Hierarchical diagram classification
✅ Detailed difficulty assessment (reasoning, time, prerequisites, mistakes)
✅ Automatic TikZ validation with error fixing
✅ Specialized TikZ agent routing
✅ Bloom's taxonomy cognitive levels
✅ Cross-subject problem combination

Usage Example

from vbagent.agents.classification import (
    classify_primary_image,
    classify_diagram_image,
    assess_difficulty,
    validate_tikz,
)

# Classify from image
classification = classify_primary_image("question.png")

# Classify the diagram separately when needed
if classification.has_diagram:
    diagram = classify_diagram_image("question.png", classification)

# Assess difficulty after scanning
difficulty = assess_difficulty(latex_content, classification, diagram)

# Validate TikZ
validation = validate_tikz(tikz_code, auto_fix=True)

Auto-Generated API Documentation

Question Classifier

question_classifier

Two-stage question routing and subject-specific image analysis.

classify_question_image

classify_question_image(image_path: str, subject: Optional[str] = None, show_spinner: bool = True, routing: Optional[QuestionRoutingClassification] = None) -> QuestionClassification

Route an image, then perform its subject-specific detailed analysis.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to question image	required
`subject`	`Optional[str]`	Optional explicit subject override.	`None`
`show_spinner`	`bool`	Whether to show spinner	`True`
`routing`	`Optional[QuestionRoutingClassification]`	Optional cached first-pass result.	`None`

Returns:

Type	Description
`QuestionClassification`	Complete question classification and diagram data

classify_primary_image

classify_primary_image(image_path: str, subject: Optional[str] = None, show_spinner: bool = True) -> PrimaryClassification

Classify an image and return only the compact primary view.

create_question_classifier

create_question_classifier(subject: str = 'physics')

Create the detailed subject-specific second-pass analyzer.

Diagram Classifier

diagram_classifier

Standalone diagram classifier.

Analyzes diagrams in detail and determines TikZ requirements. Routes to specialized TikZ agents based on diagram type.

classify_diagram_image

classify_diagram_image(image_path: str, primary: PrimaryClassification, subject: Optional[str] = None, show_spinner: bool = True) -> DiagramAnalysis

Classify a diagram directly from a question image.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to question image	required
`primary`	`PrimaryClassification`	Primary classification result	required
`subject`	`Optional[str]`	Subject override	`None`
`show_spinner`	`bool`	Whether to show animated spinner	`True`

Returns:

Type	Description
`DiagramAnalysis`	DiagramAnalysis with TikZ requirements

classify_diagram_description

classify_diagram_description(description: str, primary: PrimaryClassification, subject: Optional[str] = None) -> DiagramAnalysis

Analyze diagram from text description (for generated problems).

Parameters:

Name	Type	Description	Default
`description`	`str`	Text description of the diagram	required
`primary`	`PrimaryClassification`	Primary classification result	required
`subject`	`Optional[str]`	Subject override	`None`

Returns:

Type	Description
`DiagramAnalysis`	DiagramAnalysis with TikZ requirements

create_diagram_classifier

create_diagram_classifier(subject: Optional[str] = None)

Create the standalone diagram classifier.

Difficulty Assessor

difficulty_assessor

Post-solution difficulty assessor.

Assesses difficulty AFTER LaTeX extraction and TikZ generation. Provides detailed reasoning and metadata.

assess_difficulty

assess_difficulty(latex_content: str, primary: PrimaryClassification, diagram: Optional[DiagramAnalysis] = None, tikz_code: Optional[str] = None, subject: Optional[str] = None, show_spinner: bool = True, exam: Optional[str] = None, exam_pattern_description: Optional[str] = None, target_difficulty_score: Optional[int] = None) -> DifficultyAssessment

Assess difficulty after LaTeX extraction.

Parameters:

Name	Type	Description	Default
`latex_content`	`str`	Extracted LaTeX content	required
`primary`	`PrimaryClassification`	Primary classification	required
`diagram`	`Optional[DiagramAnalysis]`	Diagram analysis (if available)	`None`
`tikz_code`	`Optional[str]`	Generated TikZ code (if available)	`None`
`subject`	`Optional[str]`	Subject override	`None`
`show_spinner`	`bool`	Whether to show animated spinner	`True`
`exam`	`Optional[str]`	Target exam used as the student-population calibration baseline	`None`
`exam_pattern_description`	`Optional[str]`	Versioned response-format rule for that exam	`None`
`target_difficulty_score`	`Optional[int]`	Requested score, supplied only as a comparison target	`None`

Returns:

Type	Description
`DifficultyAssessment`	DifficultyAssessment with detailed metadata

create_difficulty_assessor_agent

create_difficulty_assessor_agent(subject: Optional[str] = None)

Create difficulty assessor agent.

LaTeX Classifier

latex_classifier

LaTeX question classifier.

Classifies questions from LaTeX text for batch processing.

classify_from_latex

classify_from_latex(latex_content: str, subject: Optional[str] = None) -> PrimaryClassification

Classify a question from LaTeX.

Parameters:

Name	Type	Description	Default
`latex_content`	`str`	LaTeX content to classify	required
`subject`	`Optional[str]`	Subject override	`None`

Returns:

Type	Description
`PrimaryClassification`	PrimaryClassification without difficulty

create_latex_classifier_agent

create_latex_classifier_agent(subject: Optional[str] = None)

Create LaTeX classifier agent.

Idea Generator

idea_generator

Idea-to-problem generator.

Generates complete problems from physics/chemistry ideas and concepts.

generate_from_idea

generate_from_idea(ideas: List[str], concepts: List[str], topic: str, difficulty: str = 'medium', question_type: str = 'mcq_sc', subject: Optional[str] = None, exam: Optional[str] = None, exam_pattern_description: Optional[str] = None, chapter: Optional[str] = None, chapter_description: Optional[str] = None, syllabus_topic: Optional[str] = None, syllabus_topic_description: Optional[str] = None, difficulty_score: Optional[int] = None, cognitive_level: Optional[str] = None, reasoning_lens: Optional[str] = None, representation: Optional[str] = None, construction_family: Optional[str] = None, diagram_policy: Optional[str] = None, forbidden_concepts: Optional[List[str]] = None, tone: Optional[str] = None, random_seed: Optional[int] = None, retry_feedback: Optional[str] = None, passage_question_count: Optional[int] = None, include_solution: bool = True, include_idea: bool = True) -> GeneratedProblem

Generate a problem from ideas.

Parameters:

Name	Type	Description	Default
`ideas`	`List[str]`	List of physics/chemistry ideas	required
`concepts`	`List[str]`	List of concepts to cover	required
`topic`	`str`	Topic for the problem	required
`difficulty`	`str`	Target difficulty	`'medium'`
`question_type`	`str`	Target question type	`'mcq_sc'`
`subject`	`Optional[str]`	Subject override	`None`
`exam`	`Optional[str]`	Exact target exam, when authoring from a syllabus	`None`
`exam_pattern_description`	`Optional[str]`	Versioned response-format rule for the target exam	`None`
`chapter`	`Optional[str]`	Exact target syllabus chapter	`None`
`chapter_description`	`Optional[str]`	Official/custom chapter scope statement	`None`
`syllabus_topic`	`Optional[str]`	Exact target syllabus topic statement	`None`
`syllabus_topic_description`	`Optional[str]`	Additional official/custom topic scope	`None`
`difficulty_score`	`Optional[int]`	Anchored 1-10 target difficulty	`None`
`cognitive_level`	`Optional[str]`	Requested cognitive operation	`None`
`reasoning_lens`	`Optional[str]`	Requested solution/construction lens	`None`
`representation`	`Optional[str]`	Requested problem representation	`None`
`construction_family`	`Optional[str]`	Requested construction family	`None`
`diagram_policy`	`Optional[str]`	required, optional, or forbidden	`None`
`forbidden_concepts`	`Optional[List[str]]`	Concepts that must not enter the problem	`None`
`tone`	`Optional[str]`	Optional authoring tone instruction	`None`
`random_seed`	`Optional[int]`	Stable creative seed from the immutable item specification	`None`
`retry_feedback`	`Optional[str]`	Evidence from a prior rejected attempt that must be corrected	`None`
`passage_question_count`	`Optional[int]`	Exact number of passage subquestions when applicable	`None`
`include_solution`	`bool`	Whether to generate the solution component now	`True`
`include_idea`	`bool`	Whether to generate an idea component	`True`

Returns:

Type	Description
`GeneratedProblem`	GeneratedProblem with complete content

create_idea_generator_agent

create_idea_generator_agent(subject: Optional[str] = None)

Create idea generator agent.

Problem Combiner

problem_combiner

Multi-problem combiner.

Combines multiple problems into a single comprehensive problem.

combine_problems

combine_problems(problems: List[Dict[str, str]], strategy: str = 'sequential', target_difficulty: str = 'hard', cross_subject: bool = False) -> CombinedProblem

Combine multiple problems.

Parameters:

Name	Type	Description	Default
`problems`	`List[Dict[str, str]]`	List of problem dicts with keys: id, latex, solution, subject, topic	required
`strategy`	`str`	Combination strategy (sequential, parallel, nested)	`'sequential'`
`target_difficulty`	`str`	Target difficulty for combined problem	`'hard'`
`cross_subject`	`bool`	Whether to combine across subjects	`False`

Returns:

Type	Description
`CombinedProblem`	CombinedProblem with integrated content

create_problem_combiner_agent

create_problem_combiner_agent()

Create problem combiner agent.

TikZ Checker

tikz_checker

TikZ checker agent for LaTeX diagrams.

Checks TikZ/PGF code for syntax errors, best practices, and physics diagram conventions.

Supports two modes: 1. Legacy mode: Returns full corrected content (check_tikz) 2. Patch mode: Uses apply_patch tool for structured diffs (check_tikz_with_patch)

validate_tikz

validate_tikz(tikz_code: str, context: Optional[str] = None, auto_fix: bool = True, compile_test: bool = True, cache_group_id: Optional[str] = None) -> TikZValidation

Validate and fix TikZ code, returning structured TikZValidation.

Parameters:

Name	Type	Description	Default
`tikz_code`	`str`	TikZ code to validate	required
`context`	`Optional[str]`	Optional context (problem description, diagram type)	`None`
`auto_fix`	`bool`	Whether to automatically apply fixes	`True`
`compile_test`	`bool`	Whether to test compilation	`True`

Returns:

Type	Description
`TikZValidation`	TikZValidation with errors, fixes, and corrected code

create_tikz_checker_agent

create_tikz_checker_agent(use_context: bool = True, classification: ClassificationResult | None = None, diagram_type: Optional[str] = None) -> Any

Create a TikZ checker agent with optional reference context.

Parameters:

Name	Type	Description	Default
`use_context`	`bool`	Whether to include reference context	`True`
`classification`	`ClassificationResult \| None`	Optional ClassificationResult for metadata matching	`None`
`diagram_type`	`Optional[str]`	Optional filter by diagram type (e.g., 'circuit')	`None`

Returns:

Type	Description
`Any`	Configured Agent instance