added utils directory

UTILS_DIRECTORY_GUIDE.md

@@ -65,11 +65,6 @@ pages/Format_Resume.py
 | `data/job_titles.json` | **Job title patterns** - Used by extractor_fixed.py for regex matching | When all AI methods fail (fallback) | 🟡 BACKUP |
 | `data/skills.json` | **Skills database** - Used by extractor_fixed.py for spaCy skill matching | When all AI methods fail (fallback) | 🟡 BACKUP |
 
-### **❌ NOT NEEDED - Other Features**
-
-| File | Purpose | Why Not Needed |
-|------|---------|----------------|
-| `screening.py` | Resume evaluation, scoring, candidate screening | Used by TalentLens.py, not Format_Resume.py |
 
 ## 🚀 **Format_Resume.py Extraction Flow**
 
@@ -83,127 +78,3 @@ pages/Format_Resume.py
    └── If all fail → Use extractor_fixed.py (regex fallback) → uses data/*.json
 3. builder.py generates formatted Word document with preserved template headers/footers
 4. User downloads formatted resume with Qvell branding and proper formatting
-```
-
-## 🏗️ **Document Builder Enhancements**
-
-The `builder.py` has been enhanced to properly handle template preservation:
-
-### **Header/Footer Preservation**
-- ✅ **Preserves Qvell logo** and branding in header
-- ✅ **Maintains footer address** (6001 Tain Dr. Suite 203, Dublin, OH, 43016)
-- ✅ **Eliminates blank pages** by clearing only body content
-- ✅ **Preserves image references** to prevent broken images
-
-### **Content Generation Features**
-- ✅ **Professional Summary** extraction and formatting
-- ✅ **Skills table** with 3-column layout
-- ✅ **Professional Experience** with job titles, companies, dates
-- ✅ **Career Timeline** chronological job history
-- ✅ **Education and Training** sections
-- ✅ **Proper date formatting** (e.g., "February 2017 – Present")
-
-## 📊 **File Usage Statistics**
-
-- **Total utils files**: 11
-- **Required for Format_Resume.py**: 10 files (91%)
-- **Not needed for Format_Resume.py**: 1 file (9%)
-
-## 🧹 **Cleanup Recommendations**
-
-If you want to **minimize the utils folder** for Format_Resume.py only:
-
-### **Keep These 10 Files:**
-```
-utils/
-├── hybrid_extractor.py      # Main orchestrator
-├── openai_extractor.py      # OpenAI GPT-4o (primary)
-├── hf_cloud_extractor.py    # HF Cloud (backup)
-├── ai_extractor.py          # HF AI (fallback)
-├── hf_extractor_simple.py   # Simple HF (fallback)
-├── extractor_fixed.py       # Regex (last resort)
-├── builder.py               # Document generation with template preservation
-├── parser.py                # File parsing
-└── data/
-    ├── job_titles.json      # Job title patterns for regex fallback
-    └── skills.json          # Skills database for spaCy fallback
-```
-
-### **Can Remove This 1 File (if only using Format_Resume.py):**
-```
-utils/
-└── screening.py             # Only used by TalentLens.py
-```
-
-## 💡 **Best Practices for Format_Resume.py**
-
-1. **Always use `hybrid_extractor.py`** as your main entry point
-2. **Set environment variables** for best results:
-   - `OPENAI_API_KEY` for OpenAI GPT-4o (primary)
-   - `HF_API_TOKEN` for Hugging Face Cloud (backup)
-3. **Use this configuration** in Format_Resume.py:
-   ```python
-   data = extract_resume_sections(
-       resume_text, 
-       prefer_ai=True, 
-       use_openai=True,      # Try OpenAI GPT-4o first (best results)
-       use_hf_cloud=True     # Fallback to HF Cloud (good backup)
-   )
-   ```
-4. **Template preservation** is automatic - headers and footers are maintained
-5. **Fallback system** ensures extraction never completely fails
-
-## 🔧 **Recent System Improvements**
-
-### **Header/Footer Preservation (Latest Fix)**
-- **Problem**: Template headers and footers were being lost during document generation
-- **Solution**: Conservative content clearing that preserves document structure
-- **Result**: Qvell branding and footer address now properly maintained
-
-### **Extraction Quality Enhancements**
-- **OpenAI GPT-4o Integration**: Primary extraction method with structured prompts
-- **Contact Info Extraction**: Automatic email, phone, LinkedIn detection
-- **Skills Cleaning**: Improved filtering to remove company names and broken fragments
-- **Experience Structuring**: Better job title, company, and date extraction
-
-### **Fallback System Reliability**
-- **JSON Dependencies**: job_titles.json and skills.json required for regex fallback
-- **Quality Validation**: Each extraction method is validated before acceptance
-- **Graceful Degradation**: System never fails completely, always produces output
-
-## 🧪 **Testing Format_Resume.py Dependencies**
-
-```python
-# Test all required components for Format_Resume.py
-from utils.hybrid_extractor import extract_resume_sections, HybridResumeExtractor
-from utils.builder import build_resume_from_data
-from utils.parser import parse_resume
-
-# Test extraction with all fallbacks
-sample_text = "John Doe\nSoftware Engineer\nPython, Java, React"
-result = extract_resume_sections(sample_text, prefer_ai=True, use_openai=True, use_hf_cloud=True)
-
-# Test document building with template preservation
-template_path = "templates/blank_resume.docx"
-doc = build_resume_from_data(template_path, result)
-
-print("✅ All Format_Resume.py dependencies working!")
-print(f"✅ Extraction method used: {result.get('extraction_method', 'unknown')}")
-print(f"✅ Headers/footers preserved: {len(doc.sections)} sections")
-```
-
-## 🎯 **System Architecture Summary**
-
-The Format_Resume.py system now provides:
-
-1. **Robust Extraction**: 5-tier fallback system (OpenAI → HF Cloud → HF AI → HF Simple → Regex)
-2. **Template Preservation**: Headers, footers, and branding maintained perfectly
-3. **Quality Assurance**: Each extraction method validated for completeness
-4. **Professional Output**: Properly formatted Word documents with consistent styling
-5. **Reliability**: System never fails completely, always produces usable output
-
----
-
-**The utils directory analysis shows 10 out of 11 files are needed for Format_Resume.py functionality! 🎯**
-
-**Recent improvements ensure perfect template preservation and reliable extraction quality.** ✨