Refine index configuration validation and typed helpers (#173)

## Summary
- add typed HNSW/fulltext configuration helpers and export them from
package entry points
- enforce stricter parameter validation and normalization for
dense/sparse/fulltext index configs while preserving forward-compatible
pass-through for unknown analyzers/properties
- update vector index SQL generation to honor configured `type`/`lib`
and extend unit tests for new defaults and validation behavior

## Test plan
- [x] `PYTHONPATH=src pytest tests/unit_tests/test_configuration.py
tests/unit_tests/test_sparse_vector_index_config.py`
- [ ] Run full unit/integration suite in CI

Made with [Cursor](https://cursor.com)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added specialized fulltext configs (IK, SPACE, BENG, NGRAM, NGRAM2)
and BQ/SQ variants for HNSW vector indexes.

* **Improvements**
* Stronger validation, normalization and safer defaults for index and
sparse-vector configs (updated prune/refine/drop/refine_k defaults).
* HNSW config now exposes configurable type/lib and uses those values in
index generation.

* **Breaking Changes**
* Top-level export for the embedded client removed — import the client
from the client module instead.

* **Chores**
  * Excluded a specific numpy release in dependency constraints.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: hnwyllmm

.github/workflows/ci.yml

@@ -100,7 +100,7 @@ jobs:
           fi
           set -o pipefail
           uv run pytest tests/integration_tests/ -v --log-cli-level=${log_level} -k "not server and not embedded and not oceanbase" | tee pytest.log
-          tail -n 1 pytest.log | grep '=======' | grep 'passed' | grep -q 'failed' && exit 1 || exit 0
+          tail -n 1 pytest.log | grep '=======' | grep 'passed' |grep -q 'failed' && exit 1 || exit 0
 
   integration-test:
     runs-on: ubuntu-latest

pyproject.toml

@@ -18,7 +18,7 @@ dependencies = [
     "tqdm; python_version < \"3.14\"",
     "sentence-transformers; python_version >= \"3.14\"",
     "tenacity",
-    "numpy>=1.26",
+    "numpy>=1.26,!=2.4.0",
 ]
 
 [project.urls]

src/pyseekdb/__init__.py

@@ -71,6 +71,8 @@
     AdminClient,
     BaseClient,
     BaseConnection,
+    BengFulltextIndexConfig,
+    BqHNSWConfiguration,
     Client,
     ClientAPI,
     Configuration,
@@ -79,14 +81,19 @@
     EmbeddingFunction,
     FulltextIndexConfig,
     HNSWConfiguration,
+    IKFulltextIndexConfig,
+    IKMode,
     K,
+    Ngram2FulltextIndexConfig,
+    NgramFulltextIndexConfig,
     RemoteServerClient,
     Schema,
-    SeekdbEmbeddedClient,
+    SpaceFulltextIndexConfig,
     SparseEmbeddingFunction,
     SparseEmbeddingFunctionRegistry,
     SparseVector,
     SparseVectorIndexConfig,
+    SqHNSWConfiguration,
     VectorIndexConfig,
     Version,
     get_default_embedding_function,
@@ -107,6 +114,8 @@
     "AdminClient",
     "BaseClient",
     "BaseConnection",
+    "BengFulltextIndexConfig",
+    "BqHNSWConfiguration",
     "Client",
     "ClientAPI",
     "Collection",
@@ -116,14 +125,19 @@
     "EmbeddingFunction",
     "FulltextIndexConfig",
     "HNSWConfiguration",
+    "IKFulltextIndexConfig",
+    "IKMode",
     "K",
+    "Ngram2FulltextIndexConfig",
+    "NgramFulltextIndexConfig",
     "RemoteServerClient",
     "Schema",
-    "SeekdbEmbeddedClient",
+    "SpaceFulltextIndexConfig",
     "SparseEmbeddingFunction",
     "SparseEmbeddingFunctionRegistry",
     "SparseVector",
     "SparseVectorIndexConfig",
+    "SqHNSWConfiguration",
     "VectorIndexConfig",
     "Version",
     "get_default_embedding_function",

src/pyseekdb/client/__init__.py

@@ -18,18 +18,25 @@
 
 import logging
 import os
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from .admin_client import AdminAPI, _AdminClientProxy, _ClientProxy
 from .base_connection import BaseConnection
 from .client_base import BaseClient, ClientAPI
-from .client_seekdb_embedded import SeekdbEmbeddedClient
 from .client_seekdb_server import RemoteServerClient
 from .configuration import (
+    BengFulltextIndexConfig,
+    BqHNSWConfiguration,
     Configuration,
     FulltextIndexConfig,
     HNSWConfiguration,
+    IKFulltextIndexConfig,
+    IKMode,
+    Ngram2FulltextIndexConfig,
+    NgramFulltextIndexConfig,
+    SpaceFulltextIndexConfig,
     SparseVectorIndexConfig,
+    SqHNSWConfiguration,
     VectorIndexConfig,
 )
 from .database import Database
@@ -49,6 +56,9 @@
 from .types import K
 from .version import Version
 
+if TYPE_CHECKING:
+    from .client_seekdb_embedded import SeekdbEmbeddedClient
+
 logger = logging.getLogger(__name__)
 
 
@@ -81,6 +91,8 @@ def _create_server_client(
     if/else by sharing this helper between Client() and AdminClient().
     """
     if path is not None:
+        from .client_seekdb_embedded import SeekdbEmbeddedClient
+
         if is_admin:
             logger.debug(f"Creating embedded admin client: path={path}")
         else:
@@ -111,6 +123,8 @@ def _create_server_client(
     from .client_seekdb_embedded import _PYLIBSEEKDB_AVAILABLE
 
     if _PYLIBSEEKDB_AVAILABLE:
+        from .client_seekdb_embedded import SeekdbEmbeddedClient
+
         default_path = _default_seekdb_path()
         if is_admin:
             logger.debug(f"Creating embedded admin client (default): path={default_path}")
@@ -124,11 +138,27 @@ def _create_server_client(
     )
 
 
+def __getattr__(name: str) -> Any:
+    """
+    Lazily expose optional embedded client symbols.
+
+    This avoids importing pylibseekdb during `import pyseekdb`, which can crash
+    on unsupported interpreter/platform combinations (e.g. some Python 3.14 CI environments).
+    """
+    if name == "SeekdbEmbeddedClient":
+        from .client_seekdb_embedded import SeekdbEmbeddedClient
+
+        return SeekdbEmbeddedClient
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
 __all__ = [
     "AdminAPI",
     "AdminClient",
     "BaseClient",
     "BaseConnection",
+    "BengFulltextIndexConfig",
+    "BqHNSWConfiguration",
     "Client",
     "ClientAPI",
     "Configuration",
@@ -137,14 +167,20 @@ def _create_server_client(
     "EmbeddingFunction",
     "FulltextIndexConfig",
     "HNSWConfiguration",
+    "IKFulltextIndexConfig",
+    "IKMode",
     "K",
+    "Ngram2FulltextIndexConfig",
+    "NgramFulltextIndexConfig",
     "RemoteServerClient",
     "Schema",
     "SeekdbEmbeddedClient",
+    "SpaceFulltextIndexConfig",
     "SparseEmbeddingFunction",
     "SparseEmbeddingFunctionRegistry",
     "SparseVector",
     "SparseVectorIndexConfig",
+    "SqHNSWConfiguration",
     "VectorIndexConfig",
     "Version",
     "get_default_embedding_function",

src/pyseekdb/client/client_base.py

@@ -175,7 +175,7 @@ def _get_vector_index_sql(hnsw_config: HNSWConfiguration) -> str:
             property_parts.append(f"{k}={v}")
     property_str = ", ".join(property_parts)
     properties_str = f", {property_str}" if property_str else ""
-    return f"WITH (DISTANCE={hnsw_config.distance}, TYPE=hnsw, LIB=vsag{properties_str})"
+    return f"WITH (DISTANCE={hnsw_config.distance}, TYPE={hnsw_config.type}, LIB={hnsw_config.lib}{properties_str})"
 
 
 def _get_sparse_vector_index_sql(sparse_config: SparseVectorIndexConfig) -> str: