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/index/page_index.py

@@ -679,11 +679,11 @@ def process_none_page_numbers(toc_items, page_list, start_index=1, model=None):
                     continue
 
             item_copy = copy.deepcopy(item)
-            del item_copy['page']
+            item_copy.pop('page', None)
             result = add_page_number_to_toc(page_contents, item_copy, model)
             if isinstance(result[0]['physical_index'], str) and result[0]['physical_index'].startswith('<physical_index'):
                 item['physical_index'] = int(result[0]['physical_index'].split('_')[-1].rstrip('>').strip())
-                del item['page']
+                item.pop('page', None)
     
     return toc_items
 
@@ -1113,11 +1113,14 @@ def page_index_main(doc, opt=None):
 def page_index(doc, model=None, toc_check_page_num=None, max_page_num_each_node=None, max_token_num_each_node=None,
                if_add_node_id=None, if_add_node_summary=None, if_add_doc_description=None, if_add_node_text=None):
     
-    from ..config import IndexConfig
+    # Snapshot the call args BEFORE importing IndexConfig — otherwise the
+    # imported class would be captured by locals() and rejected by
+    # IndexConfig(extra="forbid").
     user_opt = {
         arg: value for arg, value in locals().items()
         if arg != "doc" and value is not None
     }
+    from ..config import IndexConfig
     opt = IndexConfig(**user_opt)
     return page_index_main(doc, opt)
 

pageindex/index/page_index_md.py

@@ -237,7 +237,21 @@ def clean_tree_for_output(tree_nodes):
     return cleaned_nodes
 
 
+def _coerce_bool(value):
+    """Coerce a legacy 'yes'/'no' string flag to bool (a bare 'no' is truthy)."""
+    if isinstance(value, str):
+        return value.strip().lower() in ("yes", "true", "1", "y", "on")
+    return bool(value)
+
+
 async def md_to_tree(md_path, if_thinning=False, min_token_threshold=None, if_add_node_summary=False, summary_token_threshold=None, model=None, if_add_doc_description=False, if_add_node_text=False, if_add_node_id=True):
+    # Accept legacy 'yes'/'no' string flags — a bare 'no' would otherwise be
+    # truthy and wrongly enable the option.
+    if_thinning = _coerce_bool(if_thinning)
+    if_add_node_summary = _coerce_bool(if_add_node_summary)
+    if_add_doc_description = _coerce_bool(if_add_doc_description)
+    if_add_node_text = _coerce_bool(if_add_node_text)
+    if_add_node_id = _coerce_bool(if_add_node_id)
     with open(md_path, 'r', encoding='utf-8') as f:
         markdown_content = f.read()
     line_count = markdown_content.count('\n') + 1

pageindex/index/pipeline.py

@@ -44,17 +44,22 @@ def _run_async(coro):
     import asyncio
     import concurrent.futures
     import contextvars
+    # Only the detection is guarded — NOT the run. If the coroutine's own work
+    # raises RuntimeError, letting it fall into `except RuntimeError` here would
+    # misfire the "no running loop" branch and mask the real error behind a
+    # bogus "asyncio.run() cannot be called from a running event loop".
     try:
         asyncio.get_running_loop()
-        # Already inside an event loop -- run in a separate thread. Copy the
-        # current context so ContextVar-based settings (e.g. the
-        # max_concurrency_scope override set by build_index) propagate into the
-        # worker thread instead of silently falling back to the process default.
-        ctx = contextvars.copy_context()
-        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            return pool.submit(ctx.run, asyncio.run, coro).result()
     except RuntimeError:
+        # No running loop -- drive the coroutine directly.
         return asyncio.run(coro)
+    # Already inside an event loop -- run in a separate thread so we don't nest
+    # asyncio.run. Copy the current context so ContextVar-based settings (e.g.
+    # the max_concurrency_scope override set by build_index) propagate into the
+    # worker thread; .result() re-raises the worker's real exception unchanged.
+    ctx = contextvars.copy_context()
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+        return pool.submit(ctx.run, asyncio.run, coro).result()
 
 
 def build_index(parsed: ParsedDocument, model: str = None, opt=None) -> dict: