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

pageindex/backend/cloud.py

@@ -162,6 +162,9 @@ class CloudBackend:
         folder_id = self._get_folder_id(name)
         if folder_id:
             self._request("DELETE", f"/folder/{self._enc(folder_id)}/")
+        # Drop the cached id so a later same-name op re-resolves instead of
+        # reusing the now-deleted folder_id.
+        self._folder_id_cache.pop(name, None)
 
     # ── Document management ───────────────────────────────────────────────
 
@@ -307,6 +310,8 @@ class CloudBackend:
                 "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)
+        if not doc_id:
+            raise ValueError("collection has no documents to query")
         # A non-streaming completion returns nothing until generation
         # finishes, so it needs far more than the default 30s. retries=1:
         # retrying this non-idempotent call would redo the full server-side
@@ -340,6 +345,8 @@ class CloudBackend:
                 "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)
+        if not doc_id:
+            raise ValueError("collection has no documents to query")
         headers = self._headers
         # Queue carries QueryEvent, an Exception to re-raise, or None (end).
         queue: asyncio.Queue[QueryEvent | Exception | None] = asyncio.Queue()

pageindex/backend/local.py

@@ -190,6 +190,10 @@ class LocalBackend:
                 LocalBackend._fill_node_text(node["nodes"], page_map)
 
     def get_document_structure(self, collection: str, doc_id: str) -> list:
+        # Parity with get_document / the cloud backend: a missing doc must raise,
+        # not masquerade as an empty structure.
+        if not self._storage.get_document(collection, doc_id):
+            raise DocumentNotFoundError(f"Document {doc_id} not found")
         return self._storage.get_document_structure(collection, doc_id)
 
     def get_page_content(self, collection: str, doc_id: str, pages: str) -> list:
@@ -255,7 +259,10 @@ class LocalBackend:
             rejection = _reject(doc_id)
             if rejection:
                 return rejection
-            return json.dumps(storage.get_document(col_name, doc_id))
+            doc = storage.get_document(col_name, doc_id)
+            if not doc:
+                return json.dumps({"error": f"doc_id '{doc_id}' not found."})
+            return json.dumps(doc)
 
         @function_tool
         def get_document_structure(doc_id: str) -> str:
@@ -263,6 +270,8 @@ class LocalBackend:
             rejection = _reject(doc_id)
             if rejection:
                 return rejection
+            if not storage.get_document(col_name, doc_id):
+                return json.dumps({"error": f"doc_id '{doc_id}' not found."})
             structure = storage.get_document_structure(col_name, doc_id)
             return json.dumps(remove_fields(structure, fields=["text"]), ensure_ascii=False)
 
@@ -272,7 +281,10 @@ class LocalBackend:
             rejection = _reject(doc_id)
             if rejection:
                 return rejection
-            result = backend.get_page_content(col_name, doc_id, pages)
+            try:
+                result = backend.get_page_content(col_name, doc_id, pages)
+            except DocumentNotFoundError:
+                return json.dumps({"error": f"doc_id '{doc_id}' not found."})
             return json.dumps(result, ensure_ascii=False)
 
         tools = [get_document, get_document_structure, get_page_content]