msgsearch 0.2.1__tar.gz → 0.2.2__tar.gz

{msgsearch-0.2.1 → 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.1 → msgsearch-0.2.2}/CHANGELOG.md

@@ -3,6 +3,22 @@
 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: msgsearch
-Version: 0.2.1
+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
@@ -69,9 +69,8 @@ what lands on your disk is unencrypted.
 # 1. install  (needs an arm64 Python — see Install if this errors)
 pipx install msgsearch
 
-# 2. get the embedding model
-#    accept the licence at huggingface.co/google/embeddinggemma-300m, then:
-hf auth login
+# 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
@@ -93,12 +92,21 @@ so it takes seconds:
 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.
+### Granting Full Disk Access
+
+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.
+
+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
+
+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
 
@@ -160,12 +168,15 @@ arch -arm64 python3 -m venv .venv          # must be an arm64 interpreter
 
 ## Setup
 
-Get access to the embedding model. `google/embeddinggemma-300m` is gated, so
-accept the licence at <https://huggingface.co/google/embeddinggemma-300m>, then:
+Get access to the embedding model. `google/embeddinggemma-300m` is gated, so:
 
-```bash
-hf auth login
-```
+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`.
@@ -193,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.1 → msgsearch-0.2.2}/README.md

@@ -23,9 +23,8 @@ what lands on your disk is unencrypted.
 # 1. install  (needs an arm64 Python — see Install if this errors)
 pipx install msgsearch
 
-# 2. get the embedding model
-#    accept the licence at huggingface.co/google/embeddinggemma-300m, then:
-hf auth login
+# 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
@@ -47,12 +46,21 @@ so it takes seconds:
 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.
+### Granting Full Disk Access
+
+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.
+
+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
+
+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
 
@@ -114,12 +122,15 @@ arch -arm64 python3 -m venv .venv          # must be an arm64 interpreter
 
 ## Setup
 
-Get access to the embedding model. `google/embeddinggemma-300m` is gated, so
-accept the licence at <https://huggingface.co/google/embeddinggemma-300m>, then:
+Get access to the embedding model. `google/embeddinggemma-300m` is gated, so:
 
-```bash
-hf auth login
-```
+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`.
@@ -147,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.1 → msgsearch-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "msgsearch"
-version = "0.2.1"
+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.1 → 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.1"
+__version__ = "0.2.2"
 
 __all__ = ["__version__"]

{msgsearch-0.2.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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)