refactor: Pydantic IndexConfig, bool flags, early API key validation

- Replace ConfigLoader + config.yaml with Pydantic IndexConfig
- Use bool for config flags (if_add_node_summary etc.) instead of "yes"/"no"
- Enable doc_description by default for better agent QA
- Early API key validation on LocalClient init via litellm provider detection
- Expose index_config parameter on LocalClient for advanced users
- Remove config.yaml dependency from pip package

Author: KylinMountain

pageindex/client.py

@@ -1,9 +1,8 @@
 # pageindex/client.py
 from __future__ import annotations
-import os
 from pathlib import Path
 from .collection import Collection
-from .config import ConfigLoader
+from .config import IndexConfig
 from .parser.protocol import DocumentParser
 
 
@@ -42,17 +41,51 @@ def _init_cloud(self, api_key: str):
         from .backend.cloud import CloudBackend
         self._backend = CloudBackend(api_key=api_key)
 
-    def _init_local(self, model: str = None, retrieve_model: str = None,
-                    storage_path: str = None, storage=None):
-        if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
-            os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
+    @staticmethod
+    def _check_llm_api_key(model: str) -> None:
+        """Verify that the LLM provider's API key is configured."""
+        import os
+        try:
+            import litellm
+            _, provider, _, _ = litellm.get_llm_provider(model=model)
+        except Exception:
+            return  # Can't resolve provider — let litellm fail later with details
+
+        provider_env = {
+            "openai": "OPENAI_API_KEY",
+            "anthropic": "ANTHROPIC_API_KEY",
+            "azure": "AZURE_API_KEY",
+            "cohere": "COHERE_API_KEY",
+            "replicate": "REPLICATE_API_KEY",
+            "huggingface": "HUGGINGFACE_API_KEY",
+        }
+        env_var = provider_env.get(provider)
+        if env_var and not os.getenv(env_var):
+            from .errors import PageIndexError
+            raise PageIndexError(
+                f"API key not found. Set the {env_var} environment variable "
+                f"for provider '{provider}' (model: {model})."
+            )
 
+    def _init_local(self, model: str = None, retrieve_model: str = None,
+                    storage_path: str = None, storage=None,
+                    index_config: IndexConfig | dict = None):
+        # Build IndexConfig: merge model/retrieve_model with index_config
         overrides = {}
         if model:
             overrides["model"] = model
         if retrieve_model:
             overrides["retrieve_model"] = retrieve_model
-        opt = ConfigLoader().load(overrides or None)
+        if isinstance(index_config, IndexConfig):
+            opt = index_config.model_copy(update=overrides)
+        elif isinstance(index_config, dict):
+            overrides.update(index_config)
+            opt = IndexConfig(**overrides)
+        else:
+            opt = IndexConfig(**overrides) if overrides else IndexConfig()
+
+        # Early validation: check API key before any expensive operations
+        self._check_llm_api_key(opt.model)
 
         storage_path = Path(storage_path or "~/.pageindex").expanduser()
         storage_path.mkdir(parents=True, exist_ok=True)
@@ -65,6 +98,7 @@ def _init_local(self, model: str = None, retrieve_model: str = None,
             files_dir=str(storage_path / "files"),
             model=opt.model,
             retrieve_model=_normalize_retrieve_model(opt.retrieve_model or opt.model),
+            index_config=opt,
         )
 
     def collection(self, name: str = "default") -> Collection:
@@ -87,11 +121,33 @@ def register_parser(self, parser: DocumentParser) -> None:
 
 
 class LocalClient(PageIndexClient):
-    """Local mode — indexes and queries documents on your machine."""
+    """Local mode — indexes and queries documents on your machine.
+
+    Args:
+        model: LLM model for indexing (default: gpt-4o-2024-11-20)
+        retrieve_model: LLM model for agent QA (default: same as model)
+        storage_path: Directory for SQLite DB and files (default: ~/.pageindex)
+        storage: Custom StorageEngine instance (default: SQLiteStorage)
+        index_config: Advanced indexing parameters. Pass an IndexConfig instance
+            or a dict. All fields have sensible defaults — most users don't need this.
+
+    Example::
+
+        # Simple — defaults are fine
+        client = LocalClient(model="gpt-5.4")
+
+        # Advanced — tune indexing parameters
+        from pageindex.config import IndexConfig
+        client = LocalClient(
+            model="gpt-5.4",
+            index_config=IndexConfig(toc_check_page_num=30),
+        )
+    """
 
     def __init__(self, model: str = None, retrieve_model: str = None,
-                 storage_path: str = None, storage=None):
-        self._init_local(model, retrieve_model, storage_path, storage)
+                 storage_path: str = None, storage=None,
+                 index_config: IndexConfig | dict = None):
+        self._init_local(model, retrieve_model, storage_path, storage, index_config)
 
 
 class CloudClient(PageIndexClient):

