clens-cli 1.0.1__py3-none-any.whl

clens/app_config.py

@@ -0,0 +1,29 @@
+from pydantic import BaseModel, Field
+from pathlib import Path
+from clens.paths import CONFIG_FILE
+import json
+
+
+class UserPreferences(BaseModel):
+    default_host: str = "127.0.0.1"
+    default_port: int = 6969
+
+
+class AppConfig(BaseModel):
+    preferences: UserPreferences = Field(default_factory=UserPreferences)
+
+    @classmethod
+    def load_from_file(cls, path: Path = CONFIG_FILE) -> "AppConfig":
+        if not path.exists():
+            return cls()
+        try:
+            with open(path, "r") as f:
+                data = json.load(f)
+            return cls.model_validate(data)
+        except Exception:
+            return cls()
+
+    def save_to_file(self, path: Path = CONFIG_FILE) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            f.write(self.model_dump_json(indent=2))

clens/cli.py

@@ -0,0 +1,389 @@
+import os
+
+os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
+os.environ.setdefault("HF_HUB_VERBOSITY", "error")
+os.environ.setdefault("TRANSFORMERS_VERBOSITY", "error")
+os.environ.setdefault("TOKENIZERS_PARALLELISM", "false")
+
+import argparse
+import sys
+from clens.app_config import AppConfig
+from pathlib import Path
+from typing import override
+import logging
+from clens.paths import CONFIG_FILE, RUNTIME_FILE
+from clens.runtime import RuntimeState
+from importlib.metadata import version
+
+
+class ClensCLIParser(argparse.ArgumentParser):
+    COMMANDS = {
+        "server": {
+            "desc": "Manage the clens server",
+            "arguments": {
+                "start": {
+                    "desc": "Start the clens server",
+                    "arguments": {},
+                    "options": {
+                        "-H, --host": "Host to start the server on",
+                        "-p, --port": "Port to start the server on",
+                    },
+                    "flags": {
+                        "-d, --detach": "Detach server from the current shell session",
+                    },
+                    "req_server": False,
+                },
+                "stop": {
+                    "desc": "Stop the clens server",
+                    "arguments": {},
+                    "options": {},
+                    "flags": {},
+                    "req_server": True,
+                },
+                "status": {
+                    "desc": "Get the status of the clens server",
+                    "arguments": {},
+                    "options": {},
+                    "flags": {},
+                    "req_server": False,
+                },
+            },
+            "options": {},
+            "flags": {},
+            "req_server": False,
+        },
+        "index": {
+            "desc": "Index a given directory of images",
+            "arguments": {
+                "path": {
+                    "desc": "Directory of images to index",
+                    "arguments": {},
+                    "options": {},
+                    "flags": {},
+                },
+            },
+            "options": {},
+            "flags": {},
+            "req_server": True,
+        },
+        "find": {
+            "desc": "Find an image from the indexed directories",
+            "arguments": {
+                "query_term": {
+                    "desc": "Query term to search for",
+                    "arguments": {},
+                    "options": {},
+                    "flags": {},
+                }
+            },
+            "options": {"-c, --count": "Number of images to find (default: 5)"},
+            "flags": {"-p, --plain": "Output plain tab-seperated result"},
+            "req_server": True,
+        },
+        "match": {
+            "desc": "Match an image from the indexed directories",
+            "arguments": {
+                "image_path": {
+                    "desc": "Image to find matches for",
+                    "arguments": {},
+                    "options": {},
+                    "flags": {},
+                }
+            },
+            "options": {"-c, --count": "Numbers of images to find (default: 5)"},
+            "flags": {"-p, --plain": "Output plain tab-seperated result"},
+            "req_server": True,
+        },
+        "version": {
+            "desc": "Print the current clens version",
+            "arguments": {},
+            "options": {},
+            "flags": {},
+            "req_server": False,
+        },
+    }
+
+    def __init__(self, *args, custom_help: str | None = None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.custom_help = custom_help
+
+    @override
+    def format_help(self) -> str:
+        if self.custom_help:
+            return self.custom_help
+        if self.prog != "clens":
+            return super().format_help()
+        command_desc = ""
+        for command in self.COMMANDS.keys():
+            command_desc += f"    {command}: {self.COMMANDS[command]['desc']}\n"
+
+        return f"""
+clens: Local semantic image search tool
+
+Description:
+    Clens is a semantic image search tool that allows users 
+    to index a given directory of images and search through it 
+    using natural language, search for matching images using 
+    another image etc. locally on their device.
+
+Usage:
+    clens [COMMAND] <ARGUMENT> <...options>
+    clens [COMMAND] --help
+
+Commands:
+{command_desc}
+
+Examples:
+    clens server start --port 6969 --detach
+
+    clens index ./Pictures
+
+    clens find "a dog with a hat"
+
+"""
+
+
+logging.basicConfig(
+    level=logging.INFO,
+    format=" [%(levelname)s] %(name)s: %(message)s",
+)
+
+logger = logging.getLogger(__name__)
+runtime_state = RuntimeState().load_runtime()
+
+config = AppConfig.load_from_file(CONFIG_FILE)
+config.save_to_file()
+
+
+def cli():
+
+    clens_parser = ClensCLIParser(prog="clens", add_help=True)
+    commands = clens_parser.add_subparsers(dest="command")
+
+    # Server sub command
+    server_parser = commands.add_parser(
+        "server",
+        custom_help=format_custom_help(
+            "clens server", ClensCLIParser.COMMANDS["server"]
+        ),
+    )
+    server_commands = server_parser.add_subparsers(dest="server_action")
+
+    server_start_parser = server_commands.add_parser(
+        "start",
+        custom_help=format_custom_help(
+            "clens server start",
+            ClensCLIParser.COMMANDS["server"]["arguments"]["start"],
+        ),
+    )
+    server_start_parser.add_argument(
+        "-H",
+        "--host",
+        type=str,
+        default=config.preferences.default_host,
+    )
+    server_start_parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=config.preferences.default_port,
+    )
+    server_start_parser.add_argument(
+        "-d",
+        "--detach",
+        action="store_true",
+    )
+
+    server_commands.add_parser(
+        "stop",
+        custom_help=format_custom_help(
+            "clens server stop",
+            ClensCLIParser.COMMANDS["server"]["arguments"]["stop"],
+        ),
+    )
+    server_commands.add_parser(
+        "status",
+        custom_help=format_custom_help(
+            "clens server status",
+            ClensCLIParser.COMMANDS["server"]["arguments"]["status"],
+        ),
+    )
+
+    # Index sub command
+    index_parser = commands.add_parser(
+        "index",
+        custom_help=format_custom_help("clens index", ClensCLIParser.COMMANDS["index"]),
+    )
+    index_parser.add_argument(
+        "path",
+        nargs="?",
+        default=None,
+    )
+
+    # Find sub command
+    find_parser = commands.add_parser(
+        "find",
+        custom_help=format_custom_help("clens find", ClensCLIParser.COMMANDS["find"]),
+    )
+    find_parser.add_argument(
+        "query_term",
+        nargs="?",
+        default=None,
+    )
+    find_parser.add_argument(
+        "-p",
+        "--plain",
+        action="store_true",
+    )
+    find_parser.add_argument(
+        "-c",
+        "--count",
+        type=int,
+        default=5,
+    )
+
+    # Match sub command
+    match_parser = commands.add_parser(
+        "match",
+        custom_help=format_custom_help("clens match", ClensCLIParser.COMMANDS["match"]),
+    )
+    match_parser.add_argument(
+        "image_path",
+        nargs="?",
+        default=None,
+    )
+    match_parser.add_argument(
+        "-c",
+        "--count",
+        type=int,
+        default=5,
+    )
+    match_parser.add_argument(
+        "-p",
+        "--plain",
+        action="store_true",
+    )
+
+    # Version sub command
+    version_parser = commands.add_parser(
+        "version",
+        custom_help=format_custom_help(
+            "clens version", ClensCLIParser.COMMANDS["version"]
+        ),
+    )
+
+    args = clens_parser.parse_args()
+
+    if args.command is not None and clens_parser.COMMANDS[args.command]["req_server"]:
+        if not RUNTIME_FILE.exists():
+            logger.error("Clens server is not running!")
+            logger.info("Start the server first with: clens server start")
+            sys.exit(1)
+
+    match args.command:
+        case "server":
+            match args.server_action:
+                case "start":
+                    from clens.command_handlers import cmd_start_server
+
+                    cmd_start_server(args.host, args.port, args.detach)
+                case "stop":
+                    from clens.command_handlers import cmd_stop_server
+
+                    cmd_stop_server()
+                case "status":
+                    from clens.command_handlers import cmd_server_status
+
+                    cmd_server_status()
+                case _:
+                    server_parser.print_help()
+                    sys.exit(0)
+
+        case "index":
+            if args.path is None:
+                index_parser.print_help()
+                sys.exit(0)
+            from clens.command_handlers import cmd_index_images
+
+            cmd_index_images(args.path)
+        case "find":
+            if args.query_term is None:
+                find_parser.print_help()
+                sys.exit(0)
+            from clens.command_handlers import cmd_find_images
+
+            cmd_find_images(args.query_term, args.count, args.plain)
+        case "match":
+            if args.image_path is None:
+                match_parser.print_help()
+                sys.exit(0)
+            from clens.command_handlers import cmd_match_image
+
+            cmd_match_image(args.image_path, args.count, args.plain)
+        case "version":
+            print(f"clens v{version('clens-cli')}")
+        case _:
+            clens_parser.print_help()
+            sys.exit(0)
+
+
+def format_custom_help(prog: str, cmd_data: dict) -> str:
+    prog_name = prog if prog.startswith("clens") else f"clens {prog}"
+    desc = cmd_data.get("desc", "")
+    args = cmd_data.get("arguments", {})
+    options = cmd_data.get("options", {})
+    flags = cmd_data.get("flags", {})
+
+    usage_parts = [prog_name, "[-h]"]
+
+    for flag_key in flags.keys():
+        short = flag_key.split(",")[0].strip()
+        usage_parts.append(f"[{short}]")
+
+    for opt_key in options.keys():
+        parts = [p.strip() for p in opt_key.split(",")]
+        short = parts[0]
+        val_name = parts[-1].lstrip("-").upper()
+        usage_parts.append(f"[{short} {val_name}]")
+
+    has_subcommands = len(args) > 1 or any(
+        isinstance(v, dict)
+        and (v.get("options") or v.get("flags") or v.get("arguments"))
+        for v in args.values()
+    )
+
+    if args:
+        if has_subcommands:
+            usage_parts.append(f"{{{','.join(args.keys())}}}")
+        else:
+            usage_parts.extend(f"<{k}>" for k in args.keys())
+
+    sections = [
+        f"\n{prog_name}: {desc}\n",
+        f"Usage:\n    {' '.join(usage_parts)}\n",
+    ]
+
+    if args:
+        header = "Commands:" if has_subcommands else "Arguments:"
+        lines = [f"{header}"]
+        max_w = max(len(k) for k in args.keys())
+        for k, v in args.items():
+            arg_desc = v.get("desc", "") if isinstance(v, dict) else str(v)
+            lines.append(f"    {k:<{max_w}}    {arg_desc}")
+        sections.append("\n".join(lines) + "\n")
+
+    if options:
+        lines = ["Options:"]
+        max_w = max(len(k) for k in options.keys())
+        for k, v in options.items():
+            lines.append(f"    {k:<{max_w}}    {v}")
+        sections.append("\n".join(lines) + "\n")
+
+    all_flags = {**flags, "-h, --help": "Show this help message and exit\n"}
+    lines = ["Flags:"]
+    max_w = max(len(k) for k in all_flags.keys())
+    for k, v in all_flags.items():
+        lines.append(f"    {k:<{max_w}}    {v}")
+    sections.append("\n".join(lines) + "\n")
+
+    return "\n".join(sections)

