pageindex 0.2.10.dev4__tar.gz → 0.2.10.dev5__tar.gz

{pageindex-0.2.10.dev4 → pageindex-0.2.10.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pageindex
-Version: 0.2.10.dev4
+Version: 0.2.10.dev5
 Summary: Python SDK for PageIndex — reasoning-based, vectorless document retrieval, cloud and local
 License: MIT
 License-File: LICENSE

{pageindex-0.2.10.dev4 → pageindex-0.2.10.dev5}/pageindex/client.py

@@ -87,6 +87,15 @@ class PageIndexClient:
             ``chat_model``.
         storage_path (str, optional): Local mode only — directory where
             indexed documents are stored. Defaults to ``./.pageindex``.
+        index_backend (dict, optional): Local mode only — connection
+            overrides for the indexing lane's LLM calls. Keys are
+            LiteLLM's own connection params — ``api_key``, ``api_base``,
+            ``api_version``, ``aws_*``, … — passed through verbatim.
+        chat_backend (dict, optional): Local mode only — default
+            connection overrides for the chat surfaces; a call's own
+            ``backend`` keys win over it. The dict reaches whichever
+            door runs, in that door's vocabulary (see each method) —
+            ``api_key`` / ``base_url`` mean the same thing on all three.
 
     Usage:
         client = PageIndexClient(api_key="...")   # cloud
@@ -113,6 +122,8 @@ class PageIndexClient:
         summary_model: Optional[str] = None,
         retrieve_model: Optional[str] = None,
         storage_path: Optional[str] = None,
+        index_backend: Optional[dict[str, Any]] = None,
+        chat_backend: Optional[dict[str, Any]] = None,
     ):
         if api_key == "":
             raise PageIndexAPIError(
@@ -123,7 +134,9 @@ class PageIndexClient:
                       "model": model, "summary_model": summary_model,
                       "retrieve_model": retrieve_model}
         if api_key is not None:
-            local_only = dict(model_args, storage_path=storage_path)
+            local_only = dict(model_args, storage_path=storage_path,
+                              index_backend=index_backend,
+                              chat_backend=chat_backend)
             passed = [name for name, value in local_only.items() if value is not None]
             if passed:
                 raise PageIndexAPIError(
@@ -143,6 +156,7 @@ class PageIndexClient:
             self.index_model = opt.index_model
             self.summary_model = opt.summary_model
             self.chat_model = _agents_sdk_model_name(opt.chat_model)
+            self.chat_backend = chat_backend
             self.storage_path = storage_path or ".pageindex"
             from .local_api import LocalAPI
             self._api = LocalAPI(
@@ -150,6 +164,7 @@ class PageIndexClient:
                 model=self.model,
                 summary_model=self.summary_model,
                 retrieve_model=self.chat_model,
+                index_backend=index_backend,
             )
             # LiteLLM's multi-second import would otherwise land on the
             # first chat call; failures resurface there with real context.
@@ -433,6 +448,8 @@ class PageIndexClient:
         max_tokens: Optional[int] = None,
         reasoning_effort: Optional[str] = None,
         extra_body: Optional[dict[str, Any]] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+        backend: Optional[dict[str, Any]] = None,
     ) -> Union[dict[str, Any], Iterator[str], Iterator[dict[str, Any]]]:
         """
         PageIndex Chat Completions: document QA in one call.
@@ -490,6 +507,17 @@ class PageIndexClient:
                 OpenAI-compatible backends take them verbatim in the
                 request body; LiteLLM-routed providers take them as
                 LiteLLM's own params (mapped or refused per provider).
+                Credentials belong in ``backend``, never here.
+            extra_headers: Local only — extra HTTP headers merged into
+                each backend request; caller headers win. One exception:
+                LiteLLM's anthropic adapter owns the ``anthropic-beta``
+                header (your value is dropped there) — use ``messages()``
+                for Anthropic beta flags.
+            backend: Local only — connection overrides for this call's
+                backend, merged over the client's ``chat_backend``
+                (per-call keys win). Keys are LiteLLM's own connection
+                params — ``api_key``, ``base_url``, ``api_version``,
+                ``aws_*``, … — passed through verbatim.
 
         Returns:
             - stream=False: complete response dict ({'id', 'object', 'created',
@@ -512,14 +540,16 @@ class PageIndexClient:
                 enable_citations=enable_citations, model=model,
                 max_turns=max_turns, top_p=top_p, max_tokens=max_tokens,
                 reasoning_effort=reasoning_effort, extra_body=extra_body,
+                extra_headers=extra_headers, backend=backend,
             )
         if (model is not None or max_turns is not None or top_p is not None
                 or max_tokens is not None or reasoning_effort is not None
-                or extra_body is not None):
+                or extra_body is not None or extra_headers is not None
+                or backend is not None):
             raise PageIndexAPIError(
-                "model, max_turns, top_p, max_tokens, reasoning_effort and "
-                "extra_body are local-mode parameters — the cloud chat "
-                "endpoint selects its own model."
+                "model, max_turns, top_p, max_tokens, reasoning_effort, "
+                "extra_body, extra_headers and backend are local-mode "
+                "parameters — the cloud chat endpoint selects its own model."
             )
         return self._api.chat_completions(
             messages=messages, stream=stream, doc_id=doc_id,
@@ -540,6 +570,8 @@ class PageIndexClient:
         max_output_tokens: Optional[int] = None,
         reasoning: Optional[dict[str, Any]] = None,
         extra_body: Optional[dict[str, Any]] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+        backend: Optional[dict[str, Any]] = None,
     ) -> Union[dict[str, Any], Iterator[dict[str, Any]]]:
         """
         Document QA over the OpenAI Responses protocol — the agentic surface.
