feat: Implement centralized configuration system for HiRAG

[dev-mirzabicer]

• Create comprehensive centralized configuration module (hirag/config.py)

  • Hierarchical configuration structure with 7 logical groups
  • Type-safe configuration classes with validation and defaults
  • Environment variable overrides support (15+ env vars)
  • Backward compatibility with legacy configuration format

• Add comprehensive configuration template (hirag_config.yaml)

  • Centralize all 70+ configuration parameters
  • Clear documentation for each configuration section
  • Legacy compatibility section for smooth migration

• Update core modules to use centralized configuration:

  • hirag.py: Add factory methods for config-based initialization
  • _cluster_utils.py: Replace hardcoded clustering parameters
  • _op.py: Update text processing and performance settings
  • prompt.py: Centralize prompt delimiter constants

• Benefits delivered:

  • Single source of truth for all configuration
  • Environment variable support for deployment flexibility
  • Type safety with full validation
  • Backward compatibility maintained
  • Easy parameter tuning without code changes

Resolves #17

[claude]

Claude finished @dev-mirzabicer's task —— View job

---

Code Review Complete ✅

I've conducted a comprehensive review of the centralized configuration system implementation. Here's my detailed analysis:

Review Tasks

• Analyze new configuration architecture (config.py)
• Review configuration template (hirag_config.yaml)
• Check integration with existing modules
• Evaluate type safety and validation
• Assess environment variable handling
• Check backward compatibility approach
• Identify potential bugs and security issues
• Review performance considerations
• Assess test coverage needs

Overall Assessment: Strong Implementation 🌟

This is a well-architected centralized configuration system that significantly improves the codebase organization. The implementation demonstrates good software engineering practices with type safety, validation, and backward compatibility.

---

🟢 Strengths

1. Architecture & Design

• Excellent hierarchical organization: 7 logical configuration groups make settings discoverable and maintainable
• Type-safe dataclasses: Proper use of type hints with StrOrNone, IntOrNone etc.
• Clean separation of concerns: Each config class has a single responsibility
• Factory pattern implementation: Multiple initialization methods (from_config(), from_config_manager(), from_config_dict())

2. Configuration Management

• Comprehensive parameter coverage: Successfully consolidates 70+ parameters from across the codebase
• Smart file discovery: _find_config_file() checks multiple standard locations
• Graceful fallback: System continues with defaults if config file is missing or invalid
• Environment variable support: 15+ environment variables with automatic type conversion

3. Backward Compatibility

• Legacy mapping: get_legacy_config_dict() maintains compatibility with existing code
• Dual configuration support: YAML file includes both new and legacy sections
• Migration path: Clear path for gradual adoption without breaking changes

4. Integration Quality

• Consistent usage patterns: Updated modules use consistent get_*_config() imports
• Centralized constants: Prompt delimiters moved from hardcoded to configurable
• Non-breaking changes: Existing code continues to work while gaining configuration benefits

---

🟡 Areas for Improvement

1. Error Handling & Validation (Medium Priority)

Issue: Limited validation scope

# config.py:403-418 - Only basic validations
def _validate_config(self):
    if self.config.text_processing.chunk_token_size <= 0:
        raise ValueError("chunk_token_size must be positive")
    # Missing validation for many other parameters

Recommendations:

• Add validation for all threshold values (0-1 ranges)
• Validate that batch sizes are reasonable (not 0 or extremely large)
• Check that directory paths are valid
• Validate API endpoints format

2. Type Safety Enhancements (Low Priority)

Issue: Environment variable type conversion could be more robust

# config.py:391-401 - Basic type conversion
if isinstance(current_value, bool):
    value = value.lower() in ('true', '1', 'yes', 'on')
elif isinstance(current_value, int):
    value = int(value)  # Could raise ValueError

Recommendations:

• Add try-catch around type conversions
• Provide better error messages for invalid environment variable values
• Consider using a validation library like pydantic for more robust type checking

3. Configuration Consistency (Low Priority)

Issue: Some parameter names have inconsistencies

# config.py:244 - Typo in legacy compatibility
'enable_hierachical_mode': self.config.system_behavior.enable_hierarchical_mode,

Recommendations:

• Fix the typo: hierachical → hierarchical
• Ensure consistent naming conventions across all parameters
• Add a deprecation warning for the misspelled legacy parameter

4. Performance Considerations (Low Priority)

Issue: Configuration loading happens on every get_*_config() call

# config.py:542-544
def get_api_config() -> APIConfig:
    return get_config().api  # Loads global config every time

Recommendations:

• Configuration is already cached via global _config_manager, so this is actually efficient
• Consider adding docstrings to clarify that caching is handled internally

---

🔒 Security Assessment

✅ Secure Implementation:

• API keys properly handled via environment variables
• No hardcoded secrets in configuration files
• Placeholder values ("***") used in YAML template
• Configuration validation prevents obvious misconfigurations

No security concerns identified.

---

🚀 Performance Assessment

✅ Good Performance Characteristics:

• Singleton pattern for configuration manager prevents repeated loading
• Lazy loading of configuration files
• Environment variable caching
• No expensive operations in configuration access

Minor optimization opportunity: The try-except block in prompt.py:15-26 could be avoided by ensuring the config system is always available, but current approach is safe.

---

🧪 Test Coverage Assessment

❌ Missing Test Coverage (Needs Attention):

The PR doesn't include tests for the new configuration system. Recommended test cases:

1. Configuration Loading Tests:

   def test_config_loads_from_yaml()
   def test_config_uses_defaults_when_file_missing()
   def test_config_handles_malformed_yaml()

2. Environment Variable Tests:

   def test_env_var_overrides_config_values()
   def test_env_var_type_conversion()
   def test_invalid_env_var_values_handled_gracefully()

3. Backward Compatibility Tests:

   def test_legacy_config_dict_mapping()
   def test_hirag_from_config_equals_traditional_init()

4. Validation Tests:

   def test_invalid_config_values_raise_errors()
   def test_threshold_values_validated()

---

🐛 Potential Bugs Identified

Bug 1: Typo in Legacy Compatibility

# config.py:334 - Bug: wrong parameter name
if 'enable_hierachical_mode' in hirag_data:
    config.system_behavior.enable_hierarchical_mode = hirag_data['enable_hierachical_mode']

Impact: Low - legacy configs with the misspelled parameter won't work
Fix: Support both spellings for backward compatibility

Bug 2: Environment Variable Type Conversion

# config.py:397 - Potential ValueError not caught
elif isinstance(current_value, int):
    value = int(value)  # Could raise ValueError for invalid strings

Impact: Medium - invalid environment variables crash the system
Fix: Add try-catch with meaningful error messages

---

📋 Recommendations Summary

High Priority:

1. Add comprehensive tests for the configuration system
2. Fix the typo in enable_hierachical_mode

Medium Priority:

3. Improve error handling for environment variable type conversion
4. Expand validation to cover more configuration parameters

Low Priority:

5. Add docstring clarifications about caching behavior
6. Consider migration to pydantic for enhanced type validation in future iterations

---

✅ Final Verdict

This is a high-quality implementation that significantly improves the HiRAG codebase. The centralized configuration system is well-designed, maintains backward compatibility, and provides a solid foundation for future development.

Recommendation: Approve with minor revisions

The identified issues are minor and don't block the core functionality. The benefits of centralized configuration far outweigh the small improvements needed.

---