feat(config): forward num_retries to LiteLLM per call

[01luyicheng]

Forward num_retries to LiteLLM per call

Closes #164.

Problem

Issue #164 reports that when a provider returns a transient failure
(Gemini 503 ServiceUnavailableError — "model is currently experiencing
high demand"), OpenKB does not retry: the step fails and is skipped
(e.g. 5 concept(s) planned but only 4 written … (ServiceUnavailableError)).
LiteLLM supports a num_retries knob for exactly this, but OpenKB only
exposed it as a process-wide litellm.<key> global, which is not applied
per request and is easy to mis-set.

Approach

Mirror the existing timeout plumbing (the proven precedent for
per-call LLM tuning):

• resolve_num_retries(config) — validates a non-negative int at the
  config boundary. Returns None (use LiteLLM's default) when absent or
  invalid. Rejects bools (int subclass), floats, and strings — a retry
  count is discrete, so no numeric coercion is applied (the one
  deliberate divergence from resolve_timeout, documented in its docstring).
• set_num_retries / get_num_retries / _runtime_num_retries — a
  process-wide stash, populated by cli._setup_llm_key from both the
  legacy top-level num_retries: key and the litellm: block (the block
  value wins, matching timeout's precedence).
• compiler._llm_call / _llm_call_async forward it to
  litellm.completion / litellm.acompletion via kwargs.setdefault,
  so an explicit per-call value is never clobbered.

Default = None (zero behavior change)

The new knob is opt-in. Nothing is forwarded when num_retries is
unset, so existing configs behave identically and LiteLLM keeps applying
its own default. This deliberately does not change retry behavior for
non-configurers.

How to enable

litellm:
  num_retries: 3      # retries on transient failures (e.g. model overloaded)

Decisions a maintainer may want to revisit

1. Scope: compile path only. Like timeout's direct call-site use,
   num_retries is forwarded at compiler._llm_call(_async) — the path
   named in Requesting retry logic when model is overloaded #164 (concept/entity/summary-rewrite). Unlike timeout,
   this PR does not add an Agents-SDK analogue of
   get_timeout_extra_args(), so the knob does not currently apply
   to the chat / query / lint / skill-eval / skill-creator paths that run
   LLM calls through openai-agents ModelSettings. A user setting
   num_retries: 3 will see retries on openkb add/compile but not
   on openkb chat/query/lint. This is intentional for this PR
   (keeps it small and focused on the reported issue) but is an asymmetry
   vs. timeout; a follow-up can add get_num_retries_extra_args() once
   we confirm how ModelSettings exposes retries.
2. Opt-in default. Because the default is None, this does not
   auto-fix Requesting retry logic when model is overloaded #164 for users who don't add the key. If the maintainers
   prefer to ship retries by default, that's a one-line follow-up — kept
   out of this PR to preserve zero behavior change.

Tests

• tests/test_config.py — resolve/stash for absent, int, 0, negative,
  bool, float, string, non-int containers.
• tests/test_llm_config_passthrough.py — litellm: block routes
  num_retries per-call (not as a module global).
• tests/test_llm_retries.py (new) — sync + async call sites: forwards
  configured value, omits when unset, does not override an explicit
  per-call kwarg (setdefault semantics).

All 958 tests pass; ruff check, ruff format --check, and mypy openkb
are clean.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[KylinMountain]

@01luyicheng can you help to resolve the conflicts? Thanks

[KylinMountain]

Thanks — the plumbing is clean. But one thing before we take it: num_retries already works today. It's a litellm global, so litellm: { num_retries: 3 } in config already retries every call (compile + query/chat/lint/skill) via litellm.num_retries.

Really appreciate the contribution.

[01luyicheng]

Thanks for the review and the clear explanation. You're right that num_retries already works today via the litellm global and covers every call path (compile + query/chat/lint/skill), which is actually broader than what this PR proposed — its per-call plumbing only reached the compile path, so merging it would have added an asymmetry rather than an improvement. I respect the decision to close it. I'll keep an eye out for a more genuinely useful contribution and follow up then. Thanks again for maintaining OpenKB.