Agents API Reference

Complete API documentation for VBAgent's multi-agent system.

Quick Links

Classification System - 7-agent pipeline for metadata extraction
Data Models - Pydantic models for all data structures
CLI Functions - Command-line interface modules
Orchestrator - Tool wrappers and orchestration

Agent Architecture

VBAgent uses a multi-agent architecture with specialized agents for different tasks:

Classification Agents (v2)

Advanced 7-agent system for comprehensive metadata extraction:

Image Classifier - Classify questions from images
Diagram Analyzer - Hierarchical diagram categorization
Difficulty Assessor - Post-scan difficulty with detailed metadata
LaTeX Classifier - Batch processing of LaTeX files
Idea Generator - Generate problems from concepts
Problem Combiner - Combine multiple problems
TikZ Checker - Validate and fix TikZ code

Core Processing Agents

Main workflow agents:

Scanner - Extract LaTeX from images
TikZ Generator - Generate TikZ diagrams
Variant Generator - Create problem variants
Alternate Solutions - Generate alternative solutions
Idea Extraction - Extract physics concepts

Quality Assurance Agents

Review and validation:

Reviewer - Comprehensive QA review
Solution Checker - Verify solution correctness
Grammar Checker - Check grammar and style
Clarity Checker - Assess clarity and readability

Classification Agents (v2 Multi-Agent System)

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.

Core Agents

Base Agent Functions

base

Base agent utilities using OpenAI Agents SDK.

create_agent

create_agent(name: str, instructions: str, model: Optional[str] = None, model_settings: Optional[ModelSettings] = None, output_type: Optional[type] = None, tools: Optional[list] = None, agent_type: Optional[str] = None) -> Agent

Create an agent with default configuration.

Parameters:

Name	Type	Description	Default
`name`	`str`	Agent name	required
`instructions`	`str`	System prompt / instructions	required
`model`	`Optional[str]`	Model to use (if None, uses config for agent_type)	`None`
`model_settings`	`Optional[ModelSettings]`	Optional ModelSettings for temperature, max_tokens, etc.	`None`
`output_type`	`Optional[type]`	Optional Pydantic model for structured output	`None`
`tools`	`Optional[list]`	Optional list of tools (@function_tool decorated functions)	`None`
`agent_type`	`Optional[str]`	Agent type for config lookup (classifier, scanner, tikz, etc.)	`None`

Returns:

Type	Description
`Agent`	Configured Agent instance

run_agent_sync

run_agent_sync(agent: Agent, input_text: str | list, show_spinner: bool = True) -> Any

Run an agent synchronously and return the final output.

Uses a thread to allow immediate Ctrl+C interruption.

Parameters:

Name	Type	Description	Default
`agent`	`Agent`	The Agent instance to run	required
`input_text`	`str \| list`	The input text or message (can be string or list for images)	required
`show_spinner`	`bool`	Whether to show animated spinner (default: True)	`True`

Returns:

Type	Description
`Any`	The agent's final output (string or structured type)

Raises:

Type	Description
`KeyboardInterrupt`	If user presses Ctrl+C

create_image_message

create_image_message(image_path: str, text: str) -> list[dict[str, Any]]

Create a message with image and text for the agent.

Uses the OpenAI Responses API format for image input.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to the image file	required
`text`	`str`	Text message to accompany the image	required

Returns:

Type	Description
`list[dict[str, Any]]`	List containing a single message dict in Responses API format

Classifier Agent (v1)

classifier

Classifier agent for question image classification.

Uses openai-agents SDK to analyze question images and extract structured metadata including question type, difficulty, topic, etc.

classify

classify(image_path: str, subject: Optional[str] = None) -> ClassificationResult

Analyze a question image and return structured metadata.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to the image file to classify	required
`subject`	`Optional[str]`	Subject override (uses config if not provided)	`None`

Returns:

Type	Description
`ClassificationResult`	ClassificationResult with extracted metadata (chapter auto-determined)

Raises:

Type	Description
`FileNotFoundError`	If the image file doesn't exist

create_classifier_agent

create_classifier_agent(subject: Optional[str] = None) -> Agent

Create a classifier agent for a subject.

Parameters:

Name	Type	Description	Default
`subject`	`Optional[str]`	Subject override (uses config if not provided)	`None`

Returns:

Type	Description
`Agent`	Configured Agent instance for classification

Scanner Agent

scanner

Scanner agent for extracting LaTeX from question images.

Uses openai-agents SDK to analyze question images and extract LaTeX code using type-specific and subject-specific prompts.

scan

scan(image_path: str, classification: ClassificationResult, use_context: bool = True, subject: Optional[str] = None, show_spinner: bool = True) -> ScanResult

Extract LaTeX from a question image.

Uses the classification result to select the appropriate prompt for the question type.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to the image file to scan	required
`classification`	`ClassificationResult`	Classification result with question type info	required
`use_context`	`bool`	Whether to include reference context in prompt	`True`
`subject`	`Optional[str]`	Subject override (uses config if not provided)	`None`
`show_spinner`	`bool`	Whether to show animated spinner (default: True)	`True`

Returns:

Type	Description
`ScanResult`	ScanResult with extracted LaTeX and diagram info

Raises:

Type	Description
`FileNotFoundError`	If the image file doesn't exist

scan_with_type

scan_with_type(image_path: str, question_type: str, use_context: bool = True, subject: Optional[str] = None) -> ScanResult

Extract LaTeX from a question image with explicit type.

Bypasses classification and uses the provided question type directly.

Parameters:

Name	Type	Description	Default
`image_path`	`str`	Path to the image file to scan	required
`question_type`	`str`	The type of question (mcq_sc, mcq_mc, etc.)	required
`use_context`	`bool`	Whether to include reference context in prompt	`True`
`subject`	`Optional[str]`	Subject override (uses config if not provided)	`None`

Returns:

Type	Description
`ScanResult`	ScanResult with extracted LaTeX

Raises:

Type	Description
`FileNotFoundError`	If the image file doesn't exist

create_scanner_agent

create_scanner_agent(question_type: str, use_context: bool = True, subject: Optional[str] = None) -> Agent

Create a scanner agent with type-specific prompt.

Parameters:

Name	Type	Description	Default
`question_type`	`str`	The type of question (mcq_sc, mcq_mc, etc.)	required
`use_context`	`bool`	Whether to include reference context in prompt	`True`
`subject`	`Optional[str]`	Subject override (uses config if not provided)	`None`

Returns:

Type	Description
`Agent`	Configured Agent instance for scanning that question type

TikZ Agent

tikz

TikZ agent for diagram generation.

Uses openai-agents SDK to generate TikZ/PGF code for physics diagrams, with tool access to search reference files for syntax examples.

Feature: physics-question-pipeline Validates: Requirements 3.1, 3.2, 3.3, 3.4

generate_tikz

generate_tikz(description: str = '', image_path: str | None = None, problem_text: str | None = None, search_references: bool = True, use_context: bool = True, classification: ClassificationResult | None = None, show_spinner: bool = True) -> str

Generate TikZ code for a diagram.

Can generate from: - A text description - An image - A problem text (LaTeX) - Any combination of the above

The agent can search reference files for relevant syntax.

Parameters:

Name	Type	Description	Default
`description`	`str`	Text description of the diagram to generate	`''`
`image_path`	`str \| None`	Optional path to an image of the diagram	`None`
`problem_text`	`str \| None`	Optional LaTeX problem text to analyze and generate diagram from	`None`
`search_references`	`bool`	Whether to enable reference search (default True)	`True`
`use_context`	`bool`	Whether to include reference context in prompt	`True`
`classification`	`ClassificationResult \| None`	Optional ClassificationResult for metadata-based context	`None`
`show_spinner`	`bool`	Whether to show animated spinner (default: True)	`True`

Returns:

Type	Description
`str`	Generated TikZ code as a string

Raises:

Type	Description
`FileNotFoundError`	If image_path is provided but file doesn't exist
`ValueError`	If neither description, image_path, nor problem_text is provided

create_tikz_agent

create_tikz_agent(use_context: bool = True, classification: ClassificationResult | None = None)

