PyPI - socratic-debug - Versions diffs - 0.0.4__tar.gz → 0.0.6__tar.gz - Mend

socratic-debug 0.0.4tar.gz → 0.0.6tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

{socratic_debug-0.0.4/socratic_debug.egg-info → socratic_debug-0.0.6}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socratic-debug
-Version: 0.0.4
+Version: 0.0.6
 Summary: Autonomous pedagogical debugging mentor powered by LangGraph, Rich, and LangSmith
 Author: Mohamed Elawakey
 Requires-Python: >=3.10
@@ -13,38 +13,61 @@ 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
+Requires-Dist: sqlalchemy>=2.0.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.
+> 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 +110,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 +129,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 +141,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 +153,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.6/README.md ADDED Viewed

@@ -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.6}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "socratic-debug"
-version = "0.0.4"
+version = "0.0.6"
 description = "Autonomous pedagogical debugging mentor powered by LangGraph, Rich, and LangSmith"
 authors = [{ name = "Mohamed Elawakey" }]
 readme = "README.md"
@@ -17,6 +17,7 @@ dependencies = [
     "langchain>=1.4.0",
     "langchain-ollama>=1.1.0",
     "langchain-openrouter>=0.2.0",
+    "sqlalchemy>=2.0.0",
 ]
 [project.scripts]

{socratic_debug-0.0.4 → socratic_debug-0.0.6/socratic_debug.egg-info}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: socratic-debug
-Version: 0.0.4
+Version: 0.0.6
 Summary: Autonomous pedagogical debugging mentor powered by LangGraph, Rich, and LangSmith
 Author: Mohamed Elawakey
 Requires-Python: >=3.10
@@ -13,38 +13,61 @@ 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
+Requires-Dist: sqlalchemy>=2.0.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.
+> 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 +110,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 +129,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 +141,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 +153,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.6}/socratic_debug.egg-info/SOURCES.txt RENAMED Viewed

@@ -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,15 @@ src/agent/prompts/mentor_prompt.py
 src/agent/prompts/questioner_prompt.py
 src/agent/prompts/solution_prompt.py
 src/agent/state/state.py
+src/db/connection.py
+src/db/detector.py
+src/db/migrator.py
+src/db/models.py
+src/db/service.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 +48,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.6}/socratic_debug.egg-info/requires.txt RENAMED Viewed

@@ -5,3 +5,4 @@ langgraph>=1.2.0
 langchain>=1.4.0
 langchain-ollama>=1.1.0
 langchain-openrouter>=0.2.0
+sqlalchemy>=2.0.0

{socratic_debug-0.0.4 → socratic_debug-0.0.6}/src/agent/llm/factory.py RENAMED Viewed

@@ -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.6/src/agent/llm/invoker.py ADDED Viewed

@@ -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.6}/src/agent/llm/providers/ollama.py RENAMED Viewed

@@ -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.6}/src/agent/nodes/diagnose_node.py RENAMED Viewed

@@ -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.6}/src/agent/nodes/evaluate_node.py RENAMED Viewed

@@ -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.6}/src/agent/nodes/human_input_node.py RENAMED Viewed

@@ -7,6 +7,12 @@ class HumanInputNode:
     def human_input_node(state: SocraticAgentState) -> dict:
         user_input = EventBus.request_user_input()
+        # Increment dialogue turns count in database
+        event_id = state.get("event_id")
+        if event_id:
+            from src.db.service import MetricsService
+            MetricsService.increment_dialogue_turns(event_id)
         history = list(state.get("dialogue_history", []))
         history.append({"role": "student", "content": user_input})

{socratic_debug-0.0.4 → socratic_debug-0.0.6}/src/agent/nodes/questioner_node.py RENAMED Viewed

@@ -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,17 @@ 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)
+        # Update hint level metric in database
+        event_id = state.get("event_id")
+        if event_id:
+            from src.db.service import MetricsService
+            MetricsService.update_hint_level(event_id, current_hint)
         EventBus.emit_mentor_message(
             content=response.content,

{socratic_debug-0.0.4 → socratic_debug-0.0.6}/src/agent/nodes/solution_node.py RENAMED Viewed

@@ -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,26 @@ 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)
+        # Mark error event as resolved in database
+        event_id = state.get("event_id")
+        if event_id:
+            from src.db.service import MetricsService
+            MetricsService.record_error_resolved(event_id)
         EventBus.emit_solution(response.content)

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

socratic-debug 0.0.4tar.gz → 0.0.6tar.gz