fix: address PR #272 review findings (directly-fixable items)

Verified against current dev; the compat/behavior decisions (#7 api_key
semantics, #10 CLI flags, #11 doc-description default) are deferred.

Crashes:
- page_index(): snapshot args before importing IndexConfig — locals() was
  capturing the imported class and IndexConfig(extra='forbid') made every call
  raise ValidationError.
- process_none_page_numbers: pop('page', None) instead of del (a TOC item
  without 'page' raised KeyError mid-pipeline).
- pipeline._run_async: guard only the loop detection, not the run, so a real
  RuntimeError from the coroutine isn't masked as "asyncio.run() cannot be
  called from a running event loop".

Silent-wrong / robustness:
- LocalBackend.get_document_structure and the agent get_document /
  get_document_structure tools now surface a missing doc (raise / error-JSON)
  instead of returning empty, matching get_page_content and the cloud backend.
- cloud delete_collection drops the cached folder_id.
- cloud query raises on an empty collection instead of POSTing doc_id:[].
- LocalClient skips the API-key check for keyless providers (ollama, lm_studio,
  …) so keyless LiteLLM models aren't rejected at construction.

Compat / cleanup:
- md_to_tree coerces legacy 'yes'/'no' string flags (a bare 'no' was truthy).
- FileTypeError also subclasses ValueError (0.2.x raised ValueError).
- _validate_llm_provider no longer mutates global litellm.model_cost_map_url.
- __all__ re-includes legacy exports (page_index, md_to_tree, get_*).
- Rewrite examples/agentic_vectorless_rag_demo.py to the Collection API and use
  the in-repo attention.pdf (the old workspace=/client.index/client.documents
  API no longer exists).

Adds tests/test_review_fixes.py (10 regressions). Full suite: 189 passed.

Claude-Session: https://claude.ai/code/session_01Kx5DgKbhK1N8autqXH8SmS

examples/agentic_vectorless_rag_demo.py

@@ -1,22 +1,28 @@
 """
-Agentic Vectorless RAG with PageIndex - Demo
+Agentic Vectorless RAG with PageIndex — Demo
 
-A simple example of building a document QA agent with self-hosted PageIndex
-and the OpenAI Agents SDK. Instead of vector similarity search and chunking,
-PageIndex builds a hierarchical tree index and uses agentic LLM reasoning for
-human-like, context-aware retrieval.
+Build a document-QA agent with self-hosted PageIndex and the OpenAI Agents SDK.
+Instead of vector similarity search and chunking, PageIndex builds a
+hierarchical tree index and lets an agent reason over it for human-like,
+context-aware retrieval.
+
+This demo wires up your OWN agent + tools against the PageIndex Collection API.
+For the batteries-included version, just use ``col.query(..., stream=True)`` —
+see local_demo.py.
 
 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
+  - get_document()           — document metadata (name, type, description)
+  - get_document_structure() — the document's tree-structure index
+  - get_page_content()       — text of specific pages / line ranges
 
 Steps:
-  1 — Index a PDF and view its tree structure index
+  1 — Index a PDF and view its tree structure
   2 — View document metadata
   3 — Ask a question (agent reasons over the index and auto-calls tools)
 
-Requirements: pip install openai-agents
+Requirements:
+    pip install pageindex openai-agents
+    export OPENAI_API_KEY=your-api-key   # or any LiteLLM-supported provider
 """
 import sys
 import json
@@ -32,19 +38,19 @@ from agents.model_settings import ModelSettings
 from agents.stream_events import RawResponsesStreamEvent, RunItemStreamEvent
 from openai.types.responses import ResponseTextDeltaEvent, ResponseReasoningSummaryTextDeltaEvent
 
-from pageindex import PageIndexClient
-import pageindex.utils as utils
+from pageindex import LocalClient
 
-PDF_URL = "https://arxiv.org/pdf/2603.15031"
+PDF_URL = "https://arxiv.org/pdf/1706.03762.pdf"
 
 _EXAMPLES_DIR = Path(__file__).parent
-PDF_PATH = _EXAMPLES_DIR / "documents" / "attention-residuals.pdf"
+PDF_PATH = _EXAMPLES_DIR / "documents" / "attention.pdf"
 WORKSPACE = _EXAMPLES_DIR / "workspace"
+MODEL = "gpt-4o-2024-11-20"  # any LiteLLM-supported model
 
 AGENT_SYSTEM_PROMPT = """
 You are PageIndex, a document QA assistant.
 TOOL USE:
-- Call get_document() first to confirm status and page/line count.
+- Call get_document() first to confirm the document's name and type.
 - 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.
@@ -52,7 +58,7 @@ 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(col, doc_id: str, prompt: str, model: 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.
@@ -61,13 +67,15 @@ def query_agent(client: PageIndexClient, doc_id: str, prompt: str, verbose: bool
 
     @function_tool
     def get_document() -> str:
-        """Get document metadata: status, page count, name, and description."""
-        return client.get_document(doc_id)
+        """Get document metadata: name, type, and description."""
+        doc = col.get_document(doc_id)
+        doc.pop("structure", None)  # keep tool output small for the LLM context
+        return json.dumps(doc, ensure_ascii=False)
 
     @function_tool
     def get_document_structure() -> str:
         """Get the document's full tree structure (without text) to find relevant sections."""
-        return client.get_document_structure(doc_id)
+        return json.dumps(col.get_document_structure(doc_id), ensure_ascii=False)
 
     @function_tool
     def get_page_content(pages: str) -> str:
@@ -76,13 +84,13 @@ def query_agent(client: PageIndexClient, doc_id: str, prompt: str, verbose: bool
         Use tight ranges: e.g. '5-7' for pages 5 to 7, '3,8' for pages 3 and 8, '12' for page 12.
         For Markdown documents, use line numbers from the structure's line_num field.
         """
-        return client.get_page_content(doc_id, pages)
+        return json.dumps(col.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=client.retrieve_model,
+        model=model,
         # model_settings=ModelSettings(reasoning={"effort": "low", "summary": "auto"}),  # Uncomment to enable reasoning
     )
 
@@ -128,12 +136,14 @@ def query_agent(client: PageIndexClient, doc_id: str, prompt: str, verbose: bool
             print()
         return "" if not streamed_run.final_output else str(streamed_run.final_output)
 
+    # Only the detection is guarded, not the run, so a real error inside _run
+    # isn't misread as "no running loop".
     try:
         asyncio.get_running_loop()
-        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            return pool.submit(asyncio.run, _run()).result()
     except RuntimeError:
         return asyncio.run(_run())
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+        return pool.submit(asyncio.run, _run()).result()
 
 
 if __name__ == "__main__":
@@ -152,37 +162,33 @@ if __name__ == "__main__":
                         f.write(chunk)
         print("Download complete.\n")
 
-    # Setup
-    client = PageIndexClient(workspace=WORKSPACE)
+    # Setup: self-hosted local client + a collection
+    client = LocalClient(model=MODEL, storage_path=str(WORKSPACE))
+    col = client.collection("agentic-demo")
 
     # Step 1: Index PDF and view tree structure
     print("=" * 60)
     print("Step 1: Index PDF and view tree structure")
     print("=" * 60)
-    doc_id = next(
-        (did for did, doc in client.documents.items() if doc.get('doc_name') == PDF_PATH.name),
-        None,
-    )
-    if doc_id:
-        print(f"\nLoaded cached doc_id: {doc_id}")
-    else:
-        doc_id = client.index(PDF_PATH)
-        print(f"\nIndexed. doc_id: {doc_id}")
+    # Content-hash dedup: re-running reuses the existing doc_id, no re-index.
+    doc_id = col.add(str(PDF_PATH))
+    print(f"\ndoc_id: {doc_id}")
     print("\nTree Structure (top-level sections):")
-    structure = json.loads(client.get_document_structure(doc_id))
-    utils.print_tree(structure)
+    for node in col.get_document_structure(doc_id):
+        print(f"  - {node.get('title', '(untitled)')}")
 
     # Step 2: View document metadata
     print("\n" + "=" * 60)
     print("Step 2: View document metadata")
     print("=" * 60)
-    doc_metadata = client.get_document(doc_id)
-    print(f"\n{doc_metadata}")
+    meta = col.get_document(doc_id)
+    meta.pop("structure", None)
+    print("\n" + json.dumps(meta, ensure_ascii=False, indent=2))
 
     # Step 3: Agent Query
     print("\n" + "=" * 60)
     print("Step 3: Agent Query (auto tool-use)")
     print("=" * 60)
-    question = "Explain Attention Residuals in simple language."
+    question = "Explain the Transformer's self-attention in simple language."
     print(f"\nQuestion: '{question}'")
-    query_agent(client, doc_id, question, verbose=True)
+    query_agent(col, doc_id, question, MODEL, verbose=True)