Create a TikZ agent with optional context.

Parameters:

Name	Type	Description	Default
`use_context`	`bool`	Whether to include reference context in prompt	`True`
`classification`	`ClassificationResult \| None`	Optional ClassificationResult for metadata-based context	`None`

Returns:

Type	Description
	Configured Agent instance for TikZ generation

get_tikz_context_for_classification

get_tikz_context_for_classification(classification) -> str

Get TikZ context matched to classification metadata.

Parameters:

Name	Type	Description	Default
`classification`		ClassificationResult with diagram metadata	required

Returns:

Type	Description
`str`	Formatted context string with matching TikZ examples

TikZ Router

tikz_router

TikZ Agent Router.

Routes TikZ generation to specialized agents based on diagram analysis. Uses Agent 2 (Diagram Analyzer) output for intelligent routing.

generate_tikz_with_routing

generate_tikz_with_routing(image_path: Optional[str] = None, description: Optional[str] = None, diagram: Optional[DiagramAnalysis] = None, primary: Optional[PrimaryClassification] = None, use_context: bool = True, show_spinner: bool = True) -> tuple[str, AgentType]

Generate TikZ code with automatic agent routing.

Parameters:

Name	Type	Description	Default
`image_path`	`Optional[str]`	Path to diagram image	`None`
`description`	`Optional[str]`	Text description of diagram	`None`
`diagram`	`Optional[DiagramAnalysis]`	DiagramAnalysis from Agent 2	`None`
`primary`	`Optional[PrimaryClassification]`	PrimaryClassification from Agent 1	`None`
`use_context`	`bool`	Whether to use reference context	`True`
`show_spinner`	`bool`	Whether to show animated spinner (default: True)	`True`

Returns:

Type	Description
`tuple[str, AgentType]`	Tuple of (tikz_code, agent_type_used)

get_agent_capabilities

get_agent_capabilities(agent_type: AgentType) -> dict

Get capabilities and specializations of an agent type.

Parameters:

Name	Type	Description	Default
`agent_type`	`AgentType`	Type of agent	required

Returns:

Type	Description
`dict`	Dict with capabilities, strengths, and limitations

route_tikz_agent

route_tikz_agent(diagram: Optional[DiagramAnalysis] = None, primary: Optional[PrimaryClassification] = None, diagram_type: Optional[str] = None) -> AgentType

Route to appropriate TikZ agent based on diagram analysis.

Priority: 1. diagram.suggested_tikz_agent (from Agent 2) 2. diagram.diagram_type (specific type) 3. diagram.diagram_category (general category) 4. primary classification hints 5. Default to generic

Parameters:

Name	Type	Description	Default
`diagram`	`Optional[DiagramAnalysis]`	DiagramAnalysis from Agent 2	`None`
`primary`	`Optional[PrimaryClassification]`	PrimaryClassification from Agent 1	`None`
`diagram_type`	`Optional[str]`	Manual override	`None`

Returns:

Type	Description
`AgentType`	Agent type to use: fbd, circuit, graph, optics, generic

Free Body Diagram Agent

fbd

FBD agent for Free Body Diagram generation.

Uses openai-agents SDK to generate TikZ code specifically for physics FBDs, with specialized validation and reference context.

generate_fbd

generate_fbd(description: str = '', image_path: str | None = None, problem_text: str | None = None, search_references: bool = True, use_context: bool = True, classification=None, show_spinner: bool = True) -> str

Generate FBD TikZ code for a physics problem.

Can generate from: - A text description - An image of the scenario - A problem text (LaTeX) - Any combination of the above

Parameters:

Name	Type	Description	Default
`description`	`str`	Text description of the FBD to generate	`''`
`image_path`	`str \| None`	Optional path to an image of the scenario	`None`
`problem_text`	`str \| None`	Optional LaTeX problem text to analyze	`None`
`search_references`	`bool`	Whether to enable reference search (default True)	`True`
`use_context`	`bool`	Whether to include reference context in prompt	`True`
`classification`		Optional ClassificationResult for metadata-based context	`None`

Returns:

Type	Description
`str`	Generated FBD TikZ code as a string

