feat(config): make compile concurrency configurable (closes #173)

Concept/entity generation ran at a hardcoded concurrency of 5
(DEFAULT_COMPILE_CONCURRENCY) with no way to lower it when the LLM provider
rate-limits. Add a `compile_concurrency` config key (default 5) and thread it
through every add / recompile / cloud-import compile call via a shared
`_compile_concurrency` resolver (null / non-positive → the compiler default).

Pairs with `pageindex_max_concurrency` (indexing side) from this PR — both
concurrency knobs are now KB-configurable.

Author: KylinMountain

openkb/cli.py

@@ -47,7 +47,7 @@ def filter(self, record: logging.LogRecord) -> bool:
 litellm.suppress_debug_info = True
 from dotenv import load_dotenv
 
-from openkb.agent.compiler import compile_long_doc
+from openkb.agent.compiler import DEFAULT_COMPILE_CONCURRENCY, compile_long_doc
 from openkb.config import (
     DEFAULT_CONFIG,
     load_config,
@@ -439,6 +439,19 @@ def _run_compile_with_retry(coro_factory, label: str) -> None:
                 raise
 
 
+def _compile_concurrency(config: dict) -> int:
+    """Concurrency cap for the compile step (concept/entity generation).
+
+    Configurable per KB via ``compile_concurrency`` in config.yaml; a missing,
+    null, or non-positive value falls back to the compiler's built-in default.
+    Lower it when the LLM provider rate-limits.
+    """
+    value = config.get("compile_concurrency")
+    if isinstance(value, int) and value > 0:
+        return value
+    return DEFAULT_COMPILE_CONCURRENCY
+
+
 def add_single_file(
     file_path: Path, kb_dir: Path, *, stage: bool = True
 ) -> Literal["added", "skipped", "failed"]:
@@ -564,6 +577,7 @@ def _add_single_file_locked(
                     kb_dir,
                     model,
                     doc_description=index_result.description,
+                    max_concurrency=_compile_concurrency(config),
                 ),
                 label=f"Compiling long doc (doc_id={index_result.doc_id})",
             )
@@ -572,7 +586,13 @@ def _add_single_file_locked(
                 raise RuntimeError(f"Converted document has no source artifact: {file_path.name}")
             source_path = result.source_path
             _run_compile_with_retry(
-                lambda: compile_short_doc(doc_name, source_path, kb_dir, model),
+                lambda: compile_short_doc(
+                    doc_name,
+                    source_path,
+                    kb_dir,
+                    model,
+                    max_concurrency=_compile_concurrency(config),
+                ),
                 label="Compiling short doc",
             )
 
@@ -699,6 +719,7 @@ def import_from_pageindex_cloud(doc_id: str, kb_dir: Path) -> Literal["added", "
                 kb_dir,
                 model,
                 doc_description=cloud.description,
+                max_concurrency=_compile_concurrency(config),
             ),
             label=f"Compiling imported doc (doc_id={doc_id})",
         )
@@ -1679,7 +1700,16 @@ def _classify(meta: dict) -> str:
             click.echo(f"[{i}/{total}] Recompiling long doc {name}...")
             start = time.time()
             try:
-                asyncio.run(compiler.compile_long_doc(name, summary_path, doc_id, kb_dir, model))
+                asyncio.run(
+                    compiler.compile_long_doc(
+                        name,
+                        summary_path,
+                        doc_id,
+                        kb_dir,
+                        model,
+                        max_concurrency=_compile_concurrency(config),
+                    )
+                )
             except Exception as exc:
                 click.echo(f"  [ERROR] Compilation failed: {exc}")
                 logging.getLogger(__name__).debug("Recompile traceback:", exc_info=True)
@@ -1699,7 +1729,15 @@ def _classify(meta: dict) -> str:
             click.echo(f"[{i}/{total}] Recompiling short doc {name}...")
             start = time.time()
             try:
-                asyncio.run(compiler.compile_short_doc(name, source_path, kb_dir, model))
+                asyncio.run(
+                    compiler.compile_short_doc(
+                        name,
+                        source_path,
+                        kb_dir,
+                        model,
+                        max_concurrency=_compile_concurrency(config),
+                    )
+                )
             except Exception as exc:
                 click.echo(f"  [ERROR] Compilation failed: {exc}")
                 logging.getLogger(__name__).debug("Recompile traceback:", exc_info=True)

openkb/config.py

@@ -21,6 +21,9 @@
     # document. None = let PageIndex apply its own default. Raise it to index
     # faster, lower it if you hit provider rate limits or "too many open files".
     "pageindex_max_concurrency": None,
+    # Cap on concurrent compile LLM calls OpenKB makes when generating concept
+    # and entity pages. Lower it if your LLM provider rate-limits.
+    "compile_concurrency": 5,
 }
 
 # Default entity-type vocabulary. Overridable per-KB via the optional

tests/test_add_command.py

@@ -97,6 +97,39 @@ def test_add_single_file_compile_failure_rolls_back_converted_artifacts(self, tm
         assert not (kb_dir / "wiki" / "sources" / "notes.md").exists()
         assert HashRegistry(kb_dir / ".openkb" / "hashes.json").all_entries() == {}
 
+    def test_compile_concurrency_resolution(self):
+        from openkb.agent.compiler import DEFAULT_COMPILE_CONCURRENCY
+        from openkb.cli import _compile_concurrency
+
+        assert _compile_concurrency({}) == DEFAULT_COMPILE_CONCURRENCY
+        assert _compile_concurrency({"compile_concurrency": 3}) == 3
+        # None / non-positive / non-int fall back to the compiler default.
+        assert _compile_concurrency({"compile_concurrency": None}) == DEFAULT_COMPILE_CONCURRENCY
+        assert _compile_concurrency({"compile_concurrency": 0}) == DEFAULT_COMPILE_CONCURRENCY
+
+    def test_add_forwards_compile_concurrency_from_config(self, tmp_path):
+        from unittest.mock import AsyncMock
+
+        from openkb.cli import add_single_file
+
+        kb_dir = self._setup_kb(tmp_path)
+        (kb_dir / ".openkb" / "config.yaml").write_text(
+            "model: gpt-4o-mini\ncompile_concurrency: 3\n", encoding="utf-8"
+        )
+        doc = tmp_path / "notes.md"
+        doc.write_text("# Notes\n\nBody", encoding="utf-8")
+
+        with (
+            patch(
+                "openkb.agent.compiler.compile_short_doc", new_callable=AsyncMock
+            ) as mock_compile,
+            patch("openkb.cli._setup_llm_key"),
+        ):
+            outcome = add_single_file(doc, kb_dir)
+
+        assert outcome == "added"
+        assert mock_compile.call_args.kwargs["max_concurrency"] == 3
+
     def _long_doc_conv(self, kb_dir, name, file_hash):
         from openkb.converter import ConvertResult
 

tests/test_config.py

@@ -36,6 +36,16 @@ def test_load_pageindex_max_concurrency_override(tmp_path):
     assert load_config(config_path)["pageindex_max_concurrency"] == 12
 
 
+def test_compile_concurrency_defaults_to_5():
+    assert DEFAULT_CONFIG["compile_concurrency"] == 5
+
+
+def test_load_compile_concurrency_override(tmp_path):
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text("compile_concurrency: 3\n", encoding="utf-8")
+    assert load_config(config_path)["compile_concurrency"] == 3
+
+
 def test_load_missing_file_returns_defaults(tmp_path):
     missing = tmp_path / "nonexistent" / "config.yaml"
     config = load_config(missing)