clens/command_handlers.py

@@ -0,0 +1,322 @@
+import signal
+import requests
+from pathlib import Path
+import logging
+import os
+import subprocess
+import sys
+import time
+from clens.data_schemas import ResponseBody
+from pydantic import ValidationError
+from urllib.parse import urljoin, quote
+from clens.paths import RUNTIME_FILE, LOG_FILE
+from clens.cli import runtime_state
+
+logger = logging.getLogger(__name__)
+
+
+def cmd_start_server(host: str, port: int, detach: bool):
+
+    if RUNTIME_FILE.exists() and runtime_state.pid is not None:
+        logger.warning("Clens server is already running!")
+        return
+
+    os.environ["CLENS_RUNTIME_HOST"] = host
+    os.environ["CLENS_RUNTIME_PORT"] = str(port)
+
+    if not detach:
+        try:
+            logger.info(f"Server running at http://{host}:{port}")
+            import uvicorn
+
+            uvicorn.run(
+                "clens.server:clens_server",
+                host=host,
+                port=port,
+                log_level=logging.INFO,
+                access_log=False,
+            )
+
+        finally:
+            logger.info(f"Server shutting down....")
+            logger.info(f"Server shutdown successfully.")
+    else:
+        logger.info(f"Starting clens server...")
+        LOG_FILE.parent.mkdir(parents=True, exist_ok=True)
+
+        output = open(LOG_FILE, "a")
+
+        start_cmd = [
+            sys.executable,
+            "-m",
+            "uvicorn",
+            "clens.server:clens_server",
+            "--host",
+            host,
+            "--port",
+            str(port),
+            "--log-level",
+            "warning",
+        ]
+
+        process = subprocess.Popen(
+            start_cmd, stdout=output, stderr=output, start_new_session=True
+        )
+        output.close()
+
+        # Check if server is actually up
+        health_url = f"http://{host}:{port}/api/health"
+        server_started = False
+        timeout = 60.0
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            exit_code = process.poll()
+            if exit_code is not None:
+                break
+
+            try:
+                res = requests.get(health_url, timeout=0.2)
+                if res.status_code == 200:
+                    server_started = True
+                    break
+            except requests.RequestException:
+                time.sleep(0.1)
+
+        if server_started:
+            logger.info(
+                f"Server started in background on http://{host}:{port} (PID: {process.pid})"
+            )
+            logger.info(f"Logs available at: {LOG_FILE}")
+        else:
+            # if server didnt respond check if the subprocess is still up
+
+            # if not timeout and kill the process
+            if process.poll() is None:
+                process.terminate()
+                process.wait(timeout=1.0)
+                logger.error("Server start failed! Clens server timed out.")
+
+            logger.error("Failed to start clens server!")
+
+
+def cmd_stop_server():
+    if not RUNTIME_FILE.exists():
+        logger.error("No running clens server found.")
+        return
+    try:
+        os.kill(runtime_state.pid, signal.SIGTERM)
+        logger.info(f"Clens server stopped successfully (PID: {runtime_state.pid})")
+    except ProcessLookupError:
+        logger.info(f"Clens server was already stopped")
+
+
+def cmd_server_status():
+    if RUNTIME_FILE.exists() and runtime_state.pid is not None:
+        try:
+            os.kill(runtime_state.pid, 0)
+            print(
+                f"Clens server is running on http://{runtime_state.active_host}:{runtime_state.active_port} (PID: {runtime_state.pid}) "
+            )
+            return
+        except ProcessLookupError, OSError:
+            pass
+    else:
+        print("Clens server isnt running!! Start the server with: clens server start")
+
+
+def cmd_index_images(path: str) -> None:
+    root_dir = Path(path).absolute()
+    url = f"http://{runtime_state.active_host}:{runtime_state.active_port}/api/index"
+
+    logger.info(f"Indexing the directory: {str(root_dir)}...")
+    logger.info(f"This may take a few moments...")
+
+    try:
+        response = requests.post(
+            url,
+            json={"path": str(root_dir)},
+        )
+        response.raise_for_status()
+
+        data = ResponseBody.model_validate_json(response.text)
+
+        logger.info(f"{data.message}")
+
+    except ValidationError as VE:
+        logger.error(f"API contract violation (Invalid response schema): {VE}")
+    except requests.exceptions.ConnectionError:
+        logger.error(f"Could not connect to {url}")
+    except requests.exceptions.Timeout:
+        logger.error(f"Request to {url} timed out")
+    except requests.exceptions.HTTPError as e:
+        data = ResponseBody.model_validate_json(response.text)
+        logger.error(f"{data.message}")
+    except requests.exceptions.RequestException as e:
+        logger.error(f"Request failed: {e}")
+
+    return None
+
+
+def cmd_find_images(query: str, count: int, plain: bool) -> None:
+
+    if count <= 0:
+        logger.error(f"count must be greater than 0: got -c/--count: {count}")
+        sys.exit(1)
+
+    url = urljoin(
+        f"http://{runtime_state.active_host}:{runtime_state.active_port}/api/find/",
+        quote(query),
+    )
+
+    logger.info(f"Finding results for {query}...")
+    logger.info(f"This may take a few moments...")
+
+    try:
+        response = requests.get(
+            url,
+            params={"count": count},
+        )
+        response.raise_for_status()
+        data = ResponseBody.model_validate_json(response.text)
+
+        logger.info(f"{data.message}")
+        if not plain:
+            display_results_table(data.body)
+            return
+        display_results_plain(data.body)
+
+    except ValidationError as VE:
+        logger.error(f"API contract violation (Invalid response schema): {VE}")
+    except requests.exceptions.ConnectionError:
+        logger.error(f"Connection: Could not connect to {url}")
+    except requests.exceptions.Timeout:
+        logger.error(f"Timeout: Request to {url} timed out")
+    except requests.exceptions.HTTPError:
+        data = ResponseBody.model_validate_json(response.text)
+        logger.error(f"{data.message}")
+        if data.error_type == "ChromaNotFoundError":
+            logger.info(f"Index a directory first! Try: clens index <path>")
+    except requests.exceptions.RequestException as e:
+        logger.error(f"Request failed: {e}")
+    return None
+
+
+def cmd_match_image(img_path: str, count: int, plain: bool) -> None:
+    image_to_match = Path(img_path).absolute()
+    print(count)
+
+    if count <= 0:
+        logger.error(f"count must be greater than 0: got -c/--count: {count}")
+        sys.exit(1)
+
+    url = f"http://{runtime_state.active_host}:{runtime_state.active_port}/api/match"
+
+    logger.info(f"Finding matches for {os.path.basename(img_path)}...")
+    logger.info(f"This may take a few moments...")
+
+    try:
+        response = requests.get(
+            url,
+            params={"image_path": img_path, "count": count},
+        )
+        response.raise_for_status()
+        data = ResponseBody.model_validate_json(response.text)
+
+        logger.info(f"{data.message}")
+        if not plain:
+            display_results_table(data.body)
+            return
+        display_results_plain(data.body)
+
+    except ValidationError as VE:
+        logger.error(f"API contract violation (Invalid response schema): {VE}")
+    except requests.exceptions.ConnectionError:
+        logger.error(f"Connection: Could not connect to {url}")
+    except requests.exceptions.Timeout:
+        logger.error(f"Timeout: Request to {url} timed out")
+    except requests.exceptions.HTTPError:
+        data = ResponseBody.model_validate_json(response.text)
+        if data.error_type == "ChromaNotFoundError":
+            logger.info(f"Index a directory first! Try: clens index <path>")
+    except requests.exceptions.RequestException as e:
+        logger.error(f"Request failed: {e}")
+    return None
+
+
+def display_results_table(response) -> None:
+    results = response.get("message", response)
+    metadatas = results.get("metadatas", [[]])
+    distances = results.get("distances", [[]])
+
+    if not metadatas or not metadatas[0]:
+        print("\n\033[33mNo matching images found.\033[0m\n")
+        return
+
+    items_meta = metadatas[0]
+    items_dist = distances[0] if distances else [0.0] * len(items_meta)
+
+    headers = ["RANK", "SCORE", "FILENAME", "PATH"]
+    rows = []
+
+    for i, (meta, dist) in enumerate(zip(items_meta, items_dist), start=1):
+        path_str = meta.get("path", "")
+        filename = Path(path_str).name or "Unknown"
+
+        # In ChromaDB cosine space: distance = 1 - cosine_similarity
+        # So: similarity = (1 - distance) * 100%
+        similarity = max(0.0, min(1.0, 1.0 - dist)) * 100
+
+        rows.append([f"#{i}", f"{similarity:.1f}%", filename, path_str])
+
+    # 1. Compute dynamic column widths so nothing wraps awkwardly
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for idx, col in enumerate(row):
+            widths[idx] = max(widths[idx], len(col))
+
+    # 2. Build dividers and format strings
+    divider = "─" * (sum(widths) + 2 * (len(widths) - 1))
+
+    # 3. Print table with clean ANSI styling (hardcoded bright white base)
+    print()
+    header_str = "  ".join(f"{h:<{widths[i]}}" for i, h in enumerate(headers))
+    print(f"\033[1;97m{header_str}\033[0m")
+    print(f"\033[97m{divider}\033[0m")
+
+    for rank, score, fname, pth in rows:
+        # Green score accent, clickable OSC 8 hyperlink on path, white base colors
+        # get file path with file:// prefixed
+        uri = Path(pth).resolve().as_uri()
+        # turn that into a hyprlink with OSC 8 esc sequence
+        linked_pth = f"\033]8;;{uri}\033\\{pth}\033]8;;\033\\"
+        print(
+            f"\033[97m{rank:<{widths[0]}}\033[0m  "
+            f"\033[1;32m{score:<{widths[1]}}\033[0m  "
+            f"\033[1;97m{fname:<{widths[2]}}\033[0m  "
+            f"\033[97m{linked_pth}\033[0m"
+        )
+
+    print(f"\033[97m{divider}\033[0m")
+    print(f"\033[97mFound {len(rows)} matching results\033[0m\n")
+
+
+def display_results_plain(response) -> None:
+    results = response.get("message", response)
+    metadatas = results.get("metadatas", [[]])
+    distances = results.get("distances", [[]])
+
+    if not metadatas or not metadatas[0]:
+        return
+
+    items_meta = metadatas[0]
+    items_dist = distances[0] if distances else [0.0] * len(items_meta)
+
+    headers = ["RANK", "SCORE", "FILENAME", "PATH"]
+    print("\t".join(headers))
+
+    for i, (meta, dist) in enumerate(zip(items_meta, items_dist), start=1):
+        path_str = meta.get("path", "")
+        filename = Path(path_str).name or "Unknown"
+        similarity = max(0.0, min(1.0, 1.0 - dist)) * 100
+        print(f"{i}\t{similarity:.1f}%\t{filename}\t{path_str}")

