socratic-debug 0.0.1__py3-none-any.whl

src/agent/prompts/solution_prompt.py

@@ -0,0 +1,38 @@
+class SolutionPrompt:
+    @staticmethod
+    def solution_prompt(
+        error_type: str,
+        line_number: int,
+        code_snippet: str,
+        root_cause: str,
+        eval_status: str = "solved",
+        language: str = "English",
+        style: str = "friendly",
+    ) -> str:
+        return f"""You are a Socratic Coding Mentor wrapping up a debugging session.
+
+Session Context:
+- Language: Respond strictly in {language}.
+- Style/Tone: {style}.
+- Final Status: {eval_status.upper()} (The developer {'successfully understood and solved the bug' if eval_status == 'solved' else 'struggled or surrendered'}).
+- Error Type: {error_type}
+- Line #{line_number}
+- Known Root Cause:
+{root_cause}
+
+Original Code Context:
+```python
+{code_snippet}
+```
+
+Instructions:
+1. If status is SOLVED:
+   - Enthusiastically praise the developer for discovering and understanding the bug themselves.
+   - Summarize the core takeaway lesson in one memorable sentence.
+2. If status is SURRENDERED:
+   - Be empathetic, encouraging, and clear.
+   - Concisely explain the concept so they understand why it happened.
+3. IN BOTH CASES:
+   - Provide a clean, idiomatic Python code snippet demonstrating the "Best Practice" or defensive programming way to prevent this bug (e.g., using default values, proper guards, or cleaner logic).
+   - Keep the entire response concise and under 250 words.
+"""

src/agent/runner.py

@@ -0,0 +1,21 @@
+from src.extractor import extract_crash_context
+from src.agent.graph.graph import SocraticGraph
+
+def run_socratic_agent(exception_type, exception_value, exception_traceback):
+    context = extract_crash_context(exception_traceback)
+
+    initial_state = {
+        "file_path": context["file_path"],
+        "function_name": context["function_name"],
+        "line_number": context["line_number"],
+        "line_content": context["line_content"],
+        "code_snippet": context["code_snippet"],
+        "error_type": exception_type.__name__,
+        "error_name": str(exception_value),
+        "root_cause": "",
+        "dialogue_history": [],
+        "is_solved": False,
+    }
+    
+    app = SocraticGraph.build_graph()
+    app.invoke(initial_state)

src/agent/state/state.py

@@ -0,0 +1,21 @@
+from typing import TypedDict, List, Dict, Any, Optional
+
+
+class SocraticAgentState(TypedDict):
+    # data about the problem
+    file_path: str
+    function_name: Optional[str]
+    line_number: int
+    line_content: str
+    code_snippet: str
+    error_type: str
+    error_name: str
+
+    # root cause of the problem
+    root_cause: str
+
+    # chat with user
+    dialogue_history: List[Dict[str, str]]
+
+    # dose problem is solved or not !
+    is_solved: bool

src/cli.py

@@ -0,0 +1,98 @@
+import sys
+import os
+from pathlib import Path
+
+# Add project root to sys.path so modules and UI resolve everywhere
+project_root = str(Path(__file__).resolve().parent.parent)
+if project_root not in sys.path:
+    sys.path.insert(0, project_root)
+
+from src.hook import install
+from ui.console import console
+
+
+def print_usage():
+    console.print("""
+[bold cyan]🧠 Socratic Debug — Autonomous Pedagogical Debugger[/bold cyan]
+
+[bold yellow]Usage:[/bold yellow]
+  [green]socratic run <script.py>[/green]   Run a Python file under Socratic supervision
+  [green]socratic init[/green]              Create a default .socratic.yaml config file
+  [green]socratic --help[/green]            Show this help message
+""")
+
+
+def run_target_script(script_path: str, script_args: list):
+    resolved_path = Path(script_path).resolve()
+    if not resolved_path.exists():
+        console.print(f"[bold red]Error:[/bold red] File not found: [yellow]{resolved_path}[/yellow]")
+        sys.exit(1)
+
+    # Automatically install Socratic hook before user code executes
+    install()
+
+    # Prepare execution environment simulating direct `python <script.py>`
+    sys.argv = [str(resolved_path)] + script_args
+    sys.path.insert(0, str(resolved_path.parent))
+
+    # Read and execute target code in its own module namespace
+    with open(resolved_path, "r", encoding="utf-8") as f:
+        code_str = f.read()
+
+    namespace = {
+        "__name__": "__main__",
+        "__file__": str(resolved_path),
+        "__doc__": None,
+    }
+
+    try:
+        exec(compile(code_str, str(resolved_path), "exec"), namespace)
+    except SystemExit:
+        raise
+    except Exception:
+        # sys.excepthook will catch this cleanly and launch Socratic GUI!
+        sys.excepthook(*sys.exc_info())
+
+
+def main():
+    if len(sys.argv) < 2:
+        print_usage()
+        sys.exit(0)
+
+    command = sys.argv[1].lower()
+
+    if command in ("-h", "--help", "help"):
+        print_usage()
+        sys.exit(0)
+
+    elif command == "init":
+        from src.config_creator import create_config
+        create_config()
+        console.print("[bold green]✔[/bold green] Created [cyan].socratic.yaml[/cyan] with default settings.")
+        sys.exit(0)
+
+    elif command == "session":
+        # Internal command executed inside the dedicated popup window
+        target_file = sys.argv[2]
+        extra_args = sys.argv[3:]
+        run_target_script(target_file, extra_args, force_in_process=True)
+
+    elif command == "run":
+        if len(sys.argv) < 3:
+            console.print("[bold red]Error:[/bold red] Missing script file to run.")
+            console.print("Example: [green]socratic run app.py[/green]")
+            sys.exit(1)
+
+        target_file = sys.argv[2]
+        extra_args = sys.argv[3:]
+        run_target_script(target_file, extra_args)
+
+    else:
+        # Default fallback: if user runs `socratic script.py` directly
+        target_file = sys.argv[1]
+        extra_args = sys.argv[2:]
+        run_target_script(target_file, extra_args)
+
+
+if __name__ == "__main__":
+    main()

