msgsearch 0.2.0__tar.gz → 0.2.1__tar.gz

{msgsearch-0.2.0 → msgsearch-0.2.1}/CHANGELOG.md

@@ -3,6 +3,24 @@
 Notable changes to msgsearch. Retrieval changes carry the measurement that
 justified them; see `ARCHITECTURE.md` for the full evaluation.
 
+## [0.2.1] — 2026-09-06
+
+Documentation only. PyPI freezes a project's description at publish time, so
+correcting the README required a release.
+
+### Fixed
+- The install instructions recommended `pipx install --python <arm64 python>`,
+  which does not work on Apple silicon with an Intel Homebrew. Python from
+  python.org is a universal binary that runs as whichever architecture its
+  parent process is, so an Intel-built pipx launches it as x86_64 whichever
+  interpreter you name, and PyTorch has no x86_64 macOS wheels. The working
+  recipe creates the venv under `arch -arm64`.
+
+### Added
+- A quickstart covering install through first search in one block, and an
+  explicit note that Full Disk Access and Contacts are separate permissions
+  granted to the application rather than the shell.
+
 ## [0.2.0] — 2026-09-06
 
 ### Added

{msgsearch-0.2.0 → msgsearch-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: msgsearch
-Version: 0.2.0
+Version: 0.2.1
 Summary: Search your iMessage history by meaning, entirely on your own machine.
 Project-URL: Homepage, https://github.com/dhruv1707/msgsearch
 Project-URL: Documentation, https://github.com/dhruv1707/msgsearch/blob/main/README.md
@@ -63,46 +63,113 @@ up to make committing it difficult. Treat that directory the way you would treat
 password manager's database. Both models run locally, so nothing is uploaded, but
 what lands on your disk is unencrypted.
 
-## Requirements
+## Quickstart
 
-- macOS with an **arm64** Python 3.10 or newer. PyTorch stopped publishing
-  x86_64 macOS wheels, so an Intel-built interpreter cannot install torch and
-  cannot use the GPU — and Homebrew's `/usr/local` Python is an Intel build even
-  on Apple silicon. Check with:
+```bash
+# 1. install  (needs an arm64 Python — see Install if this errors)
+pipx install msgsearch
 
-  ```bash
-  python3 -c "import platform; print(platform.machine())"   # must say arm64
-  ```
+# 2. get the embedding model
+#    accept the licence at huggingface.co/google/embeddinggemma-300m, then:
+hf auth login
 
-  If it says `x86_64`, point the installer at an arm64 interpreter explicitly:
+# 3. snapshot your messages            [needs Full Disk Access]
+msgsearch sync
 
-  ```bash
-  pipx install --python /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 msgsearch
-  ```
+# 4. check the setup, and fix whatever it names
+msgsearch doctor
 
-  Architecture is not something package metadata can express, so this fails at
-  dependency resolution rather than with a helpful message. `msgsearch doctor`
-  checks it.
+# 5. build the index                   [~30 min per 100k messages, once]
+msgsearch index
+
+# 6. search
+msgsearch search "that restaurant we talked about"
+```
+
+Afterwards, one command keeps it current — only genuinely new text is embedded,
+so it takes seconds:
+
+```bash
+msgsearch sync --index
+```
+
+**Two permissions, and they are different.** `sync` needs **Full Disk Access** to
+read `~/Library/Messages`. Resolving names needs **Contacts**. macOS grants both
+to the *application*, not the shell, so if you run from an editor's integrated
+terminal the grant has to go to the editor — Terminal.app is the simple option.
+Both live in System Settings → Privacy & Security, and you must restart the app
+afterwards.
+
+## Requirements
+
+- **macOS on Apple silicon.** PyTorch no longer publishes x86_64 macOS wheels.
+- **Python 3.10 or newer, running as arm64.** See the note below — this is the
+  one thing that reliably goes wrong.
 - About 3 GB of disk for dependencies and model weights.
 
 ## Install
 
 ```bash
-uvx msgsearch doctor          # run it without installing anything
-pipx install msgsearch        # or install the command globally
+pipx install msgsearch
+msgsearch doctor
 ```
 
-Either pulls PyTorch, which is around 1 GB, so the first run is slow. Everything
-after that is local and fast.
+This pulls PyTorch, around 1 GB, so the first install is slow. Everything after
+that is local and fast.
+
+<details>
+<summary><b>If that fails with "No matching distribution found for torch"</b></summary>
 
-To work on it instead, clone and install in place:
+You have an Intel-built Python, which is common on Apple silicon after migrating
+from an Intel Mac. Check:
+
+```bash
+python3 -c "import platform; print(platform.machine())"   # must say arm64
+```
+
+The confusing part is that `pipx install --python /path/to/arm64/python` often
+**does not fix it**. Python from python.org is a *universal* binary that runs as
+whichever architecture its parent process is, and if pipx itself was installed by
+an Intel Homebrew (`/usr/local/...`), it launches that Python as x86_64. pip then
+looks for x86_64 wheels that PyTorch does not publish.
+
+Install into a venv created explicitly under arm64 instead:
+
+```bash
+arch -arm64 /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 \
+    -m venv ~/.msgsearch-venv
+~/.msgsearch-venv/bin/pip install msgsearch
+ln -sf ~/.msgsearch-venv/bin/msgsearch /usr/local/bin/msgsearch
+```
+
+Adjust the interpreter path to any arm64 Python 3.10+. To undo:
+`rm /usr/local/bin/msgsearch && rm -rf ~/.msgsearch-venv`.
+
+Architecture cannot be expressed in package metadata, which is why this surfaces
+as a dependency-resolution wall rather than a useful error. `msgsearch doctor`
+reports it in one line.
+</details>
+
+To work on msgsearch rather than use it:
 
 ```bash
 git clone https://github.com/dhruv1707/msgsearch && cd msgsearch
-python3 -m venv .venv                  # must be an arm64 interpreter
+arch -arm64 python3 -m venv .venv          # must be an arm64 interpreter
 ./.venv/bin/python -m pip install -e ".[dev]"
 ```
 
+## Setup
+
+Get access to the embedding model. `google/embeddinggemma-300m` is gated, so
+accept the licence at <https://huggingface.co/google/embeddinggemma-300m>, then:
+
+```bash
+hf auth login
+```
+
+Any sentence-transformers model works instead, for example
+`MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5`.
+
 Take a snapshot of the Messages database. **Never point this tool at
 `~/Library/Messages`**: that file is live, Messages.app holds locks on it, and it
 is irreplaceable.

{msgsearch-0.2.0 → msgsearch-0.2.1}/README.md

@@ -17,46 +17,113 @@ up to make committing it difficult. Treat that directory the way you would treat
 password manager's database. Both models run locally, so nothing is uploaded, but
 what lands on your disk is unencrypted.
 
-## Requirements
+## Quickstart
 
-- macOS with an **arm64** Python 3.10 or newer. PyTorch stopped publishing
-  x86_64 macOS wheels, so an Intel-built interpreter cannot install torch and
-  cannot use the GPU — and Homebrew's `/usr/local` Python is an Intel build even
-  on Apple silicon. Check with:
+```bash
+# 1. install  (needs an arm64 Python — see Install if this errors)
+pipx install msgsearch
 
-  ```bash
-  python3 -c "import platform; print(platform.machine())"   # must say arm64
-  ```
+# 2. get the embedding model
+#    accept the licence at huggingface.co/google/embeddinggemma-300m, then:
+hf auth login
 
-  If it says `x86_64`, point the installer at an arm64 interpreter explicitly:
+# 3. snapshot your messages            [needs Full Disk Access]
+msgsearch sync
 
-  ```bash
-  pipx install --python /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 msgsearch
-  ```
+# 4. check the setup, and fix whatever it names
+msgsearch doctor
 
-  Architecture is not something package metadata can express, so this fails at
-  dependency resolution rather than with a helpful message. `msgsearch doctor`
-  checks it.
+# 5. build the index                   [~30 min per 100k messages, once]
+msgsearch index
+
+# 6. search
+msgsearch search "that restaurant we talked about"
+```
+
+Afterwards, one command keeps it current — only genuinely new text is embedded,
+so it takes seconds:
+
+```bash
+msgsearch sync --index
+```
+
+**Two permissions, and they are different.** `sync` needs **Full Disk Access** to
+read `~/Library/Messages`. Resolving names needs **Contacts**. macOS grants both
+to the *application*, not the shell, so if you run from an editor's integrated
+terminal the grant has to go to the editor — Terminal.app is the simple option.
+Both live in System Settings → Privacy & Security, and you must restart the app
+afterwards.
+
+## Requirements
+
+- **macOS on Apple silicon.** PyTorch no longer publishes x86_64 macOS wheels.
+- **Python 3.10 or newer, running as arm64.** See the note below — this is the
+  one thing that reliably goes wrong.
 - About 3 GB of disk for dependencies and model weights.
 
 ## Install
 
 ```bash
-uvx msgsearch doctor          # run it without installing anything
-pipx install msgsearch        # or install the command globally
+pipx install msgsearch
+msgsearch doctor
 ```
 
-Either pulls PyTorch, which is around 1 GB, so the first run is slow. Everything
-after that is local and fast.
+This pulls PyTorch, around 1 GB, so the first install is slow. Everything after
+that is local and fast.
+
+<details>
+<summary><b>If that fails with "No matching distribution found for torch"</b></summary>
 
-To work on it instead, clone and install in place:
+You have an Intel-built Python, which is common on Apple silicon after migrating
+from an Intel Mac. Check:
+
+```bash
+python3 -c "import platform; print(platform.machine())"   # must say arm64
+```
+
+The confusing part is that `pipx install --python /path/to/arm64/python` often
+**does not fix it**. Python from python.org is a *universal* binary that runs as
+whichever architecture its parent process is, and if pipx itself was installed by
+an Intel Homebrew (`/usr/local/...`), it launches that Python as x86_64. pip then
+looks for x86_64 wheels that PyTorch does not publish.
+
+Install into a venv created explicitly under arm64 instead:
+
+```bash
+arch -arm64 /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 \
+    -m venv ~/.msgsearch-venv
+~/.msgsearch-venv/bin/pip install msgsearch
+ln -sf ~/.msgsearch-venv/bin/msgsearch /usr/local/bin/msgsearch
+```
+
+Adjust the interpreter path to any arm64 Python 3.10+. To undo:
+`rm /usr/local/bin/msgsearch && rm -rf ~/.msgsearch-venv`.
+
+Architecture cannot be expressed in package metadata, which is why this surfaces
+as a dependency-resolution wall rather than a useful error. `msgsearch doctor`
+reports it in one line.
+</details>
+
+To work on msgsearch rather than use it:
 
 ```bash
 git clone https://github.com/dhruv1707/msgsearch && cd msgsearch
-python3 -m venv .venv                  # must be an arm64 interpreter
+arch -arm64 python3 -m venv .venv          # must be an arm64 interpreter
 ./.venv/bin/python -m pip install -e ".[dev]"
 ```
 
+## Setup
+
+Get access to the embedding model. `google/embeddinggemma-300m` is gated, so
+accept the licence at <https://huggingface.co/google/embeddinggemma-300m>, then:
+
+```bash
+hf auth login
+```
+
+Any sentence-transformers model works instead, for example
+`MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5`.
+
 Take a snapshot of the Messages database. **Never point this tool at
 `~/Library/Messages`**: that file is live, Messages.app holds locks on it, and it
 is irreplaceable.

{msgsearch-0.2.0 → msgsearch-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "msgsearch"
-version = "0.2.0"
+version = "0.2.1"
 description = "Search your iMessage history by meaning, entirely on your own machine."
 readme = "README.md"
 license = { file = "LICENSE" }

{msgsearch-0.2.0 → msgsearch-0.2.1}/src/msgsearch/__init__.py

@@ -13,6 +13,6 @@ The pipeline, in the order data flows through it:
 Nothing here sends message text anywhere. Both models run locally.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = ["__version__"]