Raises:

Type	Description
`FileNotFoundError`	If image_path is provided but file doesn't exist
`ValueError`	If no input is provided

create_fbd_agent

create_fbd_agent(use_context: bool = True, classification=None)

Create an FBD agent with optional context.

Parameters:

Name	Type	Description	Default
`use_context`	`bool`	Whether to include reference context in prompt	`True`
`classification`		Optional ClassificationResult for metadata-based context	`None`

Returns:

Type	Description
	Configured Agent instance for FBD generation

Variant Agent

variant

Variant agents for physics problem generation.

Uses openai-agents SDK to generate different types of problem variants: - numerical: Modify only numerical values - context: Modify only the scenario/context - conceptual: Modify the core physics concept - calculus: Add calculus-based modifications

generate_variant

generate_variant(source_latex: str, variant_type: str, ideas: Optional[IdeaResult] = None, use_context: bool = True) -> str

Generate a variant of the source problem.

Creates a new problem variant based on the specified type: - numerical: Changes only numerical values - context: Changes only the scenario/context - conceptual: Changes the core physics concept - calculus: Adds calculus-based modifications

Parameters:

Name	Type	Description	Default
`source_latex`	`str`	The source problem in LaTeX format	required
`variant_type`	`str`	Type of variant to generate	required
`ideas`	`Optional[IdeaResult]`	Optional IdeaResult with extracted concepts (used for context)	`None`
`use_context`	`bool`	Whether to include reference context in prompt	`True`

Returns:

Type	Description
`str`	The generated variant in LaTeX format

Raises:

Type	Description
`ValueError`	If source_latex is empty or variant_type is invalid

generate_numerical_variant

generate_numerical_variant(source_latex: str, ideas: Optional[IdeaResult] = None, use_context: bool = True) -> str

Generate a numerical variant (changes only numerical values).

Parameters:

Name	Type	Description	Default
`source_latex`	`str`	The source problem in LaTeX format	required
`ideas`	`Optional[IdeaResult]`	Optional IdeaResult with extracted concepts	`None`
`use_context`	`bool`	Whether to include reference context in prompt	`True`

Returns:

Type	Description
`str`	The generated variant in LaTeX format

generate_context_variant

generate_context_variant(source_latex: str, ideas: Optional[IdeaResult] = None, use_context: bool = True) -> str

Generate a context variant (changes only the scenario/context).

Parameters:

Name	Type	Description	Default
`source_latex`	`str`	The source problem in LaTeX format	required
`ideas`	`Optional[IdeaResult]`	Optional IdeaResult with extracted concepts	`None`
`use_context`	`bool`	Whether to include reference context in prompt	`True`

Returns:

Type	Description
`str`	The generated variant in LaTeX format

Multi-Variant Agent

multi_variant

Multi-context variant agent for physics problems.

Uses openai-agents SDK to generate problem variants by combining elements from multiple source problems into a single coherent problem.

generate_multi_context_variant

generate_multi_context_variant(source_problems: list[str], target_style: Optional[str] = None) -> str

Combine elements from multiple problems into a single coherent problem.

Analyzes multiple source problems and creates a new problem that synthesizes concepts, techniques, or scenarios from the sources into a unified, coherent question.

Parameters:

Name	Type	Description	Default
`source_problems`	`list[str]`	List of source problems in LaTeX format	required
`target_style`	`Optional[str]`	Optional style guidance for the output (e.g., "MCQ", "subjective")	`None`

Returns:

Type	Description
`str`	A single coherent problem in LaTeX format that combines elements
`str`	from the source problems

Raises:

Type	Description
`ValueError`	If source_problems is empty or contains only empty strings

Alternate Solution Agent

alternate

Alternate solution agent for physics problems.

Uses openai-agents SDK to generate alternative solution methods while maintaining the same final answer.

generate_alternate

generate_alternate(problem: str, solution: str, ideas: Optional[IdeaResult] = None, existing_alternates: Optional[list[str]] = None, full_content: Optional[str] = None) -> str

Generate an alternate solution approach for a physics problem.

