Metadata-Version: 2.5
Name: pyqmd-mlx
Version: 0.7.0
Summary: Local hybrid search (BM25 + vectors + reranking) over markdown collections, running on MLX on Apple Silicon — a Python rewrite of qmd.
License-Expression: MIT
License-File: LICENSE
Keywords: apple-silicon,bm25,markdown,mcp,mlx,rag,search,vector-search
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.12
Requires-Dist: mcp>=2.0.0
Requires-Dist: mlx-embeddings>=0.1.0
Requires-Dist: mlx-lm>=0.31.3
Requires-Dist: pyyaml>=6.0
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: tree-sitter-go>=0.23.4
Requires-Dist: tree-sitter-javascript>=0.23.1
Requires-Dist: tree-sitter-python>=0.25.0
Requires-Dist: tree-sitter-rust>=0.24.0
Requires-Dist: tree-sitter-typescript>=0.23.2
Requires-Dist: tree-sitter>=0.26.0
Requires-Dist: typer>=0.15
Requires-Dist: wcmatch<12.0,>=11.0
Description-Content-Type: text/markdown

# qmd (Python/MLX rewrite)

Python/MLX rewrite of [qmd](https://github.com/tobi/qmd) — hybrid search over your markdown
collections. Apple Silicon + MLX only (no GGUF, no cross-platform support).

> **Beta: feedback wanted.** pyqmd is in public beta. Please report problems or surprises in
> [Issues](https://github.com/after2400/pyqmd/issues).

## Install

```sh
uv tool install pyqmd-mlx
```

(or `pipx install pyqmd-mlx`). The package is `pyqmd-mlx`; the command it installs is
`pyqmd` — PyPI's `pyqmd` is an unrelated project. Upgrade with `uv tool upgrade pyqmd-mlx`.

Or build it yourself from a clone:

```sh
git clone https://github.com/after2400/pyqmd && cd pyqmd
just install   # uv tool install --editable .
```

(editable, so pulling new commits in the clone updates the installed `pyqmd` command without
reinstalling)

```sh
just uninstall
```

## Usage

```sh
pyqmd collection add ~/notes --name notes
pyqmd embed
pyqmd query "how do I configure auth"
pyqmd mcp                 # MCP server over stdio
pyqmd mcp --http          # MCP server over Streamable HTTP
pyqmd --help
```

Index lives at `~/.cache/pyqmd/index.sqlite`, distinct from the live Node `qmd`'s
`~/.cache/qmd/index.sqlite` — both can coexist during the transition.

## Performance note: prefer `pyqmd mcp` for repeated queries

Every one-shot CLI call (`search`/`vsearch`/`query`) that touches embeddings pays a real,
per-process MLX model-load cost, and it doesn't get cheaper on repeat launches the way
Node's mmap-backed GGUF loading does (see `parity/README.md`'s "Performance benchmark"
section for why). Measured on an Apple Silicon Mac with a warm disk: `search` 0.4–0.5 s,
`vsearch` about 2.5 s, `query --no-rerank` 3.5–4.5 s, full `query` 9–11 s (a cold disk adds
more on the first run). If you're issuing more than one embedding-backed query, run
`pyqmd mcp` (or `pyqmd mcp --http`) instead of shelling out per query — it loads models once
and serves unlimited calls from the same process, which is the actual equivalent of Node's
cheap repeated invocations here, not a faster load path. Pure-BM25 `search` doesn't touch MLX
at all and stays cheap either way.

## Development

```sh
just develop     # install dev deps + pre-commit hooks
just test-fast   # non-slow suite
just test-slow   # real-model tests (downloads MLX weights)
just lint
```
