VBAgent

A multi-agent library and CLI for processing physics, chemistry, and mathematics question images. Supports classification, LaTeX extraction, TikZ diagram generation, solution generation, variant creation, paper orchestration, and LaTeX compilation.

📚 Documentation | 🐛 Issues | 💬 Discussions

Installation

pip install -e ".[dev]"

Requirements

• Python 3.12+
• API key for your provider (set as env variable)
• For compilation: pdflatex (TeX Live or MacTeX)

Supported Providers

Default Models (OpenAI)

Switch provider or model easily:

vbagent config provider xai              # Switch to xAI
vbagent config provider google           # Switch to Google
vbagent config provider openai           # Back to OpenAI
vbagent config set solution -m gpt-5.6-sol    # Override solution model
vbagent config set tikz -m gpt-5.6-sol        # Override tikz model
vbagent config set default -m gpt-5.6-luna    # Change global default

CLI Usage

Quick Start

vbagent init                              # Initialize workspace config
vbagent scan -i question.png -o out.tex   # Extract LaTeX
vbagent classify -i question.png          # Classify question type
vbagent tikz -i diagram.png -o diag.tex   # Generate TikZ
vbagent run -i question.png               # Full pipeline
vbagent solve -t scanned.tex -o solved.tex # Generate solutions from scanned TeX
vbagent solve -t scanned-problems/ -o solved-problems/ --no-diagram
vbagent solve -t scanned-problems/ --in-place --no-diagram --from 1 --to 5 --exclude 4,3

Commands

Paper Orchestrator

End-to-end paper generation workflow:

# Initialize a paper project
vbagent paper init physics --title "JEE Advanced 2025" --problems 4

# Generate problems from syllabus topics
vbagent paper generate /path/to/paper/

# Generate solutions for all problems
vbagent paper solve /path/to/paper/

# Generate hints
vbagent paper hint /path/to/paper/

# Compile to main.tex (stitches problems + solutions + hints + ideas + remarks)
vbagent paper compile /path/to/paper/

# Compile only solutions
vbagent paper compile /path/to/paper/ --only solutions

# Compile only hints
vbagent paper compile /path/to/paper/ --only hints

# Export zip for Overleaf
vbagent paper export /path/to/paper/

Paper directory structure:

paper_dir/
├── manifest.yaml          # Paper config (subject, title, problems)
├── main.tex               # Compiled output
├── scans/                 # Per-problem .tex files (problem + solution + hint + idea + remark)
│   ├── Problem_1.tex
│   ├── Problem_2.tex
│   └── ...
├── solutions/             # Raw solution .tex files
├── hints/                 # Raw hint .tex files
└── paper_export.zip       # Overleaf-ready zip

Configuration

vbagent config show                       # Show all agent configs
vbagent config models                     # List available models
vbagent config provider                   # Show current provider
vbagent config provider xai               # Switch to xAI (auto-applies model group)
vbagent config provider openai            # Switch back to OpenAI
vbagent config set scanner -m gpt-5.6-luna   # Override scanner model
vbagent config set default -m gpt-5.6-luna   # Change global default
vbagent config model-group                # List all model groups
vbagent config model-group openai         # Apply OpenAI model group
vbagent config subject chemistry          # Set subject
vbagent config log-level INFO             # Verbose JSON input/usage/output logs
vbagent config debug on                   # Add tracebacks + lifecycle JSONL
vbagent config reset                      # Reset to defaults

Config hierarchy: global (~/.config/vbagent/models.json) → workspace (.vbagent.json).

Agent logging defaults to verbose INFO output with JSON input, usage, and output panels for every agent. vbagent config debug on is an alias for log-level DEBUG; it adds tracebacks and writes metadata-only lifecycle events to .vbagent/logs/agent-events.jsonl. Set VBAGENT_LOG_FILE=/path/to/events.jsonl to persist lifecycle events at any log level, or VBAGENT_LOG_FILE=off to disable the DEBUG event file.

Supported Question Types

• mcq_sc — MCQ Single Correct
• mcq_mc — MCQ Multiple Correct
• assertion_reason — Assertion-Reason
• match — Match the Following (matrix match with codes)
• passage — Passage/Comprehension (paragraph MCQ)
• integer — Integer type (\ansint{N})
• subjective — Subjective/Numerical

Project Structure

