vectorwave 0.2.6__tar.gz → 0.2.8__tar.gz

vectorwave-0.2.8/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: vectorwave
+Version: 0.2.8
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Requires-Dist: weaviate-client>=4.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: sentence-transformers
+Requires-Dist: requests
+Requires-Dist: openai
+License-File: LICENSE
+License-File: NOTICE
+Summary: VectorWave: Seamless Auto-Vectorization Framework
+Author-email: junyeonggim <junyeonggim5@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/cozymori/vectorwave
+
+Need more information? Visit [here](https://cozymori.github.io/vectorwave-docs/)
+
+# VectorWave
+![Star](https://badgen.net/github/stars/cozymori/vectorwave)
+![Release](https://badgen.net/github/release/cozymori/vectorwave)
+![Tag](https://badgen.net/github/tag/cozymori/vectorwave)
+![Commit](https://badgen.net/github/last-commit/cozymori/vectorwave)
+![Contributors](https://badgen.net/github/contributors/cozymori/vectorwave)
+![OpenPrs](https://badgen.net/github/open-prs/cozymori/vectorwave)
+![MergedPrs](https://badgen.net/github/merged-prs/cozymori/vectorwave)
+![Checks](https://badgen.net/github/checks/cozymori/vectorwave)
+![Pypi](https://badgen.net/pypi/v/vectorwave)
+<br>**Seamless Auto-Vectorization Framework**
+
+We transform volatile data that disappears the moment code is executed into a Searchable and Reusable permanent knowledge asset.
+
+### Requirements
+
+* **Python**: 3.10 ~ 3.13
+* **Docker**: Required to run the Weaviate database.
+* (Optional) **OpenAI API Key**: Required for AI auto-documentation and high-performance embedding.
+
+### How to reach us
+
+Have questions or found a bug? Please join our community.
+
+* **GitHub Issues**: [https://github.com/cozymori/vectorwave/issues](https://github.com/cozymori/vectorwave/issues)
+
+### Contributors
+[See the contributors of vectorwave](https://github.com/Cozymori/VectorWave/graphs/contributors)<br>
+VectorWave is an open-source project and we welcome your contributions.
+Please refer to [CONTRIBUTING.md](https://www.google.com/search?q=https://github.com/cozymori/vectorwave/blob/main/CONTRIBUTING.md) in the GitHub repository.
+
+

vectorwave-0.2.8/Readme.md

@@ -0,0 +1,33 @@
+Need more information? Visit [here](https://cozymori.github.io/vectorwave-docs/)
+
+# VectorWave
+![Star](https://badgen.net/github/stars/cozymori/vectorwave)
+![Release](https://badgen.net/github/release/cozymori/vectorwave)
+![Tag](https://badgen.net/github/tag/cozymori/vectorwave)
+![Commit](https://badgen.net/github/last-commit/cozymori/vectorwave)
+![Contributors](https://badgen.net/github/contributors/cozymori/vectorwave)
+![OpenPrs](https://badgen.net/github/open-prs/cozymori/vectorwave)
+![MergedPrs](https://badgen.net/github/merged-prs/cozymori/vectorwave)
+![Checks](https://badgen.net/github/checks/cozymori/vectorwave)
+![Pypi](https://badgen.net/pypi/v/vectorwave)
+<br>**Seamless Auto-Vectorization Framework**
+
+We transform volatile data that disappears the moment code is executed into a Searchable and Reusable permanent knowledge asset.
+
+### Requirements
+
+* **Python**: 3.10 ~ 3.13
+* **Docker**: Required to run the Weaviate database.
+* (Optional) **OpenAI API Key**: Required for AI auto-documentation and high-performance embedding.
+
+### How to reach us
+
+Have questions or found a bug? Please join our community.
+
+* **GitHub Issues**: [https://github.com/cozymori/vectorwave/issues](https://github.com/cozymori/vectorwave/issues)
+
+### Contributors
+[See the contributors of vectorwave](https://github.com/Cozymori/VectorWave/graphs/contributors)<br>
+VectorWave is an open-source project and we welcome your contributions.
+Please refer to [CONTRIBUTING.md](https://www.google.com/search?q=https://github.com/cozymori/vectorwave/blob/main/CONTRIBUTING.md) in the GitHub repository.
+

vectorwave-0.2.8/crates/src/lib.rs

@@ -0,0 +1,171 @@
+use pyo3::prelude::*;
+use pyo3::types::{PyDict, PyList, PyString, PyBool, PyFloat, PyInt};
+use std::collections::HashSet;
+use std::thread;
+use std::time::{Duration, Instant};
+use std::sync::Mutex;
+use crossbeam_channel::{bounded, Receiver, Sender, TrySendError};
+
+struct LogItem {
+    collection: PyObject,
+    properties: Py<PyDict>,
+    uuid: Option<PyObject>,
+    vector: Option<Vec<f32>>,
+}
+
+#[pyclass]
+struct RustBatchManager {
+    sender: Sender<LogItem>,
+    #[allow(dead_code)]
+    flush_callback: PyObject,
+    worker_handle: Mutex<Option<thread::JoinHandle<()>>>,
+    stop_signal: Sender<()>,
+}
+
+#[pymethods]
+impl RustBatchManager {
+    #[new]
+    fn new(
+        py: Python<'_>,
+        callback: PyObject,
+        batch_threshold: usize,
+        flush_interval_ms: u64,
+    ) -> Self {
+        let (tx, rx) = bounded::<LogItem>(10000);
+        let (stop_tx, stop_rx) = bounded(1);
+        let worker_callback = callback.clone_ref(py);
+
+        let handle = thread::spawn(move || {
+            Self::worker_loop(rx, stop_rx, worker_callback, batch_threshold, flush_interval_ms);
+        });
+
+        RustBatchManager {
+            sender: tx,
+            flush_callback: callback,
+            worker_handle: Mutex::new(Some(handle)),
+            stop_signal: stop_tx,
+        }
+    }
+
+    #[pyo3(signature = (collection, properties, uuid=None, vector=None))]
+    fn add_object(&self, collection: PyObject, properties: Py<PyDict>, uuid: Option<PyObject>, vector: Option<Vec<f32>>) {
+        let item = LogItem { collection, properties, uuid, vector };
+        let _ = self.sender.try_send(item);
+    }
+
+    fn shutdown(&self, py: Python<'_>) {
+        let _ = self.stop_signal.send(());
+        py.allow_threads(|| {
+            if let Ok(mut handle_guard) = self.worker_handle.lock() {
+                if let Some(handle) = handle_guard.take() {
+                    let _ = handle.join();
+                }
+            }
+        });
+    }
+}
+
+impl RustBatchManager {
+    fn worker_loop(rx: Receiver<LogItem>, stop_rx: Receiver<()>, callback: PyObject, threshold: usize, interval_ms: u64) {
+            let mut buffer = Vec::with_capacity(threshold);
+            let mut last_flush = Instant::now();
+            let flush_interval = Duration::from_millis(interval_ms);
+
+            loop {
+                crossbeam_channel::select! {
+                    recv(stop_rx) -> msg => {
+                        break;
+                    }
+                    recv(rx) -> msg => {
+                        match msg {
+                            Ok(item) => buffer.push(item),
+                            Err(_) => break,
+                        }
+                    }
+                    default(Duration::from_millis(100)) => {}
+                }
+
+
+                if stop_rx.is_empty() && (buffer.len() >= threshold || (last_flush.elapsed() >= flush_interval && !buffer.is_empty())) {
+
+                     let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+                        Self::flush_buffer(&buffer, &callback);
+                    }));
+                    buffer.clear();
+                    last_flush = Instant::now();
+                }
+            }
+        }
+
+    fn flush_buffer(buffer: &Vec<LogItem>, callback: &PyObject) {
+        Python::with_gil(|py| {
+            let py_list = PyList::empty(py);
+
+            for item in buffer {
+                let dict = PyDict::new(py);
+                let mut set_field = |key: &str, val: PyObject| -> bool {
+                    if let Err(_) = dict.set_item(key, val) { return false; }
+                    true
+                };
+
+                if !set_field("collection", item.collection.clone_ref(py)) { continue; }
+                if !set_field("properties", item.properties.to_object(py)) { continue; }
+                let uuid_val = item.uuid.as_ref().map_or(py.None(), |u| u.clone_ref(py));
+                if !set_field("uuid", uuid_val) { continue; }
+                let vector_val = item.vector.as_ref().map_or(py.None(), |v| v.to_object(py));
+                if !set_field("vector", vector_val) { continue; }
+
+                if let Err(e) = py_list.append(dict) {
+                     eprintln!("[RustCore] ⚠️ Failed to append item: {}", e);
+                }
+            }
+
+            if let Err(e) = callback.call1(py, (py_list,)) {
+                eprintln!("[RustCore] ⚠️ Flush failed: {}", e);
+            }
+        });
+    }
+}
+
+fn process_recursive(py: Python, value: &Bound<'_, PyAny>, sensitive_set: &HashSet<String>) -> PyResult<PyObject> {
+    if let Ok(dict_obj) = value.downcast::<PyDict>() {
+        let new_dict = PyDict::new(py);
+        for (k, v) in dict_obj {
+            let k_str = k.to_string().to_lowercase();
+            if sensitive_set.contains(&k_str) {
+                new_dict.set_item(k, "[MASKED]")?;
+            } else {
+                new_dict.set_item(k, process_recursive(py, &v, sensitive_set)?)?;
+            }
+        }
+        Ok(new_dict.into())
+    } else if let Ok(list_obj) = value.downcast::<PyList>() {
+        let new_list = PyList::empty(py);
+        for item in list_obj {
+            new_list.append(process_recursive(py, &item, sensitive_set)?)?;
+        }
+        Ok(new_list.into())
+    } else {
+        if value.is_none() || value.is_instance_of::<PyBool>() || value.is_instance_of::<PyFloat>() || value.is_instance_of::<PyInt>() || value.is_instance_of::<PyString>() {
+            Ok(value.clone().unbind())
+        } else {
+            match value.str() {
+                Ok(s) => Ok(s.into()),
+                Err(_) => Ok(PyString::new(py, "[SERIALIZATION_ERROR]").into())
+            }
+        }
+    }
+}
+
+#[pyfunction]
+fn mask_and_serialize(py: Python, data: &Bound<'_, PyAny>, sensitive_keys: Vec<String>) -> PyResult<PyObject> {
+    let sensitive_set: HashSet<String> = sensitive_keys.into_iter().map(|s| s.to_lowercase()).collect();
+    process_recursive(py, data, &sensitive_set)
+}
+
+#[pymodule]
+fn vectorwave_core(m: &Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<RustBatchManager>()?;
+    m.add_function(wrap_pyfunction!(mask_and_serialize, m)?)?;
+    Ok(())
+}

{vectorwave-0.2.6 → vectorwave-0.2.8}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "maturin"
 
 [project]
 name = "vectorwave"
-version = "0.2.06"
+version = "0.2.8"
 authors = [
     { name = "junyeonggim", email = "junyeonggim5@gmail.com" },
 ]

{vectorwave-0.2.6 → vectorwave-0.2.8}/src/vectorwave/core/decorator.py

@@ -26,6 +26,9 @@ def vectorize(search_description: Optional[str] = None,
               cache_threshold: float = 0.9,
               replay: bool = False,
               attributes_to_capture: Optional[List[str]] = None,
+              capture_inputs: bool = False,
+              semantic_cache_filters: Optional[Dict[str, Any]] = None,
+              semantic_cache_scope: Optional[List[str]] = None,
               **execution_tags):
     """
     VectorWave Decorator with Auto-Generation support.
@@ -60,6 +63,15 @@ def vectorize(search_description: Optional[str] = None,
                 if attr not in final_attributes:
                     final_attributes.append(attr)
 
+        if capture_inputs:
+            try:
+                sig = inspect.signature(func)
+                for param_name in sig.parameters:
+                    if param_name not in ('self', 'cls') and param_name not in final_attributes:
+                        final_attributes.append(param_name)
+            except Exception as e:
+                logger.warning(f"Failed to inspect signature for auto-capture in '{function_name}': {e}")
+
         if replay:
             try:
                 sig = inspect.signature(func)
@@ -109,7 +121,6 @@ def vectorize(search_description: Optional[str] = None,
                     "static_properties": static_properties
                 })
             else:
-                # [Existing] Immediate Registration Mode
                 current_content_hash = function_cache_manager.calculate_content_hash(func_identifier, static_properties)
 
                 if function_cache_manager.is_cached_and_unchanged(func_uuid, current_content_hash):
@@ -137,6 +148,25 @@ def vectorize(search_description: Optional[str] = None,
         except Exception as e:
             logger.error("Error in @vectorize setup for '%s': %s", func.__name__, e)
 
+        def resolve_semantic_filters(args, kwargs):
+            runtime_filters = semantic_cache_filters.copy() if semantic_cache_filters else {}
+
+            if semantic_cache_scope:
+                try:
+                    sig = inspect.signature(func)
+                    bound_args = sig.bind(*args, **kwargs)
+                    bound_args.apply_defaults()
+
+                    for arg_name in semantic_cache_scope:
+                        if arg_name in bound_args.arguments:
+                            runtime_filters[arg_name] = bound_args.arguments[arg_name]
+                        else:
+                            logger.warning(f"Semantic Scope: Argument '{arg_name}' not found in call to '{function_name}'.")
+                except Exception as e:
+                    logger.error(f"Failed to resolve semantic_cache_scope for '{function_name}': {e}")
+
+            return runtime_filters
+
         # --- Wrapper Logic ---
 
         if is_async_func:
@@ -144,7 +174,6 @@ def vectorize(search_description: Optional[str] = None,
             @trace_span(attributes_to_capture=final_attributes, capture_return_value=capture_return_value)
             @wraps(func)
             async def inner_wrapper(*args, **kwargs):
-                # Remove injected tags from kwargs before calling original func
                 clean_kwargs = {k: v for k, v in kwargs.items() if
                                 k not in valid_execution_tags and k != 'function_uuid' and k != 'exec_source'}
                 return await func(*args, **clean_kwargs)
@@ -152,7 +181,8 @@ def vectorize(search_description: Optional[str] = None,
             @wraps(func)
             async def outer_wrapper(*args, **kwargs):
                 if semantic_cache:
-                    cached = _check_and_return_cached_result(func, args, kwargs, function_name, cache_threshold, True)
+                    filters = resolve_semantic_filters(args, kwargs)
+                    cached = _check_and_return_cached_result(func, args, kwargs, function_name, cache_threshold, True, filters=filters)
                     if cached is not None: return cached
 
                 full_kwargs = kwargs.copy()
@@ -176,7 +206,8 @@ def vectorize(search_description: Optional[str] = None,
             @wraps(func)
             def outer_wrapper(*args, **kwargs):
                 if semantic_cache:
-                    cached = _check_and_return_cached_result(func, args, kwargs, function_name, cache_threshold, False)
+                    filters = resolve_semantic_filters(args, kwargs)
+                    cached = _check_and_return_cached_result(func, args, kwargs, function_name, cache_threshold, False, filters=filters)
                     if cached is not None: return cached
 
                 full_kwargs = kwargs.copy()

vectorwave-0.2.8/src/vectorwave/database/db.py

@@ -0,0 +1,308 @@
+import logging
+from functools import lru_cache
+
+import weaviate
+import weaviate.classes.config as wvc
+from weaviate.classes.config import Tokenization
+from vectorwave.exception.exceptions import (
+    WeaviateConnectionError,
+    WeaviateNotReadyError,
+    SchemaCreationError
+)
+from vectorwave.models.db_config import WeaviateSettings
+from vectorwave.models.db_config import get_weaviate_settings
+from weaviate.config import AdditionalConfig
+from weaviate.exceptions import WeaviateConnectionError as WeaviateClientConnectionError
+
+logger = logging.getLogger(__name__)
+
+
+def get_weaviate_client(settings: WeaviateSettings) -> weaviate.WeaviateClient:
+    try:
+        client = weaviate.connect_to_local(
+            host=settings.WEAVIATE_HOST,
+            port=settings.WEAVIATE_PORT,
+            grpc_port=settings.WEAVIATE_GRPC_PORT,
+            additional_config=AdditionalConfig(
+                dynamic=True,
+                batch_size=20,
+                timeout_retries=3
+            )
+        )
+    except WeaviateClientConnectionError as e:
+        raise WeaviateConnectionError(f"Failed to connect to Weaviate: {e}")
+    except Exception as e:
+        raise WeaviateConnectionError(f"An unknown error occurred while connecting to Weaviate: {e}")
+
+    if not client.is_ready():
+        raise WeaviateNotReadyError("Connected to Weaviate, but the server is not ready.")
+
+    logger.info("Weaviate client connected successfully")
+    return client
+
+
+@lru_cache()
+def get_cached_client() -> weaviate.WeaviateClient:
+    logger.debug("Creating and caching new Weaviate client instance")
+    settings = get_weaviate_settings()
+    client = get_weaviate_client(settings)
+    return client
+
+
+def _create_property_from_config(name: str, prop_details: dict) -> wvc.Property:
+    dtype_str = prop_details.get("data_type")
+    if not dtype_str:
+        raise ValueError(f"Property '{name}' missing 'data_type'")
+
+    if not hasattr(wvc.DataType, dtype_str.upper()):
+        raise ValueError(f"Invalid data_type '{dtype_str}' for property '{name}'")
+
+    data_type = getattr(wvc.DataType, dtype_str.upper())
+    description = prop_details.get("description")
+
+    tokenization = None
+    token_str = prop_details.get("tokenization")
+
+    if token_str:
+        token_map = {
+            "word": Tokenization.WORD,
+            "whitespace": Tokenization.WHITESPACE,
+            "field": Tokenization.FIELD,
+            "lowercase": Tokenization.LOWERCASE
+        }
+        token_key = token_str.lower()
+        if token_key in token_map:
+            tokenization = token_map[token_key]
+        else:
+            logger.warning(f"Invalid tokenization '{token_str}' for '{name}'. Using default.")
+
+    return wvc.Property(
+        name=name,
+        data_type=data_type,
+        description=description,
+        tokenization=tokenization
+    )
+
+
+def create_vectorwave_schema(client: weaviate.WeaviateClient, settings: WeaviateSettings):
+    collection_name = settings.COLLECTION_NAME
+
+    if client.collections.exists(collection_name):
+        logger.info("Collection '%s' already exists, skipping creation", collection_name)
+        return client.collections.get(collection_name)
+
+    logger.info("Creating collection '%s'", collection_name)
+
+    base_properties = [
+        wvc.Property(name="function_name", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="module_name", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="docstring", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="source_code", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="search_description", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="sequence_narrative", data_type=wvc.DataType.TEXT),
+    ]
+
+    custom_properties = []
+    if settings.custom_properties:
+        logger.info(f"Adding {len(settings.custom_properties)} custom properties to '{collection_name}'")
+        for name, prop_details in settings.custom_properties.items():
+            try:
+                prop = _create_property_from_config(name, prop_details)
+                custom_properties.append(prop)
+            except Exception as e:
+                logger.error(f"Invalid property definition for '{name}': {e}")
+                raise SchemaCreationError(f"Invalid property definition for '{name}': {e}")
+
+    all_properties = base_properties + custom_properties
+
+    vector_config = wvc.Configure.Vectorizer.none()
+    generative_config = None
+
+    if settings.VECTORIZER.lower() == "weaviate_module":
+        if settings.WEAVIATE_VECTORIZER_MODULE == "text2vec-openai":
+            vector_config = wvc.Configure.Vectorizer.text2vec_openai()
+        if settings.WEAVIATE_GENERATIVE_MODULE == "generative-openai":
+            generative_config = wvc.Configure.Generative.openai()
+
+    elif settings.VECTORIZER.lower() not in ["none", "huggingface", "openai_client"]:
+        raise SchemaCreationError(f"Invalid VECTORIZER setting: {settings.VECTORIZER}")
+
+    try:
+        return client.collections.create(
+            name=collection_name,
+            properties=all_properties,
+            vectorizer_config=vector_config,
+            generative_config=generative_config
+        )
+    except Exception as e:
+        raise SchemaCreationError(f"Error during schema creation: {e}")
+
+
+def create_execution_schema(client: weaviate.WeaviateClient, settings: WeaviateSettings):
+    collection_name = settings.EXECUTION_COLLECTION_NAME
+
+    if client.collections.exists(collection_name):
+        logger.info("Collection '%s' already exists, skipping creation", collection_name)
+        return client.collections.get(collection_name)
+
+    logger.info("Creating collection '%s'", collection_name)
+
+    properties = [
+        wvc.Property(name="trace_id", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="span_id", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="parent_span_id", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="function_name", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="function_uuid", data_type=wvc.DataType.UUID),
+        wvc.Property(name="timestamp_utc", data_type=wvc.DataType.DATE),
+        wvc.Property(name="duration_ms", data_type=wvc.DataType.NUMBER),
+        wvc.Property(name="status", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="error_message", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="error_code", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="return_value", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="exec_source", data_type=wvc.DataType.TEXT)
+    ]
+
+    if settings.custom_properties:
+        logger.info(f"Adding {len(settings.custom_properties)} custom properties to '{collection_name}'")
+        for name, prop_details in settings.custom_properties.items():
+            try:
+                prop = _create_property_from_config(name, prop_details)
+                properties.append(prop)
+            except Exception as e:
+                logger.error(f"Invalid property definition for '{name}': {e}")
+                raise SchemaCreationError(f"Invalid property definition for '{name}': {e}")
+
+    try:
+        return client.collections.create(
+            name=collection_name,
+            properties=properties,
+            vectorizer_config=wvc.Configure.Vectorizer.none(),
+        )
+    except Exception as e:
+        raise SchemaCreationError(f"Error during execution schema creation: {e}")
+
+
+def create_golden_dataset_schema(client: weaviate.WeaviateClient, settings: WeaviateSettings):
+    collection_name = settings.GOLDEN_COLLECTION_NAME
+
+    if client.collections.exists(collection_name):
+        logger.info("Collection '%s' already exists.", collection_name)
+        return client.collections.get(collection_name)
+
+    logger.info("Creating collection '%s'", collection_name)
+
+    properties = [
+        wvc.Property(name="original_uuid", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="function_name", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="function_uuid", data_type=wvc.DataType.UUID),
+        wvc.Property(name="return_value", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="note", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="created_at", data_type=wvc.DataType.DATE),
+        wvc.Property(name="tags", data_type=wvc.DataType.TEXT_ARRAY)
+    ]
+
+    if settings.custom_properties:
+        logger.info(f"Adding {len(settings.custom_properties)} custom properties to '{collection_name}'")
+        for name, prop_details in settings.custom_properties.items():
+            try:
+                prop = _create_property_from_config(name, prop_details)
+                properties.append(prop)
+            except Exception as e:
+                logger.error(f"Invalid property definition for '{name}' in Golden Dataset: {e}")
+                raise SchemaCreationError(f"Invalid property definition for '{name}': {e}")
+
+    try:
+        return client.collections.create(
+            name=collection_name,
+            properties=properties,
+            vectorizer_config=wvc.Configure.Vectorizer.none(),
+        )
+    except Exception as e:
+        raise SchemaCreationError(f"Error creating Golden Dataset schema: {e}")
+
+
+def create_usage_schema(client: weaviate.WeaviateClient, settings: WeaviateSettings):
+    collection_name = "VectorWaveTokenUsage"
+    if client.collections.exists(collection_name):
+        return client.collections.get(collection_name)
+
+    logger.info("Creating collection '%s'", collection_name)
+    properties = [
+        wvc.Property(name="timestamp_utc", data_type=wvc.DataType.DATE),
+        wvc.Property(name="model", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="usage_type", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="category", data_type=wvc.DataType.TEXT),
+        wvc.Property(name="tokens", data_type=wvc.DataType.INT),
+    ]
+    try:
+        return client.collections.create(
+            name=collection_name,
+            properties=properties,
+            vectorizer_config=wvc.Configure.Vectorizer.none(),
+        )
+    except Exception as e:
+        raise SchemaCreationError(f"Error usage schema: {e}")
+
+
+def update_database_schema():
+    """
+    [Migration Utility]
+    Updates the schema of the running database.
+    Finds properties defined in .weaviate_properties that are missing from the DB and adds them.
+    Used to apply new filtering features without data loss.
+    """
+    try:
+        settings = get_weaviate_settings()
+        client = get_cached_client()
+
+        target_collections = [
+            settings.EXECUTION_COLLECTION_NAME,
+            settings.GOLDEN_COLLECTION_NAME
+        ]
+
+        logger.info("🚀 Starting Schema Migration...")
+
+        for col_name in target_collections:
+            if not client.collections.exists(col_name):
+                logger.warning(f"Collection '{col_name}' does not exist. Skipping.")
+                continue
+
+            collection = client.collections.get(col_name)
+            # 현재 DB에 존재하는 속성 이름 가져오기
+            existing_props = {p.name for p in collection.config.get().properties}
+
+            # 추가할 속성 확인
+            if settings.custom_properties:
+                for name, prop_details in settings.custom_properties.items():
+                    if name not in existing_props:
+                        logger.info(f"➕ Adding new property '{name}' to '{col_name}'...")
+                        try:
+                            new_prop = _create_property_from_config(name, prop_details)
+                            collection.config.add_property(new_prop)
+                            logger.info(f"   ✅ Property '{name}' added successfully.")
+                        except Exception as e:
+                            logger.error(f"   ❌ Failed to add property '{name}': {e}")
+                    else:
+                        logger.debug(f"   Pass: Property '{name}' already exists.")
+
+        logger.info("✨ Schema Migration Completed!")
+        return True
+
+    except Exception as e:
+        logger.error(f"Migration failed: {e}", exc_info=True)
+        return False
+
+
+def initialize_database():
+    try:
+        settings = get_weaviate_settings()
+        client = get_cached_client()
+        if client:
+            create_vectorwave_schema(client, settings)
+            create_execution_schema(client, settings)
+            create_usage_schema(client, settings)
+            create_golden_dataset_schema(client, settings)
+            return client
+    except Exception as e:
+        logger.error("Failed to initialize VectorWave database: %s", e)
+        return None