feat(config): configurable LLM request timeout

config.yaml.example

@@ -17,3 +17,7 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 #   - organization
 #   - 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

openkb/agent/compiler.py

@@ -29,7 +29,12 @@
 import litellm
 
 from openkb import frontmatter
-from openkb.config import DEFAULT_ENTITY_TYPES, get_extra_headers, resolve_entity_types
+from openkb.config import (
+    DEFAULT_ENTITY_TYPES,
+    get_extra_headers,
+    get_timeout,
+    resolve_entity_types,
+)
 from openkb.lint import list_existing_wiki_targets, strip_ghost_wikilinks
 from openkb.schema import INDEX_SEED, get_agents_md
 
@@ -326,6 +331,9 @@ def _llm_call(model: str, messages: list[dict], step_name: str, **kwargs) -> str
     extra_headers = get_extra_headers()
     if extra_headers:
         kwargs.setdefault("extra_headers", extra_headers)
+    timeout = get_timeout()
+    if timeout is not None:
+        kwargs.setdefault("timeout", timeout)
     logger.debug("LLM request [%s]:\n%s", step_name, _fmt_messages(messages))
     if kwargs:
         logger.debug("LLM kwargs [%s]: %s", step_name, kwargs)
@@ -348,6 +356,9 @@ async def _llm_call_async(model: str, messages: list[dict], step_name: str, **kw
     extra_headers = get_extra_headers()
     if extra_headers:
         kwargs.setdefault("extra_headers", extra_headers)
+    timeout = get_timeout()
+    if timeout is not None:
+        kwargs.setdefault("timeout", timeout)
     logger.debug("LLM request [%s]:\n%s", step_name, _fmt_messages(messages))
     if kwargs:
         logger.debug("LLM kwargs [%s]: %s", step_name, kwargs)

openkb/agent/linter.py

@@ -7,7 +7,7 @@
 from agents.model_settings import ModelSettings
 
 from openkb.agent.tools import list_wiki_files, read_wiki_file
-from openkb.config import get_extra_headers
+from openkb.config import get_extra_headers, get_timeout_extra_args
 
 MAX_TURNS = 50
 from openkb.schema import get_agents_md
@@ -81,7 +81,10 @@ def read_file(path: str) -> str:
         instructions=instructions,
         tools=[list_files, read_file],
         model=f"litellm/{model}",
-        model_settings=ModelSettings(extra_headers=get_extra_headers() or None),
+        model_settings=ModelSettings(
+            extra_headers=get_extra_headers() or None,
+            extra_args=get_timeout_extra_args(),
+        ),
     )
 
 

openkb/agent/query.py

@@ -6,7 +6,7 @@
 from agents import Agent, Runner, function_tool
 
 from agents import ToolOutputImage, ToolOutputText
-from openkb.config import get_extra_headers
+from openkb.config import get_extra_headers, get_timeout_extra_args
 from openkb.agent.tools import (
     get_wiki_page_content,
     read_wiki_file,
@@ -98,6 +98,7 @@ def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
         model_settings=ModelSettings(
             parallel_tool_calls=False,
             extra_headers=get_extra_headers() or None,
+            extra_args=get_timeout_extra_args(),
         ),
     )
 

openkb/cli.py

@@ -43,7 +43,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_extra_headers, set_extra_headers, resolve_timeout, set_timeout,
 )
 from openkb.converter import _registry_path, convert_document
 from openkb.locks import atomic_write_json, atomic_write_text, kb_ingest_lock, kb_read_lock
@@ -108,17 +108,21 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
 
     api_key = os.environ.get("LLM_API_KEY", "")
 
-    # Try to resolve the active provider and extra headers from the KB config
+    # Try to resolve the active provider, extra headers, and request timeout
+    # from the KB config
     provider: str | None = None
     extra_headers: dict[str, str] = {}
+    timeout: float | None = None
     if kb_dir is not None:
         config_path = kb_dir / ".openkb" / "config.yaml"
         if config_path.exists():
             config = load_config(config_path)
             model = config.get("model", "")
             provider = _extract_provider(str(model))
             extra_headers = resolve_extra_headers(config)
+            timeout = resolve_timeout(config)
     set_extra_headers(extra_headers)
+    set_timeout(timeout)
 
     if not api_key:
         # Check if any provider key is already set. OAuth-based providers

openkb/config.py

@@ -2,6 +2,7 @@
 
 import contextlib
 import logging
+import math
 import re
 from pathlib import Path
 from typing import Any, Iterator
@@ -136,6 +137,41 @@ def resolve_extra_headers(config: dict) -> dict[str, str]:
     return headers
 
 