vbagent/
├── __init__.py                          # Public API with lazy imports
├── config.py                            # Configuration (models, providers, subjects)
├── compile.py                           # LaTeX compilation, validation, verbose debug
├── cache.py                             # Pipeline cache (solutions, hints, problems)
├── tex.py                               # TeX formatting utilities (format_tex, center_wrap_tikz)
│
├── cli/                                 # CLI commands (Click-based, lazy-loaded)
│   ├── main.py                          # Entry point with SectionedGroup
│   ├── common.py                        # Shared utilities (panels, prompts, formatting)
│   ├── core/
│   │   ├── init.py                      # Workspace initialization
│   │   ├── classify.py                  # Classification command
│   │   ├── scan.py                      # LaTeX extraction command
│   │   ├── process.py                   # Full pipeline command
│   │   └── batch.py                     # Batch processing command
│   ├── generation/
│   │   ├── tikz.py                      # TikZ generation command
│   │   ├── fbd.py                       # FBD generation command
│   │   ├── idea.py                      # Concept extraction command
│   │   ├── alternate.py                 # Alternate solutions command
│   │   ├── variant.py                   # Variant generation command
│   │   └── convert.py                   # Format conversion command
│   ├── quality/
│   │   └── check.py                     # QA review command
│   ├── compilation/
│   │   └── compile_main.py              # LaTeX compile command + preamble
│   ├── management/
│   │   ├── config.py                    # Config management (provider, model-group, set)
│   │   ├── ref.py                       # Reference management
│   │   ├── db.py                        # Database management
│   │   ├── metadata.py                  # Metadata management
│   │   ├── export.py                    # Export command
│   │   ├── dpp.py                       # DPP command
│   │   ├── extans.py                    # Answer extraction
│   │   ├── screenshot.py                # Screenshot utilities
│   │   └── util.py                      # File utilities
│   ├── cache/
│   │   └── cache_commands.py            # Cache management commands
│   ├── interfaces/
│   │   ├── chat.py                      # Chat interface
│   │   ├── mcp.py                       # MCP server
│   │   └── ui.py                        # UI helpers
│   └── paper/
│       └── paper_commands.py            # Paper orchestrator CLI (init, generate, solve, hint, compile, export)
│
├── agents/                              # AI agent implementations
│   ├── base.py                          # Base agent (create, run, encode image)
│   ├── classifier.py                    # Backward-compatible classifier facade
│   ├── classification/                  # Classification system
│   │   ├── question_classifier.py       # Canonical image question classifier
│   │   ├── diagram_classifier.py        # Standalone diagram classification
│   │   ├── difficulty_assessor.py       # Difficulty assessment
│   │   ├── latex_classifier.py          # LaTeX classification
│   │   ├── taxonomy_classifier.py       # Taxonomy classification
│   │   ├── subject_classifier.py        # Standalone subject classification
│   │   └── schema_builder.py            # Schema builder
│   ├── content_generation/
│   │   ├── scanner.py                   # LaTeX extraction agent
│   │   ├── alternate.py                 # Alternate solution agent
│   │   ├── converter.py                 # Format converter agent
│   │   ├── idea.py                      # Concept extractor agent
│   │   ├── idea_generator.py            # Idea-to-problem generator
│   │   ├── idea_curator.py              # Idea-bank curator
│   │   ├── idea_combiner.py             # Multi-idea problem designer
│   │   ├── problem_combiner.py          # Multi-problem combiner
│   │   └── solution/
│   │       └── __init__.py              # Solution agent (routes by subject × question_type)
│   ├── diagram/                         # TikZ diagram agents
│   │   ├── base.py                      # Base diagram agent (600s timeout, style discipline)
│   │   ├── tikz.py                      # Generic TikZ agent
│   │   ├── tikz_router.py              # TikZ agent routing
│   │   ├── tikz_checker.py             # TikZ validation agent
│   │   ├── mcq_option_coordinator.py   # MCQ option diagram coordinator
│   │   ├── physics/
│   │   │   ├── fbd.py                   # Free body diagram
│   │   │   ├── circuit.py               # Circuit diagram
│   │   │   ├── graph.py                 # Physics graph
│   │   │   └── optics.py               # Optics diagram
│   │   ├── chemistry/
│   │   │   ├── organic_structure.py     # Organic structure
│   │   │   ├── organic_orchestrator.py  # Organic multi-step orchestrator
│   │   │   ├── organic_simple.py        # Simple organic
│   │   │   ├── organic_complex.py       # Complex organic
│   │   │   ├── organic_functional.py    # Functional group
│   │   │   ├── organic_mechanism.py     # Reaction mechanism
│   │   │   ├── organic_multistep.py     # Multi-step synthesis
│   │   │   ├── organic_stereo.py        # Stereochemistry
│   │   │   ├── chemical_equation.py     # Chemical equation
│   │   │   ├── energy_diagram.py        # Energy diagram
│   │   │   ├── lewis_structure.py       # Lewis structure
│   │   │   ├── orbital.py              # Orbital diagram
│   │   │   └── reaction_mechanism.py    # Reaction mechanism
│   │   └── mathematics/
│   │       ├── coordinate_geometry.py   # Coordinate geometry
│   │       ├── function_graph.py        # Function graph
│   │       ├── geometric_figure.py      # Geometric figure
│   │       ├── number_line.py           # Number line
│   │       └── venn_diagram.py          # Venn diagram
│   ├── orchestration/
│   │   ├── problem_orchestrator.py      # Problem orchestrator
│   │   └── solution_orchestrator.py     # Solution orchestrator
│   ├── quality/
│   │   ├── base.py                      # Base quality agent
│   │   ├── reviewer.py                  # QA reviewer
│   │   ├── solution_checker.py          # Solution checker
│   │   ├── grammar_checker.py           # Grammar checker
│   │   ├── clarity_checker.py           # Clarity checker
│   │   ├── format_checker.py            # Format checker
│   │   └── latex_fixer.py              # LaTeX fixer
│   ├── variants/
│   │   ├── variant.py                   # Single variant generator
│   │   ├── cross_topic.py              # Cross-topic variant
│   │   └── multi_context_variant.py    # Multi-context variant
│   ├── selection/
│   │   └── selector.py                 # Problem selector
│   └── metadata/
│       └── enricher.py                 # Metadata enricher
│
├── prompts/                             # LLM prompt templates
│   ├── classification/
│   │   ├── classifier.py                # Base classifier prompt
│   │   ├── question_classifier.py       # Question classifier prompt
│   │   ├── diagram_classifier.py        # Diagram classifier prompt
│   │   ├── question_types.py            # Question type definitions
│   │   └── taxonomy.py                  # Taxonomy definitions
│   ├── content_generation/
│   │   ├── alternate.py                 # Alternate solution prompt
│   │   ├── converter.py                 # Converter prompt
│   │   ├── idea.py                      # Idea extraction prompt
│   │   ├── idea_generator.py            # Idea generator prompt
│   │   ├── idea_curator.py              # Idea curator prompt
│   │   ├── idea_combiner.py             # Idea combiner prompt
│   │   ├── problem_combiner.py           # Problem combiner prompt
│   │   ├── scanner/                     # Scanner prompts (per subject × question type)
│   │   │   ├── _shared.py               # Shared scanner rules
│   │   │   ├── physics/
│   │   │   │   ├── common.py            # Physics common rules
│   │   │   │   ├── formatting_rules.py  # Physics formatting
│   │   │   │   ├── mcq_sc.py, mcq_mc.py, subjective.py
│   │   │   │   ├── assertion_reason.py, match.py, passage.py
│   │   │   │   ├── problem_only.py, solution_only.py
│   │   │   │   └── __init__.py          # Router
│   │   │   ├── chemistry/               # (same structure as physics)
│   │   │   └── mathematics/             # (same structure as physics)
│   │   └── solution/                    # Solution prompts (per subject × question type)
│   │       ├── __init__.py              # Top-level router
│   │       ├── physics/
│   │       │   ├── common.py            # Physics solution rules
│   │       │   ├── mcq_sc.py, mcq_mc.py, subjective.py
│   │       │   ├── assertion_reason.py, match.py, passage.py
│   │       │   └── __init__.py          # Router
│   │       ├── chemistry/               # (same structure as physics)
│   │       └── mathematics/             # (same structure as physics)
│   ├── diagram/
│   │   ├── _style_discipline.py         # TikZ style rules (no colors, no inline overrides)
│   │   ├── tikz_checker.py              # TikZ checker prompt
│   │   ├── physics/
│   │   │   ├── fbd.py, circuit.py, graph.py, optics.py, generic.py
│   │   │   └── __init__.py
│   │   ├── chemistry/
│   │   │   ├── organic_structure.py, organic_simple.py, organic_complex.py
│   │   │   ├── organic_functional.py, organic_mechanism.py, organic_multistep.py
│   │   │   ├── organic_stereo.py, chemical_equation.py, energy_diagram.py
│   │   │   ├── lewis_structure.py, orbital.py, reaction_mechanism.py
│   │   │   └── __init__.py
│   │   └── mathematics/
│   │       ├── coordinate_geometry.py, function_graph.py, geometric_figure.py
│   │       ├── number_line.py, venn_diagram.py
│   │       └── __init__.py
│   ├── quality/
│   │   ├── reviewer.py, solution_checker.py, grammar_checker.py
│   │   ├── clarity_checker.py, format_checker.py
│   │   └── __init__.py
│   ├── variants/
│   │   ├── numerical.py, context.py, conceptual.py
│   │   ├── conceptual_calculus.py, cross_topic.py, multi_context.py
│   │   └── __init__.py
│   └── subjects/
│       └── __init__.py                  # Subject-specific context
│
├── models/                              # Pydantic data models
│   ├── classification.py                # Classification models
│   ├── content.py                       # Content models
│   ├── diagram.py                       # Diagram models
│   ├── diff.py                          # Diff models
│   ├── metadata.py                      # Metadata models
│   ├── orchestration.py                 # Orchestration models
│   ├── pipeline.py                      # Pipeline models
│   ├── quality.py                       # Quality models
│   ├── review.py                        # Review models
│   ├── solution.py                      # Solution models
│   ├── version_store.py                 # Version store models
│   └── workflow.py                      # Workflow models
│
├── paper/                               # Paper orchestrator
│   ├── __init__.py
│   ├── models.py                        # Paper data models
│   ├── manifest.py                      # Manifest YAML handling
│   ├── syllabus.py                      # Syllabus topic definitions
│   ├── generator.py                     # Problem generation
│   ├── orchestrator.py                  # Paper orchestrator (compile, export, assemble)
│   └── qa.py                            # Paper QA
│
├── pipeline/                            # Processing pipeline
│   ├── __init__.py
│   ├── io.py                            # Pipeline I/O
│   ├── runner.py                        # Pipeline runner
│   └── stages.py                        # Pipeline stages
│
├── database/                            # SQLite question bank
│   ├── store.py                         # QuestionDatabase
│   ├── extractor.py                     # ContentExtractor
│   ├── reconstructor.py                 # LaTeX reconstruction
│   └── metadata_helper.py              # Agent metadata population
│
├── references/                          # Reference context management
│   ├── store.py                         # Reference store
│   ├── context.py                       # Context builder
│   ├── tikz_store.py                    # TikZ reference store
│   └── samples/                         # Sample references
│       ├── physics/                     # assertion_reason.tex, mcq_mc.tex, mcq_sc.tex, subjective.tex
│       ├── chemistry/                   # mcq_mc.tex, mcq_sc.tex, subjective.tex
│       └── mathematics/                 # mcq_mc.tex, mcq_sc.tex, subjective.tex
│
├── storage/                             # Content storage
│   ├── content_cache.py                 # Content cache
│   └── metadata_manager.py             # Metadata manager
│
├── orchestrator/                        # Chat orchestrator
│   ├── conversation.py                  # Conversation handler
│   ├── tools.py                         # Tool definitions
│   └── tool_wrappers.py               # Tool wrappers
│
├── dpp/
│   └── builder.py                       # DPP builder
│
├── export/
│   └── exporter.py                      # LaTeX exporter
│
├── mcp/
│   └── server.py                        # MCP server
│
├── metadata/
│   └── store.py                         # Metadata store
│
├── templates/
│   └── agentic_context.py              # CONTEXT.md generator
│
├── ui/                                  # Terminal UI
│   ├── components.py                    # UI components
│   ├── logging.py                       # Logging
│   ├── styles.py                        # Styles
│   └── tables.py                        # Tables
│
└── utils/
    ├── formatting.py                    # Formatting utilities
    └── latex.py                         # LaTeX utilities

