clens-cli 1.0.1__tar.gz

clens_cli-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+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.

clens_cli-1.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,168 @@
+<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/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "clens-cli"
+version = "1.0.1"
+description = "Local semantic image search tool"
+readme = "README.md"
+keywords = [
+    "cli",
+    "image search",
+    "semantic search",
+    "computer vision",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+]
+requires-python = ">=3.14"
+dependencies = [
+    "chromadb>=1.5.9",
+    "fastapi[standard]>=0.142.2",
+    "filetype>=1.2.0",
+    "pillow>=12.3.0",
+    "sentence-transformers>=6.1.0",
+    "torch>=2.14.0",
+]
+
+[[project.authors]]
+name = "k4rkie"
+email = "karkeekrish07@gmail.com"
+
+[project.license]
+file = "LICENSE"
+
+[project.project-urls]
+Repository = "https://github.com/k4rkie/clens"
+
+[project.scripts]
+clens = "clens.cli:cli"
+
+[build-system]
+requires = ["uv_build>=0.12.11,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "clens"
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources.torch]
+index = "pytorch-cpu"
+
+[tool.pyright]
+exclude = [
+    ".venv",
+    "venv",
+    ".chroma_store",
+    "__pycache__",
+]
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]

clens_cli-1.0.1/pyproject.toml.orig

@@ -0,0 +1,58 @@
+[project]
+name = "clens-cli"
+version = "1.0.1"
+description = "Local semantic image search tool"
+readme = "README.md"
+authors = [
+    { name = "k4rkie", email = "karkeekrish07@gmail.com" }
+]
+license = { file = "LICENSE" }
+keywords = ["cli", "image search", "semantic search", "computer vision"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Graphics",
+]
+project-urls = { Repository = "https://github.com/k4rkie/clens" }
+requires-python = ">=3.14"
+dependencies = [
+    "chromadb>=1.5.9",
+    "fastapi[standard]>=0.142.2",
+    "filetype>=1.2.0",
+    "pillow>=12.3.0",
+    "sentence-transformers>=6.1.0",
+    "torch>=2.14.0",
+]
+
+[project.scripts]
+clens = "clens.cli:cli"
+
+[build-system]
+requires = ["uv_build>=0.12.11,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "clens"
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = { index = "pytorch-cpu" }
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[tool.pyright]
+exclude = [
+    ".venv",
+    "venv",
+    ".chroma_store",
+    "__pycache__",
+]

clens_cli-1.0.1/src/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))