+def resolve_timeout(config: dict) -> float | None:
+    """Resolve the optional ``timeout:`` key to a finite positive number of seconds.
+
+    Returns ``None`` (use LiteLLM's default) when absent or invalid; rejects
+    bools and ``nan``/``inf``, warning when present but unusable.
+    """
+    raw = config.get("timeout")
+    if raw is None:
+        return None
+    if isinstance(raw, bool) or not isinstance(raw, (int, float, str)):
+        logger.warning(
+            "config: 'timeout' must be a positive number of seconds, got %s — "
+            "ignoring it.",
+            type(raw).__name__,
+        )
+        return None
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        logger.warning(
+            "config: 'timeout' must be a positive number of seconds, got %r — "
+            "ignoring it.",
+            raw,
+        )
+        return None
+    if not math.isfinite(value) or value <= 0:
+        logger.warning(
+            "config: 'timeout' must be a finite positive number of seconds, got "
+            "%s — ignoring it.",
+            value,
+        )
+        return None
+    return value
+
+
 # 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
@@ -155,6 +191,29 @@ def get_extra_headers() -> dict[str, str]:
     return dict(_runtime_extra_headers)
 
 
+# Process-wide LLM request timeout (seconds), set from config by the CLI and
+# read at the call sites via get_timeout(). None = use LiteLLM's default.
+_runtime_timeout: float | None = None
+
+
+def set_timeout(timeout: float | None) -> None:
+    """Set the process-wide LLM request timeout in seconds; ``None`` clears it."""
+    global _runtime_timeout
+    _runtime_timeout = timeout
+
+
+def get_timeout() -> float | None:
+    """Return the process-wide LLM request timeout in seconds, or ``None``."""
+    return _runtime_timeout
+
+
+def get_timeout_extra_args() -> dict[str, float] | None:
+    """Timeout as Agents-SDK ``ModelSettings.extra_args`` (it has no ``timeout``
+    field), or ``None``. The LiteLLM provider forwards it to the completion call.
+    """
+    return {"timeout": _runtime_timeout} if _runtime_timeout is not None else None
+
+
 def load_config(config_path: Path) -> dict[str, Any]:
     """Load YAML config from config_path, merged with DEFAULT_CONFIG.
 

openkb/skill/creator.py

@@ -19,7 +19,7 @@
 from agents import Agent, Runner, ToolOutputImage, ToolOutputText, function_tool
 from agents.model_settings import ModelSettings
 
-from openkb.config import get_extra_headers
+from openkb.config import get_extra_headers, get_timeout_extra_args
 from openkb.skill import skill_dir
 from openkb.skill.tools import (
     get_skill_page_content as _get_page_content_impl,
@@ -154,6 +154,7 @@ def done(summary: str) -> str:
         model_settings=ModelSettings(
             parallel_tool_calls=True,
             extra_headers=get_extra_headers() or None,
+            extra_args=get_timeout_extra_args(),
         ),
     )
 

openkb/skill/evaluator.py

@@ -46,7 +46,7 @@
 from agents.exceptions import MaxTurnsExceeded
 from agents.model_settings import ModelSettings
 
-from openkb.config import get_extra_headers
+from openkb.config import get_extra_headers, get_timeout_extra_args
 from openkb.skill import extract_body, extract_frontmatter
 
 
@@ -243,7 +243,10 @@ async def generate_eval_set(
         name="eval-set-generator",
         instructions=instructions,
         model=f"litellm/{model}",
-        model_settings=ModelSettings(extra_headers=get_extra_headers() or None),
+        model_settings=ModelSettings(
+            extra_headers=get_extra_headers() or None,
+            extra_args=get_timeout_extra_args(),
+        ),
     )
     try:
         result = await Runner.run(agent, "Generate the eval set now.", max_turns=3)
@@ -302,7 +305,10 @@ async def grade_one(
         name="trigger-grader",
         instructions=instructions,
         model=f"litellm/{model}",
-        model_settings=ModelSettings(extra_headers=get_extra_headers() or None),
+        model_settings=ModelSettings(
+            extra_headers=get_extra_headers() or None,
+            extra_args=get_timeout_extra_args(),
+        ),
     )
     try:
         result = await Runner.run(agent, f"Question: {question}", max_turns=2)
@@ -351,7 +357,10 @@ async def grade_coverage(
         name="coverage-grader",
         instructions=instructions,
         model=f"litellm/{model}",
-        model_settings=ModelSettings(extra_headers=get_extra_headers() or None),
+        model_settings=ModelSettings(
+            extra_headers=get_extra_headers() or None,
+            extra_args=get_timeout_extra_args(),
+        ),
     )
     try:
         result = await Runner.run(agent, f"Question: {question}", max_turns=2)

tests/conftest.py

@@ -4,10 +4,11 @@
 
 @pytest.fixture(autouse=True)
 def _reset_extra_headers():
-    """Keep the process-wide LLM extra-headers stash from leaking across tests."""
-    from openkb.config import set_extra_headers
+    """Keep the process-wide LLM extra-headers / timeout stashes from leaking across tests."""
+    from openkb.config import set_extra_headers, set_timeout
     yield
     set_extra_headers({})
+    set_timeout(None)
 
 
 @pytest.fixture

tests/test_cli.py

@@ -373,12 +373,14 @@ class TestSetupLlmKey:
     """_setup_llm_key: OAuth-provider warning skip + extra-headers stash."""
 
     @staticmethod
-    def _make_kb(tmp_path, model, extra_headers=None):
+    def _make_kb(tmp_path, model, extra_headers=None, timeout=None):
         openkb_dir = tmp_path / ".openkb"
         openkb_dir.mkdir()
         config = {"model": model}
         if extra_headers is not None:
             config["extra_headers"] = extra_headers
+        if timeout is not None:
+            config["timeout"] = timeout
         (openkb_dir / "config.yaml").write_text(
             yaml.safe_dump(config), encoding="utf-8"
         )
@@ -445,3 +447,20 @@ def test_extra_headers_reset_when_config_has_none(self, tmp_path):
         kb = self._make_kb(tmp_path, "gpt-5.4-mini")
         _setup_llm_key(kb)
         assert get_extra_headers() == {}
+
+    def test_timeout_stashed_from_config(self, tmp_path):
+        from openkb.cli import _setup_llm_key
+        from openkb.config import get_timeout
+
+        kb = self._make_kb(tmp_path, "gpt-5.4-mini", timeout=1200)
+        _setup_llm_key(kb)
+        assert get_timeout() == 1200.0
+
+    def test_timeout_reset_when_config_has_none(self, tmp_path):
+        from openkb.cli import _setup_llm_key
+        from openkb.config import get_timeout, set_timeout
+
+        set_timeout(999.0)
+        kb = self._make_kb(tmp_path, "gpt-5.4-mini")
+        _setup_llm_key(kb)
+        assert get_timeout() is None

tests/test_config.py

@@ -1,10 +1,13 @@
 from openkb.config import (
     DEFAULT_CONFIG,
     get_extra_headers,
+    get_timeout,
     load_config,
     resolve_extra_headers,
+    resolve_timeout,
     save_config,
     set_extra_headers,
+    set_timeout,
 )
 
 
@@ -102,3 +105,48 @@ def test_extra_headers_stash_roundtrip_and_isolation():
     assert get_extra_headers() == {"A": "1"}
     set_extra_headers({})
     assert get_extra_headers() == {}
+
+
+# --- timeout -----------------------------------------------------------------
+
+def test_resolve_timeout_absent_returns_none():
+    assert resolve_timeout({}) is None
+
+
+def test_resolve_timeout_int_and_float():
+    assert resolve_timeout({"timeout": 1200}) == 1200.0
+    assert resolve_timeout({"timeout": 0.5}) == 0.5
+
+
+def test_resolve_timeout_numeric_string_coerced():
+    assert resolve_timeout({"timeout": "1200"}) == 1200.0
+
+
+def test_resolve_timeout_rejects_non_positive():
+    assert resolve_timeout({"timeout": 0}) is None
+    assert resolve_timeout({"timeout": -10}) is None
+
+
+def test_resolve_timeout_rejects_bool():
+    # bool is a subclass of int; True/False are not durations.
+    assert resolve_timeout({"timeout": True}) is None
+
+
+def test_resolve_timeout_rejects_non_numeric():
+    assert resolve_timeout({"timeout": "soon"}) is None
+    assert resolve_timeout({"timeout": [1200]}) is None
+
+
+def test_resolve_timeout_rejects_nan_and_inf():
+    # nan/inf pass a naive `<= 0` check; YAML's .nan/.inf yield real floats.
+    assert resolve_timeout({"timeout": float("inf")}) is None
+    assert resolve_timeout({"timeout": float("nan")}) is None
+    assert resolve_timeout({"timeout": "inf"}) is None
+    assert resolve_timeout({"timeout": "nan"}) is None
+
+
+def test_timeout_stash_roundtrip_and_reset():
+    set_timeout(1200.0)
+    assert get_timeout() == 1200.0
+    set_timeout(None)
+    assert get_timeout() is None