semfind 0.1.0__tar.gz

semfind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 puri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semfind-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: semfind
+Version: 0.1.0
+Summary: Semantic grep for the terminal — search files by meaning, not pattern
+Author: puri
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/puri/semsearch
+Keywords: semantic-search,grep,embeddings,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastembed>=0.7.0
+Requires-Dist: faiss-cpu>=1.7.0
+Requires-Dist: numpy>=1.24.0
+Dynamic: license-file
+
+# semsearch
+
+Semantic grep for the terminal. Search files by meaning, not pattern.
+
+Uses [fastembed](https://github.com/qdrant/fastembed) (BAAI/bge-small-en-v1.5) + FAISS for fast local vector search. No API keys needed — everything runs locally.
+
+## Install
+
+```bash
+pip install semsearch
+```
+
+## Usage
+
+```bash
+# Search a file
+semsearch "deployment issue" logs.md
+
+# Search multiple files, top 3 results
+semsearch "permission error" memory/*.md -k 3
+
+# Show 2 lines of context around each match
+semsearch "database migration" notes.md -n 2
+
+# Force re-index (ignore cache)
+semsearch "query" file.md --reindex
+
+# Set minimum similarity threshold
+semsearch "auth bug" *.md -m 0.5
+```
+
+## How it works
+
+1. On first search, each file's non-empty lines are embedded and cached in `~/.cache/semsearch/`
+2. Cache is keyed by file content hash — changes auto-invalidate
+3. Your query is embedded and compared via FAISS inner-product search
+4. Results are printed grep-style with similarity scores
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-k, --top-k` | Number of results | 5 |
+| `-n, --context` | Context lines before/after | 0 |
+| `-m, --max-distance` | Minimum similarity score | none |
+| `--reindex` | Force re-embed | false |
+| `--model` | Embedding model | BAAI/bge-small-en-v1.5 |
+| `--no-cache` | Skip cache | false |
+| `--version` | Print version | |
+
+## License
+
+MIT

semfind-0.1.0/README.md

@@ -0,0 +1,53 @@
+# semsearch
+
+Semantic grep for the terminal. Search files by meaning, not pattern.
+
+Uses [fastembed](https://github.com/qdrant/fastembed) (BAAI/bge-small-en-v1.5) + FAISS for fast local vector search. No API keys needed — everything runs locally.
+
+## Install
+
+```bash
+pip install semsearch
+```
+
+## Usage
+
+```bash
+# Search a file
+semsearch "deployment issue" logs.md
+
+# Search multiple files, top 3 results
+semsearch "permission error" memory/*.md -k 3
+
+# Show 2 lines of context around each match
+semsearch "database migration" notes.md -n 2
+
+# Force re-index (ignore cache)
+semsearch "query" file.md --reindex
+
+# Set minimum similarity threshold
+semsearch "auth bug" *.md -m 0.5
+```
+
+## How it works
+
+1. On first search, each file's non-empty lines are embedded and cached in `~/.cache/semsearch/`
+2. Cache is keyed by file content hash — changes auto-invalidate
+3. Your query is embedded and compared via FAISS inner-product search
+4. Results are printed grep-style with similarity scores
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-k, --top-k` | Number of results | 5 |
+| `-n, --context` | Context lines before/after | 0 |
+| `-m, --max-distance` | Minimum similarity score | none |
+| `--reindex` | Force re-embed | false |
+| `--model` | Embedding model | BAAI/bge-small-en-v1.5 |
+| `--no-cache` | Skip cache | false |
+| `--version` | Print version | |
+
+## License
+
+MIT

semfind-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "semfind"
+version = "0.1.0"
+description = "Semantic grep for the terminal — search files by meaning, not pattern"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "puri" }]
+keywords = ["semantic-search", "grep", "embeddings", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: General",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "fastembed>=0.7.0",
+    "faiss-cpu>=1.7.0",
+    "numpy>=1.24.0",
+]
+
+[project.scripts]
+semsearch = "semsearch.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/puri/semsearch"
+
+[tool.setuptools.packages.find]
+where = ["src"]

semfind-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

semfind-0.1.0/src/semfind.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: semfind
+Version: 0.1.0
+Summary: Semantic grep for the terminal — search files by meaning, not pattern
+Author: puri
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/puri/semsearch
+Keywords: semantic-search,grep,embeddings,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastembed>=0.7.0
+Requires-Dist: faiss-cpu>=1.7.0
+Requires-Dist: numpy>=1.24.0
+Dynamic: license-file
+
+# semsearch
+
+Semantic grep for the terminal. Search files by meaning, not pattern.
+
+Uses [fastembed](https://github.com/qdrant/fastembed) (BAAI/bge-small-en-v1.5) + FAISS for fast local vector search. No API keys needed — everything runs locally.
+
+## Install
+
+```bash
+pip install semsearch
+```
+
+## Usage
+
+```bash
+# Search a file
+semsearch "deployment issue" logs.md
+
+# Search multiple files, top 3 results
+semsearch "permission error" memory/*.md -k 3
+
+# Show 2 lines of context around each match
+semsearch "database migration" notes.md -n 2
+
+# Force re-index (ignore cache)
+semsearch "query" file.md --reindex
+
+# Set minimum similarity threshold
+semsearch "auth bug" *.md -m 0.5
+```
+
+## How it works
+
+1. On first search, each file's non-empty lines are embedded and cached in `~/.cache/semsearch/`
+2. Cache is keyed by file content hash — changes auto-invalidate
+3. Your query is embedded and compared via FAISS inner-product search
+4. Results are printed grep-style with similarity scores
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-k, --top-k` | Number of results | 5 |
+| `-n, --context` | Context lines before/after | 0 |
+| `-m, --max-distance` | Minimum similarity score | none |
+| `--reindex` | Force re-embed | false |
+| `--model` | Embedding model | BAAI/bge-small-en-v1.5 |
+| `--no-cache` | Skip cache | false |
+| `--version` | Print version | |
+
+## License
+
+MIT

semfind-0.1.0/src/semfind.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/semfind.egg-info/PKG-INFO
+src/semfind.egg-info/SOURCES.txt
+src/semfind.egg-info/dependency_links.txt
+src/semfind.egg-info/entry_points.txt
+src/semfind.egg-info/requires.txt
+src/semfind.egg-info/top_level.txt
+src/semsearch/__init__.py
+src/semsearch/cli.py
+src/semsearch/index.py
+src/semsearch/search.py

semfind-0.1.0/src/semfind.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

semfind-0.1.0/src/semfind.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+semsearch = semsearch.cli:main

semfind-0.1.0/src/semfind.egg-info/requires.txt

@@ -0,0 +1,3 @@
+fastembed>=0.7.0
+faiss-cpu>=1.7.0
+numpy>=1.24.0

semfind-0.1.0/src/semfind.egg-info/top_level.txt

@@ -0,0 +1 @@
+semsearch

semfind-0.1.0/src/semsearch/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

semfind-0.1.0/src/semsearch/cli.py

@@ -0,0 +1,95 @@
+"""CLI entry point for semsearch."""
+
+import argparse
+import sys
+
+from . import __version__
+from .index import DEFAULT_MODEL
+from .search import search
+
+
+# ANSI color helpers
+def _cyan(s: str) -> str:
+    return f"\033[36m{s}\033[0m"
+
+
+def _green(s: str) -> str:
+    return f"\033[32m{s}\033[0m"
+
+
+def _dim(s: str) -> str:
+    return f"\033[2m{s}\033[0m"
+
+
+def _read_context_lines(filepath: str) -> list[str]:
+    with open(filepath) as f:
+        return f.readlines()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="semsearch",
+        description="Semantic grep — search files by meaning, not pattern.",
+    )
+    parser.add_argument("query", help="Search query")
+    parser.add_argument("files", nargs="+", help="Files to search")
+    parser.add_argument("-k", "--top-k", type=int, default=5, help="Number of results (default: 5)")
+    parser.add_argument("-n", "--context", type=int, default=0, help="Lines of context before/after match")
+    parser.add_argument("-m", "--max-distance", type=float, default=None, help="Minimum similarity threshold")
+    parser.add_argument("--reindex", action="store_true", help="Force re-embed even if cache exists")
+    parser.add_argument("--model", default=DEFAULT_MODEL, help=f"Embedding model (default: {DEFAULT_MODEL})")
+    parser.add_argument("--no-cache", action="store_true", help="Don't save/load embeddings cache")
+    parser.add_argument("--version", action="version", version=f"semsearch {__version__}")
+
+    args = parser.parse_args(argv)
+
+    # Validate files exist
+    missing = [f for f in args.files if not __import__("os").path.isfile(f)]
+    if missing:
+        for f in missing:
+            print(f"semsearch: {f}: No such file", file=sys.stderr)
+        return 1
+
+    results = search(
+        query=args.query,
+        filepaths=args.files,
+        top_k=args.top_k,
+        max_distance=args.max_distance,
+        model_name=args.model,
+        reindex=args.reindex,
+        no_cache=args.no_cache,
+    )
+
+    if not results:
+        print("No results found.", file=sys.stderr)
+        return 0
+
+    # Cache of file lines for context display
+    file_lines: dict[str, list[str]] = {}
+    ctx = args.context
+
+    for r in results:
+        if ctx > 0 and r.file not in file_lines:
+            file_lines[r.file] = _read_context_lines(r.file)
+
+        if ctx > 0:
+            lines = file_lines[r.file]
+            start = max(0, r.line_num - 1 - ctx)
+            end = min(len(lines), r.line_num + ctx)
+            for i in range(start, end):
+                ln = i + 1
+                text = lines[i].rstrip("\n")
+                if ln == r.line_num:
+                    print(f"{_cyan(r.file)}:{_green(str(ln))}: {text}  {_dim(f'({r.score:.3f})')}")
+                else:
+                    print(f"{_dim(f'{r.file}:{ln}: {text}')}")
+            if r != results[-1]:
+                print("--")
+        else:
+            print(f"{_cyan(r.file)}:{_green(str(r.line_num))}: {r.text}  {_dim(f'({r.score:.3f})')}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

semfind-0.1.0/src/semsearch/index.py

@@ -0,0 +1,98 @@
+"""Indexing: embed file lines, save/load from cache."""
+
+import hashlib
+import json
+import os
+from pathlib import Path
+
+import faiss
+import numpy as np
+from fastembed import TextEmbedding
+
+DEFAULT_MODEL = "BAAI/bge-small-en-v1.5"
+CACHE_DIR = Path.home() / ".cache" / "semsearch"
+
+# Module-level model cache to avoid re-loading across calls
+_model_cache: dict[str, TextEmbedding] = {}
+
+
+def _get_model(model_name: str) -> TextEmbedding:
+    if model_name not in _model_cache:
+        _model_cache[model_name] = TextEmbedding(model_name=model_name)
+    return _model_cache[model_name]
+
+
+def _content_hash(filepath: str) -> str:
+    h = hashlib.sha256()
+    with open(filepath, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _cache_key(filepath: str, model_name: str, content_hash: str) -> str:
+    raw = f"{os.path.abspath(filepath)}|{content_hash}|{model_name}"
+    return hashlib.sha256(raw.encode()).hexdigest()
+
+
+def _cache_paths(key: str) -> tuple[Path, Path]:
+    return CACHE_DIR / f"{key}.npy", CACHE_DIR / f"{key}.json"
+
+
+def _load_cache(filepath: str, model_name: str) -> tuple[np.ndarray, list[dict]] | None:
+    ch = _content_hash(filepath)
+    key = _cache_key(filepath, model_name, ch)
+    npy_path, json_path = _cache_paths(key)
+    if npy_path.exists() and json_path.exists():
+        embeddings = np.load(npy_path)
+        with open(json_path) as f:
+            metadata = json.load(f)
+        return embeddings, metadata
+    return None
+
+
+def _save_cache(filepath: str, model_name: str, embeddings: np.ndarray, metadata: list[dict]) -> None:
+    ch = _content_hash(filepath)
+    key = _cache_key(filepath, model_name, ch)
+    npy_path, json_path = _cache_paths(key)
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    np.save(npy_path, embeddings)
+    with open(json_path, "w") as f:
+        json.dump(metadata, f)
+
+
+def build_index(
+    filepath: str,
+    model_name: str = DEFAULT_MODEL,
+    reindex: bool = False,
+    no_cache: bool = False,
+) -> tuple[np.ndarray, list[dict]]:
+    """Embed all non-empty lines of a file. Returns (embeddings, metadata)."""
+    if not reindex and not no_cache:
+        cached = _load_cache(filepath, model_name)
+        if cached is not None:
+            return cached
+
+    with open(filepath) as f:
+        raw_lines = f.readlines()
+
+    lines: list[str] = []
+    metadata: list[dict] = []
+    for i, line in enumerate(raw_lines):
+        stripped = line.rstrip("\n")
+        if stripped.strip():
+            lines.append(stripped)
+            metadata.append({"file": filepath, "line_num": i + 1, "text": stripped})
+
+    if not lines:
+        empty = np.empty((0, 0), dtype=np.float32)
+        return empty, []
+
+    model = _get_model(model_name)
+    embeddings = np.array(list(model.embed(lines)), dtype=np.float32)
+    faiss.normalize_L2(embeddings)
+
+    if not no_cache:
+        _save_cache(filepath, model_name, embeddings, metadata)
+
+    return embeddings, metadata

semfind-0.1.0/src/semsearch/search.py

@@ -0,0 +1,63 @@
+"""Search: embed query, FAISS lookup, return ranked results."""
+
+from dataclasses import dataclass
+
+import faiss
+import numpy as np
+
+from .index import DEFAULT_MODEL, build_index, _get_model
+
+
+@dataclass
+class Result:
+    file: str
+    line_num: int
+    text: str
+    score: float
+
+
+def search(
+    query: str,
+    filepaths: list[str],
+    top_k: int = 5,
+    max_distance: float | None = None,
+    model_name: str = DEFAULT_MODEL,
+    reindex: bool = False,
+    no_cache: bool = False,
+) -> list[Result]:
+    """Search files for lines semantically similar to query."""
+    all_embeddings: list[np.ndarray] = []
+    all_metadata: list[dict] = []
+
+    for fp in filepaths:
+        embeddings, metadata = build_index(fp, model_name, reindex=reindex, no_cache=no_cache)
+        if embeddings.size == 0:
+            continue
+        all_embeddings.append(embeddings)
+        all_metadata.extend(metadata)
+
+    if not all_embeddings:
+        return []
+
+    combined = np.vstack(all_embeddings)
+    dim = combined.shape[1]
+    index = faiss.IndexFlatIP(dim)
+    index.add(combined)
+
+    model = _get_model(model_name)
+    query_vec = np.array(list(model.embed([query])), dtype=np.float32)
+    faiss.normalize_L2(query_vec)
+
+    k = min(top_k, len(all_metadata))
+    distances, indices = index.search(query_vec, k)
+
+    results: list[Result] = []
+    for score, idx in zip(distances[0], indices[0]):
+        if idx == -1:
+            continue
+        if max_distance is not None and score < max_distance:
+            continue
+        m = all_metadata[idx]
+        results.append(Result(file=m["file"], line_num=m["line_num"], text=m["text"], score=float(score)))
+
+    return results