Quickstart

1. Run an engine

git clone https://github.com/hallelx2/vectorless-engine.git
cd vectorless-engine/selfhost
cp .env.example .env   # VECTORLESS_API_KEY, an answer-model key, VECTORLESS_TYPESAFE_API_KEY
docker compose up -d
# API → http://localhost:8080 (send Authorization: Bearer <VECTORLESS_API_KEY>)

git clone https://github.com/hallelx2/vectorless-engine.git && cd vectorless-engine
docker compose up -d postgres
export VLE_LLM_ANTHROPIC_API_KEY=<your key>
export TYPESAFE_API_KEY=<your TypeSafe key>
export VLE_INGEST_MODE=toc VLE_RETRIEVAL_STRATEGY=judgewalk
go run ./cmd/engine --local      # listens on :7654

The Docker setup runs the server binary production ran (cmd/server), with pincites, page images and the strategy fallback, on port 8080 behind your VECTORLESS_API_KEY. Self-hosting covers every setting. Without a TypeSafe key the engine still runs, on the generative fallbacks described in Jev and System One models.

"From source" runs the standalone engine (cmd/engine --local) on port 7654 with no token. It has the /v1/replay route but no pincites. The examples below use the Docker setup. For the standalone engine, use port 7654 and drop the API key.

2. Install an SDK

npm install vectorless

pip install vectorless-sdk

go get github.com/hallelx2/vectorless-sdk/go

3. Ingest a document and ask

import { VectorlessClient } from "vectorless";

const client = new VectorlessClient({
  baseUrl: "http://localhost:8080",
  apiKey: process.env.VECTORLESS_API_KEY,
});

const { document_id } = await client.ingestDocument("./10-K.pdf");
const doc = await client.waitForReady(document_id);

const response = await client.query(doc.id, "What were FY2018 capital expenditures?");
for (const section of response.sections) {
  console.log(section.title, section.content.slice(0, 200));
}

import os

from vectorless import VectorlessClient

client = VectorlessClient(
    base_url="http://localhost:8080",
    api_key=os.environ["VECTORLESS_API_KEY"],
)

result = client.ingest_document("./10-K.pdf")
doc = client.wait_for_ready(result.document_id)

response = client.query(doc.id, "What were FY2018 capital expenditures?")
for section in response.sections:
    print(section.title, section.content[:200])

query returns the sections that hold the pages retrieval chose, verbatim and in document order. For the pages themselves, with page numbers and pincites, ask for an answer.

4. Get an answer

The SDKs do not yet wrap POST /v1/answer. Call it over HTTP:

curl -s http://localhost:8080/v1/answer \
  -H "Authorization: Bearer $VECTORLESS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"document_id":"<id>","query":"What were FY2018 capital expenditures?"}'

The response carries the answer, the evidence pages, a trace_token for replay and the pincites: each claim's page, its precision (line or page), the quote, and the rectangles to highlight on GET /v1/documents/{id}/pages/{n}/image.

1. Run an engine

2. Install an SDK

3. Ingest a document and ask

4. Get an answer

On this page