Skip to content

Classification API Reference

The v2 multi-agent classification system provides comprehensive metadata extraction through 7 specialized agents.

System Overview

The classification pipeline supports multiple input modalities:

  • Image → Agent 1 (Image Classifier)
  • LaTeX → Agent 4 (LaTeX Classifier)
  • Idea/Concept → Agent 5 (Idea Generator)
  • Multiple Problems → Agent 6 (Problem Combiner)

Additional agents provide: - Agent 2 - Diagram analysis (hierarchical categorization) - Agent 3 - Difficulty assessment (post-scan, detailed metadata) - Agent 7 - TikZ validation (automatic fixing)

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_from_image,
    analyze_diagram,
    assess_difficulty,
    validate_tikz,
)

# Agent 1: Classify from image
classification = classify_from_image("question.png")

# Agent 2: Analyze diagram (if has_diagram)
if classification.has_diagram:
    diagram = analyze_diagram("question.png", classification)

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

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

Auto-Generated API Documentation

Pipeline Orchestrator

pipeline

Classification pipeline orchestrator.

Coordinates multiple specialized agents for comprehensive classification.

ClassificationPipeline 

ClassificationPipeline()

Orchestrates multi-agent classification pipeline.

Supports multiple input modalities: - image: Question images - latex: LaTeX text files - idea: Generate from concepts - multi_problem: Combine multiple problems

Initialize pipeline with lazy agent loading.

diagram_analyzer property 

diagram_analyzer

Lazy load diagram analyzer

difficulty_assessor property 

difficulty_assessor

Lazy load difficulty assessor

idea_generator property 

idea_generator

Lazy load idea generator

image_classifier property 

image_classifier

Lazy load image classifier

latex_classifier property 

latex_classifier

Lazy load LaTeX classifier

problem_combiner property 

problem_combiner

Lazy load problem combiner

tikz_checker property 

tikz_checker

Lazy load TikZ checker

analyze_diagram 

analyze_diagram(image_path: Optional[str], latex_content: Optional[str], primary: PrimaryClassification) -> Optional[DiagramAnalysis]

Step 2: Analyze diagram (Agent 2) - Conditional

assess_difficulty 

assess_difficulty(image_path: Optional[str], latex_content: str, primary: PrimaryClassification, diagram: Optional[DiagramAnalysis], tikz_code: Optional[str] = None) -> DifficultyAssessment

Step 3: Assess difficulty (Agent 3) - After scan

classify_from_image 

classify_from_image(image_path: str, subject: Optional[str] = None) -> PrimaryClassification

Step 1: Classify from image (Agent 1)

classify_from_latex 

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

Step 1: Classify from LaTeX (Agent 4)

process 

process(input_data: str, input_type: Literal['image', 'latex', 'idea', 'multi_problem'] = 'image', subject: Optional[str] = None, latex_content: Optional[str] = None, tikz_code: Optional[str] = None) -> ClassificationResult

Complete classification pipeline.

Parameters:

Name Type Description Default
input_data str

Path to image/latex file, or data for generation

 required
input_type Literal['image', 'latex', 'idea', 'multi_problem']

Type of input

 'image'
subject Optional[str]

Subject override

 None
latex_content Optional[str]

LaTeX content (for difficulty assessment)

 None
tikz_code Optional[str]

TikZ code (for difficulty assessment)

 None

Returns:

Type Description
ClassificationResult

Complete ClassificationResult

validate_tikz_code 

validate_tikz_code(tikz_code: str, context: Optional[str] = None, auto_fix: bool = True)

Validate and fix TikZ code (Agent 7)

get_pipeline 

get_pipeline() -> ClassificationPipeline

Get global pipeline instance

Agent 1: Image Classifier

image_classifier

Agent 1: Enhanced Image Classifier.

Classifies question images without difficulty assessment. Difficulty is assessed later by Agent 3 after LaTeX extraction.

classify_from_image 

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

Classify question from image (Agent 1).

Parameters:

Name Type Description Default
image_path str

Path to question image

 required
subject Optional[str]

Subject override

 None
show_spinner bool

Whether to show animated spinner

 True

Returns:

Type Description
PrimaryClassification

PrimaryClassification without difficulty

create_image_classifier_agent 

create_image_classifier_agent(subject: Optional[str] = None)

Create enhanced image classifier agent.

Agent 2: Diagram Analyzer

diagram_analyzer

Agent 2: Diagram Analyzer.

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

analyze_diagram 

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

Analyze diagram in detail (Agent 2).

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

analyze_diagram_from_description 

analyze_diagram_from_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_analyzer_agent 

create_diagram_analyzer_agent(subject: Optional[str] = None)

Create diagram analyzer agent.

Agent 3: Difficulty Assessor

difficulty_assessor

Agent 3: 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) -> DifficultyAssessment

Assess difficulty after LaTeX extraction (Agent 3).

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

Returns:

Type Description
DifficultyAssessment

DifficultyAssessment with detailed metadata

create_difficulty_assessor_agent 

create_difficulty_assessor_agent(subject: Optional[str] = None)

Create difficulty assessor agent.

Agent 4: LaTeX Classifier

latex_classifier

Agent 4: LaTeX Classifier.

Classifies questions from LaTeX text for batch processing.

classify_from_latex 

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

Classify question from LaTeX (Agent 4).

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.

Agent 5: Idea Generator

idea_generator

Agent 5: 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) -> GeneratedProblem

Generate problem from ideas (Agent 5).

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

Returns:

Type Description
GeneratedProblem

GeneratedProblem with complete content

create_idea_generator_agent 

create_idea_generator_agent(subject: Optional[str] = None)

Create idea generator agent.

Agent 6: Problem Combiner

problem_combiner

Agent 6: Multi-Problem Combiner.

Combines multiple problems into a single comprehensive problem. Supports cross-subject combinations (physics + chemistry).

combine_problems 

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

Combine multiple problems (Agent 6).

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.

Agent 7: TikZ Checker

tikz_checker

Agent 7: TikZ Checker/Validator.

Validates and fixes TikZ code automatically. Ensures compilation success and best practices.

validate_tikz 

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

Validate and fix TikZ code (Agent 7).

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()

Create TikZ checker agent.