Quickstart

Install Pelorus, load the Pelorus Space dataset, and watch a question fall through to source chunks, record demand, and come back as an Extract — no API key needed until you create Extracts.

Run locally

Pelorus Query is an early open-source project. Clone the repository, install it with the admin and MCP extras, and start the engine and Admin UI together. Querying uses a local fastembed model (a one-time download of about 65 MB), so no provider API key is required to load a dataset or ask it questions.

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

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

# Put the Pelorus Space v2.1 Dataset where Pelorus looks for datasets:
# the shared RAG Connector Datasets directory (`rag-connector datasets-dir`
# prints it; ~/rag-connector/datasets by default).
# macOS / Linux
mkdir -p "$(rag-connector datasets-dir)"
cp -r examples/pelorus-space-v2.1 "$(rag-connector datasets-dir)/"
# Windows PowerShell
New-Item -ItemType Directory -Force "$(rag-connector datasets-dir)" | Out-Null
Copy-Item -Recurse examples\pelorus-space-v2.1 "$(rag-connector datasets-dir)\"

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

Open http://127.0.0.1:8000 and go to Datasets. The pelorus-space-v2.1 folder appears as a rag-connector Dataset (ds-900cf7746b744988, 28 documents, 426 chunks) marked Not Imported. Click Import, choose the Default group, click Connect (it offers Create vectors, which embeds the chunks locally), then Enable. The dataset keeps the Dataset's own chunk ids, so citations agree with the test sets built on the same corpus by RAGauge.

The same steps from Python, if you would rather not click:

from pelorus import PelorusEngine

engine = PelorusEngine(config_path="config.yaml")
ds = engine.import_spec_dataset(
    "examples/pelorus-space-v2.1",
    expected_dataset_id="ds-900cf7746b744988",
)
engine.connect_dataset_group(ds["id"], "default", vector_policy="revectorize_all")
engine.enable_dataset(dataset=ds["id"])

result = engine.query("Can I do an EVA at Enceladus?", dataset=ds["id"])
print(result.status, result.extract_id)
for document in result.documents:
    print(document.metadata.get("type"), document.content[:200])

engine.shutdown()

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. Pointing Pelorus at your own documents instead is Add Dataset in the console, or create_managed_dataset() from the library; see Core Workflow.

First pass