@@ -588,7 +620,15 @@ class PageIndexClient:
                 nothing (the backend's default applies).
             extra_body: Extra request fields beyond this method's
                 parameters, merged verbatim into the request body (last,
-                so they win).
+                so they win). Credentials belong in ``backend``, never
+                here.
+            extra_headers: Extra HTTP headers merged into each request;
+                caller headers win over defaults.
+            backend: Connection overrides for this call's backend client,
+                merged over the client's ``chat_backend`` (per-call keys
+                win). Keys are the openai SDK's client params —
+                ``api_key``, ``base_url``, ``organization``, … — passed
+                verbatim; unknown keys raise.
         """
         from .cloud_api import CloudAPI
         if isinstance(self._api, CloudAPI):
@@ -602,6 +642,7 @@ class PageIndexClient:
             instructions=instructions, temperature=temperature, top_p=top_p,
             max_turns=max_turns, max_output_tokens=max_output_tokens,
             reasoning=reasoning, extra_body=extra_body,
+            extra_headers=extra_headers, backend=backend,
         )
 
     def messages(
@@ -619,6 +660,8 @@ class PageIndexClient:
         max_turns: Optional[int] = None,
         thinking: Optional[dict[str, Any]] = None,
         extra_body: Optional[dict[str, Any]] = None,
+        extra_headers: Optional[dict[str, str]] = None,
+        backend: Optional[dict[str, Any]] = None,
     ) -> Union[dict[str, Any], Iterator[Any]]:
         """
         Document QA over the Anthropic Messages protocol — Claude-native.
@@ -658,6 +701,15 @@ class PageIndexClient:
                 constraints are the backend's. Unset sends nothing.
             extra_body: Extra request fields beyond this method's
                 parameters, merged verbatim into each request body.
