vector-inspector 0.3.6__tar.gz → 0.3.8__tar.gz

{vector_inspector-0.3.6 → vector_inspector-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vector-inspector
-Version: 0.3.6
+Version: 0.3.8
 Summary: A comprehensive desktop application for visualizing, querying, and managing vector database data
 Author-Email: Anthony Dawson <anthonypdawson+github@gmail.com>
 License: MIT
@@ -31,9 +31,31 @@ Requires-Dist: pgvector>=0.4.2
 Description-Content-Type: text/markdown
 
 # Latest updates
-- Added Postgres (pgvector extension) support as a new vector database connection option.
-- Fixed issue with embedding regeneration on add/edit
-- Added option for editing items without regenerating embeddings
+
+## Vector Inspector 2026.01 Release Notes
+
+### Major Refactor and Studio-Ready Architecture
+- Refactored main window into modular components:
+  - InspectorShell: reusable UI shell (splitter, tabs, layout)
+  - ProviderFactory: centralized connection creation
+  - DialogService: dialog management
+  - ConnectionController: connection lifecycle and threading
+  - InspectorTabs: pluggable tab registry
+- MainWindow now inherits from InspectorShell and is fully reusable as a widget
+- Bootstrap logic is separated from UI logic—Studio can host Inspector as a component
+- Tab system is now pluggable: Studio and Inspector can add, remove, or override tabs via TabDefinition
+- All Inspector UI logic is self-contained; Studio can extend without modifying Inspector code
+
+### Data Browser Improvements
+- Added a checkbox: Generate embeddings on edit (default: checked)
+  - When unchecked, editing a row skips embedding regeneration
+  - Setting is persisted per user
+
+### Developer and Architecture Notes
+- All modules pass syntax checks and are ready for Studio integration
+- No breaking changes for existing Inspector users
+- Inspector is now a true UI module, not just an application
+
 ---
 
 # Vector Inspector
@@ -41,7 +63,7 @@ Description-Content-Type: text/markdown
 > **Disclaimer:** This tool is currently under active development and is **not production ready**. Not all features have been thoroughly tested and code is released frequently. Use with caution in critical or production environments.
 
 [![CI](https://github.com/anthonypdawson/vector-inspector/actions/workflows/ci-tests.yml/badge.svg?branch=master)](https://github.com/anthonypdawson/vector-inspector/actions/workflows/ci-tests.yml)
-[![Publish](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish.yml/badge.svg?branch=master)](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish.yml)
+[![Publish](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish%20copy.yml/badge.svg?branch=master)](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish%20copy.yml)
 
 [![PyPI Version](https://img.shields.io/pypi/v/vector-inspector.svg?cacheSeconds=300)](https://pypi.org/project/vector-inspector/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/vector-inspector?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/vector-inspector)

{vector_inspector-0.3.6 → vector_inspector-0.3.8}/README.md

@@ -1,7 +1,29 @@
 # Latest updates
-- Added Postgres (pgvector extension) support as a new vector database connection option.
-- Fixed issue with embedding regeneration on add/edit
-- Added option for editing items without regenerating embeddings
+
+## Vector Inspector 2026.01 Release Notes
+
+### Major Refactor and Studio-Ready Architecture
+- Refactored main window into modular components:
+  - InspectorShell: reusable UI shell (splitter, tabs, layout)
+  - ProviderFactory: centralized connection creation
+  - DialogService: dialog management
+  - ConnectionController: connection lifecycle and threading
+  - InspectorTabs: pluggable tab registry
+- MainWindow now inherits from InspectorShell and is fully reusable as a widget
+- Bootstrap logic is separated from UI logic—Studio can host Inspector as a component
+- Tab system is now pluggable: Studio and Inspector can add, remove, or override tabs via TabDefinition
+- All Inspector UI logic is self-contained; Studio can extend without modifying Inspector code
+
+### Data Browser Improvements
+- Added a checkbox: Generate embeddings on edit (default: checked)
+  - When unchecked, editing a row skips embedding regeneration
+  - Setting is persisted per user
+
+### Developer and Architecture Notes
+- All modules pass syntax checks and are ready for Studio integration
+- No breaking changes for existing Inspector users
+- Inspector is now a true UI module, not just an application
+
 ---
 
 # Vector Inspector
@@ -9,7 +31,7 @@
 > **Disclaimer:** This tool is currently under active development and is **not production ready**. Not all features have been thoroughly tested and code is released frequently. Use with caution in critical or production environments.
 
 [![CI](https://github.com/anthonypdawson/vector-inspector/actions/workflows/ci-tests.yml/badge.svg?branch=master)](https://github.com/anthonypdawson/vector-inspector/actions/workflows/ci-tests.yml)
-[![Publish](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish.yml/badge.svg?branch=master)](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish.yml)
+[![Publish](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish%20copy.yml/badge.svg?branch=master)](https://github.com/anthonypdawson/vector-inspector/actions/workflows/publish%20copy.yml)
 
 [![PyPI Version](https://img.shields.io/pypi/v/vector-inspector.svg?cacheSeconds=300)](https://pypi.org/project/vector-inspector/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/vector-inspector?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/vector-inspector)

{vector_inspector-0.3.6 → vector_inspector-0.3.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vector-inspector"
-version = "0.3.6"
+version = "0.3.8"
 description = "A comprehensive desktop application for visualizing, querying, and managing vector database data"
 authors = [
     { name = "Anthony Dawson", email = "anthonypdawson+github@gmail.com" },

{vector_inspector-0.3.6 → vector_inspector-0.3.8}/src/vector_inspector/core/connections/chroma_connection.py

@@ -489,7 +489,7 @@ class ChromaDBConnection(VectorDBConnection):
             name: Collection name
 
         Returns:
-            True if successful, False otherwise
+            True if successful or collection does not exist, False otherwise
         """
         if not self._client:
             return False
@@ -500,6 +500,9 @@ class ChromaDBConnection(VectorDBConnection):
                 self._current_collection = None
             return True
         except Exception as e:
+            # If the exception is about the collection not existing, treat as success (idempotent)
+            if "does not exist" in str(e).lower():
+                return True
             log_error("Failed to delete collection: %s", e)
             return False
 

{vector_inspector-0.3.6 → vector_inspector-0.3.8}/src/vector_inspector/core/connections/pgvector_connection.py

@@ -1,6 +1,6 @@
 """PgVector/PostgreSQL connection manager."""
 
-from typing import Optional, List, Dict, Any
+from typing import Any
 import json
 import psycopg2
 from psycopg2 import sql
@@ -36,7 +36,7 @@ class PgVectorConnection(VectorDBConnection):
         self.database = database
         self.user = user
         self.password = password
-        self._client: Optional[psycopg2.extensions.connection] = None
+        self._client = None
         # Track how many embeddings were regenerated by the last update operation
         self._last_regenerated_count: int = 0
 
@@ -94,7 +94,7 @@ class PgVectorConnection(VectorDBConnection):
         """Check if connected to PostgreSQL."""
         return self._client is not None
 
-    def list_collections(self) -> List[str]:
+    def list_collections(self) -> list[str]:
         """
         Get list of all vector tables (collections).
 
@@ -117,7 +117,7 @@ class PgVectorConnection(VectorDBConnection):
             log_error("Failed to list collections: %s", e)
             return []
 
-    def list_databases(self) -> List[str]:
+    def list_databases(self) -> list[str]:
         """
         List available databases on the server (non-template databases).
 
@@ -155,7 +155,7 @@ class PgVectorConnection(VectorDBConnection):
                 except Exception:
                     pass
 
-    def get_collection_info(self, name: str) -> Optional[Dict[str, Any]]:
+    def get_collection_info(self, name: str) -> dict[str, Any] | None:
         """
         Get collection metadata and statistics.
 
@@ -291,10 +291,10 @@ class PgVectorConnection(VectorDBConnection):
     def add_items(
         self,
         collection_name: str,
-        documents: List[str],
-        metadatas: Optional[List[Dict[str, Any]]] = None,
-        ids: Optional[List[str]] = None,
-        embeddings: Optional[List[List[float]]] = None,
+        documents: list[str],
+        metadatas: list[dict[str, Any]] | None = None,
+        ids: list[str] | None = None,
+        embeddings: list[list[float]] | None = None,
     ) -> bool:
         """
         Add items to a collection.
@@ -312,66 +312,16 @@ class PgVectorConnection(VectorDBConnection):
         if not self._client:
             return False
 
-        # If embeddings weren't provided, try to compute them using configured/default model
+        # If embeddings weren't provided, try to compute them using the helper method
         if not embeddings:
             try:
-                from vector_inspector.services.settings_service import SettingsService
-                from vector_inspector.core.embedding_utils import (
-                    load_embedding_model,
-                    get_embedding_model_for_dimension,
-                    DEFAULT_MODEL,
-                    encode_text,
-                )
-
-                model_name = None
-                model_type = None
-
-                # 1) settings
-                settings = SettingsService()
-                model_info = settings.get_embedding_model(self.database, collection_name)
-                if model_info:
-                    model_name = model_info.get("model")
-                    model_type = model_info.get("type", "sentence-transformer")
-
-                # 2) collection metadata
-                coll_info = None
-                if not model_name:
-                    coll_info = self.get_collection_info(collection_name)
-                    if coll_info and coll_info.get("embedding_model"):
-                        model_name = coll_info.get("embedding_model")
-                        model_type = coll_info.get("embedding_model_type", "stored")
-
-                # 3) dimension-based fallback
-                loaded_model = None
-                if not model_name:
-                    # Try to get vector dimension
-                    dim = None
-                    if not coll_info:
-                        coll_info = self.get_collection_info(collection_name)
-                    if coll_info and coll_info.get("vector_dimension"):
-                        try:
-                            dim = int(coll_info.get("vector_dimension"))
-                        except Exception:
-                            dim = None
-                    if dim:
-                        loaded_model, model_name, model_type = get_embedding_model_for_dimension(
-                            dim
-                        )
-                    else:
-                        model_name, model_type = DEFAULT_MODEL
-
-                # Load model
-                if not loaded_model:
-                    loaded_model = load_embedding_model(model_name, model_type)
-
-                # Compute embeddings for all documents
-                if model_type != "clip":
-                    embeddings = loaded_model.encode(documents, show_progress_bar=False).tolist()
-                else:
-                    embeddings = [encode_text(d, loaded_model, model_type) for d in documents]
+                embeddings = self.compute_embeddings_for_documents(collection_name, documents)
             except Exception as e:
                 log_error("Failed to compute embeddings on add: %s", e)
                 return False
+            if embeddings is None:
+                return False
+
         try:
             import uuid
 
@@ -428,7 +378,7 @@ class PgVectorConnection(VectorDBConnection):
                 self._client.rollback()
             return False
 
-    def get_items(self, name: str, ids: List[str]) -> Dict[str, Any]:
+    def get_items(self, name: str, ids: list[str]) -> dict[str, Any]:
         """
         Retrieve items by IDs.
 
@@ -548,12 +498,12 @@ class PgVectorConnection(VectorDBConnection):
     def query_collection(
         self,
         collection_name: str,
-        query_texts: Optional[List[str]] = None,
-        query_embeddings: Optional[List[List[float]]] = None,
+        query_texts: list[str] | None = None,
+        query_embeddings: list[list[float]] | None = None,
         n_results: int = 10,
-        where: Optional[Dict[str, Any]] = None,
-        where_document: Optional[Dict[str, Any]] = None,
-    ) -> Optional[Dict[str, Any]]:
+        where: dict[str, Any] | None = None,
+        where_document: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
         """
         Query a collection for similar vectors.
 
@@ -601,6 +551,7 @@ class PgVectorConnection(VectorDBConnection):
                 # 3) dimension-based fallback
                 loaded_model = None
                 if not model_name:
+                    # Try to get vector dimension
                     dim = None
                     coll_info = self.get_collection_info(collection_name)
                     if coll_info and coll_info.get("vector_dimension"):
@@ -613,6 +564,7 @@ class PgVectorConnection(VectorDBConnection):
                             dim
                         )
                     else:
+                        # Use default model
                         model_name, model_type = DEFAULT_MODEL
 
                 if not loaded_model:
@@ -636,11 +588,11 @@ class PgVectorConnection(VectorDBConnection):
             # so callers receive the top-N results per query (matching SearchView expectations).
             with self._client.cursor() as cur:
                 # Prepare containers for per-query results
-                per_ids: List[List[str]] = []
-                per_docs: List[List[str]] = []
-                per_metas: List[List[Dict[str, Any]]] = []
-                per_embeds: List[List[List[float]]] = []
-                per_dists: List[List[float]] = []
+                per_ids = []
+                per_docs = []
+                per_metas = []
+                per_embeds = []
+                per_dists = []
 
                 for emb in query_embeddings:
                     # Build base query for this single embedding
@@ -675,11 +627,11 @@ class PgVectorConnection(VectorDBConnection):
                     colnames = [desc[0] for desc in cur.description]
 
                     # Build per-query result lists
-                    ids_q: List[str] = []
-                    docs_q: List[str] = []
-                    metas_q: List[Dict[str, Any]] = []
-                    embeds_q: List[List[float]] = []
-                    dists_q: List[float] = []
+                    ids_q = []
+                    docs_q = []
+                    metas_q = []
+                    embeds_q = []
+                    dists_q = []
 
                     for row in rows:
                         row_dict = dict(zip(colnames, row))
@@ -731,10 +683,10 @@ class PgVectorConnection(VectorDBConnection):
     def get_all_items(
         self,
         collection_name: str,
-        limit: Optional[int] = None,
-        offset: Optional[int] = None,
-        where: Optional[Dict[str, Any]] = None,
-    ) -> Optional[Dict[str, Any]]:
+        limit: int | None = None,
+        offset: int | None = None,
+        where: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
         """
         Get all items from a collection.
 
@@ -835,10 +787,10 @@ class PgVectorConnection(VectorDBConnection):
     def update_items(
         self,
         collection_name: str,
-        ids: List[str],
-        documents: Optional[List[str]] = None,
-        metadatas: Optional[List[Dict[str, Any]]] = None,
-        embeddings: Optional[List[List[float]]] = None,
+        ids: list[str],
+        documents: list[str] | None = None,
+        metadatas: list[dict[str, Any]] | None = None,
+        embeddings: list[list[float]] | None = None,
     ) -> bool:
         """
         Update items in a collection.
@@ -1002,8 +954,8 @@ class PgVectorConnection(VectorDBConnection):
     def delete_items(
         self,
         collection_name: str,
-        ids: Optional[List[str]] = None,
-        where: Optional[Dict[str, Any]] = None,
+        ids: list[str] | None = None,
+        where: dict[str, Any] | None = None,
     ) -> bool:
         """
         Delete items from a collection.
@@ -1034,7 +986,7 @@ class PgVectorConnection(VectorDBConnection):
                 self._client.rollback()
             return False
 
-    def get_connection_info(self) -> Dict[str, Any]:
+    def get_connection_info(self) -> dict[str, Any]:
         """
         Get information about the current connection.
 
@@ -1050,7 +1002,7 @@ class PgVectorConnection(VectorDBConnection):
             "connected": self.is_connected,
         }
 
-    def _get_table_schema(self, table_name: str) -> Dict[str, str]:
+    def _get_table_schema(self, table_name: str) -> dict[str, str]:
         """
         Get the schema (column names and types) for a table.
 
@@ -1081,7 +1033,7 @@ class PgVectorConnection(VectorDBConnection):
             log_error("Failed to get table schema: %s", e)
             return {}
 
-    def _parse_vector(self, vector_str: Any) -> List[float]:
+    def _parse_vector(self, vector_str: Any) -> list[float]:
         """
         Parse pgvector string format to Python list.
 
@@ -1098,3 +1050,66 @@ class PgVectorConnection(VectorDBConnection):
             vector_str = vector_str.strip("[]")
             return [float(x) for x in vector_str.split(",")]
         return []
+
+    def compute_embeddings_for_documents(
+        self, collection_name: str, documents: list[str]
+    ) -> list[list[float]] | None:
+        """
+        Compute embeddings for a list of documents using the configured/default model for the collection.
+        Returns a list of embeddings, or None on failure.
+        """
+        try:
+            from vector_inspector.services.settings_service import SettingsService
+            from vector_inspector.core.embedding_utils import (
+                load_embedding_model,
+                get_embedding_model_for_dimension,
+                DEFAULT_MODEL,
+                encode_text,
+            )
+
+            model_name = None
+            model_type = None
+
+            # 1) settings
+            settings = SettingsService()
+            model_info = settings.get_embedding_model(self.database, collection_name)
+            if model_info:
+                model_name = model_info.get("model")
+                model_type = model_info.get("type", "sentence-transformer")
+
+            # 2) collection metadata
+            if not model_name:
+                coll_info = self.get_collection_info(collection_name)
+                if coll_info and coll_info.get("embedding_model"):
+                    model_name = coll_info.get("embedding_model")
+                    model_type = coll_info.get("embedding_model_type", "stored")
+
+            # 3) dimension-based fallback
+            loaded_model = None
+            if not model_name:
+                # Try to get vector dimension
+                dim = None
+                coll_info = self.get_collection_info(collection_name)
+                if coll_info and coll_info.get("vector_dimension"):
+                    try:
+                        dim = int(coll_info.get("vector_dimension"))
+                    except Exception:
+                        dim = None
+                if dim:
+                    loaded_model, model_name, model_type = get_embedding_model_for_dimension(dim)
+                else:
+                    model_name, model_type = DEFAULT_MODEL
+
+            # Load model
+            if not loaded_model:
+                loaded_model = load_embedding_model(model_name, model_type)
+
+            # Compute embeddings for all documents
+            if model_type != "clip":
+                embeddings = loaded_model.encode(documents, show_progress_bar=False).tolist()
+            else:
+                embeddings = [encode_text(d, loaded_model, model_type) for d in documents]
+            return embeddings
+        except Exception as e:
+            log_error("Failed to compute embeddings: %s", e)
+            return None

{vector_inspector-0.3.6 → vector_inspector-0.3.8}/src/vector_inspector/core/connections/pinecone_connection.py

@@ -239,6 +239,10 @@ class PineconeConnection(VectorDBConnection):
                 log_error("Embeddings are required for Pinecone and computing them failed: %s", e)
                 return False
 
+        if not embeddings:
+            log_error("Embeddings are required for Pinecone but none were provided or computed")
+            return False
+
         index = self._get_index(collection_name)
         if not index:
             return False

{vector_inspector-0.3.6 → vector_inspector-0.3.8}/src/vector_inspector/core/connections/qdrant_connection.py

@@ -512,6 +512,19 @@ class QdrantConnection(VectorDBConnection):
         """
         if not self._client:
             return False
+        # Reject empty document lists early
+        if not documents:
+            return False
+
+        # If embeddings provided, ensure counts match
+        if embeddings is not None and len(embeddings) != len(documents):
+            log_error(
+                "Embeddings length (%d) does not match documents length (%d) for collection %s",
+                len(embeddings),
+                len(documents),
+                collection_name,
+            )
+            return False
 
         # If embeddings not provided, compute using model resolution helper
         if not embeddings and documents:

vector_inspector-0.3.8/src/vector_inspector/core/provider_factory.py

@@ -0,0 +1,97 @@
+"""Factory for creating vector database connections from provider configs."""
+
+from typing import Dict, Any
+from vector_inspector.core.connections.base_connection import VectorDBConnection
+from vector_inspector.core.connections.chroma_connection import ChromaDBConnection
+from vector_inspector.core.connections.qdrant_connection import QdrantConnection
+from vector_inspector.core.connections.pinecone_connection import PineconeConnection
+from vector_inspector.core.connections.pgvector_connection import PgVectorConnection
+
+
+class ProviderFactory:
+    """Factory for creating database connections from configuration."""
+
+    @staticmethod
+    def create(
+        provider: str, config: Dict[str, Any], credentials: Dict[str, Any] = None
+    ) -> VectorDBConnection:
+        """Create a connection object for the specified provider.
+
+        Args:
+            provider: Provider type (chromadb, qdrant, pinecone, pgvector)
+            config: Provider-specific configuration
+            credentials: Optional credentials (API keys, passwords, etc.)
+
+        Returns:
+            VectorDBConnection instance
+
+        Raises:
+            ValueError: If provider is unsupported or configuration is invalid
+        """
+        credentials = credentials or {}
+
+        if provider == "chromadb":
+            return ProviderFactory._create_chroma(config, credentials)
+        elif provider == "qdrant":
+            return ProviderFactory._create_qdrant(config, credentials)
+        elif provider == "pinecone":
+            return ProviderFactory._create_pinecone(config, credentials)
+        elif provider == "pgvector":
+            return ProviderFactory._create_pgvector(config, credentials)
+        else:
+            raise ValueError(f"Unsupported provider: {provider}")
+
+    @staticmethod
+    def _create_chroma(config: Dict[str, Any], credentials: Dict[str, Any]) -> ChromaDBConnection:
+        """Create a ChromaDB connection."""
+        conn_type = config.get("type")
+
+        if conn_type == "persistent":
+            return ChromaDBConnection(path=config.get("path"))
+        elif conn_type == "http":
+            return ChromaDBConnection(host=config.get("host"), port=config.get("port"))
+        else:  # ephemeral
+            return ChromaDBConnection()
+
+    @staticmethod
+    def _create_qdrant(config: Dict[str, Any], credentials: Dict[str, Any]) -> QdrantConnection:
+        """Create a Qdrant connection."""
+        conn_type = config.get("type")
+        api_key = credentials.get("api_key")
+
+        if conn_type == "persistent":
+            return QdrantConnection(path=config.get("path"))
+        elif conn_type == "http":
+            return QdrantConnection(
+                host=config.get("host"), port=config.get("port"), api_key=api_key
+            )
+        else:  # ephemeral
+            return QdrantConnection()
+
+    @staticmethod
+    def _create_pinecone(config: Dict[str, Any], credentials: Dict[str, Any]) -> PineconeConnection:
+        """Create a Pinecone connection."""
+        api_key = credentials.get("api_key")
+        if not api_key:
+            raise ValueError("Pinecone requires an API key")
+
+        return PineconeConnection(api_key=api_key)
+
+    @staticmethod
+    def _create_pgvector(config: Dict[str, Any], credentials: Dict[str, Any]) -> PgVectorConnection:
+        """Create a PgVector/Postgres connection."""
+        conn_type = config.get("type")
+
+        if conn_type == "http":
+            host = config.get("host", "localhost")
+            port = int(config.get("port", 5432))
+            database = config.get("database")
+            user = config.get("user")
+            # Prefer password from credentials
+            password = credentials.get("password")
+
+            return PgVectorConnection(
+                host=host, port=port, database=database, user=user, password=password
+            )
+
+        raise ValueError("Unsupported connection type for PgVector profile")

vector_inspector-0.3.8/src/vector_inspector/services/update_service.py

@@ -0,0 +1,73 @@
+import os
+import json
+import time
+import requests
+from typing import Optional, Dict
+
+GITHUB_API_URL = "https://api.github.com/repos/anthonypdawson/vector-inspector/releases/latest"
+CACHE_FILE = os.path.expanduser("~/.vector_inspector_update_cache.json")
+CACHE_TTL = 24 * 60 * 60  # 1 day in seconds
+
+
+class UpdateService:
+    @staticmethod
+    def get_latest_release(force_refresh: bool = False) -> Optional[Dict]:
+        """
+        Fetch the latest release info from GitHub, with caching and rate limit handling.
+        Returns None on error or if rate limited.
+        """
+        now = int(time.time())
+        # Check cache for rate limit state or valid release
+        if os.path.exists(CACHE_FILE):
+            try:
+                with open(CACHE_FILE, "r", encoding="utf-8") as f:
+                    cache = json.load(f)
+                # If rate limited, respect the reset time
+                if cache.get("rate_limited_until", 0) > now:
+                    return None
+                if not force_refresh and now - cache.get("timestamp", 0) < CACHE_TTL:
+                    return cache.get("release")
+            except Exception:
+                pass
+        try:
+            resp = requests.get(GITHUB_API_URL, timeout=5)
+            if resp.status_code == 200:
+                release = resp.json()
+                with open(CACHE_FILE, "w", encoding="utf-8") as f:
+                    json.dump({"timestamp": now, "release": release}, f)
+                return release
+            elif resp.status_code == 403:
+                # Check for rate limit headers
+                reset = resp.headers.get("X-RateLimit-Reset")
+                if reset:
+                    rate_limited_until = int(reset)
+                else:
+                    # Default to 1 hour if no header
+                    rate_limited_until = now + 3600
+                with open(CACHE_FILE, "w", encoding="utf-8") as f:
+                    json.dump({"rate_limited_until": rate_limited_until}, f)
+                return None
+        except Exception:
+            pass
+        return None
+
+    @staticmethod
+    def compare_versions(current_version: str, latest_version: str) -> bool:
+        """
+        Returns True if latest_version is newer than current_version.
+        """
+
+        def parse(v):
+            return [int(x) for x in v.strip("v").split(".") if x.isdigit()]
+
+        return parse(latest_version) > parse(current_version)
+
+    @staticmethod
+    def get_update_instructions() -> Dict[str, str]:
+        """
+        Returns update instructions for both PyPI and GitHub.
+        """
+        return {
+            "pip": "pip install --upgrade vector-inspector",
+            "github": "https://github.com/anthonypdawson/vector-inspector/releases/latest",
+        }