feat(collection): doc_ids accepts str|list, design cleanups

- Collection.query and Backend.query/query_stream accept doc_ids as
  str, list[str] or None. Single str is normalized to [str] inside each
  backend; bare [] is rejected with ValueError at both layers.
- wrap_with_doc_context wraps the scoped doc list in <docs>...</docs>
  and SCOPED_SYSTEM_PROMPT instructs the agent to treat that block as
  data, not instructions (defense against prompt injection via
  auto-generated doc_description).
- _require_cloud_api now distinguishes api_key="" from api_key=None;
  the former gives a targeted error pointing at the empty-string vs
  fall-back-to-local situation when legacy SDK methods are called.
- Legacy PageIndexClient.list_documents docstring spells out the
  return-shape difference vs collection.list_documents() to flag a
  silent migration footgun (paginated dict with id/name keys vs plain
  list[dict] with doc_id/doc_name keys).
- Remove dead CloudBackend.get_agent_tools stub (not on the Backend
  protocol; only ever returned an empty AgentTools()) and the
  SYSTEM_PROMPT alias (OPEN_/SCOPED_SYSTEM_PROMPT are the explicit
  names now).
- README quick start and streaming example now pass doc_ids; new
  multi-document section shows both str and list forms.
- examples/demo_query_modes.py exercises all five query-mode cases
  (single-doc, multi-doc with/without env var, scoped single, scoped
  multi) for manual verification.

pageindex/backend/cloud.py

@@ -13,7 +13,6 @@ import urllib.parse
 import requests
 from typing import AsyncIterator
 
-from .protocol import AgentTools
 from ..errors import CloudAPIError, PageIndexError
 from ..events import QueryEvent
 
@@ -230,8 +229,15 @@ class CloudBackend:
 
     # ── Query (uses cloud chat/completions, no LLM key needed) ────────────
 
-    def query(self, collection: str, question: str, doc_ids: list[str] | None = None) -> str:
+    def query(self, collection: str, question: str,
+              doc_ids: str | list[str] | None = None) -> str:
         """Non-streaming query via cloud chat/completions."""
+        if isinstance(doc_ids, str):
+            doc_ids = [doc_ids]
+        elif doc_ids == []:
+            raise ValueError(
+                "doc_ids cannot be empty; pass None to query the whole collection"
+            )
         doc_id = doc_ids if doc_ids else self._get_all_doc_ids(collection)
         resp = self._request("POST", "/chat/completions/", json={
             "messages": [{"role": "user", "content": question}],
@@ -245,7 +251,7 @@ class CloudBackend:
         return resp.get("content", resp.get("answer", ""))
 
     async def query_stream(self, collection: str, question: str,
-                           doc_ids: list[str] | None = None) -> AsyncIterator[QueryEvent]:
+                           doc_ids: str | list[str] | None = None) -> AsyncIterator[QueryEvent]:
         """Streaming query via cloud chat/completions SSE.
 
         Events are yielded in real-time as they arrive from the server.
@@ -255,6 +261,12 @@ class CloudBackend:
         import asyncio
         import threading
 
+        if isinstance(doc_ids, str):
+            doc_ids = [doc_ids]
+        elif doc_ids == []:
+            raise ValueError(
+                "doc_ids cannot be empty; pass None to query the whole collection"
+            )
         doc_id = doc_ids if doc_ids else self._get_all_doc_ids(collection)
         headers = self._headers
         queue: asyncio.Queue[QueryEvent | None] = asyncio.Queue()
@@ -350,9 +362,3 @@ class CloudBackend:
         """Get all document IDs in a collection."""
         docs = self.list_documents(collection)
         return [d["doc_id"] for d in docs]
-
-    # ── Not used in cloud mode ────────────────────────────────────────────
-
-    def get_agent_tools(self, collection: str, doc_ids: list[str] | None = None) -> AgentTools:
-        """Not used in cloud mode — query goes through chat/completions."""
-        return AgentTools()

pageindex/backend/local.py

@@ -79,7 +79,9 @@ class LocalBackend:
             raise FileTypeError(f"Not a regular file: {file_path}")
         parser = self._resolve_parser(file_path)
 
-        # Dedup: skip if same file already indexed in this collection
+        # Dedup is content-only — same file is reused regardless of IndexConfig
+        # changes. If you've changed IndexConfig and need a fresh tree, delete
+        # the existing doc first or use a new collection.
         file_hash = self._file_hash(file_path)
         existing_id = self._storage.find_document_by_hash(collection, file_hash)
         if existing_id:
@@ -265,8 +267,20 @@ class LocalBackend:
             )
         return [by_id[did] for did in doc_ids]
 
-    def query(self, collection: str, question: str, doc_ids: list[str] | None = None) -> str:
+    @staticmethod
+    def _normalize_doc_ids(doc_ids: str | list[str] | None) -> list[str] | None:
+        if isinstance(doc_ids, str):
+            return [doc_ids]
+        if doc_ids == []:
+            raise ValueError(
+                "doc_ids cannot be empty; pass None to query the whole collection"
+            )
+        return doc_ids
+
+    def query(self, collection: str, question: str,
+              doc_ids: str | list[str] | None = None) -> str:
         from ..agent import AgentRunner, SCOPED_SYSTEM_PROMPT, wrap_with_doc_context
+        doc_ids = self._normalize_doc_ids(doc_ids)
         tools = self.get_agent_tools(collection, doc_ids)
         instructions = None
         if doc_ids:
@@ -277,8 +291,9 @@ class LocalBackend:
                            instructions=instructions).run(question)
 
     async def query_stream(self, collection: str, question: str,
-                           doc_ids: list[str] | None = None):
+                           doc_ids: str | list[str] | None = None):
         from ..agent import QueryStream, SCOPED_SYSTEM_PROMPT, wrap_with_doc_context
+        doc_ids = self._normalize_doc_ids(doc_ids)
         tools = self.get_agent_tools(collection, doc_ids)
         instructions = None
         if doc_ids:

pageindex/backend/protocol.py

@@ -28,7 +28,9 @@ class Backend(Protocol):
     def list_documents(self, collection: str) -> list[dict]: ...
     def delete_document(self, collection: str, doc_id: str) -> None: ...
 
-    # Query
-    def query(self, collection: str, question: str, doc_ids: list[str] | None = None) -> str: ...
+    # Query — doc_ids accepts a single id or a list; implementations should
+    # normalize internally (a bare str is treated as a single-element list).
+    def query(self, collection: str, question: str,
+              doc_ids: str | list[str] | None = None) -> str: ...
     async def query_stream(self, collection: str, question: str,
-                           doc_ids: list[str] | None = None) -> AsyncIterator[QueryEvent]: ...
+                           doc_ids: str | list[str] | None = None) -> AsyncIterator[QueryEvent]: ...