feat: introduce PageIndex SDK with Collection-based local/cloud API

[KylinMountain]

Summary

Turn PageIndex into a proper Python SDK. The repo currently exposes a tree-generation CLI (run_pageindex.py) and a legacy cloud HTTP wrapper (pageindex_sdk 0.2.x). This PR introduces a unified PageIndexClient with a Collection-based API that works in both local self-hosted mode (your LLM key) and cloud-managed mode (PageIndex API key), while keeping the legacy SDK callable on the same client for backward compatibility.

What's in the SDK

Public surface (from pageindex import PageIndexClient):

• PageIndexClient(api_key=...) — auto-detects cloud vs local
• client.collection(name) → Collection
• Collection.add / list_documents / get_document / get_document_structure / get_page_content / delete_document / query
• col.query(question, doc_ids=..., stream=...) — doc_ids accepts str | list[str] | None
• Streaming queries via async iterator over QueryEvent

Two execution paths behind the same API:

• Local: parser → index pipeline → SQLite storage → agent QA loop (OpenAI Agents SDK)
• Cloud: thin client over /chat/completions/, /doc/... endpoints

Legacy 0.2.x compatibility on the same PageIndexClient: all 12 methods (submit_document, get_ocr, get_tree, chat_completions, document & folder management) preserved as @deprecated wrappers, same signatures and return shapes.

Highlights

• feat: add PageIndex SDK with local/cloud dual-mode support #207 — Collection-based dual-mode SDK (local + cloud), pluggable parsers, agent QA, streaming
• feat:compatible with Pageindex SDK #238 — legacy pageindex_sdk 0.2.x methods on PageIndexClient (submit_document, chat_completions, etc.), with stream-close fixes and @deprecated migration markers
• fix: poll status=="completed" in cloud add_document #226 — cloud add_document polls status == "completed" instead of the unreliable retrieval_ready flag
• Collection.query polish (latest):
  • doc_ids accepts str | list[str] | None; empty list rejected at both Collection and Backend layers
  • Scoped mode (when doc_ids is provided): drops list_documents from the agent's tool set, hard-enforces whitelist on doc_id args, and injects doc summaries into the user message inside <docs> with system-prompt guidance treating it as data, not instructions (prompt-injection mitigation)
  • Collection.list_documents() now exposes doc_description so the agent can route to the right doc
  • doc_ids=None over a multi-doc collection emits a UserWarning (cross-doc retrieval is experimental; PAGEINDEX_EXPERIMENTAL_MULTIDOC=1 to silence). Single-doc skipped, empty collection raises ValueError
  • Legacy PageIndexClient.list_documents docstring spells out the return-shape difference vs Collection.list_documents(); clearer error when legacy methods are called after api_key=""
  • Agents SDK tracing upload disabled by default (PAGEINDEX_AGENTS_TRACING=1 re-enables)
• Examples: examples/local_demo.py, examples/cloud_demo.py, examples/demo_query_modes.py (5 query-mode cases)
• README: new "SDK Usage" section covering install, local/cloud quick start, streaming, multi-document collections
• Packaging: switch to Poetry, bump to 0.3.0.dev1, add dist/ to gitignore

Test plan

• pytest tests/ — 101 passed, 2 skipped
• examples/demo_legacy_sdk.py — all 7 legacy methods green against api.pageindex.ai
• examples/demo_query_modes.py — all 5 Collection.query modes (single/multi/scoped × 2, env-var silencing) green
• Manual verify install from a built wheel
• Verify CHANGELOG / docs reflect 0.3.0 surface before tagging

[KylinMountain]

Code review

Found 1 issue:

1. pyproject.toml declares no direct pydantic dependency, but pageindex/config.py imports from pydantic import BaseModel in production code. Pydantic is currently pulled in transitively via litellm, but a future litellm release (or a constrained resolver) could break installs with ModuleNotFoundError: pydantic. Add pydantic to [tool.poetry.dependencies].

PageIndex/pageindex/config.py

