Refact: Implement Lazy Configuration Initialization for API Server

[danielaskdd]

Refact: Implement Lazy Configuration Initialization for API Server

Overview

This PR introduces a lazy initialization pattern for the LightRAG API server configuration, improving flexibility for programmatic usage while maintaining full backward compatibility with existing code.

Motivation

Previously, the API server configuration was initialized eagerly at module import time, which:

• Made it difficult to embed LightRAG programmatically in other applications
• Limited flexibility for testing and custom configurations
• Required command-line arguments even when used as a library

Changes

Core Implementation

• Lazy Configuration Pattern (lightrag/api/config.py)
  • Added initialize_config() function for explicit initialization control
  • Added get_config() function for lazy auto-initialization
  • Implemented _GlobalArgsProxy class to maintain backward compatibility
  • Configuration initializes on first access if not explicitly initialized

API Integration

• Entry Points (lightrag/api/lightrag_server.py, lightrag/api/run_with_gunicorn.py)
  • Added explicit initialize_config() calls in main() functions
  • Ensures configuration is ready before server starts
  • Clear intent for configuration initialization timing

Dependencies

• Production Server (pyproject.toml)
  • Added gunicorn to API dependencies for production-ready WSGI server support

Lock File

• Updated uv.lock to reflect new dependency

Benefits

1. Backward Compatibility: Existing code using from config import global_args continues to work without changes

2. Programmatic Usage: Applications can now initialize LightRAG with custom configurations:

   from lightrag.api.config import initialize_config
   import argparse
   
   custom_config = argparse.Namespace(
       host='localhost',
       port=8080,
       working_dir='./custom_rag'
   )
   initialize_config(custom_config)

3. Testing Flexibility: Tests can now initialize with specific configurations without relying on command-line arguments

4. Control Over Timing: Applications can control exactly when configuration initialization occurs

Technical Details

The implementation uses a proxy pattern:

• _GlobalArgsProxy intercepts attribute access to the global configuration
• First access triggers automatic initialization via parse_args()
• Subsequent accesses use the cached configuration
• Explicit initialize_config() allows pre-initialization with custom values

Testing

• Maintains backward compatibility with all existing usage patterns
• Supports new programmatic initialization patterns
• No breaking changes to existing API or behavior

[danielaskdd]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".