feat: add semantic icon search with VLM descriptions and embeddings

Add embedding-based search so users can find Lucide icons by natural
language queries ("payment", "hard work", "owl") instead of exact name
matching.

Architecture:
- Gemini 2.5 Flash Lite generates rich text descriptions from rendered
  icon PNGs + Lucide metadata (tags, categories) at build time
- nomic-embed-text-v1.5-Q computes embeddings with asymmetric
  search_query/search_document prefixes
- Descriptions saved as JSONL (durable source of truth), embeddings
  stored in a separate SQLite search DB
- Search DB auto-downloaded on first use, cached locally
- Lucide repo auto-cloned for metadata during description generation

New modules:
- search.py: public API (search_icons, search_available, SearchResult)
- build_search.py: VLM + embedding build pipeline with JSONL intermediate
- build_clusters.py: HDBSCAN clustering + Gemini Flash theme naming
- cli.py: unified `lucide` CLI with subcommands (db, describe,
  build-search, search, cluster, version)

Main DB now includes relational metadata:
- icon_tags (12,619 rows), icon_categories (3,309), icon_aliases (248)
- All indexed for fast lookup

CLI search with inline icon rendering via Kitty graphics protocol
(Ghostty, kitty, WezTerm) with white background for visibility.

Optional extra: pip install python-lucide[search]

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: mmacpherson

.github/workflows/update-lucide.yml

@@ -129,6 +129,24 @@ jobs:
           exit 1
         fi
 
+    - name: Generate search data
+      if: steps.version-check.outputs.needs-update == 'true' && steps.check-pr.outputs.pr-exists == 'false'
+      env:
+        GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+      run: |
+        echo "🔍 Generating semantic search data for new icons..."
+        make search-data
+        SEARCH_DB=src/lucide/data/lucide-search.db
+        if [ -f "$SEARCH_DB" ]; then
+          DESC_COUNT=$(sqlite3 "$SEARCH_DB" "SELECT COUNT(*) FROM icon_descriptions;")
+          EMB_COUNT=$(sqlite3 "$SEARCH_DB" "SELECT COUNT(*) FROM icon_embeddings;")
+          ICON_COUNT=$(sqlite3 src/lucide/data/lucide-icons.db "SELECT COUNT(*) FROM icons;")
+          echo "✅ Search data: $DESC_COUNT descriptions, $EMB_COUNT embeddings (of $ICON_COUNT icons)"
+          echo "search-db-size=$(du -h "$SEARCH_DB" | cut -f1)" >> $GITHUB_OUTPUT
+        else
+          echo "⚠️ Search database not created (GEMINI_API_KEY may not be set)"
+        fi
+
     - name: Run tests
       if: steps.version-check.outputs.needs-update == 'true' && steps.check-pr.outputs.pr-exists == 'false'
       run: |
@@ -143,6 +161,10 @@ jobs:
         git config --local user.name "github-actions[bot]"
 
         git add src/lucide/config.py src/lucide/data/lucide-icons.db pyproject.toml .github/lucide-version.json
+        # Include search DB if it was generated
+        if [ -f src/lucide/data/lucide-search.db ]; then
+          git add src/lucide/data/lucide-search.db
+        fi
         git commit -m "feat: Update Lucide icons to v${{ steps.version-check.outputs.latest-version }}
 
         Bumps package version to ${{ steps.version-bump.outputs.new-pkg-version }}.

.gitignore

@@ -175,3 +175,8 @@ cython_debug/
 
 # Claude Code local settings
 .claude/
+
+# Beads / Dolt files (added by bd init)
+.dolt/
+*.db
+.beads-credential-key

Makefile

@@ -4,18 +4,20 @@
 UV_CMD := uv
 PRE_COMMIT_CMD := $(UV_CMD) run pre-commit
 PYTEST_CMD := $(UV_CMD) run pytest
-LUCIDE_DB_CMD := $(UV_CMD) run lucide-db
+LUCIDE_CMD := $(UV_CMD) run lucide
 
 # Get default Lucide tag from the package's config.py
 PYTHON_CMD_FOR_TAG := $(UV_CMD) run python -c "from lucide.config import DEFAULT_LUCIDE_TAG; print(DEFAULT_LUCIDE_TAG)"
 DEFAULT_LUCIDE_TAG := $(shell $(PYTHON_CMD_FOR_TAG))
 # Allow overriding the tag via make argument, e.g., make db TAG=0.500.0
 TAG ?= $(DEFAULT_LUCIDE_TAG)
 DB_OUTPUT_PATH := src/lucide/data/lucide-icons.db
+SEARCH_DB_OUTPUT_PATH := src/lucide/data/lucide-search.db
+DESCRIPTIONS_JSONL := src/lucide/data/gemini-icon-descriptions.jsonl
 VENV_DIR := .venv
 
 # Phony targets prevent conflicts with files of the same name.
