msgsearch 0.2.0__tar.gz → 0.2.2__tar.gz

{msgsearch-0.2.0 → msgsearch-0.2.2}/ARCHITECTURE.md

@@ -125,7 +125,7 @@ Both run locally on Metal via MPS.
 
 | role | model | notes |
 |---|---|---|
-| embedding | `google/embeddinggemma-300m` | 768-dim. **Gated** — needs Gemma licence acceptance and `hf auth login`. Matryoshka truncation to 512/256/128 available if the array grows. |
+| embedding | `google/embeddinggemma-300m` | 768-dim. **Gated** — needs Gemma licence acceptance and `msgsearch login`. Matryoshka truncation to 512/256/128 available if the array grows. |
 | rerank | `Qwen/Qwen3-Reranker-0.6B` | matches qmd's choice |
 
 Rerankers measured over 50 candidates on the one query available:

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

@@ -3,6 +3,40 @@
 Notable changes to msgsearch. Retrieval changes carry the measurement that
 justified them; see `ARCHITECTURE.md` for the full evaluation.
 
+## [0.2.2] — 2026-09-06
+
+### Added
+- `msgsearch login`, which authenticates with HuggingFace. The instructions
+  previously said to run `hf auth login`, but installing msgsearch does not put
+  `hf` on your PATH -- pipx exposes only the entry points a package declares, so
+  that step failed with "command not found" for everyone who installed normally.
+  It also verifies afterwards that the gated model is actually reachable, since
+  being logged in and having accepted the model licence are different things
+  whose failures look identical.
+
+### Changed
+- Full Disk Access instructions are now step by step, including that macOS grants
+  it to the application rather than the shell and that the application must be
+  restarted before it takes effect.
+
+## [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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: msgsearch
-Version: 0.2.0
+Version: 0.2.2
 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,124 @@ 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
+
+```bash
+# 1. install  (needs an arm64 Python — see Install if this errors)
+pipx install msgsearch
+
+# 2. get the embedding model  (accept the licence in a browser first, then:)
+msgsearch login
+
+# 3. snapshot your messages            [needs Full Disk Access]
+msgsearch sync
+
+# 4. check the setup, and fix whatever it names
+msgsearch doctor
+
+# 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:
 
-- 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
+msgsearch sync --index
+```
 
-  ```bash
-  python3 -c "import platform; print(platform.machine())"   # must say arm64
-  ```
+### Granting Full Disk Access
 
-  If it says `x86_64`, point the installer at an arm64 interpreter explicitly:
+Step 3 fails without it. macOS grants this to the **application**, not to your
+shell, so the grant goes to whatever program you type commands into.
 
-  ```bash
-  pipx install --python /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 msgsearch
-  ```
+1. Open **System Settings → Privacy & Security → Full Disk Access**
+2. Click **+**
+3. Press **⌘⇧G** and paste `/Applications/Utilities/Terminal.app`, then Open
+   (if you use iTerm, VS Code or another terminal, choose that instead)
+4. Make sure its toggle is **on**
+5. **Quit and reopen that application** — the permission is only read at launch
 
-  Architecture is not something package metadata can express, so this fails at
-  dependency resolution rather than with a helpful message. `msgsearch doctor`
-  checks it.
+Resolving contact names needs a *separate* permission, **Contacts**, granted the
+same way in the same place. It is optional; without it speakers appear as phone
+numbers. Full Disk Access does not include it.
+
+## 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:
+
+1. Accept the licence at <https://huggingface.co/google/embeddinggemma-300m>
+2. Create a read token at <https://huggingface.co/settings/tokens>
+3. Run `msgsearch login` and paste it
+
+`msgsearch login` checks afterwards that you can actually reach the model, since
+being logged in and having accepted the licence are different things — and the
+failure for the second looks identical to the first.
+
+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.
@@ -126,7 +204,7 @@ accept the Gemma licence at
 <https://huggingface.co/google/embeddinggemma-300m> and authenticate:
 
 ```bash
-./.venv/bin/hf auth login
+./.venv/bin/msgsearch login
 ```
 
 Any sentence-transformers model works instead if you would rather not, for example

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

