CLI API Reference
Auto-generated API documentation for VBAgent CLI modules.
Main Entry Point
main
Main CLI entry point for VBAgent.
VBAgent - Physics question processing pipeline.
Uses lazy loading to speed up CLI startup time by deferring heavy imports (openai, agents, mcp, etc.) until commands are actually invoked.
main
VBAgent - Physics question processing pipeline.
A multi-agent CLI system for processing physics question images. Supports classification, scanning, diagram generation, variant creation, and format conversion.
Commands: init - Initialize workspace config (.vbagent.json) chat - Interactive conversational interface mcp - Start MCP server for external agents metadata - Manage question bank metadata dpp - Create Daily Practice Problem sets export - Export LaTeX files in different formats extans - Extract answers from LaTeX problem files db - Database management for question bank process - Full pipeline orchestration classify - Stage 1: Classify question image scan - Stage 2: Extract LaTeX from image tikz - Generate TikZ code for diagrams fbd - Generate Free Body Diagram TikZ code idea - Extract concepts and ideas alternate - Generate alternative solutions variant - Generate problem variants convert - Convert between question formats batch - Batch processing with resume capability check - QA review with interactive approval ref - Manage reference context files config - Configure models and settings util - File utilities (rename, count, clean)
Classification Commands
classify
CLI command for classifying physics question images.
Stage 1: Classify physics question image to extract metadata.
classify
Stage 1: Classify physics question image.
Analyzes a physics question image and extracts metadata including: question type, difficulty, topic, subtopic, diagram presence, etc.
Examples: vbagent classify -i question.png vbagent classify --image images/q1.png --json vbagent classify -i images/q1.png -o result.json
Scanning Commands
scan
CLI command for scanning physics question images to extract LaTeX.
Stage 2: Extract LaTeX from image using type-specific prompts.
display_scan_result
Display scan result with syntax highlighting.
scan
scan(image: str | None, tex: str | None, question_type: str | None, output: str | None, do_compile: bool, verbose_compile: bool, assess_difficulty: bool, analyze_diagram: bool, use_orchestrator: bool)
Stage 2: Extract LaTeX from physics question image.
Runs classification first (unless --type provided), then extracts LaTeX using the appropriate type-specific prompt.
Examples: vbagent scan -i question.png vbagent scan --image images/q1.png --output output.tex vbagent scan -i images/q1.png --type mcq_sc vbagent scan -i q.png -t existing.tex -o updated.tex
Processing Commands
process
CLI command for full pipeline processing.
Orchestrates all agents for complete physics question processing: Classify → Scan → TikZ → Ideas → Variants.
convert_primary_to_classification
Convert PrimaryClassification (v2) to ClassificationResult (v1) for compatibility.
Used when calling legacy functions that expect ClassificationResult.
extract_items_from_tex
Extract individual items from a TeX file.
Splits content by \item markers to get individual problems.
filter_items_by_range
Filter items by the specified range (1-based, inclusive).
generate_alternate_solution
Generate an alternate solution using the alternate agent.
generate_image_paths_from_range
Generate image paths from a template and range.
Given an image path like 'images/Problem_3.png' and range (1, 5), generates paths: Problem_1.png, Problem_2.png, ..., Problem_5.png
Supports patterns: - Problem_3.png -> Problem_1.png, Problem_2.png, ... - question3.png -> question1.png, question2.png, ... - img_03.png -> img_01.png, img_02.png, ...
get_base_name
Extract base name from source path (without extension).
insert_tikz_into_latex
Replace diagram placeholders with actual TikZ code.
Handles two types of placeholders: 1. Main diagram: \begin{center}\input{diagram}\end{center} 2. Option diagrams: \OptionA, \OptionB, etc. with \def definitions
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
latex
|
str
|
The LaTeX content with placeholder(s) |
required |
tikz_code
|
str
|
The generated TikZ code (may include \def\OptionX{...}) |
required |
Returns:
| Type | Description |
|---|---|
str
|
LaTeX with TikZ code inserted |
merge_metadata_into_latex
merge_metadata_into_latex(latex: str, primary: 'PrimaryClassification', diagram: Optional['DiagramAnalysis'] = None, difficulty: Optional['DifficultyAssessment'] = None) -> str
Prepend classification metadata as comments to LaTeX content.
process
process(image: Optional[str], tex: Optional[str], item_range: Optional[tuple[int, int]], variant_types_str: Optional[str], alternate: bool, ideas: bool, ref_dirs: tuple[str, ...], output: str, context: bool, parallel: int, do_compile: bool, verbose_compile: bool, assess_difficulty: bool, analyze_diagram: bool, validate_tikz: bool, use_orchestrator: bool, merge_metadata: bool, no_cache: bool, clear_cache: bool)
Full pipeline: Classify → Scan → TikZ → Ideas → Variants.
Orchestrates all agents for complete physics question processing. Processes images or TeX files through the full pipeline.
By default, only classification, scanning, and TikZ generation run. Use --ideas, --alternate, and --variants to enable additional stages.
Pipeline Stages: 1. Classification - Extract metadata from image 2. Scanning - Extract LaTeX from image 3. TikZ - Generate diagram code (if has_diagram) 4. Ideas - Extract physics concepts (--ideas) 5. Alternates - Generate alternate solutions (--alternate) 6. Variants - Generate problem variants (--variants)
Output Structure: agentic/ ├── scans/problem_1.tex ├── classifications/problem_1.json ├── alternates/problem_1.tex (if --alternate) ├── variants/numerical/problem_1.tex (if --variants) ├── ideas/problem_1.json (if --ideas) └── tikz/problem_1.tex
Examples: vbagent process -i images/Problem_1.png vbagent process -i images/Problem_1.png --ideas vbagent process -i images/Problem_1.png --ideas --alternate vbagent process -i images/Problem_1.png --variants numerical,context vbagent process -i images/Problem_1.png -r 1 5 vbagent process -i images/Problem_1.png -r 1 10 --parallel 3 vbagent process -t problems.tex --range 1 5 --alternate --ideas
process_generated_problem
process_generated_problem(generated: 'GeneratedProblem', problem_num: int, output_base_dir: Path = Path('agentic')) -> dict
Process a generated problem through the full pipeline.
Runs the complete workflow on a problem generated by Agent 5: 1. Generate TikZ from diagram_description (if present) 2. Run Agent 4 (LaTeX Classifier) on the problem 3. Run Agent 2 (Diagram Analyzer) if has_diagram 4. Run Agent 3 (Difficulty Assessor) 5. Merge metadata into LaTeX 6. Save everything in standard format
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
generated
|
'GeneratedProblem'
|
GeneratedProblem from Agent 5 |
required |
problem_num
|
int
|
Problem number for file naming |
required |
output_base_dir
|
Path
|
Base directory for output (default: agentic/) |
Path('agentic')
|
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with paths and metadata |
process_image
process_image(image_path: str, variant_types: list[str], generate_alternate: bool, generate_ideas: bool = False, use_context: bool = True, assess_difficulty: bool = True, analyze_diagram: bool = True, merge_metadata: bool = True, use_orchestrator: bool = False, use_cache: bool = True, problem_id: Optional[str] = None) -> PipelineResult
Process an image through the full pipeline.
Pipeline stages: 1. Classification (Agent 1 + optional Agent 2) 2. Scanning (Agent 3 + optional difficulty assessment) 3. TikZ (parallel with scanning if has_diagram) 4. Ideas, Alternates, Variants (sequential, optional)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
use_cache
|
bool
|
If True, use cached results from previous runs |
True
|
problem_id
|
Optional[str]
|
Problem identifier for caching (auto-generated if None) |
None
|
process_tex_item
process_tex_item(tex_content: str, source_path: str, variant_types: list[str], generate_alternate: bool, generate_ideas: bool = False, use_context: bool = True) -> PipelineResult
Process a TeX item through the pipeline (skips classification/scanning).
save_pipeline_result
Save pipeline result to output directory (legacy flat structure).
Returns dict mapping output type to file path.
save_pipeline_result_organized
save_pipeline_result_organized(result: PipelineResult, base_dir: Path, base_name: str) -> dict[str, str]
Save pipeline result to organized directory structure.
Structure
agentic/ ├── scans/{base_name}.tex ├── classifications/{base_name}.json ├── alternates/{base_name}.tex ├── variants/ │ ├── numerical/{base_name}.tex │ ├── context/{base_name}.tex │ └── ... ├── ideas/{base_name}.json └── tikz/{base_name}.tex
Returns dict mapping output type to file path.
TikZ Commands
tikz
CLI command for generating TikZ diagram code.
Generates TikZ/PGF code for physics diagrams from images or descriptions.
tikz
tikz(image: str | None, description: str | None, tex: str | None, ref_dirs: tuple[str, ...], output: str | None, do_compile: bool, verbose_compile: bool)
Generate TikZ code for physics diagrams.
Can generate TikZ code from: - An image (-i/--image) - A text description (-d/--description) - A problem text file (-t/--tex) - Any combination of the above
Optionally searches reference files (STY, TeX, PDF) for syntax examples.
Examples: vbagent tikz -d "Free body diagram with gravity and normal force" vbagent tikz -i diagram.png -o diagram.tex vbagent tikz -t problem.tex -o diagram.tex vbagent tikz -t problem.tex -i reference.png -o diagram.tex vbagent tikz -d "RC circuit" --ref refs/circuitikz/ -o circuit.tex
Variant Commands
variant
CLI command for generating problem variants.
Generates different types of physics problem variants: - numerical: Modify only numerical values - context: Modify only the scenario/context - conceptual: Modify the core physics concept - calculus: Add calculus-based modifications - multi: Combine multiple problems
extract_items_from_tex
Extract individual items from a TeX file.
filter_items_by_range
Filter items by the specified range.
variant
variant(image: Optional[str], tex: Optional[str], variant_type: str, item_range: Optional[tuple[int, int]], count: int, context_files: tuple[str, ...], ideas: Optional[str], output: Optional[str], do_compile: bool, verbose_compile: bool)
Generate problem variants.
Creates variants of physics problems with controlled modifications.
Variant Types: numerical - Change only numbers, keep context context - Change scenario, keep numbers conceptual - Change physics concept calculus - Add calculus elements multi - Combine multiple problems
Examples: vbagent variant -t problem.tex --type numerical vbagent variant --tex problem.tex --type numerical --count 3 vbagent variant -t problem.tex --type context -o variants.tex vbagent variant -t problems.tex --type numerical -r 1 5 vbagent variant --type multi --context p1.tex --context p2.tex -o combined.tex vbagent variant -i image.png --type numerical --output variant.tex
Batch Processing
batch
CLI commands for batch processing with resume capability.
Provides init and continue commands for processing multiple images
with SQLite-based state tracking and caffeinate support.
SleepInhibitor
batch
Batch processing commands with resume capability.
Process multiple images through the full pipeline with SQLite-based state tracking and automatic resume on interruption.
Commands: init - Initialize and start batch processing continue - Resume from where you left off status - Show current progress
Examples: vbagent batch init -i ./images vbagent batch continue vbagent batch status
continue_batch
Continue batch processing from where it left off.
Resumes processing using the existing SQLite database. Use --reset-failed to retry previously failed images.
Examples: vbagent batch continue vbagent batch continue --reset-failed
Tip: Run 'vbagent batch status' to see current progress.
discover_images
Discover all images in a directory matching the pattern.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
images_dir
|
str
|
Directory to search |
required |
pattern
|
str
|
Glob pattern for images (default: *.png) |
'*.png'
|
Returns:
| Type | Description |
|---|---|
list[str]
|
Sorted list of image paths |
init
Initialize batch processing for all images in a directory.
Scans the images directory, creates a SQLite database to track progress, and starts processing all images through the full pipeline.
Examples: vbagent batch init vbagent batch init -i ./my_images vbagent batch init --images-dir ./images --output ./results vbagent batch init --variants numerical,context --no-alternate vbagent batch init -i ./images -o ./output --no-context
Quality Assurance
check
CLI commands for QA review with interactive approval workflow.
Provides check command for random spot-checking of processed physics
questions with AI-powered quality review and diff-based suggestions.
apply
Apply a previously rejected suggestion.
Retrieves a stored suggestion by ID and applies its diff. Use --edit to review/modify the suggested content in your editor first.
Examples: vbagent check apply 42 vbagent check apply 42 -e vbagent check apply 42 --edit
apply_suggestion
Apply an approved suggestion to the file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
suggestion
|
'Suggestion'
|
The suggestion to apply |
required |
problem_id
|
str
|
Problem ID for path resolution |
''
|
Returns:
| Type | Description |
|---|---|
|
DiffResult with success status and error details if failed |
check
QA review commands for spot-checking processed problems.
Commands: run - Start a random QA review session init - Initialize problem tracking database continue - Continue from where you left off status - Show check progress recheck - Reset problems for rechecking alternate - Generate alternate solutions idea - Generate idea summaries solution - Check solution correctness grammar - Check grammar and spelling clarity - Check clarity and conciseness tikz - Check/generate TikZ diagrams apply - Apply a stored suggestion history - View suggestion history resume - Resume interrupted session stats - View review statistics
Examples: vbagent check run vbagent check init -d ./agentic vbagent check continue -c 10 vbagent check status vbagent check alternate -d ./src_tex/ vbagent check idea -d ./src_tex/ vbagent check solution -d ./src_tex/ vbagent check grammar -d ./src_tex/ vbagent check clarity -d ./src_tex/ vbagent check tikz -d ./scans/ # Check/generate TikZ vbagent check tikz --patch --ref-type circuit
check_alternate
check_alternate(output_dir: str, count: int, min_alternates: int, problem_id: Optional[str], images_dir: Optional[str], prompt: Optional[str])
Check and generate alternate solutions for problems.
Scans all .tex files in the specified directory (or subdirectories), checks if they have alternate solutions, and generates new ones with interactive approval.
The alternate solution is appended to the problem file using the \begin{alternatesolution}...\end{alternatesolution} environment.
Images are matched by filename (e.g., problem_1.tex -> problem_1.png). Use --prompt to add specific instructions for generating alternates.
Supports: - Direct directory with .tex files (e.g., ./src/src_tex/) - Agentic folder structure (scans/, variants/) - Single .tex file
Examples: vbagent check alternate vbagent check alternate -d ./src/src_tex/ vbagent check alternate -d ./src/src_tex/ -i ./src/src_images/ vbagent check alternate --dir ./problem_1.tex vbagent check alternate -c 10 vbagent check alternate --count 10 --min-alternates 2 vbagent check alternate -p Problem_1 vbagent check alternate --prompt "Use energy conservation method" vbagent check alternate -d ./agentic/scans -p Problem_5
check_clarity_cmd
check_clarity_cmd(output_dir: str, count: int, problem_id: Optional[str], prompt: Optional[str], reset: bool)
Check content for clarity and conciseness.
Reviews text for unclear statements, verbose explanations, and pedagogical improvements. Prompts for approval to apply changes.
Use --prompt to add specific instructions for the checker.
Examples: vbagent check clarity vbagent check clarity -d ./src/src_tex/ vbagent check clarity -c 10 vbagent check clarity -p Problem_1 vbagent check clarity --prompt "Keep explanations brief for JEE level" vbagent check clarity --reset
check_grammar_cmd
check_grammar_cmd(output_dir: str, count: int, problem_id: Optional[str], prompt: Optional[str], reset: bool)
Check content for grammar and spelling errors.
Reviews text for grammar, spelling, punctuation, and awkward phrasing issues. Prompts for approval to apply fixes.
Use --prompt to add specific instructions for the checker.
Examples: vbagent check grammar vbagent check grammar -d ./src/src_tex/ vbagent check grammar -c 10 vbagent check grammar -p Problem_1 vbagent check grammar --prompt "Use British English spelling" vbagent check grammar --reset
check_idea
Generate and append idea summaries to problems.
Scans .tex files, extracts key concepts/formulas/techniques,
and appends them in a \begin{idea}...\end{idea} environment.
Supports: - Direct directory with .tex files - Agentic folder structure (scans/, variants/) - Single .tex file
Examples: vbagent check idea vbagent check idea -d ./src/src_tex/ vbagent check idea -c 10 vbagent check idea -p Problem_1
check_solution_cmd
check_solution_cmd(output_dir: str, count: int, problem_id: Optional[str], images_dir: Optional[str], prompt: Optional[str], reset: bool)
Check or create solutions for physics problems.
If a solution EXISTS: Verifies calculations, physics principles, and final answers. If a solution is MISSING: Creates a complete solution using the problem context.
Prompts for approval before applying corrections or new solutions. Images are matched by filename (e.g., problem_1.tex -> problem_1.png). Use --prompt to add specific instructions for the checker.
Examples: vbagent check solution vbagent check solution -d ./src/src_tex/ vbagent check solution -d ./src/src_tex/ -i ./src/src_images/ vbagent check solution -c 10 vbagent check solution -p Problem_1 vbagent check solution --prompt "Focus on unit consistency" vbagent check solution --reset
check_status
Show check progress and status.
Displays statistics for problem checking in the specified directory.
Examples: vbagent check status vbagent check status -d ./my_output vbagent check status -s pending vbagent check status --show failed vbagent check status --dir ./agentic --show all
check_tikz_cmd
check_tikz_cmd(output_dir: str, count: int, problem_id: Optional[str], images_dir: Optional[str], prompt: Optional[str], only_tikz: bool, reset: bool, patch: bool, use_context: bool, ref_type: Optional[str])
Check and generate TikZ diagram code.
This command has two modes:
-
CHECK MODE: Reviews existing TikZ/PGF code for syntax errors, missing libraries, and physics diagram conventions.
-
GENERATE MODE: If a file has \input{diagram} placeholder but no TikZ code, automatically generates TikZ from the corresponding image (auto-discovered in images/ directory).
Images are auto-discovered by filename (e.g., Problem_1.tex -> images/Problem_1.png) or can be specified with --images-dir.
Reference examples are matched by diagram type from classification metadata, or can be filtered manually with --ref-type.
Use --patch to enable apply_patch mode for more precise edits.
Examples: vbagent check tikz # Check/generate in agentic/ vbagent check tikz -d ./scans/ # Check specific directory vbagent check tikz -d ./scans/Problem_1.tex # Check single file vbagent check tikz -c 10 # Process 10 files vbagent check tikz -p Problem_1 # Check specific problem vbagent check tikz -i ./images/ # Explicit images directory vbagent check tikz --only-tikz # Skip files without TikZ vbagent check tikz --reset # Re-check all files vbagent check tikz --patch # Use apply_patch mode vbagent check tikz --ref-type circuit # Use only circuit references vbagent check tikz --prompt "Use circuitikz" # Add instructions
continue_check
Continue checking from where you left off.
Picks up pending problems from the tracking database and runs AI-powered quality review with interactive approval.
Examples: vbagent check continue vbagent check continue -c 10 vbagent check continue --count 10 --dir ./my_output
display_suggestion
Display a suggestion with all details.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
suggestion
|
'Suggestion'
|
The suggestion to display |
required |
console
|
'Console'
|
Rich console for output |
required |
format_diff_error
Format a diff error for display.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
result
|
'DiffResult'
|
DiffResult with error information |
required |
Returns:
| Type | Description |
|---|---|
str
|
Human-readable error message |
history
Display rejected suggestion history.
Shows previously rejected suggestions that can be applied later.
Examples: vbagent check history vbagent check history -p Problem_42 vbagent check history --problem-id Problem_42 --limit 50 vbagent check history -f conceptual_variant.tex -n 10
init_check
Initialize problem check tracking.
Discovers all problems in the output directory and adds them to the tracking database. Use --range to limit to specific problems.
Examples: vbagent check init vbagent check init -d ./my_output vbagent check init --dir ./agentic --range 1 50 vbagent check init -r 1 50 vbagent check init --reset
prompt_review_action
Display suggestion and prompt user for action.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
suggestion
|
'Suggestion'
|
The suggestion to review |
required |
console
|
'Console'
|
Rich console for output |
required |
Returns:
| Type | Description |
|---|---|
ReviewAction
|
The user's chosen action |
recheck
Reset problems for rechecking.
Resets the status of problems to pending so they can be checked again.
Examples: vbagent check recheck vbagent check recheck --failed vbagent check recheck -p Problem_1 vbagent check recheck -p Problem_1 -p Problem_2 vbagent check recheck --dir ./output --failed
resolve_file_path
Resolve a stored file path to an actual file.
Tries multiple strategies to find the file: 1. Direct path (if absolute or exists relative to cwd) 2. Look in common output directories (agentic/, output/) 3. Search for problem_id directory and find file within
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stored_path
|
str
|
The path stored in the database |
required |
problem_id
|
str
|
The problem ID associated with this file |
required |
Returns:
| Type | Description |
|---|---|
Optional[str]
|
Resolved path if found, None otherwise |
resume
Resume an interrupted review session.
If no session ID is provided, shows a list of incomplete sessions. Session IDs can be shortened (prefix match).
Examples: vbagent check resume vbagent check resume abc12345 vbagent check resume abc
run_check
Start a QA review session.
Randomly selects problems from the output directory and runs AI-powered quality review with interactive approval.
Examples: vbagent check run vbagent check run -c 10 vbagent check run --count 10 --dir ./output vbagent check run -p Problem_42 vbagent check run --problem-id Problem_42 -d ./my_output
run_review_session
run_review_session(problems: list, store: 'VersionStore', console: 'Console', output_dir: str = 'agentic', session_id: Optional[str] = None) -> dict
Run an interactive review session.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problems
|
list
|
List of problem contexts to review |
required |
store
|
'VersionStore'
|
Version store for saving rejected suggestions |
required |
console
|
'Console'
|
Rich console for output |
required |
output_dir
|
str
|
Output directory being reviewed (for resume capability) |
'agentic'
|
session_id
|
Optional[str]
|
Optional existing session ID (for resume) |
None
|
Returns:
| Type | Description |
|---|---|
dict
|
Dictionary with session statistics |
Chat Interface
chat
Chat interface for conversational orchestrator.
Provides an interactive terminal-based chat interface using the Rich library for formatted output and user interaction.
ChatInterface
Terminal chat interface with rich formatting.
Provides an interactive chat session with: - Formatted message display (user/assistant/system panels) - Tool execution progress indicators - Exit command handling - Conversation history maintenance
Initialize chat interface.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
orchestrator
|
Orchestrator
|
Orchestrator instance for handling conversations |
required |
display_message
Display a formatted message.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
role
|
str
|
Message role (user, assistant, system) |
required |
content
|
str
|
Message content |
required |
display_tool_execution
Display tool execution progress.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tool_name
|
str
|
Name of the tool being executed |
required |
status
|
str
|
Status (executing, success, error) |
required |
chat
Start interactive chat session.
Provides a conversational interface to vbagent functionality. The assistant can help with tasks like scanning questions, generating variants, creating DPPs, and more.
Examples:
# Start a chat session
vbagent chat
# Use a specific model
vbagent chat --model gpt-4
# Load previous conversation
vbagent chat --history conversation.json
# Save conversation on exit
vbagent chat --save-history conversation.json
Database Management
db
CLI commands for database management.
db
Database management for question bank.
Commands: init - Initialize database from directory insert - Insert problems into database update - Update existing question query - Query questions with filters stats - Show database statistics export - Export questions from database delete - Delete question by ID
delete
Delete question by ID (cascade deletes children).
Examples: vbagent db delete 42
init
Initialize empty database.
Creates database schema without inserting any questions. Use 'vbagent db insert' to add questions later.
Examples: vbagent db init # Create default database vbagent db init --db-path custom.db # Create custom database vbagent db init --force # Recreate existing database
insert
Insert problems into database.
Examples: vbagent db insert ./new_questions vbagent db insert ./questions --update-existing vbagent db insert ./questions --classify
query
query(db_path: str, subject: str, chapter: str, topic: str, difficulty: str, question_type: str, limit: int, output_format: str)
Query questions with filters.
Examples: vbagent db query --topic Kinematics vbagent db query --difficulty medium --subject physics vbagent db query --type passage --format json
Reference Management
ref
CLI commands for managing reference context files.
Provides commands to add, remove, list, and configure reference files stored in ~/.config/vbagent for use as context in LLM prompts.
add
Add a reference file to a category.
Arguments: CATEGORY Category to add to (tikz, latex, variants, problems) FILE Path to the file to add
Examples: vbagent ref add tikz my_diagram.tex vbagent ref add variants example.tex -n "numerical_example.tex" vbagent ref add latex formatting.tex -d "Standard formatting template"
disable
Disable context usage in prompts.
When disabled, reference files will not be included in prompts.
enable
Enable context usage in prompts.
When enabled, reference files will be included as examples in LLM prompts to improve output quality.
list_refs
List all reference files.
Examples: vbagent ref list vbagent ref list -c tikz
ref
Manage reference files for context.
Reference files are stored in ~/.config/vbagent/references/ and can be used as examples to improve LLM output quality.
Categories: tikz - TikZ/PGF code examples latex - LaTeX formatting examples variants - Variant generation examples problems - Example physics problems
Examples: vbagent ref add tikz diagram.tex vbagent ref add variants example.tex -d "Numerical variant" vbagent ref list vbagent ref list -c tikz vbagent ref remove tikz diagram.tex vbagent ref enable vbagent ref disable vbagent ref status
remove
Remove a reference file.
Arguments: CATEGORY Category of the reference NAME Name of the reference file
Examples: vbagent ref remove tikz diagram.tex vbagent ref remove variants example.tex
set_max
Set maximum examples per category.
Controls how many reference files from each category are included in prompts.
Arguments: MAX_EXAMPLES Maximum number of examples (1-20)
Examples: vbagent ref set-max 3 vbagent ref set-max 10
show
Show the content of a reference file.
Arguments: CATEGORY Category of the reference NAME Name of the reference file
Examples: vbagent ref show tikz diagram.tex
tikz_group
Manage TikZ references with metadata-based context.
TikZ references are stored with classification metadata (diagram_type, topic, subtopic) for intelligent context matching.
Commands: import - Import TikZ from processed problem list - List TikZ references remove - Remove a TikZ reference show - Show TikZ reference content status - Show TikZ reference statistics
Examples: vbagent ref tikz import agentic/scans/Problem_5.tex vbagent ref tikz import -d agentic/scans -r 1 10 vbagent ref tikz list vbagent ref tikz list --diagram-type pulley vbagent ref tikz status
tikz_import
Import TikZ references from processed problems.
Extracts TikZ code and loads classification metadata automatically. Can import a single file or a range of problems from a directory.
Arguments: PATH Path to scan file or scans directory
Examples: # Import single problem vbagent ref tikz import agentic/scans/Problem_5.tex
# Import range from directory
vbagent ref tikz import agentic/scans -r 1 10
# Import with custom tikz/classification directories
vbagent ref tikz import agentic/scans/Problem_5.tex -t agentic/tikz -c agentic/classifications
tikz_list
List TikZ references.
Examples: vbagent ref tikz list vbagent ref tikz list --diagram-type pulley vbagent ref tikz list -t mechanics
tikz_remove
Remove a TikZ reference.
Arguments: REF_ID ID of the reference to remove
Examples: vbagent ref tikz remove Problem_5
tikz_show
Show TikZ reference content.
Arguments: REF_ID ID of the reference to show
Examples: vbagent ref tikz show Problem_5
Configuration
config
CLI commands for configuring vbagent models.
Provides commands to view and set model configurations for different agents.
config
Configure vbagent models and settings.
View and modify model configurations for different agent types.
Agent Types: classifier - Image classification scanner - LaTeX extraction from images tikz - TikZ diagram generation idea - Concept extraction alternate - Alternate solution generation variant - Problem variant generation converter - Format conversion
Examples: vbagent config show vbagent config models vbagent config set scanner --model gpt-4o vbagent config set scanner -m gpt-4o vbagent config set variant --model o1-mini --reasoning medium vbagent config reset
debug
Enable or disable debug mode.
Debug mode prints detailed input/output for all agent calls.
Examples: vbagent config debug on # Enable debug mode vbagent config debug off # Disable debug mode vbagent config debug status # Show current status vbagent config debug on -w # Enable in workspace config
init
Initialize workspace config interactively.
Creates .vbagent.json in current directory with customized settings.
This is an alias for vbagent init.
Examples: vbagent config init # Interactive setup vbagent config init --quick # Only ask for subject vbagent config init --yes # Use all defaults vbagent config init --force # Overwrite existing
model_group
View or apply a model group.
Model groups are pre-configured sets of models for each agent, optimized per provider. Switching providers auto-applies the matching group, but you can also apply one manually.
Examples: vbagent config model-group # List all groups vbagent config model-group openai # Apply OpenAI group vbagent config model-group xai # Apply xAI group vbagent config model-group google -w # Apply Google group to workspace
provider
Set the API provider (openai, xai, google, or custom URL).
Switching providers auto-applies the matching model group so every agent gets the right model. Use --no-models to skip this.
Known Providers: openai - OpenAI (default, no base_url needed) xai - xAI Grok (https://api.x.ai/v1) google - Google Gemini (OpenAI-compatible endpoint)
Examples: vbagent config provider openai vbagent config provider xai --api-key xai-xxx vbagent config provider xai --workspace vbagent config provider xai --no-models # keep current models vbagent config provider --base-url https://custom.api/v1
set
Set model configuration for an agent type.
Arguments: AGENT_TYPE Agent to configure (classifier, scanner, tikz, etc.)
Examples: vbagent config set scanner --model gpt-4o vbagent config set variant --model o1-mini --reasoning medium vbagent config set default --model gpt-4.1 vbagent config set scanner -m gpt-4o --workspace # Save to .vbagent.json
subject
Set the subject for prompts.
Subjects: physics - Physics problems (default) chemistry - Chemistry problems mathematics - Mathematics problems biology - Biology problems
Examples: vbagent config subject chemistry vbagent config subject physics --workspace
Utilities
util
Utility commands for file management.
Provides helper commands for organizing and managing question files.
clean
Remove generated files and directories.
Examples: vbagent util clean --output # Remove agentic/ directory vbagent util clean --config # Remove .vbagent.json vbagent util clean --all # Remove everything vbagent util clean -a -y # Remove all without confirmation
count
Count files by type in a directory.
Examples: vbagent util count images/ vbagent util count . --recursive
list
List files ready for processing.
Shows files that can be processed with vbagent process.
Examples: vbagent util list images/ vbagent util list . --ext .tex
rename
rename(directory: str, prefix: str, start: int, ext: tuple, dry_run: bool, yes: bool, preserve_order: bool, shuffle: bool, lowercase: bool, uppercase: bool, pad: int)
Rename files to serialized format.
Renames files in a directory to a consistent format like: problem_1.png, problem_2.png, problem_3.png, etc.
Examples: vbagent util rename images/ # Rename to problem_N.png vbagent util rename . --prefix Q # q_1.png, q_2.png, ... vbagent util rename . --ext .tex # Rename .tex files vbagent util rename . --start 10 # Start from problem_10.png vbagent util rename images/ --dry-run # Preview changes vbagent util rename . --preserve-order # Keep existing numbers vbagent util rename . --shuffle # Randomize order vbagent util rename . --uppercase # Problem_1.png vbagent util rename . --pad 3 # problem_001.png
util
Utility commands for file management.
Commands: rename - Rename files to serialized format (Problem_1.png, etc.) count - Count files by type in a directory clean - Remove generated files (agentic/, .vbagent.json)
Examples: vbagent util rename images/ vbagent util rename . --prefix Question --ext .tex vbagent util count images/ vbagent util clean
Common Utilities
common
Common CLI utilities for interactive sessions.
Provides shared functionality for: - Diff display with Rich color coding - Interactive action prompts - Session summary display - Signal handling for graceful shutdown - LaTeX formatting - Editor integration