clens/data_schemas.py

@@ -0,0 +1,29 @@
+from pydantic import BaseModel
+from pathlib import Path
+from typing import Generic, TypeVar, TypedDict
+from numpy.typing import NDArray
+import numpy as np
+
+T = TypeVar("T")
+
+
+class IndexDirData(BaseModel):
+    path: str
+
+
+class ResponseBody(BaseModel, Generic[T]):
+    message: str
+    body: T | None = None
+    error_type: str | None = None
+
+
+class ImageData(TypedDict):
+    id: str
+    file_type: str
+    path: Path
+    embedding: NDArray[np.float32]
+
+
+class Candidate(TypedDict):
+    id: str
+    path: Path

clens/data_store.py

@@ -0,0 +1,56 @@
+from typing import TYPE_CHECKING
+from clens.paths import STORE_DIR
+from clens.data_schemas import Candidate
+
+if TYPE_CHECKING:
+    from chromadb.api import ClientAPI
+    from chromadb.api.types import QueryResult
+    from clens.embedder import ImageData
+
+
+_chroma_client = None
+
+
+def get_chroma_client() -> ClientAPI:
+    from chromadb import PersistentClient
+
+    global _chroma_client
+    if _chroma_client is None:
+        _chroma_client = PersistentClient(path=STORE_DIR)
+    return _chroma_client
+
+
+def filter_preexisting_images(
+    client: ClientAPI, candidates: list[Candidate]
+) -> list[Candidate]:
+    image_collection = client.get_or_create_collection(
+        "image_data", configuration={"hnsw": {"space": "cosine"}}
+    )
+
+    existing_ids: set[str] = set(
+        image_collection.get(ids=[entry["id"] for entry in candidates])["ids"]
+    )
+
+    if len(existing_ids) == 0:
+        return candidates
+
+    return [entry for entry in candidates if entry["id"] not in existing_ids]
+
+
+def store_image_data(client: ClientAPI, image_data: list[ImageData]) -> None:
+    image_collection = client.get_or_create_collection(
+        "image_data", configuration={"hnsw": {"space": "cosine"}}
+    )
+    image_collection.add(
+        ids=[str(data["id"]) for data in image_data],
+        embeddings=[data["embedding"] for data in image_data],
+        metadatas=[
+            {"file_type": str(data["file_type"]), "path": str(data["path"])}
+            for data in image_data
+        ],
+    )
+
+
+def retrieve_images(embedding, client: ClientAPI, result_count: int) -> QueryResult:
+    image_collection = client.get_collection("image_data")
+    return image_collection.query(query_embeddings=embedding, n_results=result_count)

