Metadata-Version: 2.4
Name: alcove-search
Version: 0.2.0
Summary: Local-first document retrieval. Your data never leaves your disk.
Author-email: John Malone <john.malone@gmail.com>
License: MIT
License-File: LICENSE
Keywords: chromadb,documents,local-first,retrieval,search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4<5.0,>=4.12
Requires-Dist: chromadb<1.0,>=0.5.5
Requires-Dist: fastapi<1.0,>=0.115.0
Requires-Dist: jinja2<4.0,>=3.1
Requires-Dist: pypdf<5.0,>=4.3
Requires-Dist: python-multipart<1.0,>=0.0.6
Requires-Dist: uvicorn<1.0,>=0.30.0
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: python-docx>=1.0; extra == 'dev'
Provides-Extra: docx
Requires-Dist: python-docx>=1.0; extra == 'docx'
Provides-Extra: epub
Requires-Dist: ebooklib<1.0,>=0.18; extra == 'epub'
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=3.0; extra == 'semantic'
Provides-Extra: zvec
Requires-Dist: zvec>=0.1; extra == 'zvec'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/logo.svg" alt="Alcove" height="56">
</p>

<p align="center">
  <a href="https://github.com/Pro777/alcove/actions/workflows/ci.yml"><img src="https://github.com/Pro777/alcove/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/alcove-search/"><img src="https://img.shields.io/pypi/v/alcove-search" alt="PyPI"></a>
</p>

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

<p align="center">
  <img src="docs/assets/web-ui-screenshot.png" alt="Alcove web UI showing search results with file-type badges" width="760">
</p>

> **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.

> [Watch the 30-second CLI demo](https://pro777.github.io/alcove/demo.html)

## Get started

> **Requires:** Python 3.9+ — [download at python.org](https://www.python.org/downloads/) if you don't have it.

```bash
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](docs/SECURITY.md) for the full trust-boundary diagram.

---

## For developers

### CLI

```bash
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

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

### Make targets

```bash
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

```http
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`:

```bash
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](docs/ARCHITECTURE.md) for details.

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Seed corpus](docs/SEED_CORPUS.md)
- [Operations](docs/OPERATIONS.md)
- [Security](docs/SECURITY.md)
- [Roadmap](docs/ROADMAP.md)
- [Contributing](CONTRIBUTING.md)

## License

[MIT](LICENSE)
