fix: py3.10 litellm type repair; chat() gains reasoning_effort

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")
 

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")
 

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")
 

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")
 

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")
 

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")
 

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")
 

pageindex/client.py

@@ -382,6 +382,7 @@ def chat(
  doc_id: Optional[Union[str, list[str]]] = None,
  stream: bool = False,
  model: Optional[str] = None,
+ reasoning_effort: Optional[str] = None,
  ) -> Union[str, Iterator[str]]:
  """
  Ask a question about your documents, get the answer.
@@ -401,13 +402,18 @@ def chat(
  stream: Yield the answer as text chunks as it is produced.
  model: Local only — backend model name (defaults to
  ``chat_model``).
+ reasoning_effort: Local only — how hard the model thinks
+ (``"low"`` / ``"medium"`` / ``"high"``; what a backend
+ accepts is its own). Unset sends nothing — the model's
+ default behavior applies.
 
  Returns:
  - stream=False: the answer string
  - stream=True: iterator of text chunks
  """
  result = self.chat_completions(messages, stream=stream,
- doc_id=doc_id, model=model)
+ doc_id=doc_id, model=model,
+ reasoning_effort=reasoning_effort)
  if stream:
  return cast(Iterator[str], result)
  envelope = cast(dict[str, Any], result)

pageindex/local_chat.py

@@ -254,6 +254,8 @@ def _openai_model(protocol: str, model_name: str):
  f"'{model_name}' routes through LiteLLM, but litellm is not "
  "installed. Run: pip install 'litellm>=1.97'"
  )
+ from .utils import _repair_litellm_types
+ _repair_litellm_types()
  wire = model_name.removeprefix("litellm/")
  if "/" not in wire or wire.startswith("openai/"):
  if not os.environ.get("OPENAI_API_KEY"):

pageindex/utils.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import sys
 import textwrap
 from datetime import datetime
 import time
@@ -19,6 +20,23 @@
 # litellm is imported inside the functions that use it; eager import is slow
 # and fetches a remote model-cost map.
 
+
+def _repair_litellm_types() -> None:
+ """litellm 1.97.0's Message/Delta annotations carry nested forward refs
+ Python 3.10 cannot resolve (BerriAI/litellm#36384), so every completion
+ dies constructing its response. Rebuild them once with the defining
+ modules' names; no-op on 3.11+ and on fixed litellm releases."""
+ if sys.version_info >= (3, 11):
+ return
+ try:
+ import litellm.types.llms.openai as openai_types
+ import litellm.types.utils as litellm_types
+ namespace = {**vars(openai_types), **vars(litellm_types)}
+ litellm_types.Message.model_rebuild(_types_namespace=namespace)
+ litellm_types.Delta.model_rebuild(_types_namespace=namespace)
+ except Exception:
+ pass # best-effort: a failed repair leaves litellm's own error
+
 # Backward compatibility: support CHATGPT_API_KEY as alias for OPENAI_API_KEY
 if not os.getenv("OPENAI_API_KEY") and os.getenv("CHATGPT_API_KEY"):
  os.environ["OPENAI_API_KEY"] = os.getenv("CHATGPT_API_KEY")
@@ -81,6 +99,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = litellm.completion(
  model=model,
  messages=messages,
@@ -127,6 +146,7 @@ async def llm_acompletion(model, prompt):
  )
  else:
  import litellm
+ _repair_litellm_types()
  response = await litellm.acompletion(
  model=model,
  messages=messages,

tests/test_local_chat.py

@@ -282,6 +282,8 @@ def test_cloud_guards():
  with pytest.raises(PageIndexAPIError, match="local-mode"):
  cloud.chat_completions([{"role": "user", "content": "x"}],
  max_tokens=256)
+ with pytest.raises(PageIndexAPIError, match="local-mode"):
+ cloud.chat("x", reasoning_effort="low")
  with pytest.raises(PageIndexAPIError, match="not available on PageIndex "
  "cloud yet"):
  cloud.responses("x")
@@ -403,6 +405,28 @@ def test_chat_multi_turn_history(client, store_path, fake_model):
  assert fake.inputs[0][-3:] == history
 
 
+@needs_agents
+def test_chat_reasoning_effort_reaches_the_engine(client, store_path,
+ fake_model, monkeypatch):
+ """The business door's one thinking knob rides chat_completions'
+ channel unchanged; unset sends nothing."""
+ seen = {}
+ real = local_chat._openai_agent
+
+ def spy(*args, **kwargs):
+ agent = real(*args, **kwargs)
+ seen["settings"] = agent.model_settings
+ return agent
+
+ monkeypatch.setattr(local_chat, "_openai_agent", spy)
+ fake_model([[_msg_item("ok")]])
+ client.chat("q", reasoning_effort="low")
+ assert seen["settings"].extra_args["reasoning_effort"] == "low"
+ fake_model([[_msg_item("ok")]])
+ client.chat("q")
+ assert seen["settings"].extra_args is None
+
+
 def test_chat_cloud_unwraps_envelope(monkeypatch):
  cloud = PageIndexCloudClient(api_key="pi-test-key")