-.PHONY: help default env lucide-db test install-hooks run-hooks-all-files check-lucide-version clean nuke
+.PHONY: help default env lucide-db describe build-search search-data lucide-db-full test install-hooks run-hooks-all-files check-lucide-version clean nuke
 
 # Default target
 default: help
@@ -31,6 +33,10 @@ help:
 	@echo "  lucide-db              (Re)builds the Lucide icon database into $(DB_OUTPUT_PATH)."
 	@echo "                         Uses TAG=$(TAG). Default TAG is read from src/lucide/config.py (currently $(DEFAULT_LUCIDE_TAG))."
 	@echo "                         Example: make lucide-db TAG=0.520.0"
+	@echo "  describe               Generate icon descriptions via VLM (requires GEMINI_API_KEY)."
+	@echo "  build-search           Build search SQLite DB from descriptions JSONL."
+	@echo "  search-data            Run describe + build-search."
+	@echo "  lucide-db-full         Build icons database + search data."
 	@echo "  test                   Run tests using pytest."
 	@echo "  install-hooks          Install pre-commit hooks."
 	@echo "  update-hooks           Update pre-commit hooks to latest version."
@@ -52,9 +58,21 @@ $(VENV_DIR)/pyvenv.cfg:
 lucide-db:
 	@echo "Building Lucide icon database with tag $(TAG) into $(DB_OUTPUT_PATH)..."
 	@mkdir -p src/lucide/data # Ensure data directory exists
-	$(LUCIDE_DB_CMD) -o $(DB_OUTPUT_PATH) -t $(TAG) -v
+	$(LUCIDE_CMD) db -o $(DB_OUTPUT_PATH) -t $(TAG) -v
 	@echo "Database build complete: $(DB_OUTPUT_PATH)"
 
+describe:
+	@echo "Generating icon descriptions..."
+	$(LUCIDE_CMD) describe --icons-db $(DB_OUTPUT_PATH) -o $(DESCRIPTIONS_JSONL) -v
+
+build-search:
+	@echo "Building search DB from descriptions..."
+	$(LUCIDE_CMD) build-search --descriptions-file $(DESCRIPTIONS_JSONL) -o $(SEARCH_DB_OUTPUT_PATH) -v
+
+search-data: describe build-search
+
+lucide-db-full: lucide-db search-data
+
 test:
 	@echo "Running tests..."
 	$(PYTEST_CMD)

pyproject.toml

@@ -4,14 +4,19 @@ requires = ["uv_build>=0.8.3,<0.12.0"]
 
 [dependency-groups]
 dev = [
+  "cairosvg>=2.7.0",
+  "fastembed>=0.4.0",
+  "hdbscan>=0.8.0",
   "mypy-extensions>=1.0.0",
   "mypy>=1.0.0",
+  "plotly>=5.0.0",
   "pre-commit>=3.0.0",
   "pytest-cov>=4.0.0",
   "pytest>=7.0.0",
   "ruff>=0.1.0",
   "types-setuptools>=80.9.0.20250529",
-  "typing-extensions>=4.1.0"
+  "typing-extensions>=4.1.0",
+  "umap-learn>=0.5.0"
 ]
 
 [project]
@@ -37,9 +42,13 @@ readme = "README.md"
 requires-python = ">=3.10"
 version = "0.2.24"
 
+[project.optional-dependencies]
+search = ["fastembed>=0.4.0"]
+
 [project.scripts]
 check-lucide-version = "lucide.dev_utils:print_version_status"
-lucide-db = "lucide.cli:main"
+lucide = "lucide.cli:main"
+lucide-db = "lucide.cli:main_legacy_db"
 
 [project.urls]
 "Bug Tracker" = "https://github.com/mmacpherson/python-lucide/issues"
@@ -126,7 +135,8 @@ section-order = [
 
 [tool.ruff.lint.per-file-ignores]
 "**/__init__.py" = ["F401"]
-"tests/**/*.py" = ["D", "SLF001"]
+"scripts/**/*.py" = ["D", "SLF001", "PLR2004", "PLR0915", "PLC0415", "ERA001", "E741", "C408"]
+"tests/**/*.py" = ["D", "SLF001", "PLR2004", "ARG005"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"

src/lucide/__init__.py

@@ -8,11 +8,21 @@
 
 from .core import create_placeholder_svg, get_icon_list, lucide_icon
 from .db import get_db_connection, get_default_db_path
+from .search import (
+    SearchNotAvailableError,
+    SearchResult,
+    search_available,
+    search_icons,
+)
 
 __all__ = [
+    "SearchNotAvailableError",
+    "SearchResult",
     "create_placeholder_svg",
     "get_db_connection",
     "get_default_db_path",
     "get_icon_list",
     "lucide_icon",
+    "search_available",
+    "search_icons",
 ]