As a library
The core: multi-size slicer, structural markers, containment forest, and the budget-fitting selection engine. Standard library only, synchronous, and embeddable in any pipeline.
pip install phoropterOpen source · pre-alpha
Right-sized retrieval context under a token budget.
Phoropter is a multi-view RAG server — and an embeddable Python library — that indexes every document at multiple slice sizes on a shared origin-aligned grid, then fits the most coherent context to the budget you have.
The core is under active development; APIs will change.
The idea
Stop picking a chunk size at ingest time.
Conventional RAG pipelines choose one chunk size up front and live with it forever: small chunks match precisely but strip away context, large chunks preserve context but crowd the model's window. Phoropter defers that choice to query time.
Because every size is sliced on the same origin-aligned grid, a larger slice provably contains its smaller slices — containment is decided by offset arithmetic and verified with content hashes, not similarity heuristics. So swapping a small relevant slice for its enclosing parent never loses relevant content; it only spends tokens.
That turns token budgeting into a sequence of safe, explainable moves — and every decision comes with a trace.
-
Index at every size
Each document is sliced at multiple sizes on one shared grid.
-
Retrieve across sizes
A query searches all of them at once, not just one chosen view.
-
Discard the redundant
Slices contained inside other slices are detected exactly, and dropped.
-
Trade up while it fits
Small slices trade up to their enclosing parents while the budget allows.
Get started
Two ways to run it.
As a server
Adds FastAPI REST and MCP surfaces over a pluggable vector store (Qdrant by default) and pluggable embedders (Ollama and OpenAI-compatible included).
pip install "phoropter[server,qdrant]"Documentation
Read the manual.
New here? Start with concepts for the method, then architecture for the system.
- Concepts The method: multi-size slicing, containment, right-sizing.
- Architecture How the system fits together.
- Quickstart · library Run it in-process, inside your own pipeline.
- Quickstart · server Stand up the REST and MCP surfaces.
- Engine The right-sizing selection engine in detail.
- API reference REST endpoints, with an OpenAPI spec.
- MCP The Model Context Protocol surface.
- Adapters Pluggable vector stores and embedders.
- Decisions The design log — why things are the way they are.
- Testing How correctness is verified, in plain English.
Community
Ask, report, propose.
Phoropter's community lives on GitHub, alongside the code — so questions, bugs, and ideas sit next to the commits that resolve them.
Ask a question
Stuck on setup, tuning, or a concept? Ask in Q&A — answers get marked so the next person finds them.
Report a bug
Something broken or behaving oddly? File an issue, right next to the code that needs fixing.
Request a feature
Propose an idea and vote on others. Ideas with traction shape what gets built next.
Read the wiki
Community notes, recipes, and hard-won knowledge that outgrew a single answer.
Contributions are welcome — see CONTRIBUTING and the code of conduct.