src/config_creator.py

@@ -0,0 +1,32 @@
+try:
+    from src.config_template import ConfigTemplate
+except ImportError:
+    from config_template import ConfigTemplate
+from pathlib import Path
+import yaml
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+# make the socratic.config file
+def create_config():
+    config_path = PROJECT_ROOT / ".socratic.yaml"
+
+    if config_path.exists():
+        return
+
+    with open(config_path, "w") as f:
+        f.write(ConfigTemplate.DEFAULT_CONFIG_TEMPLATE)
+
+# read the socratic.config file and return the values
+def read_config() -> dict:
+    config_path = PROJECT_ROOT / ".socratic.yaml"
+
+    if not config_path.exists():
+        return {}
+
+    with open(config_path, "r") as f:
+        return yaml.safe_load(f) or {}
+
+if __name__ == "__main__":
+    create_config()
+    print("Config created!")

src/config_template.py

@@ -0,0 +1,21 @@
+class ConfigTemplate:
+    DEFAULT_CONFIG_TEMPLATE = """# Socratic Configuration
+# in this file you can configure the socratic debugging tool
+
+# LLM Configurations
+provider: "ollama"
+provider_name: "gemma4:31b-cloud"
+provider_link: "http://localhost:11434"
+
+# API Key (the variable name must named `api_key`)
+api_key: "your_api_key"
+
+# Socratic Mentor configuration
+socratic_language: "English"
+socratic_style: "friendly"
+
+# Observability
+LANGSMITH_TRACING: "true"
+LANGSMITH_API_KEY: "your_langsmith_api_key"
+LANGSMITH_PROJECT: "socratic-debug"
+"""

src/extractor.py

@@ -0,0 +1,34 @@
+import traceback
+
+def extract_crash_context(exception_traceback) -> dict:
+    frames = traceback.extract_tb(exception_traceback)
+    last_frame = frames[-1]
+
+    snippet = get_code_snippet(last_frame.filename, last_frame.lineno)
+
+    return {
+        "file_path": last_frame.filename,
+        "line_number": last_frame.lineno,
+        "function_name": last_frame.name,
+        "line_content": last_frame.line,
+        "code_snippet": snippet
+    }
+
+def get_code_snippet(file_path: str, line_number: int, context_lines: int = 5) -> str:
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+
+            start_lines = max(1, line_number - context_lines)
+            end_lines = min(len(lines), line_number + context_lines)
+
+            snippet_lines = []
+            for i in range(start_lines, end_lines + 1):
+                prefix = ">" if i == line_number else " "
+                line_text = lines[i - 1]
+                snippet_lines.append(f"{prefix} {i:3d} | {line_text}")
+
+            return "".join(snippet_lines)
+
+    except Exception as e:
+        return f"Error getting code snippet: {e}"

src/hook.py

@@ -0,0 +1,67 @@
+import sys
+import os
+import threading
+from src.extractor import extract_crash_context
+from src.config_creator import create_config
+from src.agent.runner import run_socratic_agent
+from ui.views import SocraticUI
+
+
+def socratic_excepthook(exception_type, exception_value, exception_traceback):
+    """Intercepts uncaught exceptions and launches the Socratic GUI Terminal window."""
+    context = extract_crash_context(exception_traceback)
+
+    # Check if graphical desktop display is available
+    has_display = bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY") or sys.platform == "win32")
+
+    if has_display:
+        try:
+            from PyQt6.QtWidgets import QApplication
+            from ui.app import SocraticWindow
+
+            os.environ["SOCRATIC_GUI_ACTIVE"] = "1"
+
+            app = QApplication.instance()
+            if app is None:
+                app = QApplication(sys.argv)
+
+            # Create and display the centered Socratic Terminal window
+            window = SocraticWindow(
+                error_type=exception_type.__name__,
+                error_message=str(exception_value),
+                file_path=context["file_path"],
+                line_number=context["line_number"],
+                line_content=context["line_content"],
+            )
+            window.show()
+
+            # Run LangGraph State Machine in background worker thread
+            agent_thread = threading.Thread(
+                target=run_socratic_agent,
+                args=(exception_type, exception_value, exception_traceback),
+                daemon=True,
+            )
+            agent_thread.start()
+
+            # Run Qt GUI event loop
+            app.exec()
+            return
+        except Exception as e:
+            # Fallback to terminal mode if GUI setup fails
+            pass
+
+    # Headless / Terminal Fallback Mode
+    os.environ["SOCRATIC_GUI_ACTIVE"] = "0"
+    SocraticUI.display_crash_banner(
+        error_type=exception_type.__name__,
+        error_message=str(exception_value),
+        file_path=context["file_path"],
+        line_number=context["line_number"],
+        line_content=context["line_content"],
+    )
+    run_socratic_agent(exception_type, exception_value, exception_traceback)
+
+# use the hook 
+def install():
+    create_config()
+    sys.excepthook = socratic_excepthook

src/utils/read_yaml.py

@@ -0,0 +1,36 @@
+from src.config_creator import create_config
+from pathlib import Path
+import yaml
+import os
+
+
+class ReadYaml:
+    @staticmethod
+    def get_config_path() -> Path:
+        # 1. First check in current working directory
+        cwd_file = Path.cwd() / ".socratic.yaml"
+        if cwd_file.exists():
+            return cwd_file
+
+        # 2. Check in project root
+        project_root = Path(__file__).resolve().parent.parent.parent
+        root_file = project_root / ".socratic.yaml"
+        if root_file.exists():
+            return root_file
+
+        # 3. Fallback: auto-create in project root and return
+        create_config()
+        return root_file if root_file.exists() else cwd_file
+
+    @staticmethod
+    def read_yaml() -> dict:
+        config_path = ReadYaml.get_config_path()
+        try:
+            with open(config_path, "r", encoding="utf-8") as file:
+                data = yaml.safe_load(file) or {}
+                for key in ["LANGSMITH_TRACING", "LANGSMITH_API_KEY", "LANGSMITH_PROJECT"]:
+                    if data.get(key):
+                        os.environ[key] = str(data[key])
+                return data
+        except Exception:
+            return {}

ui/__init__.py

@@ -0,0 +1,15 @@
+from ui.app import SocraticWindow, bridge, wait_for_gui_user_input
+from ui.views import SocraticUI
+from ui.translations import TRANSLATIONS
+from ui.styles import SOCRATIC_DARK_THEME
+from ui.templates import ChatTemplates
+
+__all__ = [
+    "SocraticWindow",
+    "SocraticUI",
+    "bridge",
+    "wait_for_gui_user_input",
+    "TRANSLATIONS",
+    "SOCRATIC_DARK_THEME",
+    "ChatTemplates",
+]

ui/app.py

@@ -0,0 +1,203 @@
+import sys
+import threading
+from PyQt6.QtWidgets import (
+    QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout,
+    QTextEdit, QLineEdit, QPushButton, QLabel, QFrame
+)
+from PyQt6.QtCore import Qt, pyqtSignal, QObject
+from PyQt6.QtGui import QTextCursor
+
+from src.utils.read_yaml import ReadYaml
+from ui.translations import TRANSLATIONS
+from ui.styles import SOCRATIC_DARK_THEME
+from ui.templates import ChatTemplates
+
+
+class UIBridge(QObject):
+    """Bridge to pass messages from background agent threads to the Qt GUI thread."""
+    mentor_message_received = pyqtSignal(str, int)
+    user_input_requested = pyqtSignal()
+    solution_received = pyqtSignal(str)
+    evaluator_verdict_received = pyqtSignal(str)
+
+
+bridge = UIBridge()
+_user_reply_event = threading.Event()
+_user_reply_text = ""
+
+
+def wait_for_gui_user_input() -> str:
+    _user_reply_event.clear()
+    bridge.user_input_requested.emit()
+    _user_reply_event.wait()
+    return _user_reply_text
+
+
+def submit_gui_user_input(text: str):
+    global _user_reply_text
+    _user_reply_text = text
+    _user_reply_event.set()
+
+
+class SocraticWindow(QMainWindow):
+    """Pure, clean, fully-localized Socratic Terminal window."""
+
+    def __init__(self, error_type: str, error_message: str, file_path: str, line_number: int, line_content: str):
+        super().__init__()
+        
+        # Load language setting from .socratic.yaml
+        config = ReadYaml.read_yaml()
+        lang_setting = config.get("socratic_language", "English").strip().lower()
+        self.is_arabic = "arab" in lang_setting
+        self.translations = TRANSLATIONS["arabic"] if self.is_arabic else TRANSLATIONS["english"]
+
+        self.setWindowTitle(self.translations["app_title"])
+        self.resize(880, 640)
+
+        # Dynamic RTL / LTR layout
+        self.setLayoutDirection(Qt.LayoutDirection.RightToLeft if self.is_arabic else Qt.LayoutDirection.LeftToRight)
+
+        self._center_on_screen()
+        self.setStyleSheet(SOCRATIC_DARK_THEME)
+        self._build_ui(error_type, error_message, file_path, line_number, line_content)
+        self._connect_signals()
+
+    def _center_on_screen(self):
+        screen = QApplication.primaryScreen()
+        if screen:
+            screen_geom = screen.availableGeometry()
+            x = (screen_geom.width() - self.width()) // 2
+            y = (screen_geom.height() - self.height()) // 2
+            self.move(x, y)
+
+    def _build_ui(self, error_type: str, error_message: str, file_path: str, line_number: int, line_content: str):
+        central_widget = QWidget(self)
+        self.setCentralWidget(central_widget)
+        main_layout = QVBoxLayout(central_widget)
+        main_layout.setContentsMargins(18, 16, 18, 16)
+        main_layout.setSpacing(12)
+
+        # Header Bar
+        top_bar = QHBoxLayout()
+        header_label = QLabel(self.translations["header_title"], self)
+        header_label.setObjectName("headerTitle")
+        
+        self.status_badge = QLabel(self.translations["status_active"], self)
+        self.status_badge.setObjectName("statusBadge")
+        self.status_badge.setStyleSheet("color: #3fb950; background-color: #162a1c;")
+        
+        top_bar.addWidget(header_label)
+        top_bar.addStretch()
+        top_bar.addWidget(self.status_badge)
+        main_layout.addLayout(top_bar)
+
+        # Crash Summary Box
+        crash_frame = QFrame(self)
+        crash_frame.setObjectName("crashBanner")
+        crash_layout = QVBoxLayout(crash_frame)
+        crash_layout.setContentsMargins(12, 10, 12, 10)
+        crash_layout.setSpacing(4)
+
+        crash_title = QLabel(f"💥 <b>{error_type}</b>: {error_message}", crash_frame)
+        crash_title.setStyleSheet("color: #ff7b72; font-size: 15px;")
+        crash_title.setTextFormat(Qt.TextFormat.RichText)
+
+        loc_text = self.translations["crash_location"]
+        line_text = self.translations["crashing_line"]
+        crash_info = QLabel(
+            f"📍 {loc_text}: <i>{file_path}:{line_number}</i> &nbsp;&nbsp;|&nbsp;&nbsp; ⚡ {line_text}: <code style='color: #ffffff; background: #2b1d20; padding: 2px 6px;'>{line_content.strip()}</code>",
+            crash_frame
+        )
+        crash_info.setStyleSheet("color: #8b949e; font-size: 13px;")
+        crash_info.setTextFormat(Qt.TextFormat.RichText)
+
+        crash_layout.addWidget(crash_title)
+        crash_layout.addWidget(crash_info)
+        main_layout.addWidget(crash_frame)
+
+        # Chat Feed Area
+        self.chat_area = QTextEdit(self)
+        self.chat_area.setObjectName("chatArea")
+        self.chat_area.setReadOnly(True)
+        main_layout.addWidget(self.chat_area, stretch=1)
+
+        # Bottom Input Area
+        input_layout = QHBoxLayout()
+        input_layout.setSpacing(10)
+
+        self.input_field = QLineEdit(self)
+        self.input_field.setObjectName("inputField")
+        self.input_field.setPlaceholderText(self.translations["placeholder"])
+        self.input_field.returnPressed.connect(self._on_send_clicked)
+        self.input_field.setEnabled(False)
+
+        self.send_button = QPushButton(self.translations["send_btn"], self)
+        self.send_button.setObjectName("sendButton")
+        self.send_button.clicked.connect(self._on_send_clicked)
+        self.send_button.setEnabled(False)
+
+        input_layout.addWidget(self.input_field, stretch=1)
+        input_layout.addWidget(self.send_button)
+        main_layout.addLayout(input_layout)
+
+    def _connect_signals(self):
+        bridge.mentor_message_received.connect(self._append_mentor_message)
+        bridge.user_input_requested.connect(self._enable_user_input)
+        bridge.solution_received.connect(self._append_solution)
+        bridge.evaluator_verdict_received.connect(self._append_verdict)
+
+    def _append_mentor_message(self, content: str, hint_level: int):
+        html_msg = ChatTemplates.mentor_bubble(
+            content=content,
+            hint_level=hint_level,
+            mentor_name=self.translations["mentor_tag"],
+            hint_label=self.translations["hint_level"],
+            is_arabic=self.is_arabic,
+        )
+        self.chat_area.append(html_msg)
+        self._scroll_to_bottom()
+
+    def _enable_user_input(self):
+        self.input_field.setEnabled(True)
+        self.send_button.setEnabled(True)
+        self.input_field.setFocus()
+
+    def _on_send_clicked(self):
+        text = self.input_field.text().strip()
+        if not text:
+            return
+
+        self.input_field.clear()
+        self.input_field.setEnabled(False)
+        self.send_button.setEnabled(False)
+
+        user_html = ChatTemplates.user_bubble(
+            text=text,
+            user_tag=self.translations["user_tag"],
+            is_arabic=self.is_arabic,
+        )
+        self.chat_area.append(user_html)
+        self._scroll_to_bottom()
+
+        submit_gui_user_input(text)
+
+    def _append_verdict(self, verdict: str):
+        badge_html = ChatTemplates.verdict_badge(verdict)
+        self.chat_area.append(badge_html)
+        self._scroll_to_bottom()
+
+    def _append_solution(self, content: str):
+        self.status_badge.setText(self.translations["status_solved"])
+        self.status_badge.setStyleSheet("color: #ffffff; background-color: #238636;")
+
+        sol_html = ChatTemplates.solution_bubble(
+            content=content,
+            wrapup_title=self.translations["wrapup_title"],
+        )
+        self.chat_area.append(sol_html)
+        self._scroll_to_bottom()
+
+    def _scroll_to_bottom(self):
+        cursor = self.chat_area.textCursor()
+        cursor.movePosition(QTextCursor.MoveOperation.End)
+        self.chat_area.setTextCursor(cursor)

