refactor(config): default parallel_tool_calls to false; null = omit for Bedrock

Revised per review: the default must NOT change existing behavior. Keep the
historical default (false = force sequential tool calls) for every provider,
and make `null` the explicit "don't send the setting" escape hatch that
Bedrock Claude needs (sending any value trips the LiteLLM malformed-tool_choice
bug, #175). No provider special-casing in code — it's purely the config value.

- DEFAULT_CONFIG parallel_tool_calls: false (was None).
- resolve_parallel_tool_calls: absent → false (default); true/false → that;
  explicit null → None (omit, silent); other → default + warning.
- Docs updated: default false, set `null` for Bedrock.

Author: KylinMountain

config.yaml.example

@@ -2,11 +2,13 @@ model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 
-# Optional: whether query/chat agents may call tools in parallel. Omit (the
-# default) to let the provider decide. Leave it unset for Amazon Bedrock Claude
-# models — sending it makes LiteLLM emit a malformed tool_choice and every
-# query/chat fails. Set false to force sequential tool calls on other providers.
-# parallel_tool_calls: false
+# Optional: whether query/chat agents may call tools in parallel.
+#   false (default) force sequential tool calls
+#   true            allow parallel tool calls
+#   null            don't send the setting (use the provider default) — set this
+#                   for Amazon Bedrock Claude, which rejects the request when
+#                   parallel_tool_calls is sent at all (any value). See #175.
+# parallel_tool_calls: null
 
 # Optional: override the entity-type vocabulary used for entity pages.
 # Omit this key to use the default 7 types

examples/configuration/README.md

@@ -70,11 +70,13 @@ model: gpt-5.4                   # LLM model (any LiteLLM-supported provider)
 language: en                     # Wiki output language
 pageindex_threshold: 20          # PDF pages threshold for PageIndex
 
-# Optional: whether query/chat agents may call tools in parallel. Omit (the
-# default) to let the provider decide. Leave it unset for Amazon Bedrock Claude
-# models — sending it makes LiteLLM emit a malformed tool_choice and every
-# query/chat fails. Set false to force sequential tool calls on other providers.
-# parallel_tool_calls: false
+# Optional: whether query/chat agents may call tools in parallel.
+#   false (default) force sequential tool calls
+#   true            allow parallel tool calls
+#   null            don't send the setting (use the provider default) — set this
+#                   for Amazon Bedrock Claude, which rejects the request when
+#                   parallel_tool_calls is sent at all (any value). See #175.
+# parallel_tool_calls: null
 
 # Optional: override the entity-type vocabulary used for entity pages.
 # Omit this key to use the default 7 types
@@ -101,7 +103,7 @@ pageindex_threshold: 20          # PDF pages threshold for PageIndex
 | `model` | `gpt-5.4` | LLM used for all compile/query/chat work. |
 | `language` | `en` | Language the wiki is written in. |
 | `pageindex_threshold` | `20` | PDFs with this many pages **or more** take the long-doc (PageIndex) path; shorter ones go through the short-doc path. See [`pageindex-cloud/`](../pageindex-cloud/). |
-| `parallel_tool_calls` | *(unset)* | Whether query/chat agents may call tools in parallel. Unset = provider default. **Leave unset for Amazon Bedrock** (see below). Set `false` to force sequential tool calls elsewhere. |
+| `parallel_tool_calls` | `false` | Whether query/chat agents may call tools in parallel. `false` (default) forces sequential; `true` allows parallel; `null` omits the setting (provider default). **Amazon Bedrock needs `null`** (see below). |
 | `entity_types` | 7 defaults | Custom vocabulary for entity pages. `other` is always kept. |
 | `litellm:` | – | A pass-through block for LiteLLM. See below. |
 
@@ -198,9 +200,10 @@ LLM_API_KEY=your-key-here
   ```yaml
   # <kb>/.openkb/config.yaml
   model: bedrock/eu.anthropic.claude-sonnet-4-6
-  # Do NOT set parallel_tool_calls for Bedrock Claude — leaving it unset (the
-  # default) is what keeps query/chat working; setting it makes LiteLLM send a
-  # malformed tool_choice that Bedrock rejects (issue #175).
+  parallel_tool_calls: null   # REQUIRED for Bedrock Claude: the default (false)
+                              # — and any explicit value — makes LiteLLM send a
+                              # malformed tool_choice that Bedrock rejects (#175).
+                              # null tells OpenKB not to send the setting at all.
   ```
 
 **Where keys are read from** (first match wins, existing env always respected):

openkb/cli.py

@@ -176,7 +176,7 @@ def _setup_llm_key(kb_dir: Path | None = None) -> None:
     provider: str | None = None
     extra_headers: dict[str, str] = {}
     timeout: float | None = None
-    parallel_tool_calls: bool | None = None
+    parallel_tool_calls: bool | None = DEFAULT_CONFIG["parallel_tool_calls"]
     litellm_settings: dict = {}
     if kb_dir is not None:
         config_path = kb_dir / ".openkb" / "config.yaml"

openkb/config.py

@@ -17,12 +17,13 @@
     "model": "gpt-5.4",
     "language": "en",
     "pageindex_threshold": 20,
-    # Whether query/chat agents may call tools in parallel. None (default) omits
-    # the setting so the provider decides — required for Amazon Bedrock's Claude
-    # models, where sending parallel_tool_calls makes LiteLLM emit a malformed
-    # tool_choice (missing `type`) and every query/chat fails (issue #175). Set
-    # false to force sequential tool calls (fine on OpenAI/Anthropic-direct).
-    "parallel_tool_calls": None,
+    # Whether query/chat agents may call tools in parallel. Default false =
+    # force sequential tool calls (historical behavior). true = allow parallel.
+    # null = don't send the setting at all (use the provider default) — the
+    # escape hatch for Amazon Bedrock Claude, where sending parallel_tool_calls
+    # (any value) makes LiteLLM emit a malformed tool_choice missing `type`, so
+    # every query/chat fails (issue #175).
+    "parallel_tool_calls": False,
 }
 
 # Default entity-type vocabulary. Overridable per-KB via the optional