clens/dir_crawler.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+image_types = ["jpg", "png"]
+
+
+def find_images(root_dir: str | Path) -> list[Path]:
+    root = Path(root_dir)
+    if root.is_file():
+        raise NotADirectoryError(f"Path must be a directory and not a file: {root}")
+    if not root.exists():
+        raise FileNotFoundError(f"No such directory found: {root}")
+
+    file_paths: list[Path] = []
+    for image_type in image_types:
+        for file_path in root.rglob(f"*.{image_type}"):
+            file_paths.append(file_path.absolute())
+
+    return file_paths

clens/embedder.py

@@ -0,0 +1,74 @@
+from pathlib import Path
+from filetype import guess_mime
+import uuid
+import hashlib
+from numpy.typing import NDArray
+import numpy as np
+from clens.data_schemas import ImageData, Candidate
+
+CLIP_MODEL = "clip-ViT-B-32"
+_model = None
+
+
+def get_model():
+    from sentence_transformers import SentenceTransformer
+
+    global _model
+    if _model is None:
+        try:
+            _model = SentenceTransformer(CLIP_MODEL, local_files_only=True)
+        except Exception:
+            _model = SentenceTransformer(CLIP_MODEL)
+    return _model
+
+
+def embed_image(image_data) -> NDArray[np.float32]:
+
+    model = get_model()
+    return model.encode(image_data, normalize_embeddings=True)
+
+
+def generate_image_hash(image_path: Path) -> str:
+    sha256 = hashlib.sha256()
+    with open(image_path, "rb") as img:
+        while chunk := img.read(65536):
+            sha256.update(chunk)
+    return sha256.hexdigest()
+
+
+def embed_images(files: list[Path]) -> list[ImageData]:
+    from clens.data_store import filter_preexisting_images, get_chroma_client
+
+    candidates: list[Candidate] = []
+    for file in files:
+        image_hash = generate_image_hash(file)
+        candidates.append({"id": image_hash, "path": file})
+
+    chroma_client = get_chroma_client()
+
+    new_images = filter_preexisting_images(chroma_client, candidates)
+
+    if len(new_images) == 0:
+        return []
+
+    embedded: list[ImageData] = []
+    for candidate in new_images:
+        from PIL import Image
+
+        pil_image = Image.open(candidate["path"])
+        embedding = embed_image(pil_image)
+        embedded.append(
+            {
+                "id": candidate["id"],
+                "file_type": guess_mime(candidate["path"]),
+                "path": candidate["path"],
+                "embedding": embedding,
+            }
+        )
+    return embedded
+
+
+def embed_text(query_text: str) -> NDArray[np.float32]:
+    model = get_model()
+
+    return model.encode(query_text, normalize_embeddings=True)