ui/bidi.py

@@ -0,0 +1,23 @@
+class BidiHelper:
+    """Helper to detect text direction for Socratic views."""
+
+    @staticmethod
+    def is_rtl_text(text: str) -> bool:
+        """Determines whether text is predominantly Arabic / RTL."""
+        if not text:
+            return False
+        for char in text:
+            code = ord(char)
+            # Arabic unicode ranges
+            if 0x0600 <= code <= 0x06FF or 0x0750 <= code <= 0x077F or 0x08A0 <= code <= 0x08FF:
+                return True
+        return False
+
+    @staticmethod
+    def format_text(text: str) -> str:
+        """
+        Modern Linux terminal emulators (GNOME Terminal, VTE, Kitty) have native
+        HarfBuzz shaping and BiDi engines. Passing raw Unicode preserves perfect
+        ligatures and prevents double-reversing artifacts.
+        """
+        return text

ui/console.py

@@ -0,0 +1,23 @@
+import shutil
+from rich.console import Console
+from rich.theme import Theme
+
+# Modern Dev Theme with sleek accents
+custom_theme = Theme({
+    "mentor": "bold cyan",
+    "mentor.box": "cyan",
+    "crash": "bold red",
+    "crash.box": "red",
+    "code": "bright_white on #1e1e2e",
+    "user": "bold yellow",
+    "success": "bold green",
+    "success.box": "green",
+    "subtle": "dim white",
+    "badge": "bold black on bright_cyan",
+})
+
+# Global rich console instance for socratic (adapts dynamically to window dimensions)
+console = Console(
+    theme=custom_theme,
+    highlight=False,
+)