msgsearch 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -3,6 +3,28 @@
 Notable changes to msgsearch. Retrieval changes carry the measurement that
 justified them; see `ARCHITECTURE.md` for the full evaluation.
 
+## [0.2.4] — 2026-09-06
+
+Documentation only; released because PyPI freezes a project's description at
+publish time.
+
+### Fixed
+- The Setup section explained the gated model twice, and the second copy used a
+  development path (`./.venv/bin/msgsearch`) that an installed user does not have.
+- Model access is now spelled out step by step: create an account, accept the
+  Gemma licence, create a **Read** token, run `msgsearch login`. It previously
+  assumed a HuggingFace account already existed and did not say which kind of
+  token to make.
+- States explicitly that the model downloads automatically on first index, about
+  1.2 GB, so nobody goes looking for a download step that does not exist.
+
+## [0.2.3] — 2026-09-06
+
+### Fixed
+- Model-loading failures printed a Python traceback around their instructions,
+  which reads as a crash rather than "you need to log in" and buries the steps
+  under a stack. They now print the guidance alone and exit non-zero.
+
 ## [0.2.2] — 2026-09-06
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: msgsearch
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -168,49 +168,60 @@ arch -arm64 python3 -m venv .venv          # must be an arm64 interpreter
 
 ## Setup
 
-Get access to the embedding model. `google/embeddinggemma-300m` is gated, so:
+### 1. Model access
 
-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
+The default embedding model, `google/embeddinggemma-300m`, is gated: Google
+requires you to accept its licence before downloading. This is a one-time thing.
 
-`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.
+1. **Create a HuggingFace account** if you do not have one — <https://huggingface.co/join>. Free.
+2. **Accept the licence.** Open <https://huggingface.co/google/embeddinggemma-300m>,
+   sign in, and click the button acknowledging the Gemma terms at the top of the
+   page. Approval is normally immediate.
+3. **Create a token.** Go to <https://huggingface.co/settings/tokens>, click
+   *Create new token*, give it the **Read** role, and copy it. It looks like
+   `hf_...`.
+4. **Log in:**
 
-Any sentence-transformers model works instead, for example
-`MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5`.
+   ```bash
+   msgsearch login
+   ```
 
-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.
+   Paste the token when prompted. It is stored in `~/.cache/huggingface`, not by
+   msgsearch. You can also pass it directly with `msgsearch login --token hf_...`.
+
+`msgsearch login` checks afterwards that the model is genuinely reachable, rather
+than only that the token is valid. Those are different conditions — you can be
+perfectly logged in and still be refused because step 2 was skipped — and
+HuggingFace reports both as the same 401 saying "please log in", which sends
+people back to re-do the step they already did.
+
+The model itself downloads automatically the first time you index, about 1.2 GB,
+cached in `~/.cache/huggingface`. There is no separate download step.
+
+**Don't want a HuggingFace account?** Use an ungated model instead. Retrieval is
+somewhat weaker, but nothing else changes:
 
 ```bash
-msgsearch sync
+export MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5
 ```
 
-This needs Full Disk Access, which macOS grants to the *application* running the
-command (System Settings → Privacy & Security → Full Disk Access). A terminal
-usually has it; an editor's integrated terminal often does not.
-
-It uses SQLite's backup API rather than `cp`, which matters more than it sounds.
-Messages runs in WAL mode, so your most recent messages live in a `chat.db-wal`
-sidecar until they are checkpointed — `cp chat.db` alone loses exactly the
-messages you are most likely to search for, silently. The snapshot folds the
-write-ahead log in and leaves a single self-contained file.
+### 2. Snapshot your messages
 
-The default embedding model, `google/embeddinggemma-300m`, is gated. You must
-accept the Gemma licence at
-<https://huggingface.co/google/embeddinggemma-300m> and authenticate:
+**Never point this tool at `~/Library/Messages`** — that file is live, Messages
+holds locks on it, and it is irreplaceable.
 
 ```bash
-./.venv/bin/msgsearch login
+msgsearch sync
 ```
 
-Any sentence-transformers model works instead if you would rather not, for example
-`MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5`.
+This needs Full Disk Access (see above for how to grant it). It uses SQLite's
+backup API rather than `cp`, which matters more than it sounds: Messages runs in
+WAL mode, so your most recent messages live in a `chat.db-wal` sidecar until they
+are checkpointed. `cp chat.db` alone drops exactly the messages you are most
+likely to search for, silently. The snapshot folds the write-ahead log in and
+leaves a single self-contained file.
 
-### Names
+### 3. Names (optional)
 
 Without names, speakers appear as phone numbers. Resolving them makes results
 readable *and* improves retrieval, because the speaker label is part of the text

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

@@ -122,49 +122,60 @@ arch -arm64 python3 -m venv .venv          # must be an arm64 interpreter
 
 ## Setup
 
-Get access to the embedding model. `google/embeddinggemma-300m` is gated, so:
+### 1. Model access
 
-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
+The default embedding model, `google/embeddinggemma-300m`, is gated: Google
+requires you to accept its licence before downloading. This is a one-time thing.
 
-`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.
+1. **Create a HuggingFace account** if you do not have one — <https://huggingface.co/join>. Free.
+2. **Accept the licence.** Open <https://huggingface.co/google/embeddinggemma-300m>,
+   sign in, and click the button acknowledging the Gemma terms at the top of the
+   page. Approval is normally immediate.
+3. **Create a token.** Go to <https://huggingface.co/settings/tokens>, click
+   *Create new token*, give it the **Read** role, and copy it. It looks like
+   `hf_...`.
+4. **Log in:**
 
