Fixed placeholder bugs and improved prompts

agents/explainer/__init__.py

@@ -10,9 +10,8 @@ import logging
 
 from llama_index.core.agent import AgentRunner
 from llama_index.llms.litellm import LiteLLM
-from llama_index.core.tools import FunctionTool
-from services.vector_store import VectorStore # Import VectorStore
-from services.llm_factory import _PROVIDER_MAP # Import _PROVIDER_MAP directly
+from services.vector_store import VectorStore 
+from services.llm_factory import _PROVIDER_MAP 
 
 # Configure logging for explainer agent
 logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
@@ -52,41 +51,27 @@ class ExplainerAgent:
         retrieved_context = []
         if self.vector_store:
             # Use the title and content to query the vector store for relevant chunks
-            query = f"{title}. {content[:100]}" # Combine title and start of content for query
-            retrieved_docs = self.vector_store.search(query, k=3) # Retrieve top 3 relevant docs
+            # Combine title and start of context for the query and utilize top 3 relevant docs
+            query = f"{title}. {content[:100]}" 
+            retrieved_docs = self.vector_store.search(query, k=3) 
             retrieved_context = [doc['content'] for doc in retrieved_docs]
             logging.info(f"ExplainerAgent: Retrieved {len(retrieved_context)} context chunks.")
 
-        base_prompt = explain_prompter(title, content, retrieved_context) # Pass retrieved_context
+        base_prompt = explain_prompter(title, content, retrieved_context)
         
         if explanation_style == "Concise":
