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.
This commit is contained in:
mountain 2026-05-15 17:03:17 +08:00
parent d7b36aaf3f
commit a47c36a3f5
13 changed files with 322 additions and 45 deletions

View file

@ -1,4 +1,4 @@
from pageindex.agent import AgentRunner, SYSTEM_PROMPT
from pageindex.agent import AgentRunner, OPEN_SYSTEM_PROMPT, SCOPED_SYSTEM_PROMPT
from pageindex.backend.protocol import AgentTools
@ -8,7 +8,13 @@ def test_agent_runner_init():
assert runner._model == "gpt-4o"
def test_system_prompt_has_tool_instructions():
assert "list_documents" in SYSTEM_PROMPT
assert "get_document_structure" in SYSTEM_PROMPT
assert "get_page_content" in SYSTEM_PROMPT
def test_open_prompt_has_tool_instructions():
assert "list_documents" in OPEN_SYSTEM_PROMPT
assert "get_document_structure" in OPEN_SYSTEM_PROMPT
assert "get_page_content" in OPEN_SYSTEM_PROMPT
def test_scoped_prompt_omits_list_documents():
assert "list_documents" not in SCOPED_SYSTEM_PROMPT
assert "get_document_structure" in SCOPED_SYSTEM_PROMPT
assert "get_page_content" in SCOPED_SYSTEM_PROMPT