-Any sentence-transformers model works instead, for example
-`MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5`.
+   ```bash
+   msgsearch login
+   ```
 
-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.
+   Paste the token when prompted. It is stored in `~/.cache/huggingface`, not by
+   msgsearch. You can also pass it directly with `msgsearch login --token hf_...`.
+
+`msgsearch login` checks afterwards that the model is genuinely reachable, rather
+than only that the token is valid. Those are different conditions — you can be
+perfectly logged in and still be refused because step 2 was skipped — and
+HuggingFace reports both as the same 401 saying "please log in", which sends
+people back to re-do the step they already did.
+
+The model itself downloads automatically the first time you index, about 1.2 GB,
+cached in `~/.cache/huggingface`. There is no separate download step.
+
+**Don't want a HuggingFace account?** Use an ungated model instead. Retrieval is
+somewhat weaker, but nothing else changes:
 
 ```bash
-msgsearch sync
+export MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5
 ```
 
-This needs Full Disk Access, which macOS grants to the *application* running the
-command (System Settings → Privacy & Security → Full Disk Access). A terminal
-usually has it; an editor's integrated terminal often does not.
-
-It uses SQLite's backup API rather than `cp`, which matters more than it sounds.
-Messages runs in WAL mode, so your most recent messages live in a `chat.db-wal`
-sidecar until they are checkpointed — `cp chat.db` alone loses exactly the
-messages you are most likely to search for, silently. The snapshot folds the
-write-ahead log in and leaves a single self-contained file.
+### 2. Snapshot your messages
 
-The default embedding model, `google/embeddinggemma-300m`, is gated. You must
-accept the Gemma licence at
-<https://huggingface.co/google/embeddinggemma-300m> and authenticate:
+**Never point this tool at `~/Library/Messages`** — that file is live, Messages
+holds locks on it, and it is irreplaceable.
 
 ```bash
-./.venv/bin/msgsearch login
+msgsearch sync
 ```
 
-Any sentence-transformers model works instead if you would rather not, for example
-`MSGSEARCH_EMBED_MODEL=BAAI/bge-small-en-v1.5`.
+This needs Full Disk Access (see above for how to grant it). It uses SQLite's
+backup API rather than `cp`, which matters more than it sounds: Messages runs in
+WAL mode, so your most recent messages live in a `chat.db-wal` sidecar until they
+are checkpointed. `cp chat.db` alone drops exactly the messages you are most
+likely to search for, silently. The snapshot folds the write-ahead log in and
+leaves a single self-contained file.
 
-### Names
+### 3. Names (optional)
 
 Without names, speakers appear as phone numbers. Resolving them makes results
 readable *and* improves retrieval, because the speaker label is part of the text

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

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

{msgsearch-0.2.2 → msgsearch-0.2.4}/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.2"
+__version__ = "0.2.4"
 
 __all__ = ["__version__"]

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

@@ -398,6 +398,12 @@ def main(argv: list[str] | None = None) -> int:
         return args.handler(args)
     except KeyboardInterrupt:
         return 130
+    except RuntimeError as error:
+        # Model loading raises RuntimeError carrying instructions the user can
+        # act on. A traceback around them reads as "this crashed" rather than
+        # "you need to log in", and buries the steps under a stack.
+        print(error, file=sys.stderr)
+        return 1
 
 
 if __name__ == "__main__":

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

@@ -73,10 +73,6 @@ class TestEntryPoint(unittest.TestCase):
             cli.main(["nonsense"])
 
 
-if __name__ == "__main__":
-    unittest.main()
-
-
 class TestLoginCommand(unittest.TestCase):
     """Authentication is a msgsearch command because `hf` is not on the PATH.
 
@@ -98,3 +94,7 @@ class TestLoginCommand(unittest.TestCase):
 
     def test_token_is_optional_so_it_can_prompt(self):
         self.assertIsNone(self.parser.parse_args(["login"]).token)
+
+
+if __name__ == "__main__":
+    unittest.main()