review: the complete v0.2.10 line — agent tools, local chat, Flash default

.github/workflows/publish.yml

@@ -5,7 +5,8 @@ name: Publish to PyPI
 #   2. git push origin v0.2.9
 #   3. This workflow derives the version from the tag, injects it into
 #      pyproject.toml, builds, publishes to PyPI via OIDC trusted publishing
-#      (no stored secret), and creates a GitHub Release with generated notes.
+#      (no stored secret), and creates a GitHub Release with generated notes
+#      (dev tags publish to PyPI only — no GitHub Release).
 #
 # The tag must be a PEP 440 version with a leading `v`:
 #   v0.2.9   v0.2.9rc1   v0.2.9.dev1
@@ -76,6 +77,9 @@ jobs:
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1.14.0
 
       - name: Create GitHub Release
+        # dev builds need an explicit pin to install; a Release for them
+        # only doubles the feed next to the stable that follows.
+        if: ${{ !contains(github.ref_name, 'dev') }}
         uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b  # v3.0.1
         with:
           tag_name: ${{ github.ref_name }}

.github/workflows/tests.yml

@@ -30,6 +30,9 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: pip
       - run: pip install -r requirements.txt pytest
+      - if: matrix.agent-frameworks == 'without'
+        # requirements.txt carries it; this leg tests the no-framework paths
+        run: pip uninstall -y openai-agents
       - if: matrix.agent-frameworks == 'with'
-        run: pip install openai-agents claude-agent-sdk
+        run: pip install openai-agents claude-agent-sdk anthropic
       - run: python -m pytest -q

README.md

@@ -173,10 +173,11 @@ python3 run_pageindex.py --pdf_path /path/to/your/document.pdf
 <details>
 <summary>Optional parameters</summary>
 <br>
-You can customize the processing with additional optional arguments:
+You can customize the processing with additional optional arguments (the structure-tuning flags from <code>--toc-check-pages</code> down require <code>--mode standard</code>):
 
 ```
---model                 LLM model to use (default: gpt-4o-2024-11-20)
+--mode                  Processing mode: flash (default) or standard
+--index-model           LLM model used to index the document (default: gpt-5.6-luna)
 --toc-check-pages       Pages to check for table of contents (default: 20)
 --max-pages-per-node    Max pages per node (default: 10)
 --max-tokens-per-node   Max tokens per node (default: 20000)
@@ -199,23 +200,19 @@ python3 run_pageindex.py --md_path /path/to/your/document.md
 </details>
 
 > ### ⚡ PageIndex Flash *(preview)*
-> **PageIndex Flash** ([`pageindex/flash`](pageindex/flash)) generates tree structures from PDFs in seconds. Structure extraction is purely heuristic-based, no LLM needed. LLM is only used to generate node summaries.
+> **PageIndex Flash** ([`pageindex/flash`](pageindex/flash)) generates tree structures from PDFs in seconds. Structure extraction is purely heuristic-based, no LLM needed. An LLM is used only for node summaries and the optimization's expansion pass.
 >
 > ```bash
-> python3 run_pageindex.py --flash --pdf_path /path/to/your/document.pdf
+> python3 run_pageindex.py --mode flash --pdf_path /path/to/your/document.pdf
 > ```
 >
-> Add `--optimize` to refine the tree structure for more efficient retrieval (with an LLM expansion pass).
+> Tree optimization for retrieval (a deterministic merge, then an LLM expansion pass) is on by default; pass `--optimize off` to disable.
 
 ## 🚀 Agentic Vectorless RAG: An Example
 
 For a simple, end-to-end **agentic vectorless RAG** example using **self-hosted PageIndex** (with OpenAI Agents SDK), see [`examples/agentic_vectorless_rag_demo.py`](examples/agentic_vectorless_rag_demo.py).
 
 ```bash
