vbagent 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

vbagent/__init__.py

@@ -1,3 +1,221 @@
-"""VBAgent - Physics question processing pipeline using OpenAI."""
+"""VBAgent - Physics question processing pipeline using OpenAI.
 
-__version__ = "0.1.0"
+This package provides agents for processing physics questions:
+- Classification: Analyze question images for metadata
+- Scanning: Extract LaTeX from question images
+- Variants: Generate problem variants (numerical, context, conceptual)
+- Ideas: Extract physics concepts
+- TikZ: Generate and check diagrams
+- Review: QA checking
+- Alternates: Generate alternate solutions
+
+Usage as a library:
+    from vbagent import classify, scan, generate_variant
+    from vbagent.models import ClassificationResult, ScanResult
+    from vbagent.config import get_config, set_config
+
+    # Classify an image
+    result = classify("question.png")
+    
+    # Scan with classification
+    latex_result = scan("question.png", result)
+    
+    # Generate a variant
+    variant = generate_variant(latex_result.latex, "numerical")
+    
+    # Generate TikZ diagram
+    tikz = generate_tikz("A free body diagram showing forces on a block")
+    
+    # Configure models
+    config = get_config()
+    config.scanner.model = "gpt-5.2"
+    set_config(config)
+
+Submodule access:
+    from vbagent.agents import classify, scan, generate_tikz
+    from vbagent.models import ClassificationResult, ScanResult, ReviewResult
+    from vbagent.prompts import get_scanner_prompt, get_variant_prompt
+    from vbagent.references import ReferenceStore, TikZStore
+    from vbagent.config import VBAgentConfig
+"""
+
+from typing import TYPE_CHECKING
+
+__version__ = "0.2.0"
+
+# Lazy imports for library consumers
+if TYPE_CHECKING:
+    from vbagent.agents import (
+        # Classification
+        classify,
+        # Scanning
+        scan,
+        scan_with_type,
+        # Ideas
+        extract_ideas,
+        generate_idea_latex,
+        # Alternates
+        generate_alternate,
+        # Variants
+        generate_variant,
+        generate_numerical_variant,
+        generate_context_variant,
+        generate_conceptual_variant,
+        generate_calculus_variant,
+        get_variant_prompt,
+        VALID_VARIANT_TYPES,
+        # TikZ generation
+        generate_tikz,
+        validate_tikz_output,
+        # QA Checkers
+        check_solution,
+        check_grammar,
+        check_clarity,
+        check_tikz,
+        check_tikz_with_patch,
+        # Review
+        review_problem,
+        review_problem_sync,
+        # Problem selection
+        discover_problems,
+        select_random,
+        load_problem_context,
+        ProblemContext,
+        # Base utilities
+        create_agent,
+        run_agent,
+        run_agent_sync,
+        encode_image,
+        create_image_message,
+    )
+    from vbagent.models import (
+        ClassificationResult,
+        ScanResult,
+        IdeaResult,
+        PipelineResult,
+        ReviewResult,
+        ReviewStats,
+        Suggestion,
+        ReviewIssueType,
+    )
+    from vbagent.config import (
+        VBAgentConfig,
+        AgentModelConfig,
+        get_config,
+        set_config,
+        save_config,
+        reset_config,
+        get_model,
+        get_model_settings,
+        AGENT_TYPES,
+        MODELS,
+    )
+
+__all__ = [
+    # Version
+    "__version__",
+    # Classification
+    "classify",
+    # Scanning
+    "scan",
+    "scan_with_type",
+    # Ideas
+    "extract_ideas",
+    "generate_idea_latex",
+    # Alternates
+    "generate_alternate",
+    # Variants
+    "generate_variant",
+    "generate_numerical_variant",
+    "generate_context_variant",
+    "generate_conceptual_variant",
+    "generate_calculus_variant",
+    "get_variant_prompt",
+    "VALID_VARIANT_TYPES",
+    # TikZ generation
+    "generate_tikz",
+    "validate_tikz_output",
+    # QA Checkers
+    "check_solution",
+    "check_grammar",
+    "check_clarity",
+    "check_tikz",
+    "check_tikz_with_patch",
+    # Review
+    "review_problem",
+    "review_problem_sync",
+    # Problem selection
+    "discover_problems",
+    "select_random",
+    "load_problem_context",
+    "ProblemContext",
+    # Agent utilities
+    "create_agent",
+    "run_agent",
+    "run_agent_sync",
+    "encode_image",
+    "create_image_message",
+    # Models
+    "ClassificationResult",
+    "ScanResult",
+    "IdeaResult",
+    "PipelineResult",
+    "ReviewResult",
+    "ReviewStats",
+    "Suggestion",
+    "ReviewIssueType",
+    # Configuration
+    "VBAgentConfig",
+    "AgentModelConfig",
+    "get_config",
+    "set_config",
+    "save_config",
+    "reset_config",
+    "get_model",
+    "get_model_settings",
+    "AGENT_TYPES",
+    "MODELS",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import to avoid loading heavy dependencies until needed."""
+    # Agent functions
+    if name in (
+        "classify",
+        "scan", "scan_with_type",
+        "extract_ideas", "generate_idea_latex",
+        "generate_alternate",
+        "generate_variant", "generate_numerical_variant", "generate_context_variant",
+        "generate_conceptual_variant", "generate_calculus_variant",
+        "get_variant_prompt", "VALID_VARIANT_TYPES",
+        "generate_tikz", "validate_tikz_output",
+        "check_solution", "check_grammar", "check_clarity", "check_tikz", "check_tikz_with_patch",
+        "review_problem", "review_problem_sync",
+        "discover_problems", "select_random", "load_problem_context", "ProblemContext",
+        "create_agent", "run_agent", "run_agent_sync",
+        "encode_image", "create_image_message",
+    ):
+        from vbagent import agents
+        return getattr(agents, name)
+    
+    # Models
+    if name in (
+        "ClassificationResult", "ScanResult", "IdeaResult",
+        "PipelineResult", "ReviewResult", "ReviewStats",
+        "Suggestion", "ReviewIssueType",
+    ):
+        from vbagent import models
+        return getattr(models, name)
+    
+    # Configuration
+    if name in (
+        "VBAgentConfig", "AgentModelConfig",
+        "get_config", "set_config", "save_config", "reset_config",
+        "get_model", "get_model_settings",
+        "AGENT_TYPES", "MODELS",
+    ):
+        from vbagent import config
+        return getattr(config, name)
+    
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

vbagent/agents/__init__.py

@@ -2,6 +2,14 @@
 
 Uses lazy imports to avoid loading heavy dependencies (openai, agents, mcp, pydantic)
 until they are actually needed. This significantly improves CLI startup time.
+
+Available agents and functions:
+- classify: Classify physics question images
+- scan, scan_with_type: Extract LaTeX from images
+- extract_ideas, generate_idea_latex: Extract physics concepts
+- generate_alternate: Generate alternate solutions
+- generate_variant: Generate problem variants
+- check_solution, check_grammar, check_clarity, check_tikz: QA checkers
 """
 
 from typing import TYPE_CHECKING
@@ -16,8 +24,18 @@ if TYPE_CHECKING:
         run_agent_sync,
     )
     from .classifier import classifier_agent, classify
