socratic-debug 0.0.1__py3-none-any.whl

socratic.py

@@ -0,0 +1,8 @@
+"""
+Socratic Debug — Autonomous pedagogical debugging mentor.
+"""
+
+from src.hook import install
+from src.agent.runner import run_socratic_agent
+
+__all__ = ["install", "run_socratic_agent"]

socratic_debug-0.0.1.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: socratic-debug
+Version: 0.0.1
+Summary: Autonomous pedagogical debugging mentor powered by LangGraph, Rich, and LangSmith
+Author: Mohamed Elawakey
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: PyQt6>=6.6.0
+Requires-Dist: langgraph>=1.2.0
+Requires-Dist: langchain>=1.4.0
+Requires-Dist: langchain-ollama>=1.1.0
+Requires-Dist: langchain-openrouter>=0.2.0
+Dynamic: license-file
+
+# 🧠 Socratic Debug (`socratic`)
+
+> **Stop copying stack traces. Start mastering your bugs.**  
+> An autonomous pedagogical debugger and mentor powered by LangGraph, PyQt6, and LangSmith.
+
+[![CI](https://github.com/mohamedelawakey/socratic/actions/workflows/ci.yml/badge.svg)](https://github.com/mohamedelawakey/socratic/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/socratic-debug.svg?color=blue)](https://pypi.org/project/socratic-debug/)
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+## 💡 Why Socratic?
+
+When a runtime crash happens, most developers find themselves trapped in one of two extremes:
+1. **The Intimidating Traceback:** Staring at a terrifying wall of 50-line red terminal text, unsure which line actually caused the root flaw.
+2. **The "Copier" Reflex:** Blindly copying the error into an LLM chat, pasting the patch without understanding *why* it failed, only to trigger the exact same design mistake minutes later.
+
+**Socratic Debug changes the game.**  
+Instead of dumping stack traces or spoon-feeding copy-paste patches, `socratic` intercepts uncaught runtime crashes and launches a **dedicated desktop mentorship window**. It analyzes the bug silently and guides you through a calibrated, interactive dialogue to help you **discover, understand, and fix the root cause yourself.**
+
+---
+
+## ✨ Features
+
+- 🖥️ **Standalone Desktop Window:** Launches an isolated, dark-themed GUI terminal window right at the center of your screen. No terminal pollution.
+- 🌍 **Pure Native BiDi & Arabic Support:** Flawlessly displays English and Arabic with full Right-to-Left (RTL) text shaping and formatting.
+- 🎯 **Calibrated Socratic Mentorship:** 3-tier adaptive hints (Observation ➔ Mechanism ➔ Idiomatic Prevention).
+- 🧠 **Smart Evaluator:** Distinguishes between partial observations (e.g., stating a variable's value) and true comprehension before unlocking the defensive code solution.
+- 🔌 **Universal LLM Support:** Plug into local models via **Ollama** (Gemma, Llama, Qwen) or cloud providers via **OpenRouter** / **Google Gemini**.
+- 📊 **Built-in Observability:** Native tracing with **LangSmith** to monitor latency, tokens, and node execution graphs.
+- 🌐 **Cross-Platform:** Runs seamlessly on **Linux**, **macOS**, and **Windows**.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+The cleanest, recommended way to install `socratic` globally across your system without virtual environment conflicts:
+
+```bash
+# Recommended (isolated global CLI)
+pipx install socratic-debug
+
+# Or via standard pip
+pip install socratic-debug
+```
+
+Alternatively, use the one-line install script:
+```bash
+# Linux & macOS
+curl -sSL https://raw.githubusercontent.com/mohamedelawakey/socratic/main/install.sh | bash
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/mohamedelawakey/socratic/main/install.ps1 | iex
+```
+
+---
+
+## 🛠️ Usage
+
+You can use `socratic` in two distinct ways:
+
+### Method 1: Zero-Code-Change CLI Runner (Recommended)
+You don't need to add any code or imports to your script! Simply prefix your execution:
+
+```bash
+socratic run my_script.py
+```
+- If your script runs successfully, it outputs normally.
+- If an unhandled exception occurs, the **Socratic Mentor Window** springs to life immediately!
+
+### Method 2: In-Process Runtime Hook
+If you are building an application or library and want Socratic guidance baked directly into development runs:
+
+```python
+import socratic
+socratic.install()
+
+# Your regular application code
+number_1 = 10
+number_2 = 0
+print(number_1 / number_2)  # <-- ZeroDivisionError triggers Socratic window!
+```
+
+---
+
+## ⚙️ Configuration (`.socratic.yaml`)
+
+When you run `socratic` for the first time, it automatically creates a `.socratic.yaml` config file in your project or home directory:
+
+```yaml
+# LLM Provider: "ollama" or "openrouter"
+provider: "ollama"
+provider_name: "gemma4:31b-cloud"
+provider_link: "http://localhost:11434"
+
+# API Key (for cloud providers like OpenRouter)
+api_key: "your_api_key_here"
+
+# Mentor Personality & Language ("Arabic" or "English")
+socratic_language: "Arabic"
+socratic_style: "friendly"
+
+# Observability with LangSmith (Optional)
+LANGSMITH_TRACING: "true"
+LANGSMITH_API_KEY: "lsv2_pt_..."
+LANGSMITH_PROJECT: "socratic-debug"
+```
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Please review our [CONTRIBUTING.md](CONTRIBUTING.md) guidelines:
+- For large architectural changes or new features, **please open a GitHub Discussion first**.
+- For minor bug fixes, direct Pull Requests are warmly welcome.
+
+Please note that this project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## 📄 License
+
+Distributed under the **MIT License**. See [LICENSE](LICENSE) for full details.

socratic_debug-0.0.1.dist-info/RECORD

@@ -0,0 +1,40 @@
+socratic.py,sha256=vjvn2kb04RYGlU0rpDraG2HvbKbsq1AazT2PHW2mpeM,191
+socratic_debug-0.0.1.dist-info/licenses/LICENSE,sha256=ihM1UFgq0KNRA1mK7zKHG4Ek4gRjZ0lz-Jqf5R6k5HY,1073
+src/__init__.py,sha256=cCoVrcqlB8PoIqGQPWXjHrYJjZ6kyI_JK-pgTtOPKzQ,19
+src/cli.py,sha256=jcgjcf3IueLgaYmvXxHezOWKNp8lrMZ_fSxcbH451fk,3052
+src/config_creator.py,sha256=Lro60P0YQnw5hNgdFyDhNm-pLltHbGjMufweV4hXyoY,798
+src/config_template.py,sha256=gRQ9N17nnQpwXozpzaSEazyGscmTZf8fccRj6wO7BSg,548
+src/extractor.py,sha256=5i3WWr2ZysDuY-UioDAiiOrYcy7t3mxxxThkKnjrNb0,1148
+src/hook.py,sha256=HZFAXeHma52Ko5qZwrsNk4ZDCTj_z9qq2GiQ248pTgg,2329
+src/agent/runner.py,sha256=gydqyps4cXvWZVpCF_ApRPfhOFHimo_mwjcJp-I34ko,750
+src/agent/graph/graph.py,sha256=ZV7vYMJygbvh2pAKdVa49GQqEN7ef-4LpTUjQSxnuz0,1597
+src/agent/llm/factory.py,sha256=FzZhh9C_Vy9aZRBZrY82KcIgtD3myroTS1jN27dLMAc,422
+src/agent/llm/providers/__init__.py,sha256=JUftuQkiHppcu7epf4YumISPY8wK-XHLBDuBuSGgrWM,168
+src/agent/llm/providers/ollama.py,sha256=VQDwx3C3WWcdax_ZQcnFoZz9S86sfyzvEUTLHbIQv_4,306
+src/agent/llm/providers/openrouter.py,sha256=7ACDWjjNt75PovWTUUFFqvXqKCGEQp1VRCyHGynOKUQ,364
+src/agent/nodes/diagnose_node.py,sha256=Gwk3P2SPpOBFvFn17XiSxtjrT75fvuMQNzE0DLyo_AY,753
+src/agent/nodes/evaluate_node.py,sha256=wCiUsdu8nvi1vhWgJf-MhZz7o16rBhIUF57AV_4q6CQ,1317
+src/agent/nodes/human_input_node.py,sha256=GANj4vUVBdeESGB4ufK3X9iB1QQn75gG3lpGEvEwp5E,695
+src/agent/nodes/questioner_node.py,sha256=TdtDJ_8uBzsnK7pGtouie5-sHVx5z0rx0OqRrRCZnYY,1628
+src/agent/nodes/solution_node.py,sha256=h8rVtOG7vQNDcHXd6FqP-864-HQVomnQXP9mS2pFlQw,1171
+src/agent/prompts/diagnose_prompt.py,sha256=gDHtGO62MUVbLxl-maWb0iyIhBMZr74dBmWCIoUbvy0,1334
+src/agent/prompts/evaluation_prompt.py,sha256=51sBNxB2Oog7scg_TIn94aPIoWHiVLaiNY7m4zfVezY,1334
+src/agent/prompts/mentor_prompt.py,sha256=mgQ6iD0XlR_YOIciySAogjSyMI1-_T6E14MrrjFCHRI,1078
+src/agent/prompts/questioner_prompt.py,sha256=Xj7RZAyl2EYv9LZL530tyFZX0LShkl_kozPG8HgJ0uk,2160
+src/agent/prompts/solution_prompt.py,sha256=MTHldmB96ZEgzOFOSh1_grGl6WmnmP9MhoVcnl5Bqnk,1378
+src/agent/state/state.py,sha256=pPLGBzrityoDB8BsCMCtkDGWyl35VE5Vu2WawpPnvBM,458
+src/utils/read_yaml.py,sha256=nXhgCLt3P6PlwvLeyy471lWmDOaKIP_c8X3-LUx_WCQ,1179
+ui/__init__.py,sha256=kgCb95xam0txNsto6-77OamiWeibjDntEYNMQizeQkU,389
+ui/app.py,sha256=alt-5nFQeWsFP52A9z9EXIJMsTzAdIwN3zOJqOPArJc,7613
+ui/bidi.py,sha256=6c94A9TvcMFapDZBIENK-LrX0PB9zWWYZSQ-A-t4TMw,814
+ui/console.py,sha256=Vml-Mlg6cyignegw4AFWfaRZXDyxGlLM2o-GyhLmP8g,588
+ui/styles.py,sha256=3Au_ATVjGfnCB1UFVkLzgbjU_VCfCBF688vYB9vW3Dw,1588
+ui/templates.py,sha256=89cPdnQK4YsdZGiiLiEEgTzmt8Jh1mLtenyowh78L1I,4432
+ui/translations.py,sha256=DI-SaA_u5Xy41aFe3_cNlOd5xpdLSyNLzVhLKm0lIyc,1483
+ui/views.py,sha256=KWHyj44kiWosZFbdSMfKJoPcXt4R04RouhfigM-Xbs0,1992
+ui/window.py,sha256=cR22-64IGo7VlJpNqz8lGqEvYJYX418P89-jmHSIIJ4,4341
+socratic_debug-0.0.1.dist-info/METADATA,sha256=6XSpJv_Ct74s6DW32PVY339vHWmDtuHa747aUf6RGLA,5454
+socratic_debug-0.0.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+socratic_debug-0.0.1.dist-info/entry_points.txt,sha256=33bxMIy6yZotp4XPq64BMjsMceJdLln5wzJ8cFzRjJ0,42
+socratic_debug-0.0.1.dist-info/top_level.txt,sha256=nuecBGJAx4dR_afXHk8yT2mz3JAhpkYh-JcmwNzBnvI,16
+socratic_debug-0.0.1.dist-info/RECORD,,

socratic_debug-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

socratic_debug-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+socratic = src.cli:main

socratic_debug-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Alawakey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

socratic_debug-0.0.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+socratic
+src
+ui

src/__init__.py

@@ -0,0 +1 @@
+# socratic package

src/agent/graph/graph.py

@@ -0,0 +1,47 @@
+from langgraph.graph import StateGraph, END, START
+from src.agent.state.state import SocraticAgentState
+from src.agent.nodes.diagnose_node import DiagnoseNode
+from src.agent.nodes.questioner_node import QuestionerNode
+from src.agent.nodes.human_input_node import HumanInputNode
+from src.agent.nodes.evaluate_node import EvaluationNode
+from src.agent.nodes.solution_node import SolutionNode
+
+def decision_router(state: SocraticAgentState) -> str:
+    if state.get("is_solved"):
+        return "solution"
+    if state.get("hint_level", 1) > 3:
+        return "solution"
+    return "questioner"
+
+
+class SocraticGraph:
+    @staticmethod
+    def build_graph():
+    # We will assemble nodes and edges here
+        graph = StateGraph(SocraticAgentState)
+
+        # add nodes
+        graph.add_node("diagnose", DiagnoseNode.diagnose_node)
+        graph.add_node("questioner", QuestionerNode.questioner_node)
+        graph.add_node("human_input", HumanInputNode.human_input_node)
+        graph.add_node("evaluate", EvaluationNode.evaluation_node)
+        graph.add_node("solution", SolutionNode.solution_node)
+
+        # edges
+        graph.add_edge(START, "diagnose")
+        graph.add_edge("diagnose", "questioner")
+        graph.add_edge("questioner", "human_input")
+        graph.add_edge("human_input", "evaluate")
+
+        graph.add_conditional_edges(
+            "evaluate",
+            decision_router,
+            {
+                "solution": "solution",
+                "questioner": "questioner",
+            }
+        )
+        graph.add_edge("solution", END)
+
+        return graph.compile()
+

src/agent/llm/factory.py

@@ -0,0 +1,15 @@
+from src.agent.llm.providers import *
+from src.utils.read_yaml import ReadYaml
+
+
+class LLMFactory:
+    @staticmethod
+    def get_llm():
+        config = ReadYaml.read_yaml()
+
+        if config["provider"] == "openrouter":
+            return OpenRouterLLM.openrouter_llm()
+        elif config["provider"] == "ollama":
+            return OllamaLLM.ollama_llm()
+        else:
+            raise ValueError("Invalid provider")

src/agent/llm/providers/__init__.py

@@ -0,0 +1,8 @@
+from src.agent.llm.providers.openrouter import OpenRouterLLM
+from src.agent.llm.providers.ollama import OllamaLLM
+
+
+__all__ = [
+    "OpenRouterLLM",
+    "OllamaLLM",
+]

src/agent/llm/providers/ollama.py

@@ -0,0 +1,13 @@
+from langchain_ollama import ChatOllama
+from src.utils.read_yaml import ReadYaml
+
+
+class OllamaLLM:
+    @staticmethod
+    def ollama_llm():
+        config = ReadYaml.read_yaml()
+
+        return ChatOllama (
+            model=config["provider_name"],
+            base_url=config["provider_link"],
+        )

src/agent/llm/providers/openrouter.py

@@ -0,0 +1,14 @@
+from langchain_openrouter import ChatOpenRouter
+from src.utils.read_yaml import ReadYaml
+
+
+class OpenRouterLLM:
+    @staticmethod
+    def openrouter_llm():
+        config = ReadYaml.read_yaml()
+
+        return ChatOpenRouter(
+            model=config["provider_name"],
+            base_url=config["provider_link"],
+            api_key=config["api_key"],
+        )

src/agent/nodes/diagnose_node.py

@@ -0,0 +1,21 @@
+from src.agent.prompts.diagnose_prompt import DiagnosePrompt
+from src.agent.state.state import SocraticAgentState
+from src.agent.llm.factory import LLMFactory
+
+
+class DiagnoseNode:
+    @staticmethod
+    def diagnose_node(state: SocraticAgentState) -> dict:
+        prompt = DiagnosePrompt.diagnose_prompt(
+            error_type=state["error_type"],
+            error_name=state["error_name"],
+            file_path=state["file_path"],
+            line_number=state["line_number"],
+            line_content=state["line_content"],
+            code_snippet=state["code_snippet"],
+            function_name=state.get("function_name") or "",
+        )
+
+        response = LLMFactory.get_llm().invoke(prompt)
+
+        return {"root_cause": response.content}

src/agent/nodes/evaluate_node.py

@@ -0,0 +1,38 @@
+from src.agent.prompts.evaluation_prompt import EvaluationPrompt
+from src.agent.state.state import SocraticAgentState
+from src.agent.llm.factory import LLMFactory
+
+from ui.views import SocraticUI
+
+class EvaluationNode:
+    @staticmethod
+    def evaluation_node(state: SocraticAgentState):
+        prompt = EvaluationPrompt.evaluation_prompt(
+                error_type=state["error_type"],
+                code_snippet=state["code_snippet"],
+                root_cause=state["root_cause"],
+                user_input=state.get("user_input") or state["dialogue_history"][-1]["content"]
+        )
+        
+        response = LLMFactory.get_llm().invoke(prompt)
+        verdict = response.content.strip().upper()
+
+        if "SOLVED" in verdict and "UNSOLVED" not in verdict and "NOT SOLVED" not in verdict:
+            verdict_key = "SOLVED"
+            status = "solved"
+            is_solved = True
+        elif "SURRENDERED" in verdict:
+            verdict_key = "SURRENDERED"
+            status = "surrendered"
+            is_solved = True
+        else:
+            verdict_key = "STRUGGLING"
+            status = "struggling"
+            is_solved = False
+
+        SocraticUI.display_evaluator_verdict(verdict_key)
+
+        return {
+            "eval_status": status,
+            "is_solved": is_solved,
+        }

src/agent/nodes/human_input_node.py

@@ -0,0 +1,18 @@
+from src.agent.state.state import SocraticAgentState
+from ui.views import SocraticUI
+from ui.console import console
+
+
+class HumanInputNode:
+    @staticmethod
+    def human_input_node(state: SocraticAgentState) -> dict:
+        user_input = SocraticUI.prompt_user_input()
+
+        if user_input.lower().strip() in ["exit", "quit", "q"]:
+            console.print("\n[bold yellow]👋 Exiting Socratic debugging session. Keep coding![/bold yellow]\n")
+            return {"is_solved": True}
+
+        history = list(state.get("dialogue_history", []))
+        history.append({"role": "student", "content": user_input})
+        
+        return {"user_input": user_input, "dialogue_history": history}

src/agent/nodes/questioner_node.py

@@ -0,0 +1,47 @@
+from src.agent.prompts.questioner_prompt import QuestionerPrompt
+from src.agent.state.state import SocraticAgentState
+from src.agent.llm.factory import LLMFactory
+from src.utils.read_yaml import ReadYaml
+
+from ui.views import SocraticUI
+
+config = ReadYaml.read_yaml()
+
+
+class QuestionerNode:
+    @staticmethod
+    def questioner_node(state: SocraticAgentState) -> dict:
+        current_hint = state.get("hint_level", 1)
+        raw_history = state.get("dialogue_history", [])
+
+        formatted_history = "\n".join(
+            f"- {turn.get('role', 'unknown').capitalize()}: {turn.get('content', '')}"
+            for turn in raw_history
+        )
+
+        prompt = QuestionerPrompt.questioner_prompt(
+            error_type=state["error_type"],
+            line_number=state["line_number"],
+            line_content=state["line_content"],
+            code_snippet=state["code_snippet"],
+            root_cause=state["root_cause"],
+            dialogue_history=formatted_history,
+            hint_level=current_hint,
+            language=config.get("socratic_language", "English"),
+            style=config.get("socratic_style", "friendly"),
+        )
+
+        response = LLMFactory.get_llm().invoke(prompt)
+
+        SocraticUI.display_mentor_message(
+            content=response.content,
+            hint_level=current_hint,
+        )
+
+        history = list(state.get("dialogue_history", []))
+        history.append({"role": "mentor", "content": response.content})
+        
+        return {
+            "dialogue_history": history,
+            "hint_level": current_hint + 1 if current_hint < 3 else current_hint,
+        }

src/agent/nodes/solution_node.py

@@ -0,0 +1,36 @@
+from src.agent.prompts.solution_prompt import SolutionPrompt
+from src.agent.state.state import SocraticAgentState
+from src.agent.llm.factory import LLMFactory
+from src.utils.read_yaml import ReadYaml
+
+from ui.views import SocraticUI
+
+config = ReadYaml.read_yaml()
+
+
+class SolutionNode:
+    @staticmethod
+    def solution_node(state: SocraticAgentState) -> dict:
+        current_status = state.get("eval_status", "solved")
+
+        prompt = SolutionPrompt.solution_prompt(
+            error_type=state["error_type"],
+            line_number=state["line_number"],
+            code_snippet=state["code_snippet"],
+            root_cause=state["root_cause"],
+            eval_status=current_status,
+            language=config.get("socratic_language", "English"),
+            style=config.get("socratic_style", "friendly"),
+        )
+
+        response = LLMFactory.get_llm().invoke(prompt)
+
+        SocraticUI.display_solution(response.content)
+
+        history = list(state.get("dialogue_history", []))
+        history.append({"role": "mentor", "content": response.content})
+
+        return {
+            "dialogue_history": history,
+            "is_solved": True,
+        }

src/agent/prompts/diagnose_prompt.py

@@ -0,0 +1,34 @@
+class DiagnosePrompt:
+    @staticmethod
+    def diagnose_prompt(
+        error_type: str,
+        error_name: str,
+        file_path: str,
+        line_number: int,
+        line_content: str,
+        code_snippet: str,
+        function_name: str = "",
+    ) -> str:
+        return f"""You are an Expert Code Diagnostic Engine. Your mission is to silently analyze a runtime crash and identify the exact root cause and the faulty variable/expression.
+
+Crash Information:
+- Error Type: {error_type}
+- Error Message: {error_name}
+- File: {file_path} (Function: {function_name or 'global'})
+- Faulty Line #{line_number}: `{line_content}`
+
+Surrounding Code Context:
+```python
+{code_snippet}
+```
+
+Instructions:
+1. Identify the exact root cause: Why did this specific error occur at this exact line?
+2. Identify the culprit: Which variable, index, operation, or missing key caused the crash?
+3. Define the pedagogical angle: What conceptual programming misunderstanding led to this bug, and what core question should we guide the developer to reflect upon?
+
+Output your diagnosis strictly in this format:
+- Root Cause: [Concise 1-2 sentence technical explanation of why it failed]
+- Culprit: [The specific variable, operation, or expression responsible]
+- Pedagogical Angle: [The core programming concept the developer needs to discover]
+"""

src/agent/prompts/evaluation_prompt.py

@@ -0,0 +1,33 @@
+class EvaluationPrompt:
+    @staticmethod
+    def evaluation_prompt(
+        error_type: str,
+        code_snippet: str,
+        root_cause: str,
+        user_input: str,
+    ) -> str:
+        evaluation_prompt = f"""You are an Objective Judge evaluating a developer's response during a Socratic debugging session.
+Bug Context:
+- Error: {error_type}
+- Code Snippet:
+```python
+{code_snippet}
+```
+- Known Root Cause of the bug:
+{root_cause}
+
+Latest Developer Response:
+"{user_input}"
+
+Your Task:
+Evaluate whether the developer's response shows they understand the root cause and know how to fix it, or if they are still confused/struggling, or if they gave up.
+
+Output strictly ONE word from these three options:
+- SOLVED: The developer clearly demonstrates an understanding of WHY the code failed and explains the failure mechanism or proposes a valid fix/guard to resolve it.
+- STRUGGLING: The developer made a partial observation (e.g. stating a variable value or noticing a symptom without explaining why it breaks the logic or how to fix it), made an incorrect guess, expressed confusion, or asked for a hint/clarification.
+- SURRENDERED: The developer explicitly gives up, refuses to think through it, or directly demands the complete answer/code fix without trying.
+
+Classification:
+        """
+
+        return evaluation_prompt

src/agent/prompts/mentor_prompt.py

@@ -0,0 +1,30 @@
+class MentorPrompt:
+    @staticmethod
+    def mentor_prompt(
+        error_type: str,
+        line_number: int,
+        code_snippet: str,
+        language: str = "English",
+        style: str = "friendly",
+    ):
+        mentor_prompt = f"""You are a Socratic Mentor. Your goal is to guide developers to discover and fix their own coding mistakes instead of spoon-feeding them code solutions.
+
+Configuration:
+- Language: Respond strictly in {language}.
+- Tone/Style: {style}.
+
+Crash Details:
+- Error Type: {error_type}.
+- Line Number: {line_number}.
+- Code Snippet: ```python
+{code_snippet}
+```
+
+Follow these guidelines:
+1- Do not give the solution or fix directly. Point them toward the suspicious line or variable, and ask a guiding question so they identify the mistake themselves.
+2- Do not explain a whole topic to them.
+3- Ask them a question about how they can solve it themselves.
+4- Keep the conversation short and under 3 exchanges.
+5- If they can't solve it after 2 exchanges, you can help them by giving them a hint or explanation.
+"""
+        return mentor_prompt

src/agent/prompts/questioner_prompt.py

@@ -0,0 +1,47 @@
+class QuestionerPrompt:
+    @staticmethod
+    def questioner_prompt(
+        error_type: str,
+        line_number: int,
+        line_content: str,
+        code_snippet: str,
+        root_cause: str,
+        dialogue_history: str = "",
+        hint_level: int = 1,
+        language: str = "English",
+        style: str = "friendly",
+    ) -> str:
+        questioner_prompt = f"""You are a Socratic Coding Mentor. Your mission is to guide a developer through discovering, understanding, and fixing their own bug without directly giving away the solution.
+
+Mentor Configuration:
+- Language: Respond strictly in {language}.
+- Tone/Style: {style}.
+- Current Hint Level: {hint_level} of 3.
+
+Bug Context:
+- Error Type: {error_type}
+- Crashing Line #{line_number}: `{line_content}`
+- Internal Root Cause (DO NOT reveal directly):
+{root_cause}
+
+Surrounding Code:
+```python
+{code_snippet}
+```
+
+Conversation History so far:
+{dialogue_history if dialogue_history else "(No prior dialogue yet - this is your opening question)"}
+
+Pedagogical Strategy based on Hint Level:
+- Level 1 (Gentle): Do NOT explain the bug. Simply draw their attention to the suspicious variable, operation, or line, and ask what value or type they expect it to have.
+- Level 2 (Targeted): Point out why that specific operation or value is problematic in Python, and ask what condition or check could prevent it.
+- Level 3 (Direct Guidance): Explain the general concept briefly and ask which Python construct, method, or defensive check (e.g., if-statement, .get(), try/except) is best suited to fix it.
+
+Rules:
+1. NEVER write the fixed code or give the direct answer.
+2. If there is Conversation History, ALWAYS acknowledge or validate the developer's latest response directly (e.g. confirming a correct observation, comforting confusion) before asking the next question.
+3. NEVER repeat the same question or opening greeting if you already asked it in the history. Move the conversation forward!
+4. Keep your response short, focused, and conversational (1 to 2 short paragraphs).
+5. End with exactly ONE clear, thoughtful question for the developer to answer.
+"""
+        return questioner_prompt