@@ -153,20 +154,32 @@ def resolve_extra_headers(config: dict) -> dict[str, str]:
 def resolve_parallel_tool_calls(config: dict) -> bool | None:
     """Resolve the optional ``parallel_tool_calls:`` key.
 
-    Returns ``None`` (omit the setting — provider default) when absent or
-    explicitly null; ``True``/``False`` when set to a bool. A non-bool value is
-    invalid and treated as unset, with a warning. ``None`` is the normal
-    "unset" case and warns silently, matching ``resolve_timeout``.
+    Tri-state:
+      * key absent → the default (``False`` — force sequential tool calls).
+      * ``true`` / ``false`` → that bool.
+      * explicit ``null`` → ``None``, meaning "don't send the setting" so the
+        provider's own default applies. This is the escape hatch for Amazon
+        Bedrock Claude, which rejects the request when the param is sent at all.
+
+    A non-bool, non-null value is invalid → falls back to the default with a
+    warning. An explicit ``null`` is a valid choice and warns silently.
+
+    Note this relies on the config being merged with ``DEFAULT_CONFIG`` (as
+    ``load_config`` does), so an omitted key reads back as ``False`` while an
+    explicit ``null`` reads back as ``None`` — the two are distinguishable.
     """
-    value = config.get("parallel_tool_calls")
+    default = DEFAULT_CONFIG["parallel_tool_calls"]
+    value = config.get("parallel_tool_calls", default)
     if value is None:
         return None
     if not isinstance(value, bool):
         logger.warning(
-            "config: 'parallel_tool_calls' must be true or false, got %r — ignoring it.",
+            "config: 'parallel_tool_calls' must be true, false, or null, got %r "
+            "— using default (%r).",
             value,
+            default,
         )
-        return None
+        return default
     return value
 
 

tests/test_config.py

@@ -17,29 +17,33 @@
 )
 
 