Lines 1 to 7 in 595895c

	# pageindex/config.py
	from __future__ import annotations
	from pydantic import BaseModel
	class IndexConfig(BaseModel):
	"""Configuration for the PageIndex indexing pipeline.

PageIndex/pyproject.toml

Lines 22 to 33 in 595895c

	[tool.poetry.dependencies]
	python = ">=3.10"
	litellm = ">=1.83.0"
	pymupdf = ">=1.26.0"
	PyPDF2 = ">=3.0.0"
	python-dotenv = ">=1.0.0"
	pyyaml = ">=6.0"
	openai = ">=1.70.0"
	openai-agents = ">=0.1.0"
	requests = ">=2.28.0"
	httpx = {extras = ["socks"], version = ">=0.28.1"}
	typing-extensions = ">=4.9.0"

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[BukeLy]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e00d360273

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[rejojer]

Code review 发现的问题

这次 review 主要发现 4 个需要处理的问题：

1. 云端上传会重试非幂等请求

   CloudBackend.add_document() 上传 /doc/ 时使用 _request() 的默认重试逻辑。这个请求不是幂等的：如果服务端已经收到文件并开始创建文档，但客户端看到的是超时、5xx 或 429，后续重试可能会再次创建同一份文档，导致重复索引和重复计费。建议这里改成 retries=1，或者为上传接口引入幂等 key。

2. max_concurrency 没有限制同步 LLM 调用

   当前并发限制只包住了 llm_acompletion() 的异步路径，但 llm_completion() 直接调用 litellm.completion()，没有经过同一个 _llm_semaphore()。索引流程里仍有同步 LLM 调用，例如文档描述生成和部分 TOC 处理。因此在并发索引多个文档时，实际 LLM 并发仍可能超过配置值。我本地用 set_max_concurrency(1) 做了小复现，同步调用峰值仍能到 3。

3. 云端 Collection 的文档操作没有校验 collection 归属

   CloudBackend.get_document()、get_document_structure()、get_page_content() 和 delete_document() 都接收了 collection 参数，但实际只按全局 doc_id 调云端接口。启用 folder/collection 后，如果调用者把另一个 collection 的 doc_id 传进来，SDK 会读取甚至删除那个文档，而不是拒绝操作。delete_document() 这里风险最高，建议先校验该 doc_id 属于当前 collection/folder 再执行。

4. README 里的 requirements.txt 安装路径已经过期

   README 仍然指导源码用户执行 pip3 install --upgrade -r requirements.txt，但 requirements.txt 没有同步本 PR 新增的运行时依赖，比如 pydantic、openai-agents、requests、httpx、typing-extensions 等。用户按 README 从源码安装后，import pageindex 或新 SDK 路径可能直接失败。建议同步 requirements.txt，或者移除/改写这条安装路径，统一推荐 pip install . / Poetry。

验证情况：

• python3 -m build 已验证可以成功构建 sdist 和 wheel。
• 针对 cloud/storage/parser/pipeline/types 的部分测试通过：74 passed, 2 skipped。
• legacy/env/architecture 相关测试通过：25 passed。
• 完整测试在当前本地环境没有跑完，原因是本机已安装的 openai-agents 与 openai/pydantic 版本组合导入时报错，属于环境依赖状态问题。

[rejojer]

代码审查

经 5 个独立审查代理交叉验证，共发现 12 个问题，按置信度排序如下：

---

问题 1（置信度 90）— requirements.txt 缺少新的运行时依赖

pyproject.toml 声明了 pydantic、openai-agents、httpx 和 typing-extensions 作为运行时依赖，但 requirements.txt（README 中记录的安装方式）未包含这些包（openai-agents 被注释掉了）。用户按照 README 执行 pip3 install --upgrade -r requirements.txt 后，会在导入时遇到 ModuleNotFoundError。

PageIndex/requirements.txt

Lines 1 to 6 in e00d360

	litellm==1.84.0
	# openai-agents # optional: required for examples/agentic_vectorless_rag_demo.py
	pymupdf==1.26.4
	PyPDF2==3.0.1
	python-dotenv==1.2.2
	pyyaml==6.0.2

---

问题 2（置信度 85）— llm_completion 失败行为变更，破坏 12+ 个调用方的优雅降级链

旧版 pageindex/utils.py 中的 llm_completion 在重试耗尽后返回 ""（使用 return_finish_reason=True 时返回 ("", "error")）。新版 pageindex/index/utils.py 改为抛出 RuntimeError。pageindex/index/page_index.py 中的多个调用方依赖原有的返回空字符串模式——将结果传入 extract_json()（对空字符串返回 {}），再调用 .get('key', 'no') 实现优雅降级。新的异常行为会导致这些调用方因未捕获的 RuntimeError 而崩溃。受影响的同步调用方包括：toc_detector_single_page（第 126 行）、check_if_toc_extraction_is_complete（第 145 行）、check_if_toc_transformation_is_complete（第 163 行）、detect_page_index（第 217 行）、toc_index_extractor（第 266 行）、add_page_number_to_toc（第 482 行）。此外，使用 return_finish_reason=True 的调用方（第 175、189、294、315、532、566 行）以二元组方式解构返回值，也会因异常而崩溃。该优雅降级链在 commit f413c66（PR #188）中被专门加固过。

PageIndex/pageindex/index/utils.py

Lines 129 to 157 in e00d360

	def llm_completion(model, prompt, chat_history=None, return_finish_reason=False):
	if model:
	model = model.removeprefix("litellm/")
	max_retries = 10
	messages = list(chat_history) + [{"role": "user", "content": prompt}] if chat_history else [{"role": "user", "content": prompt}]
	for i in range(max_retries):
	try:
	response = litellm.completion(
	model=model,
	messages=messages,
	# Per-call litellm kwargs (default temperature=0, drop_params=True);
	# configure via config.set_llm_params(...) — never the litellm global.
	**get_llm_params(),
	)
	content = response.choices[0].message.content
	if return_finish_reason:
	finish_reason = "max_output_reached" if response.choices[0].finish_reason == "length" else "finished"
	return content, finish_reason
	return content
	except Exception as e:
	logger.warning("Retrying LLM completion (%d/%d)", i + 1, max_retries)
	logger.error(f"Error: {e}")
	if i < max_retries - 1:
	time.sleep(1)
	else:
	logger.error('Max retries reached for prompt: ' + prompt)
	raise RuntimeError(f"LLM call failed after {max_retries} retries") from e

---

问题 3（置信度 72）— 系统提示词引用了 get_document 不返回的字段

OPEN_SYSTEM_PROMPT 和 SCOPED_SYSTEM_PROMPT 都指示 agent "Call get_document(doc_id) to confirm status and page/line count"，但该工具调用的是 _require_document()，其 SQL 查询仅返回 doc_id、doc_name、doc_description、file_path、doc_type，不包含 status、page_count 或 line_count。同样的文案在 examples/agentic_vectorless_rag_demo.py 中已修正为 "confirm the document's name and type"，但 agent.py 中的两处未同步更新。LLM 不会崩溃，但会尝试查找不存在的字段，导致 QA 质量下降。

PageIndex/pageindex/agent.py

Lines 22 to 24 in e00d360

	- Call list_documents() to see available documents; use doc_name and doc_description to pick which doc(s) are relevant.
	- Call get_document(doc_id) to confirm status and page/line count.
	- Call get_document_structure(doc_id) to identify relevant page ranges.

---

问题 4（置信度 65）— get_page_content 工具未捕获 ValueError

pageindex/backend/local.py 中 get_agent_tools 的 get_page_content 闭包仅捕获 DocumentNotFoundError，未捕获 parse_pages() 在收到畸形页码参数（如 "all"、"5-"、"abc"）时抛出的 ValueError。旧版 retrieve.py 正确捕获了 (ValueError, AttributeError)，这是一个回归。实际影响较低，因为 LLM agent 很少传入畸形参数。

PageIndex/pageindex/backend/local.py

Lines 270 to 282 in e00d360

	def get_document(doc_id: str) -> str:
	"""Get document metadata."""
	rejection = _reject(doc_id)
	if rejection:
	return rejection
	try:
	# _require_document (not backend.get_document) deliberately:
	# the metadata-only row, no 'structure' — keeps this tool's
	# output small for the agent's context window.
	doc = backend._require_document(col_name, doc_id)
	except DocumentNotFoundError:
	return json.dumps({"error": f"doc_id '{doc_id}' not found."})
	return json.dumps(doc)

---

问题 5（置信度 55）— if_add_doc_description 默认值静默变更

旧版 config.yaml 中 if_add_doc_description 默认为 "no"，新版 IndexConfig 默认为 True。这会导致升级后自动触发额外的 LLM 调用（增加成本和延迟），且无迁移说明。不过这看起来是有意的产品决策，README 也已同步更新。

---

问题 6（置信度 50）— stream_metadata 标志未发送到服务器端

LegacyCloudAPI.chat_completions 接受 stream_metadata 参数，但仅在本地切换解析器，从未将该标志加入发送给服务器的 payload。CloudBackend 中的对应方法正确发送了该字段。测试 test_chat_completions_stream_metadata_returns_raw_chunks 甚至断言 "stream_metadata" not in calls[0]["json"]，将此遗漏固化为预期行为。此问题源于 PR #238，非本 PR 引入。

PageIndex/pageindex/cloud_api.py

Lines 130 to 165 in e00d360

	def chat_completions(
	self,
	messages: list[dict[str, str]],
	stream: bool = False,
	doc_id: str | list[str] | None = None,
	temperature: float | None = None,
	stream_metadata: bool = False,
	enable_citations: bool = False,
	) -> dict[str, Any] | Iterator[str] | Iterator[dict[str, Any]]:
	payload: dict[str, Any] = {
	"messages": messages,
	"stream": stream,
	}
	if doc_id is not None:
	payload["doc_id"] = doc_id
	if temperature is not None:
	payload["temperature"] = temperature
	if enable_citations:
	payload["enable_citations"] = enable_citations
	response = self._request(
	"POST",
	"/chat/completions/",
	"Failed to get chat completion",
	json=payload,
	stream=stream,
	)
	if stream:
	if stream_metadata:
	return self._stream_chat_response_raw(response)
	return self._stream_chat_response(response)
	return response.json()
	def _stream_chat_response(self, response: requests.Response) -> Iterator[str]:

---

问题 7（置信度 42）— GitHub Actions 发布工作流存在命令注入风险

.github/workflows/publish.yml 中，$VERSION（来自 git tag）被直接插入 python -c 和 sed 命令。精心构造的 tag 名可在 CI runner 中执行任意代码。但仅有仓库写权限的用户才能创建 tag，实际风险较低。建议使用环境变量传递版本号。

PageIndex/.github/workflows/publish.yml

Lines 50 to 56 in e00d360

	sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml
	grep '^version = ' pyproject.toml
	python -m build
	- name: Publish to PyPI
	uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1.14.0

---

问题 8（置信度 40）— QueryEvent.type 包含 "reasoning" 但无代码发出该事件

events.py 中 QueryEvent.type 的 Literal 包含 "reasoning"，但 agent.py 和 cloud.py 中均无代码发出该类型的事件，README 也仅记录了 4 种事件类型。这是一个预留但未实现的变体，无功能影响。

---

问题 9（置信度 40）— 云端 delete_document 不按 collection 限定范围

CloudBackend.delete_document 接受 collection 参数但完全忽略，仅按 doc_id 删除。如果误传了属于其他 collection 的 doc_id，会删除无关文档。维护者已确认此问题并刻意推迟，等待云端 workspace API 最终确定。

---

问题 10（置信度 30）— 云端 get_page_content 丢弃 image 元数据

CloudBackend.get_page_content 仅重建 page 和 content 字段，如果云端 OCR 响应包含 images 字段会被静默丢弃。本地后端保留了该字段。但无证据表明云端 API 目前返回 images 数据。

---

问题 11（置信度 20）— LegacyCloudAPI.delete_document 对空响应体调用 .json()

如果 DELETE API 返回 200 但 body 为空，会抛出 json.JSONDecodeError。CloudBackend._request 已正确处理（resp.json() if resp.content else {}），但 legacy 层未修复。此问题源于 PR #238，非本 PR 引入。

---

问题 12（置信度 15）— 误报：SSE 解析器在 choices: null 时崩溃

经验证为误报。虽然 .get("choices", []) 在 key 值为 null 时返回 None，但代码中所有 choices[0] 访问都被 if choices 或三元表达式保护，None 作为 falsy 值会正确短路，不会触发 TypeError。

---

🤖 Generated with Claude Code

_{- 如果此代码审查有帮助，请点 👍。否则请点 👎。}

[rejojer]

Code Review Findings

Reviewed 66 changed files at max effort (64 agents, 56 candidates found, 46 survived adversarial verification, 15 reported).

---

🔴 Critical — Crashes / Data Corruption

1. pageindex/index/utils.py:157 — LLM retry exhaustion now crashes the pipeline
llm_completion / llm_acompletion changed from returning "" on max-retry exhaustion to raising RuntimeError. None of the ~12 callers (toc_transformer, extract_toc_content, toc_detector_single_page, etc.) handle this exception. A transient LLM outage lasting longer than 10 retries now crashes the entire page_index() call instead of continuing with partial/degraded output.

2. pageindex/storage/sqlite.py:214 — Thread-safety bug in close()
close() only deletes the calling thread's self._local.conn attribute. Other threads' threading.local() conn attributes survive — if those threads later call _get_conn(), hasattr(self._local, 'conn') is True and returns the closed connection, causing sqlite3.ProgrammingError: Cannot operate on a closed database.

3. pageindex/backend/local.py:259 — Empty-list doc_ids bypasses security scope
set(doc_ids) if doc_ids else None treats doc_ids=[] as falsy (= None = open mode). Calling get_agent_tools(collection, doc_ids=[]) directly gives the agent list_documents with no scope restriction — access to every document instead of none.

4. pageindex/index/utils.py:132 — Sync LLM calls bypass concurrency semaphore
llm_completion (sync path) never acquires _llm_semaphore — only llm_acompletion (async) is bounded. With if_add_doc_description=True (new default), generate_doc_description uses sync llm_completion. Multiple threads indexing concurrently run uncapped, exceeding max_concurrency and hitting provider rate limits.

5. pageindex/index/utils.py:55 — Semaphore replacement orphans in-flight permits
set_max_concurrency() replaces the Semaphore object. In-flight coroutines still hold permits on the old (discarded) semaphore and will release() on it, not the new one. Effective concurrency briefly exceeds the intended cap.

---

🟠 Backward-Incompatible Changes (silent breakage for existing users)

6. pageindex/index/utils.py:875 — config.yaml no longer loaded from disk
ConfigLoader no longer reads config.yaml. Users who customized it (e.g. changing model or toc_check_page_num) will have their overrides silently ignored — the system uses IndexConfig's hardcoded defaults instead.

7. pageindex/config.py:29 — if_add_doc_description default flipped from False to True
Legacy callers using page_index() without explicitly passing this flag now get doc descriptions generated (extra LLM calls, increased cost/latency, different output shape with doc_description key).

8. pageindex/retrieve.py:46 — Markdown page-content retrieval semantics changed
Old code: range-based matching (all nodes with line_num in [min, max]). New code: exact-match only. get_page_content(docs, doc_id, '5,20') previously returned all nodes between lines 5–20; now returns only nodes at exactly line 5 and line 20, silently dropping everything in between.

---

🟡 Cloud Backend Issues

9. pageindex/backend/cloud.py:157 — list_collections missing 403/404 handling
Does not handle _FOLDER_UNAVAILABLE for plans without folder support, unlike create_collection, get_or_create_collection, _get_folder_id, and delete_collection which all gracefully return empty results.

10. pageindex/backend/cloud.py:208 — doc_type hardcoded as 'pdf'
get_document and list_documents always return doc_type='pdf' regardless of actual file type. Downstream code branching on doc_type (page-number vs line-number semantics) misclassifies Markdown docs.

11. pageindex/cloud_api.py:88 — Python bool capitalization in URL query params
get_tree interpolates Python True/False into URL, producing summary=True (capital T) instead of summary=true. If the API is case-sensitive (common), summaries are silently omitted. The newer CloudBackend correctly passes lowercase 'true'.

---

🟡 Parser Issue

12. pageindex/parser/markdown.py:38 — Code fence type not tracked
A backtick-opened fence can be "closed" by a tilde line (and vice versa), violating CommonMark spec. Lines inside the still-open fence are then incorrectly parsed as headings.

---

💡 Cleanup / Performance

13. pageindex/backend/cloud.py:187 — add_document blocks thread up to 10 minutes
Uses time.sleep(5) in a 120-iteration polling loop. In web server or async contexts, this starves the event loop / thread pool.

14. pageindex/backend/cloud.py:239 — get_page_content fetches all pages then filters client-side
For a 500-page PDF requesting pages 5–7, the entire OCR result is downloaded and filtered locally, wasting bandwidth and memory.

15. pageindex/client.py:53 — BASE_URL defined three times
PageIndexClient.BASE_URL, LegacyCloudAPI.BASE_URL, and cloud.API_BASE are independent copies of 'https://api.pageindex.ai'. Changing the URL for staging or migration requires updating all three.

---

Automated review by Claude Code — 64 agents, max effort.

[KylinMountain]

Code review 发现的问题

这次 review 主要发现 4 个需要处理的问题：

1. 云端上传会重试非幂等请求
   CloudBackend.add_document() 上传 /doc/ 时使用 _request() 的默认重试逻辑。这个请求不是幂等的：如果服务端已经收到文件并开始创建文档，但客户端看到的是超时、5xx 或 429，后续重试可能会再次创建同一份文档，导致重复索引和重复计费。建议这里改成 retries=1，或者为上传接口引入幂等 key。
2. max_concurrency 没有限制同步 LLM 调用
   当前并发限制只包住了 llm_acompletion() 的异步路径，但 llm_completion() 直接调用 litellm.completion()，没有经过同一个 _llm_semaphore()。索引流程里仍有同步 LLM 调用，例如文档描述生成和部分 TOC 处理。因此在并发索引多个文档时，实际 LLM 并发仍可能超过配置值。我本地用 set_max_concurrency(1) 做了小复现，同步调用峰值仍能到 3。
3. 云端 Collection 的文档操作没有校验 collection 归属
   CloudBackend.get_document()、get_document_structure()、get_page_content() 和 delete_document() 都接收了 collection 参数，但实际只按全局 doc_id 调云端接口。启用 folder/collection 后，如果调用者把另一个 collection 的 doc_id 传进来，SDK 会读取甚至删除那个文档，而不是拒绝操作。delete_document() 这里风险最高，建议先校验该 doc_id 属于当前 collection/folder 再执行。
4. README 里的 requirements.txt 安装路径已经过期
   README 仍然指导源码用户执行 pip3 install --upgrade -r requirements.txt，但 requirements.txt 没有同步本 PR 新增的运行时依赖，比如 pydantic、openai-agents、requests、httpx、typing-extensions 等。用户按 README 从源码安装后，import pageindex 或新 SDK 路径可能直接失败。建议同步 requirements.txt，或者移除/改写这条安装路径，统一推荐 pip install . / Poetry。

验证情况：

• python3 -m build 已验证可以成功构建 sdist 和 wheel。
• 针对 cloud/storage/parser/pipeline/types 的部分测试通过：74 passed, 2 skipped。
• legacy/env/architecture 相关测试通过：25 passed。
• 完整测试在当前本地环境没有跑完，原因是本机已安装的 openai-agents 与 openai/pydantic 版本组合导入时报错，属于环境依赖状态问题。

1. 不建议修复，当前云端也没有做幂等，该问题不建议子啊当前PR修复
2. 修复
3. 当前PR 不包含云端folder的功能，会在后续的PR中实现。
4. 修复。

[KylinMountain]

问题 1（置信度 90）— requirements.txt 缺少新的运行时依赖

✅ 已修复 1dffa76：补齐 pydantic、requests、typing-extensions、openai、httpx[socks]（openai-agents 仍按 README 保持可选）。已在只装 requirements.txt 的干净 venv 里验证 import pageindex + legacy API 正常。

问题 2（置信度 85）— llm_completion 失败行为变更，破坏优雅降级链

✅ 已修复 9ad7c68：改回耗尽后返回空结果（"" / ("", "error")），并打 WARNING 日志（不再静默）；异步 gather 站点保留 return_exceptions=True 兜底。单次持续失败不再阻断整份索引。

问题 3（置信度 72）— 系统提示词引用了 get_document 不返回的字段

✅ 已修复 e18ccde：OPEN_/SCOPED_SYSTEM_PROMPT 两处均改为 "confirm the document's name and type"（与 demo 一致）。

问题 4（置信度 65）— get_page_content 工具未捕获 ValueError

✅ 已修复 56fc3bf：捕获 (ValueError, AttributeError)，返回可操作的 "Invalid pages format..." 错误，模型可自行纠正。

问题 5（置信度 55）— if_add_doc_description 默认值静默变更

🟢 有意为之，不改：新 SDK 的默认，README 已同步（"on by default"）。

问题 6（置信度 50）— stream_metadata 标志未发送到服务器端

✅ 已修复 4c7d108：转发 stream_metadata 到 payload，并把此前固化旧行为的测试断言翻转。

问题 7（置信度 42）— GitHub Actions 命令注入风险

🟢 不修：推 tag 需仓库写权限，且不带来超出"能推 tag 者已有权限"的提权；触发器是 push: tags，非不可信的 fork 输入。

问题 8（置信度 40）— QueryEvent.type 含 "reasoning" 但无代码发出

🕒 暂不处理：预留但未实现的枚举值，无功能影响。

问题 9（置信度 40）— 云端 delete_document 不按 collection 限定

🕒 推迟：等云端 workspace API 定稿后在后续 PR 处理。

问题 10（置信度 30）— 云端 get_page_content 丢弃 image 元数据

✅ 已修复 4456b92：透传 images（空则省略）。实测真实 OCR 端点确实返回 images 字段。

问题 11（置信度 20）— LegacyCloudAPI.delete_document 对空响应体调用 .json()

✅ 已修复 fc401c9：response.json() if response.content else {}。

问题 12（置信度 15）— 误报：SSE 解析器在 choices: null 时崩溃

⚪ 确认误报，无需处理。

[KylinMountain]

Thanks for the max-effort pass — went through all 15 against current dev.

1. LLM retry exhaustion now crashes the pipeline

✅ Fixed 9ad7c68 — restored the empty-result contract ("" / ("", "error")) on exhaustion, now logged at WARNING so it's visible rather than silent. The async gather sites keep return_exceptions=True. A single persistently-failing call no longer aborts the whole index.

2. Thread-safety bug in close()

🕒 Low-impact edge, deferred. close() already closes all tracked connections (not just the caller's). The residual is a stale thread-local reference returning a closed conn on use-after-close from another thread — but close() only runs via __exit__/__del__, so this isn't reachable in normal lifecycle. Will harden with a closed-flag if it ever bites.

3. Empty-list doc_ids bypasses security scope

✅ Fixed d97231b — set(doc_ids) if doc_ids is not None else None, so [] is a scope of nothing (rejects every doc), not open mode. (The public query/query_stream path already guarded [] via _normalize_doc_ids; this hardens direct get_agent_tools callers.)

4. Sync LLM calls bypass concurrency semaphore

✅ Fixed 56590c6 — llm_completion now acquires the same process-wide cap as the async path; follow-up d3ea9b9 fixed a scoped-semaphore over-release on cancellation.

5. Semaphore replacement orphans in-flight permits

🟢 Accepted tradeoff — resizing happens only on an explicit set_max_concurrency() config change, never on the hot path (documented in the code). Not worth the added machinery to make config-time resizing atomic.

6. config.yaml no longer loaded from disk

🟢 Intentional — the new SDK deprecates config.yaml in favor of IndexConfig (noted in ConfigLoader's docstring). Not a silent regression.

7. if_add_doc_description default flipped False → True

🟢 Intentional SDK default, documented in the README ("on by default").

8. Markdown page-content retrieval semantics changed

🟢 Not a regression — matches parse_pages semantics (, = specific pages, - = range which expands to the full list) and the PDF path. '5,20' correctly means "lines 5 and 20"; use '5-20' for the range.

9. list_collections missing 403/404 handling

🕒 Deferred — part of the cloud folder/workspace surface that's waiting on the finalized API; will align in the follow-up PR.

10. doc_type hardcoded as 'pdf'

🕒 Deferred — same cloud-workspace follow-up; will surface the real type once the API exposes it.

11. Python bool capitalization in URL query params

✅ Fixed d97231b — legacy get_tree now sends summary=true/false (lowercase), matching the modern CloudBackend.

12. Code fence type not tracked

✅ Fixed d97231b — the parser now tracks the opening fence char, so a ``` fence is closed only by ``` (and ~~~ only by ~~~); #-lines inside a still-open block stay out of the headings.

13. add_document blocks thread up to 10 minutes

🕒 By design for the synchronous "index and wait" call; use query_stream/the async path where non-blocking matters. Low priority.

14. get_page_content fetches all pages then filters client-side

🕒 The cloud OCR endpoint returns the whole document (no page-range parameter), so filtering is client-side by necessity. Low priority pending an API-side range filter.

15. BASE_URL defined three times

✅ Fixed d97231b — single API_BASE in cloud_api, referenced by CloudBackend and PageIndexClient.

[chatgpt-codex-connector]

To use Codex here, create a Codex account and connect to github.

[rejojer]

Max-effort 复审 — 15 项发现（已逐条对照当前 dev HEAD 核实）

来自一轮 max 级别的多 agent 审查：6 个 finder 产出 50 个候选，经独立验证驳回 12 个，报告其中最重要的 15 项。每项标注了验证结论（CONFIRMED = 已按代码路径确认，PLAUSIBLE = 机制成立但依赖云 API 实际返回形状）。

---

✅ 已在 dev 上修复 / 复核后无需修改（3 项）

1. 旧 SDK 本地方法被移除（client.py）— ✅ 已修复：@_legacy_sdk deprecated shim 已恢复 index() / get_document() / get_page_content() 等方法。

2. BASE_URL 与 API_BASE 重复定义（client.py:54）— ✅ 已修复：现在 BASE_URL = API_BASE，单一来源在 cloud_api。

3. MD 检索从区间语义变为精确匹配（retrieve.py:46 → index/utils.py:606）— 复核结论：这是正确的修正，无需改代码。parse_pages 会展开 '5-100' 这类连字符区间，所以两种语义对区间输入完全等价；唯一差异是逗号分隔的离散值（'5,100'）——旧版错误地返回了整个 [5,100] 区间，新版只返回这两行，与 PDF 路径一致（docstring 已注明意图）。建议在 changelog 里提一句这个行为差异。

---

🔴 会崩溃，建议必修（2 项，CONFIRMED）

4. index/utils.py:523 — _get_text_of_pages 无越界检查

for page_num in range(start_page - 1, end_page):
    text += page_list[page_num][0]   # LLM 生成的 end_index 超页数 → IndexError

start_index / end_index 来自 LLM 生成的 physical_index，越界时 get_document(include_text=True) 或索引管线的摘要生成直接崩溃。建议 clamp：start = max(start_page, 1)、end = min(end_page, len(page_list))。
⚠️ 注意与第 15 项联动：get_text_of_pdf_pages（utils.py:833）是同一函数的逐字节拷贝，修的时候建议先合并，否则要改两处。

5. backend/cloud.py:223/237 — _normalize_tree(None) TypeError

raw_tree = resp.get("tree", resp.get("structure", resp.get("result", [])))

当 API 返回显式 {"tree": null} 时（key 存在、值为 null），.get() 返回 None 而不是 fallback，_normalize_tree 里 for node in nodes 直接 TypeError。建议末尾加 or []，或在 _normalize_tree 开头加 if not nodes: return []。

---

🟡 升级兼容性，需要设计决策（2 项，CONFIRMED）

6. client.py — api_key 参数语义静默变更

旧版：api_key 是 OpenAI key（os.environ["OPENAI_API_KEY"] = api_key，走本地模式）。
新版：任何非 None 的 api_key 都路由到云端模式。老用户传 api_key="sk-..." 会拿 OpenAI key 去调 PageIndex 云 API，得到一个莫名其妙的鉴权失败。

建议（两层互补，均不依赖猜 key 前缀）：

• 云端返回 401/403 时，错误信息里明确说明语义变更："api_key 现在是 PageIndex cloud key；本地模式请省略 api_key 并设置 OPENAI_API_KEY"（成本极低，建议无条件加）；
• 可选：过渡期新增 cloud_api_key 参数承接云端语义，api_key 保留旧行为 + DeprecationWarning，下个大版本移除。

7. client.py — workspace 参数被移除，且旧 JSON 数据无迁移路径

问题分两层：

• 老用户传 workspace=... 直接 TypeError；
• 即使改成 storage_path 指向同一目录，新版只认 SQLite（pageindex.db），不会读旧的 <doc_id>.json + _meta.json——所有已索引文档需要重新烧 token 重建。

建议：workspace 作为 storage_path 的 deprecated 别名（几乎零成本）；数据层面提供显式迁移函数（如 migrate_workspace(old_dir, client)），检测到目录里有 _meta.json 时提示用户运行。旧格式很简单，迁移代码约几十行。也可考虑利用现有 StorageEngine 协议做一个只读的 LegacyJSONStorage 适配器（旧数据挂到 default collection 下）。

---

🟠 防御性修复，成本都很低（3 项，PLAUSIBLE）

8. backend/cloud.py:257 — 页码过滤无类型强转

if p.get("page", p.get("page_index")) in page_nums   # API 返回 "5"（str）时永远匹配不上 {5,6,7}（int）

若云 API 返回字符串页码，get_page_content 静默返回空列表。一行 int() 强转（包 try）即可免疫。

9. backend/cloud.py:109/126/155 — folder_id 缓存把 None 当有效值

self._folder_id_cache[name] = resp.get("folder", {}).get("id") —— 若 POST /folder/ 返回平铺结构（{"id": ..., "name": ...} 而非嵌套在 "folder" 下），缓存存入 None；后续 add_document / list_documents 因 if folder_id: 全部省略 folder_id，文档静默落入全局空间、列表返回所有文档。另外 :155 处"名字未找到"也缓存 None，与"该 plan 不支持 folders"共用同一个哨兵值，会永久压制后续查找。建议：只缓存真值；取不到 folder.id 时回退尝试顶层 resp.get("id")，两者都取不到时 raise 而不是静默降级。

10. agent.py:68 — doc_id 插入 prompt 未经 _defang_delimiters

line = f"- {d['doc_id']}: {_defang_delimiters(d.get('doc_name', ''))}"   # doc_name 过了，doc_id 没过

云端返回的 doc_id 若含 </docs> 可提前闭合信任边界实现 prompt 注入。一行修复：_defang_delimiters(str(d['doc_id']))。

---

⚪ 清理项，不紧急（4 项）

11. 云端 query 双重 list_documents（collection.py:128 + cloud.py:321/497）— guard 与 warning 已合并为一次调用（👍），但跨层重复仍在：Collection.query 为 guard 查一次，doc_ids=None 传下去后 CloudBackend._get_all_doc_ids 又完整分页查一次。最常见的"查整个 collection"路径每次多一轮 HTTP。可让 Collection 层把已取到的 doc id 列表直接传下去。

12. doc_ids 标准化逻辑 ×4（collection.py:119、cloud.py:315/350、local.py:346）— str→list、空列表报错的逻辑复制了四份，将来改行为要同步四处。建议抽一个共享 helper。

13. _validate_collection_name ×3（sqlite.py:18、local.py:49、cloud.py:90）— 三份相同实现，建议收敛到一处。

14–15. get_text_of_pdf_pages（utils.py:833）≡ _get_text_of_pages（utils.py:523） — 同文件内逐字节重复，且都带第 4 项的越界问题。建议合并后统一修。

---

另有 12 个候选在验证阶段被驳回（含 SQLite 连接泄漏、__init__ 通配导入污染、OCR format 参数注入等），确认为误报，未列出。

[rejojer]

跟进 之前的 max-effort 复审：3ff04d5 已推到 dev，修复了其中可直接修的项；两个兼容性问题经过考证后定案为不做兼容（理由见下）。

3ff04d5 修复的项

复审条目	修复
4 _get_text_of_pages 越界	循环范围 clamp 到 [1, len(page_list)]；同模式的 get_text_of_pdf_pages_with_labels 一并 clamp
14–15 get_text_of_pdf_pages 重复	改为转调 _get_text_of_pages，越界修复只需一处
5 _normalize_tree(None)	开头 if not nodes: return []；验证时发现同类未防护点又补了 4 处——folders 迭代 ×3、documents 分页 ×1（API 对这些 key 返回显式 null 同样会 TypeError）
8 页码类型不匹配	_as_int() 强转后再比较，转不了则跳过；返回的 page 字段统一为 int（对齐 PageContent.page: int）
9 folder 缓存存 None	新增 _create_folder()：响应缺 folder.id 时 raise（PageIndexError，不会被 except CloudAPIError 吞掉）；_get_folder_id 查不到名字不再缓存，folder 后建后可被发现。403/404 "plan 不支持" 的哨兵缓存保持原样
10 doc_id 未 defang	wrap_with_doc_context 中 doc_id 过 _defang_delimiters
6（部分）	401 错误信息统一追加提示："api_key 是 PageIndex cloud key，本地模式请设 LLM provider 的环境变量"。覆盖三条路径：CloudBackend._request、LegacyCloudAPI._request、query_stream 的流式 POST。特意只挂 401 不挂 403——本代码库将 403 定义为 plan 限制（_FOLDER_UNAVAILABLE），key 正确的用户收到 key 提示是误导
7（收尾）	删除 examples/workspace/ 里旧 JSON 格式的示例数据（_meta.json + 文档 JSON）。dev 上两个 demo 的 storage_path 都指向该目录，旧文件是 SQLite 存储读不了的死数据，留着会让 demo 用户在空库旁边看到误导性的遗留文件

两个兼容性问题的定案

6. api_key 语义变更 → 不做旧语义兼容。 考证结论：api_key=<OpenAI key> 这个用法在整个仓库历史中（全部分支、全部 commit）从未出现在任何 README、demo、cookbook 或 docstring 中——唯一存在过的地方就是 main 上 client.py 的实现代码本身，仓库内调用者为零（demo 只传 workspace）。cookbook 里所有 api_key= 示例传的都是 PageIndex key（PyPI SDK 语义）。已发布的 0.2.x SDK 契约优先，开源侧未发版的隐藏行为不构成兼容义务。残留措施就是上面的 401 提示。

7. workspace 参数移除 → 不做兼容检测/迁移。 考证结论：JSON workspace 存储从未进过任何 PyPI 发行版，唯一使用者是仓库自己的 demo，而 dev 上的 demo 已改用 storage_path。为一个只有 demo 用过的参数在产品代码里加检测不值得；直接删掉遗留数据即可。建议 0.3.0 release notes 里加一句："本地存储改为 SQLite，旧 demo 的 JSON workspace 数据不再可读，需重新索引"。

验证

每个修复有针对性单元测试（含 clamp 前后在合法输入上的逐一等价性比对）；另跑了一轮独立的对抗式审查（其发现的流式 401 路径遗漏和 403 误导问题已在本 commit 中修正）；全测试套件与修复前的 HEAD 对照运行，通过/失败完全一致（12 个失败为既有的 openai-agents/pydantic 环境不兼容，与本改动无关）。

未处理（可选清理项，留待后续）

复审条目 11–13：云端 query 的双重 list_documents、doc_ids 标准化 ×4、_validate_collection_name ×3。均为重复代码/多余请求，不影响正确性。

另外验证中发现一个与条目 4 同类的既有问题供参考：page_index.py 的 check_title_appearance 用 LLM 输出直接索引 page_list，无 clamp（上界越界被 gather(return_exceptions=True) 吞掉，下界负索引会静默读错页）。未在本 commit 处理。

[rejojer]

补充一个复审时漏判的兼容性问题：config.yaml 的移除应该做兼容，和 api_key / workspace 两个"不做兼容"的定案不是一类。

为什么这个不一样

前两个定案的依据是"未文档化、仓库内零调用、发现它得翻源码"。config.yaml 不满足这个条件：

• README 主推的用法就是 python3 run_pageindex.py --pdf_path ...——CLI 是这个开源仓库最大用户群的标准工作流，而 config.yaml 就是它的配置入口
• 文件内容本身就是设计给用户改的——里面留着 # model: "anthropic/claude-sonnet-4-6" 这类注释掉的备选项，等于邀请编辑
• 当前 dev 上的行为：手改过 config.yaml 的用户升级后，改动静默失效（不报错，按新默认值跑）。比如把 model 换成 claude 的用户会悄悄变回 gpt-4o，跑完看账单才发现

建议方案

1. 恢复 pageindex/config.yaml 文件（默认值 + 注释，同 main）——老用户 git pull 时本地改动可正常合并，工作流不变
2. run_pageindex.py 恢复读取：文件存在则作为 IndexConfig 的基础配置，命令行参数优先级更高。"yes"/"no" 字符串转换可复用现有 _coerce_bool，加载器约 20 行
3. SDK（PageIndexClient）保持不读——库代码依赖 CWD 下的环境文件是坑（pip 用户没有这个文件，行为会随运行目录变化），显式传参的新设计是对的。如需文件配置可提供显式的 IndexConfig.from_yaml(path)

即 CLI 侧完全向后兼容，SDK 侧保持新架构不妥协。

顺带两个相关的小观察（无需行动，release notes 提一句即可）：

• if_add_doc_description 默认值从 CLI 的 "no" 变为 True（旧 client 路径本来就总传 'yes'，SDK 用户无感知；CLI 用户每文档多一次 LLM 调用生成描述）
• 若采纳上面的方案，此项也自动回到旧 CLI 行为，无需单独处理