clens/indexer.py

@@ -0,0 +1,20 @@
+from clens.dir_crawler import find_images
+from clens.embedder import embed_images
+from clens.data_store import get_chroma_client, store_image_data
+
+
+def index_images(root_dir: str) -> None:
+    # get images recursively form the provided dir
+    file_paths = find_images(root_dir)
+
+    # generate embeddings from images
+    image_data = embed_images(file_paths)
+
+    if len(image_data) == 0:
+        return
+
+    # get the shared chroma client
+    chroma_client = get_chroma_client()
+
+    # store the embeddings in chroma db
+    store_image_data(chroma_client, image_data)

clens/paths.py

@@ -0,0 +1,22 @@
+import os
+from pathlib import Path
+
+APP = "clens"
+
+
+def _xdg(env: str, fallback: Path) -> Path:
+    base = os.environ.get(env)
+    return Path(base) if base else fallback
+
+
+CONFIG_DIR = _xdg("XDG_CONFIG_HOME", Path.home() / ".config") / APP
+DATA_DIR = _xdg("XDG_DATA_HOME", Path.home() / ".local/share") / APP
+STATE_DIR = _xdg("XDG_STATE_HOME", Path.home() / ".local/state") / APP
+
+_runtime = os.environ.get("XDG_RUNTIME_DIR")
+RUNTIME_DIR = (Path(_runtime) if _runtime else STATE_DIR) / APP
+
+CONFIG_FILE = CONFIG_DIR / "config.json"
+STORE_DIR = DATA_DIR / "chroma"
+LOG_FILE = STATE_DIR / "logs" / "clens.log"
+RUNTIME_FILE = RUNTIME_DIR / "runtime.json"

