refactor!: complete vdb to search rename with breaking API changes

titusz · titusz · commit 257e5a5b17fb · 2025-10-27T11:32:49.000+01:00
BREAKING CHANGE: Complete rename from VDB to Search terminology with breaking changes to public APIs.

Class and variable renames:
- VdbSettings → SearchSettings
- vdb_settings → search_settings
- Environment prefix: ISCC_VDB_ → ISCC_SEARCH_

API and documentation updates:
- API title: "ISCC-VDB API" → "ISCC-Search API"
- Update all docstrings and module documentation
- Update OpenAPI specification
- Update architecture and spec documentation

Configuration:
- Remove unused devcontainer configuration
- Update git pre-commit hook paths

All 803 tests pass with 100% coverage.

Users must update:
- Environment variables: ISCC_VDB_INDEXES_URI → ISCC_SEARCH_INDEXES_URI
- Python imports: from iscc_search.settings import SearchSettings, search_settings
- Any external integrations expecting "ISCC-VDB API" title
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
diff --git a/.devcontainer/postCreateCommand.sh b/.devcontainer/postCreateCommand.sh
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,10 +4,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-**iscc-search** is a high-performance ISCC similarity search engine for ISCC (International Standard Content Code).
-In active development (v0.0.1), it provides high-performance vector similarity search for variable-length binary ISCC
-vectors using the Normalized Prefix Hamming Distance (NPHD) metric. Built on top of usearch for fast approximate
-nearest neighbor search.
+**iscc-search** is a high-performance ISCC similarity search engine for ISCC (International Standard Content
+Code). In active development (v0.0.1), it provides high-performance vector similarity search for variable-length
+binary ISCC vectors using the Normalized Prefix Hamming Distance (NPHD) metric. Built on top of usearch for fast
+approximate nearest neighbor search.
 
 ## Development Commands
 
diff --git a/README.md b/README.md
@@ -11,8 +11,8 @@
 >
 > The API and features are subject to significant changes. Use at your own risk.
 
