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:

1. Image Classifier - Classify questions from images
2. Diagram Analyzer - Hierarchical diagram categorization
3. Difficulty Assessor - Post-scan difficulty with detailed metadata
4. LaTeX Classifier - Batch processing of LaTeX files
5. Idea Generator - Generate problems from concepts
6. Problem Combiner - Combine multiple problems
7. 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

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.

to_primary_classification

to_primary_classification(result: QuestionClassification) -> PrimaryClassification

Extract the compact primary-classification view.

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

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, timeout: float | None = None) -> Any

Run an agent synchronously and return the final output.

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 Compatibility Facade

classifier

Backward-compatible public facade for question-image classification.

New code should import from vbagent.agents.classification.question_classifier.

classify

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

Classify an image using the canonical question classifier.

create_classifier_agent

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

Compatibility wrapper for :func:create_question_classifier.

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, sample_reference: Optional[str] = None) -> 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
sample_reference	Optional[str]	Optional golden sample .tex for formatting reference	None

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, sample_reference: 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
sample_reference	Optional[str]	Optional golden sample .tex for formatting reference	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) -> Any

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
Any	Configured Agent instance for TikZ generation

get_tikz_context_for_classification

get_tikz_context_for_classification(classification: ClassificationResult) -> str

Get TikZ context matched to classification metadata.

Parameters:

Name	Type	Description	Default
classification	ClassificationResult	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 structured diagram-classification 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, subject: Optional[str] = None, diagram_type: Optional[str] = None, problem_text: Optional[str] = None, solution_context: Optional[str] = None, values: Optional[dict] = None, labels: Optional[list] = None, mcq_options: bool = False, diagram_context: str = 'solution') -> 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]	Structured diagram classification	None
primary	Optional[PrimaryClassification]	Compact question classification	None
use_context	bool	Whether to use reference context	True
show_spinner	bool	Whether to show animated spinner (default: True)	True
subject	Optional[str]	Subject name (physics, chemistry, etc.)	None
diagram_type	Optional[str]	Manual diagram type override for routing	None
problem_text	Optional[str]	Optional problem text for context	None
solution_context	Optional[str]	Optional rich context from solution agent	None
values	Optional[dict]	Optional dict of variable values	None
labels	Optional[list]	Optional list of labels needed	None
mcq_options	bool	Whether generating MCQ options (use \def\OptionA{...} format)	False
diagram_context	str	"problem" or "solution". When "problem", force/FBD routing is redirected to the neutral setup agent so the printed problem figure shows the physical scene without force vectors.	'solution'

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, subject: Optional[str] = None, diagram_context: str = 'solution') -> AgentType

Route to appropriate TikZ agent based on diagram analysis and subject.

Priority: 1. diagram.suggested_tikz_agent 2. Subject-specific routing (chemistry vs physics) 3. diagram.diagram_type (specific type) 4. diagram.diagram_category (general category) 5. primary classification hints 6. Default to generic

Parameters:

Name	Type	Description	Default
diagram	Optional[DiagramAnalysis]	Structured diagram classification	None
primary	Optional[PrimaryClassification]	Compact question classification	None
diagram_type	Optional[str]	Manual override	None
subject	Optional[str]	Subject name (physics, chemistry, etc.)	None
diagram_context	str	"problem" or "solution". In "problem" context a free-body (force) diagram is not appropriate for the printed figure, so an fbd route is redirected to the setup agent (physical scene, no force vectors).	'solution'

Returns:

Type	Description
AgentType	Agent type to use

Free Body Diagram Agent

fbd

FBD agent for Free Body Diagram generation.

generate_fbd module-attribute

generate_fbd = _agent.generate

create_fbd_agent module-attribute

create_fbd_agent = _agent.create_agent

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, classification: Optional[Any] = None, *, include_solution: bool = True, include_idea: bool = False) -> 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 - cross_topic: Integrates a complementary physics topic (multi-stage)

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
classification	Optional[Any]	Optional ClassificationResult for cross_topic variants	None
include_solution	bool	Include a worked solution now, or defer it	True
include_idea	bool	Include a concise conceptual idea after the question/solution	False

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_context_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, hint: 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
hint	Optional[str]	Optional method hint selected by the solution agent	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 problems across subjects.

Uses openai-agents SDK to analyze problems and solutions, extracting core concepts, formulas, techniques, and difficulty factors. Subject-aware: adapts prompts for physics, chemistry, mathematics.

extract_ideas

extract_ideas(problem_latex: str, solution_latex: str, subject: str | None = None) -> IdeaResult

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

Parameters:

Name	Type	Description	Default
problem_latex	str	The problem statement in LaTeX format	required
solution_latex	str	The solution in LaTeX format	required
subject	str | None	Subject override (physics/chemistry/mathematics)	None

Returns:

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

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

latex_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.

check_solution

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

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

Grammar Checker

grammar_checker

Grammar checker agent for physics content.

check_grammar

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

Check physics content for grammar and spelling errors.

Clarity Checker

clarity_checker

Clarity checker agent for physics content.

check_clarity

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

Check physics content for clarity and conciseness.

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, subject: str = 'physics', compile_error: str | None = None, 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.