feat(config): pass through LiteLLM settings via a litellm: config block

Add an optional `litellm:` mapping in .openkb/config.yaml as the single place to
tune LiteLLM. Keys are forwarded to LiteLLM: `timeout` and `extra_headers` apply
per request (the existing per-call mechanism, covering both the compiler and the
agents-SDK paths), and the rest are set as litellm module globals (drop_params,
num_retries, ssl_verify, ...). Resolves the Ollama UnsupportedParamsError in
#137: `litellm: {drop_params: true}` lets LiteLLM drop params a provider rejects
(e.g. parallel_tool_calls on Ollama).

- config.resolve_litellm_settings(): validate the value is a mapping, drop
  non-string keys, pass values through verbatim (the user owns them).
- cli._setup_llm_key(): the `litellm:` block is canonical — when it specifies
  `timeout` / `extra_headers` they route to the per-call stashes and replace the
  legacy top-level keys (an empty `extra_headers: {}` clears, not reverts); the
  rest go to cli._apply_litellm_settings(), which setattrs each onto litellm.
  Guards: skip+warn an unknown key, and refuse to overwrite a litellm function.
  Globals are applied process-wide and not reset.
- Back-compat: the legacy top-level `timeout:` / `extra_headers:` keys still work
  (now undocumented; the `litellm:` block is the documented surface).
- warnings go through the logger (stderr), not click.echo, so a typo can't
  corrupt piped stdout (e.g. `openkb query > out.txt`).
- docs: config.yaml.example consolidated under `litellm:`; README drops the
  now-redundant top-level extra_headers section.

Closes #137

Author: KylinMountain

README.md