clens/runtime.py

@@ -0,0 +1,31 @@
+from pydantic import BaseModel, Field
+from pathlib import Path
+from clens.paths import RUNTIME_FILE
+import json
+import os
+
+
+class RuntimeState(BaseModel):
+    active_host: str | None = None
+    active_port: int | None = None
+    pid: int | None = None
+
+    @classmethod
+    def load_runtime(cls, path: Path = RUNTIME_FILE) -> "RuntimeState":
+        if not path.exists():
+            return cls()
+        try:
+            with open(path, "r") as f:
+                runtime_data = json.load(f)
+            return cls.model_validate(runtime_data)
+        except:
+            return cls()
+
+    def save_runtime(self, path: Path = RUNTIME_FILE) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w") as f:
+            f.write(self.model_dump_json(indent=2))
+
+    def clear_runtime(self, path: Path = RUNTIME_FILE) -> None:
+        if path.exists():
+            os.remove(path)

clens/search.py

@@ -0,0 +1,25 @@
+from pathlib import Path
+from PIL import Image
+
+
+def find_images(query_text: str, count: int):
+    from clens.embedder import embed_text
+    from clens.data_store import get_chroma_client, retrieve_images
+
+    query_text_embd = embed_text(query_text)
+    chroma_client = get_chroma_client()
+
+    return retrieve_images(query_text_embd, chroma_client, count)
+
+
+def match_images(img_path: Path, count: int):
+    from clens.embedder import embed_image
+    from clens.data_store import get_chroma_client, retrieve_images
+    from PIL import Image
+
+    image_data = Image.open(img_path)
+    image_embedding = embed_image(image_data)
+
+    chroma_client = get_chroma_client()
+
+    return retrieve_images(image_embedding, chroma_client, count)

clens/server.py

@@ -0,0 +1,100 @@
+from fastapi import FastAPI, Response, status
+from contextlib import asynccontextmanager
+from clens.data_schemas import IndexDirData, ResponseBody
+import logging
+from clens.embedder import get_model
+from clens.data_store import get_chroma_client
+import asyncio
+from clens.runtime import RuntimeState
+from chromadb.errors import NotFoundError as ChromaNotFoundError
+import os
+
+runtime_state = RuntimeState().load_runtime()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    runtime_state.active_host = os.environ.get("CLENS_RUNTIME_HOST")
+    runtime_state.active_port = int(os.environ.get("CLENS_RUNTIME_PORT"))
+    runtime_state.pid = os.getpid()
+    runtime_state.save_runtime()
+    await asyncio.to_thread(get_model)
+    get_chroma_client()
+    yield
+    runtime_state.clear_runtime()
+
+
+clens_server = FastAPI(lifespan=lifespan)
+
+logging.basicConfig(
+    level=logging.INFO, format=" [%(levelname)s] %(name)s: %(message)s", force=True
+)
+logger = logging.getLogger(__name__)
+
+
+@clens_server.get("/api/health", response_model=ResponseBody)
+def health():
+    return ResponseBody(message="Status OK")
+
+
+@clens_server.post("/api/index", response_model=ResponseBody)
+def index_dir(req: IndexDirData, response: Response):
+    from clens.indexer import index_images
+
+    try:
+        index_images(req.path)
+        return ResponseBody(message=f"The directory {req.path} has been indexed")
+    except NotADirectoryError as NAD:
+        response.status_code = status.HTTP_400_BAD_REQUEST
+        return ResponseBody(message=f"{NAD}", error_type="NotADirectoryError")
+    except FileNotFoundError as FNF:
+        response.status_code = status.HTTP_400_BAD_REQUEST
+        return ResponseBody(message=f"{FNF}", error_type="FileNotFoundError")
+    except Exception as E:
+        response.status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        return ResponseBody(
+            message=f"Something went wrong", error_type="InternalServerError"
+        )
+
+
+@clens_server.get("/api/find/{query_term}", response_model=ResponseBody)
+def find_image(query_term: str, response: Response, count: int = 5):
+    from clens.search import find_images
+
+    try:
+        result = find_images(query_term, count)
+        return ResponseBody(message=f"Found results for {query_term}", body=result)
+    except ChromaNotFoundError:
+        response.status_code = status.HTTP_400_BAD_REQUEST
+        return ResponseBody(
+            message="Seems like you have no indexed directories",
+            error_type="ChromaNotFoundError",
+        )
+    except Exception:
+        response.status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        return ResponseBody(
+            message=f"Something went wrong", error_type="InternalServerError"
+        )
+
+
+@clens_server.get("/api/match", response_model=ResponseBody)
+def match_image(image_path: str, response: Response, count: int = 5):
+    from clens.search import match_images
+    from pathlib import Path
+
+    try:
+        result = match_images(Path(image_path).absolute(), count)
+        return ResponseBody(
+            message=f"Found matches for {os.path.basename(image_path)}", body=result
+        )
+    except ChromaNotFoundError:
+        response.status_code = status.HTTP_400_BAD_REQUEST
+        return ResponseBody(
+            message="Seems like you have no indexed directories",
+            error_type="ChromaNotFoundError",
+        )
+    except Exception:
+        response.status_code = status.HTTP_500_INTERNAL_SERVER_ERROR
+        return ResponseBody(
+            message=f"Something went wrong", error_type="InternalServerError"
+        )

