refactor: standardize logging and exception handling

- Add Logger class with configurable LOG_LEVEL setting
- Replace all module loggers with Logger class
- Use specific exceptions from exceptions.py instead of generic ValueError/Exception
- Replace os.getenv with direct api_settings access
- Update all adapters (astradb, chroma, milvus, pgvector) with consistent patterns

Author: markdownpipe

README.md

@@ -104,8 +104,8 @@ from crossvector.dbs.astradb import AstraDBAdapter
 
 # Initialize engine
 engine = VectorEngine(
-    embedding_adapter=OpenAIEmbeddingAdapter(model_name="text-embedding-3-small"),
-    db_adapter=AstraDBAdapter(),
+    db=AstraDBAdapter(),
+    embedding=OpenAIEmbeddingAdapter(model_name="text-embedding-3-small"),
     collection_name="my_documents",
     store_text=True  # Optional: Set to False to not store original text
 )
@@ -121,9 +121,9 @@ print(f"Inserted {len(docs)} documents")
 # Alternative: Upsert with VectorDocument (if you have embeddings already)
 vector_docs = [
     VectorDocument(
-        id="doc3", 
-        text="Python programming", 
-        vector=[0.1]*1536, 
+        id="doc3",
+        text="Python programming",
+        vector=[0.1]*1536,
         metadata={"category": "tech"}
     )
 ]
@@ -269,14 +269,14 @@ from typing import Any, Dict, List, Set, Optional, Union, Sequence, Tuple
 
 class MyCustomDBAdapter(VectorDBAdapter):
     """Custom vector database adapter implementation."""
-    
+
     # Optional: Set to True if your database uses '$vector' instead of 'vector'
     use_dollar_vector: bool = False
-    
+
     def initialize(
-        self, 
-        collection_name: str, 
-        embedding_dimension: int, 
+        self,
+        collection_name: str,
+        embedding_dimension: int,
         metric: str = "cosine",
         **kwargs: Any
     ) -> None:
@@ -285,9 +285,9 @@ class MyCustomDBAdapter(VectorDBAdapter):
         pass
 
     def add_collection(
-        self, 
-        collection_name: str, 
-        embedding_dimension: int, 
+        self,
+        collection_name: str,
+        embedding_dimension: int,
         metric: str = "cosine"
     ) -> Any:
         """Create a new collection."""
@@ -300,9 +300,9 @@ class MyCustomDBAdapter(VectorDBAdapter):
         pass
 
     def get_or_create_collection(
-        self, 
-        collection_name: str, 
-        embedding_dimension: int, 
+        self,
+        collection_name: str,
+        embedding_dimension: int,
         metric: str = "cosine"
     ) -> Any:
         """Get existing collection or create if doesn't exist."""
@@ -343,15 +343,8 @@ class MyCustomDBAdapter(VectorDBAdapter):
         # Should return VectorDocument instance
         pass
 
-    def get_or_create(
-        self, 
-        defaults: Optional[Dict[str, Any]] = None, 
-        **kwargs
-    ) -> Tuple[VectorDocument, bool]:
-        """Get document by pk or create if not found."""
-        # Your implementation
-        # Should return (VectorDocument, created: bool)
-        pass
+    # NOTE: get_or_create has been centralized in VectorEngine.
+    # Adapters no longer implement this to avoid duplicated logic.
 
     def create(self, **kwargs: Any) -> VectorDocument:
         """Create and persist a single document."""
@@ -384,16 +377,8 @@ class MyCustomDBAdapter(VectorDBAdapter):
         # Should return updated VectorDocument instance
         pass
 