-# Install optional dependency
-pip3 install openai-agents
-
-# Run the demo
 python3 examples/agentic_vectorless_rag_demo.py
 ```
 

examples/agentic_vectorless_rag_demo.py

@@ -6,33 +6,33 @@
 chunking, PageIndex builds a hierarchical tree index and uses agentic LLM
 reasoning for human-like, context-aware retrieval.
 
-Agent tools:
-  - get_document()           — document metadata (status, page count, etc.)
-  - get_document_structure() — tree structure index of a document
-  - get_page_content()       — retrieve text content of specific pages
+The agent tools come straight from the SDK — ``client.as_openai_tools()``
+exposes the PageIndex tool contract (browse_documents, get_document,
+get_document_structure, get_page_content) and ``client.agent_instructions()``
+provides the retrieval playbook, so the whole agent is a few lines. Swap
+``PageIndexLocalClient()`` for ``PageIndexCloudClient(api_key=...)`` and the
+same code runs against the cloud.
 
 Steps:
   1 — Index a PDF locally and view its tree structure index
   2 — View document metadata
   3 — Ask a question (agent reasons over the index and auto-calls tools)
 
-Requirements: pip install openai-agents; OPENAI_API_KEY in the environment.
+Requirements: pip install pageindex; OPENAI_API_KEY in the environment.
 """
 import sys
-import json
 import asyncio
 import concurrent.futures
 from pathlib import Path
 import requests
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
-from agents import Agent, Runner, function_tool, set_tracing_disabled
-from agents.model_settings import ModelSettings
+from agents import Agent, Runner, set_tracing_disabled
 from agents.stream_events import RawResponsesStreamEvent, RunItemStreamEvent
 from openai.types.responses import ResponseTextDeltaEvent, ResponseReasoningSummaryTextDeltaEvent
 
-from pageindex import PageIndexClient
+from pageindex import PageIndexLocalClient
 import pageindex.utils as utils
 
 PDF_URL = "https://arxiv.org/pdf/2603.15031"
@@ -41,48 +41,18 @@
 PDF_PATH = _EXAMPLES_DIR / "documents" / "attention-residuals.pdf"
 STORAGE_PATH = _EXAMPLES_DIR / ".pageindex"
 
-AGENT_SYSTEM_PROMPT = """
-You are PageIndex, a document QA assistant.
-TOOL USE:
-- Call get_document() first to confirm status and page count.
-- Call get_document_structure() to identify relevant page ranges.
-- Call get_page_content(pages="5-7") with tight ranges; never fetch the whole document.
-- Before each tool call, output one short sentence explaining the reason.
-Answer based only on tool output. Be concise.
-"""
-
 
-def query_agent(client: PageIndexClient, doc_id: str, prompt: str, verbose: bool = False) -> str:
+def query_agent(client: PageIndexLocalClient, doc_id: str, prompt: str, verbose: bool = False) -> str:
     """Run a document QA agent using the OpenAI Agents SDK.
 
     Streams text output token-by-token and returns the full answer string.
     Tool calls are always printed; verbose=True also prints arguments and output previews.
     """
-
-    @function_tool
-    def get_document() -> str:
-        """Get document metadata: status, page count, name, and description."""
-        return json.dumps(client.get_document(doc_id))
-
-    @function_tool
-    def get_document_structure() -> str:
-        """Get the document's full tree structure (without text) to find relevant sections."""
-        return json.dumps(client.get_document_structure(doc_id), ensure_ascii=False)
-
-    @function_tool
-    def get_page_content(pages: str) -> str:
-        """
-        Get the text content of specific pages.
-        Use tight ranges: e.g. '5-7' for pages 5 to 7, '3,8' for pages 3 and 8, '12' for page 12.
-        """
-        return json.dumps(client.get_page_content(doc_id, pages), ensure_ascii=False)
-
     agent = Agent(
-        name="PageIndex",
-        instructions=AGENT_SYSTEM_PROMPT,
-        tools=[get_document, get_document_structure, get_page_content],
-        model=getattr(client, "retrieve_model", None),
-        # model_settings=ModelSettings(reasoning={"effort": "low", "summary": "auto"}),  # Uncomment to enable reasoning
+        **client.openai_agent_config(
+            doc_id=doc_id,
+            # model_settings=ModelSettings(reasoning={"effort": "low", "summary": "auto"}),  # from agents.model_settings import ModelSettings
+        ),
     )
 
     async def _run():
@@ -152,21 +122,19 @@ async def _run():
         print("Download complete.\n")
 
     # Setup: local mode — no PageIndex API key needed, your LLM key does the work
-    client = PageIndexClient(storage_path=str(STORAGE_PATH))
+    client = PageIndexLocalClient(storage_path=str(STORAGE_PATH))
 
     # Step 1: Index PDF and view tree structure
     print("=" * 60)
     print("Step 1: Index PDF and view tree structure")
     print("=" * 60)
     doc_id = next(
         (doc["id"] for doc in client.list_documents(limit=100)["documents"]
-         if doc["name"] == PDF_PATH.name),
-        None,
-    )
+         if doc["name"] == PDF_PATH.name), None)
     if doc_id:
         print(f"\nLoaded cached doc_id: {doc_id}")
     else:
-        doc_id = client.submit_document(str(PDF_PATH))["doc_id"]
+        doc_id = client.submit_document(str(PDF_PATH), wait=True)["doc_id"]
         print(f"\nIndexed. doc_id: {doc_id}")
     print("\nTree Structure (top-level sections):")
     structure = client.get_tree(doc_id, node_summary=True)["result"]

pageindex/__init__.py

@@ -22,9 +22,10 @@
     "optimize_tree": ".tree_optimize",
     "md_to_tree": ".page_index_md",
 }
-_SUBMODULES = {"client", "cloud_api", "errors", "flash", "local_api",
-               "local_store", "page_index_classic", "page_index_md", "tree_optimize",
-               "utils"}
+_SUBMODULES = {"agent_tools", "client", "cloud_api", "errors", "flash",
+               "integrations", "local_api", "local_chat", "local_store",
+               "mcp_bridge", "page_index_classic", "page_index_md",
+               "tree_optimize", "utils"}
 
 
 def __getattr__(name):

pageindex/_version.py

@@ -0,0 +1,10 @@
+"""Installed-package version, shared by every surface that reports it upstream."""
+from __future__ import annotations
+
+
+def sdk_version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("pageindex")
+    except Exception:
+        return "0.0.0"