Creates a different valid solution method that arrives at the same final answer as the original solution.

Parameters:

Name	Type	Description	Default
`problem`	`str`	The problem statement in LaTeX format (legacy, used if full_content not provided)	required
`solution`	`str`	The original solution in LaTeX format (legacy, used if full_content not provided)	required
`ideas`	`Optional[IdeaResult]`	Optional IdeaResult with extracted concepts and techniques	`None`
`existing_alternates`	`Optional[list[str]]`	List of existing alternate solutions to avoid repeating	`None`
`full_content`	`Optional[str]`	Full LaTeX file content (preferred - pass entire file)	`None`

Returns:

Type	Description
`str`	Alternative solution in LaTeX format within alternatesolution environment

Raises:

Type	Description
`ValueError`	If content is empty

Idea Extraction Agent

idea

Idea extraction agent for physics problems.

Uses openai-agents SDK to analyze physics problems and solutions, extracting core concepts, formulas, techniques, and difficulty factors.

extract_ideas

extract_ideas(problem_latex: str, solution_latex: str) -> IdeaResult

Extract core concepts and techniques from a physics problem (JSON output).

Analyzes the problem statement and solution to identify: - Primary physics concepts being tested - Key formulas and equations used - Problem-solving techniques employed - Factors that make the problem challenging

Parameters:

Name	Type	Description	Default
`problem_latex`	`str`	The problem statement in LaTeX format	required
`solution_latex`	`str`	The solution in LaTeX format	required

Returns:

Type	Description
`IdeaResult`	IdeaResult with extracted concepts, formulas, techniques,
`IdeaResult`	and difficulty factors

Raises:

Type	Description
`ValueError`	If both problem and solution are empty

Converter Agent

converter

Format converter agent for physics questions.

Uses openai-agents SDK to convert questions between different formats: - MCQ (single/multiple correct) - Subjective - Integer type

convert_format

convert_format(source_latex: str, source_format: FormatType, target_format: FormatType) -> str

Convert a physics question from one format to another.

Converts questions between MCQ (single/multiple correct), subjective, and integer type formats while preserving the core physics content and difficulty level.

Parameters:

Name	Type	Description	Default
`source_latex`	`str`	The source question in LaTeX format	required
`source_format`	`FormatType`	The format of the source question	required
`target_format`	`FormatType`	The desired target format	required

Returns:

Type	Description
`str`	Converted question in LaTeX format with solution

Raises:

Type	Description
`ValueError`	If source_latex is empty or formats are invalid

Compile Fixer Agent

compile_fixer

Agent for fixing LaTeX compilation errors.

Takes a LaTeX snippet and pdflatex error output, returns corrected LaTeX.

fix_latex

fix_latex(error_summary: str, latex: str) -> str

Send LaTeX + errors to agent and get fixed version.

Parameters:

Name	Type	Description	Default
`error_summary`	`str`	Parsed pdflatex error output	required
`latex`	`str`	The LaTeX code that failed to compile	required

Returns:

Type	Description
`str`	Corrected LaTeX code

QA Agents

Reviewer Agent

reviewer

QA Review Agent for physics question quality assurance.

Uses OpenAI Agents SDK to analyze physics problems and variants, generating structured suggestions with diffs for any issues found.

review_problem_sync

review_problem_sync(context: ProblemContext, max_retries: int = DEFAULT_MAX_RETRIES, base_delay: float = DEFAULT_BASE_DELAY) -> ReviewResult

Synchronous wrapper for review_problem.

Parameters:

Name	Type	Description	Default
`context`	`ProblemContext`	ProblemContext with all files loaded	required
`max_retries`	`int`	Maximum number of retry attempts (default: 3)	`DEFAULT_MAX_RETRIES`
`base_delay`	`float`	Base delay for exponential backoff in seconds (default: 1.0)	`DEFAULT_BASE_DELAY`

Returns:

Type	Description
`ReviewResult`	ReviewResult with pass/fail status and suggestions

Raises:

Type	Description
`ReviewAgentError`	If all retry attempts fail

Solution Checker

solution_checker

Solution checker agent for physics problems.

