Uploading Files

agent.py

@@ -0,0 +1,165 @@
+"""
+CodeMentor Automata - Agent & Orchestration (LangGraph Upgraded)
+Implements a state-of-the-art LangGraph ReAct agent bound to DuckDuckGo 
+to search unfamiliar libraries and return verified documentation.
+"""
+import re
+from ddgs import DDGS
+from langgraph.prebuilt import create_react_agent
+from langchain_community.tools import DuckDuckGoSearchRun
+from langchain_groq import ChatGroq
+
+from config import GROQ_API_KEY1, GROQ_MODEL
+from prompts import (
+    LEVEL_PROMPTS, JSON_OUTPUT_INSTRUCTIONS, PLAN_PROMPT,
+    CLEANUP_PROMPT, OPTIMIZATION_PROMPT, RESOURCE_QUERY_HINT,
+    TOPIC_EXTRACTION_PROMPT,
+)
+from llm import call_groq_json
+
+_search_tool = DuckDuckGoSearchRun()
+_search_tool.name = "duckduckgo_search"  # Required for LangGraph routing
+
+# Common stdlib modules we don't bother looking up
+_KNOWN_STDLIB = {
+    "os", "sys", "json", "re", "math", "time", "random", "collections",
+    "itertools", "functools", "typing", "datetime", "string", "copy",
+}
+
+
+def _get_llm(temperature=0.2):
+    if not GROQ_API_KEY1:
+        raise RuntimeError("GROQ_API_KEY not set.")
+    return ChatGroq(model=GROQ_MODEL, temperature=temperature, api_key=GROQ_API_KEY1)
+
+
+def _build_doc_agent():
+    """Builds a modern LangGraph ReAct agent."""
+    llm = _get_llm()
+    tools = [_search_tool]
+
+    # LangGraph handles the system prompting and ReAct loop automatically
+    return create_react_agent(llm, tools)
+
+
+def _detect_candidate_libraries(code: str) -> list:
+    """Heuristic: pull import statements as agent search candidates."""
+    imports = re.findall(r"^\s*(?:import|from)\s+([\w\.]+)", code, re.MULTILINE)
+    top_level = {imp.split(".")[0] for imp in imports}
+    return sorted(top_level - _KNOWN_STDLIB)
+
+
+def _youtube_thumbnail(url: str):
+    match = re.search(r"(?:v=|youtu\.be/)([\w-]{11})", url)
+    return f"https://img.youtube.com/vi/{match.group(1)}/hqdefault.jpg" if match else None
+
+
+def _structured_citations(query: str, max_results: int = 3) -> list:
+    """Direct DDGS search — real titles + links, so citations are always structured."""
+    try:
+        with DDGS() as ddgs:
+            raw = list(ddgs.text(query, max_results=max_results))
+    except Exception:
+        return []
+    return [
+        {
+            "title": r.get("title", "Untitled"),
+            "url": r.get("href", ""),
+            "snippet": (r.get("body", "") or "")[:160],
+            "thumbnail": _youtube_thumbnail(r.get("href", "")),
+        }
+        for r in raw
+    ]
+
+
+def search_documentation(code: str) -> list:
+    candidates = _detect_candidate_libraries(code)
+    if not candidates:
+        return []
+
+    try:
+        agent = _build_doc_agent()
+    except RuntimeError as e:
+        return [{"library": lib, "summary": f"(doc search unavailable: {e})", "citations": []} for lib in candidates]
+
+    findings = []
+    for lib in candidates:
+        try:
+            query = (
+                f"Search for official documentation on the '{lib}' Python library/module "
+                f"and summarize in 2-3 sentences what it's for and the most relevant "
+                f"function/API that would show up in a typical code snippet."
+            )
+            response = agent.invoke({"messages": [("user", query)]})
+            summary = response["messages"][-1].content
+        except Exception as e:
+            summary = f"(doc search failed: {e})"
+
+        citations = _structured_citations(f"{lib} python library documentation", max_results=3)
+        findings.append({"library": lib, "summary": summary, "citations": citations})
+
+    return findings
+
+
+def extract_code_topic(code: str, language: str) -> str:
+    """
+    Identifies the core algorithm/data-structure/concept the code implements
+    (e.g. "Dijkstra's Algorithm", "Binary Search"), so resource search can
+    target that exact topic instead of just the language name or raw import
+    names — this is what makes 'Further Resources' show topic-specific
+    videos/articles rather than generic language tutorials.
+    """
+    try:
+        result = call_groq_json(TOPIC_EXTRACTION_PROMPT, f"Language: {language}\n\nCode:\n{code}")
+        topic = (result or {}).get("topic", "").strip()
+        return topic or f"{language} programming"
+    except Exception:
+        return f"{language} programming"
+
+
+def find_resources(language: str, topic: str) -> dict:
+    """
+    Finds learning resources for the CORE TOPIC extracted from the code
+    (e.g. "Dijkstra's Algorithm"), not just the language name. A dedicated
+    video-biased query runs first — a walkthrough video of a named
+    algorithm/concept is usually the most useful resource — then a broader
+    query fills in with articles/docs, skipping anything already found.
+    """
+    video_query = f"{topic} {language} explained tutorial site:youtube.com"
+    article_query = f"{topic} {language} tutorial {RESOURCE_QUERY_HINT}"
+
+    video_citations = _structured_citations(video_query, max_results=3)
+    seen_urls = {c["url"] for c in video_citations}
+    article_citations = [
+        c for c in _structured_citations(article_query, max_results=4)
+        if c["url"] not in seen_urls
+    ]
+
+    citations = video_citations + article_citations
+    return {
+        "query": video_query,
+        "topic": topic,
+        "citations": citations,
+        "ok": bool(citations),
+    }
+
+
+def generate_breakdown(code: str, language: str, level: str) -> dict:
+    system_prompt = LEVEL_PROMPTS[level] + "\n\n" + JSON_OUTPUT_INSTRUCTIONS
+    user_content = f"Language: {language}\n\nCode:\n{code}"
+    return call_groq_json(system_prompt, user_content)
+
+
+def generate_plan(code: str, language: str) -> dict:
+    user_content = f"Language: {language}\n\nCode:\n{code}"
+    return call_groq_json(PLAN_PROMPT, user_content)
+
+
+def cleanup_code(code: str, language: str) -> dict:
+    user_content = f"Language: {language}\n\nCode:\n{code}"
+    return call_groq_json(CLEANUP_PROMPT, user_content)
+
+
+def suggest_optimal_solution(code: str, language: str) -> dict:
+    user_content = f"Language: {language}\n\nCode:\n{code}"
+    return call_groq_json(OPTIMIZATION_PROMPT, user_content)

app.py

@@ -0,0 +1,491 @@
+"""
+CodeMentor Automata - Main Gradio App
+"""
+import os
+import difflib
+import tempfile
+
+import gradio as gr
+
+from config import SUPPORTED_LANGUAGES, EXPLANATION_LEVELS
+from llm import call_groq_chat, call_groq_vision_ocr, LLMNotConfiguredError
+from agent import (
+    generate_breakdown, generate_plan, cleanup_code,
+    suggest_optimal_solution, search_documentation, find_resources,
+    extract_code_topic,
+)
+from error_detector import detect_errors
+from sandbox import benchmark_two_versions, verify_fix_equivalence
+from store import get_progress_snapshot
+from prompts import FOLLOWUP_SYSTEM_PROMPT_TEMPLATE
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _validate_inputs(code: str) -> bool:
+    if not code or not code.strip():
+        gr.Warning("Please paste a code snippet before running an analysis.")
+        return False
+    return True
+
+def _greeting_message(language=None, level=None):
+    if language and level:
+        text = (
+            f"Got it! I've analyzed your **{language}** code at **{level}** level. "
+            "Ask me anything about it — bugs, alternate approaches, or just \"explain line 5 again\"."
+        )
+    else:
+        text = (
+            "👋 Hi, I'm CodeMentor! Head over to the **Analyze Code** tab first and run an analysis — "
+            "once that's done, come back here and I'll remember the context for follow-up questions."
+        )
+    return [{"role": "assistant", "content": text}]
+
+
+def _safe_call(label, fn, *args, **kwargs):
+    """Runs fn and never lets an exception escape to the UI as a raw traceback."""
+    try:
+        return fn(*args, **kwargs), None
+    except LLMNotConfiguredError as e:
+        return None, f"{label} unavailable — {e}"
+    except Exception as e:
+        return None, f"{label} failed — {e}"
+    
+def _citation_cards_html(citations: list) -> str:
+    if not citations:
+        return "<p style='opacity:0.7'>No citations found.</p>"
+    cards = []
+    for i, c in enumerate(citations, start=1):
+        thumb = (
+            f"<img src='{c['thumbnail']}' style='width:120px;height:68px;object-fit:cover;border-radius:6px;margin-right:12px;'/>"
+            if c.get("thumbnail") else
+            "<div style='width:120px;height:68px;background:#2a2a2a;border-radius:6px;margin-right:12px;"
+            "display:flex;align-items:center;justify-content:center;font-size:22px;'>🔗</div>"
+        )
+        cards.append(f"""
+        <div style='display:flex;align-items:center;padding:10px;border-bottom:1px solid #333;'>
+          <div style='min-width:24px;font-weight:bold;opacity:0.6;'>{i}.</div>
+          {thumb}
+          <div>
+            <a href='{c['url']}' target='_blank' style='font-weight:600;text-decoration:none;'>{c['title']}</a>
+            <div style='font-size:12px;opacity:0.7;margin-top:2px;'>{c.get('snippet','')}</div>
+          </div>
+        </div>""")
+    return "<div style='max-height:280px;overflow-y:auto;border:1px solid #333;border-radius:8px;'>" + "".join(cards) + "</div>"
+
+
+
+def build_session_report(code, language, level, breakdown_md, analogy_md,
+                          errors_md, cleanup_md, optimal_md, docs_md, resources_md) -> str:
+    report = (
+        "# CodeMentor Automata — Session Report\n\n"
+        f"**Language:** {language}  |  **Explanation level:** {level}\n\n"
+        "## Original Code\n"
+        f"```{language}\n{code}\n```\n\n"
+        "## Explanation\n"
+        f"{breakdown_md}\n\n"
+        "## Analogy\n"
+        f"{analogy_md}\n\n"
+        "## Errors & Weakness Review\n"
+        f"{errors_md}\n\n"
+        "## Cleanup\n"
+        f"{cleanup_md}\n\n"
+        "## Optimal Solution\n"
+        f"{optimal_md}\n\n"
+        "## Documentation Findings\n"
+        f"{docs_md}\n\n"
+        "## Further Resources\n"
+        f"{resources_md}\n"
+    )
+    tmp_dir = tempfile.mkdtemp(prefix="codementor_report_")
+    path = os.path.join(tmp_dir, "codementor_session_report.md")
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(report)
+    return path
+
+
+# ---------------------------------------------------------------------------
+# Tab 1 callbacks — Analyze Code
+# ---------------------------------------------------------------------------
+
+def on_generate_plan(code, language):
+    if not _validate_inputs(code):
+        return gr.update(value="", visible=False), gr.update(visible=False)
+
+    plan, err = _safe_call("Plan generation", generate_plan, code, language)
+    if err:
+        gr.Warning(err)
+        return gr.update(value="", visible=False), gr.update(visible=False)
+
+    steps = (plan or {}).get("steps", [])
+    plan_md = "**Here's what I'll run:**\n\n" + "\n".join(f"- {s}" for s in steps)
+    if (plan or {}).get("estimated_focus"):
+        plan_md += f"\n\n*Focus: {plan['estimated_focus']}*"
+
+    return gr.update(value=plan_md, visible=True), gr.update(visible=True)
+
+def on_extract_from_image(image_path):
+    if not image_path:
+        gr.Warning("Please upload an image first.")
+        return gr.update()
+    extracted, err = _safe_call("Vision OCR", call_groq_vision_ocr, image_path)
+    if err:
+        gr.Warning(err)
+        return gr.update()
+    if not extracted:
+        gr.Warning("Couldn't extract any code from that image — try a clearer photo.")
+        return gr.update()
+    gr.Info("Code extracted — please review it before running analysis, OCR can misread characters.")
+    return gr.update(value=extracted)
+
+
+def on_cancel_plan():
+    return gr.update(value="", visible=False), gr.update(visible=False)
+
+
+def on_approve_run(code, language, level, progress=gr.Progress()):
+    empty_return = ("", "", "", "", "", "", "", None, gr.update(visible=False), gr.update(visible=False))
+    if not _validate_inputs(code):
+        return empty_return
+
+    # --- Explanation & breakdown ---
+    progress(0.1, desc="Explaining code...")
+    breakdown_result, err = _safe_call("Explanation", generate_breakdown, code, language, level)
+    if err:
+        gr.Warning(err)
+    breakdown_items = (breakdown_result or {}).get("breakdown", [])
+    breakdown_md = "\n\n".join(
+        f"**{item.get('line_or_block', '')}** — {item.get('explanation', '')}" for item in breakdown_items
+    ) or "_No breakdown available._"
+    analogy_md = (breakdown_result or {}).get("analogy") or "_No analogy returned._"
+    bugs = (breakdown_result or {}).get("bugs", [])
+
+    # --- Multi-type error detection & weakness review ---
+    progress(0.3, desc="Detecting errors & weaknesses...")
+    err_result, err = _safe_call("Error detection", detect_errors, code, language)
+    if err:
+        gr.Warning(err)
+
+    content_lines = []
+    if err_result:
+        if err_result["syntax"]["found"]:
+            content_lines.append(f"🔴 **Syntax error**: {err_result['syntax']['message']}")
+        if err_result["runtime"]["found"]:
+            content_lines.append(f"🔴 **Runtime error**: {err_result['runtime']['message']}")
+        if err_result["tle"]["found"]:
+            content_lines.append(f"🟠 **TLE**: {err_result['tle']['message']}")
+        for issue in err_result["logical"]["issues"]:
+            content_lines.append(
+                f"🟡 **Logical issue**: {issue.get('description', '')}\n   ↳ Fix: {issue.get('suggested_fix', '')}"
+            )
+        for bug in bugs:
+            content_lines.append(f"🟡 {bug.get('description', '')}\n   ↳ Fix: {bug.get('concrete_fix', '')}")
+        if not content_lines:
+            content_lines.append("✅ No errors detected.")
+        if err_result.get("weakness_note"):
+            content_lines.append(f"\n📊 **Weakness note**: {err_result['weakness_note']}")
+        if not err_result.get("verified_by_execution"):
+            content_lines.append("\n_Note: this language is checked via LLM static estimate, not sandboxed execution._")
+    elif err:
+        content_lines.append(f"⚠️ {err}")
+    else:
+        content_lines.append("No error data available.")
+    errors_md = "\n\n".join(content_lines)
+
+    # --- Cleanup pass ---
+    progress(0.5, desc="Cleaning up code...")
+    clean_res, err = _safe_call("Cleanup", cleanup_code, code, language)
+    if err:
+        gr.Warning(err)
+    clean_res = clean_res or {}
+    cleaned_code = clean_res.get("cleaned_code", "") or ""
+
+    cleanup_lines = []
+    if clean_res.get("needs_cleanup") and cleaned_code.strip():
+        diff = difflib.unified_diff(
+            code.splitlines(), cleaned_code.splitlines(),
+            fromfile="original", tofile="cleaned", lineterm="",
+        )
+        diff_text = "\n".join(diff)
+        cleanup_lines.append(f"```diff\n{diff_text}\n```" if diff_text else "No line-level differences.")
+
+        changes = clean_res.get("changes_made", [])
+        if changes:
+            cleanup_lines.append("**Changes made:**\n" + "\n".join(f"- {c}" for c in changes))
+
+        if language == "python":
+            equivalence, eq_err = _safe_call("Fix verification", verify_fix_equivalence, code, cleaned_code)
+            if eq_err:
+                cleanup_lines.append(f"⚠️ Could not verify equivalence — {eq_err}")
+            elif equivalence:
+                if equivalence["outputs_match"]:
+                    cleanup_lines.append("✅ **Verified by execution**: cleaned code produces identical output to the original.")
+                else:
+                    cleanup_lines.append(
+                        "⚠️ **Could not confirm equivalence** — outputs differ. Please review the cleaned version before trusting it."
+                    )
+    elif err:
+        cleanup_lines.append(f"⚠️ {err}")
+    else:
+        cleanup_lines.append("Code already looks clean — no restructuring needed.")
+    cleanup_md = "\n\n".join(cleanup_lines)
+
+    # --- Optimal solution pass ---
+    progress(0.7, desc="Checking for a better approach...")
+    opt_res, err = _safe_call("Optimization", suggest_optimal_solution, code, language)
+    if err:
+        gr.Warning(err)
+    opt_res = opt_res or {}
+
+    optimal_lines = []
+    cur = opt_res.get("current_complexity", {}) or {}
+    structures = opt_res.get("data_structures_used", []) or []
+    pattern = opt_res.get("algorithm_pattern", "")
+
+    if opt_res:
+        optimal_lines.append(f"**Time complexity:** {cur.get('time', '?')}  |  **Space complexity:** {cur.get('space', '?')}")
+        if structures:
+            optimal_lines.append(f"**Data structures used:** {', '.join(structures)}")
+        if pattern:
+            optimal_lines.append(f"**Pattern:** {pattern}")
+
+        if opt_res.get("has_better_approach"):
+            sug = opt_res.get("suggested_complexity", {}) or {}
+            optimal_lines.append(f"**Suggested complexity:** time {sug.get('time', '?')}, space {sug.get('space', '?')}")
+            if opt_res.get("explanation"):
+                optimal_lines.append(f"**Why it's better:** {opt_res['explanation']}")
+            suggested_code = opt_res.get("suggested_code", "") or ""
+            if suggested_code.strip():
+                optimal_lines.append(f"```{language}\n{suggested_code}\n```")
+                if language == "python":
+                    bench, bench_err = _safe_call("Benchmark", benchmark_two_versions, code, suggested_code)
+                    if bench_err:
+                        optimal_lines.append(f"⚠️ Could not measure runtime — {bench_err}")
+                    elif bench:
+                        optimal_lines.append(
+                            f"**Measured runtime** — original: {bench['original_runtime']}s "
+                            f"({'ok' if bench['original_ok'] else 'failed/TLE'}), "
+                            f"suggested: {bench['optimized_runtime']}s "
+                            f"({'ok' if bench['optimized_ok'] else 'failed/TLE'})"
+                        )
+                        if bench.get("speedup"):
+                            optimal_lines.append(f"🚀 Speedup: {bench['speedup']}x")
+        else:
+            optimal_lines.append(f"**Why this is already optimal:** {opt_res.get('explanation', 'No further improvement possible.')}")
+    elif err:
+        optimal_lines.append(f"⚠️ {err}")
+    else:
+        optimal_lines.append("Optimization analysis unavailable.")
+    optimal_md = "\n\n".join(optimal_lines)
+
+
+    # --- Documentation search ---
+    progress(0.85, desc="Searching documentation...")
+    doc_findings, err = _safe_call("Documentation search", search_documentation, code)
+    if err:
+        docs_html = f"<p>⚠️ {err}</p>"
+    elif doc_findings:
+        blocks = []
+        for d in doc_findings:
+            blocks.append(f"<h4>{d['library']}</h4><p>{d['summary']}</p>")
+            blocks.append(_citation_cards_html(d.get("citations", [])))
+        docs_html = "".join(blocks)
+    else:
+        docs_html = "<p>No unfamiliar libraries detected — nothing to look up.</p>"
+
+    # --- Resource finder (topic-based, not just language-based) ---
+    progress(0.9, desc="Identifying core topic...")
+    topic, err = _safe_call("Topic extraction", extract_code_topic, code, language)
+    topic = topic or f"{language} programming"
+
+    progress(0.95, desc=f"Finding resources on {topic}...")
+    resources, err = _safe_call("Resource search", find_resources, language, topic)
+    if err:
+        resources_html = f"<p>⚠️ {err}</p>"
+    elif resources and resources.get("ok"):
+        topic_header = (
+            f"<p style='opacity:0.75;font-size:13px;margin-bottom:8px;'>"
+            f"📌 Topic identified: <strong>{topic}</strong></p>"
+        )
+        resources_html = topic_header + _citation_cards_html(resources.get("citations", []))
+    else:
+        resources_html = f"<p>No resources found for <strong>{topic}</strong> this time — try again in a moment.</p>"
+
+
+    # --- Downloadable report ---
+    report_path = None
+    try:
+        report_path = build_session_report(
+            code, language, level, breakdown_md, analogy_md,
+            errors_md, cleanup_md, optimal_md, docs_html, resources_html,
+        )
+    except Exception as e:
+        gr.Warning(f"Could not build downloadable report: {e}")
+
+    progress(1.0, desc="Done!")
+    return (
+        breakdown_md, analogy_md, errors_md, cleanup_md, optimal_md,
+        docs_html, resources_html, report_path,
+        gr.update(visible=False), gr.update(visible=False),
+    )
+    
+
+# ---------------------------------------------------------------------------
+# Tab 2 callbacks — Chat / Follow-up
+# ---------------------------------------------------------------------------
+
+def on_chat_send(message, chat_history, last_code, last_language, last_level):
+    chat_history = chat_history or []
+    if not message or not message.strip():
+        return chat_history, ""
+    if not last_code:
+        gr.Warning("Analyze a code snippet in the 'Analyze Code' tab first so I have context for follow-ups.")
+        chat_history = chat_history + [
+            {"role": "user", "content": message},
+            {"role": "assistant", "content": "⚠️ I don't have any code to discuss yet — please run an analysis in the **Analyze Code** tab first."},
+        ]
+        return chat_history, ""
+
+    system_prompt = FOLLOWUP_SYSTEM_PROMPT_TEMPLATE.format(
+        level=last_level or "Intermediate",
+        language=last_language or "python",
+        code=last_code,
+    )
+    api_history = chat_history
+
+    try:
+        reply = call_groq_chat(system_prompt, api_history, message)
+    except LLMNotConfiguredError as e:
+        reply = f"⚠️ {e}"
+    except Exception as e:
+        reply = f"⚠️ Something went wrong answering that: {e}"
+
+    chat_history = chat_history + [
+        {"role": "user", "content": message},
+        {"role": "assistant", "content": reply},
+    ]
+    return chat_history, ""
+# ---------------------------------------------------------------------------
+# Tab 3 callbacks — My Progress
+# ---------------------------------------------------------------------------
+
+def on_refresh_progress():
+    try:
+        return get_progress_snapshot()
+    except Exception as e:
+        gr.Warning(f"Could not refresh progress: {e}")
+        return gr.update(), gr.update(), gr.update()
+
+# ---------------------------------------------------------------------------
+# UI
+# ---------------------------------------------------------------------------
+
+with gr.Blocks(title="CodeMentor Automata") as demo:
+    gr.Markdown("# 🧑‍💻 CodeMentor Automata\nYour personal, execution-verified coding coach.")
+
+    state_last_code = gr.State("")
+    _initial_table, _initial_chart, _initial_summary = get_progress_snapshot()
+    state_last_language = gr.State(SUPPORTED_LANGUAGES[0])
+    state_last_level = gr.State(EXPLANATION_LEVELS[0])
+
+    with gr.Tab("Analyze Code"):
+        with gr.Row():
+            with gr.Column(scale=2):
+                code_input = gr.Textbox(label="Paste your code", lines=16, placeholder="Paste your code here, or upload a screenshot below…")
+                with gr.Accordion("📸 Or upload a code screenshot", open=False):
+                    image_input = gr.Image(label="Code screenshot", type="filepath", height=240)
+                    extract_btn = gr.Button("🔍 Extract Code from Image", variant="secondary")
+            with gr.Column(scale=1):
+                language_dd = gr.Dropdown(SUPPORTED_LANGUAGES, value=SUPPORTED_LANGUAGES[0], label="Language")
+                level_dd = gr.Dropdown(EXPLANATION_LEVELS, value=EXPLANATION_LEVELS[0], label="Explanation level")
+                plan_btn = gr.Button("1. Preview Plan", variant="primary")
+
+        plan_output = gr.Markdown(visible=False)
+        with gr.Row(visible=False) as plan_actions:
+            approve_btn = gr.Button("✅ Approve & Run Analysis", variant="primary")
+            cancel_btn = gr.Button("❌ Cancel")
+
+        with gr.Accordion("📖 Breakdown", open=True):
+            breakdown_out = gr.Markdown()
+        with gr.Accordion("💡 Analogy", open=False):
+            analogy_out = gr.Markdown()
+        with gr.Accordion("🐞 Errors & Weakness Review", open=True):
+            errors_out = gr.Markdown()
+        with gr.Accordion("🧹 Cleanup Diff", open=False):
+            cleanup_out = gr.Markdown()
+        with gr.Accordion("⚡ Optimal Solution", open=False):
+            optimal_out = gr.Markdown()
+        with gr.Accordion("📚 Documentation Findings", open=False):
+            docs_out = gr.HTML()
+        with gr.Accordion("🔗 Further Resources", open=False):
+            resources_out = gr.HTML()
+
+        report_file = gr.File(label="Download session report")
+
+    with gr.Tab("Chat / Follow-up"):
+        gr.Markdown("Ask follow-up questions about the code you analyzed — I'll remember the context.")
+        chatbot = gr.Chatbot(label="CodeMentor", height=400, value=_greeting_message())
+        chat_input = gr.Textbox(label="Your question", placeholder="e.g. why did you suggest that fix?")
+        chat_send_btn = gr.Button("Send", variant="primary")
+
+    with gr.Tab("My Progress"):
+        gr.Markdown("Your language-wise revision history and skill breakdown.")
+        refresh_btn = gr.Button("🔄 Refresh")
+        revision_table = gr.Dataframe(
+            headers=["Language", "Submissions", "Syntax Errors", "Logical Errors", "TLE Count", "Last Seen"],
+            value=_initial_table,
+            interactive=False,
+        )
+        skill_pie = gr.Plot(value=_initial_chart)
+        skill_summary = gr.Markdown(value=_initial_summary)
+
+    # ------------------------------ Event wiring ------------------------------
+     
+    plan_btn.click(
+        on_generate_plan,
+        inputs=[code_input, language_dd],
+        outputs=[plan_output, plan_actions],
+    )
+
+    cancel_btn.click(
+        on_cancel_plan,
+        outputs=[plan_output, plan_actions],
+    )
+     
+    extract_btn.click(
+        on_extract_from_image,
+        inputs=[image_input],
+        outputs=[code_input],
+    )
+    
+    approve_btn.click(
+        on_approve_run,
+        inputs=[code_input, language_dd, level_dd],
+        outputs=[
+            breakdown_out, analogy_out, errors_out, cleanup_out,
+            optimal_out, docs_out, resources_out, report_file,
+            plan_output, plan_actions,
+        ],
+    ).then(
+    lambda c, l, lv: (c, l, lv, _greeting_message(language=l, level=lv)),
+    inputs=[code_input, language_dd, level_dd],
+    outputs=[state_last_code, state_last_language, state_last_level, chatbot],
+     )
+
+    chat_send_btn.click(
+        on_chat_send,
+        inputs=[chat_input, chatbot, state_last_code, state_last_language, state_last_level],
+        outputs=[chatbot, chat_input],
+    )
+    chat_input.submit(
+        on_chat_send,
+        inputs=[chat_input, chatbot, state_last_code, state_last_language, state_last_level],
+        outputs=[chatbot, chat_input],
+    )
+
+    refresh_btn.click(on_refresh_progress, outputs=[revision_table, skill_pie, skill_summary])
+
+if __name__ == "__main__":
+    demo.launch()

config.py

@@ -0,0 +1,26 @@
+"""
+CodeMentor Automata - Configuration
+Central place for API keys, model names, and constants.
+"""
+import os
+import matplotlib
+from dotenv import load_dotenv
+
+load_dotenv()  # .env file ko actual environment mein load karta hai
+# ---- Groq LLM ----
+# Support either env var name so existing deployments (GROQ_API_KEY1) and the
+# conventional name (GROQ_API_KEY, used internally by langchain_groq) both work.
+GROQ_API_KEY1 = os.environ.get("GROQ_API_KEY1")
+GROQ_MODEL = os.environ.get("GROQ_MODEL", "openai/gpt-oss-120b")  # llama-3.3-70b-versatile deprecated by Groq (2026-06-17)
+GROQ_VISION_MODEL = os.environ.get("GROQ_VISION_MODEL", "qwen/qwen3.6-27b")
+
+# ---- Sandbox execution ----
+TLE_THRESHOLD_SECONDS = float(os.environ.get("TLE_THRESHOLD_SECONDS", "3.0"))
+SANDBOX_TIMEOUT_SECONDS = float(os.environ.get("SANDBOX_TIMEOUT_SECONDS", "5.0"))
+
+# ---- Persistent store ----
+_BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+STORE_PATH = os.environ.get("STORE_PATH", os.path.join(_BASE_DIR, "data", "progress.json"))
+
+SUPPORTED_LANGUAGES = ["python", "javascript", "java", "cpp"]
+EXPLANATION_LEVELS = ["Beginner", "Intermediate", "Expert"]