+    from .scanner import scan, scan_with_type, create_scanner_agent
     from .idea import idea_agent_json, idea_agent_latex, extract_ideas, generate_idea_latex
     from .alternate import alternate_agent, generate_alternate, extract_answer
+    from .variant import (
+        generate_variant,
+        generate_numerical_variant,
+        generate_context_variant,
+        generate_conceptual_variant,
+        generate_calculus_variant,
+        get_variant_prompt,
+        VALID_VARIANT_TYPES,
+    )
     from .selector import (
         ProblemContext,
         discover_problems,
@@ -42,26 +60,58 @@ if TYPE_CHECKING:
     from .tikz_checker import (
         tikz_checker_agent,
         check_tikz,
+        check_tikz_with_patch,
         has_tikz_passed,
         has_tikz_environment,
+        PatchResult,
+    )
+    from .tikz import (
+        generate_tikz,
+        create_tikz_agent,
+        validate_tikz_output,
+        search_tikz_reference,
+    )
+    from .reviewer import (
+        review_problem,
+        review_problem_sync,
+        ReviewAgentError,
+        ReviewError,
+        ReviewErrorType,
     )
 
 
 __all__ = [
+    # Base utilities
     "encode_image",
     "create_image_message",
     "create_agent",
     "run_agent",
     "run_agent_sync",
+    # Classifier
     "classifier_agent",
     "classify",
+    # Scanner
+    "scan",
+    "scan_with_type",
+    "create_scanner_agent",
+    # Idea extraction
     "idea_agent_json",
     "idea_agent_latex",
     "extract_ideas",
     "generate_idea_latex",
+    # Alternate solutions
     "alternate_agent",
     "generate_alternate",
     "extract_answer",
+    # Variants
+    "generate_variant",
+    "generate_numerical_variant",
+    "generate_context_variant",
+    "generate_conceptual_variant",
+    "generate_calculus_variant",
+    "get_variant_prompt",
+    "VALID_VARIANT_TYPES",
+    # Problem selection
     "ProblemContext",
     "discover_problems",
     "select_random",
@@ -81,8 +131,21 @@ __all__ = [
     # TikZ checker
     "tikz_checker_agent",
     "check_tikz",
+    "check_tikz_with_patch",
     "has_tikz_passed",
     "has_tikz_environment",
+    "PatchResult",
+    # TikZ generator
+    "generate_tikz",
+    "create_tikz_agent",
+    "validate_tikz_output",
+    "search_tikz_reference",
+    # Reviewer
+    "review_problem",
+    "review_problem_sync",
+    "ReviewAgentError",
+    "ReviewError",
+    "ReviewErrorType",
 ]
 
 
@@ -96,6 +159,10 @@ def __getattr__(name: str):
         from . import classifier
         return getattr(classifier, name)
     
+    if name in ("scan", "scan_with_type", "create_scanner_agent"):
+        from . import scanner
+        return getattr(scanner, name)
+    
     if name in ("idea_agent_json", "idea_agent_latex", "extract_ideas", "generate_idea_latex"):
         from . import idea
         return getattr(idea, name)
@@ -104,6 +171,14 @@ def __getattr__(name: str):
         from . import alternate
         return getattr(alternate, name)
     
+    if name in (
+        "generate_variant", "generate_numerical_variant", "generate_context_variant",
+        "generate_conceptual_variant", "generate_calculus_variant",
+        "get_variant_prompt", "VALID_VARIANT_TYPES",
+    ):
+        from . import variant
+        return getattr(variant, name)
+    
     if name in ("ProblemContext", "discover_problems", "select_random", "load_problem_context"):
         from . import selector
         return getattr(selector, name)
@@ -120,8 +195,16 @@ def __getattr__(name: str):
         from . import clarity_checker
         return getattr(clarity_checker, name)
     
-    if name in ("tikz_checker_agent", "check_tikz", "has_tikz_passed", "has_tikz_environment"):
+    if name in ("tikz_checker_agent", "check_tikz", "check_tikz_with_patch", "has_tikz_passed", "has_tikz_environment", "PatchResult"):
         from . import tikz_checker
         return getattr(tikz_checker, name)
     
+    if name in ("generate_tikz", "create_tikz_agent", "validate_tikz_output", "search_tikz_reference"):
+        from . import tikz
+        return getattr(tikz, name)
+    
+    if name in ("review_problem", "review_problem_sync", "ReviewAgentError", "ReviewError", "ReviewErrorType"):
+        from . import reviewer
+        return getattr(reviewer, name)
+    
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

vbagent/agents/base.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Any, Optional
 if TYPE_CHECKING:
     from agents import Agent, ModelSettings
 
-from vbagent.config import get_model, get_model_settings
+from vbagent.config import get_model, get_model_settings, apply_provider_config
 
 
 def _get_agent_class():
@@ -115,6 +115,9 @@ def create_agent(
     """
     Agent = _get_agent_class()
     
+    # Apply provider config (base_url, api_key) before creating agent
+    apply_provider_config()
+    
     # Get model and settings from config if not explicitly provided
     if model is None:
         model = get_model(agent_type or "default")

vbagent/agents/classifier.py

@@ -1,32 +1,56 @@
-"""Classifier agent for physics question image classification.
+"""Classifier agent for question image classification.
 
-Uses openai-agents SDK to analyze physics question images and extract
+Uses openai-agents SDK to analyze question images and extract
 structured metadata including question type, difficulty, topic, etc.
 """
 
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from agents import Agent
+
 from vbagent.agents.base import (
     create_agent,
     create_image_message,
     run_agent_sync,
 )
+from vbagent.config import get_config
 from vbagent.models.classification import ClassificationResult
-from vbagent.prompts.classifier import SYSTEM_PROMPT, USER_TEMPLATE
+from vbagent.prompts.classifier import get_classifier_prompt, get_user_template
 
 
-# Create the classifier agent with structured output
-classifier_agent = create_agent(
-    name="Classifier",
-    instructions=SYSTEM_PROMPT,
-    output_type=ClassificationResult,
-    agent_type="classifier",
-)
+def create_classifier_agent(subject: Optional[str] = None) -> "Agent":
+    """Create a classifier agent for a subject.
+    
+    Args:
+        subject: Subject override (uses config if not provided)
+        
+    Returns:
+        Configured Agent instance for classification
+    """
+    if subject is None:
+        subject = get_config().subject
+    
+    prompt = get_classifier_prompt(subject)
+    
+    return create_agent(
+        name=f"Classifier-{subject}",
+        instructions=prompt,
+        output_type=ClassificationResult,
+        agent_type="classifier",
+    )
 
 
-def classify(image_path: str) -> ClassificationResult:
-    """Analyze a physics question image and return structured metadata.
+# Legacy: Create default classifier agent for backward compatibility
+classifier_agent = create_classifier_agent("physics")
+
+
+def classify(image_path: str, subject: Optional[str] = None) -> ClassificationResult:
+    """Analyze a question image and return structured metadata.
     
     Args:
         image_path: Path to the image file to classify
+        subject: Subject override (uses config if not provided)
         
     Returns:
         ClassificationResult with extracted metadata
@@ -34,6 +58,11 @@ def classify(image_path: str) -> ClassificationResult:
     Raises:
         FileNotFoundError: If the image file doesn't exist
     """
-    message = create_image_message(image_path, USER_TEMPLATE)
-    result = run_agent_sync(classifier_agent, message)
+    if subject is None:
+        subject = get_config().subject
+    
+    agent = create_classifier_agent(subject)
+    user_template = get_user_template(subject)
+    message = create_image_message(image_path, user_template)
+    result = run_agent_sync(agent, message)
     return result

vbagent/agents/compile_fixer.py

@@ -0,0 +1,57 @@
+"""Agent for fixing LaTeX compilation errors.
+
+Takes a LaTeX snippet and pdflatex error output, returns corrected LaTeX.
+"""
+
+from vbagent.agents.base import create_agent, run_agent_sync
+
+
+SYSTEM_PROMPT = r"""You are a LaTeX error fixer. You receive LaTeX code that failed to compile and the pdflatex error output.
+
+Your job:
+1. Read the error messages carefully
+2. Fix ONLY the errors — do not change the content or structure
+3. Common fixes: missing braces, undefined commands, wrong environment names, missing $ delimiters
+4. Output ONLY the corrected LaTeX code — no explanations, no markdown, no code blocks
+
+CRITICAL: Output the EXACT same content with ONLY the compilation errors fixed. Do not add \documentclass, preamble, or any wrapping."""
+
+USER_TEMPLATE = """Fix the compilation errors in this LaTeX code.
+
+**Errors from pdflatex:**
+```
+{errors}
+```
+
+**LaTeX code to fix:**
+```latex
+{latex}
+```
+
+Output ONLY the corrected LaTeX code:"""
+
+
+def fix_latex(error_summary: str, latex: str) -> str:
+    """Send LaTeX + errors to agent and get fixed version.
+
+    Args:
+        error_summary: Parsed pdflatex error output
+        latex: The LaTeX code that failed to compile
+
+    Returns:
+        Corrected LaTeX code
+    """
+    agent = create_agent(
+        name="LaTeX-Fixer",
+        instructions=SYSTEM_PROMPT,
+        agent_type="converter",  # Use converter model (lighter/cheaper)
+    )
+
+    prompt = USER_TEMPLATE.format(errors=error_summary, latex=latex)
+    result = run_agent_sync(agent, prompt)
+
+    # Clean markdown artifacts
+    import re
+    result = re.sub(r'^```(?:latex|tex)?\s*\n?', '', result, flags=re.IGNORECASE)
+    result = re.sub(r'\n?```\s*$', '', result)
+    return result.strip()

vbagent/agents/converter.py

@@ -48,9 +48,9 @@ from vbagent.prompts.converter import (
 
 
 # Valid format types
-FormatType = Literal["mcq_sc", "mcq_mc", "subjective", "integer"]
+FormatType = Literal["mcq_sc", "mcq_mc", "subjective", "integer", "match", "passage"]
 
-VALID_FORMATS = {"mcq_sc", "mcq_mc", "subjective", "integer"}
+VALID_FORMATS = {"mcq_sc", "mcq_mc", "subjective", "integer", "match", "passage"}
 
 
 # Create the format converter agent

vbagent/agents/reviewer.py

@@ -208,13 +208,13 @@ def _convert_issue_type(issue_type_str: str) -> ReviewIssueType:
 
 
 def _create_suggestion_with_diff(
-    raw: RawSuggestion,
+    raw,  # RawSuggestion instance
     context: ProblemContext,
 ) -> Suggestion:
     """Convert a raw suggestion to a Suggestion with generated diff.
     
     Args:
-        raw: Raw suggestion from the AI
+        raw: Raw suggestion from the AI (RawSuggestion instance)
         context: Problem context for file path resolution
         
     Returns: