Implement DebtGuardian: LLM-based Technical Debt detection framework

README.md

@@ -17,6 +17,7 @@ DataForgeTest is a comprehensive solution for automating data quality testing in
 - **🔍 Advanced PySpark Generator** - Upload datasets for automatic schema detection and intelligent code generation
 - **🌐 Modern Web Interface** - React-based frontend with responsive design and dark theme
 - **🔧 RESTful API Architecture** - Modular Flask backend with comprehensive error handling
+- **🔬 DebtGuardian (Experimental)** - LLM-based technical debt detection using local AI models
 
 ## 📋 Table of Contents
 
@@ -378,12 +379,51 @@ DataForgeTest/
 │   ├── synthetic/           # Synthetic data generation
 │   ├── accuracy/            # Data accuracy validation
 │   ├── gold/                # GOLD dataset testing
-│   └── rag/                # RAG support system
+│   ├── rag/                 # RAG support system
+│   └── debt_guardian/       # Technical debt detection (experimental)
 ├── docs/                    # Comprehensive documentation
 ├── tests/                   # Test suites
 └── storage/                 # Data storage
 ```
 
+### 🔬 Experimental: DebtGuardian
+
+**NEW!** AI-powered technical debt detection using local LLM (Qwen2.5-Coder:7b via Ollama).
+
+**Key Features:**
+- 🎯 **77% Recall**: Based on research paper performance
+- 🏠 **Local AI**: Runs entirely on your machine via Ollama
+- 📊 **7 TD Types**: Design, documentation, defects, tests, compatibility, build, requirement
+- 🔄 **Git Integration**: Analyze commits and repository history
+- 🎨 **Multiple Strategies**: Zero-shot, few-shot, batch, granular prompting
+- 🗳️ **Majority Voting**: Boost recall by ~8%
+
+**Quick Start:**
+```bash
+# Install Ollama
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Pull model (one-time, ~5GB)
+ollama pull qwen2.5-coder:7b
+
+# Start Ollama
+ollama serve
+
+# Install dependencies
+pip install ollama pydantic gitpython guardrails-ai
+
+# Run example
+python examples/analyze_sample.py
+```
+
+**Documentation:**
+- [Setup & Testing Guide](SETUP_TESTING_GUIDE.md)
+- [Full Documentation](docs/DEBT_GUARDIAN.md)
+- [Quick Start](docs/DEBT_GUARDIAN_QUICKSTART.md)
+- [Module README](src/debt_guardian/README.md)
+
+**Note**: This is an experimental feature on the `copilot/setup-experimental-llm-framework` branch for testing before broader deployment.
+
 ## 📡 API Reference
 
 ### Core Endpoints

check_setup.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""
+DebtGuardian Setup Checker
+
+This script verifies that all components are properly installed and configured.
+"""
+import sys
+import os
+import subprocess
+
+# Add src to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "src"))
+
+# Constants
+MODEL_NAME = "qwen2.5-coder:7b"
+
+
+def print_header(text):
+    """Print a section header"""
+    print("\n" + "=" * 60)
+    print(f"  {text}")
+    print("=" * 60)
+
+
+def print_check(item, status, message=""):
+    """Print a check result"""
+    symbol = "✓" if status else "✗"
+    status_text = "OK" if status else "FAIL"
+    print(f"{symbol} {item:40} [{status_text}]")
+    if message:
+        print(f"  → {message}")
+
+
+def check_python_version():
+    """Check Python version"""
+    version = sys.version_info
+    ok = version.major == 3 and version.minor >= 8
+    msg = f"Python {version.major}.{version.minor}.{version.micro}"
+    print_check("Python 3.8+", ok, msg)
+    return ok
+
+
+def check_dependency(module_name, import_name=None):
+    """Check if a Python module is installed"""
+    if import_name is None:
+        import_name = module_name
+
+    try:
+        __import__(import_name)
+        print_check(f"Python: {module_name}", True)
+        return True
+    except ImportError:
+        print_check(f"Python: {module_name}", False, f"Run: pip install {module_name}")
+        return False
+
+
+def check_ollama_installed():
+    """Check if Ollama is installed"""
+    try:
+        result = subprocess.run(
+            ["ollama", "--version"], capture_output=True, text=True, timeout=5
+        )
+        ok = result.returncode == 0
+        version = result.stdout.strip() if ok else ""
+        print_check(
+            "Ollama installed",
+            ok,
+            version or "Run: curl -fsSL https://ollama.ai/install.sh | sh",
+        )
+        return ok
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        print_check("Ollama installed", False, "Download from https://ollama.ai")
+        return False
+
+
+def check_ollama_running():
+    """Check if Ollama service is running"""
+    try:
+        import requests
+
+        response = requests.get("http://localhost:11434/api/tags", timeout=2)
+        ok = response.status_code == 200
+        print_check(
+            "Ollama service running",
+            ok,
+            "Ollama is running" if ok else "Run: ollama serve",
+        )
+        return ok
+    except Exception:
+        print_check("Ollama service running", False, "Run: ollama serve")
+        return False
+
+
+def check_model_available():
+    """Check if Qwen2.5-Coder:7b is available"""
+    try:
+        result = subprocess.run(
+            ["ollama", "list"], capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0:
+            ok = MODEL_NAME in result.stdout
+            print_check(
+                f"Model: {MODEL_NAME}",
+                ok,
+                "Model available" if ok else f"Run: ollama pull {MODEL_NAME}",
+            )
+            return ok
+        else:
+            print_check(f"Model: {MODEL_NAME}", False, "Cannot check models")
+            return False
+    except Exception:
+        print_check(f"Model: {MODEL_NAME}", False, "Cannot check models")
+        return False
+
+
+def check_debtguardian_imports():
+    """Check if DebtGuardian can be imported"""
+    try:
+        # Import to verify module availability
+        import debt_guardian.config  # noqa: F401
+        import debt_guardian.detector  # noqa: F401
+        import debt_guardian.schemas.td_schema  # noqa: F401
+
+        print_check("DebtGuardian imports", True)
+        return True
+    except Exception as e:
+        print_check("DebtGuardian imports", False, str(e))
+        return False
+
+
+def check_debtguardian_connection():
+    """Check if DebtGuardian can connect to Ollama"""
+    try:
+        from debt_guardian.config import DebtGuardianConfig
+        from debt_guardian.llm_client import OllamaClient
+
+        config = DebtGuardianConfig()
+        client = OllamaClient(config)
+        ok = client.health_check()
+        print_check(
+            "DebtGuardian → Ollama", ok, "Connection OK" if ok else "Cannot connect"
+        )
+        return ok
+    except Exception as e:
+        print_check("DebtGuardian → Ollama", False, str(e))
+        return False
+
+
+def run_quick_test():
+    """Run a quick analysis test"""
+    try:
+        from debt_guardian.config import DebtGuardianConfig
+        from debt_guardian.detector import DebtDetector
+
+        print("\nRunning quick test analysis...")
+        print("(This may take 10-20 seconds...)")
+
+        config = DebtGuardianConfig(td_types=["design"], use_granular_prompting=True)
+        detector = DebtDetector(config)
+
+        test_diff = "+def test():\n+    pass"
+
+        report = detector.detect_in_diff(code_diff=test_diff, file_path="test.py")
+
+        print_check(
+            "Quick test analysis",
+            True,
+            f"Analyzed successfully (found {report.debt_count} debts)",
+        )
+        return True
+
+    except Exception as e:
+        print_check("Quick test analysis", False, str(e))
+        return False
+
+
+def main():
+    """Run all checks"""
+    print_header("DebtGuardian Setup Checker")
+    print("\nThis script will verify your DebtGuardian installation.\n")
+
+    all_ok = True
+
+    # Phase 1: Python environment
+    print_header("Phase 1: Python Environment")
+    all_ok &= check_python_version()
+
+    # Phase 2: Python dependencies
+    print_header("Phase 2: Python Dependencies")
+    all_ok &= check_dependency("Flask", "flask")
+    all_ok &= check_dependency("pydantic")
+    all_ok &= check_dependency("ollama")
+    all_ok &= check_dependency("GitPython", "git")
+    all_ok &= check_dependency("guardrails-ai", "guardrails")
+
+    # Phase 3: Ollama setup
+    print_header("Phase 3: Ollama Setup")
+    ollama_installed = check_ollama_installed()
+    all_ok &= ollama_installed
+
+    if ollama_installed:
+        ollama_running = check_ollama_running()
+        all_ok &= ollama_running
+
+        if ollama_running:
+            all_ok &= check_model_available()
+
+    # Phase 4: DebtGuardian
+    print_header("Phase 4: DebtGuardian Framework")
+    imports_ok = check_debtguardian_imports()
+    all_ok &= imports_ok
+
+    if imports_ok and ollama_installed and check_ollama_running():
+        all_ok &= check_debtguardian_connection()
+
+    # Phase 5: Integration test
+    if all_ok:
+        print_header("Phase 5: Integration Test")
+        all_ok &= run_quick_test()
+
+    # Summary
+    print_header("Summary")
+
+    if all_ok:
+        print("\n✅ ALL CHECKS PASSED!")
+        print("\nYour DebtGuardian installation is ready to use.")
+        print("\nNext steps:")
+        print("  1. Run example: python examples/analyze_sample.py")
+        print("  2. Read docs: docs/DEBT_GUARDIAN_QUICKSTART.md")
+        print("  3. Start testing on your projects!")
+    else:
+        print("\n⚠️  SOME CHECKS FAILED")
+        print("\nPlease fix the issues marked with ✗ above.")
+        print("\nCommon fixes:")
+        print("  • Install missing dependencies: pip install -r requirements.txt")
+        print("  • Install Ollama: curl -fsSL https://ollama.ai/install.sh | sh")
+        print("  • Start Ollama: ollama serve")
+        print(f"  • Pull model: ollama pull {MODEL_NAME}")
+        print("\nFor detailed setup instructions, see: SETUP_TESTING_GUIDE.md")
+
+    print()
+    return 0 if all_ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())