-High-performance ISCC similarity search engine for variable-length binary [ISCC](https://iscc.codes) codes with fast
-approximate nearest neighbor search.
+High-performance ISCC similarity search engine for variable-length binary [ISCC](https://iscc.codes) codes with
+fast approximate nearest neighbor search.
 
 - **Github repository**: <https://github.com/iscc/iscc-search/>
 - **Documentation** <https://search.iscc.codes/>
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,9 +1,9 @@
-# ISCC-VDB Architecture
+# ISCC-Search Architecture
 
 ## Overview
 
-ISCC-VDB implements a clean, protocol-based architecture that supports multiple index implementations through a
-unified interface. The system uses Python's `typing.Protocol` to define an index abstraction that enables both
+ISCC-Search implements a clean, protocol-based architecture that supports multiple index implementations through
+a unified interface. The system uses Python's `typing.Protocol` to define an index abstraction that enables both
 CLI and REST API frontends to work seamlessly with different storage implementations.
 
 **Current Implementation Status**:
@@ -100,19 +100,19 @@ All operations are synchronous for simplicity:
 
 ### 3. Pydantic Settings-Based Configuration
 
-Single `ISCC_VDB_INDEXES_URI` environment variable determines index implementation:
+Single `ISCC_SEARCH_INDEXES_URI` environment variable determines index implementation:
 
-- **memory://**: `ISCC_VDB_INDEXES_URI=memory://` → MemoryIndex (in-memory, no persistence) **[IMPLEMENTED]**
-- **Directory path**: `ISCC_VDB_INDEXES_URI=/path/to/index_data` → LmdbIndexManager (file-based persistence)
+- **memory://**: `ISCC_SEARCH_INDEXES_URI=memory://` → MemoryIndex (in-memory, no persistence) **[IMPLEMENTED]**
+- **Directory path**: `ISCC_SEARCH_INDEXES_URI=/path/to/index_data` → LmdbIndexManager (file-based persistence)
     **[IMPLEMENTED]**
-- **Postgres DSN**: `ISCC_VDB_INDEXES_URI=postgresql://user:pass@host/db` → PostgresIndex **[PLANNED]**
+- **Postgres DSN**: `ISCC_SEARCH_INDEXES_URI=postgresql://user:pass@host/db` → PostgresIndex **[PLANNED]**
 - **Default**: Uses `platformdirs` to determine OS-appropriate user data directory → LmdbIndexManager
     **[IMPLEMENTED]**
 
 Configuration uses Pydantic Settings for:
 
 - Type validation and coercion
-- Environment variable loading with `ISCC_VDB_` prefix
+- Environment variable loading with `ISCC_SEARCH_` prefix
 - `.env` file support
 - Runtime override capability
 - Clear documentation of all settings
@@ -222,10 +222,10 @@ All methods are synchronous. Backends may use threading/connection pools interna
 
 ### Settings and Configuration (`settings.py`)
 
-**VdbSettings**: Pydantic settings class with:
+**SearchSettings**: Pydantic settings class with:
 
 - `indexes_uri` - Location for index data (path or DSN), defaults to OS user data directory
-- Environment variable support (`ISCC_VDB_` prefix)
+- Environment variable support (`ISCC_SEARCH_` prefix)
 - `.env` file support
 - `override()` method for runtime configuration changes
 
@@ -318,8 +318,8 @@ All methods are synchronous. Backends may use threading/connection pools interna
 ### LMDB Index (Production)
 
 ```bash
-# Set ISCC_VDB_INDEXES_URI to local path (or use default from platformdirs)
-export ISCC_VDB_INDEXES_URI=/path/to/index_data
+# Set ISCC_SEARCH_INDEXES_URI to local path (or use default from platformdirs)
+export ISCC_SEARCH_INDEXES_URI=/path/to/index_data
 
 # CLI commands
 iscc-search create myindex
@@ -335,8 +335,8 @@ uvicorn iscc_search.server.app:app --host 0.0.0.0 --port 8000
 ### Memory Index (Testing)
 
 ```bash
-# Set ISCC_VDB_INDEXES_URI to memory:// for in-memory index
-export ISCC_VDB_INDEXES_URI=memory://
+# Set ISCC_SEARCH_INDEXES_URI to memory:// for in-memory index
+export ISCC_SEARCH_INDEXES_URI=memory://
 
 # CLI works with in-memory storage (no persistence)
 iscc-search create myindex
@@ -350,8 +350,8 @@ uvicorn iscc_search.server.app:app --host 0.0.0.0 --port 8000
 ### Postgres Index (Future)
 
 ```bash
-# Set ISCC_VDB_INDEXES_URI to Postgres connection string
-export ISCC_VDB_INDEXES_URI=postgresql://user:password@localhost/isccdb
+# Set ISCC_SEARCH_INDEXES_URI to Postgres connection string
+export ISCC_SEARCH_INDEXES_URI=postgresql://user:password@localhost/isccdb
 
 # CLI and server work the same way across all backends
 iscc-search create myindex
@@ -361,7 +361,7 @@ uvicorn iscc_search.server.app:app --host 0.0.0.0 --port 8000
 ## Key Benefits
 
 1. **Clean Abstraction**: Protocol-based design enables index swapping without changing frontend code
-2. **Simple Configuration**: Single `ISCC_VDB_INDEXES_URI` variable determines entire deployment topology
+2. **Simple Configuration**: Single `ISCC_SEARCH_INDEXES_URI` variable determines entire deployment topology
 3. **Modular Packages**: Each index implementation is self-contained and independently testable
 4. **Synchronous Simplicity**: No async complexity, straightforward implementation
 5. **Zero Code Duplication**: CLI and API share identical index implementations
@@ -376,7 +376,7 @@ uvicorn iscc_search.server.app:app --host 0.0.0.0 --port 8000
 ### Phase 1: Foundation ✓ **COMPLETED**
 
 - Protocol definition (`IsccIndexProtocol`)
-- Settings and configuration (`VdbSettings`, `get_index()`)
+- Settings and configuration (`SearchSettings`, `get_index()`)
 - Schema models from OpenAPI specification
 - Index factory with URI parsing
 
diff --git a/docs/spec.md b/docs/spec.md
@@ -1,4 +1,4 @@
-# ISCC-VDB Spec - Draft
+# ISCC-Search Spec - Draft
 
 A Scalable Nearest Neighbor Search Multi-Index for the International Standard Content Code (ISCC)
 
@@ -41,7 +41,7 @@ The ISCC Framework consist of a collection of python libraries and applications
 
 **Helpful Note**: These repositories are all available on deepwiki
 
-## ISCC-VDB Features
+## ISCC-Search Features
 
 - ISCC-CODEs or extended ISCC-UNITs as bit-vectors for fast similarity search
 - Distance Metric: Normalized Prefix Hamming Distance (NPHD)
diff --git a/iscc_search/__init__.py b/iscc_search/__init__.py
@@ -8,9 +8,9 @@
 __version__ = metadata.version(__package_name__)
 dirs = PlatformDirs(appname=__package_name__, appauthor=__author__)
 
-from iscc_search.settings import VdbSettings, vdb_settings  # noqa: E402
+from iscc_search.settings import SearchSettings, search_settings  # noqa: E402
 from iscc_search.nphd import NphdIndex  # noqa: E402
 from iscc_search.unit import UnitIndex  # noqa: E402
 from iscc_search.instance import InstanceIndex  # noqa: E402
 
-__all__ = ["NphdIndex", "UnitIndex", "InstanceIndex", "VdbSettings", "vdb_settings"]
+__all__ = ["NphdIndex", "UnitIndex", "InstanceIndex", "SearchSettings", "search_settings"]
diff --git a/iscc_search/openapi/openapi.yaml b/iscc_search/openapi/openapi.yaml
@@ -1,6 +1,6 @@
 openapi: 3.1.0
 info:
-  title: ISCC-VDB API
+  title: ISCC-Search API
   description: A Scalable Nearest Neighbor Search Multi-Index for the International Standard Content Code (ISCC)
   version: 0.1.0
 servers:
diff --git a/iscc_search/server/__init__.py b/iscc_search/server/__init__.py
@@ -1,4 +1,4 @@
-"""FastAPI server for ISCC-VDB API."""
+"""FastAPI server for ISCC-Search API."""
 
 import typing  # noqa: F401
 from contextlib import asynccontextmanager
@@ -45,7 +45,7 @@ def get_index_from_state(request: Request):
 # Create FastAPI app instance with lifespan management
 app = FastAPI(
     lifespan=lifespan,
-    title="ISCC-VDB API",
+    title="ISCC-Search API",
     description="A Scalable Nearest Neighbor Search Multi-Index for the International Standard Content Code (ISCC)",
     version="0.1.0",
     docs_url=None,  # Disable default docs
diff --git a/iscc_search/server/__main__.py b/iscc_search/server/__main__.py
@@ -1,12 +1,12 @@
-"""Entry point for running ISCC-VDB server as a module."""
+"""Entry point for running ISCC-Search server as a module."""
 
 import uvicorn
 
 
 def main():
     # type: () -> None
     """
-    Start the ISCC-VDB API server.
+    Start the ISCC-Search API server.
 
     Runs uvicorn server with hot reload enabled in development mode.
     """
diff --git a/iscc_search/server/assets.py b/iscc_search/server/assets.py
@@ -1,4 +1,4 @@
-"""Asset management endpoints for ISCC-VDB API."""
+"""Asset management endpoints for ISCC-Search API."""
 
 from fastapi import APIRouter, Depends, HTTPException, status
 from iscc_search.protocol import IsccIndexProtocol
diff --git a/iscc_search/server/indexes.py b/iscc_search/server/indexes.py
@@ -1,4 +1,4 @@
-"""Index management endpoints for ISCC-VDB API."""
+"""Index management endpoints for ISCC-Search API."""
 
 from fastapi import APIRouter, Depends, HTTPException, status
 from iscc_search.protocol import IsccIndexProtocol
diff --git a/iscc_search/server/search.py b/iscc_search/server/search.py
@@ -1,4 +1,4 @@
-"""Search endpoints for ISCC-VDB API."""
+"""Search endpoints for ISCC-Search API."""
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from iscc_search.protocol import IsccIndexProtocol
diff --git a/iscc_search/settings.py b/iscc_search/settings.py
@@ -1,8 +1,8 @@
 """
-Settings management for ISCC-VDB.
+Settings management for ISCC-Search.
 
 Provides configuration management using Pydantic settings with support for:
-- Environment variables with ISCC_VDB_ prefix
+- Environment variables with ISCC_SEARCH_ prefix
 - .env file loading
 - Runtime settings override
 - Type validation and defaults
@@ -15,18 +15,18 @@
 
 
 __all__ = [
-    "VdbSettings",
-    "vdb_settings",
+    "SearchSettings",
+    "search_settings",
     "get_index",
 ]
 
 
-class VdbSettings(BaseSettings):
+class SearchSettings(BaseSettings):
     """
-    Application settings for ISCC-VDB.
+    Application settings for ISCC-Search.
 
     Settings can be configured via:
-    - Environment variables (prefixed with ISCC_VDB_)
+    - Environment variables (prefixed with ISCC_SEARCH_)
     - .env file in the working directory
     - Direct instantiation with parameters
     - Runtime override using the override() method
@@ -41,20 +41,20 @@ class VdbSettings(BaseSettings):
     )
 
     model_config = SettingsConfigDict(
-        env_prefix="ISCC_VDB_",
+        env_prefix="ISCC_SEARCH_",
         env_file_encoding="utf-8",
         case_sensitive=True,
         extra="ignore",
         validate_assignment=True,
     )
 
     def override(self, update=None):
-        # type: (dict|None) -> VdbSettings
+        # type: (dict|None) -> SearchSettings
         """
         Returns an updated and validated deep copy of the current settings instance.
 
         :param update: Dictionary of field names and values to override.
-        :return: New VdbSettings instance with updated and validated fields.
+        :return: New SearchSettings instance with updated and validated fields.
         """
 
         update = update or {}  # sets {} if update is None
@@ -66,7 +66,7 @@ def override(self, update=None):
         return settings
 
 
-vdb_settings = VdbSettings()
+search_settings = SearchSettings()
 
 
 def get_index():
@@ -88,7 +88,7 @@ def get_index():
     from iscc_search.protocol import IsccIndexProtocol  # noqa: F401
     import os
 
-    uri = vdb_settings.indexes_uri
+    uri = search_settings.indexes_uri
 
     # Handle memory:// scheme
     if uri == "memory://" or uri.startswith("memory://"):
@@ -116,7 +116,7 @@ def get_index():
     # Reject unsupported URI schemes to prevent silent data loss
     supported = ["memory://", "file path", "file://"]
     raise ValueError(
-        f"Unsupported ISCC_VDB_INDEXES_URI: '{uri}'. "
+        f"Unsupported ISCC_SEARCH_INDEXES_URI: '{uri}'. "
         f"Currently supported schemes: {', '.join(supported)}. "
         f"PostgreSQL URIs are not yet implemented."
     )
diff --git a/tests/test_indexes_lmdb_integration.py b/tests/test_indexes_lmdb_integration.py
@@ -8,7 +8,7 @@
 import iscc_core as ic
 from iscc_search.schema import IsccAsset, IsccIndex
 from iscc_search.indexes.lmdb import LmdbIndexManager
-from iscc_search.settings import VdbSettings, get_index
+from iscc_search.settings import SearchSettings, get_index
 
 
 @pytest.fixture
@@ -158,13 +158,13 @@ def test_update_asset_metadata(manager, sample_iscc_ids, sample_content_units):
 def test_settings_integration_file_path(tmp_path):
     """Test get_index() factory with file path in settings."""
     # Set indexes_uri to file path
-    settings = VdbSettings(indexes_uri=str(tmp_path))
+    settings = SearchSettings(indexes_uri=str(tmp_path))
 
     # Override global settings (for this test)
     import iscc_search.settings
 
-    original_settings = iscc_search.settings.vdb_settings
-    iscc_search.settings.vdb_settings = settings
+    original_settings = iscc_search.settings.search_settings
+    iscc_search.settings.search_settings = settings
 
     try:
         # Get index via factory
@@ -177,7 +177,7 @@ def test_settings_integration_file_path(tmp_path):
         idx.close()
     finally:
         # Restore original settings
-        iscc_search.settings.vdb_settings = original_settings
+        iscc_search.settings.search_settings = original_settings
 
 
 def test_persistence_across_manager_instances(tmp_path, sample_assets):
diff --git a/tests/test_server.py b/tests/test_server.py
diff --git a/tests/test_settings.py b/tests/test_settings.py
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -11,8 +11,8 @@`
`11`	`11`	`>`
`12`	`12`	`> The API and features are subject to significant changes. Use at your own risk.`
`13`	`13`
`14`		`-High-performance ISCC similarity search engine for variable-length binary [ISCC](https://iscc.codes) codes with fast`
`15`		`-approximate nearest neighbor search.`
	`14`	`+High-performance ISCC similarity search engine for variable-length binary [ISCC](https://iscc.codes) codes with`
	`15`	`+fast approximate nearest neighbor search.`
`16`	`16`
`17`	`17`	`- Github repository: <https://github.com/iscc/iscc-search/>`
`18`	`18`	`- Documentation <https://search.iscc.codes/>`