-    def update_or_create(
-        self,
-        defaults: Optional[Dict[str, Any]] = None,
-        create_defaults: Optional[Dict[str, Any]] = None,
-        **kwargs
-    ) -> Tuple[VectorDocument, bool]:
-        """Update document if exists, otherwise create."""
-        # Your implementation
-        # Should return (VectorDocument, created: bool)
-        pass
+    # NOTE: update_or_create has been centralized in VectorEngine.
+    # Adapters no longer implement this to avoid duplicated logic.
 
     def bulk_update(
         self,
@@ -408,8 +393,8 @@ class MyCustomDBAdapter(VectorDBAdapter):
         pass
 
     def upsert(
-        self, 
-        documents: List[VectorDocument], 
+        self,
+        documents: List[VectorDocument],
         batch_size: int = None
     ) -> List[VectorDocument]:
         """Insert new documents or update existing ones."""
@@ -668,8 +653,8 @@ from crossvector.embeddings.openai import OpenAIEmbeddingAdapter
 from crossvector.dbs.pgvector import PGVectorAdapter
 
 engine = VectorEngine(
-    embedding_adapter=OpenAIEmbeddingAdapter(),
-    db_adapter=PGVectorAdapter(),
+    db=PGVectorAdapter(),
+    embedding=OpenAIEmbeddingAdapter(),
     collection_name="docs",
     store_text=True
 )

docs/adapters/databases.md

@@ -68,13 +68,13 @@ from typing import Any, Dict, List, Set, Optional, Union, Sequence, Tuple
 
 class MyCustomDBAdapter(VectorDBAdapter):
     """Custom vector database adapter implementation."""
-    
+
     use_dollar_vector: bool = False  # Set to True if your DB uses '$vector'
-    
+
     def initialize(
-        self, 
-        collection_name: str, 
-        embedding_dimension: int, 
+        self,
+        collection_name: str,
+        embedding_dimension: int,
         metric: str = "cosine",
         **kwargs: Any
     ) -> None:
@@ -99,8 +99,8 @@ class MyCustomDBAdapter(VectorDBAdapter):
         pass
 
     def upsert(
-        self, 
-        documents: List[VectorDocument], 
+        self,
+        documents: List[VectorDocument],
         batch_size: int = None
     ) -> List[VectorDocument]:
         """Insert new documents or update existing ones."""

docs/configuration.md

@@ -88,8 +88,8 @@ If you're only using embeddings for search and don't need to retrieve the origin
 from crossvector import VectorEngine
 
 engine = VectorEngine(
-    embedding_adapter=...,
-    db_adapter=...,
+    embedding=...,
+    db=...,
     collection_name="my_docs",
     store_text=False  # Don't store text, only embeddings and metadata
 )

docs/quickstart.md

@@ -7,8 +7,8 @@ from crossvector.dbs.astradb import AstraDBAdapter
 
 # Initialize engine
 engine = VectorEngine(
-    embedding_adapter=OpenAIEmbeddingAdapter(model_name="text-embedding-3-small"),
-    db_adapter=AstraDBAdapter(),
+    embedding=OpenAIEmbeddingAdapter(model_name="text-embedding-3-small"),
+    db=AstraDBAdapter(),
     collection_name="my_documents",
     store_text=True  # Optional: Set to False to save space
 )

docs/schema.md

@@ -13,7 +13,7 @@ from crossvector import VectorDocument
 
 # Without ID - auto-generated based on PRIMARY_KEY_MODE
 doc = VectorDocument(text="Hello world")
-print(doc.id)  
+print(doc.id)
 # Possible values depending on PRIMARY_KEY_MODE:
 # - 'uuid' (default): Random UUID like "a1b2c3d4e5f6..."
 # - 'hash_text': SHA256 hash of text like "a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e"

scripts/tests/test_integration.py

@@ -7,7 +7,7 @@
 
 from dotenv import load_dotenv
 
-from crossvector import VectorDocument, VectorEngine
+from crossvector import VectorEngine
 from crossvector.dbs.astradb import AstraDBAdapter
 from crossvector.dbs.chroma import ChromaDBAdapter
 from crossvector.dbs.milvus import MilvusDBAdapter
@@ -32,13 +32,13 @@
 test_pks = ["doc1", "doc2", "doc3"]
 
 
-def test_engine(db_name: str, db_adapter, embedding_adapter, collection_name: str):
+def test_engine(db_name: str, db, embedding, collection_name: str):
     """Test VectorEngine with a specific database adapter."""
     print(f"\n{'=' * 80}")
-    print(f"Testing {db_name} with {embedding_adapter.model_name}")
+    print(f"Testing {db_name} with {embedding.model_name}")
     print(f"{'=' * 80}")
 
-    engine = VectorEngine(embedding_adapter=embedding_adapter, db_adapter=db_adapter, collection_name=collection_name)
+    engine = VectorEngine(embedding=embedding, db=db, collection_name=collection_name)
 
     # Clean up existing data (if collection exists, drop it)
     try:
@@ -49,11 +49,12 @@ def test_engine(db_name: str, db_adapter, embedding_adapter, collection_name: st
         print(f"Note: Could not drop collection (may not exist): {e}")
 
     # Re-initialize after dropping
-    engine = VectorEngine(embedding_adapter=embedding_adapter, db_adapter=db_adapter, collection_name=collection_name)
+    engine = VectorEngine(embedding=embedding, db=db, collection_name=collection_name)
 
-    # Test 1: Upsert VectorDocuments from texts (with auto-embedding)
-    print("\n1. Testing upsert_from_texts...")
-    result = engine.upsert_from_texts(texts=test_texts, metadatas=test_metadatas, pks=test_pks)
+    # Test 1: Upsert VectorDocuments (with auto-embedding)
+    print("\n1. Testing upsert...")
+    docs = [{"id": test_pks[i], "text": test_texts[i], "metadata": test_metadatas[i]} for i in range(len(test_texts))]
+    result = engine.upsert(docs)
     print(f"Inserted {len(result)} VectorDocuments")
 
     # Test 2: Count VectorDocuments

src/crossvector/__init__.py

@@ -6,6 +6,7 @@
 from .abc import EmbeddingAdapter, VectorDBAdapter
 from .engine import VectorEngine
 from .schema import VectorDocument
+from .types import Doc, DocId, DocIds
 
 __version__ = "0.1.1"
 
@@ -14,4 +15,7 @@
     "EmbeddingAdapter",
     "VectorDBAdapter",
     "VectorDocument",
+    "Doc",
+    "DocId",
+    "DocIds",
 ]