error_detector.py

@@ -0,0 +1,92 @@
+"""
+CodeMentor Automata - Multi-type Error Detection
+"""
+from sandbox import run_python_sandboxed
+from store import record_submission, get_weakness_note
+from llm import call_groq_json
+from prompts import LOGICAL_ERROR_PROMPT, STATIC_ANALYSIS_PROMPT
+
+
+def detect_errors(code: str, language: str) -> dict:
+    result = {
+        "syntax": {"found": False, "message": ""},
+        "runtime": {"found": False, "message": ""},
+        "tle": {"found": False, "message": "", "runtime_seconds": None},
+        "logical": {"found": False, "issues": []},
+        "weakness_note": "",
+        "verified_by_execution": False,
+    }
+
+    syntax_err = False
+    tle_err = False
+
+    if language == "python":
+        exec_result = run_python_sandboxed(code)
+        result["verified_by_execution"] = True
+        result["tle"]["runtime_seconds"] = exec_result.runtime_seconds
+
+        if exec_result.error_type == "syntax":
+            result["syntax"] = {"found": True, "message": exec_result.error_message}
+            syntax_err = True
+        elif exec_result.error_type == "runtime":
+            result["runtime"] = {"found": True, "message": exec_result.error_message}
+        elif exec_result.error_type == "tle":
+            result["tle"] = {
+                "found": True,
+                "message": exec_result.error_message,
+                "runtime_seconds": exec_result.runtime_seconds,
+            }
+            tle_err = True
+    else:
+        # No sandbox available for this language yet -> hybrid LLM static estimate.
+        try:
+            static_result = call_groq_json(
+                STATIC_ANALYSIS_PROMPT, f"Language: {language}\n\nCode:\n{code}"
+            )
+            if static_result.get("syntax_error_found"):
+                result["syntax"] = {
+                    "found": True,
+                    "message": static_result.get(
+                        "syntax_error_message",
+                        "Potential syntax issue detected (unverified — static estimate).",
+                    ),
+                }
+                syntax_err = True
+            else:
+                result["syntax"]["message"] = (
+                    f"No obvious syntax issues found for {language} "
+                    "(unverified — static LLM estimate, not real execution)."
+                )
+
+            if static_result.get("runtime_error_found"):
+                result["runtime"] = {
+                    "found": True,
+                    "message": static_result.get("runtime_error_message", ""),
+                }
+
+            if static_result.get("tle_risk_found"):
+                result["tle"] = {
+                    "found": True,
+                    "message": static_result.get(
+                        "tle_risk_message",
+                        "Potential performance risk (unverified — static estimate).",
+                    ),
+                    "runtime_seconds": None,
+                }
+                tle_err = True
+        except Exception as e:
+            result["syntax"]["message"] = f"{language} static analysis unavailable: {e}"
+
+    logical_err = False
+    if not syntax_err:
+        try:
+            llm_result = call_groq_json(LOGICAL_ERROR_PROMPT, f"Language: {language}\n\nCode:\n{code}")
+            if llm_result.get("logical_errors_found"):
+                logical_err = True
+                result["logical"] = {"found": True, "issues": llm_result.get("issues", [])}
+        except Exception as e:
+            result["logical"] = {"found": False, "issues": [], "error": str(e)}
+
+    record_submission(language, code, syntax_error=syntax_err, logical_error=logical_err, tle=tle_err)
+    result["weakness_note"] = get_weakness_note(language)
+    return result