+                Credentials belong in ``backend``, never here.
+            extra_headers: Extra HTTP headers merged into each request
+                (e.g. ``anthropic-beta`` feature flags); caller headers
+                win over defaults.
+            backend: Connection overrides for this call's backend client,
+                merged over the client's ``chat_backend`` (per-call keys
+                win). Keys are the anthropic SDK's client params —
+                ``api_key``, ``base_url``, ``auth_token``, … — passed
+                verbatim; unknown keys raise.
         """
         from .cloud_api import CloudAPI
         if isinstance(self._api, CloudAPI):
@@ -672,6 +724,7 @@ class PageIndexClient:
             temperature=temperature, top_p=top_p, top_k=top_k,
             stop_sequences=stop_sequences, max_turns=max_turns,
             thinking=thinking, extra_body=extra_body,
+            extra_headers=extra_headers, backend=backend,
         )
 
     # ---------- DOCUMENT MANAGEMENT ----------
@@ -825,7 +878,9 @@ class PageIndexClient:
         ``as_openai_tools`` as the tools; local clients also carry their
         configured ``chat_model`` (cloud omits ``model`` so the
         framework default applies). To customize further, switch to
-        those methods directly.
+        those methods directly. You run this config in your own
+        environment, so its model auth comes from there —
+        ``chat_backend`` does not travel with it.
 
         Args:
             doc_id: Document ID or list of IDs to target, as in
@@ -1107,7 +1162,10 @@ class PageIndexLocalClient(PageIndexClient):
         summary_model: Optional[str] = None,
         retrieve_model: Optional[str] = None,
         storage_path: Optional[str] = None,
+        index_backend: Optional[dict[str, Any]] = None,
+        chat_backend: Optional[dict[str, Any]] = None,
     ):
         super().__init__(None, index_model=index_model, chat_model=chat_model,
                          model=model, summary_model=summary_model,
-                         retrieve_model=retrieve_model, storage_path=storage_path)
+                         retrieve_model=retrieve_model, storage_path=storage_path,
+                         index_backend=index_backend, chat_backend=chat_backend)

{pageindex-0.2.10.dev4 → pageindex-0.2.10.dev5}/pageindex/local_api.py

@@ -35,14 +35,25 @@ class LocalAPI:
     """Backs PageIndexClient's local mode. One instance per client."""
 
     def __init__(self, storage_path: str, model: str, summary_model: str,
-                 retrieve_model: str):
+                 retrieve_model: str, index_backend: dict | None = None):
         self._store = DocStore(storage_path)
         self._model = model
         self._summary_model = summary_model
         self._retrieve_model = retrieve_model
+        self._index_backend = index_backend
         from .utils import ConfigLoader
         self._config_loader = ConfigLoader()
 
