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

vbagent/prompts/converter.py

@@ -4,74 +4,247 @@ Prompts for converting physics questions between different formats:
 - MCQ (single correct) ↔ MCQ (multiple correct)
 - MCQ ↔ Subjective
 - MCQ ↔ Integer type
-- Subjective ↔ Integer type
+- Match the following
+- Passage/Comprehension type
 """
 
-SYSTEM_PROMPT = """You are an expert physics educator specializing in question format conversion. Your task is to convert physics questions between different assessment formats while preserving the core physics content and difficulty level.
+SYSTEM_PROMPT = r"""You are an expert physics educator specializing in question format conversion. Your task is to convert physics questions between different assessment formats while preserving the core physics content and difficulty level.
 
 SUPPORTED FORMATS:
 1. mcq_sc - Multiple Choice Question (Single Correct): Has 4 options with exactly one correct answer
 2. mcq_mc - Multiple Choice Question (Multiple Correct): Has 4 options with one or more correct answers
 3. subjective - Subjective/Descriptive: Open-ended question requiring detailed solution
 4. integer - Integer Type: Question where the answer is a single integer (0-9 or multi-digit)
+5. match - Match the Following: Two columns to be matched with combination options
+6. passage - Passage/Comprehension: A passage followed by multiple questions based on it
 
-FORMAT-SPECIFIC GUIDELINES:
-
-**Converting TO mcq_sc (Single Correct MCQ):**
-- Generate exactly 4 options labeled (A), (B), (C), (D)
-- Exactly ONE option must be correct
-- Create plausible distractors based on common misconceptions
-- Distractors should be numerically close or conceptually related
-- Use \\begin{tasks}(4) ... \\end{tasks} environment for options
-- Include \\task before each option
-
-**Converting TO mcq_mc (Multiple Correct MCQ):**
-- Generate exactly 4 options labeled (A), (B), (C), (D)
-- At least 2 options should be correct
-- Each option should test a different aspect of the concept
-- Use \\begin{tasks}(4) ... \\end{tasks} environment for options
-- Include \\task before each option
-
-**Converting TO subjective:**
-- Remove all options
-- Rephrase to ask for derivation, explanation, or calculation
-- May ask for intermediate steps or multiple parts
-- Do NOT use tasks environment
-- Question should require showing work
-
-**Converting TO integer:**
-- Reformulate so the answer is a single integer or simple number
-- Specify the expected format (e.g., "nearest integer", "in units of...")
-- Remove options if converting from MCQ
-- Do NOT use tasks environment
-- Ensure the numerical answer is unambiguous
-
-CRITICAL REQUIREMENTS:
+---
+
+## FORMAT-SPECIFIC OUTPUT STRUCTURES:
+
+### MCQ Single Correct (mcq_sc):
+```latex
+\item [Question text with math in $...$]
+\begin{center}
+    % TikZ diagram if present
+\end{center}
+\begin{tasks}(2)
+    \task $\dfrac{RMg}{B_0L}$ \ans
+    \task $\dfrac{RMg}{2B_0L}$
+    \task $\dfrac{2RMg}{B_0L}$
+    \task None of these
+\end{tasks}
+\begin{solution}
+\begin{align*}
+[Step-by-step solution using align* with \intertext{} for explanations]
+\end{align*}
+\end{solution}
+```
+- Use `\begin{tasks}(2)` for numerical/short options, `\begin{tasks}(1)` for long text options
+- Mark the correct answer with `\ans` at the END of the \task line
+- Exactly ONE option gets `\ans`
+
+### MCQ Multiple Correct (mcq_mc):
+```latex
+\item [Question text with math in $...$]
+\begin{tasks}(2)
+    \task Option A \ans
+    \task Option B \ans
+    \task Option C
+    \task Option D
+\end{tasks}
+\begin{solution}
+\begin{align*}
+[Solution explaining why multiple options are correct]
+\end{align*}
+\end{solution}
+```
+- At least 2 options should have `\ans`
+
+### Integer Type (integer):
+
+**Format A - Direct numerical answer:**
+```latex
+\item [Question text ending with] \hrulefill [unit]. \ansint{value}
+\begin{solution}
+\begin{align*}
+[Step-by-step solution]
+&= \text{final integer value}
+\end{align*}
+\end{solution}
+```
+Example: `...the current will be \hrulefill A. \ansint{3}`
+
+**Format B - Answer expressed in terms of a variable (common pattern):**
+```latex
+\item [Question text]. The answer is $\frac{2\pi}{\beta}$ volt. The value of $\beta$ is \hrulefill. \ansint{5}
+\begin{solution}
+\begin{align*}
+[Derive the expression]
+&= \frac{2\pi}{5}\,\mathrm{V}
+\intertext{Comparing with $\frac{2\pi}{\beta}$:}
+\beta &= 5
+\end{align*}
+\end{solution}
+```
+- This format expresses the final answer as an expression involving a variable ($k$, $\alpha$, $\beta$, $n$, etc.)
+- The question asks to find the VALUE of that variable
+- Common patterns: `$\frac{a\pi}{k}$`, `$\alpha \times 10^n$`, `$\frac{n}{m}$`
+
+- NO tasks environment for integer type
+- `\ansint{N}` contains the integer value of the variable
+
+### Subjective Type (subjective):
+```latex
+\item [Question text asking for derivation/explanation/calculation]
+\begin{solution}
+\begin{align*}
+[Detailed step-by-step solution]
+\end{align*}
+\end{solution}
+```
+- NO tasks environment
+- Question should ask for work to be shown
+
+### Match the Following (match):
+```latex
+\item Match the items in Column I with the appropriate items in Column II.
+
+\begin{center}
+    \renewcommand{\arraystretch}{2}
+    \begin{tabular}{p{0.25cm}p{8cm}|p{0.25cm}p{5cm}}
+    \hline
+    & Column I & & Column II \\
+    \hline
+    (a) & Item A description & (p) & Match P description \\
+    (b) & Item B description & (q) & Match Q description \\
+    (c) & Item C description & (r) & Match R description \\
+    (d) & Item D description & (s) & Match S description \\
+    \hline
+    \end{tabular}
+\end{center}
+
+\begin{tasks}(2)
+    \task $a \rightarrow p$, $b \rightarrow q$, $c \rightarrow r$, $d \rightarrow s$
+    \task $a \rightarrow q$, $b \rightarrow p$, $c \rightarrow s$, $d \rightarrow r$ \ans
+    \task $a \rightarrow r$, $b \rightarrow s$, $c \rightarrow p$, $d \rightarrow q$
+    \task $a \rightarrow s$, $b \rightarrow r$, $c \rightarrow q$, $d \rightarrow p$
+\end{tasks}
+\begin{solution}
+\begin{align*}
+\intertext{Analyzing each match:}
+\intertext{(a) matches with (q) because...}
+\intertext{(b) matches with (p) because...}
+\intertext{(c) matches with (s) because...}
+\intertext{(d) matches with (r) because...}
+\end{align*}
+Therefore, the correct option is (b).
+\end{solution}
+```
+- Column I uses (a), (b), (c), (d) labels
+- Column II uses (p), (q), (r), (s) labels
+- Options show matching combinations using `$a \rightarrow p$` notation
+- Use `\renewcommand{\arraystretch}{2}` for table spacing
+
+### Passage/Comprehension Type (passage):
+```latex
+\item[]
+\begin{center}
+    \textsc{Passage Title (if any)}
+\end{center}
+
+[Passage text describing the physics scenario, setup, or context. This can be multiple paragraphs with equations, diagrams, etc.]
+
+\begin{center}
+    % TikZ diagram if present
+\end{center}
+
+\item Based on the passage, what is the velocity of the particle?
+\begin{tasks}(2)
+    \task $10\,\mathrm{m/s}$
+    \task $20\,\mathrm{m/s}$ \ans
+    \task $30\,\mathrm{m/s}$
+    \task $40\,\mathrm{m/s}$
+\end{tasks}
+\begin{solution}
+\begin{align*}
+[Solution for question 1]
+\end{align*}
+Therefore, the correct option is (b).
+\end{solution}
+
+\item What is the acceleration?
+\begin{tasks}(2)
+    \task $5\,\mathrm{m/s^2}$ \ans
+    \task $10\,\mathrm{m/s^2}$
+    \task $15\,\mathrm{m/s^2}$
+    \task $20\,\mathrm{m/s^2}$
+\end{tasks}
+\begin{solution}
+\begin{align*}
+[Solution for question 2]
+\end{align*}
+Therefore, the correct option is (a).
+\end{solution}
+```
+- Starts with `\item[]` for the passage header (empty item)
+- Optional centered title using `\textsc{}`
+- Passage text follows (can include math, diagrams)
+- Each question is a separate `\item` with its own tasks and solution
+- Solution appears IMMEDIATELY after each question's tasks
+
+---
+
+## SOLUTION FORMATTING (CRITICAL):
+
+Use `align*` environment with `\intertext{}` for explanations:
+
+```latex
+\begin{solution}
+\begin{align*}
+V &= iR + L\frac{di}{dt} \\
+i &= \frac{V - L\frac{di}{dt}}{R} \\
+\intertext{At the instant considered, the rheostat resistance is $12\,\Omega$, the inductance is $3\,\mathrm{H}$, and $\frac{di}{dt}=-8\,\mathrm{A/s}$.}
+i &= \frac{12 - 3(-8)}{12} \\
+&= \frac{36}{12} \\
+&= 3\,\mathrm{A}
+\end{align*}
+Therefore, the correct option is (a).
+\end{solution}
+```
+
+**Rules for align*:**
+- Use `&` for alignment (typically before `=`)
+- Use `\\` to end each line
+- Use `\intertext{}` for text explanations BETWEEN equation lines
+- Inside `\intertext{}`, use `$...$` for inline math, NOT `\text{}`
+- Keep ONE step per line
+- NO blank lines inside align*
+- End with a concluding statement for MCQ (e.g., "Therefore, the correct option is (a).")
+
+---
+
+## LATEX FORMATTING RULES:
+
+- **Math Mode:** Use `$...$` for ALL inline math
+- **Fractions:** Use `\frac{a}{b}` or `\dfrac{a}{b}` (display style in tasks)
+- **Units:** Use `\,\mathrm{unit}` format (e.g., `3\,\mathrm{A}`, `12\,\Omega`)
+- **Vectors:** Use `\vec{a}` for vectors, `\hat{i}`, `\hat{j}`, `\hat{k}` for unit vectors
+- **Parentheses:** Use `\left( ... \right)` for auto-sizing
+- **DO NOT** use `\tfrac`, `\bigl`, `\bigr`
+
+---
+
+## CRITICAL REQUIREMENTS:
 1. PRESERVE the core physics concept being tested
 2. MAINTAIN the same difficulty level
-3. ENSURE the solution remains valid for the new format
-4. OUTPUT valid LaTeX starting with \\item
-5. INCLUDE a complete solution in \\begin{solution}...\\end{solution}
-6. RECALCULATE or adjust the solution for the new format
-7. DO NOT wrap output in markdown code blocks (no ``` markers)
-8. Output ONLY the LaTeX content, nothing else
-
-OUTPUT STRUCTURE:
-\\item [Question text in target format]
-[Options if MCQ format, using tasks environment]
-\\begin{solution}
-[Complete solution appropriate for target format]
-\\end{solution}
-
-FORMATTING RULES:
-- Use proper LaTeX math mode: $...$ for inline, \\[...\\] or align* for display
-- Use \\SI{value}{unit} or proper unit formatting
-- For MCQ: use \\begin{tasks}(4) with \\task before each option
-- Ensure all environments are properly closed
-- Use \\frac{}{} for fractions, not /
-- Use \\sqrt{} for square roots"""
-
-USER_TEMPLATE = """Convert this physics question from {source_format} to {target_format}.
+3. OUTPUT valid LaTeX starting with `\item`
+4. Use the EXACT format structure for the target type
+5. DO NOT wrap output in markdown code blocks (no ``` markers)
+6. Output ONLY the LaTeX content, nothing else
+7. If source has TikZ diagrams, preserve them in a `\begin{center}...\end{center}` block"""
+
+USER_TEMPLATE = r"""Convert this physics question from {source_format} to {target_format}.
 
 Source Question:
 {source_latex}
@@ -80,36 +253,106 @@ Requirements:
 1. Preserve the core physics being tested
 2. Maintain the same difficulty level
 3. Output valid LaTeX in the target format
-4. Include a complete solution
-5. Start with \\item and end with \\end{{solution}}
+4. Include a complete solution using align* with \intertext{{}} for explanations
+5. Start with \item and end with \end{{solution}}
+6. If source has diagrams/TikZ, preserve them
 
 {format_specific_instructions}"""
 
 # Format-specific instruction templates
 FORMAT_INSTRUCTIONS = {
-    "mcq_sc": """Target Format Instructions (MCQ Single Correct):
-- Create exactly 4 options using \\begin{tasks}(4)...\\end{tasks}
-- Use \\task before each option
-- Exactly ONE option must be correct
-- Create plausible distractors based on common errors""",
+    "mcq_sc": r"""Target Format Instructions (MCQ Single Correct):
+- Create exactly 4 options using \begin{tasks}(2)...\end{tasks} for short options or (1) for long
+- Use \task before each option
+- Mark the SINGLE correct answer with \ans at the END of its \task line
+- Example: \task $\dfrac{RMg}{B_0L}$ \ans
+- Create plausible distractors based on common errors
+- End solution with "Therefore, the correct option is (X)." """,
     
-    "mcq_mc": """Target Format Instructions (MCQ Multiple Correct):
-- Create exactly 4 options using \\begin{tasks}(4)...\\end{tasks}
-- Use \\task before each option
-- At least 2 options should be correct
+    "mcq_mc": r"""Target Format Instructions (MCQ Multiple Correct):
+- Create exactly 4 options using \begin{tasks}(2)...\end{tasks}
+- Use \task before each option
+- Mark ALL correct answers with \ans at the END of their \task lines
+- At least 2 options should have \ans
 - Each option should test a different aspect""",
     
-    "subjective": """Target Format Instructions (Subjective):
+    "subjective": r"""Target Format Instructions (Subjective):
 - Remove all options (no tasks environment)
 - Ask for derivation, explanation, or detailed calculation
 - May include multiple parts (a), (b), (c) if appropriate
-- Solution should show complete working""",
+- Solution should show complete working using align* with \intertext{}""",
     
-    "integer": """Target Format Instructions (Integer Type):
+    "integer": r"""Target Format Instructions (Integer Type):
 - Remove all options (no tasks environment)
-- Reformulate so answer is a single integer
-- Specify units or rounding if needed (e.g., "nearest integer")
-- Solution should clearly show how to arrive at the integer answer""",
+- Two common formats:
+
+FORMAT A - Direct numerical answer:
+- Question ends with: \hrulefill [unit]. \ansint{N}
+- Example: "...the value of the current will be \hrulefill A. \ansint{3}"
+
+FORMAT B - Answer in terms of a variable (COMMON):
+- Express the answer as an expression with a variable ($k$, $\alpha$, $\beta$, $n$, etc.)
+- Ask to find the VALUE of that variable
+- Example: "The maximum voltage is $\frac{2\pi}{\beta}$ volt. The value of $\beta$ is \hrulefill. \ansint{5}"
+- Common patterns: $\frac{a\pi}{k}$, $\alpha \times 10^n$, $\frac{n}{m}$
+
+- The integer answer goes inside \ansint{}
+- Solution should derive the expression and identify the variable's value
+- If answer needs rounding, mention "nearest integer" in question text""",
+    
+    "match": r"""Target Format Instructions (Match the Following):
+- Create a matching table with Column I (a, b, c, d) and Column II (p, q, r, s)
+- Use tabular environment with \renewcommand{\arraystretch}{2} for spacing
+- Create 4 options showing different matching combinations
+- Use $a \rightarrow p$ notation for matches in options
+- Mark the correct combination with \ans
+- Solution should explain WHY each item matches
+
+Structure:
+\item [Question asking to match columns]
+\begin{center}
+    \renewcommand{\arraystretch}{2}
+    \begin{tabular}{p{0.25cm}p{8cm}|p{0.25cm}p{5cm}}
+    ...table content...
+    \end{tabular}
+\end{center}
+\begin{tasks}(2)
+    \task [combination 1]
+    \task [combination 2] \ans
+    ...
+\end{tasks}
+\begin{solution}...\end{solution}""",
+    
+    "passage": r"""Target Format Instructions (Passage/Comprehension Type):
+- Create a passage describing a physics scenario or context
+- Follow with 2-4 questions based on the passage
+- Each question has its own \item, tasks, and solution
+
+Structure:
+\item[]
+\begin{center}
+    \textsc{Passage Title}
+\end{center}
+
+[Passage text - can be multiple paragraphs with equations]
+
+\item [Question 1 based on passage]
+\begin{tasks}(2)
+    \task ... \ans
+    \task ...
+\end{tasks}
+\begin{solution}...\end{solution}
+
+\item [Question 2 based on passage]
+\begin{tasks}(2)
+    \task ...
+    \task ... \ans
+\end{tasks}
+\begin{solution}...\end{solution}
+
+- Start with \item[] for passage header
+- Each sub-question gets its own solution IMMEDIATELY after its tasks
+- Questions should test different aspects of the passage content""",
 }
 
 

vbagent/prompts/tikz_checker.py

@@ -2,11 +2,13 @@
 
 Prompts for checking TikZ/PGF code for syntax errors, best practices,
 and physics diagram conventions.
-"""
 
-SYSTEM_PROMPT = r"""You are an expert TikZ/PGF code reviewer. Check TikZ code for errors and provide ONLY the corrected version.
+Includes both legacy prompts (full content output) and patch prompts
+(for use with apply_patch tool).
+"""
 
-## Review Checklist
+# Shared review checklist used by both legacy and patch modes
+_REVIEW_CHECKLIST = r"""## Review Checklist
 
 **1. Syntax Errors**
 - Missing semicolons at end of commands
@@ -195,6 +197,16 @@ When using `kinematikz` package for frames/supports:
 % GOOD - use hyphen for kinematikz pic anchors:
 \draw (support-center) -- (mass.north);  % support is \pic, mass is \node
 ```
+"""
+
+
+# =============================================================================
+# LEGACY PROMPTS (full content output)
+# =============================================================================
+
+SYSTEM_PROMPT = r"""You are an expert TikZ/PGF code reviewer. Check TikZ code for errors and provide ONLY the corrected version.
+
+""" + _REVIEW_CHECKLIST + r"""
 
 ## Output Format
 
@@ -228,3 +240,79 @@ IMPORTANT:
 - Do NOT add \documentclass, preamble, or anything not in the original
 - If errors found: `% TIKZ_CHECK: [fixes]` then the corrected content
 - If correct: `% TIKZ_CHECK: PASSED - No TikZ errors found`"""
+
+
+# =============================================================================
+# PATCH PROMPTS (for use with apply_patch tool)
+# =============================================================================
+
+PATCH_SYSTEM_PROMPT = r"""You are an expert TikZ/PGF code reviewer with the ability to apply patches to fix code.
+
+You have access to the `apply_patch` tool to make precise, targeted fixes to TikZ code.
+
+""" + _REVIEW_CHECKLIST + r"""
+
+## How to Use apply_patch
+
+When you find issues, use the `apply_patch` tool to emit structured diffs:
+
+1. For each fix, call `apply_patch` with:
+   - `path`: The file path provided in the user message
+   - `operation`: "update_file"
+   - `diff`: A V4A diff showing the change
+
+2. V4A diff format:
+   ```
+   @@ context_line_to_match
+   -line_to_remove
+   +line_to_add
+    unchanged_line (space prefix)
+   ```
+
+3. Make MINIMAL, TARGETED patches - fix only what's broken
+4. Group related fixes into a single patch when they're adjacent
+
+## Output Rules
+
+1. If NO errors found: Just respond with "PASSED - No TikZ errors found"
+2. If errors found: Use apply_patch tool for each fix, then summarize what you fixed
+3. Do NOT output the full corrected file - only patches
+4. Make patches as small as possible while being complete
+5. Include enough context in @@ line for unique matching
+
+## Example Patch
+
+For fixing a missing semicolon:
+```
+@@ \draw (0,0) -- (1,1)
+-\draw (0,0) -- (1,1)
++\draw (0,0) -- (1,1);
+```
+
+For fixing spring decoration:
+```
+@@ spring/.style={
+-    spring/.style={decorate, decoration={coil}}
++    spring/.style={thick, decorate, decoration={
++        coil,
++        amplitude=4pt,
++        segment length=4.5pt,
++        pre length=5pt,
++        post length=5pt
++    }}
+```
+"""
+
+PATCH_USER_TEMPLATE = r"""Check this TikZ code for errors and apply patches to fix them.
+
+File: {file_path}
+
+```latex
+{full_content}
+```
+
+INSTRUCTIONS:
+1. Review the code using the checklist
+2. If errors found: Use apply_patch tool to fix each issue
+3. If no errors: Just respond "PASSED - No TikZ errors found"
+4. After patching, briefly summarize what you fixed"""

vbagent/references/__init__.py

@@ -1,5 +1,62 @@
-"""Reference store modules for vbagent."""
+"""Reference store modules for vbagent.
 
-from vbagent.references.store import ReferenceStore, SearchResult
+Provides reference context management for agents:
+- ReferenceStore: Store and retrieve reference examples for LaTeX/TikZ
+- TikZStore: Store and retrieve TikZ diagram examples with metadata
+- get_context_prompt_section: Get context for prompts
 
-__all__ = ["ReferenceStore", "SearchResult"]
+Usage:
+    from vbagent.references import ReferenceStore, TikZStore, get_context_prompt_section
+    
+    # Use reference store
+    store = ReferenceStore.get_instance()
+    store.add("example", "content")
+    results = store.search("query")
+    
+    # Use 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")
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .store import ReferenceStore, SearchResult
+    from .tikz_store import TikZReferenceStore, TikZReference, TikZMetadata
+    from .context import get_context_prompt_section, set_context_enabled
+
+__all__ = [
+    # Reference store
+    "ReferenceStore",
+    "SearchResult",
+    # TikZ store
+    "TikZStore",
+    "TikZReferenceStore",
+    "TikZReference",
+    "TikZMetadata",
+    # Context utilities
+    "get_context_prompt_section",
+    "set_context_enabled",
+]
+
+
+def __getattr__(name: str):
+    """Lazy import of reference modules."""
+    if name in ("ReferenceStore", "SearchResult"):
+        from . import store
+        return getattr(store, name)
+    
+    if name in ("TikZStore", "TikZReferenceStore", "TikZReference", "TikZMetadata"):
+        from . import tikz_store
+        if name == "TikZStore":
+            return tikz_store.TikZReferenceStore
+        return getattr(tikz_store, name)
+    
+    if name in ("get_context_prompt_section", "set_context_enabled"):
+        from . import context
+        return getattr(context, name)
+    
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")