llm.py

@@ -0,0 +1,125 @@
+"""
+CodeMentor Automata - Groq LLM wrapper.
+Handles API connection and bulletproof JSON parsing.
+"""
+import json
+from groq import Groq
+from config import GROQ_API_KEY1, GROQ_MODEL
+import base64
+from config import GROQ_API_KEY1, GROQ_MODEL, GROQ_VISION_MODEL
+
+_client = None
+
+
+class LLMNotConfiguredError(RuntimeError):
+    pass
+
+
+def _get_client() -> Groq:
+    global _client
+    if _client is None:
+        if not GROQ_API_KEY1:
+            raise LLMNotConfiguredError("GROQ_API_KEY is not set.")
+        _client = Groq(api_key=GROQ_API_KEY1)
+    return _client
+
+def call_groq_vision_ocr(image_path: str) -> str:
+    """
+    Image ko Groq ke vision model ko bhejta hai aur usme jo bhi code dikh raha
+    hai, usse exactly waisa hi transcribe karwata hai (OCR). Caller (app.py)
+    ki zimmedari hai ki user ko yeh review karne de before trusting it —
+    vision OCR characters galat padh sakta hai.
+    """
+    client = _get_client()
+    with open(image_path, "rb") as f:
+        b64_image = base64.b64encode(f.read()).decode("utf-8")
+
+    response = client.chat.completions.create(
+        model=GROQ_VISION_MODEL,
+        temperature=0.0,
+        messages=[
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "text",
+                        "text": (
+                            "Transcribe ONLY the source code visible in this image, exactly as written. "
+                            "Preserve indentation, line breaks, and symbols precisely. "
+                            "Do not explain, describe, or add commentary — output the raw code only, "
+                            "no markdown code fences."
+                        ),
+                    },
+                    {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{b64_image}"}},
+                ],
+            }
+        ],
+    )
+    return response.choices[0].message.content.strip()
+
+def call_groq_text(system_prompt: str, user_content: str, temperature: float = 0.3) -> str:
+    """Plain text completion, single turn."""
+    client = _get_client()
+    response = client.chat.completions.create(
+        model=GROQ_MODEL,
+        temperature=temperature,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content},
+        ],
+    )
+    return response.choices[0].message.content
+
+
+def call_groq_chat(system_prompt: str, history: list, user_content: str, temperature: float = 0.4) -> str:
+    """
+    Multi-turn completion for follow-up conversations.
+    `history` is a list of either {"role": ..., "content": ...} dicts (possibly
+    with extra keys like Gradio's 'metadata') or (role, content) tuples.
+    """
+    client = _get_client()
+    messages = [{"role": "system", "content": system_prompt}]
+    for turn in history:
+        if isinstance(turn, dict):
+            role = turn.get("role")
+            content = turn.get("content")
+        else:
+            role, content = turn
+        if role and content:
+            messages.append({"role": role, "content": content})  # sirf role+content, kuch aur nahi
+    messages.append({"role": "user", "content": user_content})
+
+    response = client.chat.completions.create(
+        model=GROQ_MODEL,
+        temperature=temperature,
+        messages=messages,
+    )
+    return response.choices[0].message.content
+
+
+def call_groq_json(system_prompt: str, user_content: str, temperature: float = 0.2) -> dict:
+    """JSON-mode completion with fallback parsing."""
+    client = _get_client()
+    response = client.chat.completions.create(
+        model=GROQ_MODEL,
+        temperature=temperature,
+        response_format={"type": "json_object"},
+        messages=[
+            {
+                "role": "system",
+                "content": system_prompt + "\n\nRespond ONLY with valid JSON. No preamble, no markdown fences.",
+            },
+            {"role": "user", "content": user_content},
+        ],
+    )
+    raw = response.choices[0].message.content
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        cleaned = raw.strip().strip("`")
+        if cleaned.lower().startswith("json"):
+            cleaned = cleaned[4:].strip()
+        try:
+            return json.loads(cleaned)
+        except json.JSONDecodeError:
+            return {}  # Safe fallback to prevent raw tracebacks in UI

