python-lucide 0.3.0__tar.gz → 0.5.0__tar.gz

{python_lucide-0.3.0 → python_lucide-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-lucide
-Version: 0.3.0
+Version: 0.5.0
 Summary: A Python package for working with Lucide icons
 Keywords: lucide,icons,svg,sqlite
 Author: Mike Macpherson
@@ -15,6 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: cairosvg>=2.7.0 ; extra == 'search'
 Requires-Dist: fastembed>=0.4.0 ; extra == 'search'
 Requires-Python: >=3.10
 Project-URL: Bug Tracker, https://github.com/mmacpherson/python-lucide/issues
@@ -43,6 +44,7 @@ in your Python projects, with no javascript in sight.
 
 ## Features
 - 🎨 **Access 1600+ Lucide icons** directly from Python
+- 🔍 **Semantic search** - find icons by meaning, in the terminal or [in the browser](https://mmacpherson.github.io/python-lucide/)
 - 🛠 **Customize icons** with classes, sizes, colors, and other SVG attributes
 - 🚀 **Framework-friendly** with examples for FastHTML, Flask, Django, and more
 - 📦 **Lightweight** with minimal dependencies
@@ -83,6 +85,60 @@ lucide_icon("user", fill="currentColor")  # Inherit color from CSS
 lucide_icon("user", stroke="#ff6b6b")     # Hex colors work too
 ```
 
+## Semantic Search
+
+Find icons by describing what you mean, not what they're called — in English
+or [50+ languages](https://mmacpherson.github.io/python-lucide/):
+
+<p align="center">
+  <a href="https://mmacpherson.github.io/python-lucide/">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-english.png" width="49%" alt="Searching &quot;celebrate a big achievement&quot; returns trophy, award, medal, party-popper">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-multilingual.png" width="49%" alt="Searching in Japanese with the multilingual model returns key, user-key, lock icons">
+  </a>
+</p>
+
+```bash
+# One-off, no install (requires uv)
+uvx --from "python-lucide[search]" lucide search "waiting for a download"
+
+# Or install the search extra
+pip install "python-lucide[search]"
+lucide search "celebrate a big achievement"
+```
+
+<img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-cli.png" width="360" alt="Terminal output of lucide search: each result icon renders inline next to its name and match score">
+
+In terminals supporting the Kitty graphics protocol (kitty, Ghostty,
+WezTerm), the icons render inline as above — inside tmux too, with
+`tmux set -g allow-passthrough on`. Elsewhere you get the plain text
+list. (Rendering uses the cairo system library; if it's missing, the
+CLI prints a hint.)
+
+Icons are matched against AI-generated descriptions using the same embedding
+model the [web app](https://mmacpherson.github.io/python-lucide/) uses,
+so descriptive phrases ("an idea just occurred to me") work better than
+keywords. Options:
+
+- `--model multilingual` — search in 50+ languages (default `bge-small` ranks
+  best for English)
+- `--limit N` — number of results; `--verbose` — include each icon's description
+
+The first search downloads the embedding model (~67 MB) and the pre-built
+search index (11 MB); both are cached, and every search after that runs
+locally in well under a second.
+
+The same search is available as a Python API:
+
+```python
+from lucide.search import search_icons
+
+for r in search_icons("secure login", limit=5):
+    print(r.name, r.score)
+```
+
+Prefer not to install anything? The [browser version](https://mmacpherson.github.io/python-lucide/)
+runs the whole pipeline client-side.
+
 ## Framework Integration Examples
 
 ### Starlette

{python_lucide-0.3.0 → python_lucide-0.5.0}/README.md

@@ -18,6 +18,7 @@ in your Python projects, with no javascript in sight.
 
 ## Features
 - 🎨 **Access 1600+ Lucide icons** directly from Python
+- 🔍 **Semantic search** - find icons by meaning, in the terminal or [in the browser](https://mmacpherson.github.io/python-lucide/)
 - 🛠 **Customize icons** with classes, sizes, colors, and other SVG attributes
 - 🚀 **Framework-friendly** with examples for FastHTML, Flask, Django, and more
 - 📦 **Lightweight** with minimal dependencies
@@ -58,6 +59,60 @@ lucide_icon("user", fill="currentColor")  # Inherit color from CSS
 lucide_icon("user", stroke="#ff6b6b")     # Hex colors work too
 ```
 
+## Semantic Search
+
+Find icons by describing what you mean, not what they're called — in English
+or [50+ languages](https://mmacpherson.github.io/python-lucide/):
+
+<p align="center">
+  <a href="https://mmacpherson.github.io/python-lucide/">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-english.png" width="49%" alt="Searching &quot;celebrate a big achievement&quot; returns trophy, award, medal, party-popper">
+    <img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-multilingual.png" width="49%" alt="Searching in Japanese with the multilingual model returns key, user-key, lock icons">
+  </a>
+</p>
+
+```bash
+# One-off, no install (requires uv)
+uvx --from "python-lucide[search]" lucide search "waiting for a download"
+
+# Or install the search extra
+pip install "python-lucide[search]"
+lucide search "celebrate a big achievement"
+```
+
+<img src="https://raw.githubusercontent.com/mmacpherson/python-lucide/main/.github/images/search-cli.png" width="360" alt="Terminal output of lucide search: each result icon renders inline next to its name and match score">
+
+In terminals supporting the Kitty graphics protocol (kitty, Ghostty,
+WezTerm), the icons render inline as above — inside tmux too, with
+`tmux set -g allow-passthrough on`. Elsewhere you get the plain text
+list. (Rendering uses the cairo system library; if it's missing, the
+CLI prints a hint.)
+
+Icons are matched against AI-generated descriptions using the same embedding
+model the [web app](https://mmacpherson.github.io/python-lucide/) uses,
+so descriptive phrases ("an idea just occurred to me") work better than
+keywords. Options:
+
+- `--model multilingual` — search in 50+ languages (default `bge-small` ranks
+  best for English)
+- `--limit N` — number of results; `--verbose` — include each icon's description
+
+The first search downloads the embedding model (~67 MB) and the pre-built
+search index (11 MB); both are cached, and every search after that runs
+locally in well under a second.
+
+The same search is available as a Python API:
+
+```python
+from lucide.search import search_icons
+
+for r in search_icons("secure login", limit=5):
+    print(r.name, r.score)
+```
+
+Prefer not to install anything? The [browser version](https://mmacpherson.github.io/python-lucide/)
+runs the whole pipeline client-side.
+
 ## Framework Integration Examples
 
 ### Starlette

{python_lucide-0.3.0 → python_lucide-0.5.0}/pyproject.toml

@@ -11,6 +11,7 @@ dev = [
   "mypy>=1.0.0",
   "plotly>=5.0.0",
   "pre-commit>=3.0.0",
+  "pydantic-ai-slim[google]>=1.0.0",
   "pytest-cov>=4.0.0",
   "pytest>=7.0.0",
   "ruff>=0.1.0",
@@ -40,10 +41,10 @@ license = {text = "MIT"}
 name = "python-lucide"
 readme = "README.md"
 requires-python = ">=3.10"
-version = "0.3.0"
+version = "0.5.0"
 
 [project.optional-dependencies]
-search = ["fastembed>=0.4.0"]
+search = ["cairosvg>=2.7.0", "fastembed>=0.4.0"]
 
 [project.scripts]
 check-lucide-version = "lucide.dev_utils:print_version_status"

{python_lucide-0.3.0 → python_lucide-0.5.0}/src/lucide/build_clusters.py

@@ -13,51 +13,68 @@ import logging
 import os
 import pathlib
 import sqlite3
-import urllib.request
 from datetime import datetime, timezone
 
+from pydantic import BaseModel, field_validator
+from pydantic_ai import Agent
+from pydantic_ai.models import Model
+
+from .config import DEFAULT_SEARCH_MODEL_ID
+
 logger = logging.getLogger(__name__)
 
 CLUSTER_NAMING_MODEL = "gemini-2.5-flash"
 
-NAMING_PROMPT_TEMPLATE = """\
-Here are icon names that form a visual/semantic cluster: {icon_names}
+NAMING_INSTRUCTIONS = """\
+You name clusters of icons. Given icon names that form a visual/semantic
+cluster, respond with a short, evocative theme name (2-4 words).
+Be specific about what unifies the icons.
+Do not use generic labels like "UI elements" or "miscellaneous"."""
 
-Give this cluster a short, evocative theme name (2-4 words).
-Be specific about what unifies these icons.
-Do not use generic labels like "UI elements" or "miscellaneous".
+# Generous bound for a "2-4 word" name; anything longer means the model
+# ignored the instruction (e.g. leaked its reasoning)
+MAX_THEME_LENGTH = 40
 
-Return ONLY the theme name, nothing else."""
 
-GEMINI_API_URL = (
-    "https://generativelanguage.googleapis.com/v1beta/models/"
-    "{model}:generateContent?key={api_key}"
-)
+def _sanitize_theme(raw: str) -> str | None:
+    """Validate a model-proposed theme name.
 
+    Models occasionally return their full chain-of-thought instead of just
+    the name — two shipped clusters once carried ~4k-char reasoning dumps
+    as their theme. Reject anything multi-line or implausibly long rather
+    than trying to salvage it.
+
+    Args:
+        raw: The raw model response text.
+
+    Returns:
+        The cleaned theme name, or None if the response is unusable.
+    """
+    theme = raw.strip().strip("\"'").strip()
+    if not theme or "\n" in theme or len(theme) > MAX_THEME_LENGTH:
+        return None
+    return theme
 
-def _call_gemini_text(prompt: str, api_key: str) -> str | None:
-    """Call Gemini API with a text-only prompt."""
-    payload = {"contents": [{"parts": [{"text": prompt}]}]}
-    body = json.dumps(payload).encode("utf-8")
-    url = GEMINI_API_URL.format(model=CLUSTER_NAMING_MODEL, api_key=api_key)
-    req = urllib.request.Request(
-        url,
-        data=body,
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
-    try:
-        with urllib.request.urlopen(req, timeout=30) as resp:
-            result = json.loads(resp.read().decode("utf-8"))
-        candidates = result.get("candidates", [])
-        if candidates:
-            parts = candidates[0].get("content", {}).get("parts", [])
-            if parts:
-                text: str = parts[0].get("text", "")
-                return text.strip()
-    except Exception:
-        logger.warning("Gemini API call failed", exc_info=True)
-    return None
+
+class ClusterTheme(BaseModel):
+    """Structured output for cluster naming.
+
+    A failed validation here becomes a retry request to the model, so a
+    leaked chain-of-thought gets re-asked instead of stored or discarded.
+    """
+
+    theme: str
+
+    @field_validator("theme")
+    @classmethod
+    def _must_be_short_single_line(cls, value: str) -> str:
+        clean = _sanitize_theme(value)
+        if clean is None:
+            raise ValueError(
+                f"theme must be a single line of at most {MAX_THEME_LENGTH} "
+                "characters — return only the 2-4 word name itself"
+            )
+        return clean
 
 
 def discover_clusters(
@@ -83,7 +100,9 @@ def discover_clusters(
         "SELECT e.name, e.embedding, d.description "
         "FROM icon_embeddings e "
         "JOIN icon_descriptions d ON e.name = d.name "
-        "ORDER BY e.name"
+        "WHERE e.model = ? "
+        "ORDER BY e.name",
+        (DEFAULT_SEARCH_MODEL_ID,),
     ).fetchall()
     conn.close()
 
@@ -140,19 +159,40 @@ def name_clusters(
     data: dict,
     *,
     api_key: str | None = None,
+    model: Model | None = None,
 ) -> dict:
-    """Name each cluster using Gemini Flash.
+    """Name each cluster using Gemini Flash via a Pydantic AI agent.
+
+    Output is validated by ``ClusterTheme``; an invalid response (e.g. a
+    leaked chain-of-thought) triggers an automatic retry instead of being
+    stored. Only after retries are exhausted does a cluster fall back to a
+    ``Cluster {id}`` placeholder.
 
     Args:
         data: Output from ``discover_clusters()``.
         api_key: Gemini API key. Falls back to ``GEMINI_API_KEY`` env var.
+        model: Model override, used by tests to avoid real API calls.
 
     Returns:
         The same data dict with ``theme`` populated for each cluster.
     """
-    api_key = api_key or os.environ.get("GEMINI_API_KEY")
-    if not api_key:
-        raise ValueError("Gemini API key required. Set GEMINI_API_KEY.")
+    if model is None:
+        from pydantic_ai.models.google import GoogleModel  # noqa: PLC0415
+        from pydantic_ai.providers.google import GoogleProvider  # noqa: PLC0415
+
+        api_key = api_key or os.environ.get("GEMINI_API_KEY")
+        if not api_key:
+            raise ValueError("Gemini API key required. Set GEMINI_API_KEY.")
+        model = GoogleModel(
+            CLUSTER_NAMING_MODEL, provider=GoogleProvider(api_key=api_key)
+        )
+
+    agent = Agent(
+        model,
+        output_type=ClusterTheme,
+        instructions=NAMING_INSTRUCTIONS,
+        output_retries=3,
+    )
 
     clusters = data["clusters"]
     for lid in sorted(clusters, key=lambda k: -len(clusters[k]["icons"])):
@@ -163,17 +203,15 @@ def name_clusters(
         icons = clusters[lid]["icons"]
         # Cap at 40 names to keep prompt short
         icon_names = ", ".join(icons[:40])
-        prompt = NAMING_PROMPT_TEMPLATE.format(icon_names=icon_names)
-        theme = _call_gemini_text(prompt, api_key)
-
-        if theme:
-            # Strip quotes if the model wraps it
-            theme = theme.strip("\"'")
-            clusters[lid]["theme"] = theme
-            logger.info("Cluster %s (%d icons): %s", lid, len(icons), theme)
-        else:
+        try:
+            result = agent.run_sync(f"Icon cluster: {icon_names}")
+            clusters[lid]["theme"] = result.output.theme
+            logger.info(
+                "Cluster %s (%d icons): %s", lid, len(icons), result.output.theme
+            )
+        except Exception:
             clusters[lid]["theme"] = f"Cluster {lid}"
-            logger.warning("Failed to name cluster %s", lid)
+            logger.warning("Failed to name cluster %s", lid, exc_info=True)
 
     return data
 
@@ -260,8 +298,7 @@ def build_cluster_visualization(
     fig.update_layout(
         title={
             "text": (
-                "Lucide Icon Embedding Clusters \u2014 "
-                "themes discovered via HDBSCAN in 768d space"
+                "Lucide Icon Embedding Clusters \u2014 themes discovered via HDBSCAN"
             ),
             "font": {"size": 16},
         },

{python_lucide-0.3.0 → python_lucide-0.5.0}/src/lucide/build_search.py

@@ -30,10 +30,9 @@ from datetime import datetime, timezone
 from typing import TypedDict
 
 from .config import (
-    DEFAULT_EMBEDDING_DIM,
-    DEFAULT_EMBEDDING_MODEL,
     DEFAULT_VLM_MODEL,
-    EMBEDDING_DOCUMENT_PREFIX,
+    EMBEDDING_MODELS,
+    SEARCH_DB_SCHEMA_VERSION,
 )
 
 logger = logging.getLogger(__name__)
@@ -486,9 +485,10 @@ def _ensure_search_tables(conn: sqlite3.Connection) -> None:
     )
     conn.execute(
         "CREATE TABLE IF NOT EXISTS icon_embeddings ("
-        "  name TEXT PRIMARY KEY,"
+        "  name TEXT NOT NULL,"
         "  embedding BLOB NOT NULL,"
-        "  model TEXT NOT NULL"
+        "  model TEXT NOT NULL,"
+        "  PRIMARY KEY (name, model)"
         ")"
     )
     conn.execute(
@@ -513,23 +513,35 @@ def _write_search_db(  # noqa: PLR0913
     search_db_path: pathlib.Path,
     ordered_names: list[str],
     records: dict[str, DescriptionRecord],
-    embeddings: list,
+    embeddings: dict[str, dict[str, object]],
     clusters_path: pathlib.Path,
     *,
     version: str | None = None,
     verbose: bool = False,
 ) -> None:
-    """Write descriptions, embeddings, clusters, and metadata to SQLite."""
+    """Write descriptions, embeddings, clusters, and metadata to SQLite.
+
+    Args:
+        search_db_path: Output SQLite path (recreated from scratch).
+        ordered_names: Icon names in insertion order.
+        records: Description records keyed by icon name.
+        embeddings: Embedding vectors as ``{model_id: {icon_name: vector}}``.
+            A model may cover only a subset of icons; absent names are
+            simply not inserted for that model.
+        clusters_path: JSON file with cluster assignments.
+        version: Lucide icon-set version for the metadata table.
+        verbose: Verbose logging.
+    """
     import numpy as np  # noqa: PLC0415
 
     search_db_path.parent.mkdir(parents=True, exist_ok=True)
+    # Recreate rather than DELETE-and-reuse: the schema itself may have
+    # changed since the last build (CREATE IF NOT EXISTS won't migrate it)
+    search_db_path.unlink(missing_ok=True)
     conn = sqlite3.connect(search_db_path)
     try:
         _ensure_search_tables(conn)
 
-        conn.execute("DELETE FROM icon_descriptions")
-        conn.execute("DELETE FROM icon_embeddings")
-
         for name in ordered_names:
             rec = records[name]
             conn.execute(
@@ -538,15 +550,18 @@ def _write_search_db(  # noqa: PLR0913
                 (name, rec["description"], rec["model"]),
             )
 
-        for name, emb in zip(ordered_names, embeddings, strict=True):
-            blob = np.array(emb, dtype=np.float32).tobytes()
-            conn.execute(
-                "INSERT INTO icon_embeddings (name, embedding, model) VALUES (?, ?, ?)",
-                (name, blob, DEFAULT_EMBEDDING_MODEL),
-            )
+        for model_id, vectors_by_name in embeddings.items():
+            for name in ordered_names:
+                if name not in vectors_by_name:
+                    continue
+                blob = np.array(vectors_by_name[name], dtype=np.float32).tobytes()
+                conn.execute(
+                    "INSERT INTO icon_embeddings (name, embedding, model)"
+                    " VALUES (?, ?, ?)",
+                    (name, blob, model_id),
+                )
 
         # Load clusters
-        conn.execute("DELETE FROM icon_clusters")
         cluster_data = json.loads(clusters_path.read_text())
         for cid, cluster in cluster_data["clusters"].items():
             theme = cluster.get("theme", f"Cluster {cid}")
@@ -584,10 +599,11 @@ def _write_search_db(  # noqa: PLR0913
         first = records[ordered_names[0]]
         resolved_version = version or first.get("lucide_version", "unknown")
         now = datetime.now(tz=timezone.utc).isoformat()
+        model_dims = json.dumps({mid: EMBEDDING_MODELS[mid].dim for mid in embeddings})
         for key, value in [
             ("version", resolved_version),
-            ("embedding_model", DEFAULT_EMBEDDING_MODEL),
-            ("embedding_dim", str(DEFAULT_EMBEDDING_DIM)),
+            ("schema_version", str(SEARCH_DB_SCHEMA_VERSION)),
+            ("embedding_models", model_dims),
             ("description_model", DEFAULT_VLM_MODEL),
             ("built_at", now),
         ]:
@@ -631,9 +647,10 @@ def build_search_db(
 ) -> None:
     """Build the SQLite search database from descriptions, embeddings, and clusters.
 
-    Reads descriptions from *jsonl_path*, computes embeddings with fastembed,
-    loads cluster assignments from *clusters_path*, and writes everything to
-    *search_db_path*.  The DB is rebuilt from scratch each time.
+    Reads descriptions from *jsonl_path*, computes one embedding set per
+    model in ``EMBEDDING_MODELS`` with fastembed, loads cluster assignments
+    from *clusters_path*, and writes everything to *search_db_path*.  The DB
+    is rebuilt from scratch each time.
 
     When *icons_db_path* is provided, only icons present in that database are
     included and the version metadata is read from it.
@@ -687,12 +704,18 @@ def build_search_db(
         if rec["categories"]:
             parts.append(f"Categories: {', '.join(rec['categories'])}")
         parts.append(rec["description"])
-        return f"{EMBEDDING_DOCUMENT_PREFIX}{'. '.join(parts)}"
-
-    texts = [_embedding_text(records[n]) for n in ordered_names]
-    embedder = TextEmbedding(model_name=DEFAULT_EMBEDDING_MODEL)
-    embeddings = list(embedder.embed(texts))
-    logger.info("Computed %d embeddings", len(embeddings))
+        return ". ".join(parts)
+
+    base_texts = [_embedding_text(records[n]) for n in ordered_names]
+    embeddings: dict[str, dict[str, object]] = {}
+    for model_id, model_cfg in EMBEDDING_MODELS.items():
+        texts = [f"{model_cfg.document_prefix}{t}" for t in base_texts]
+        embedder = TextEmbedding(model_name=model_cfg.fastembed_model)
+        vecs = list(embedder.embed(texts))
+        embeddings[model_id] = dict(zip(ordered_names, vecs, strict=True))
+        logger.info(
+            "Computed %d embeddings with %s", len(texts), model_cfg.fastembed_model
+        )
 
     _write_search_db(
         search_db_path,