From 43153fecd998d4853656856a525c13fe70144a2a Mon Sep 17 00:00:00 2001 From: Ray Date: Sun, 19 Jul 2026 15:25:17 +0800 Subject: [PATCH] refactor: spell out collection instead of col in examples, README, and docstrings --- README.md | 14 +++++++------- examples/cloud_demo.py | 6 +++--- examples/local_demo.py | 6 +++--- pageindex/agent.py | 2 +- pageindex/collection.py | 8 ++++---- 5 files changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 38614ff..5327af7 100644 --- a/README.md +++ b/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. diff --git a/examples/cloud_demo.py b/examples/cloud_demo.py index 15aecd1..fe6bfff 100644 --- a/examples/cloud_demo.py +++ b/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 diff --git a/examples/local_demo.py b/examples/local_demo.py index 2db4a8f..c5be0b2 100644 --- a/examples/local_demo.py +++ b/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, ) diff --git a/pageindex/agent.py b/pageindex/agent.py index 253d028..fd7508d 100644 --- a/pageindex/agent.py +++ b/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) diff --git a/pageindex/collection.py b/pageindex/collection.py index 8d974d0..7d6c0f8 100644 --- a/pageindex/collection.py +++ b/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)