prompts.py

@@ -0,0 +1,120 @@
+"""
+CodeMentor Automata - Prompt Library
+"""
+
+JSON_OUTPUT_INSTRUCTIONS = """
+Respond ONLY with a JSON object in exactly this shape:
+{
+  "breakdown": [
+    {"line_or_block": "...", "explanation": "..."}
+  ],
+  "analogy": "...",
+  "bugs": [
+    {"description": "...", "concrete_fix": "..."}
+  ]
+}
+"""
+
+BEGINNER_SYSTEM_PROMPT = """You are CodeMentor, a patient teacher explaining code to a beginner.
+Explain what EVERY line does in plain language. Use ONE central everyday analogy (cooking, library, etc.).
+Do NOT mention Big-O notation or complex idioms. Keep sentences short."""
+
+INTERMEDIATE_SYSTEM_PROMPT = """You are CodeMentor, explaining code to a developer comfortable with basics.
+Group code into logical blocks. Name CS concepts (recursion, hashing) where they apply.
+Use an analogy that maps to a technical parallel (e.g. comparing cache to a cheat-sheet). Mention Big-O briefly."""
+
+EXPERT_SYSTEM_PROMPT = """You are CodeMentor, giving a senior-engineer code review.
+Focus on architectural decisions, time/space complexity precisely, and subtle correctness issues (race conditions, memory leaks).
+Skip basic mechanics entirely."""
+
+LEVEL_PROMPTS = {
+    "Beginner": BEGINNER_SYSTEM_PROMPT,
+    "Intermediate": INTERMEDIATE_SYSTEM_PROMPT,
+    "Expert": EXPERT_SYSTEM_PROMPT,
+}
+
+PLAN_PROMPT = """You are CodeMentor's planning module. Given a code snippet, produce a short plan.
+Respond ONLY with JSON:
+{
+  "steps": ["Run sandbox for errors", "Cleanup pass", "Optimization pass", "Doc search"],
+  "estimated_focus": "one short sentence naming the most useful thing this analysis will surface"
+}"""
+
+CLEANUP_PROMPT = """You are CodeMentor's cleanup module. 
+NEVER change the logic. Only rename variables, fix indentation, and restructure for readability.
+Respond ONLY with JSON:
+{
+  "needs_cleanup": true,
+  "cleaned_code": "...",
+  "changes_made": ["bullet points"]
+}"""
+
+OPTIMIZATION_PROMPT = """You are CodeMentor's optimization module.
+You must ALWAYS report the time and space complexity of the given code, and name the
+data structures and algorithmic pattern it uses — do this every single time, even if
+the code is already optimal.
+
+Then decide if a better approach exists:
+- If yes, provide the improved code and explain why it's better.
+- If no, still explain WHY it's already optimal (e.g. "O(n) is optimal here because
+  every element must be read at least once") instead of a bare statement.
+
+Respond ONLY with JSON in exactly this shape:
+{
+  "current_complexity": {"time": "O(...)", "space": "O(...)"},
+  "data_structures_used": ["array", "hash map"],
+  "algorithm_pattern": "short label, e.g. brute force / two-pointer / dynamic programming / greedy",
+  "has_better_approach": true,
+  "suggested_code": "",
+  "suggested_complexity": {"time": "O(...)", "space": "O(...)"},
+  "explanation": "reasoning for improvement OR reasoning for why current is already optimal"
+}"""
+
+LOGICAL_ERROR_PROMPT = """You are a meticulous code reviewer looking ONLY for LOGICAL errors (off-by-one, wrong bounds, bad edge cases).
+Respond ONLY with JSON:
+{
+  "logical_errors_found": true,
+  "issues": [{"description": "...", "suggested_fix": "..."}]
+}"""
+
+STATIC_ANALYSIS_PROMPT = """You are a meticulous static code analyzer for a language where sandboxed execution is not available (e.g. C++, Java, JavaScript).
+Read the code carefully as a compiler/interpreter would, WITHOUT running it, and look for:
+1. Syntax errors — anything that would fail to compile or parse.
+2. Obvious runtime errors — null/undefined dereference, out-of-bounds access, division by zero, unhandled exceptions.
+3. Time-limit risk — nested loops with high complexity, obviously unbounded loops, or unbounded recursion.
+
+Be conservative: only flag something if you are reasonably confident, since this is an unverified static estimate, not an actual execution.
+
+Respond ONLY with JSON in exactly this shape:
+{
+  "syntax_error_found": false,
+  "syntax_error_message": "",
+  "runtime_error_found": false,
+  "runtime_error_message": "",
+  "tle_risk_found": false,
+  "tle_risk_message": ""
+}"""
+
+TOPIC_EXTRACTION_PROMPT = """You are identifying the SINGLE core topic that this code snippet is built around, so that
+a learner could search for videos/articles about that exact topic — not the programming language, not the imported
+libraries, but the actual algorithm, data structure, or concept the code implements.
+
+Examples of good topics: "Dijkstra's Shortest Path Algorithm", "Binary Search", "Merge Sort", "AVL Tree Rotation",
+"Dynamic Programming - Longest Common Subsequence", "Two Pointer Technique", "Depth-First Search on a Graph",
+"Producer-Consumer Pattern with Threads".
+
+Do NOT answer with just the language name (e.g. "Python") or a generic phrase like "coding" or "programming" unless
+the code is truly too trivial/generic to have a specific named concept (e.g. a simple print statement or a basic
+for-loop with no notable pattern) — in that case fall back to a short, honest generic description.
+
+Respond ONLY with JSON in exactly this shape:
+{
+  "topic": "short, specific, searchable name of the core concept",
+  "confidence": "high"
+}"""
+
+FOLLOWUP_SYSTEM_PROMPT_TEMPLATE = """You are CodeMentor, continuing a conversation. Match explanation level: {level}.
+Original snippet ({language}):
+{code}"""
+
+RESOURCE_QUERY_HINT = "site:geeksforgeeks.org OR site:realpython.com OR docs"

requirements.txt

@@ -0,0 +1,15 @@
+groq
+langchain
+langchain-community
+langchain-groq
+langchain-huggingface
+duckduckgo-search
+gradio
+chromadb
+sentence-transformers
+langgraph
+matplotlib
+pandas
+ddgs
+plotly
+python-dotenv

sandbox.py

@@ -0,0 +1,104 @@
+"""
+CodeMentor Automata - Sandbox Executor
+"""
+import os, subprocess, sys, tempfile, time
+from dataclasses import dataclass
+from typing import Optional
+from config import SANDBOX_TIMEOUT_SECONDS, TLE_THRESHOLD_SECONDS
+
+
+@dataclass
+class ExecutionResult:
+    ok: bool
+    stdout: str = ""
+    stderr: str = ""
+    runtime_seconds: float = 0.0
+    error_type: Optional[str] = None
+    error_message: str = ""
+
+
+def check_syntax(code: str) -> ExecutionResult:
+    try:
+        compile(code, "<submitted_code>", "exec")
+        return ExecutionResult(ok=True)
+    except SyntaxError as e:
+        return ExecutionResult(ok=False, error_type="syntax", error_message=f"Line {e.lineno}: {e.msg}")
+
+
+def run_python_sandboxed(code: str, stdin_input: str = "") -> ExecutionResult:
+    syntax_check = check_syntax(code)
+    if not syntax_check.ok:
+        return syntax_check
+
+    tmp_path = None
+    try:
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(code)
+            tmp_path = f.name
+
+        start = time.monotonic()
+        try:
+            proc = subprocess.run(
+                [sys.executable, tmp_path],
+                input=stdin_input,
+                capture_output=True,
+                text=True,
+                timeout=SANDBOX_TIMEOUT_SECONDS,
+            )
+        except subprocess.TimeoutExpired:
+            elapsed = time.monotonic() - start
+            return ExecutionResult(ok=False, error_type="tle", error_message="Sandbox timeout exceeded.", runtime_seconds=elapsed)
+
+        elapsed = time.monotonic() - start
+        if proc.returncode != 0:
+            last_line = proc.stderr.strip().splitlines()[-1] if proc.stderr.strip() else "Unknown runtime error"
+            return ExecutionResult(ok=False, stdout=proc.stdout, stderr=proc.stderr, runtime_seconds=elapsed, error_type="runtime", error_message=last_line)
+
+        is_tle = elapsed > TLE_THRESHOLD_SECONDS
+        return ExecutionResult(
+            ok=not is_tle,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+            runtime_seconds=elapsed,
+            error_type="tle" if is_tle else None,
+            error_message=(f"Ran in {elapsed:.2f}s, over {TLE_THRESHOLD_SECONDS}s threshold." if is_tle else ""),
+        )
+    finally:
+        if tmp_path:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+
+
+def benchmark_two_versions(original_code: str, optimized_code: str) -> dict:
+    original = run_python_sandboxed(original_code)
+    optimized = run_python_sandboxed(optimized_code)
+    speedup = None
+    if optimized.ok and original.ok and optimized.runtime_seconds > 0:
+        speedup = round(original.runtime_seconds / optimized.runtime_seconds, 2)
+    return {
+        "original_runtime": round(original.runtime_seconds, 4),
+        "optimized_runtime": round(optimized.runtime_seconds, 4),
+        "original_ok": original.ok,
+        "optimized_ok": optimized.ok,
+        "speedup": speedup,
+    }
+
+
+def verify_fix_equivalence(original_code: str, fixed_code: str, stdin_input: str = "") -> dict:
+    """
+    Runs the original and a fixed/cleaned version with the same input and
+    compares stdout, to confirm a cleanup/fix pass didn't change behaviour
+    (Python only — this is Feature 8's 'hard rule' and Feature 13's reuse).
+    """
+    original = run_python_sandboxed(original_code, stdin_input)
+    fixed = run_python_sandboxed(fixed_code, stdin_input)
+    outputs_match = fixed.ok and (original.stdout == fixed.stdout)
+    return {
+        "original_ok": original.ok,
+        "fixed_ok": fixed.ok,
+        "outputs_match": outputs_match,
+        "original_stdout": original.stdout,
+        "fixed_stdout": fixed.stdout,
+    }