-def test_parallel_tool_calls_defaults_to_none():
-    assert DEFAULT_CONFIG["parallel_tool_calls"] is None
+def test_parallel_tool_calls_defaults_to_false():
+    # Default preserves the historical behavior: force sequential tool calls.
+    assert DEFAULT_CONFIG["parallel_tool_calls"] is False
 
 
-def test_resolve_parallel_tool_calls_absent_is_none():
-    assert resolve_parallel_tool_calls({}) is None
+def test_resolve_parallel_tool_calls_absent_is_false():
+    # Key omitted → the default (force sequential), same as before this knob existed.
+    assert resolve_parallel_tool_calls({}) is False
 
 
 def test_resolve_parallel_tool_calls_explicit_bools():
     assert resolve_parallel_tool_calls({"parallel_tool_calls": True}) is True
     assert resolve_parallel_tool_calls({"parallel_tool_calls": False}) is False
 
 
-def test_resolve_parallel_tool_calls_none_is_silent(caplog):
+def test_resolve_parallel_tool_calls_null_means_omit(caplog):
+    # Explicit null = "don't send the param" (provider default). This is the
+    # escape hatch for Amazon Bedrock, and is silent (not an invalid value).
     with caplog.at_level(logging.WARNING, logger="openkb.config"):
         assert resolve_parallel_tool_calls({"parallel_tool_calls": None}) is None
     assert caplog.text == ""
 
 
 def test_resolve_parallel_tool_calls_rejects_non_bool(caplog):
-    # A non-bool (e.g. a string or int) is invalid → treat as unset, with a warning.
+    # A non-bool, non-null value is invalid → fall back to the default, with a warning.
     with caplog.at_level(logging.WARNING, logger="openkb.config"):
-        assert resolve_parallel_tool_calls({"parallel_tool_calls": "true"}) is None
+        assert resolve_parallel_tool_calls({"parallel_tool_calls": "true"}) is False
     assert "parallel_tool_calls" in caplog.text
 
 

tests/test_query.py

@@ -161,26 +161,35 @@ def test_no_extra_headers_by_default(self, tmp_path):
 
 
 class TestQueryAgentParallelToolCalls:
-    """Config-driven parallel_tool_calls reaches the agents-SDK model settings.
+    """The resolved parallel_tool_calls value (stash) reaches the model settings.
 
-    Default is None (omit the param → provider default), which is what keeps
-    Bedrock's Claude models working: passing parallel_tool_calls at all makes
-    LiteLLM emit a tool_choice object missing the required `type` field (see
-    issue #175). Users can still force sequential tool calls with
-    `parallel_tool_calls: false`.
+    Default is False (force sequential — unchanged historical behavior). A
+    config value of null resolves to None, which the agents-SDK omits from the
+    request — the escape hatch for Amazon Bedrock, whose Claude models reject
+    the request when parallel_tool_calls is sent at all (issue #175).
     """
 
-    def test_omitted_by_default(self, tmp_path):
+    def test_null_stash_is_omitted(self, tmp_path):
+        from openkb.config import set_parallel_tool_calls
+
+        set_parallel_tool_calls(None)
         agent = build_query_agent(str(tmp_path), "bedrock/eu.anthropic.claude-sonnet-4-6")
         assert agent.model_settings.parallel_tool_calls is None
 
-    def test_applied_from_stash(self, tmp_path):
+    def test_false_stash_forces_sequential(self, tmp_path):
         from openkb.config import set_parallel_tool_calls
 
         set_parallel_tool_calls(False)
         agent = build_query_agent(str(tmp_path), "gpt-4o-mini")
         assert agent.model_settings.parallel_tool_calls is False
 
+    def test_true_stash_allows_parallel(self, tmp_path):
+        from openkb.config import set_parallel_tool_calls
+
+        set_parallel_tool_calls(True)
+        agent = build_query_agent(str(tmp_path), "gpt-4o-mini")
+        assert agent.model_settings.parallel_tool_calls is True
+
 
 class TestQueryAgentTimeout:
     """Config-driven timeout reaches the agents-SDK model settings via extra_args.