socratic-debug 0.0.4__tar.gz → 0.0.5__tar.gz

{socratic_debug-0.0.4/socratic_debug.egg-info → socratic_debug-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socratic-debug
-Version: 0.0.4
+Version: 0.0.5
 Summary: Autonomous pedagogical debugging mentor powered by LangGraph, Rich, and LangSmith
 Author: Mohamed Elawakey
 Requires-Python: >=3.10
@@ -18,33 +18,55 @@ 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.
+> An autonomous pedagogical debugger and AI mentor built for **students learning to code** and **developers** who want to truly understand their errors instead of copy-pasting AI patches.
 
 [![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)
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)  
+[![LangChain](https://img.shields.io/badge/LangChain-1.4+-1C3C3C?logo=chainlink&logoColor=white)](https://www.langchain.com/)
+[![LangGraph](https://img.shields.io/badge/LangGraph-1.2+-FF8800?logo=diagram-next&logoColor=white)](https://langchain-ai.github.io/langgraph/)
+[![PyQt6](https://img.shields.io/badge/PyQt6-GUI%20Terminal-41CD52?logo=qt&logoColor=white)](https://riverbankcomputing.com/software/pyqt/)
+[![Rich](https://img.shields.io/badge/Rich-Terminal%20UX-blueviolet)](https://github.com/Textualize/rich)
+
+[📦 PyPI Package](https://pypi.org/project/socratic-debug/) • [🐛 Report Bug](https://github.com/mohamedelawakey/socratic/issues)
+
+---
+
+<p align="center">
+  <a href="test/test_hook.py">
+    <img src="assets/socratic_ui_demo.png" alt="Socratic Debug Interactive Desktop UI" width="900" style="border-radius: 10px; box-shadow: 0 4px 20px rgba(0,0,0,0.5);" />
+  </a>
+  <br />
+  <sub>⚡ <em>Interactive debugging session generated live from <a href="test/test_hook.py"><code>test/test_hook.py</code></a></em></sub>
+</p>
 
 ---
 
 ## 💡 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.
+When a runtime crash happens, both beginners learning to program and seasoned developers often hit a wall:
+1. **For Students & Beginners:** A 50-line red terminal traceback feels overwhelming and cryptic. In the age of AI, copying the error into an LLM and pasting the generated code creates an illusion of progress—the student passes the assignment but never builds problem-solving intuition or mental models.
+2. **For Developers & Engineers:** Blindly pasting fixes without dissecting the failure mechanism leads to fragile code, cascading bugs, and recurring design flaws.
 
-**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.**
+**Socratic Debug changes the paradigm.**  
+Instead of dumping walls of red text or spoon-feeding copy-paste solutions, `socratic` intercepts uncaught runtime crashes and launches a **dedicated desktop mentorship window**. Powered by LangGraph, it acts like a personal coding instructor sitting right next to you:
+- It guides you through a progressive, calibrated Socratic dialogue.
+- It asks probing questions that help you spot the exact misconception on your own.
+- It verifies your understanding before finally unlocking defensive programming best practices.
 
 ---
 
 ## ✨ Features
 
-- 🖥️ **Standalone Desktop Window:** Launches an isolated, dark-themed GUI terminal window right at the center of your screen. No terminal pollution.
+- 🖥️ **Standalone Desktop Window:** Launches an isolated, dark-themed GUI terminal window right at the center of your screen. No terminal clutter.
+- ⚙️ **In-App Settings Drawer & Secret Masking:** Configure models and API keys directly from the GUI with a slide-in settings panel, toggleable secret masking (`👁️`), and instant hot-reloading.
+- ⚡ **Real-Time Auto-Reload & Live Watcher:** Background file monitor (`FileMonitor`) listens for fixes as you edit your code. It handles editor auto-save with a smart typing debounce, validates syntax, and auto-detects solutions live—no manual re-runs needed!
 - 🌍 **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**.
+- 🏗️ **Clean Decoupled Architecture:** Core agent nodes and exception hooks communicate via an abstract `EventBus`, allowing Socratic to plug cleanly into Desktop GUI, CLI, or future IDE plugins (VS Code, JetBrains).
 - 📊 **Built-in Observability:** Native tracing with **LangSmith** to monitor latency, tokens, and node execution graphs.
 - 🌐 **Cross-Platform:** Runs seamlessly on **Linux**, **macOS**, and **Windows**.
 
@@ -87,6 +109,7 @@ 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!
+- Edit your file in your editor (VS Code, PyCharm, etc.)—Socratic will detect your fix live and celebrate your solution!
 
 ### Method 2: In-Process Runtime Hook
 If you are building an application or library and want Socratic guidance baked directly into development runs:
@@ -105,7 +128,7 @@ 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:
+You can configure settings via the in-app **⚙️ Settings** drawer or directly in `.socratic.yaml`:
 
 ```yaml
 # LLM Provider: "ollama" or "openrouter"
@@ -117,7 +140,7 @@ provider_link: "http://localhost:11434"
 api_key: "your_api_key_here"
 
 # Mentor Personality & Language ("Arabic" or "English")
-socratic_language: "Arabic"
+socratic_language: "English"
 socratic_style: "friendly"
 
 # Observability with LangSmith (Optional)
@@ -129,10 +152,11 @@ 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.
+ 
+We welcome contributions from developers worldwide! Please review our [CONTRIBUTING.md](CONTRIBUTING.md) guidelines:
+- For feature requests or major changes, **please open a GitHub Discussion or Issue first**.
+- For bug fixes, direct Pull Requests are warmly welcome.
+- Browse our open issues labeled `good first issue` to start contributing.
 
 Please note that this project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
 

socratic_debug-0.0.5/README.md

@@ -0,0 +1,150 @@
+# 🧠 Socratic Debug (`socratic`)
+
+> **Stop copying stack traces. Start mastering your bugs.**  
+> An autonomous pedagogical debugger and AI mentor built for **students learning to code** and **developers** who want to truly understand their errors instead of copy-pasting AI patches.
+
+[![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%20%7C%203.14-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)  
+[![LangChain](https://img.shields.io/badge/LangChain-1.4+-1C3C3C?logo=chainlink&logoColor=white)](https://www.langchain.com/)
+[![LangGraph](https://img.shields.io/badge/LangGraph-1.2+-FF8800?logo=diagram-next&logoColor=white)](https://langchain-ai.github.io/langgraph/)
+[![PyQt6](https://img.shields.io/badge/PyQt6-GUI%20Terminal-41CD52?logo=qt&logoColor=white)](https://riverbankcomputing.com/software/pyqt/)
+[![Rich](https://img.shields.io/badge/Rich-Terminal%20UX-blueviolet)](https://github.com/Textualize/rich)
+
+[📦 PyPI Package](https://pypi.org/project/socratic-debug/) • [🐛 Report Bug](https://github.com/mohamedelawakey/socratic/issues)
+
+---
+
+<p align="center">
+  <a href="test/test_hook.py">
+    <img src="assets/socratic_ui_demo.png" alt="Socratic Debug Interactive Desktop UI" width="900" style="border-radius: 10px; box-shadow: 0 4px 20px rgba(0,0,0,0.5);" />
+  </a>
+  <br />
+  <sub>⚡ <em>Interactive debugging session generated live from <a href="test/test_hook.py"><code>test/test_hook.py</code></a></em></sub>
+</p>
+
+---
+
+## 💡 Why Socratic?
+
+When a runtime crash happens, both beginners learning to program and seasoned developers often hit a wall:
+1. **For Students & Beginners:** A 50-line red terminal traceback feels overwhelming and cryptic. In the age of AI, copying the error into an LLM and pasting the generated code creates an illusion of progress—the student passes the assignment but never builds problem-solving intuition or mental models.
+2. **For Developers & Engineers:** Blindly pasting fixes without dissecting the failure mechanism leads to fragile code, cascading bugs, and recurring design flaws.
+
+**Socratic Debug changes the paradigm.**  
+Instead of dumping walls of red text or spoon-feeding copy-paste solutions, `socratic` intercepts uncaught runtime crashes and launches a **dedicated desktop mentorship window**. Powered by LangGraph, it acts like a personal coding instructor sitting right next to you:
+- It guides you through a progressive, calibrated Socratic dialogue.
+- It asks probing questions that help you spot the exact misconception on your own.
+- It verifies your understanding before finally unlocking defensive programming best practices.
+
+---
+
+## ✨ Features
+
+- 🖥️ **Standalone Desktop Window:** Launches an isolated, dark-themed GUI terminal window right at the center of your screen. No terminal clutter.
+- ⚙️ **In-App Settings Drawer & Secret Masking:** Configure models and API keys directly from the GUI with a slide-in settings panel, toggleable secret masking (`👁️`), and instant hot-reloading.
+- ⚡ **Real-Time Auto-Reload & Live Watcher:** Background file monitor (`FileMonitor`) listens for fixes as you edit your code. It handles editor auto-save with a smart typing debounce, validates syntax, and auto-detects solutions live—no manual re-runs needed!
+- 🌍 **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**.
+- 🏗️ **Clean Decoupled Architecture:** Core agent nodes and exception hooks communicate via an abstract `EventBus`, allowing Socratic to plug cleanly into Desktop GUI, CLI, or future IDE plugins (VS Code, JetBrains).
+- 📊 **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!
+- Edit your file in your editor (VS Code, PyCharm, etc.)—Socratic will detect your fix live and celebrate your solution!
+
+### 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`)
+
+You can configure settings via the in-app **⚙️ Settings** drawer or directly in `.socratic.yaml`:
+
+```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: "English"
+socratic_style: "friendly"
+
+# Observability with LangSmith (Optional)
+LANGSMITH_TRACING: "true"
+LANGSMITH_API_KEY: "lsv2_pt_..."
+LANGSMITH_PROJECT: "socratic-debug"
+```
+
+---
+
+## 🤝 Contributing
+ 
+We welcome contributions from developers worldwide! Please review our [CONTRIBUTING.md](CONTRIBUTING.md) guidelines:
+- For feature requests or major changes, **please open a GitHub Discussion or Issue first**.
+- For bug fixes, direct Pull Requests are warmly welcome.
+- Browse our open issues labeled `good first issue` to start contributing.
+
+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.4 → socratic_debug-0.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "socratic-debug"
-version = "0.0.4"
+version = "0.0.5"
 description = "Autonomous pedagogical debugging mentor powered by LangGraph, Rich, and LangSmith"
 authors = [{ name = "Mohamed Elawakey" }]
 readme = "README.md"

{socratic_debug-0.0.4 → socratic_debug-0.0.5/socratic_debug.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socratic-debug
-Version: 0.0.4
+Version: 0.0.5
 Summary: Autonomous pedagogical debugging mentor powered by LangGraph, Rich, and LangSmith
 Author: Mohamed Elawakey
 Requires-Python: >=3.10
@@ -18,33 +18,55 @@ 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.
+> An autonomous pedagogical debugger and AI mentor built for **students learning to code** and **developers** who want to truly understand their errors instead of copy-pasting AI patches.
 
 [![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)
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)  
+[![LangChain](https://img.shields.io/badge/LangChain-1.4+-1C3C3C?logo=chainlink&logoColor=white)](https://www.langchain.com/)
+[![LangGraph](https://img.shields.io/badge/LangGraph-1.2+-FF8800?logo=diagram-next&logoColor=white)](https://langchain-ai.github.io/langgraph/)
+[![PyQt6](https://img.shields.io/badge/PyQt6-GUI%20Terminal-41CD52?logo=qt&logoColor=white)](https://riverbankcomputing.com/software/pyqt/)
+[![Rich](https://img.shields.io/badge/Rich-Terminal%20UX-blueviolet)](https://github.com/Textualize/rich)
+
+[📦 PyPI Package](https://pypi.org/project/socratic-debug/) • [🐛 Report Bug](https://github.com/mohamedelawakey/socratic/issues)
+
+---
+
+<p align="center">
+  <a href="test/test_hook.py">
+    <img src="assets/socratic_ui_demo.png" alt="Socratic Debug Interactive Desktop UI" width="900" style="border-radius: 10px; box-shadow: 0 4px 20px rgba(0,0,0,0.5);" />
+  </a>
+  <br />
+  <sub>⚡ <em>Interactive debugging session generated live from <a href="test/test_hook.py"><code>test/test_hook.py</code></a></em></sub>
+</p>
 
 ---
 
 ## 💡 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.
+When a runtime crash happens, both beginners learning to program and seasoned developers often hit a wall:
+1. **For Students & Beginners:** A 50-line red terminal traceback feels overwhelming and cryptic. In the age of AI, copying the error into an LLM and pasting the generated code creates an illusion of progress—the student passes the assignment but never builds problem-solving intuition or mental models.
+2. **For Developers & Engineers:** Blindly pasting fixes without dissecting the failure mechanism leads to fragile code, cascading bugs, and recurring design flaws.
 
-**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.**
+**Socratic Debug changes the paradigm.**  
+Instead of dumping walls of red text or spoon-feeding copy-paste solutions, `socratic` intercepts uncaught runtime crashes and launches a **dedicated desktop mentorship window**. Powered by LangGraph, it acts like a personal coding instructor sitting right next to you:
+- It guides you through a progressive, calibrated Socratic dialogue.
+- It asks probing questions that help you spot the exact misconception on your own.
+- It verifies your understanding before finally unlocking defensive programming best practices.
 
 ---
 
 ## ✨ Features
 
-- 🖥️ **Standalone Desktop Window:** Launches an isolated, dark-themed GUI terminal window right at the center of your screen. No terminal pollution.
+- 🖥️ **Standalone Desktop Window:** Launches an isolated, dark-themed GUI terminal window right at the center of your screen. No terminal clutter.
+- ⚙️ **In-App Settings Drawer & Secret Masking:** Configure models and API keys directly from the GUI with a slide-in settings panel, toggleable secret masking (`👁️`), and instant hot-reloading.
+- ⚡ **Real-Time Auto-Reload & Live Watcher:** Background file monitor (`FileMonitor`) listens for fixes as you edit your code. It handles editor auto-save with a smart typing debounce, validates syntax, and auto-detects solutions live—no manual re-runs needed!
 - 🌍 **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**.
+- 🏗️ **Clean Decoupled Architecture:** Core agent nodes and exception hooks communicate via an abstract `EventBus`, allowing Socratic to plug cleanly into Desktop GUI, CLI, or future IDE plugins (VS Code, JetBrains).
 - 📊 **Built-in Observability:** Native tracing with **LangSmith** to monitor latency, tokens, and node execution graphs.
 - 🌐 **Cross-Platform:** Runs seamlessly on **Linux**, **macOS**, and **Windows**.
 
@@ -87,6 +109,7 @@ 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!
+- Edit your file in your editor (VS Code, PyCharm, etc.)—Socratic will detect your fix live and celebrate your solution!
 
 ### Method 2: In-Process Runtime Hook
 If you are building an application or library and want Socratic guidance baked directly into development runs:
@@ -105,7 +128,7 @@ 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:
+You can configure settings via the in-app **⚙️ Settings** drawer or directly in `.socratic.yaml`:
 
 ```yaml
 # LLM Provider: "ollama" or "openrouter"
@@ -117,7 +140,7 @@ provider_link: "http://localhost:11434"
 api_key: "your_api_key_here"
 
 # Mentor Personality & Language ("Arabic" or "English")
-socratic_language: "Arabic"
+socratic_language: "English"
 socratic_style: "friendly"
 
 # Observability with LangSmith (Optional)
@@ -129,10 +152,11 @@ 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.
+ 
+We welcome contributions from developers worldwide! Please review our [CONTRIBUTING.md](CONTRIBUTING.md) guidelines:
+- For feature requests or major changes, **please open a GitHub Discussion or Issue first**.
+- For bug fixes, direct Pull Requests are warmly welcome.
+- Browse our open issues labeled `good first issue` to start contributing.
 
 Please note that this project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
 

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/socratic_debug.egg-info/SOURCES.txt

@@ -10,8 +10,6 @@ socratic_debug.egg-info/requires.txt
 socratic_debug.egg-info/top_level.txt
 src/__init__.py
 src/cli.py
-src/config_creator.py
-src/config_template.py
 src/events.py
 src/extractor.py
 src/hook.py
@@ -19,6 +17,7 @@ src/watcher.py
 src/agent/runner.py
 src/agent/graph/graph.py
 src/agent/llm/factory.py
+src/agent/llm/invoker.py
 src/agent/llm/providers/__init__.py
 src/agent/llm/providers/ollama.py
 src/agent/llm/providers/openrouter.py
@@ -33,6 +32,10 @@ src/agent/prompts/mentor_prompt.py
 src/agent/prompts/questioner_prompt.py
 src/agent/prompts/solution_prompt.py
 src/agent/state/state.py
+src/utils/config_creator.py
+src/utils/config_manager.py
+src/utils/config_template.py
+src/utils/config_watcher.py
 src/utils/read_yaml.py
 test/test_hook.py
 ui/__init__.py
@@ -40,6 +43,7 @@ ui/adapter.py
 ui/app.py
 ui/bidi.py
 ui/console.py
+ui/settings_drawer.py
 ui/styles.py
 ui/templates.py
 ui/translations.py

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/agent/llm/factory.py

@@ -1,4 +1,5 @@
-from src.agent.llm.providers import *
+from src.agent.llm.providers.openrouter import OpenRouterLLM
+from src.agent.llm.providers.ollama import OllamaLLM
 from src.utils.read_yaml import ReadYaml
 
 

socratic_debug-0.0.5/src/agent/llm/invoker.py

@@ -0,0 +1,28 @@
+import os
+import time
+from src.agent.llm.factory import LLMFactory
+from src.events import EventBus
+
+
+class LLMInvoker:
+    @staticmethod
+    def invoke_with_retry(prompt: str, max_headless_retries: int = 3):
+        is_gui = os.environ.get("SOCRATIC_GUI_ACTIVE") == "1"
+        attempts = 0
+
+        while True:
+            if EventBus.is_session_cancelled():
+                raise RuntimeError("Session was cancelled by user.")
+
+            try:
+                return LLMFactory.get_llm().invoke(prompt)
+            except Exception as e:
+                err_msg = str(e)
+                EventBus.emit_llm_error(err_msg)
+
+                if not is_gui:
+                    attempts += 1
+                    if attempts >= max_headless_retries:
+                        raise RuntimeError(f"LLM invocation failed after {attempts} attempts: {err_msg}") from e
+
+                time.sleep(2)

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/agent/llm/providers/ollama.py

@@ -7,7 +7,7 @@ class OllamaLLM:
     def ollama_llm():
         config = ReadYaml.read_yaml()
 
-        return ChatOllama (
+        return ChatOllama(
             model=config["provider_name"],
             base_url=config["provider_link"],
         )

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/agent/nodes/diagnose_node.py

@@ -1,6 +1,6 @@
 from src.agent.prompts.diagnose_prompt import DiagnosePrompt
 from src.agent.state.state import SocraticAgentState
-from src.agent.llm.factory import LLMFactory
+from src.agent.llm.invoker import LLMInvoker
 
 
 class DiagnoseNode:
@@ -16,6 +16,6 @@ class DiagnoseNode:
             function_name=state.get("function_name") or "",
         )
 
-        response = LLMFactory.get_llm().invoke(prompt)
+        response = LLMInvoker.invoke_with_retry(prompt)
 
         return {"root_cause": response.content}

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/agent/nodes/evaluate_node.py

@@ -1,6 +1,6 @@
 from src.agent.prompts.evaluation_prompt import EvaluationPrompt
 from src.agent.state.state import SocraticAgentState
-from src.agent.llm.factory import LLMFactory
+from src.agent.llm.invoker import LLMInvoker
 from src.events import EventBus
 
 
@@ -26,7 +26,7 @@ class EvaluationNode:
             user_input=user_input,
         )
 
-        response = LLMFactory.get_llm().invoke(prompt)
+        response = LLMInvoker.invoke_with_retry(prompt)
         verdict = response.content.strip().upper()
 
         if "SOLVED" in verdict and "UNSOLVED" not in verdict and "NOT SOLVED" not in verdict:

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/agent/nodes/questioner_node.py

@@ -1,6 +1,6 @@
 from src.agent.prompts.questioner_prompt import QuestionerPrompt
 from src.agent.state.state import SocraticAgentState
-from src.agent.llm.factory import LLMFactory
+from src.agent.llm.invoker import LLMInvoker
 from src.utils.read_yaml import ReadYaml
 
 from src.events import EventBus
@@ -14,6 +14,9 @@ class QuestionerNode:
         current_hint = state.get("hint_level", 1)
         raw_history = state.get("dialogue_history", [])
 
+        # Re-read YAML configuration dynamically to reflect any runtime updates
+        live_config = ReadYaml.read_yaml()
+
         formatted_history = "\n".join(
             f"- {turn.get('role', 'unknown').capitalize()}: {turn.get('content', '')}"
             for turn in raw_history
@@ -27,11 +30,11 @@ class QuestionerNode:
             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"),
+            language=live_config.get("socratic_language", "English"),
+            style=live_config.get("socratic_style", "friendly"),
         )
 
-        response = LLMFactory.get_llm().invoke(prompt)
+        response = LLMInvoker.invoke_with_retry(prompt)
 
         EventBus.emit_mentor_message(
             content=response.content,

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/agent/nodes/solution_node.py

@@ -1,6 +1,6 @@
 from src.agent.prompts.solution_prompt import SolutionPrompt
 from src.agent.state.state import SocraticAgentState
-from src.agent.llm.factory import LLMFactory
+from src.agent.llm.invoker import LLMInvoker
 from src.utils.read_yaml import ReadYaml
 from src.events import EventBus
 
@@ -12,17 +12,20 @@ class SolutionNode:
     def solution_node(state: SocraticAgentState) -> dict:
         current_status = state.get("eval_status", "solved")
 
+        # Dynamically re-read config to adapt to live changes
+        live_config = ReadYaml.read_yaml()
+
         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"),
+            language=live_config.get("socratic_language", "English"),
+            style=live_config.get("socratic_style", "friendly"),
         )
 
-        response = LLMFactory.get_llm().invoke(prompt)
+        response = LLMInvoker.invoke_with_retry(prompt)
 
         EventBus.emit_solution(response.content)
 

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/agent/state/state.py

@@ -1,4 +1,4 @@
-from typing import TypedDict, List, Dict, Any, Optional
+from typing import TypedDict, List, Dict, Optional
 
 
 class SocraticAgentState(TypedDict):

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/cli.py

@@ -64,7 +64,7 @@ def main():
         sys.exit(0)
 
     elif command == "init":
-        from src.config_creator import create_config
+        from src.utils.config_creator import create_config
         create_config()
         print("✔ Created .socratic.yaml with default settings.")
         sys.exit(0)

{socratic_debug-0.0.4 → socratic_debug-0.0.5}/src/events.py

@@ -8,6 +8,16 @@ class EventBus:
     _on_evaluator_verdict: Optional[Callable[[str], None]] = None
     _on_solution: Optional[Callable[[str], None]] = None
     _on_crash: Optional[Callable[[Dict[str, Any], Any, Any, Any], None]] = None
+    _on_llm_error: Optional[Callable[[str], None]] = None
+    _is_session_cancelled: bool = False
+
+    @classmethod
+    def emit_session_cancelled(cls):
+        cls._is_session_cancelled = True
+
+    @classmethod
+    def is_session_cancelled(cls) -> bool:
+        return cls._is_session_cancelled
 
     @classmethod
     def register_handlers(
@@ -17,6 +27,7 @@ class EventBus:
         on_evaluator_verdict: Optional[Callable[[str], None]] = None,
         on_solution: Optional[Callable[[str], None]] = None,
         on_crash: Optional[Callable[[Dict[str, Any], Any, Any, Any], None]] = None,
+        on_llm_error: Optional[Callable[[str], None]] = None,
     ):
         """Registers presentation callbacks into the Core event bus."""
         if on_mentor_message:
@@ -29,6 +40,8 @@ class EventBus:
             cls._on_solution = on_solution
         if on_crash:
             cls._on_crash = on_crash
+        if on_llm_error:
+            cls._on_llm_error = on_llm_error
 
     @classmethod
     def emit_mentor_message(cls, content: str, hint_level: int = 1):
@@ -65,3 +78,10 @@ class EventBus:
         else:
             print(f"\n💥 {exc_type.__name__}: {exc_val}")
             print(f"📍 {context.get('file_path')}:{context.get('line_number')}\n")
+
+    @classmethod
+    def emit_llm_error(cls, err_msg: str):
+        if cls._on_llm_error:
+            cls._on_llm_error(err_msg)
+        else:
+            print(f"⚠️ [LLM Error]: {err_msg}")