store.py

@@ -0,0 +1,137 @@
+"""
+CodeMentor Automata - Vector Store & Semantic Memory
+Uses ChromaDB for persistent semantic memory. Implements Skill breakdown (pie chart).
+"""
+import os, uuid
+from datetime import date
+from typing import List
+import plotly.graph_objects as go
+
+import matplotlib
+matplotlib.use("Agg")  # must happen before pyplot is imported anywhere in the process
+
+import chromadb
+from chromadb.config import Settings
+from langchain_huggingface import HuggingFaceEmbeddings
+
+from config import STORE_PATH
+
+_db_dir = os.path.dirname(STORE_PATH) or "data"
+os.makedirs(_db_dir, exist_ok=True)
+
+_chroma_client = chromadb.PersistentClient(path=_db_dir, settings=Settings(anonymized_telemetry=False))
+_embedding_function = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
+_memory_collection = _chroma_client.get_or_create_collection(name="user_error_memory", metadata={"hnsw:space": "cosine"})
+
+
+def _get_embeddings(texts: List[str]) -> List[List[float]]:
+    return _embedding_function.embed_documents(texts)
+
+
+def record_submission(language: str, code: str, syntax_error: bool, logical_error: bool, tle: bool) -> dict:
+    doc_id = str(uuid.uuid4())
+    metadata = {
+        "language": language,
+        "syntax_error": int(syntax_error),
+        "logical_error": int(logical_error),
+        "tle": int(tle),
+        "date": date.today().isoformat(),
+    }
+    _memory_collection.add(ids=[doc_id], documents=[code], embeddings=_get_embeddings([code]), metadatas=[metadata])
+    return metadata
+
+
+def get_weakness_note(language: str) -> str:
+    results = _memory_collection.get(where={"language": language}, include=["metadatas"])
+    metadatas = results.get("metadatas", [])
+    if not metadatas or len(metadatas) < 2:
+        return f"Not enough history yet for {language} to determine a weakness pattern."
+
+    counts = {
+        "Syntax": sum(m.get("syntax_error", 0) for m in metadatas),
+        "Logical": sum(m.get("logical_error", 0) for m in metadatas),
+        "TLE": sum(m.get("tle", 0) for m in metadatas),
+    }
+    total_errors = sum(counts.values())
+    if total_errors == 0:
+        return f"Clean track record across {len(metadatas)} submissions in {language}!"
+
+    weakest = max(counts, key=counts.get)
+    pct = round(100 * counts[weakest] / total_errors)
+    return f"Across {len(metadatas)} {language} submissions, {pct}% of your errors are {weakest} errors. Focus on this."
+
+
+def _fetch_all_metadatas():
+    """Single ChromaDB read — reused by table/chart/summary to avoid 3x round-trips."""
+    results = _memory_collection.get(include=["metadatas"])
+    return results.get("metadatas", []) or []
+
+
+def _build_revision_table(metadatas: list) -> list:
+    stats = {}
+    for m in metadatas:
+        lang = m.get("language")
+        if not lang:
+            continue
+        if lang not in stats:
+            stats[lang] = {"submissions": 0, "syntax_errors": 0, "logical_errors": 0, "tle_count": 0, "last_seen": m.get("date", "")}
+        stats[lang]["submissions"] += 1
+        stats[lang]["syntax_errors"] += m.get("syntax_error", 0)
+        stats[lang]["logical_errors"] += m.get("logical_error", 0)
+        stats[lang]["tle_count"] += m.get("tle", 0)
+        stats[lang]["last_seen"] = max(stats[lang]["last_seen"], m.get("date", ""))
+    return [
+        [lang, rec["submissions"], rec["syntax_errors"], rec["logical_errors"], rec["tle_count"], rec["last_seen"]]
+        for lang, rec in sorted(stats.items())
+    ]
+
+
+def _build_skill_pie_chart(metadatas: list):
+    total = max(len(metadatas), 1)
+    mastery = {
+        "Syntax Mastery": max(total - sum(m.get("syntax_error", 0) for m in metadatas), 0),
+        "Logic Mastery": max(total - sum(m.get("logical_error", 0) for m in metadatas), 0),
+        "Performance Mastery": max(total - sum(m.get("tle", 0) for m in metadatas), 0),
+    }
+    labels = list(mastery.keys())
+    values = list(mastery.values())
+    pull = [0.08 if v == max(values) else 0 for v in values]
+
+    fig = go.Figure(data=[go.Pie(
+        labels=labels, values=values, pull=pull, hole=0.35,
+        marker=dict(colors=["#6C63FF", "#00C2A8", "#FF6B6B"], line=dict(color="#1e1e1e", width=2)),
+        textinfo="label+percent", hoverinfo="label+value",
+    )])
+    fig.update_layout(
+        title="Your Skill Ability Breakdown", showlegend=True,
+        margin=dict(t=60, b=20, l=20, r=20), paper_bgcolor="rgba(0,0,0,0)",
+    )
+    return fig
+
+
+def _build_skill_summary(metadatas: list) -> str:
+    if not metadatas:
+        return "No submissions yet — analyze some code to build your skill profile."
+    total = len(metadatas)
+    counts = {
+        "Syntax": sum(m.get("syntax_error", 0) for m in metadatas),
+        "Logical": sum(m.get("logical_error", 0) for m in metadatas),
+        "Performance (TLE)": sum(m.get("tle", 0) for m in metadatas),
+    }
+    languages = sorted({m.get("language") for m in metadatas if m.get("language")})
+    if sum(counts.values()) == 0:
+        return f"🎉 **Summary:** Clean record across {total} submissions in {', '.join(languages)} — no recurring weak area yet."
+    weakest = max(counts, key=counts.get)
+    return (
+        f"📊 **Summary:** {total} submissions across **{', '.join(languages)}**. "
+        f"Your most frequent issue type is **{weakest}** ({counts[weakest]} occurrences). "
+        f"Focus your next few practice sessions there for the fastest improvement."
+    )
+
+
+def get_progress_snapshot():
+    """ONE DB read, returns (table, chart, summary) together. This is the only
+    function app.py should call — used both for the first static render and
+    for the manual Refresh button, so there's never a redundant scan."""
+    metadatas = _fetch_all_metadatas()
+    return _build_revision_table(metadatas), _build_skill_pie_chart(metadatas), _build_skill_summary(metadatas)