@@ -17,46 +17,124 @@ 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
+
+```bash
+# 1. install  (needs an arm64 Python — see Install if this errors)
+pipx install msgsearch
+
+# 2. get the embedding model  (accept the licence in a browser first, then:)
+msgsearch login
+
+# 3. snapshot your messages            [needs Full Disk Access]
+msgsearch sync
+
+# 4. check the setup, and fix whatever it names
+msgsearch doctor
+
+# 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:
 
-- 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
+msgsearch sync --index
+```
 
-  ```bash
-  python3 -c "import platform; print(platform.machine())"   # must say arm64
-  ```
+### Granting Full Disk Access
 
-  If it says `x86_64`, point the installer at an arm64 interpreter explicitly:
+Step 3 fails without it. macOS grants this to the **application**, not to your
+shell, so the grant goes to whatever program you type commands into.
 
-  ```bash
-  pipx install --python /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 msgsearch
-  ```
+1. Open **System Settings → Privacy & Security → Full Disk Access**
+2. Click **+**
+3. Press **⌘⇧G** and paste `/Applications/Utilities/Terminal.app`, then Open
+   (if you use iTerm, VS Code or another terminal, choose that instead)
+4. Make sure its toggle is **on**
+5. **Quit and reopen that application** — the permission is only read at launch
 
-  Architecture is not something package metadata can express, so this fails at
-  dependency resolution rather than with a helpful message. `msgsearch doctor`
-  checks it.
+Resolving contact names needs a *separate* permission, **Contacts**, granted the
+same way in the same place. It is optional; without it speakers appear as phone
+numbers. Full Disk Access does not include it.
+
+## 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:
+
+1. Accept the licence at <https://huggingface.co/google/embeddinggemma-300m>
+2. Create a read token at <https://huggingface.co/settings/tokens>
+3. Run `msgsearch login` and paste it
+
+`msgsearch login` checks afterwards that you can actually reach the model, since
+being logged in and having accepted the licence are different things — and the
+failure for the second looks identical to the first.
+
+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.
@@ -80,7 +158,7 @@ accept the Gemma licence at
 <https://huggingface.co/google/embeddinggemma-300m> and authenticate:
 
 ```bash
-./.venv/bin/hf auth login
+./.venv/bin/msgsearch login
 ```
 
 Any sentence-transformers model works instead if you would rather not, for example

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "msgsearch"
-version = "0.2.0"
+version = "0.2.2"
 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.2}/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.2"
 
 __all__ = ["__version__"]

{msgsearch-0.2.0 → msgsearch-0.2.2}/src/msgsearch/cli.py

@@ -156,6 +156,63 @@ def _run_search(args) -> int:
     return 0
 
 
