First run

Quickstart

Install Pelorus, run the Pelorus Space example, and see queries answered from chunks, Query Extracts, or Cluster Extracts — no API key required.

Run locally

Pelorus Query is an early open-source project. Clone the repository, install it with the admin and MCP extras, then run the shipped Pelorus Space example. The example uses a local fastembed model and serves curated answers without an LLM, so no provider API key is required for the first run.

# Clone the repository.
git clone https://github.com/staceyfarias/pelorus-query.git
cd pelorus-query

# Install with the admin and MCP extras.
pip install -e ".[admin,mcp]"

# Install the Pelorus Space example dataset.
# macOS / Linux
examples/pelorus-space/install.sh
# Windows
examples\pelorus-space\install.bat

# Run the demo queries.
python examples/pelorus-space/run_demo.py

# Start the engine and Admin UI together (the supported dev workflow).
# macOS / Linux
./start.sh
# Windows
start.bat

Attaching the console to a separately-run engine with pelorus-admin --connect also works, but is experimental and unsupported for now — use start.sh / start.bat for local development.

First pass

1. Confirm the hit

The demo query should return a source-grounded result and identify the retrieval path in metadata: source chunks, Query Extract, or Cluster Extract.

2. Open the map

Use the Admin UI to inspect the Query Map. Look for repeated demand, cluster neighborhoods, overlap, and gaps instead of judging the system only by one answer.

3. Curate

Review generated Extracts, refine their summaries, adjust status, and process demand in controlled batches once the query patterns are clear.