whatwasit 0.1.0__py3-none-any.whl

whatwasit/__init__.py

@@ -0,0 +1,3 @@
+"""whatwasit - local-first semantic search for your shell history."""
+
+__version__ = "0.1.0"

whatwasit/brand.py

@@ -0,0 +1,59 @@
+"""Single source of truth for product naming and on-disk identifiers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+APP_NAME = "whatwasit"
+CLI_NAME = "whatwasit"
+PYPI_NAME = "whatwasit"
+GITHUB_REPO = "whatwasit"
+
+# Pre-rename install used ``hist`` as the internal app id.
+LEGACY_APP_NAME = "hist"
+LEGACY_DB_FILENAME = "whatwasit.db"
+LEGACY_SOCKET_FILENAME = "whatwasit.sock"
+
+DB_FILENAME = f"{APP_NAME}.db"
+SOCKET_FILENAME = f"{APP_NAME}.sock"
+PID_FILENAME = "daemon.pid"
+CONFIG_FILENAME = "config.toml"
+
+
+def data_dir_name_candidates() -> tuple[str, ...]:
+    """Preferred data directory names, newest first."""
+    return (APP_NAME, LEGACY_APP_NAME)
+
+
+def config_dir_name_candidates() -> tuple[str, ...]:
+    """Preferred config directory names, newest first."""
+    return (APP_NAME, LEGACY_APP_NAME)
+
+
+def resolve_data_dir(xdg_data_home: Path) -> Path:
+    """Pick data dir: prefer new name, fall back to legacy if indexed there."""
+    for name in data_dir_name_candidates():
+        candidate = xdg_data_home / name
+        if (candidate / DB_FILENAME).is_file() or (candidate / LEGACY_DB_FILENAME).is_file():
+            return candidate
+    return xdg_data_home / APP_NAME
+
+
+def resolve_config_file(xdg_config_home: Path) -> Path:
+    """Pick config file path: prefer new, fall back to legacy if present."""
+    for name in config_dir_name_candidates():
+        path = xdg_config_home / name / CONFIG_FILENAME
+        if path.is_file():
+            return path
+    return xdg_config_home / APP_NAME / CONFIG_FILENAME
+
+
+def resolve_db_path(data_dir: Path) -> Path:
+    """Return the SQLite path, preferring the new filename when both exist."""
+    primary = data_dir / DB_FILENAME
+    legacy = data_dir / LEGACY_DB_FILENAME
+    if primary.is_file():
+        return primary
+    if legacy.is_file():
+        return legacy
+    return primary

whatwasit/cli.py

@@ -0,0 +1,216 @@
+"""Command-line entry point for ``whatwasit``.
+
+Two modes:
+
+- ``whatwasit index [--window N] [--rebuild]`` builds/refreshes the on-disk index
+  from shell history.
+- ``whatwasit <natural language query...>`` (the common case) searches the index
+  and renders the results with :mod:`whatwasit.output`.
+
+Implemented with :mod:`argparse`; the query subcommand is detected purely by
+position (``index`` is only ever a subcommand when it is the first token),
+so a bare quoted natural-language query never collides with it unless the
+query literally starts with the word ``index``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from typing import List, Optional, Sequence
+
+from .config import Config
+from .daemon import daemon_search, daemon_status, start_daemon, stop_daemon
+from .embedder import is_model_cached
+from .indexer import build_index_from_history
+from .output import display_results
+from .search import search
+from .tui import run_repl
+
+from .brand import CLI_NAME
+
+PROG = CLI_NAME
+
+
+def _configure_hf_hub_when_cached() -> None:
+    """Avoid hub network/progress overhead when ONNX assets are already local."""
+    if is_model_cached(Config.default()):
+        os.environ.setdefault("HF_HUB_OFFLINE", "1")
+        os.environ.setdefault("TRANSFORMERS_OFFLINE", "1")
+        os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=PROG,
+        description="Local-first semantic search over your shell history.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    index_parser = subparsers.add_parser(
+        "index", help="Build or refresh the search index from shell history."
+    )
+    index_parser.add_argument(
+        "--window",
+        type=int,
+        default=None,
+        help="Session grouping window in seconds (default: config default).",
+    )
+    index_parser.add_argument(
+        "--rebuild",
+        action="store_true",
+        help="Force a full rebuild of the index from scratch.",
+    )
+
+    daemon_parser = subparsers.add_parser(
+        "daemon", help="Start, stop, or check the warm-query daemon."
+    )
+    daemon_parser.add_argument(
+        "action",
+        choices=("start", "stop", "status"),
+        help="Daemon control action.",
+    )
+
+    return parser
+
+
+def _print_help(parser: argparse.ArgumentParser) -> None:
+    parser.print_help()
+
+
+def _run_index(args: argparse.Namespace) -> int:
+    config = Config.default()
+    if args.window is not None:
+        config.session_window_seconds = args.window
+
+    stats = build_index_from_history(config)
+    print(
+        f"Indexed {stats.n_commands} commands into {stats.n_sessions} sessions "
+        f"in {stats.elapsed_seconds:.2f}s."
+    )
+    return 0
+
+
+def _run_repl() -> int:
+    """Launch the persistent interactive REPL."""
+    config = Config.default()
+
+    if not config.db_path.exists():
+        print(
+            "No index found. Run `whatwasit index` first to build a search index "
+            "from your shell history."
+        )
+        return 1
+
+    def do_search(query: str):
+        results = None
+        if config.use_daemon:
+            results = daemon_search(config, query)
+        if results is None:
+            results = search(config, query)
+        return results
+
+    run_repl(
+        do_search,
+        page_size=config.tui_page_size,
+        low_confidence_threshold=config.low_confidence_threshold,
+    )
+    return 0
+
+
+def _run_query(
+    query: str,
+    top_k: Optional[int],
+    *,
+    force_plain: bool = False,
+) -> int:
+    config = Config.default()
+    if top_k is not None:
+        config.top_k = top_k
+
+    if not config.db_path.exists():
+        print(
+            "No index found. Run `whatwasit index` first to build a search index "
+            "from your shell history."
+        )
+        return 1
+
+    results = None
+    if config.use_daemon:
+        results = daemon_search(config, query, k=top_k)
+    if results is None:
+        results = search(config, query, k=top_k)
+    display_results(results, query, config, force_plain=force_plain)
+    return 0
+
+
+def _run_daemon(action: str) -> int:
+    if action == "start":
+        return start_daemon()
+    if action == "stop":
+        return stop_daemon()
+    return daemon_status()
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    _configure_hf_hub_when_cached()
+
+    if argv is None:
+        argv = sys.argv[1:]
+    argv = list(argv)
+
+    parser = _build_parser()
+
+    if not argv:
+        return _run_repl()
+
+    if argv[0] in ("-h", "--help"):
+        _print_help(parser)
+        return 0
+
+    if argv[0] == "index":
+        args = parser.parse_args(argv)
+        return _run_index(args)
+
+    if argv[0] == "daemon":
+        args = parser.parse_args(argv)
+        return _run_daemon(args.action)
+
+    # Anything else is a natural-language query. Pull out -k/--top-k,
+    # --plain/--headless (which may appear anywhere) and treat the remaining
+    # tokens as the query text.
+    top_k: Optional[int] = None
+    force_plain = False
+    query_tokens: List[str] = []
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+        if token in ("-k", "--top-k"):
+            if i + 1 >= len(argv):
+                print(f"{PROG}: argument {token}: expected one argument", file=sys.stderr)
+                return 2
+            try:
+                top_k = int(argv[i + 1])
+            except ValueError:
+                print(f"{PROG}: argument {token}: invalid int value: {argv[i + 1]!r}", file=sys.stderr)
+                return 2
+            i += 2
+            continue
+        if token in ("--plain", "--headless"):
+            force_plain = True
+            i += 1
+            continue
+        query_tokens.append(token)
+        i += 1
+
+    query = " ".join(query_tokens).strip()
+    if not query:
+        _print_help(parser)
+        return 0
+
+    return _run_query(query, top_k, force_plain=force_plain)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

