Reduce default gunicorn workers and clean up documentation (#60)

* Reduce default gunicorn workers to 1 to avoid out-of-memory errors on low-memory hosts

* chore: Remove outdated implementation summaries for guardrails and query expansion

* chore: Add comment to clarify default worker setting in run.sh

ISSUE_24_IMPLEMENTATION_SUMMARY.md

@@ -1,223 +0,0 @@
-# Issue #24: Guardrails and Response Quality System - Implementation Summary
-
-## 🎯 Overview
-
-Successfully implemented a comprehensive guardrails and response quality system for the RAG pipeline as specified in Issue #24. The implementation includes enterprise-grade safety validation, quality assessment, and source attribution capabilities.
-
-## 🏗️ Architecture
-
-### Core Components
-
-1. **ResponseValidator** (`src/guardrails/response_validator.py`)
-   - Quality scoring across multiple dimensions (relevance, completeness, coherence, source fidelity)
-   - Safety validation with pattern-based detection
-   - Confidence scoring and recommendation generation
-
-2. **SourceAttributor** (`src/guardrails/source_attribution.py`)
-   - Automatic citation generation with multiple formats
-   - Source ranking and relevance scoring
-   - Quote extraction and validation
-   - Citation text enhancement
-
-3. **ContentFilter** (`src/guardrails/content_filters.py`)
-   - PII detection and masking
-   - Inappropriate content filtering
-   - Bias detection and mitigation
-   - Topic validation against allowed categories
-
-4. **QualityMetrics** (`src/guardrails/quality_metrics.py`)
-   - Multi-dimensional quality assessment
-   - Configurable scoring weights and thresholds
-   - Detailed recommendations for improvement
-   - Professional tone analysis
-
-5. **ErrorHandler** (`src/guardrails/error_handlers.py`)
-   - Circuit breaker patterns for resilience
-   - Graceful degradation strategies
-   - Comprehensive fallback mechanisms
-   - Error tracking and recovery
-
-6. **GuardrailsSystem** (`src/guardrails/guardrails_system.py`)
-   - Main orchestrator coordinating all components
-   - Comprehensive validation pipeline
-   - Approval logic with configurable thresholds
-   - Health monitoring and diagnostics
-
-### Integration Layer
-
-7. **EnhancedRAGPipeline** (`src/rag/enhanced_rag_pipeline.py`)
-   - Seamless integration with existing RAG pipeline
-   - Backward compatibility maintained
-   - Enhanced response type with guardrails metadata
-   - Standalone validation capabilities
-
-## 📋 Features Implemented
-
-### ✅ Safety Requirements (All Met)
-- **Content Safety**: Inappropriate content detection and filtering
-- **PII Protection**: Automatic detection and masking of sensitive information
-- **Bias Mitigation**: Pattern-based bias detection and scoring
-- **Topic Validation**: Ensures responses stay within allowed corporate topics
-- **Safety Scoring**: Comprehensive risk assessment
-
-### ✅ Quality Standards (All Met)
-- **Multi-dimensional Quality Assessment**:
-  - Relevance scoring (0.3 weight)
-  - Completeness scoring (0.25 weight)
-  - Coherence scoring (0.2 weight)
-  - Source fidelity scoring (0.25 weight)
-- **Configurable Thresholds**: Quality threshold (0.7), minimum response length (50 chars)
-- **Quality Recommendations**: Specific suggestions for improvement
-- **Professional Tone Analysis**: Ensures appropriate business communication
-
-### ✅ Technical Standards (All Met)
-- **Error Handling**: Comprehensive circuit breaker patterns and graceful degradation
-- **Performance**: Efficient validation with configurable timeouts
-- **Logging**: Detailed logging for debugging and monitoring
-- **Configuration**: Flexible configuration system for all components
-- **Testing**: Complete test coverage with 13 passing tests
-- **Documentation**: Comprehensive docstrings and type hints
-
-## 🔧 Configuration
-
-The system is highly configurable with default settings optimized for corporate policy applications:
-
-```python
-# Example configuration
-guardrails_config = {
-    "min_confidence_threshold": 0.7,
-    "strict_mode": False,
-    "enable_response_enhancement": True,
-    "content_filter": {
-        "enable_pii_filtering": True,
-        "enable_bias_detection": True,
-        "safety_threshold": 0.8
-    },
-    "quality_metrics": {
-        "quality_threshold": 0.7,
-        "min_response_length": 50,
-        "preferred_source_count": 3
-    }
-}
-```
-
-## 🧪 Testing
-
-### Test Coverage
-- **7 Guardrails Tests**: All core functionality validated
-- **4 Enhanced Pipeline Tests**: Integration testing complete
-- **6 Enhanced App Tests**: API endpoint integration verified
-
-### Test Results
-```
-tests/test_guardrails/: 7 tests PASSED
-tests/test_enhanced_app_guardrails.py: 6 tests PASSED
-Total: 13 tests PASSED
-```
-
-## 🚀 Usage Examples
-
-### Basic Integration
-```python
-from src.rag.enhanced_rag_pipeline import EnhancedRAGPipeline
-from src.rag.rag_pipeline import RAGPipeline
-
-# Create enhanced pipeline
-base_pipeline = RAGPipeline(search_service, llm_service)
-enhanced_pipeline = EnhancedRAGPipeline(base_pipeline)
-
-# Generate validated response
-response = enhanced_pipeline.generate_answer("What is our remote work policy?")
-
-# Access guardrails information
-print(f"Approved: {response.guardrails_approved}")
-print(f"Safety: {response.safety_passed}")
-print(f"Quality: {response.quality_score}")
-```
-
-### API Integration
-```python
-# Enhanced Flask app with guardrails
-from enhanced_app import app
-
-# POST /chat with guardrails enabled
-{
-  "message": "What is our remote work policy?",
-  "enable_guardrails": true,
-  "include_sources": true
-}
-
-# Response includes guardrails metadata
-{
-  "status": "success",
-  "message": "...",
-  "guardrails": {
-    "approved": true,
-    "confidence": 0.85,
-    "safety_passed": true,
-    "quality_score": 0.8
-  }
-}
-```
-
-## 📊 Performance Characteristics
-
-- **Validation Time**: ~0.001-0.01 seconds per response
-- **Memory Usage**: Minimal overhead, pattern-based processing
-- **Scalability**: Stateless design, horizontally scalable
-- **Reliability**: Circuit breaker patterns prevent cascade failures
-
-## 🔄 Future Enhancements
-
-While all Issue #24 requirements are met, potential future improvements include:
-
-1. **Machine Learning Integration**: Replace pattern-based detection with ML models
-2. **Advanced Metrics**: Custom quality metrics for specific domains
-3. **Real-time Monitoring**: Integration with monitoring systems
-4. **A/B Testing**: Framework for testing different validation strategies
-
-## 📁 File Structure
-
-```
-src/
-├── guardrails/
-│   ├── __init__.py                # Package exports
-│   ├── guardrails_system.py       # Main orchestrator
-│   ├── response_validator.py      # Quality and safety validation
-│   ├── source_attribution.py      # Citation generation
-│   ├── content_filters.py         # Safety filtering
-│   ├── quality_metrics.py         # Quality assessment
-│   └── error_handlers.py          # Error handling
-├── rag/
-│   └── enhanced_rag_pipeline.py   # Integration layer
-tests/
-├── test_guardrails/
-│   ├── test_guardrails_system.py  # Core system tests
-│   └── test_enhanced_rag_pipeline.py  # Integration tests
-└── test_enhanced_app_guardrails.py    # API tests
-enhanced_app.py                     # Demo Flask app
-```
-
-## ✅ Acceptance Criteria Validation
-
-| Requirement | Status | Implementation |
-|-------------|--------|----------------|
-| Content safety filtering | ✅ COMPLETE | ContentFilter with PII, bias, inappropriate content detection |
-| Response quality scoring | ✅ COMPLETE | QualityMetrics with multi-dimensional assessment |
-| Source attribution | ✅ COMPLETE | SourceAttributor with citation generation and validation |
-| Error handling | ✅ COMPLETE | ErrorHandler with circuit breakers and graceful degradation |
-| Configuration | ✅ COMPLETE | Flexible configuration system for all components |
-| Testing | ✅ COMPLETE | 13 comprehensive tests with 100% pass rate |
-| Documentation | ✅ COMPLETE | Full docstrings and implementation summary |
-
-## 🎉 Conclusion
-
-Issue #24 has been successfully completed with a production-ready guardrails system that exceeds the specified requirements. The implementation provides:
-
-- **Enterprise-grade safety**: Comprehensive content filtering and validation
-- **Quality assurance**: Multi-dimensional quality assessment with recommendations
-- **Seamless integration**: Backward-compatible enhancement of existing RAG pipeline
-- **Production readiness**: Robust error handling, monitoring, and configuration
-- **Extensibility**: Modular design enabling future enhancements
-
-The guardrails system is now ready for production deployment and will significantly enhance the safety, quality, and reliability of RAG responses in the corporate policy application.

QUERY_EXPANSION_IMPLEMENTATION_SUMMARY.md

@@ -1,76 +0,0 @@
-# Query Expansion Implementation Summary
-
-## Overview
-Successfully implemented natural language query expansion to bridge the gap between employee terminology and HR document language, dramatically improving semantic search quality for intuitive queries.
-
-## Problem Solved
-**Before**: Employee queries using natural language failed to retrieve relevant content
-- ❌ "How much personal time do I earn each year?" → 0 context, no answer
-- ❌ "What's my vacation allowance?" → Failed to match document terminology
-
-**After**: Natural language queries successfully retrieve relevant policy information
-- ✅ "How much personal time do I earn each year?" → 2960 characters context, proper PTO policy answer
-- ✅ "What health insurance options do I have?" → 3055 characters context, benefits guide content
-
-## Technical Implementation
-
-### Core Components
-
-1. **QueryExpander Class** (`src/search/query_expander.py`)
-   - Comprehensive HR terminology synonym mappings
-   - Pattern-based query enhancement
-   - Domain-specific term expansion
-
-2. **SearchService Integration** (`src/search/search_service.py`)
-   - Optional query expansion with `enable_query_expansion` parameter
-   - Expansion occurs before embedding generation
-   - Maintains original query intent while adding synonyms
-
-3. **Synonym Database**
-   - 100+ mapped relationships across HR domains
-   - Time off, benefits, remote work, career development, safety, expenses
-   - Bidirectional mapping for comprehensive coverage
-
-### Key Synonym Mappings
-- **Time Off**: "personal time" ↔ "PTO", "paid time off", "vacation", "accrual", "leave"
-- **Benefits**: "health insurance" ↔ "healthcare", "medical", "coverage", "benefits"
-- **Remote Work**: "work from home" ↔ "remote work", "telecommuting", "WFH", "telework"
-- **Career**: "promotion" ↔ "advancement", "career growth", "progression"
-- **Safety**: "harassment" ↔ "discrimination", "complaint", "workplace issues"
-
-## Results & Impact
-
-### Performance Metrics
-- **Query Success Rate**: Significant improvement for natural language queries
-- **Response Quality**: Maintained high precision while improving recall
-- **Latency Impact**: Minimal (~10ms additional processing)
-- **Memory Footprint**: Lightweight implementation (< 1MB)
-
-### User Experience Enhancement
-- **Natural Language Support**: Employees can ask questions using intuitive terminology
-- **Reduced Friction**: No need to learn specific HR terminology
-- **Broader Coverage**: Handles various ways of expressing the same concepts
-- **Consistent Results**: Reliable retrieval across synonym variations
-
-## Validation Testing
-Comprehensive testing demonstrated improvement across key categories:
-- ✅ Time Off & Leave policies
-- ✅ Benefits & healthcare information
-- ✅ Remote work guidelines
-- ✅ Career development policies
-- ✅ Safety & compliance procedures
-- ✅ Expense & travel policies
-
-## Future Enhancements
-- Monitor real-world query patterns for additional synonym opportunities
-- Context-aware expansion based on document types
-- Integration with external HR terminology databases
-- Machine learning-based synonym discovery
-
-## Files Modified
-- **NEW**: `src/search/query_expander.py` - Core expansion logic
-- **UPDATED**: `src/search/search_service.py` - Integration layer
-- **UPDATED**: `.gitignore` - Test directory exclusion
-- **DOCUMENTATION**: README.md, CHANGELOG.md updates
-
-This implementation represents a significant enhancement to the RAG system's natural language understanding capabilities, making it more user-friendly and accessible for employee self-service HR queries.

run.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 set -e
 
-# Default values
-WORKERS_VALUE="${WORKERS:-4}"
+# Default to 1 worker to prevent OOM on low-memory hosts
+WORKERS_VALUE="${WORKERS:-1}"
 TIMEOUT_VALUE="${TIMEOUT:-120}"
 PORT_VALUE="${PORT:-10000}"