pageindex/config.py

@@ -1,37 +1,22 @@
 # pageindex/config.py
-import yaml
-from pathlib import Path
-from types import SimpleNamespace
+from __future__ import annotations
+from pydantic import BaseModel
 
 
-_DEFAULT_CONFIG_PATH = Path(__file__).parent / "config.yaml"
+class IndexConfig(BaseModel):
+    """Configuration for the PageIndex indexing pipeline.
 
+    All fields have sensible defaults. Advanced users can override
+    via LocalClient(index_config=IndexConfig(...)) or a dict.
+    """
+    model_config = {"extra": "forbid"}
 
-class ConfigLoader:
-    def __init__(self, default_path: str = None):
-        if default_path is None:
-            default_path = _DEFAULT_CONFIG_PATH
-        self._default_dict = self._load_yaml(default_path)
-
-    @staticmethod
-    def _load_yaml(path):
-        with open(path, "r", encoding="utf-8") as f:
-            return yaml.safe_load(f) or {}
-
-    def _validate_keys(self, user_dict):
-        unknown_keys = set(user_dict) - set(self._default_dict)
-        if unknown_keys:
-            raise ValueError(f"Unknown config keys: {unknown_keys}")
-
-    def load(self, user_opt=None) -> SimpleNamespace:
-        if user_opt is None:
-            user_dict = {}
-        elif isinstance(user_opt, SimpleNamespace):
-            user_dict = vars(user_opt)
-        elif isinstance(user_opt, dict):
-            user_dict = user_opt
-        else:
-            raise TypeError("user_opt must be dict, SimpleNamespace or None")
-        self._validate_keys(user_dict)
-        merged = {**self._default_dict, **user_dict}
-        return SimpleNamespace(**merged)
+    model: str = "gpt-4o-2024-11-20"
+    retrieve_model: str | None = None
+    toc_check_page_num: int = 20
+    max_page_num_each_node: int = 10
+    max_token_num_each_node: int = 20000
+    if_add_node_id: bool = True
+    if_add_node_summary: bool = True
+    if_add_doc_description: bool = True
+    if_add_node_text: bool = False

pageindex/config.yaml

@@ -1081,17 +1081,17 @@ def page_index_main(doc, opt=None):
 
     async def page_index_builder():
         structure = await tree_parser(page_list, opt, doc=doc, logger=logger)
-        if opt.if_add_node_id == 'yes':
-            write_node_id(structure)    
-        if opt.if_add_node_text == 'yes':
+        if opt.if_add_node_id:
+            write_node_id(structure)
+        if opt.if_add_node_text:
             add_node_text(structure, page_list)
-        if opt.if_add_node_summary == 'yes':
-            if opt.if_add_node_text == 'no':
+        if opt.if_add_node_summary:
+            if not opt.if_add_node_text:
                 add_node_text(structure, page_list)
             await generate_summaries_for_structure(structure, model=opt.model)
-            if opt.if_add_node_text == 'no':
+            if not opt.if_add_node_text:
                 remove_structure_text(structure)
-            if opt.if_add_doc_description == 'yes':
+            if opt.if_add_doc_description:
                 # Create a clean structure without unnecessary fields for description generation
                 clean_structure = create_clean_structure_for_description(structure)
                 doc_description = generate_doc_description(clean_structure, model=opt.model)

pageindex/index/page_index.py

@@ -240,7 +240,7 @@ def clean_tree_for_output(tree_nodes):
     return cleaned_nodes
 
 
-async def md_to_tree(md_path, if_thinning=False, min_token_threshold=None, if_add_node_summary='no', summary_token_threshold=None, model=None, if_add_doc_description='no', if_add_node_text='no', if_add_node_id='yes'):
+async def md_to_tree(md_path, if_thinning=False, min_token_threshold=None, if_add_node_summary=False, summary_token_threshold=None, model=None, if_add_doc_description=False, if_add_node_text=False, if_add_node_id=True):
     with open(md_path, 'r', encoding='utf-8') as f:
         markdown_content = f.read()
     line_count = markdown_content.count('\n') + 1
@@ -259,25 +259,24 @@ async def md_to_tree(md_path, if_thinning=False, min_token_threshold=None, if_ad
     print(f"Building tree from nodes...")
     tree_structure = build_tree_from_nodes(nodes_with_content)
 
-    if if_add_node_id == 'yes':
+    if if_add_node_id:
         write_node_id(tree_structure)
 
     print(f"Formatting tree structure...")
-    
-    if if_add_node_summary == 'yes':
+
+    if if_add_node_summary:
         # Always include text for summary generation
         tree_structure = format_structure(tree_structure, order = ['title', 'node_id', 'line_num', 'summary', 'prefix_summary', 'text', 'nodes'])
-        
+
         print(f"Generating summaries for each node...")
         tree_structure = await generate_summaries_for_structure_md(tree_structure, summary_token_threshold=summary_token_threshold, model=model)
-        
-        if if_add_node_text == 'no':
+
+        if not if_add_node_text:
             # Remove text after summary generation if not requested
             tree_structure = format_structure(tree_structure, order = ['title', 'node_id', 'line_num', 'summary', 'prefix_summary', 'nodes'])
-        
-        if if_add_doc_description == 'yes':
+
+        if if_add_doc_description:
             print(f"Generating document description...")
-            # Create a clean structure without unnecessary fields for description generation
             clean_structure = create_clean_structure_for_description(tree_structure)
             doc_description = generate_doc_description(clean_structure, model=model)
             return {
@@ -288,7 +287,7 @@ async def md_to_tree(md_path, if_thinning=False, min_token_threshold=None, if_ad
             }
     else:
         # No summaries needed, format based on text preference
-        if if_add_node_text == 'yes':
+        if if_add_node_text:
             tree_structure = format_structure(tree_structure, order = ['title', 'node_id', 'line_num', 'summary', 'prefix_summary', 'text', 'nodes'])
         else:
             tree_structure = format_structure(tree_structure, order = ['title', 'node_id', 'line_num', 'summary', 'prefix_summary', 'nodes'])

pageindex/index/page_index_md.py

@@ -58,10 +58,10 @@ def build_index(parsed: ParsedDocument, model: str = None, opt=None) -> dict:
     from .utils import (write_node_id, add_node_text, remove_structure_text,
                         generate_summaries_for_structure, generate_doc_description,
                         create_clean_structure_for_description)
-    from ..config import ConfigLoader
+    from ..config import IndexConfig
 
     if opt is None:
-        opt = ConfigLoader().load({"model": model} if model else None)
+        opt = IndexConfig(model=model) if model else IndexConfig()
 
     nodes = parsed.nodes
     strategy = detect_strategy(nodes)
@@ -75,26 +75,25 @@ def build_index(parsed: ParsedDocument, model: str = None, opt=None) -> dict:
         structure = _run_async(_content_based_pipeline(page_list, opt))
 
     # Unified enhancement
-    if opt.if_add_node_id == "yes":
+    if opt.if_add_node_id:
         write_node_id(structure)
 
     if strategy != "level_based":
-        # For content-based, add text from page_list (reuse already-computed page_list)
-        if opt.if_add_node_text == "yes" or opt.if_add_node_summary == "yes":
+        if opt.if_add_node_text or opt.if_add_node_summary:
             add_node_text(structure, page_list)
 
-    if opt.if_add_node_summary == "yes":
+    if opt.if_add_node_summary:
         _run_async(generate_summaries_for_structure(structure, model=opt.model))
 
-        if opt.if_add_node_text == "no" and strategy != "level_based":
+        if not opt.if_add_node_text and strategy != "level_based":
             remove_structure_text(structure)
 
     result = {
         "doc_name": parsed.doc_name,
         "structure": structure,
     }
 
-    if opt.if_add_doc_description == "yes":
+    if opt.if_add_doc_description:
         clean_structure = create_clean_structure_for_description(structure)
         result["doc_description"] = generate_doc_description(
             clean_structure, model=opt.model