-            style_instruction = ("Keep the explanation concise (max 300 words), "
+            style_instruction = ("Keep the explanation concise (max 400 words), "
                                  "focusing on core concepts.")
         elif explanation_style == "Detailed":
             style_instruction = ("Provide a detailed explanation, elaborating on concepts,"
                                  " examples, and deeper insights to master the topic.")
         else:
-            style_instruction = ("Keep the explanation concise (max 300 words), "
+            style_instruction = ("Keep the explanation concise (max 400 words), "
                                  "focusing on core concepts.")
 
         prompt_message = f"""
         {base_prompt}
         {style_instruction}
-
-        You can use the `make_figure` tool to generate charts and diagrams.
-        When using `make_figure`, provide the `chart_type` (e.g., "bar_chart", "line_graph",
-        "pie_chart", "scatter_plot", "histogram")
-        and the `data` as a JSON dictionary.
-        For example:
-        `make_figure(title="Example Bar Chart", content="Data for bar chart",
-        chart_type="bar_chart", data={{"labels": ["A", "B"], "values": [10, 20]}})`
-        
-        If you decide to generate a figure, ensure the `title` and `content` arguments
-        passed to `make_figure` are relevant to the current learning unit.
-        After generating the explanation, if you used the `make_figure` tool, the output
-        will contain a placeholder like `[FIGURE_PATH: /path/to/figure.png]`.
-        You MUST include this placeholder directly in your final markdown response where
-        the figure should appear.
         """
         
         chat_response = self.agent.chat(prompt_message)
@@ -136,50 +121,49 @@ class ExplainerAgent:
             forbidden_descs = ["code", "code example", "code snippet", "sample", "example", 
                                "[error: missing or generic code description from llm]"]
 
-            is_generic_desc = False
-            if raw_llm_desc:
-                if raw_llm_desc.strip().lower() in forbidden_descs:
-                    is_generic_desc = True
-            else:
-                is_generic_desc = True
+            is_generic_desc = not raw_llm_desc or raw_llm_desc.strip().lower() in forbidden_descs
             
             if is_generic_desc:
                 actual_display_desc = f"Python code illustrating '{title}'"
                 desc_for_generator = (
-                    f"Context: '{title}'. Task: Generate a relevant Python code example. "
-                    f"The LLM failed to provide a specific description (or provided a generic one: "
-                    f"'{raw_llm_desc}') for this code block. "
-                    f"Ensure the generated code is self-contained, includes example usage, "
-                    f"and critically, MUST end with a print() statement to display the main result."
+                    f"Context: '{title}'. Task: Generate a runnable, self-contained Python code example. "
+                    f"The LLM provided a generic description: '{raw_llm_desc}'. Your final line of code MUST be a print() statement."
                 )
-                if raw_llm_desc and raw_llm_desc.strip().lower() not in forbidden_descs :
-                     logging.warning(f"ExplainerAgent: LLM provided an unusual or generic code "
-                                     f"description: '{raw_llm_desc}'. Using fallback title "
-                                     f"'{actual_display_desc}'.")
-                elif raw_llm_desc:
-                     logging.warning(f"ExplainerAgent: LLM provided generic code description: "
-                                     f"'{raw_llm_desc}'. Using fallback title '{actual_display_desc}'.")
-                else:
-                     logging.warning(f"ExplainerAgent: LLM provided no code description with [CODE:]. "
-                                     f"Using fallback title '{actual_display_desc}'.")
+                logging.warning(f"ExplainerAgent: LLM provided generic or no code description: "
+                                f"'{raw_llm_desc}'. Using fallback title.")
             else:
-                actual_display_desc = raw_llm_desc
+                actual_display_desc = raw_llm_desc.strip()
                 desc_for_generator = (
-                    f"Generate Python code for: '{raw_llm_desc}'. IMPORTANT: The example usage "
-                    f"within this generated code block MUST end with a print() statement to display "
-                    f"the main result or output clearly to the user. "
-                    f"The code should be self-contained with all necessary setup (imports, variables)."
+                    f"Generate a runnable, self-contained Python code snippet for: '{raw_llm_desc}'. "
+                    f"It must include all necessary imports and initialize all variables. "
+                    f"Your final line of code MUST be a print() statement to display the result."
                 )
             
-            code_snippet = make_code_snippet(title, content, desc_for_generator)
+            code_snippet = make_code_snippet(
+                title,
+                content,
+                desc_for_generator,
+                llm_provider=self.provider,
+                llm_model_name=self.model_name,
+                llm_api_key=self.api_key
+            )
             
             if code_snippet:
-                code_examples.append(CodeExample(language="python", code=code_snippet,
-                                                 description=actual_display_desc))
-                return_value = f'[AGENT_CODE_PLACEHOLDER_{len(code_examples) - 1}]' 
-                logging.info(f"ExplainerAgent: Generated code for title '{actual_display_desc}', "
-                             f"returning placeholder: '{return_value}'")
-                return return_value
+                # 1. Create the CodeExample object
+                new_code_example = CodeExample(language="python", code=code_snippet,
+                                               description=actual_display_desc)
+                # 2. Add it to the list that app.py will use
+                code_examples.append(new_code_example)
+                
+                # 3. Get the index of the newly added item
+                insertion_index = len(code_examples) - 1
+                
+                # 4. Create the EXACT placeholder your app.py expects
+                placeholder = f"[CODE_INSERTION_POINT_{insertion_index}]"
+
+                logging.info(f"ExplainerAgent: Generated code for '{actual_display_desc}', "
+                             f"returning placeholder: '{placeholder}'")
+                return placeholder
             else:
                 logging.warning(f"ExplainerAgent: make_code_snippet returned empty for description: "
                                 f"'{desc_for_generator}'. Removing placeholder from markdown.")

agents/explainer/explain_prompt.py

@@ -13,61 +13,61 @@ The following information has been retrieved from the original document and is h
 ---
 """
     return f"""
-You are an expert AI assistant specializing in transforming complex concepts into deeply insightful, structured explanations. Your goal is to produce thoughtful, thorough educational content—avoiding repetition and encouraging deep analytical reasoning.
+You are an expert AI assistant specializing in transforming complex concepts into deeply insightful, structured explanations. Your goal is to produce thoughtful, thorough educational content.
 
 **MANDATORY REQUIREMENTS:**
 
-1. **Structure and Formatting:**
-   - Start with a clear, concise introduction to the topic.
-   - Break the content into logically organized sections using appropriate markdown headings.
-   - Use **bold** for key terms and bullet points for lists.
-   - **Use standard MathJax LaTeX for all mathematics:**
-     - Inline math: `$ E=mc^2 $`
-     - Display math: `$$ \int_a^b f(x) dx $$`
-   - End with a summary or key takeaways.
-   - Only use tools (e.g., visual aids or code placeholders) when they add significant explanatory value.
-   - **IMPORTANT:** Ensure the final markdown output does NOT end with any trailing backticks (```).
+**1. Agent Workflow - CRITICAL:**
+- **Think:** Analyze the request and formulate a plan in a `Thought:` block.
+- **Act (Optional):** If a tool is needed, use `Action:` and `Action Input:` to call it.
+- **Observe:** The system will provide an `Observation:` with the tool's result (a success or an error).
+- **Finalize:**
+    - If the tool was successful, your NEXT and FINAL step is to generate the complete markdown explanation in an `Answer:` block. **Do not try to use another tool or repeat the `Thought:` process.**
+    - If the tool failed, you can try to correct your `Action Input` in a new `Thought:` and `Action:` sequence.
 
-2. **Code Examples - CRITICAL:**
-   - Represent ALL Python code exclusively using this format: `[CODE: specific description of what the code does]`.
-   - DO NOT use triple backticks for code blocks (e.g., ```python).
-   - Each description must be unique, precise, and clearly reflect the function or purpose of the code.
-     - ✅ Examples:
-       - `[CODE: Python function to calculate acceleration from force and mass]`
-       - `[CODE: Loading and filtering a CSV file with pandas]`
-     - ❌ Forbidden descriptions:
-       - "Code snippet", "Example", "Sample code", "Python Script"
-   - The code (to be generated by another system) must be self-contained:
-     - Include all necessary `import` statements.
-     - Initialize variables with meaningful example values.
-     - End with a `print()` statement to show the final result/output. This is essential for ensuring output visibility.
+**2. Tools: Code and Figures - CRITICAL:**
+Your role is to insert **placeholders** for code and figures. Another system will generate the actual content. You must follow these formats precisely.
 
-3. **Visual Aids - CRITICAL:**
-   - Use the `make_figure` tool **only** when the content includes numerical data or clear categorical comparisons suitable for visualization.
-   - Insert a placeholder exactly like this where the figure should appear: `[FIGURE_PATH: /path/to/figure.png]`
-   - DO NOT use `[FIGURE: {{...}}]` or JSON-style placeholders—these will not be processed correctly.
-   - Ensure the visual aid enhances clarity, provides insight, or enables comparison—not simply decorates the explanation.
+   **A. Code Placeholders:**
+   - **Your Task:** When you provide a mathematical, coding or relevant sbuject examples, you MUST immediately follow it with a `[CODE: ...]` placeholder.
+   - **CRITICAL:** The description inside the placeholder must be a **specific, runnable task that solves the exact example you just described.** This makes the code interactive and relevant. The code must be self-contained and print the final result.
+   - **Another system will generate the code.** Your job is ONLY to create this hyper-specific placeholder. Do not write any Python code yourself (no ```python).
 
-4. **Content Quality:**
-   - Provide deep, step-by-step explanations using real-world analogies and relatable examples.
-   - Clearly define all technical terms.
-   - Maintain an encouraging, educational tone.
-   - **Synthesize the 'Retrieved Context' with the 'Raw Content/Context'** to build a document-specific and relevant explanation.
-   - **Avoid hallucinating** facts not present in either source.
-   - **Avoid redundancy:** Each section should add new value. Do not restate the same point in different words.
-   - **Final Review Step:** After composing the explanation, pause and review it. Deepen any shallow sections, remove repetition, and ensure every sentence adds clarity or insight.
-   - **Enhanced Intelligence Requirements:** Think critically and analytically about the topic. Question assumptions, explore nuances, and provide multi-layered explanations that demonstrate deep understanding rather than surface-level coverage.
-- **Factual Precision:** Cross-reference information within the provided context and retrieved documents. If the content is factual/informational, verify consistency and flag any potential contradictions. Prioritize accuracy over speed of response.
-- **Adaptive Detail Level:** For creative content, unleash full creative potential with rich imagery, character development, and narrative depth. For document-based content, maintain strict fidelity to source material while expanding explanations using your knowledge base to illuminate complex concepts.
+     - ✅ **Correct Example:**
+       - ... an explanation of `∫ x*e^x dx`.
+       - `[CODE: Python code using SymPy to symbolically solve the integral of x*e^x and print the result]`
 
-5. **INTELLIGENCE AND ACCURACY MANDATE:**
-- If this is creative content: Be imaginative, original, and emotionally engaging while maintaining internal consistency.
-- If this is document-based information: Treat the source document as authoritative truth. Reference it religiously, quote directly when appropriate, and use your knowledge only to provide additional context that enhances understanding without contradicting the source.
-- In all cases: Demonstrate intellectual rigor by exploring implications, connections, and deeper meanings rather than just restating information.
+     - ❌ **Incorrect Example:**
+       - ... an explanation of `∫ x*e^x dx`.
+       - `[CODE: Python code for integration plotting]` (This is too generic and will result in non-runnable template code! ALSO DO NOT TRY TO PLOT IN CODE PLACEHOLDER)
 
+   **B. `make_figure` Tool:**
+   - **Your Task:** To request a figure, call the `make_figure` tool. It will return a file path.
+   - **CRITICAL WORKFLOW:** After the tool returns a path in the `Observation:`, you MUST use that exact path to create the placeholder in your final `Answer:`, like this: `[FIGURE_PATH: <filepath_returned_by_tool>]`.
+   - **Tool Definition:** You MUST adhere strictly to this signature. Note that labels go *inside* the `data` dictionary.
+     - **Signature:** `make_figure(title: str, content: str, chart_type: str, data: Dict[str, Any])`
+     - **Data Structure for "line_graph", "bar_chart", "scatter_plot":**
+       - `data`: `{{ "x": [...], "y": [...], "x_label": "...", "y_label": "..." }}`
+     - **Data Structure for "pie_chart":**
+       - `data`: `{{ "labels": [...], "sizes": [...] }}`
+
+**3. General Formatting:**
+   - Start with a clear introduction.
+   - Use markdown headings (`##`, `###`) to organize content.
+   - Use **bold** for key terms and bullet points for lists.
+   - Use standard MathJax LaTeX for all mathematics: `$E=mc^2$` (inline) and `$$ ... $$` (display).
+   - End with a summary or key takeaways.
+
+**4. Content Quality:**
+   - Provide deep, step-by-step explanations with real-world analogies.
+   - Clearly define all technical terms.
+   - Synthesize the 'Retrieved Context' with the 'Raw Content/Context' for a relevant explanation.
+   - Avoid hallucination and redundancy.
+
+---
 **Topic to Explain:** {title}
 
 **Raw Content/Context:** {content}
 {context_section}
 **Your Explanation (in Markdown):**
-"""
+"""

agents/explainer/tools/code_generator.py

@@ -1,8 +1,16 @@
+import re
 import textwrap
+from typing import Optional 
 from services.llm_factory import get_completion_fn
-import re # Added this import
 
-def make_code_snippet(title: str, content: str, suggestion: str) -> str:
+def make_code_snippet(
+    title: str,
+    content: str,
+    suggestion: str,
+    llm_provider: str,
+    llm_model_name: Optional[str] = None,
+    llm_api_key: Optional[str] = None
+) -> str:
     """Generate a code snippet based on suggestion using LLM."""
     if not suggestion.strip():
         return textwrap.dedent(
@@ -13,24 +21,34 @@ def make_code_snippet(title: str, content: str, suggestion: str) -> str:
         )
     
     prompt = f"""
-    Generate a concise and functional Python code snippet based on the following unit and suggestion.
-    The code should directly illustrate a key concept from the unit.
-    Do not include excessive comments or explanations within the code itself.
-    IMPORTANT: Do NOT include `plt.show()` or any other interactive plotting commands. If a plot is suggested,
-    assume it will be handled by a separate visualization component. Focus solely on the data processing or
-    algorithmic logic.
+    You are an expert Python programmer tasked with generating a single, self-contained, and runnable code snippet.
     
-    Unit Title: {title}
-    Unit Content: {content}
-    Code Suggestion: {suggestion}
+    **Task:**
+    Generate a concise Python code snippet that directly implements the following request.
+    - The code MUST be self-contained (include all necessary imports).
+    - The code MUST end with a `print()` statement to show the final result.
+    - For mathematical/scientific tasks, **strongly prefer using libraries like `numpy`, `scipy`, and `sympy`** to ensure the code is correct and robust.
+    - Do not include any explanations or comments outside of essential clarifications.
+    - Do not use plotting libraries like matplotlib.
+
+    **Request:** "{suggestion}"
     
+    **Full Context (for reference):**
+    - Unit Title: {title}
+    - Unit Content: {content}
+
+    **Your Python Code Snippet:**
     ```python
     # Your code here
     ```
     """
     
     try:
-        llm = get_completion_fn("mistral") # Using mistral for code generation
+        llm = get_completion_fn(
+            provider=llm_provider, 
+            model_name=llm_model_name, 
+            api_key=llm_api_key
+        )
         response = llm(prompt)
         
         # Extract code block, being more flexible with whitespace around backticks
@@ -40,10 +58,12 @@ def make_code_snippet(title: str, content: str, suggestion: str) -> str:
         
         # Fallback if no code block is found, return the whole response
         return response.strip()
-    except Exception:
+    except Exception as e: 
+        logging.error(f"Failed to generate code for '{title}' due to LLM error: {e}", exc_info=True)
         return textwrap.dedent(
             f"""
             # Failed to generate code for {title}
             # Content preview: {content[:40]}...
+            # Error: {e}
             """
-        )
+        )

agents/explainer/tools/figure_generator.py

@@ -1,10 +1,7 @@
-import json
+import tempfile
+from typing import Dict, Any
 import plotly.graph_objects as go
 from llama_index.core.tools import FunctionTool
-from typing import Dict, Any
-import tempfile
-import uuid
-import os
 
 def make_figure(
     title: str, 

app.py

@@ -119,7 +119,7 @@ def create_app():
                         gr.Markdown("### ✍️ Paste Content")
                         text_in = create_text_input(lines=8)
                 with gr.Row():
-                    input_type = gr.Radio(choices=["PDF", "Text"], value="Text", label="Content Type")
+                    input_type = gr.Radio(choices=["File", "Text"], value="Text", label="Content Type")
                 plan_btn = create_primary_button("🚀 Process with AI")
                 plan_status = create_status_markdown(
                     "Upload content and click 'Process with AI' to generate learning units."