pageindex-search

Python client for Page Search API by PageIndex. Upload a PDF, ask up to 10 questions at once, and get back the pages that answer each one, ranked by relevance. Every page is read.

pip install pageindex-search

Create an API key in the console and set it:

export PAGEINDEX_SEARCH_API_KEY=pis_live_...

Quick start

from pageindex_search import PageSearch

client = PageSearch()

doc = client.documents.upload("3M_2018_10K.pdf")
result = client.search(["What was capital expenditure in 2018?", "Who is the CEO?"], document=doc)

for answer in result.results:
    print(answer.question)
    for page in answer.pages:
        print(f"  page {page.page}: {page.relevance}")

print(f"cost ${result.usage.cost_usd}, credit left ${result.usage.balance_usd}")

Upload a document once and search it as often as you like; uploading the same file again returns the same document. Documents are kept until you delete them:

for doc in client.documents.list():  # every document, newest first, a page at a time
    print(doc.id, doc.filename, doc.pages)

client.search(["What was revenue in 2018?"], document="doc_60a07bcef3094b68806070f2")  # search one again by its id
client.documents.delete("doc_60a07bcef3094b68806070f2")

With many documents, search across them: the documents likely to answer are found first, then their pages.

result = client.search("What was capital expenditure in 2018?")  # every document of yours
for doc in result.results[0].documents:
    print(doc.filename, [(p.page, p.relevance) for p in doc.pages])

To find only which documents answer, use client.documents.search.

Group documents into collections, and search within one:

reports = client.collections.create("Annual reports")
client.documents.upload("3M_2018_10K.pdf", collection=reports)  # or later: client.collections.add(reports, [doc])
result = client.search("What was capital expenditure in 2018?", collection=reports)

A document may be in many collections; deleting a collection leaves its documents.

Give documents your own metadata (strings, numbers and booleans) and filter by it:

doc = client.documents.upload("3M_2018_10K.pdf", metadata={"ticker": "MMM", "year": 2018})
client.documents.update(doc, metadata={"audited": True})          # None removes a key
recent = client.documents.list(filter={"year": {"$gte": 2020}})
result = client.search("Who is the CEO?", filter={"ticker": {"$in": ["MMM", "AAPL"]}})

Filters take $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $and and $or.

Read pages: their text, or a page as a picture. Each page a search lists says how it is best read (page.read: "text", or "image" for a scan or a chart, whose text may be incomplete); include_text=True lists it with its text.

texts = client.documents.pages(doc, [38, 39])   # each with .text and .read
png = client.documents.page_image(doc, 38)       # PNG bytes
part = client.documents.page_image(doc, 38, box=(0, 0.3, 1, 0.6))  # a band of it, sharper

Agents

client.tools() gives an LLM agent seven tools over your documents: list_collections (free: your collections, to search one the question names), list_documents (free: documents whose metadata meets a filter, with your metadata's keys and values in its description, so the agent can write filters), search_documents (which documents answer a question, for when a filter cannot pick them), search_pages (with each page's text), read_pages (text, with a picture of any page that is one), view_pages (pages as pictures) and zoom_page (part of a page, sharper, for small print).

tools = client.tools(collection=reports)  # or filter=..., or neither for all your documents

response = anthropic.messages.create(model=..., tools=tools.definitions, messages=messages)
for block in response.content:
    if block.type == "tool_use":
        content = tools.run(block.name, block.input).anthropic()  # the tool_result content

For OpenAI, pass tools.openai; tools.run() gives .text and .images, each image with .data_url. With the OpenAI Agents SDK (pip install "pageindex-search[agents]"), tools.openai_agents() gives the tools ready to use:

from agents import Agent, Runner

agent = Agent(name="Reports", instructions="Answer from the documents.", tools=tools.openai_agents())
print(Runner.run_sync(agent, "What was capital expenditure in 2018?").final_output)

MCP

The same tools work in Claude Desktop, Cursor and other MCP clients. Add this to the client's MCP settings:

{
  "mcpServers": {
    "page-search": {
      "command": "uvx",
      "args": ["--from", "pageindex-search[mcp]", "pageindex-search-mcp", "--collection", "col_..."],
      "env": {"PAGEINDEX_SEARCH_API_KEY": "pis_live_..."}
    }
  }
}

Leave out --collection for all your documents, or pass --filter '{"year": 2024}' for those whose metadata meets it. In Python, tools.mcp() gives the server to run yourself.

Reference

In 0.4, search(document, questions) became search(questions, document=document), and each answer lists documents, each with its pages (answer.pages is the first document's). Before 0.2 these were upload(), document(), documents(), iter_documents() and delete() on the client; they still work, with a warning, for now.

Errors raise PageSearchError, with the API's status, code, message and request_id.

See the API reference for every field and the pricing.