vbagent 0.1.1__tar.gz → 0.2.1__tar.gz

vbagent-0.2.1/PKG-INFO

@@ -0,0 +1,1049 @@
+Metadata-Version: 2.3
+Name: vbagent
+Version: 0.2.1
+Summary: Physics question processing library and CLI - classification, LaTeX extraction, variant generation
+Author: vaibhavblayer
+Author-email: vaibhavblayer@gmail.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: all
+Provides-Extra: cli
+Provides-Extra: dev
+Requires-Dist: click (>=8.1.0) ; extra == "all"
+Requires-Dist: click (>=8.1.0) ; extra == "cli"
+Requires-Dist: click (>=8.1.0) ; extra == "dev"
+Requires-Dist: hypothesis (>=6.0.0) ; extra == "dev"
+Requires-Dist: openai-agents (>=0.6.2)
+Requires-Dist: pillow (>=10.0.0)
+Requires-Dist: pydantic (>=2.0.0)
+Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
+Requires-Dist: rich (>=13.0.0) ; extra == "all"
+Requires-Dist: rich (>=13.0.0) ; extra == "cli"
+Requires-Dist: rich (>=13.0.0) ; extra == "dev"
+Description-Content-Type: text/markdown
+
+# VBAgent
+
+A multi-agent library and CLI tool for processing physics question images. Supports classification, LaTeX extraction, TikZ diagram generation, variant creation, and format conversion.
+
+## Installation
+
+### From PyPI
+
+```bash
+# Full installation (library + CLI)
+pip install vbagent[all]
+
+# Library only (no CLI dependencies)
+pip install vbagent
+
+# CLI only
+pip install vbagent[cli]
+```
+
+### From Source
+
+```bash
+# Clone the repository
+git clone https://github.com/vaibhavblayer/vbagent.git
+cd vbagent
+
+# Install with pip
+pip install .
+
+# Or install in development mode
+pip install -e ".[dev]"
+
+# Or using Poetry
+poetry install
+```
+
+## Requirements
+
+- Python 3.12+
+- OpenAI API key (set as `OPENAI_API_KEY` environment variable)
+
+## Library Usage
+
+VBAgent can be used as a Python library in your own projects:
+
+### Quick Start
+
+```python
+from vbagent import classify, scan, generate_variant, generate_tikz
+from vbagent.models import ClassificationResult, ScanResult
+
+# Classify an image
+classification = classify("question.png")
+print(f"Type: {classification.question_type}")
+print(f"Topic: {classification.topic}")
+
+# Scan with classification
+scan_result = scan("question.png", classification)
+print(f"LaTeX: {scan_result.latex}")
+
+# Generate a variant
+variant = generate_variant(scan_result.latex, "numerical")
+print(f"Variant: {variant}")
+
+# Generate TikZ diagram
+tikz = generate_tikz("A free body diagram showing forces on a block")
+print(f"TikZ: {tikz}")
+```
+
+### Configuration
+
+```python
+from vbagent import get_config, set_config, VBAgentConfig
+
+# Get current config
+config = get_config()
+
+# Modify model settings
+config.scanner.model = "gpt-5.2"
+config.scanner.reasoning_effort = "high"
+
+# Apply changes
+set_config(config)
+
+# Or configure specific agent
+from vbagent.config import AgentModelConfig
+config.variant = AgentModelConfig(
+    model="gpt-5.1",
+    reasoning_effort="medium",
+    temperature=0.7
+)
+set_config(config)
+```
+
+### Available Functions
+
+```python
+# Classification
+from vbagent import classify
+result = classify("image.png")  # Returns ClassificationResult
+
+# Scanning
+from vbagent import scan, scan_with_type
+result = scan("image.png", classification)  # Returns ScanResult
+result = scan_with_type("image.png", "mcq_sc")  # Skip classification
+
+# Variants
+from vbagent import (
+    generate_variant,
+    generate_numerical_variant,
+    generate_context_variant,
+    generate_conceptual_variant,
+    generate_calculus_variant,
+)
+variant = generate_variant(latex, "numerical")
+variant = generate_numerical_variant(latex)
+
+# TikZ
+from vbagent import generate_tikz, validate_tikz_output
+tikz = generate_tikz("description", image_path="ref.png")
+is_valid = validate_tikz_output(tikz)
+
+# Ideas
+from vbagent import extract_ideas, generate_idea_latex
+ideas = extract_ideas(problem_latex, solution_latex)  # Returns IdeaResult
+idea_latex = generate_idea_latex(full_content)
+
+# Alternates
+from vbagent import generate_alternate
+alternate = generate_alternate(problem, solution)
+
+# QA Checkers
+from vbagent import check_solution, check_grammar, check_clarity, check_tikz
+passed, summary, corrected = check_solution(content)
+passed, summary, corrected = check_grammar(content)
+passed, summary, corrected = check_clarity(content)
+passed, summary, corrected = check_tikz(content)
+
+# Review
+from vbagent import review_problem, review_problem_sync, ProblemContext
+context = ProblemContext(...)
+result = review_problem_sync(context)  # Returns ReviewResult
+```
+
+### Models
+
+```python
+from vbagent.models import (
+    ClassificationResult,
+    ScanResult,
+    IdeaResult,
+    PipelineResult,
+    ReviewResult,
+    Suggestion,
+    ReviewIssueType,
+)
+
+# Classification result fields
+classification.question_type  # mcq_sc, mcq_mc, subjective, etc.
+classification.difficulty     # easy, medium, hard
+classification.topic          # kinematics, thermodynamics, etc.
+classification.has_diagram    # bool
+classification.diagram_type   # graph, circuit, free_body, etc.
+
+# Scan result fields
+scan_result.latex
+scan_result.has_diagram
+scan_result.raw_diagram_description
+
+# Idea result fields
+ideas.concepts      # List of physics concepts
+ideas.formulas      # List of key formulas
+ideas.techniques    # List of problem-solving techniques
+ideas.difficulty_factors
+```
+
+### Prompts
+
+Access and customize prompts:
+
+```python
+from vbagent.prompts import (
+    get_scanner_prompt,
+    get_variant_prompt,
+    CLASSIFIER_PROMPT,
+    IDEA_PROMPT,
+    TIKZ_PROMPT,
+)
+
+# Get scanner prompt for question type
+prompt = get_scanner_prompt("mcq_sc")
+
+# Get variant prompts
+system_prompt, user_template = get_variant_prompt("numerical")
+```
+
+### References
+
+Manage reference context:
+
+```python
+from vbagent.references import (
+    ReferenceStore,
+    TikZStore,
+    get_context_prompt_section,
+)
+
+# Reference store
+store = ReferenceStore.get_instance()
+results = store.search("query")
+
+# TikZ store
+tikz_store = TikZStore.get_instance()
+context = tikz_store.get_context_for_classification(classification)
+
+# Get context for prompts
+context = get_context_prompt_section("latex")
+```
+
+### Low-Level Agent Access
+
+For advanced usage:
+
+```python
+from vbagent.agents import (
+    create_agent,
+    run_agent,
+    run_agent_sync,
+    encode_image,
+    create_image_message,
+)
+
+# Create custom agent
+agent = create_agent(
+    name="MyAgent",
+    instructions="Your system prompt",
+    agent_type="scanner",  # Uses scanner model config
+)
+
+# Run agent
+result = run_agent_sync(agent, "Your input")
+
+# With image
+message = create_image_message("image.png", "Analyze this")
+result = run_agent_sync(agent, message)
+```
+
+## CLI Usage
+
+## Project Structure
+
+```
+vbagent/
+├── pyproject.toml              # Project config & dependencies
+├── poetry.lock                 # Locked dependency versions
+├── README.md                   # Documentation
+│
+├── vbagent/                    # Main package
+│   ├── __init__.py
+│   ├── config.py               # Configuration handling
+│   │
+│   ├── cli/                    # CLI commands (Click-based)
+│   │   ├── main.py             # Entry point
+│   │   ├── common.py           # Shared CLI utilities
+│   │   ├── scan.py             # LaTeX extraction command
+│   │   ├── classify.py         # Classification command
+│   │   ├── tikz.py             # TikZ generation command
+│   │   ├── variant.py          # Variant generation command
+│   │   ├── alternate.py        # Alternate solutions command
+│   │   ├── idea.py             # Concept extraction command
+│   │   ├── convert.py          # Format conversion command
+│   │   ├── process.py          # Full pipeline command
+│   │   ├── batch.py            # Batch processing command
+│   │   ├── check.py            # QA review command
+│   │   ├── ref.py              # Reference management command
+│   │   └── config.py           # Config management command
+│   │
+│   ├── agents/                 # AI agent implementations
+│   │   ├── base.py             # Base agent class
+│   │   ├── scanner.py          # LaTeX extraction agent
+│   │   ├── classifier.py       # Question type classifier
+│   │   ├── tikz.py             # TikZ diagram generator
+│   │   ├── variant.py          # Single variant generator
+│   │   ├── multi_variant.py    # Multi-context variant generator
+│   │   ├── alternate.py        # Alternate solution generator
+│   │   ├── idea.py             # Concept extractor
+│   │   ├── converter.py        # Format converter
+│   │   ├── reviewer.py         # QA reviewer
+│   │   ├── selector.py         # Problem selector
+│   │   ├── solution_checker.py # Solution correctness checker
+│   │   ├── grammar_checker.py  # Grammar checker
+│   │   ├── clarity_checker.py  # Clarity checker
+│   │   └── tikz_checker.py     # TikZ code checker
+│   │
+│   ├── prompts/                # LLM prompt templates
+│   │   ├── classifier.py       # Classification prompts
+│   │   ├── tikz.py             # TikZ generation prompts
+│   │   ├── alternate.py        # Alternate solution prompts
+│   │   ├── idea.py             # Concept extraction prompts
+│   │   ├── converter.py        # Conversion prompts
+│   │   ├── reviewer.py         # Review prompts
+│   │   ├── solution_checker.py # Solution check prompts
+│   │   ├── grammar_checker.py  # Grammar check prompts
+│   │   ├── clarity_checker.py  # Clarity check prompts
+│   │   ├── tikz_checker.py     # TikZ check prompts
+│   │   │
+│   │   ├── scanner/            # Question-type-specific scan prompts
+│   │   │   ├── common.py       # Shared scanner prompts
+│   │   │   ├── mcq_sc.py       # MCQ single correct
+│   │   │   ├── mcq_mc.py       # MCQ multiple correct
+│   │   │   ├── assertion_reason.py
+│   │   │   ├── match.py        # Match the following
+│   │   │   ├── passage.py      # Passage/comprehension
+│   │   │   └── subjective.py   # Subjective/numerical
+│   │   │
+│   │   └── variants/           # Variant generation prompts
+│   │       ├── numerical.py    # Numerical variant prompts
+│   │       ├── context.py      # Context variant prompts
+│   │       ├── conceptual.py   # Conceptual variant prompts
+│   │       ├── conceptual_calculus.py
+│   │       └── multi_context.py
+│   │
+│   ├── models/                 # Pydantic data models
+│   │   ├── batch.py            # Batch processing state
+│   │   ├── classification.py   # Question classification
+│   │   ├── scan.py             # Scan results
+│   │   ├── idea.py             # Extracted concepts
+│   │   ├── review.py           # Review results
+│   │   ├── diff.py             # Diff utilities
+│   │   ├── pipeline.py         # Pipeline state
+│   │   └── version_store.py    # Version tracking
+│   │
+│   ├── references/             # Reference context management
+│   │   ├── store.py            # Reference store
+│   │   ├── context.py          # Context builder
+│   │   └── tikz_store.py       # TikZ reference store
+│   │
+│   └── templates/              # Output templates
+│       └── agentic_context.py  # CONTEXT.md generator
+│
+├── prompt_kinds/               # Question type definitions
+│   ├── mcq_sc_type.py          # MCQ single correct
+│   ├── mcq_mc_type.py          # MCQ multiple correct
+│   ├── assertion_reason_type.py
+│   ├── match_type.py           # Match the following
+│   ├── passage_type.py         # Passage/comprehension
+│   ├── subjective_type.py      # Subjective/numerical
+│   ├── variant_numerical.py    # Numerical variant type
+│   ├── variant_context.py      # Context variant type
+│   ├── variant_conceptual.py   # Conceptual variant type
+│   ├── variant_conceptual_calculus.py
+│   └── variant_numerical_context.py
+│
+└── tests/                      # Test suite
+    ├── test_scanner.py
+    ├── test_classification.py
+    ├── test_tikz.py
+    ├── test_variant.py
+    ├── test_alternate.py
+    ├── test_idea.py
+    ├── test_converter.py
+    ├── test_batch.py
+    ├── test_process.py
+    ├── test_review.py
+    ├── test_selector.py
+    ├── test_context.py
+    ├── test_reference_store.py
+    ├── test_version_store.py
+    └── test_prompt_organization.py
+```
+
+## Command Reference
+
+### classify
+
+Classify physics question image type.
+
+```bash
+vbagent classify -i <image> [-o <output.json>] [--json]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --image` | Path to physics question image (required) |
+| `-o, --output` | Output JSON file path |
+| `--json` | Output result as JSON to stdout |
+
+### scan
+
+Extract LaTeX from physics question image.
+
+```bash
+vbagent scan -i <image> [-t <tex>] [--type <type>] [-o <output.tex>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --image` | Path to physics question image |
+| `-t, --tex` | Path to existing TeX file (for re-processing) |
+| `--type` | Override question type: `mcq_sc`, `mcq_mc`, `subjective`, `assertion_reason`, `passage`, `match` |
+| `-o, --output` | Output TeX file path |
+
+### tikz
+
+Generate TikZ/PGF code for diagrams.
+
+```bash
+vbagent tikz [-i <image>] [-d <description>] [--ref <dir>...] [-o <output.tex>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --image` | Path to diagram image |
+| `-d, --description` | Text description of diagram to generate |
+| `--ref` | Reference directories (can be used multiple times) |
+| `-o, --output` | Output TeX file path |
+
+### idea
+
+Extract physics concepts and ideas from problems.
+
+```bash
+vbagent idea -t <tex> [-o <output.json>] [--json]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-t, --tex` | Path to TeX file with problem and solution (required) |
+| `-o, --output` | Output JSON file path |
+| `--json` | Output result as JSON to stdout |
+
+### alternate
+
+Generate alternative solution methods.
+
+```bash
+vbagent alternate -t <tex> [--ideas <ideas.json>] [-n <count>] [-o <output.tex>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-t, --tex` | Path to TeX file with problem and solution (required) |
+| `--ideas` | Path to ideas JSON file for context |
+| `-n, --count` | Number of alternate solutions (default: 1) |
+| `-o, --output` | Output TeX file path |
+
+### variant
+
+Generate problem variants with controlled modifications.
+
+```bash
+vbagent variant [-i <image>] [-t <tex>] --type <type> [-r <start> <end>] [-n <count>] [--context <file>...] [--ideas <ideas.json>] [-o <output.tex>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --image` | Image file (will be scanned first) |
+| `-t, --tex` | TeX file containing problem(s) |
+| `--type` | Variant type: `numerical`, `context`, `conceptual`, `calculus`, `multi` (required) |
+| `-r, --range` | Range of items to process (1-based inclusive) |
+| `-n, --count` | Number of variants per problem (default: 1) |
+| `--context` | Additional context files for multi variant |
+| `--ideas` | Path to ideas JSON file |
+| `-o, --output` | Output TeX file path |
+
+### convert
+
+Convert physics questions between formats.
+
+```bash
+vbagent convert [-i <image>] [-t <tex>] [--from <format>] --to <format> [-o <output.tex>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --image` | Path to physics question image |
+| `-t, --tex` | Path to TeX file |
+| `--from` | Source format (auto-detected if not specified) |
+| `--to` | Target format: `mcq_sc`, `mcq_mc`, `subjective`, `integer` (required) |
+| `-o, --output` | Output TeX file path |
+
+### process
+
+Full pipeline: Classify → Scan → TikZ → Ideas → Variants.
+
+```bash
+vbagent process [-i <image>] [-t <tex>] [-r <start> <end>] [--variants <types>] [--alternate] [--ideas] [--ref <dir>...] [-o <output>] [--context] [-p <workers>]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --image` | Image file to process |
+| `-t, --tex` | TeX file containing problems |
+| `-r, --range` | Range to process (1-based inclusive) |
+| `--variants` | Variant types (comma-separated) |
+| `--alternate` | Generate alternate solutions |
+| `--ideas` | Extract physics concepts |
+| `--ref` | Reference directories for TikZ |
+| `-o, --output` | Output directory (default: `agentic`) |
+| `--context/--no-context` | Use reference context (default: yes) |
+| `-p, --parallel` | Parallel workers (default: 1, max: 10) |
+
+### batch
+
+Batch processing with resume capability.
+
+```bash
+# Initialize batch
+vbagent batch init [-i <images_dir>] [-o <output>] [--variants <types>] [--alternate] [--context]
+
+# Continue processing
+vbagent batch continue [--reset-failed]
+
+# Check status
+vbagent batch status
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `init` | Initialize and start batch processing |
+| `continue` | Resume from where you left off |
+| `status` | Show current progress |
+
+#### batch init options
+
+| Option | Description |
+|--------|-------------|
+| `-i, --images-dir` | Directory containing images (default: `./images`) |
+| `-o, --output` | Output directory (default: `agentic`) |
+| `--variants` | Variant types (default: all) |
+| `--alternate/--no-alternate` | Generate alternates (default: yes) |
+| `--context/--no-context` | Use reference context (default: yes) |
+
+### check
+
+QA review with interactive approval workflow.
+
+```bash
+# Start review session
+vbagent check run [-c <count>] [-p <problem_id>] [-d <dir>]
+
+# View history
+vbagent check history [-p <problem_id>] [-f <file>] [-n <limit>]
+
+# Apply suggestion
+vbagent check apply <version_id> [-e]
+
+# Resume session
+vbagent check resume <session_id>
+
+# Check/generate TikZ diagrams
+vbagent check tikz [-d <dir>] [-c <count>] [--patch] [--ref-type <type>]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `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 existing TikZ or generate from `\input{diagram}` placeholder |
+| `apply` | Apply a stored suggestion |
+| `history` | View suggestion history |
+| `resume` | Resume interrupted session |
+| `stats` | View review statistics |
+
+#### check tikz options
+
+| Option | Description |
+|--------|-------------|
+| `-d, --dir` | Directory or file to check (default: agentic) |
+| `-c, --count` | Number of files to process (default: 5) |
+| `-p, --problem-id` | Check specific problem by ID |
+| `-i, --images-dir` | Directory containing images (auto-discovered if not set) |
+| `--only-tikz` | Only check files with existing TikZ code |
+| `--reset` | Re-check all files |
+| `--patch` | Use apply_patch mode for precise edits |
+| `--ref-type` | Filter references by diagram type (circuit, free_body, etc.) |
+| `--prompt` | Additional instructions for the checker |
+
+### ref
+
+Manage reference context files.
+
+```bash
+# Add reference
+vbagent ref add <category> <file> [-n <name>] [-d <description>]
+
+# Remove reference
+vbagent ref remove <category> <name>
+
+# List references
+vbagent ref list [-c <category>]
+
+# Show reference content
+vbagent ref show <category> <name>
+
+# Enable/disable context
+vbagent ref enable
+vbagent ref disable
+
+# Show status
+vbagent ref status
+
+# Set max examples
+vbagent ref set-max <count>
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `add` | Add a reference file to a category |
+| `remove` | Remove a reference file |
+| `list` | List all reference files |
+| `show` | Show content of a reference file |
+| `enable` | Enable context usage in prompts |
+| `disable` | Disable context usage |
+| `status` | Show context configuration |
+| `set-max` | Set maximum examples per category |
+
+Categories: `tikz`, `latex`, `variants`, `problems`
+
+#### ref tikz (TikZ references with metadata)
+
+```bash
+# Import from processed problem
+vbagent ref tikz import <path> [-r <start> <end>] [-t <tikz_dir>] [-c <class_dir>]
+
+# List TikZ references
+vbagent ref tikz list [--diagram-type <type>] [--topic <topic>]
+
+# Remove TikZ reference
+vbagent ref tikz remove <ref_id>
+
+# Show TikZ reference
+vbagent ref tikz show <ref_id>
+
+# Show statistics
+vbagent ref tikz status
+```
+
+### config
+
+Configure models and settings.
+
+```bash
+# Show current config
+vbagent config show
+
+# Set agent config
+vbagent config set <agent_type> [--model <model>] [--reasoning <level>] [--temperature <temp>] [--max-tokens <tokens>]
+
+# Reset to defaults
+vbagent config reset
+
+# List available models
+vbagent config models
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `show` | Show current model configuration |
+| `set` | Set model configuration for an agent |
+| `reset` | Reset all configurations to defaults |
+| `models` | List available models |
+
+Agent types: `classifier`, `scanner`, `tikz`, `idea`, `alternate`, `variant`, `converter`, `default`
+
+Reasoning levels: `low`, `medium`, `high`, `xhigh`
+
+## CLI Usage
+
+### Quick Start
+
+```bash
+# Scan a physics question image to LaTeX
+vbagent scan -i question.png -o output.tex
+
+# Classify a question type
+vbagent classify -i question.png
+
+# Generate TikZ diagram from image
+vbagent tikz -i diagram.png -o diagram.tex
+
+# Generate problem variants
+vbagent variant -t problem.tex -o variants.tex
+```
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `classify` | Classify physics question image type |
+| `scan` | Extract LaTeX from question image |
+| `tikz` | Generate TikZ/PGF code for diagrams |
+| `idea` | Extract physics concepts and ideas |
+| `alternate` | Generate alternative solutions |
+| `variant` | Generate problem variants (numerical, conceptual, context) |
+| `convert` | Convert between question formats |
+| `process` | Run full processing pipeline |
+| `batch` | Batch process multiple images with resume capability |
+| `ref` | Manage reference context files |
+| `config` | Configure models and settings |
+| `check` | QA review with interactive approval |
+
+### Batch Processing
+
+Process multiple images with automatic resume on interruption:
+
+```bash
+# Initialize batch processing
+vbagent batch init -i ./images -o ./output
+
+# Continue processing (resumes from where it left off)
+vbagent batch continue
+
+# Check status
+vbagent batch status
+```
+
+### Full Pipeline
+
+Process a single image through the complete pipeline:
+
+```bash
+# Basic processing (classify + scan + tikz)
+vbagent process -i question.png
+
+# With ideas extraction
+vbagent process -i question.png --ideas
+
+# With alternate solutions
+vbagent process -i question.png --alternate
+
+# With variant generation
+vbagent process -i question.png --variants numerical,context
+
+# Full pipeline with all features
+vbagent process -i question.png --ideas --alternate --variants numerical,context,conceptual
+```
+
+Process a range of images:
+
+```bash
+# Process Problem_1.png through Problem_5.png
+vbagent process -i images/Problem_1.png -r 1 5
+
+# Process range with parallel workers (faster)
+vbagent process -i images/Problem_1.png -r 1 10 --parallel 3
+
+# Process range with all features
+vbagent process -i images/Problem_1.png -r 1 5 --ideas --alternate --variants numerical
+```
+
+Process TeX file with multiple items:
+
+```bash
+# Process items 1-5 from a TeX file
+vbagent process -t problems.tex --range 1 5
+
+# With alternate solutions and ideas
+vbagent process -t problems.tex --range 1 5 --alternate --ideas
+```
+
+Custom output directory:
+
+```bash
+vbagent process -i question.png -o ./my_output
+```
+
+#### Process Command Options
+
+| Option | Description |
+|--------|-------------|
+| `-i, --image` | Image file to process |
+| `-t, --tex` | TeX file containing problems |
+| `-r, --range` | Range of items to process (1-based, inclusive) |
+| `--variants` | Variant types (comma-separated: numerical,context,conceptual,calculus) |
+| `--alternate` | Generate alternate solutions |
+| `--ideas` | Extract physics concepts |
+| `--ref` | Reference directories for TikZ |
+| `-o, --output` | Output directory (default: agentic) |
+| `--context` | Use reference context (default: yes) |
+| `-p, --parallel` | Parallel workers for batch (default: 1, max: 10) |
+
+#### Output Structure
+
+```
+agentic/
+├── scans/problem_1.tex           # Extracted LaTeX
+├── classifications/problem_1.json # Question metadata
+├── tikz/problem_1.tex            # Generated TikZ diagrams
+├── ideas/problem_1.json          # Physics concepts (if --ideas)
+├── alternates/problem_1.tex      # Alternate solutions (if --alternate)
+├── variants/
+│   ├── numerical/problem_1.tex   # Numerical variants
+│   ├── context/problem_1.tex     # Context variants
+│   └── conceptual/problem_1.tex  # Conceptual variants
+└── CONTEXT.md                    # Documentation for AI agents
+```
+
+### Help
+
+```bash
+# General help
+vbagent --help
+
+# Command-specific help
+vbagent scan --help
+vbagent variant --help
+```
+
+### Scan Command
+
+Extract LaTeX from physics question images:
+
+```bash
+# Basic scan with auto-classification
+vbagent scan -i question.png
+
+# Save output to file
+vbagent scan -i question.png -o output.tex
+
+# Override question type (skip classification)
+vbagent scan -i question.png --type mcq_sc
+```
+
+### Variant Command
+
+Generate problem variants with controlled modifications:
+
+```bash
+# Numerical variant (change numbers only)
+vbagent variant -t problem.tex --type numerical
+
+# Context variant (change scenario)
+vbagent variant -t problem.tex --type context
+
+# Generate multiple variants
+vbagent variant -t problem.tex --type numerical --count 3
+
+# Process range of items
+vbagent variant -t problems.tex --type numerical -r 1 5
+
+# Multi-context variant (combine problems)
+vbagent variant --type multi --context p1.tex --context p2.tex -o combined.tex
+
+# From image (scans first)
+vbagent variant -i image.png --type numerical -o variant.tex
+```
+
+#### Variant Types
+
+| Type | Description |
+|------|-------------|
+| `numerical` | Change only numbers, keep context |
+| `context` | Change scenario, keep numbers |
+| `conceptual` | Change physics concept |
+| `calculus` | Add calculus elements |
+| `multi` | Combine multiple problems |
+
+### Alternate Command
+
+Generate alternative solution methods:
+
+```bash
+# Generate one alternate solution
+vbagent alternate -t problem.tex
+
+# Generate multiple alternates
+vbagent alternate -t problem.tex -n 3
+
+# With ideas context
+vbagent alternate -t problem.tex --ideas ideas.json
+
+# Save to file
+vbagent alternate -t problem.tex -n 2 -o alternates.tex
+```
+
+### Check Command (QA Review)
+
+AI-powered quality review with interactive approval workflow:
+
+```bash
+# Start a review session (random 5 problems)
+vbagent check run
+
+# Review more problems
+vbagent check run -c 10
+
+# Review specific problem
+vbagent check run -p Problem_42
+
+# Review from specific directory
+vbagent check run -d ./my_output
+
+# View suggestion history
+vbagent check history
+
+# Apply a stored suggestion
+vbagent check apply 42
+
+# Resume interrupted session
+vbagent check resume abc123
+```
+
+#### Check Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `run` | Start a random QA review session |
+| `history` | View suggestion history |
+| `apply` | Apply a stored suggestion by ID |
+| `resume` | Resume an interrupted session |
+| `solution` | Check solution correctness |
+| `grammar` | Check grammar and spelling |
+| `clarity` | Check clarity and conciseness |
+| `tikz` | Check/generate TikZ diagram code |
+
+#### check tikz - TikZ Check and Generation
+
+The `check tikz` command has two modes:
+
+1. **Check Mode**: Reviews existing TikZ code for errors and best practices
+2. **Generate Mode**: If a file has `\input{diagram}` placeholder but no TikZ, generates TikZ from the corresponding image
+
+```bash
+# Check/generate TikZ in default directory
+vbagent check tikz
+
+# Check specific directory or file
+vbagent check tikz -d ./scans/
+vbagent check tikz -d ./scans/Problem_1.tex
+
+# Process multiple files
+vbagent check tikz -c 10
+
+# Use apply_patch mode (recommended)
+vbagent check tikz --patch
+
+# Filter by diagram type
+vbagent check tikz --ref-type circuit
+
+# Re-check all files
+vbagent check tikz --reset
+```
+
+**Auto-discovery features:**
+- Images are auto-found in `images/` sibling directory (e.g., `scans/Problem_1.tex` → `images/Problem_1.png`)
+- Diagram type is auto-detected from classification metadata
+- Reference examples are matched by diagram type
+
+### TikZ Command
+
+Generate TikZ/PGF code for diagrams:
+
+```bash
+# From image
+vbagent tikz -i diagram.png
+
+# With description
+vbagent tikz -d "A block on an inclined plane with friction"
+
+# Save to file
+vbagent tikz -i diagram.png -o diagram.tex
+
+# With reference directories
+vbagent tikz -i diagram.png --ref ./tikz_examples/
+```
+
+### Idea Command
+
+Extract physics concepts and ideas from problems:
+
+```bash
+# From TeX file
+vbagent idea -t problem.tex
+
+# Save to JSON
+vbagent idea -t problem.tex -o ideas.json
+```
+
+## Supported Question Types
+
+- MCQ Single Correct
+- MCQ Multiple Correct
+- Assertion-Reason
+- Match the Following
+- Passage/Comprehension
+- Subjective/Numerical
+
+## Variant Types
+
+- **Numerical**: Change numerical values while preserving physics
+- **Conceptual**: Modify the underlying concept
+- **Context**: Change the real-world scenario
+
+## Platform Support
+
+Works on macOS, Windows, and Linux. Sleep prevention during batch processing is supported on all platforms.
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run specific test
+pytest tests/test_scanner.py -v
+```
+
+## License
+
+MIT
+