Merge origin/main into feat/import-pageindex-cloud

Resolve conflicts:
- cli.py: keep top-level compile_long_doc import (PR) + main's expanded
  openkb.config import (extra_headers/timeout/litellm resolvers).
- indexer.py: keep the PR's _write_long_doc_artifacts helper but thread
  main's new description= through it (used by both local + cloud paths).
- pyproject.toml / uv.lock: take main's pinned deps (incl. pageindex==0.3.0.dev1,
  portalocker) over the PR's loose/git@dev pins.

Author: KylinMountain

README.md

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

config.yaml.example

@@ -659,7 +659,8 @@ async def _handle_slash_deck(arg: str, kb_dir: Path, style: Style) -> None:
     model = config.get("model", DEFAULT_CONFIG["model"])
 
     from openkb.skill.generator import Generator
-    skill_label = skill_name if skill_name else "openkb-deck-editorial (default)"
+    from openkb.deck.creator import DEFAULT_DECK_SKILL
+    skill_label = skill_name if skill_name else f"{DEFAULT_DECK_SKILL} (default)"
     _fmt(
         style,
         ("class:slash.help", f"Generating deck '{name}' via skill {skill_label}...\n"),

openkb/agent/chat.py

@@ -4,8 +4,10 @@
 from pathlib import Path
 
 from agents import Agent, Runner, function_tool
+from agents.model_settings import ModelSettings
 
 from openkb.agent.tools import list_wiki_files, read_wiki_file
+from openkb.config import get_extra_headers, get_timeout_extra_args
 
 MAX_TURNS = 50
 from openkb.schema import get_agents_md
@@ -79,6 +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,
+            extra_args=get_timeout_extra_args(),
+        ),
     )
 
 

openkb/agent/compiler.py

@@ -6,6 +6,7 @@
 from agents import Agent, Runner, function_tool
 
 from agents import ToolOutputImage, ToolOutputText
+from openkb.config import get_extra_headers, get_timeout_extra_args
 from openkb.agent.tools import (
     get_wiki_page_content,
     read_wiki_file,
@@ -94,7 +95,11 @@ def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
         instructions=instructions,
         tools=[read_file, get_page_content, get_image],
         model=f"litellm/{model}",
-        model_settings=ModelSettings(parallel_tool_calls=False),
+        model_settings=ModelSettings(
+            parallel_tool_calls=False,
+            extra_headers=get_extra_headers() or None,
+            extra_args=get_timeout_extra_args(),
+        ),
     )
 
 

openkb/agent/linter.py

@@ -42,7 +42,11 @@ def filter(self, record: logging.LogRecord) -> bool:
 from dotenv import load_dotenv
 
 from openkb.agent.compiler import compile_long_doc
-from openkb.config import DEFAULT_CONFIG, load_config, save_config, load_global_config, register_kb
+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.indexer import import_cloud_document
 from openkb.locks import atomic_write_json, atomic_write_text, kb_ingest_lock, kb_read_lock
@@ -55,13 +59,20 @@ 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",
     "DEEPSEEK_API_KEY", "MISTRAL_API_KEY", "MOONSHOT_API_KEY",
     "ZHIPUAI_API_KEY", "DASHSCOPE_API_KEY",
 )
 
+# Providers that authenticate via OAuth device flow (subscription login
+# handled by LiteLLM itself) — no API key env var is needed, so the
+# missing-key warning would be a false alarm for them.
+_OAUTH_PROVIDERS = {"chatgpt", "github_copilot"}
+
 
 def _extract_provider(model: str) -> str | None:
     """Extract the LiteLLM provider name from a model string.
@@ -77,6 +88,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.
 
@@ -102,23 +138,45 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
 
     api_key = os.environ.get("LLM_API_KEY", "")
 
-    # Try to resolve the active provider 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
+    litellm_settings: dict = {}
     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)
+            litellm_settings = resolve_litellm_settings(config)
+            # `timeout` / `extra_headers` in the block route to the per-call
+            # stashes (replacing the legacy top-level keys); the rest are globals.
+            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
+        # Check if any provider key is already set. OAuth-based providers
+        # (ChatGPT subscription, GitHub Copilot) don't use API keys at all,
+        # so the warning is skipped for them.
         check_keys = (
             (f"{provider.upper()}_API_KEY",) if provider
             else _KNOWN_PROVIDER_KEYS
         )
         has_key = any(os.environ.get(k) for k in check_keys)
-        if not has_key:
+        if not has_key and provider not in _OAUTH_PROVIDERS:
             click.echo(
                 "Warning: No LLM API key found. Set one of:\n"
                 f"  1. {kb_dir / '.env' if kb_dir else '<kb_dir>/.env'} — LLM_API_KEY=sk-...\n"
@@ -289,7 +347,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)
@@ -1581,6 +1638,36 @@ def lint(ctx, fix):
     asyncio.run(run_lint(kb_dir))
 
 
+@cli.command()
+@click.option("--open/--no-open", "open_browser", default=True,
+              help="Open the graph in your browser after generating (default: on; --no-open for headless).")
+@click.pass_context
+@_with_kb_lock(exclusive=False)
+def visualize(ctx, open_browser):
+    """Render the wiki's [[wikilink]] graph as a self-contained interactive HTML page."""
+    kb_dir = _find_kb_dir(ctx.obj.get("kb_dir_override"))
+    if kb_dir is None:
+        click.echo("No knowledge base found. Run `openkb init` first.")
+        return
+    from openkb import visualize as viz
+    graph = viz.build_graph(kb_dir / "wiki")
+    if not graph["nodes"]:
+        click.echo("No wiki pages to visualize yet. Run `openkb add` first.")
+        return
+    out = kb_dir / "output" / "visualize" / "graph.html"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(viz.render_html(graph), encoding="utf-8")
+    click.echo(f"Graph written to {out}  ({len(graph['nodes'])} nodes, {len(graph['edges'])} edges)")
+    if open_browser:
+        import webbrowser
+        try:
+            opened = webbrowser.open(out.resolve().as_uri())   # resolve() so a relative --kb-dir still yields a valid file URI
+        except Exception:
+            opened = False
+        if not opened:
+            click.echo("(couldn't launch a browser — open the file above manually, or use --no-open)")
+
+
 def print_list(kb_dir: Path) -> None:
     """Print all documents in the knowledge base. Usable from CLI and chat REPL."""
     openkb_dir = kb_dir / ".openkb"
@@ -2348,8 +2435,10 @@ def deck():
     "--skill", "skill_name",
     metavar="SKILL_NAME",
     default=None,
+    # NOTE: 'openkb-deck-neon' below must stay in sync with
+    # DEFAULT_DECK_SKILL in openkb/deck/creator.py.
     help=(
-        "Which deck skill to use. Defaults to 'openkb-deck-editorial' "
+        "Which deck skill to use. Defaults to 'openkb-deck-neon' "
         "(the built-in). Pass e.g. 'deck-guizang-editorial' to route to "
         "a third-party skill installed under ~/.openkb/skills/."
     ),
@@ -2428,7 +2517,8 @@ def deck_new(ctx, name, intent, yes_flag, critique_flag, skill_name):
 
     # Run the generator.
     from openkb.skill.generator import Generator
-    skill_label = skill_name if skill_name else "openkb-deck-editorial (default)"
+    from openkb.deck.creator import DEFAULT_DECK_SKILL
+    skill_label = skill_name if skill_name else f"{DEFAULT_DECK_SKILL} (default)"
     click.echo(f"Generating deck '{name}' via skill {skill_label}...")
     gen = Generator(
         target_type="deck",