tests/
├── agents/
│   ├── classification/                  # test_classification.py, test_database.py, test_models.py, test_router.py
│   ├── content_generation/              # test_alternate.py, test_converter.py, test_idea.py, test_scanner.py
│   ├── diagram/                         # test_tikz.py
│   ├── metadata/                        # test_metadata.py
│   ├── orchestration/                   # test_orchestrator.py
│   ├── quality/                         # test_review.py
│   ├── selection/                       # test_selector.py
│   └── variants/                        # test_variant.py
├── cli/
│   ├── core/                            # test_batch.py, test_process.py
│   ├── interfaces/                      # test_chat_cli.py, test_chat_interface.py, test_mcp_server.py
│   └── management/                      # test_config.py, test_export_tools.py, test_export.py
├── integration/                         # test_context.py, test_dpp_builder.py, test_import_performance.py, ...
├── models/                              # test_version_store.py
├── paper/                               # test_cli.py, test_generator.py, test_manifest.py, test_models.py, ...
├── ui/                                  # test_ui_components.py
└── utils/                               # test_formatting.py, test_latex.py, test_tex_parser.py

LaTeX Compilation

The -c / --compile flag validates generated LaTeX by compiling with pdflatex. If compilation fails, the compile-fixer agent automatically attempts to fix errors (up to 2 retries).

Compile Preamble

• fourier[upright] for fonts
• \everymath{\displaystyle} for display-style math
• amsmath, amssymb, amsthm, mathtools
• tikz with libraries: calc, decorations, patterns, arrows.meta, positioning, shapes, intersections, angles, quotes
• circuitikz (american style), pgfplots (compat=1.18)
• tasks (MCQ options), enumitem
• mhchem, chemfig (chemistry only)
• Auto-detected packages from .tex file content

Environment Definitions

License

MIT