@@ -369,19 +369,11 @@ Model names use `provider/model` LiteLLM [format](https://docs.litellm.ai/docs/p
 | Gemini | `gemini/gemini-3.1-pro-preview` |
 
 <details>
-<summary><i>Advanced options (<code>entity_types</code>, <code>extra_headers</code>, OAuth):</i></summary>
+<summary><i>Advanced options (<code>entity_types</code>, OAuth):</i></summary>
 <br>
 
 `entity_types` (optional): a YAML list overriding the entity-type vocabulary used for entity pages; omit it to use the default `person`, `organization`, `place`, `product`, `work`, `event`, `other`.
 
-`extra_headers` (optional): a YAML mapping of extra HTTP headers sent with every LLM request (forwarded to LiteLLM's `extra_headers`). Useful for providers that expect custom headers, e.g. GitHub Copilot IDE-auth headers:
-
-```yaml
-extra_headers:
-  Editor-Version: vscode/1.95.0
-  Copilot-Integration-Id: vscode-chat
-```
-
 Subscription-based providers that authenticate via OAuth device flow (e.g. `chatgpt/*`, `github_copilot/*`) need no API key; OpenKB skips the missing-key warning for them.
 
 </details>

config.yaml.example

@@ -2,13 +2,6 @@ model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 
-# Optional: extra HTTP headers sent with every LLM request (forwarded to
-# LiteLLM's extra_headers). Some providers need these — e.g. GitHub Copilot
-# IDE-auth headers on older litellm versions:
-# extra_headers:
-#   Editor-Version: vscode/1.95.0
-#   Copilot-Integration-Id: vscode-chat
-
 # Optional: override the entity-type vocabulary used for entity pages.
 # Omit this key to use the default 7 types
 # (person, organization, place, product, work, event, other).
@@ -18,6 +11,12 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 #   - dataset
 #   - model
 
-# Optional: per-request LLM timeout in seconds, forwarded to LiteLLM.
-# Defaults to LiteLLM's 600s; raise it for slow local backends (e.g. Ollama).
-# timeout: 1200
+# Optional: LLM / LiteLLM tuning. Keys are forwarded to LiteLLM; `timeout` and
+# `extra_headers` apply per request, the rest are set as litellm.<key>.
+# litellm:
+#   timeout: 1200          # per-request timeout (s); raise for slow local backends (Ollama)
+#   drop_params: true      # let LiteLLM drop params a provider rejects (e.g. Ollama)
+#   num_retries: 3
+#   extra_headers:         # extra HTTP headers some providers need (e.g. GitHub Copilot)
+#     Editor-Version: vscode/1.95.0
+#     Copilot-Integration-Id: vscode-chat

openkb/cli.py

@@ -44,6 +44,7 @@ def filter(self, record: logging.LogRecord) -> bool:
 from openkb.config import (
     DEFAULT_CONFIG, load_config, save_config, load_global_config, register_kb,
     resolve_extra_headers, set_extra_headers, resolve_timeout, set_timeout,
+    resolve_litellm_settings,
 )
 from openkb.converter import _registry_path, convert_document
 from openkb.locks import atomic_write_json, atomic_write_text, kb_ingest_lock, kb_read_lock
@@ -56,6 +57,8 @@ def filter(self, record: logging.LogRecord) -> bool:
 
 load_dotenv()  # load from cwd (covers running inside the KB dir)
 
+logger = logging.getLogger(__name__)
+
 
 _KNOWN_PROVIDER_KEYS = (
     "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "GEMINI_API_KEY",
@@ -83,6 +86,31 @@ def _extract_provider(model: str) -> str | None:
     return "openai"
 
 
+def _apply_litellm_settings(settings: dict) -> None:
+    """Set each ``litellm:`` key verbatim onto the litellm module (process-wide
+    globals, so they reach every LiteLLM call). Skips with a warning a key the
+    installed litellm doesn't define, or one that is a litellm function (e.g.
+    ``completion``) since overwriting it would break later calls. Applied, never
+    reset — the values persist for the life of the process.
+    """
+    for key, value in settings.items():
+        if not hasattr(litellm, key):
+            logger.warning(
+                "config: LiteLLM has no setting %r — ignoring it "
+                "(check the spelling or your installed litellm version).",
+                key,
+            )
+            continue
+        if callable(getattr(litellm, key)):
+            logger.warning(
+                "config: 'litellm.%s' is a LiteLLM function, not a setting — "
+                "refusing to overwrite it from the litellm: config block.",
+                key,
+            )
+            continue
+        setattr(litellm, key, value)
+
+
 def _setup_llm_key(kb_dir: Path | None = None) -> None:
     """Set LiteLLM API key from LLM_API_KEY env var if present.
 
@@ -113,6 +141,7 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
     provider: str | None = None
     extra_headers: dict[str, str] = {}
     timeout: float | None = None
+    litellm_settings: dict = {}
     if kb_dir is not None:
         config_path = kb_dir / ".openkb" / "config.yaml"
         if config_path.exists():
@@ -121,8 +150,24 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
             provider = _extract_provider(str(model))
             extra_headers = resolve_extra_headers(config)
             timeout = resolve_timeout(config)
+            litellm_settings = resolve_litellm_settings(config)
+            # The litellm: block is the canonical place for LLM tuning. It may
+            # also carry `timeout` / `extra_headers`; those route to the per-call
+            # mechanisms, while the rest are applied as litellm module globals.
+            # When the block specifies one of these keys it is authoritative —
+            # its resolved value replaces the legacy top-level one (so an empty
+            # `extra_headers: {}` clears rather than reverting to the old value).
+            if "extra_headers" in litellm_settings:
+                extra_headers = resolve_extra_headers(
+                    {"extra_headers": litellm_settings.pop("extra_headers")}
+                )
+            if "timeout" in litellm_settings:
+                timeout = resolve_timeout(
+                    {"timeout": litellm_settings.pop("timeout")}
+                )
     set_extra_headers(extra_headers)
     set_timeout(timeout)
+    _apply_litellm_settings(litellm_settings)
 
     if not api_key:
         # Check if any provider key is already set. OAuth-based providers
@@ -304,7 +349,6 @@ def _add_single_file_locked(file_path: Path, kb_dir: Path) -> Literal["added", "
     from openkb.agent.compiler import compile_long_doc, compile_short_doc
     from openkb.state import HashRegistry
 
-    logger = logging.getLogger(__name__)
     openkb_dir = kb_dir / ".openkb"
     config = load_config(openkb_dir / "config.yaml")
     _setup_llm_key(kb_dir)

openkb/config.py

@@ -172,6 +172,34 @@ def resolve_timeout(config: dict) -> float | None:
     return value
 
 
+def resolve_litellm_settings(config: dict) -> dict[str, Any]:
+    """Resolve the optional ``litellm:`` mapping of LiteLLM module settings.
+
+    Values are forwarded verbatim (the user owns them); only the container shape
+    is enforced — returns ``{}`` if absent or not a mapping, and drops non-string
+    keys. ``cli._apply_litellm_settings`` applies them.
+    """
+    raw = config.get("litellm")
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        logger.warning(
+            "config: 'litellm' must be a mapping of LiteLLM settings, got %s — "
+            "ignoring it.",
+            type(raw).__name__,
+        )
+        return {}
+    settings: dict[str, Any] = {}
+    for key, value in raw.items():
+        if not isinstance(key, str):
+            logger.warning(
+                "config: skipping 'litellm' entry with non-string key %r.", key
+            )
+            continue
+        settings[key] = value
+    return settings
+
+
 # Process-wide extra headers for LLM requests, resolved from the active KB's
 # config by the CLI entry points (cli._setup_llm_key). LLM call sites read it
 # via get_extra_headers() so the value doesn't have to be threaded through

tests/test_config.py

@@ -1,9 +1,12 @@
+import logging
+
 from openkb.config import (
     DEFAULT_CONFIG,
     get_extra_headers,
     get_timeout,
     load_config,
     resolve_extra_headers,
+    resolve_litellm_settings,
     resolve_timeout,
     save_config,
     set_extra_headers,
@@ -150,3 +153,41 @@ def test_timeout_stash_roundtrip_and_reset():
     assert get_timeout() == 1200.0
     set_timeout(None)
     assert get_timeout() is None
+
+
+def test_resolve_litellm_settings_absent_returns_empty():
+    assert resolve_litellm_settings({}) == {}
+
+
+def test_resolve_litellm_settings_passes_mapping_through_verbatim():
+    # Values are forwarded as-is — no validation or coercion.
+    config = {"litellm": {"drop_params": True, "num_retries": 3, "ssl_verify": False}}
+    assert resolve_litellm_settings(config) == {
+        "drop_params": True,
+        "num_retries": 3,
+        "ssl_verify": False,
+    }
+
+
+def test_resolve_litellm_settings_non_mapping_ignored():
+    assert resolve_litellm_settings({"litellm": ["drop_params"]}) == {}
+    assert resolve_litellm_settings({"litellm": "drop_params=true"}) == {}
+    assert resolve_litellm_settings({"litellm": True}) == {}
+
+
+def test_resolve_litellm_settings_drops_non_string_keys():
+    assert resolve_litellm_settings({"litellm": {5: "x", "drop_params": True}}) == {
+        "drop_params": True
+    }
+
+
+def test_resolve_litellm_settings_warns_on_non_mapping(caplog):
+    with caplog.at_level(logging.WARNING, logger="openkb.config"):
+        assert resolve_litellm_settings({"litellm": ["drop_params"]}) == {}
+    assert "must be a mapping" in caplog.text
+
+
+def test_resolve_litellm_settings_warns_on_non_string_key(caplog):
+    with caplog.at_level(logging.WARNING, logger="openkb.config"):
+        resolve_litellm_settings({"litellm": {5: "x", "drop_params": True}})
+    assert "non-string key" in caplog.text