keep-skill 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

keep/api.py

@@ -962,6 +962,28 @@ class Keeper:
 
         return filtered
 
+    def get_version_offset(self, item: Item, collection: Optional[str] = None) -> int:
+        """
+        Get version offset (0=current, 1=previous, ...) for an item.
+
+        Converts the internal version number (1=oldest, 2=next...) to the
+        user-visible offset format (0=current, 1=previous, 2=two-ago...).
+
+        Args:
+            item: Item to get version offset for
+            collection: Target collection
+
+        Returns:
+            Version offset (0 for current version)
+        """
+        version_tag = item.tags.get("_version")
+        if not version_tag:
+            return 0  # Current version
+        base_id = item.tags.get("_base_id", item.id)
+        coll = self._resolve_collection(collection)
+        version_count = self._document_store.version_count(coll, base_id)
+        return version_count - int(version_tag) + 1
+
     def query_fulltext(
         self,
         query: str,

keep/cli.py

@@ -17,7 +17,6 @@ from typing import Optional
 import typer
 from typing_extensions import Annotated
 
-
 # Pattern for version identifier suffix: @V{N} where N is digits only
 VERSION_SUFFIX_PATTERN = re.compile(r'@V\{(\d+)\}$')
 
@@ -87,6 +86,7 @@ def _format_yaml_frontmatter(
     version_nav: Optional[dict[str, list[VersionInfo]]] = None,
     viewing_offset: Optional[int] = None,
     similar_items: Optional[list[Item]] = None,
+    similar_offsets: Optional[dict[str, int]] = None,
 ) -> str:
     """
     Format item as YAML frontmatter with summary as content.
@@ -96,6 +96,7 @@ def _format_yaml_frontmatter(
         version_nav: Optional version navigation info (prev/next lists)
         viewing_offset: If viewing an old version, the offset (1=previous, 2=two ago)
         similar_items: Optional list of similar items to display
+        similar_offsets: Version offsets for similar items (item.id -> offset)
 
     Note: Offset computation (v1, v2, etc.) assumes version_nav lists
     are ordered newest-first, matching list_versions() ordering.
@@ -110,14 +111,20 @@ def _format_yaml_frontmatter(
     if item.score is not None:
         lines.append(f"score: {item.score:.3f}")
 
-    # Add similar items if available
+    # Add similar items if available (version-scoped IDs with date and summary)
     if similar_items:
         lines.append("similar:")
         for sim_item in similar_items:
+            base_id = sim_item.tags.get("_base_id", sim_item.id)
+            offset = (similar_offsets or {}).get(sim_item.id, 0)
             score_str = f"({sim_item.score:.2f})" if sim_item.score else ""
-            lines.append(f"  - {sim_item.id} {score_str}")
+            date_part = sim_item.tags.get("_updated", sim_item.tags.get("_created", ""))[:10]
+            summary_preview = sim_item.summary[:40].replace("\n", " ")
+            if len(sim_item.summary) > 40:
+                summary_preview += "..."
+            lines.append(f"  - {base_id}@V{{{offset}}} {score_str} {date_part} {summary_preview}")
 
-    # Add version navigation if available
+    # Add version navigation (just @V{N} since ID is shown at top, with date + summary)
     if version_nav:
         # Current offset (0 if viewing current)
         current_offset = viewing_offset if viewing_offset is not None else 0
@@ -125,27 +132,25 @@ def _format_yaml_frontmatter(
         if version_nav.get("prev"):
             lines.append("prev:")
             for i, v in enumerate(version_nav["prev"]):
-                # Offset for this prev item: current_offset + i + 1
                 prev_offset = current_offset + i + 1
-                date_part = v.created_at[:10] if v.created_at else "unknown"
+                date_part = v.created_at[:10] if v.created_at else ""
                 summary_preview = v.summary[:40].replace("\n", " ")
                 if len(v.summary) > 40:
                     summary_preview += "..."
-                lines.append(f"  - v{prev_offset}: {date_part} {summary_preview}")
+                lines.append(f"  - @V{{{prev_offset}}} {date_part} {summary_preview}")
         if version_nav.get("next"):
             lines.append("next:")
             for i, v in enumerate(version_nav["next"]):
-                # Offset for this next item: current_offset - i - 1
                 next_offset = current_offset - i - 1
-                date_part = v.created_at[:10] if v.created_at else "unknown"
+                date_part = v.created_at[:10] if v.created_at else ""
                 summary_preview = v.summary[:40].replace("\n", " ")
                 if len(v.summary) > 40:
                     summary_preview += "..."
-                lines.append(f"  - v{next_offset}: {date_part} {summary_preview}")
+                lines.append(f"  - @V{{{next_offset}}} {date_part} {summary_preview}")
         elif viewing_offset is not None:
             # Viewing old version and next is empty means current is next
             lines.append("next:")
-            lines.append("  - v0 (current)")
+            lines.append(f"  - @V{{0}}")
 
     lines.append("---")
     lines.append(item.summary)  # Summary IS the content
@@ -188,11 +193,13 @@ def main_callback(
         item = kp.get_now()
         version_nav = kp.get_version_nav(NOWDOC_ID, None, collection="default")
         similar_items = kp.get_similar_for_display(NOWDOC_ID, limit=3, collection="default")
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
         typer.echo(_format_item(
             item,
             as_json=_get_json_output(),
             version_nav=version_nav,
             similar_items=similar_items,
+            similar_offsets=similar_offsets,
         ))
 
 
@@ -245,6 +252,7 @@ def _format_item(
     version_nav: Optional[dict[str, list[VersionInfo]]] = None,
     viewing_offset: Optional[int] = None,
     similar_items: Optional[list[Item]] = None,
+    similar_offsets: Optional[dict[str, int]] = None,
 ) -> str:
     """
     Format an item for display.
@@ -258,6 +266,7 @@ def _format_item(
         version_nav: Optional version navigation info (prev/next lists)
         viewing_offset: If viewing an old version, the offset (1=previous, 2=two ago)
         similar_items: Optional list of similar items to display
+        similar_offsets: Version offsets for similar items (item.id -> offset)
     """
     if _get_ids_output():
         return json.dumps(item.id) if as_json else item.id
@@ -274,7 +283,12 @@ def _format_item(
             result["vid"] = f"{item.id}@V{{{viewing_offset}}}"
         if similar_items:
             result["similar"] = [
-                {"id": s.id, "score": s.score, "summary": s.summary[:60]}
+                {
+                    "id": f"{s.tags.get('_base_id', s.id)}@V{{{(similar_offsets or {}).get(s.id, 0)}}}",
+                    "score": s.score,
+                    "date": s.tags.get("_updated", s.tags.get("_created", ""))[:10],
+                    "summary": s.summary[:60],
+                }
                 for s in similar_items
             ]
         if version_nav:
@@ -304,7 +318,7 @@ def _format_item(
                 result["version_nav"]["next"] = [{"offset": 0, "vid": f"{item.id}@V{{0}}", "label": "current"}]
         return json.dumps(result)
 
-    return _format_yaml_frontmatter(item, version_nav, viewing_offset, similar_items)
+    return _format_yaml_frontmatter(item, version_nav, viewing_offset, similar_items, similar_offsets)
 
 
 def _format_items(items: list[Item], as_json: bool = False) -> str:
@@ -417,7 +431,7 @@ def find(
 
 @app.command()
 def search(
-    query: Annotated[str, typer.Argument(help="Full-text search query")],
+    query: Annotated[str, typer.Argument(default=..., help="Full-text search query")],
     store: StoreOption = None,
     collection: CollectionOption = "default",
     limit: LimitOption = 10,
@@ -519,7 +533,7 @@ def tag(
 
 @app.command("tag-update")
 def tag_update(
-    ids: Annotated[list[str], typer.Argument(help="Document IDs to tag")],
+    ids: Annotated[list[str], typer.Argument(default=..., help="Document IDs to tag")],
     tags: Annotated[Optional[list[str]], typer.Option(
         "--tag", "-t",
         help="Tag as key=value (empty value removes: key=)"
@@ -807,17 +821,19 @@ def now(
         item = kp.get_now()
         version_nav = kp.get_version_nav(NOWDOC_ID, None, collection=collection)
         similar_items = kp.get_similar_for_display(NOWDOC_ID, limit=3, collection=collection)
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
         typer.echo(_format_item(
             item,
             as_json=_get_json_output(),
             version_nav=version_nav,
             similar_items=similar_items,
+            similar_offsets=similar_offsets,
         ))
 
 
 @app.command()
 def get(
-    id: Annotated[str, typer.Argument(help="URI of item (append @V{N} for version)")],
+    id: Annotated[str, typer.Argument(default=..., help="URI of item (append @V{N} for version)")],
     version: Annotated[Optional[int], typer.Option(
         "--version", "-V",
         help="Get specific version (0=current, 1=previous, etc.)"
@@ -927,18 +943,22 @@ def get(
     if similar:
         # List similar items
         similar_items = kp.get_similar_for_display(actual_id, limit=limit, collection=collection)
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
 
         if _get_ids_output():
-            # Output IDs one per line
+            # Output version-scoped IDs one per line
             for item in similar_items:
-                typer.echo(item.id)
+                base_id = item.tags.get("_base_id", item.id)
+                offset = similar_offsets.get(item.id, 0)
+                typer.echo(f"{base_id}@V{{{offset}}}")
         elif _get_json_output():
             result = {
                 "id": actual_id,
                 "similar": [
                     {
-                        "id": item.id,
+                        "id": f"{item.tags.get('_base_id', item.id)}@V{{{similar_offsets.get(item.id, 0)}}}",
                         "score": item.score,
+                        "date": item.tags.get("_updated", item.tags.get("_created", ""))[:10],
                         "summary": item.summary[:60],
                     }
                     for item in similar_items
@@ -949,11 +969,14 @@ def get(
             typer.echo(f"Similar to {actual_id}:")
             if similar_items:
                 for item in similar_items:
+                    base_id = item.tags.get("_base_id", item.id)
+                    offset = similar_offsets.get(item.id, 0)
                     score_str = f"({item.score:.2f})" if item.score else ""
+                    date_part = item.tags.get("_updated", item.tags.get("_created", ""))[:10]
                     summary_preview = item.summary[:50].replace("\n", " ")
                     if len(item.summary) > 50:
                         summary_preview += "..."
-                    typer.echo(f"  {item.id} {score_str} {summary_preview}")
+                    typer.echo(f"  {base_id}@V{{{offset}}} {score_str} {date_part} {summary_preview}")
             else:
                 typer.echo("  No similar items found.")
         return
@@ -985,8 +1008,10 @@ def get(
 
     # Get similar items (unless suppressed or viewing old version)
     similar_items = None
+    similar_offsets = None
     if not no_similar and offset == 0:
         similar_items = kp.get_similar_for_display(actual_id, limit=3, collection=collection)
+        similar_offsets = {s.id: kp.get_version_offset(s) for s in similar_items}
 
     typer.echo(_format_item(
         item,
@@ -994,6 +1019,7 @@ def get(
         version_nav=version_nav,
         viewing_offset=offset if offset > 0 else None,
         similar_items=similar_items,
+        similar_offsets=similar_offsets,
     ))
 
 

keep/config.py

@@ -14,10 +14,7 @@ from pathlib import Path
 from typing import Any, Optional
 
 # tomli_w for writing TOML (tomllib is read-only)
-try:
-    import tomli_w
-except ImportError:
-    tomli_w = None  # type: ignore
+import tomli_w
 
 
 CONFIG_FILENAME = "keep.toml"
@@ -387,9 +384,6 @@ def save_config(config: StoreConfig) -> None:
 
     Creates the directory if it doesn't exist.
     """
-    if tomli_w is None:
-        raise RuntimeError("tomli_w is required to save config. Install with: pip install tomli-w")
-
     # Ensure config directory exists
     config_location = config.config_dir if config.config_dir else config.path
     config_location.mkdir(parents=True, exist_ok=True)

keep/store.py

@@ -58,15 +58,9 @@ class ChromaStore:
             embedding_dimension: Expected dimension of embeddings (for validation).
                 Can be None for read-only access; will be set on first write.
         """
-        try:
-            import chromadb
-            from chromadb.config import Settings
-        except ImportError:
-            raise RuntimeError(
-                "ChromaStore requires 'chromadb' library. "
-                "Install with: pip install chromadb"
-            )
-        
+        import chromadb
+        from chromadb.config import Settings
+
         self._store_path = store_path
         self._embedding_dimension = embedding_dimension
         

{keep_skill-0.4.1.dist-info → keep_skill-0.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keep-skill
-Version: 0.4.1
+Version: 0.4.2
 Summary: Semantic memory - remember and search documents by meaning
 Project-URL: Homepage, https://github.com/hughpyle/keep
 Project-URL: Repository, https://github.com/hughpyle/keep
@@ -56,7 +56,7 @@ Description-Content-Type: text/markdown
 Index documents and notes. Search by meaning. Track changes over time.
 
 ```bash
-pip install 'keep-skill[local]'
+uv tool install 'keep-skill[local]'
 keep init
 
 # Index content
@@ -90,16 +90,20 @@ Backed by ChromaDB for vectors, SQLite for metadata and versions.
 **Python 3.11–3.13 required.**
 
 ```bash
-# Recommended: local models (works offline)
-pip install 'keep-skill[local]'
-
-# Or with uv (faster):
+# Recommended: uv (isolated environment, fast)
 uv tool install 'keep-skill[local]'
 
-# API-based alternative (requires OPENAI_API_KEY)
-pip install 'keep-skill[openai]'
+# Alternative: pip in a virtual environment
+python -m venv .venv && source .venv/bin/activate
+pip install 'keep-skill[local]'
+
+# API-based (requires OPENAI_API_KEY)
+uv tool install 'keep-skill[openai]'
 ```
 
+> **Note:** Always use an isolated environment (uv or venv). Installing with system pip
+> may cause version conflicts with dependencies like typer.
+
 First run downloads embedding models (~3-5 minutes).
 
 ---

{keep_skill-0.4.1.dist-info → keep_skill-0.4.2.dist-info}/RECORD

@@ -1,9 +1,9 @@
 keep/__init__.py,sha256=1WVkySoomQuf9-o3pIKs1CC2OwIyfkiaCxn-mO6nhd8,1581
 keep/__main__.py,sha256=3Uu70IhIDIjh8OW6jp9jQQ3dF2lKdJWi_3FtRIQMiMY,104
-keep/api.py,sha256=EaPkI9Gv1r5LM8ZibqquGP_59xf4kQlCdv7nfct8QZw,58894
+keep/api.py,sha256=7oa6jdmeE55dATOEVw18sXGVBVndjiD_7tMDcP_xl_0,59746
 keep/chunking.py,sha256=neAXOLSvVwbUxapbqq7nZrbSNSzMXuhxj-ODoOSodsU,11830
-keep/cli.py,sha256=3flcfZHjvnHY8TxT-HJBBAuKnDusPAUD3ZwuMYYU7sw,40470
-keep/config.py,sha256=RRnHHvhc9KkJBYt0rpAFIvAVXw40b56xtT74TFIBiDU,15832
+keep/cli.py,sha256=DzZ5Dy4U25q-Mnbv5WbfRsZaN-ped24GDk34fVddmFA,42440
+keep/config.py,sha256=xhsTS_55HSzYxFNGt2z0q_0Ne-s9L9_3om8Uf_8gHB4,15643
 keep/context.py,sha256=CNpjmrv6eW2kV1E0MO6qAQfhYKRlfzAL--6v4Mj1nFY,71
 keep/document_store.py,sha256=UswqKIGSc5E-r7Tg9k0g5-byYnuar3e9FieQ7WNod9k,29109
 keep/errors.py,sha256=G9e5FbdfeugyfHOuL_SPZlM5jgWWnwsX4hM7IzanBZc,857
@@ -11,7 +11,7 @@ keep/indexing.py,sha256=dpPYo3WXnIhFDWinz5ZBZVk7_qumeNpP4EpOIY0zMbs,6063
 keep/logging_config.py,sha256=IGwkgIyg-TfYaT4MnoCXfmjeHAe_wsB_XQ1QhVT_ro8,3503
 keep/paths.py,sha256=Dv7pM6oo2QgjL6sj5wPjhuMOK2wqUkfd4Kz08TwJ1ps,3331
 keep/pending_summaries.py,sha256=_irGe7P1Lmog2c5cEgx-BElpq4YJW-tEmF5A3IUZQbQ,5727
-keep/store.py,sha256=d_exdEBQM7agpJcXL-nGsl46zXPQ2t35C8QF-NQX_Bw,18097
+keep/store.py,sha256=SBc2QdTyApdDDVjm2uZQI6tGbV5Hurfetgj7dyTO65o,17881
 keep/types.py,sha256=f6uOSYsYt6mj1ulKn2iRkooi__dWCiOQFPD6he2eID4,2149
 keep/providers/__init__.py,sha256=GFX_12g9OdjmpFUkTekOQBOWvcRW2Ae6yidfVVW2SiI,1095
 keep/providers/base.py,sha256=7Ug4Kj9fK2Dq4zDcZjn-GKsoZBOAlB9b-FMk969ER-g,14590
@@ -21,8 +21,8 @@ keep/providers/embeddings.py,sha256=zi8GyitKexdbCJyU1nLrUhGt_zzPn3udYrrPZ5Ak8Wo,
 keep/providers/llm.py,sha256=BxROKOklKbkGsHcSADPNNgWQExgSN6Bg4KPQIxVuB3U,12441
 keep/providers/mlx.py,sha256=aNl00r9tGi5tCGj2ArYH7CmDHtL1jLjVzb1rofU1DAo,9050
 keep/providers/summarization.py,sha256=MlVTcYipaqp2lT-QYnznp0AMuPVG36QfcTQnvY7Gb-Q,3409
-keep_skill-0.4.1.dist-info/METADATA,sha256=sasoFYgfL9FK4nuIK99pruVoiUH65I-SN30giqc2wHs,6387
-keep_skill-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-keep_skill-0.4.1.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
-keep_skill-0.4.1.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
-keep_skill-0.4.1.dist-info/RECORD,,
+keep_skill-0.4.2.dist-info/METADATA,sha256=GKkPrekD30dauxLoogAmSaoD2zhIxltJ4RDkg7yPvzk,6606
+keep_skill-0.4.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+keep_skill-0.4.2.dist-info/entry_points.txt,sha256=W8yiI4kNeW0IC8ji4EHRWrvdhFxzaqTIePUhJAJAMOo,39
+keep_skill-0.4.2.dist-info/licenses/LICENSE,sha256=zsm0tpvtyUkevcjn5BIvs9jAho8iwxq3Ax9647AaOSg,1086
+keep_skill-0.4.2.dist-info/RECORD,,