alcove-search 0.1.0

Local-first document retrieval. Your data never leaves your disk.

Alcove

Search your own documents locally. No server, no sign-up, no data leaves your machine.

Who is this for? Teams and partners who need a working document-search demo on their own hardware in minutes — not months.

• Private — documents stay on your machine, no cloud calls, no tracking
• Zero config — pip install, two commands, searching in under a minute
• Extensible — plug in custom extractors, embedders, and backends

Alcove is free to use and we do not want your data. No benchmark claims — optimized for clarity and speed of setup.

Get started

Requires: Python 3.9+ — download at python.org if you don't have it.

pip install alcove-search
alcove seed-demo          # download a sample corpus and build a local index
alcove serve              # open http://localhost:8000

Open http://localhost:8000 in your browser. Upload your own files or search the sample corpus. No coding required after this point.

Trust model

• Local disk persistence — no hosted control plane required
• Chroma anonymized telemetry disabled by default (ANONYMIZED_TELEMETRY=False)
• You choose what data enters your local index
• We do not want your data

See Security for the full trust-boundary diagram.

---

For developers

CLI

alcove serve              # start web UI + API server
alcove ingest ./docs/     # ingest documents from a directory
alcove query "search..."  # CLI retrieval
alcove seed-demo          # fetch and index demo corpus
alcove plugins            # list installed plugins

From source

git clone https://github.com/Pro777/alcove-starter-private.git
cd alcove-starter-private
pip install -e ".[dev]"

Make targets

make setup              # create .venv, install deps
make serve              # start web UI
make seed-demo          # fetch demo corpus and build local index
make ingest             # build chunks from data/raw
make index              # write vectors to local Chroma
make query Q="..."      # run local retrieval
make smoke              # deterministic end-to-end check + tests

API

GET  /           # web UI (search + file upload)
GET  /search     # search results page (server-rendered)
POST /query      # JSON retrieval {"query":"...","k":3}
POST /ingest     # file upload (multipart)
GET  /health     # readiness check

Embedder options

By default Alcove uses a deterministic hash embedder (no network, no model download). For semantic similarity, set EMBEDDER=sentence-transformers in .env:

EMBEDDER=sentence-transformers make index
make query Q="What is liberty?"

The all-MiniLM-L6-v2 model (~80MB) downloads on first use. Each embedder type uses a separate collection, so switching embedders requires re-indexing but won't corrupt existing data.

Vector backend

Alcove supports two local vector backends:

Backend	Env value	Default path	Notes
ChromaDB	chromadb (default)	./data/chroma	Mature, full-featured
zvec	zvec	./data/zvec	Lighter-weight, suited for desktop apps

Set in .env:

VECTOR_BACKEND=chromadb   # or zvec
ZVEC_PATH=./data/zvec     # only used when VECTOR_BACKEND=zvec

Both backends are local-only and store data on disk. No cloud calls.

Architecture

data/raw/*  →  data/processed/chunks.jsonl  →  data/chroma/*  →  query results
 (ingest)            (index)                      (query)

1. Ingest — alcove/ingest/ extracts PDF, EPUB, TXT, HTML, Markdown, CSV, JSON, JSONL, and DOCX into normalized JSONL chunks
2. Index — alcove/index/ embeds chunks and writes vectors to the configured backend
3. Query — alcove/query/ retrieves from the local vector store via CLI or API

See Architecture for details.

Documentation

• Architecture
• Seed corpus
• Operations
• Security
• Roadmap
• Contributing

License

MIT