clens_cli-1.0.1.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.3
+Name: clens-cli
+Version: 1.0.1
+Summary: Local semantic image search tool
+Keywords: cli,image search,semantic search,computer vision
+Author: k4rkie
+Author-email: k4rkie <karkeekrish07@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 k4rkie
+         
+         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.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Dist: chromadb>=1.5.9
+Requires-Dist: fastapi[standard]>=0.142.2
+Requires-Dist: filetype>=1.2.0
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: sentence-transformers>=6.1.0
+Requires-Dist: torch>=2.14.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+<h1 align="center">clens</h1>
+
+Clens is a semantic image search tool that allows users 
+to index a given directory of images and search through it 
+using natural language, search for matching images using 
+another image etc. locally on their device.
+
+## Installation
+
+Clens currently requires Python 3.14 or newer. The recommended installation
+uses the CPU-only PyTorch packages, so it does not download NVIDIA/CUDA
+libraries on CPU machines.
+
+### Install with uv
+
+Install the published package as an isolated command-line tool. The extra
+PyTorch index is needed because CPU-only PyTorch wheels are published there:
+
+```bash
+uv tool install \
+  --index https://download.pytorch.org/whl/cpu \
+  --default-index https://pypi.org/simple \
+  clens-cli
+```
+
+### Install with pipx
+
+`pipx` also installs command-line applications into an isolated environment:
+
+```bash
+pipx install \
+  --pip-args="--index-url https://download.pytorch.org/whl/cpu --extra-index-url https://pypi.org/simple" \
+  clens-cli
+```
+
+After installation, verify the command:
+
+```bash
+clens version
+clens --help
+```
+
+The first indexing or search operation downloads the local CLIP model so may take a few minutes. It is
+cached locally and reused for later runs.
+
+## Usage
+
+Clens uses a local background server (FastAPI + ChromaDB + CLIP) to keep embeddings loaded in memory for faster indexing and search.
+
+### 1. Server
+
+Before indexing or searching, make sure the clens server is running.
+
+Start the server:
+```bash
+# Start in current shell
+clens server start
+
+# Or detach to run in background
+clens server start --detach
+```
+
+> Defaults to `127.0.0.1:6969`. You can pass custom host/port:
+> ```bash
+> clens server start --port 6969 --detach
+> ```
+
+Check status or stop:
+```bash
+# Check if server is running
+clens server status
+
+# Stop running server
+clens server stop
+```
+
+---
+
+### 2. Index a Directory
+
+Recursively indexes `.png` and `.jpg` images from a directory and stores embeddings in local ChromaDB:
+
+```bash
+clens index ./Pictures
+```
+*Indexing may take a few moments depending on the number of images in the directory and your hardware.*
+
+---
+
+### 3. Find Images with Text (`find`)
+
+Search indexed images with natural language:
+
+```bash
+clens find "a dog with a hat"
+```
+
+Change number of results with `-c` / `--count` (default is 5):
+```bash
+clens find "a dog with a hat" -c 10
+```
+
+---
+
+### 4. Find Matching Images (`match`)
+
+Pass an image to find visually and semantically matching images in your indexed directories:
+
+```bash
+clens match ./sample_images/dog.png
+```
+
+Specify number of matches:
+```bash
+clens match ./sample_images/dog.png -c 3
+```
+
+---
+
+### 5. Plain Output for Scripts & Piping (`-p`)
+
+By default, clens renders an ANSI table with match percentage and clickable file paths. Use `-p` / `--plain` to get raw tab-separated output (`RANK`, `SCORE`, `FILENAME`, `PATH`):
+
+```bash
+# Tab-separated output
+clens find "sunset" -p
+
+# Example: pipe top result to xdg-open
+clens find "cat sleeping" -c 1 -p | awk 'NR==2 {print $4}' | xargs xdg-open
+```
+
+---
+
+### Configuration
+
+Clens automatically generates a config file at `~/.config/clens/config.json` (or `$XDG_CONFIG_HOME/clens/config.json`):
+
+```json
+{
+  "preferences": {
+    "default_host": "127.0.0.1",
+    "default_port": 6969
+  }
+}
+```
+
+Currently available options:
+* `preferences.default_host`: Default host the server binds to and client commands connect to (default: `"127.0.0.1"`).
+* `preferences.default_port`: Default port used by the server and CLI (default: `6969`).
+
+---
+
+## Commands 
+
+```
+clens server start [-H HOST] [-p PORT] [-d]   Start clens server (-d to detach)
+clens server status                            Get server status
+clens server stop                              Stop running server
+clens index <path>                             Index a directory of images
+clens find <query_term> [-c COUNT] [-p]        Find images by text description
+clens match <image_path> [-c COUNT] [-p]       Find images matching an existing image
+clens version                                  Print current version
+```
+
+For indepth info about the program
+```bash
+clens -h/-help
+```

clens_cli-1.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+clens/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clens/app_config.py,sha256=anvL6RbEIi0twmBSdi5hbXh7uzOHkEA_iqdBpESxR-c,847
+clens/cli.py,sha256=9Q2g6HcOXMkqdT2uavxSUvBg7d62jSlx5mPaC2rY7Go,11623
+clens/command_handlers.py,sha256=qR6OaA9erDmNO7N8QhKj5N7fRam4WPCEbEFxZ4mWElE,10804
+clens/data_schemas.py,sha256=6_afD63bt8DWp3jdTeVntnsPjxeyamsKD97SQKtK7_4,510
+clens/data_store.py,sha256=3_2RQwgbU3Qr7KMycv1oTNMu2CGKCv5j_1YcBtvozQE,1725
+clens/dir_crawler.py,sha256=mo7PlZwnLUbO5buoCfey-7RJFLwGEnZadhVvtFcg-RM,537
+clens/embedder.py,sha256=0TBTuIO_MD_MvducK3eYqWjDT-clXuMcSCWUfYgbndw,1972
+clens/indexer.py,sha256=VHPYjooMnAUBh7CQ8x3oQwe9pNikO3ofeLCnlWb4kww,571
+clens/paths.py,sha256=g1WCUBBkD6Q3FcUzvSA2SM3EpamHF8lnq1umx0mkzg0,653
+clens/runtime.py,sha256=xf7u54O45wKygHvJpSDqpD2MY-I21brh-ey3dPvC8bc,911
+clens/search.py,sha256=EzC5WmlQf6Zgb6tAXT7Bjg7QzJkXpcudsw5ZgG16730,736
+clens/server.py,sha256=dxw0lFkt5b1ul-grYqNp-bpEruwT8h7llpLQ_3-OWRs,3588
+clens_cli-1.0.1.dist-info/WHEEL,sha256=mru_b36sH6joUMnwf7IlFCun3RoDjrNg9RcfBmEcqsE,81
+clens_cli-1.0.1.dist-info/entry_points.txt,sha256=06jhwVe7CveD15J4Sezfw6-HQHEGH-CNvD6uRUaXNwY,41
+clens_cli-1.0.1.dist-info/METADATA,sha256=7DBy2qEwKhHAkdN6YbLDgAZFc_EIvWt2BThgeoPJXfQ,6098
+clens_cli-1.0.1.dist-info/RECORD,,

clens_cli-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.11
+Root-Is-Purelib: true
+Tag: py3-none-any

clens_cli-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+clens = clens.cli:cli
+