+def _add_login_command(subparsers) -> None:
+    parser = subparsers.add_parser(
+        "login",
+        help="authenticate with HuggingFace to download the embedding model",
+        description="The default embedding model is gated, so it needs a "
+        "HuggingFace account that has accepted its licence. This wraps the same "
+        "login the huggingface_hub library provides -- msgsearch owns the "
+        "command because installing msgsearch does not put `hf` on your PATH.",
+    )
+    parser.add_argument(
+        "--token",
+        metavar="TOKEN",
+        help="read token from https://huggingface.co/settings/tokens "
+        "(prompted for if omitted)",
+    )
+    parser.set_defaults(handler=_run_login)
+
+
+def _run_login(args) -> int:
+    from getpass import getpass
+
+    from huggingface_hub import login
+
+    from . import config
+
+    token = args.token
+    if not token:
+        print(f"A read token is needed to download {config.EMBED_MODEL}.")
+        print("Create one at https://huggingface.co/settings/tokens")
+        print(f"and accept the licence at https://huggingface.co/{config.EMBED_MODEL}")
+        try:
+            token = getpass("\nToken (input hidden): ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print()
+            return 130
+    if not token:
+        print("No token given.", file=sys.stderr)
+        return 1
+
+    try:
+        login(token=token)
+    except Exception as error:
+        print(f"Login failed: {error}", file=sys.stderr)
+        return 1
+
+    # Logging in successfully is not the same as having access to a gated model,
+    # and that difference is exactly what produces a baffling 401 later.
+    from .doctor import check_model
+
+    result = check_model()
+    print(f"\nlogged in. model: {result.detail}")
+    if result.fix:
+        print(result.fix)
+        return 1
+    return 0
+
+
 def _add_contacts_command(subparsers) -> None:
     parser = subparsers.add_parser(
         "contacts",
@@ -325,6 +382,7 @@ def build_parser() -> argparse.ArgumentParser:
     _add_doctor_command(subparsers)
     _add_explore_command(subparsers)
     _add_index_command(subparsers)
+    _add_login_command(subparsers)
     _add_search_command(subparsers)
     _add_sync_command(subparsers)
     return parser

{msgsearch-0.2.0 → msgsearch-0.2.2}/src/msgsearch/config.py

@@ -76,7 +76,7 @@ PASSAGE_STRIDE = 1
 
 # --- models ------------------------------------------------------------------
 
-# Gated on HuggingFace: accept the model terms and `hf auth login` once, or this
+# Gated on HuggingFace: accept the model terms and run `msgsearch login` once,
 # 401s. Must match the model the index was built with -- search.py checks.
 EMBED_MODEL = os.environ.get("MSGSEARCH_EMBED_MODEL", "google/embeddinggemma-300m")
 

{msgsearch-0.2.0 → msgsearch-0.2.2}/src/msgsearch/doctor.py

@@ -124,7 +124,7 @@ def check_model() -> Check:
                 FAIL,
                 f"{name} is gated and this machine is not authorised",
                 f"Accept the licence at https://huggingface.co/{name}, then run "
-                "'hf auth login'. An expired token gives this same error, so log in "
+                "'msgsearch login'. An expired token gives this same error, so log in "
                 "again even if you have before. Or set "
                 "MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5 to use an ungated model.",
             )

{msgsearch-0.2.0 → msgsearch-0.2.2}/src/msgsearch/embedder.py

@@ -37,7 +37,7 @@ def _load_failure_hint(model_name: str, error: Exception) -> str:
         f"is not authorised.\n\n"
         f"  1. Accept the licence at https://huggingface.co/{model_name}\n"
         f"  2. Create a read token at https://huggingface.co/settings/tokens\n"
-        f"  3. Run: hf auth login\n\n"
+        f"  3. Run: msgsearch login\n\n"
         f"Note that an *expired* token produces this same error, so re-run step 3 "
         f"even if you have logged in before. To use an ungated model instead:\n\n"
         f"  MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5\n\n"

{msgsearch-0.2.0 → msgsearch-0.2.2}/tests/test_cli.py

@@ -75,3 +75,26 @@ class TestEntryPoint(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestLoginCommand(unittest.TestCase):
+    """Authentication is a msgsearch command because `hf` is not on the PATH.
+
+    Installing msgsearch exposes only the entry points msgsearch declares, so
+    telling people to run `hf auth login` failed with "command not found" for
+    everyone who installed it normally rather than from a checkout.
+    """
+
+    def setUp(self):
+        self.parser = cli.build_parser()
+
+    def test_login_is_a_command(self):
+        args = self.parser.parse_args(["login"])
+        self.assertTrue(callable(args.handler))
+
+    def test_token_can_be_passed_non_interactively(self):
+        args = self.parser.parse_args(["login", "--token", "hf_example"])
+        self.assertEqual(args.token, "hf_example")
+
+    def test_token_is_optional_so_it_can_prompt(self):
+        self.assertIsNone(self.parser.parse_args(["login"]).token)