Verifies mathematical correctness, physics principles, and final answer accuracy in physics solutions. Also creates solutions when none exists.

check_solution

check_solution(full_content: str) -> tuple[bool, str, str]

Check a physics solution for correctness, or create one if missing.

Analyzes the solution for: - Mathematical calculation errors - Physics principle misapplication - Final answer correctness - Unit consistency

If no solution exists, creates a complete solution.

Parameters:

Name	Type	Description	Default
`full_content`	`str`	Full LaTeX file content (problem with or without solution)	required

Returns:

Type	Description
`bool`	Tuple of (passed, summary, corrected_content)
`str`	passed: True if no errors found (existing solution is correct)
`str`	summary: Description of what was fixed/created (or "PASSED")
`tuple[bool, str, str]`	corrected_content: The corrected/completed file content (empty if passed)

Raises:

Type	Description
`ValueError`	If content is empty

Grammar Checker

grammar_checker

Grammar checker agent for physics content.

Checks for grammar, spelling, and language errors in physics problems and solutions.

check_grammar

check_grammar(full_content: str) -> tuple[bool, str, str]

Check physics content for grammar and spelling errors.

Analyzes the content for: - Grammar errors - Spelling mistakes - Awkward phrasing - Punctuation issues

Parameters:

Name	Type	Description	Default
`full_content`	`str`	Full LaTeX file content	required

Returns:

Type	Description
`bool`	Tuple of (passed, summary, corrected_content)
`str`	passed: True if no issues found
`str`	summary: Description of what was fixed (or "PASSED")
`tuple[bool, str, str]`	corrected_content: The corrected file content (empty if passed)

Raises:

Type	Description
`ValueError`	If content is empty

Clarity Checker

clarity_checker

Clarity checker agent for physics content.

Checks for language clarity, conciseness, and pedagogical quality in physics problems and solutions.

check_clarity

check_clarity(full_content: str) -> tuple[bool, str, str]

Check physics content for clarity and conciseness.

Analyzes the content for: - Unclear or ambiguous statements - Verbose or redundant text - Pedagogical improvements - Readability issues

Parameters:

Name	Type	Description	Default
`full_content`	`str`	Full LaTeX file content	required

Returns:

Type	Description
`bool`	Tuple of (passed, summary, corrected_content)
`str`	passed: True if no improvements needed
`str`	summary: Description of what was improved (or "PASSED")
`tuple[bool, str, str]`	corrected_content: The improved file content (empty if passed)

Raises:

Type	Description
`ValueError`	If content is empty

Selector Agent

selector

Random problem selector for QA Review Agent.

Discovers and selects problems from the processed output directory for quality review.

ProblemContext `dataclass`

ProblemContext(problem_id: str, base_path: Path, image_path: str | None, latex_path: str, latex_content: str, variants: dict[str, str] = dict(), variant_paths: dict[str, str] = dict())

Context for a problem selected for review.

Contains all the files and content needed for QA review.

discover_problems

discover_problems(output_dir: str) -> list[str]

Discover all problem IDs in the output directory.

Looks for .tex files in the following locations (in order): 1. scans/ subdirectory (standard agentic output structure) 2. Directly in the given directory (flat structure)

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Path to the output directory (e.g., "agentic" or direct tex folder)	required

Returns:

Type	Description
`list[str]`	List of problem IDs (base names without extension)

load_problem_context

load_problem_context(output_dir: str, problem_id: str) -> ProblemContext

Load all files for a problem into a review context.

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Path to the output directory	required
`problem_id`	`str`	ID of the problem to load	required

Returns:

Type	Description
`ProblemContext`	ProblemContext with all loaded content

Raises:

Type	Description
`FileNotFoundError`	If the problem's LaTeX file doesn't exist

select_random

select_random(output_dir: str, count: int) -> list[str]

Randomly select problem IDs for review.

Parameters:

Name	Type	Description	Default
`output_dir`	`str`	Path to the output directory	required
`count`	`int`	Number of problems to select	required

Returns:

Type	Description
`list[str]`	List of randomly selected problem IDs.
`list[str]`	Returns min(count, available) problems if fewer are available.