Metadata-Version: 2.4
Name: alcove-search
Version: 0.1.0
Summary: Local-first document retrieval. Your data never leaves your disk.
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.9
Requires-Dist: beautifulsoup4<5.0,>=4.12
Requires-Dist: chromadb<1.0,>=0.5.5
Requires-Dist: ebooklib<1.0,>=0.18
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'
Description-Content-Type: text/markdown

# Alcove

[![CI](https://github.com/Pro777/alcove-starter-private/actions/workflows/ci.yml/badge.svg)](https://github.com/Pro777/alcove-starter-private/actions/workflows/ci.yml)

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](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-starter-private.git
cd alcove-starter-private
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)
