refactor: spell out collection instead of col in examples, README, and docstrings

README.md

@@ -162,16 +162,16 @@ from pageindex import PageIndexClient
 # `model` drives indexing; agent QA uses `retrieve_model` (default: gpt-5.4).
 client = PageIndexClient(model="gpt-4o-2024-11-20")
 
-col = client.collection()
-doc_id = col.add("path/to/your.pdf")
+collection = client.collection()
+doc_id = collection.add("path/to/your.pdf")
 
-print(col.query("What is the main contribution?", doc_ids=doc_id))
+print(collection.query("What is the main contribution?", doc_ids=doc_id))
 
 # Cloud mode — fully managed, no LLM key needed:
 # client = PageIndexClient(api_key="your-pageindex-api-key")
 ```
 
-`col.query(...)` returns the answer string by default. Always pass `doc_ids` for reliable single-document QA — omitting it queries the entire collection, which is experimental (see below).
+`collection.query(...)` returns the answer string by default. Always pass `doc_ids` for reliable single-document QA — omitting it queries the entire collection, which is experimental (see below).
 
 ### Streaming queries
 
@@ -179,7 +179,7 @@ print(col.query("What is the main contribution?", doc_ids=doc_id))
 import asyncio
 
 async def main():
-    async for ev in col.query("Explain multi-head attention", doc_ids=doc_id, stream=True):
+    async for ev in collection.query("Explain multi-head attention", doc_ids=doc_id, stream=True):
         if ev.type == "text_delta":
             print(ev.data, end="", flush=True)
         elif ev.type == "tool_call":
@@ -195,8 +195,8 @@ asyncio.run(main())
 Passing `doc_ids` scopes the query to a specific subset of documents — this is the recommended path. `doc_ids` accepts a single id (`str`) or a list:
 
 ```python
-col.query("What does this paper say?", doc_ids=doc1)            # single
-col.query("Compare these two papers", doc_ids=[doc1, doc2])     # multi
+collection.query("What does this paper say?", doc_ids=doc1)            # single
+collection.query("Compare these two papers", doc_ids=[doc1, doc2])     # multi
 ```
 
 Omitting `doc_ids` queries the **entire collection** and lets the agent pick which docs to read. This is an **experimental** feature with a naive first implementation — we're actively working on better cross-document retrieval. A `UserWarning` is emitted; set `PAGEINDEX_EXPERIMENTAL_MULTIDOC=1` to silence it.

examples/cloud_demo.py

@@ -35,13 +35,13 @@ if not PDF_PATH.exists():
     print("Download complete.\n")
 
 client = CloudClient(api_key=os.environ["PAGEINDEX_API_KEY"])
-col = client.collection()
+collection = client.collection()
 
-doc_id = col.add(str(PDF_PATH))
+doc_id = collection.add(str(PDF_PATH))
 print(f"Indexed: {doc_id}\n")
 
 # Streaming query
-stream = col.query("What is the main contribution of this paper?", stream=True)
+stream = collection.query("What is the main contribution of this paper?", stream=True)
 
 async def main():
     streamed_text = False

examples/local_demo.py

@@ -36,13 +36,13 @@ if not PDF_PATH.exists():
     print("Download complete.\n")
 
 client = LocalClient(storage_path=str(WORKSPACE))
-col = client.collection()
+collection = client.collection()
 
-doc_id = col.add(str(PDF_PATH))
+doc_id = collection.add(str(PDF_PATH))
 print(f"Indexed: {doc_id}\n")
 
 # Streaming query
-stream = col.query(
+stream = collection.query(
     "Explain Attention Residuals in simple language.",
     stream=True,
 )

pageindex/agent.py

@@ -87,7 +87,7 @@ class QueryStream:
     """Streaming query result, similar to OpenAI's RunResultStreaming.
 
     Usage:
-        stream = col.query("question", stream=True)
+        stream = collection.query("question", stream=True)
         async for event in stream:
             if event.type == "text_delta":
                 print(event.data, end="", flush=True)

pageindex/collection.py

@@ -109,9 +109,9 @@ class Collection:
         the entire collection (experimental).
 
         Usage:
-            answer = col.query("question", doc_ids=doc_id)            # single
-            answer = col.query("question", doc_ids=[d1, d2])          # multi
-            async for event in col.query("question", doc_ids=doc_id, stream=True):
+            answer = collection.query("question", doc_ids=doc_id)            # single
+            answer = collection.query("question", doc_ids=[d1, d2])          # multi
+            async for event in collection.query("question", doc_ids=doc_id, stream=True):
                 ...
 
         Passing doc_ids=None queries the entire collection — this is
@@ -131,7 +131,7 @@ class Collection:
             if not docs:
                 raise ValueError(
                     f"Cannot query collection '{self._name}': it is empty. "
-                    "Add documents with col.add(...) first."
+                    "Add documents with collection.add(...) first."
                 )
             if len(docs) > 1 and not _multidoc_acked():
                 warnings.warn(_MULTIDOC_WARNING, UserWarning, stacklevel=2)