chore(config): dedup CONFIG_PATH + fix misleading legacy labels

src/graphstore/config.py

@@ -344,42 +344,40 @@ def apply_env_overrides(config: GraphStoreConfig) -> GraphStoreConfig:
 
 
 def merge_kwargs(config: GraphStoreConfig, **kwargs) -> GraphStoreConfig:
-    """Override config fields from constructor kwargs.
+    """Override config fields from GraphStore(...) constructor kwargs.
 
-    Supports flat shortcuts for common tuning knobs:
-        ceiling_mb, eviction_target_ratio, remember_weights, recall_decay,
-        search_oversample, similarity_threshold, duplicate_threshold, fts_tokenizer
+    Two shapes of kwargs are accepted:
 
-    Plus legacy kwargs: embedder, ingest_root, vault, retention (dict).
+    1. Flat shortcuts for tuning knobs (see _KWARG_SHORTCUTS), e.g.
+       ceiling_mb, remember_weights, recall_decay, search_oversample.
+    2. Top-level convenience kwargs that map to multi-field config
+       updates: embedder, ingest_root, vault, retention (dict).
+       These are the primary public API - GraphStore(embedder=...) is
+       how users construct the store.
     """
     updates: dict[str, dict[str, object]] = {}
 
-    # Flat shortcuts -> section overrides
     for kwarg_name, (section, field) in _KWARG_SHORTCUTS.items():
         if kwarg_name in kwargs:
             val = kwargs[kwarg_name]
             current_val = getattr(getattr(config, section), field)
             if val != current_val:
                 updates.setdefault(section, {})[field] = val
 
-    # Legacy: embedder (string or object -> vector.embedder name)
     if "embedder" in kwargs:
         emb = kwargs["embedder"]
         emb_name = emb if isinstance(emb, str) else "custom"
         if emb is None:
             emb_name = "none"
         updates.setdefault("vector", {})["embedder"] = emb_name
 
-    # Legacy: ingest_root -> server.ingest_root
     if "ingest_root" in kwargs and kwargs["ingest_root"] is not None:
         updates.setdefault("server", {})["ingest_root"] = kwargs["ingest_root"]
 
-    # Legacy: vault -> vault.enabled + vault.path
     if "vault" in kwargs and kwargs["vault"] is not None:
         updates.setdefault("vault", {})["enabled"] = True
         updates["vault"]["path"] = kwargs["vault"]
 
-    # Legacy: retention (dict)
     if "retention" in kwargs and kwargs["retention"] is not None:
         r = kwargs["retention"]
         for key in ("blob_warm_days", "blob_archive_days", "blob_delete_days"):

src/graphstore/store.py

@@ -130,8 +130,8 @@ def __init__(self, path: str | None = None, ceiling_mb=_UNSET,
 
         # Layer 4: constructor kwargs (highest priority). Every kwarg listed
         # here must also appear in config._KWARG_SHORTCUTS or be one of the
-        # legacy keys (embedder, ingest_root, vault, retention, auto_optimize,
-        # enable_wal) that merge_kwargs handles separately.
+        # top-level convenience keys (embedder, ingest_root, vault, retention,
+        # auto_optimize, enable_wal) that merge_kwargs handles separately.
         _kwarg_names = (
             "ceiling_mb", "embedder", "ingest_root", "vault", "retention",
             "remember_weights", "recall_decay", "search_oversample",

tools/autoresearch/providers.py

@@ -10,12 +10,18 @@
 import os
 from pathlib import Path
 
-_CONFIG_PATH = Path(__file__).resolve().parent / "config.json"
+CONFIG_PATH = Path(__file__).resolve().parent / "config.json"
 
 
 def load_config() -> dict:
-    if _CONFIG_PATH.exists():
-        return json.loads(_CONFIG_PATH.read_text())
+    """One-shot read of config.json. No caching, no migration.
+
+    Use when you want the providers section now. For the long-running
+    autoresearch loop use run_loop.load_config which caches + applies
+    schema migration.
+    """
+    if CONFIG_PATH.exists():
+        return json.loads(CONFIG_PATH.read_text())
     return {}
 
 

tools/autoresearch/run_loop.py

@@ -33,7 +33,7 @@
 REPO_ROOT = Path(__file__).resolve().parent.parent.parent
 ALGO_DIR = REPO_ROOT / "src" / "graphstore" / "algos"
 VENV_PYTHON = REPO_ROOT / ".venv" / "bin" / "python"
-CONFIG_FILE = Path(__file__).resolve().parent / "config.json"
+from tools.autoresearch.providers import CONFIG_PATH as CONFIG_FILE
 PROGRAM_FILE = Path(__file__).resolve().parent / "program.md"
 
 _current_algo: str = ""