whatwasit/config.py

@@ -0,0 +1,82 @@
+"""Central configuration for whatwasit.
+
+All tunable values (session window, model name, storage paths, schema version)
+live here so nothing is scattered across the codebase as magic constants.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+from .brand import resolve_data_dir, resolve_db_path
+
+SCHEMA_VERSION = 1
+"""Bumped whenever the on-disk SQLite schema changes. Stored in the ``meta`` table."""
+
+DEFAULT_MODEL_NAME = "sentence-transformers/all-MiniLM-L6-v2"
+DEFAULT_EMBEDDING_DIM = 384
+DEFAULT_LOW_CONFIDENCE_THRESHOLD = 0.40
+DEFAULT_SESSION_WINDOW_SECONDS = 300  # 5 minutes
+DEFAULT_TOP_K = 10
+
+
+def _xdg_data_home() -> Path:
+    env = os.environ.get("XDG_DATA_HOME")
+    if env:
+        return Path(env)
+    return Path.home() / ".local" / "share"
+
+
+@dataclass
+class Config:
+    """Runtime configuration. Construct via :meth:`default` then override fields."""
+
+    # Storage
+    data_dir: Path = field(default_factory=lambda: resolve_data_dir(_xdg_data_home()))
+
+    # Session grouping
+    session_window_seconds: int = DEFAULT_SESSION_WINDOW_SECONDS
+    split_on_cwd_change: bool = True
+
+    # Embedding
+    model_name: str = DEFAULT_MODEL_NAME
+    embedding_dim: int = DEFAULT_EMBEDDING_DIM
+
+    # Search
+    top_k: int = DEFAULT_TOP_K
+    hybrid_search: bool = True
+    low_confidence_threshold: float = DEFAULT_LOW_CONFIDENCE_THRESHOLD
+
+    # Output / TUI
+    output_mode: str = "tui"  # "tui" | "plain"
+    tui_page_size: int = 5
+    use_daemon: bool = True
+
+    # Schema (read-only constant exposed for convenience)
+    schema_version: int = SCHEMA_VERSION
+
+    @classmethod
+    def default(cls) -> "Config":
+        from .config_loader import apply_file_overrides
+
+        return apply_file_overrides(cls())
+
+    @property
+    def db_path(self) -> Path:
+        return resolve_db_path(self.data_dir)
+
+    @property
+    def index_path(self) -> Path:
+        return self.data_dir / "index.usearch"
+
+    def ensure_data_dir(self) -> Path:
+        """Create the data directory if it does not yet exist."""
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        return self.data_dir
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["data_dir"] = str(self.data_dir)
+        return d

whatwasit/config_loader.py

@@ -0,0 +1,78 @@
+"""Load user overrides from ``~/.config/whatwasit/config.toml`` (XDG).
+
+Uses :mod:`tomllib` on Python 3.11+ and :mod:`tomli` on 3.9–3.10.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Mapping
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+if TYPE_CHECKING:
+    from .config import Config
+
+_VALID_OUTPUT_MODES = frozenset({"tui", "plain"})
+
+
+def _xdg_config_home() -> Path:
+    env = os.environ.get("XDG_CONFIG_HOME")
+    if env:
+        return Path(env)
+    return Path.home() / ".config"
+
+
+from .brand import resolve_config_file
+
+
+def config_file_path() -> Path:
+    """Return the XDG path for the whatwasit config file."""
+    return resolve_config_file(_xdg_config_home())
+
+
+def load_config_file() -> Mapping[str, Any]:
+    """Parse the config file if it exists; otherwise return an empty mapping."""
+    path = config_file_path()
+    if not path.is_file():
+        return {}
+    with path.open("rb") as handle:
+        return tomllib.load(handle)
+
+
+def apply_file_overrides(config: "Config") -> "Config":
+    """Apply values from the on-disk config file onto *config*.
+
+    Unknown keys are ignored. Invalid ``output_mode`` values are skipped so
+    defaults remain in effect.
+    """
+    data = load_config_file()
+    if not data:
+        return config
+
+    if "output_mode" in data:
+        mode = str(data["output_mode"]).lower()
+        if mode in _VALID_OUTPUT_MODES:
+            config.output_mode = mode
+
+    if "tui_page_size" in data:
+        try:
+            config.tui_page_size = int(data["tui_page_size"])
+        except (TypeError, ValueError):
+            pass
+
+    if "low_confidence_threshold" in data:
+        try:
+            config.low_confidence_threshold = float(data["low_confidence_threshold"])
+        except (TypeError, ValueError):
+            pass
+
+    if "use_daemon" in data:
+        config.use_daemon = bool(data["use_daemon"])
+
+    return config