+    def _with_backend(self, func, *args):
+        """Scope the indexing lane's connection overrides around one
+        operation — runs inside whatever thread _run_indexer picked."""
+        from .utils import _llm_backend
+        token = _llm_backend.set(self._index_backend)
+        try:
+            return func(*args)
+        finally:
+            _llm_backend.reset(token)
+
     # ── indexing ──
 
     def submit_document(
@@ -104,11 +115,12 @@ class LocalAPI:
         try:
             if mode == "flash":
                 structure, description = _run_indexer(
-                    self._index_flash, file_path, page_texts
+                    self._with_backend, self._index_flash, file_path, page_texts
                 )
             else:
                 structure, description = _run_indexer(
-                    self._index_standard, file_path, page_texts
+                    self._with_backend, self._index_standard, file_path,
+                    page_texts
                 )
         except PageIndexAPIError:
             raise
@@ -183,11 +195,12 @@ class LocalAPI:
         from .utils import (add_node_text, create_clean_structure_for_description,
                             generate_doc_description, write_node_id)
         import litellm
-        env = litellm.validate_environment(self._summary_model)
-        if not env["keys_in_environment"]:
-            raise PageIndexAPIError(
-                f"Failed to submit document: missing API key for "
-                f"{self._summary_model}: {', '.join(env['missing_keys'])}")
+        if not self._index_backend:
+            env = litellm.validate_environment(self._summary_model)
+            if not env["keys_in_environment"]:
+                raise PageIndexAPIError(
+                    f"Failed to submit document: missing API key for "
+                    f"{self._summary_model}: {', '.join(env['missing_keys'])}")
         result = page_index_flash(file_path, summary=True,
                                   summary_model=self._summary_model,
                                   optimize="full",

{pageindex-0.2.10.dev4 → pageindex-0.2.10.dev5}/pageindex/local_chat.py

@@ -212,7 +212,7 @@ def _require_openai_agents(method: str) -> None:
         ) from exc
 
 
-def _openai_model(protocol: str, model_name: str):
+def _openai_model(protocol: str, model_name: str, backend=None):
     """The backend protocol driver — the seam tests replace with a fake.
 
     chat protocol: LiteLLM, full stop — model names mean what LiteLLM says
@@ -240,12 +240,12 @@ def _openai_model(protocol: str, model_name: str):
         import openai
         model_name = model_name.removeprefix("openai/")
         try:
-            backend = openai.AsyncOpenAI()
-        except openai.OpenAIError as exc:
+            sdk_client = openai.AsyncOpenAI(**(backend or {}))
+        except (openai.OpenAIError, TypeError) as exc:
             raise PageIndexAPIError(
                 f"The OpenAI backend is not configured: {exc}") from exc
         from agents.models.openai_responses import OpenAIResponsesModel
-        return OpenAIResponsesModel(model_name, openai_client=backend)
+        return OpenAIResponsesModel(model_name, openai_client=sdk_client)
     try:
         from agents.extensions.models.litellm_model import LitellmModel
         import litellm
@@ -258,12 +258,14 @@ def _openai_model(protocol: str, model_name: str):
     _repair_litellm_types()
     wire = model_name.removeprefix("litellm/")
     if "/" not in wire or wire.startswith("openai/"):
-        if not os.environ.get("OPENAI_API_KEY"):
+        if (not os.environ.get("OPENAI_API_KEY")
+                and not (backend or {}).get("api_key")):
             raise PageIndexAPIError(
                 "The OpenAI backend is not configured: set the "
-                "OPENAI_API_KEY environment variable (any value works "
-                "for keyless OPENAI_BASE_URL servers), or point "
-                "chat_model at another provider (e.g. 'anthropic/...')."
+                "OPENAI_API_KEY environment variable, pass an api_key "
+                "in chat_backend / backend (any value works for keyless "
+                "OPENAI_BASE_URL servers), or point chat_model at "
+                "another provider (e.g. 'anthropic/...')."
             )
     if "/" not in wire:
         wire = f"openai/{wire}"
@@ -276,7 +278,8 @@ def _openai_model(protocol: str, model_name: str):
             f"model id, use 'openai/{wire}' and point OPENAI_BASE_URL "
             "at the server."
         )
-    return LitellmModel(wire)
+    return LitellmModel(wire, api_key=(backend or {}).get("api_key"),
+                        base_url=(backend or {}).get("base_url"))
 
 
 def _reported_model(model_name: str) -> str:
@@ -307,10 +310,18 @@ def _cache_extra_args(model_name: str) -> Optional[dict]:
     return None
 
 
+def _merged_backend(client, backend):
+    """This call's connection overrides: the client's ``chat_backend``
+    under the per-call dict, per-call keys winning."""
+    merged = {**(getattr(client, "chat_backend", None) or {}),
+              **(backend or {})}
+    return merged or None
+
+
 def _openai_agent(client, protocol: str, model_name: str, instructions: str,
                   temperature, top_p, doc_ids=None, cache_key=None,
                   reasoning=None, reasoning_effort=None, extra_body=None,
-                  max_tokens=None):
+                  max_tokens=None, backend=None, extra_headers=None):
     from agents import Agent, ModelSettings
     from .integrations.openai_agents import build_openai_tools
     # ModelSettings.extra_body is the one channel all three engines put on
@@ -327,6 +338,16 @@ def _openai_agent(client, protocol: str, model_name: str, instructions: str,
     if reasoning_effort is not None:
         extra_args = {**(extra_args or {}),
                       "reasoning_effort": reasoning_effort}
+    conn = dict(backend) if backend else {}
+    if conn and protocol == "chat":
+        # LiteLLM takes connection params per call, except the two names
+        # LitellmModel pins as its own keywords — those ride its constructor.
+        lifted = {"api_key": conn.pop("api_key", None),
+                  "base_url": conn.pop("base_url", conn.pop("api_base", None))}
+        if conn:
+            extra_args = {**(extra_args or {}), **conn}
+        conn = {key: value for key, value in lifted.items()
+                if value is not None}
     body = ({"prompt_cache_key": cache_key}
             if cache_key and openai_backend else None)
     # Caller extras merge last, so they win over ours; non-OpenAI
@@ -340,11 +361,12 @@ def _openai_agent(client, protocol: str, model_name: str, instructions: str,
         name="PageIndex",
         instructions=instructions,
         tools=build_openai_tools(client, doc_ids=doc_ids),
-        model=_openai_model(protocol, model_name),
+        model=_openai_model(protocol, model_name, conn or None),
         model_settings=ModelSettings(
             temperature=temperature, top_p=top_p, max_tokens=max_tokens,
             reasoning=reasoning,
             extra_body=body,
+            extra_headers=extra_headers,
             extra_args=extra_args),
     )
 
@@ -492,6 +514,8 @@ def run_chat_completions(client, messages, stream: bool = False,
                          max_tokens: Optional[int] = None,
                          reasoning_effort: Optional[str] = None,
                          extra_body: Optional[dict] = None,
+                         extra_headers: Optional[dict] = None,
+                         backend: Optional[dict] = None,
                          ) -> Union[dict, Iterator[str], Iterator[dict]]:
     if enable_citations:
         raise PageIndexAPIError(
@@ -511,7 +535,9 @@ def run_chat_completions(client, messages, stream: bool = False,
                           cache_key=_conversation_cache_key(model_name,
                                                             managed, history),
                           reasoning_effort=reasoning_effort,
-                          extra_body=extra_body, max_tokens=max_tokens)
+                          extra_body=extra_body, max_tokens=max_tokens,
+                          backend=_merged_backend(client, backend),
+                          extra_headers=extra_headers)
     run_kwargs = _run_kwargs(max_turns)
     import openai
     from agents import Runner
@@ -601,6 +627,8 @@ def run_responses(client, input, model: Optional[str] = None,
                   max_output_tokens: Optional[int] = None,
                   reasoning: Optional[dict] = None,
                   extra_body: Optional[dict] = None,
+                  extra_headers: Optional[dict] = None,
+                  backend: Optional[dict] = None,
                   ) -> Union[dict, Iterator[dict]]:
     _require_openai_agents("responses")
     _validate_max_turns(max_turns)
@@ -624,7 +652,9 @@ def run_responses(client, input, model: Optional[str] = None,
                           cache_key=_conversation_cache_key(model_name, managed,
                                                             conversation),
                           reasoning=reasoning, extra_body=extra_body,
-                          max_tokens=max_output_tokens)
+                          max_tokens=max_output_tokens,
+                          backend=_merged_backend(client, backend),
+                          extra_headers=extra_headers)
     run_kwargs = _run_kwargs(max_turns)
     recorded: dict = {}
     import openai
@@ -759,10 +789,14 @@ def _require_anthropic() -> None:
         ) from exc
 
 
-def _anthropic_client():
+def _anthropic_client(backend=None):
     """The backend client — the seam tests replace with a fake transport."""
     import anthropic
-    return anthropic.Anthropic()
+    try:
+        return anthropic.Anthropic(**(backend or {}))
+    except TypeError as exc:
+        raise PageIndexAPIError(
+            f"The Anthropic backend is not configured: {exc}") from exc
 
 
 def _anthropic_system(extra_system, block: Optional[str]) -> list[dict]:
@@ -837,6 +871,8 @@ def run_messages(client, messages, model: str,
                  max_turns: Optional[int] = None,
                  thinking: Optional[dict] = None,
                  extra_body: Optional[dict] = None,
+                 extra_headers: Optional[dict] = None,
+                 backend: Optional[dict] = None,
                  ) -> Union[dict, Iterator[Any]]:
     from .integrations.anthropic_sdk import build_anthropic_tools
 
@@ -854,9 +890,10 @@ def run_messages(client, messages, model: str,
     passthrough = {key: value for key, value in {
         "temperature": temperature, "top_p": top_p, "top_k": top_k,
         "stop_sequences": stop_sequences, "thinking": thinking,
-        "extra_body": extra_body,
+        "extra_body": extra_body, "extra_headers": extra_headers,
     }.items() if value is not None}
-    runner = _anthropic_client().beta.messages.tool_runner(
+    runner = _anthropic_client(_merged_backend(client, backend)) \
+        .beta.messages.tool_runner(
         max_tokens=(max_tokens if max_tokens is not None
                     else _default_max_tokens(model)),
         messages=prepared,

{pageindex-0.2.10.dev4 → pageindex-0.2.10.dev5}/pageindex/page_index_classic.py

@@ -7,7 +7,6 @@ import re
 from .utils import *
 from .tree_optimize import merge_tree
 import os
-from concurrent.futures import ThreadPoolExecutor, as_completed
 
 ######################### Hardening for prompt injection patterns ####################################################
 _INJECTION_PATTERNS = re.compile(

{pageindex-0.2.10.dev4 → pageindex-0.2.10.dev5}/pageindex/utils.py

@@ -1,3 +1,4 @@
+import contextvars
 import logging
 import os
 import sys
@@ -21,6 +22,20 @@ import re
 # and fetches a remote model-cost map.
 
 
+# The indexing lane's connection overrides, scoped by LocalAPI around each
+# indexing operation — a contextvar, so the value reaches this module's
+# helpers and their asyncio tasks without threading it through every call.
+_llm_backend: contextvars.ContextVar = contextvars.ContextVar(
+    "pageindex_llm_backend", default=None)
+
+
+def _openai_sdk_kwargs(backend: dict) -> dict:
+    """The same backend dict works on both gateway paths: LiteLLM accepts
+    either endpoint spelling, the openai SDK only ``base_url``."""
+    return {("base_url" if key == "api_base" else key): value
+            for key, value in backend.items()}
+
+
 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
@@ -85,15 +100,21 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
             model = _strip_prefix(model, "openai/")
     max_retries = 10
     messages = list(chat_history) + [{"role": "user", "content": prompt}] if chat_history else [{"role": "user", "content": prompt}]
+    backend = _llm_backend.get()
     if use_openai_sdk:
-        global _openai_sync_client
-        if _openai_sync_client is None:
-            import openai
-            _openai_sync_client = openai.OpenAI(max_retries=0)
+        import openai
+        if backend:
+            oai_client = openai.OpenAI(**{"max_retries": 0,
+                                          **_openai_sdk_kwargs(backend)})
+        else:
+            global _openai_sync_client
+            if _openai_sync_client is None:
+                _openai_sync_client = openai.OpenAI(max_retries=0)
+            oai_client = _openai_sync_client
     for i in range(max_retries):
         try:
             if use_openai_sdk:
-                response = _openai_sync_client.chat.completions.create(
+                response = oai_client.chat.completions.create(
                     model=model,
                     messages=messages,
                 )
@@ -105,6 +126,7 @@ def llm_completion(model, prompt, chat_history=None, return_finish_reason=False)
                     messages=messages,
                     temperature=0,
                     drop_params=True,
+                    **(backend or {}),
                 )
             content = response.choices[0].message.content
             if return_finish_reason:
@@ -132,15 +154,21 @@ async def llm_acompletion(model, prompt):
             model = _strip_prefix(model, "openai/")
     max_retries = 10
     messages = [{"role": "user", "content": prompt}]
+    backend = _llm_backend.get()
     if use_openai_sdk:
-        global _openai_async_client
-        if _openai_async_client is None:
-            import openai
-            _openai_async_client = openai.AsyncOpenAI(max_retries=0)
+        import openai
+        if backend:
+            oai_client = openai.AsyncOpenAI(**{"max_retries": 0,
+                                               **_openai_sdk_kwargs(backend)})
+        else:
+            global _openai_async_client
+            if _openai_async_client is None:
+                _openai_async_client = openai.AsyncOpenAI(max_retries=0)
+            oai_client = _openai_async_client
     for i in range(max_retries):
         try:
             if use_openai_sdk:
-                response = await _openai_async_client.chat.completions.create(
+                response = await oai_client.chat.completions.create(
                     model=model,
                     messages=messages,
                 )
@@ -152,6 +180,7 @@ async def llm_acompletion(model, prompt):
                     messages=messages,
                     temperature=0,
                     drop_params=True,
+                    **(backend or {}),
                 )
             return response.choices[0].message.content
         except Exception as e:

{pageindex-0.2.10.dev4 → pageindex-0.2.10.dev5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pageindex"
-version = "0.2.10.dev4"
+version = "0.2.10.dev5"
 description = "Python SDK for PageIndex — reasoning-based, vectorless document retrieval, cloud and local"
 readme = "README.md"
 license = "MIT"