vectorwave 0.1.3__py3-none-any.whl

vectorwave/database/db.py

@@ -0,0 +1,328 @@
+import logging
+import weaviate
+import weaviate.classes.config as wvc  # (wvc = Weaviate Classes Config)
+import weaviate.config as wvc_config
+from weaviate.config import AdditionalConfig
+from vectorwave.models.db_config import WeaviateSettings
+from vectorwave.exception.exceptions import (
+    WeaviateConnectionError,
+    WeaviateNotReadyError,
+    SchemaCreationError
+)
+from functools import lru_cache
+from weaviate.exceptions import WeaviateConnectionError as WeaviateClientConnectionError
+from vectorwave.models.db_config import get_weaviate_settings
+from vectorwave.vectorizer.factory import get_vectorizer
+
+# Create module-level logger
+logger = logging.getLogger(__name__)
+
+# Code based on Weaviate v4 (latest) client.
+
+def get_weaviate_client(settings: WeaviateSettings) -> weaviate.WeaviateClient:
+    """
+    Creates and returns a Weaviate client.
+
+    [Raises]
+    - WeaviateConnectionError: If connection fails.
+    - WeaviateNotReadyError: If connected, but the server is not ready.
+    """
+
+    client: 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:
+    """
+    Singleton factory: Gets settings and returns a single client instance.
+    This function IS cached.
+    """
+    logger.debug("Creating and caching new Weaviate client instance")
+    settings = get_weaviate_settings()
+    client = get_weaviate_client(settings)
+    return client
+
+
+def create_vectorwave_schema(client: weaviate.WeaviateClient, settings: WeaviateSettings):
+    """
+    Defines and creates the VectorWaveFunctions collection schema.
+    Now includes custom properties loaded from the settings (via .weaviate_properties file).
+
+    [Raises]
+    - SchemaCreationError: If an error occurs during schema creation.
+    """
+    collection_name = settings.COLLECTION_NAME
+
+    # 1. Check if the collection already exists
+    if client.collections.exists(collection_name):
+        logger.info("Collection '%s' already exists, skipping creation", collection_name)
+        return client.collections.get(collection_name)
+
+    # 2. If it doesn't exist, define and create the collection
+    logger.info("Creating collection '%s'", collection_name)
+
+    # 3. Define Base Properties
+    base_properties = [
+        wvc.Property(
+            name="function_name",
+            data_type=wvc.DataType.TEXT,
+            description="The name of the vectorized function"
+        ),
+        wvc.Property(
+            name="module_name",
+            data_type=wvc.DataType.TEXT,
+            description="The Python module path where the function is defined"
+        ),
+        wvc.Property(
+            name="docstring",
+            data_type=wvc.DataType.TEXT,
+            description="The function's Docstring (description)"
+        ),
+        wvc.Property(
+            name="source_code",
+            data_type=wvc.DataType.TEXT,
+            description="The actual source code of the function"
+        ),
+        wvc.Property(
+            name="search_description",
+            data_type=wvc.DataType.TEXT,
+            description="User-provided description for similarity search (from @vectorize)"
+        ),
+        wvc.Property(
+            name="sequence_narrative",
+            data_type=wvc.DataType.TEXT,
+            description="User-provided context about what happens next (from @vectorize)"
+        ),
+    ]
+
+    # 4. Parse Custom Properties (loaded from JSON file via settings object)
+    custom_properties = []
+    if settings.custom_properties:
+        logger.info(
+            "Adding %d custom properties to '%s': %s",
+            len(settings.custom_properties),
+            collection_name,
+            list(settings.custom_properties.keys())
+        )
+
+        for name, prop_details in settings.custom_properties.items():
+            if not isinstance(prop_details, dict):
+                raise SchemaCreationError(f"Custom property '{name}' in config file must be a dictionary.")
+
+            # Get data_type (Required)
+            dtype_str = prop_details.get("data_type")
+            if not dtype_str:
+                raise SchemaCreationError(f"Custom property '{name}' in config file is missing 'data_type'.")
+
+            # Get description (Optional)
+            description = prop_details.get("description")
+
+            try:
+                # Convert string (e.g., "TEXT") to Weaviate Enum (wvc.DataType.TEXT)
+                data_type = getattr(wvc.DataType, dtype_str.upper())
+
+                custom_properties.append(
+                    wvc.Property(
+                        name=name,
+                        data_type=data_type,
+                        description=description
+                    )
+                )
+            except AttributeError:
+                raise SchemaCreationError(
+                    f"Invalid data_type '{dtype_str}' for custom property '{name}'. "
+                    f"Use a valid wvc.DataType string (e.g., 'TEXT', 'INT', 'NUMBER')."
+                )
+            except Exception as e:
+                raise SchemaCreationError(f"Error processing custom property '{name}': {e}")
+
+    # 5. Combine properties
+    all_properties = base_properties + custom_properties
+
+    vector_config = None
+    vectorizer_name_setting = settings.VECTORIZER.lower()
+
+    logger.info("Configuring vectorizer: %s", vectorizer_name_setting)
+
+    if vectorizer_name_setting == "huggingface" or vectorizer_name_setting == "openai_client":
+        print(f"Python-based vectorizer ('{vectorizer_name_setting}') is active.")
+        print("Setting Weaviate schema vectorizer to 'none'.")
+        vector_config = wvc.Configure.Vectorizer.none()
+
+    elif vectorizer_name_setting == "weaviate_module":
+        module_name = settings.WEAVIATE_VECTORIZER_MODULE.lower()
+        print(f"Using Weaviate internal module: '{module_name}'")
+
+        if module_name == "text2vec-openai":
+            vector_config = wvc.Configure.Vectorizer.text2vec_openai(
+                vectorize_collection_name=settings.IS_VECTORIZE_COLLECTION_NAME
+            )
+        # (필요시 다른 Weaviate 모듈도 여기에 추가)
+        else:
+            raise SchemaCreationError(
+                f"Unsupported WEAVIATE_VECTORIZER_MODULE: '{module_name}'.")
+
+    elif vectorizer_name_setting == "none":
+        # 벡터화 비활성화
+        print("Vectorizer is set to 'none'.")
+        vector_config = wvc.Configure.Vectorizer.none()
+
+    else:
+        raise SchemaCreationError(
+            f"Invalid VECTORIZER setting: '{vectorizer_name_setting}'.")
+
+    generative_config = None
+    if settings.WEAVIATE_GENERATIVE_MODULE.lower() == "generative-openai":
+        generative_config = wvc.Configure.Generative.openai()
+
+    try:
+        vectorwave_collection = client.collections.create(
+            name=collection_name,
+            properties=all_properties,
+
+            # 7. Vectorizer Configuration
+            vector_config=vector_config,
+
+            # 8. Generative Configuration (for RAG, etc.)
+            generative_config=generative_config
+        )
+        return vectorwave_collection
+
+    except Exception as e:
+        # Raise a specific exception instead of returning None
+        raise SchemaCreationError(f"Error during schema creation: {e}")
+
+
+def create_execution_schema(client: weaviate.WeaviateClient, settings: WeaviateSettings):
+    """
+    Defines and creates the VectorWaveExecutions (dynamic) collection schema.
+    """
+    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,
+            description="The unique ID for the entire trace/workflow"
+        ),
+        wvc.Property(
+            name="span_id",
+            data_type=wvc.DataType.TEXT,
+            description="The unique ID for this specific span/function execution"
+        ),
+        wvc.Property(
+            name="function_name",
+            data_type=wvc.DataType.TEXT,
+            description="Name of the executed function (span name)"
+        ),
+        wvc.Property(
+            name="function_uuid",
+            data_type=wvc.DataType.UUID,
+            description="The UUID of the executed function definition"
+        ),
+        wvc.Property(
+            name="timestamp_utc",
+            data_type=wvc.DataType.DATE,
+            description="The UTC timestamp when the execution started"
+        ),
+        wvc.Property(
+            name="duration_ms",
+            data_type=wvc.DataType.NUMBER,
+            description="Total execution time in milliseconds"
+        ),
+        wvc.Property(
+            name="status",
+            data_type=wvc.DataType.TEXT,  # "SUCCESS" or "ERROR"
+            description="Execution status"
+        ),
+        wvc.Property(
+            name="error_message",
+            data_type=wvc.DataType.TEXT,
+            description="Error message and traceback if status is 'ERROR'"
+        ),
+    ]
+
+    if settings.custom_properties:
+        logger.info(
+            "Adding %d custom properties: %s",
+            len(settings.custom_properties),
+            list(settings.custom_properties.keys())
+        )
+        for name, prop_details in settings.custom_properties.items():
+            try:
+                if not isinstance(prop_details, dict):
+                    raise ValueError("Property details must be a dictionary.")
+
+                dtype_str = prop_details.get("data_type")
+                if not dtype_str:
+                    raise ValueError("data_type is missing.")
+
+                data_type = getattr(wvc.DataType, dtype_str.upper())
+                description = prop_details.get("description")
+
+                properties.append(
+                    wvc.Property(
+                        name=name,
+                        data_type=data_type,
+                        description=description
+                    )
+                )
+            except Exception as e:
+                logger.warning("Skipping custom property '%s' for '%s': %s", name, collection_name, e)
+
+    try:
+        execution_collection = client.collections.create(
+            name=collection_name,
+            properties=properties,
+            vector_config=wvc.Configure.Vectorizer.none(),
+            # vector_index_config=wvc.Configure.VectorIndex.none()
+        )
+        logger.info("Collection '%s' created successfully", collection_name)
+        return execution_collection
+    except Exception as e:
+        raise SchemaCreationError(f"Error during execution schema creation: {e}")
+
+
+def initialize_database():
+    """
+    Helper function to initialize both the client and the two schemas.
+    """
+    try:
+        settings = get_weaviate_settings()
+        client = get_cached_client()
+        if client:
+            create_vectorwave_schema(client, settings)
+            create_execution_schema(client, settings)
+            return client
+    except Exception as e:
+        logger.error("Failed to initialize VectorWave database: %s", e)
+        return None
+

vectorwave/database/db_search.py

@@ -0,0 +1,122 @@
+import logging
+import weaviate
+import weaviate.classes as wvc
+from typing import Dict, Any, Optional, List
+
+from weaviate.collections.classes.filters import _Filters
+
+from ..models.db_config import get_weaviate_settings, WeaviateSettings
+from .db import get_cached_client
+from ..exception.exceptions import WeaviateConnectionError
+from ..vectorizer.factory import get_vectorizer
+
+import uuid
+from datetime import datetime
+
+# Create module-level logger
+logger = logging.getLogger(__name__)
+
+def _build_weaviate_filters(filters: Optional[Dict[str, Any]]) -> _Filters | None:
+    if not filters:
+        return None
+    filter_list = [
+        wvc.query.Filter.by_property(key).equal(value)
+        for key, value in filters.items()
+    ]
+    if not filter_list:
+        return None
+    return wvc.query.Filter.all_of(filter_list)
+
+
+def search_functions(query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None) -> List[Dict[str, Any]]:
+    """
+    Searches function definitions from the [VectorWaveFunctions] collection using natural language (nearText).
+    """
+    try:
+        settings: WeaviateSettings = get_weaviate_settings()
+        client: weaviate.WeaviateClient = get_cached_client()
+
+        collection = client.collections.get(settings.COLLECTION_NAME)
+        weaviate_filter = _build_weaviate_filters(filters)
+
+        vectorizer = get_vectorizer()
+
+        if vectorizer:
+            print("[VectorWave] Searching with Python client (near_vector)...")
+            try:
+                query_vector = vectorizer.embed(query)
+            except Exception as e:
+                print(f"Error vectorizing query with Python client: {e}")
+                raise WeaviateConnectionError(f"Query vectorization failed: {e}")
+
+            response = collection.query.near_vector(
+                near_vector=query_vector,
+                limit=limit,
+                filters=weaviate_filter,
+                return_metadata=wvc.query.MetadataQuery(distance=True)
+            )
+
+        else:
+            print("[VectorWave] Searching with Weaviate module (near_text)...")
+            response = collection.query.near_text(
+                query=query,
+                limit=limit,
+                filters=weaviate_filter,
+                return_metadata=wvc.query.MetadataQuery(distance=True)
+            )
+
+        results = [
+            {
+                "properties": obj.properties,
+                "metadata": obj.metadata,
+                "uuid": obj.uuid
+            }
+            for obj in response.objects
+        ]
+        return results
+
+    except Exception as e:
+        logger.error("Error during Weaviate search: %s", e)
+        raise WeaviateConnectionError(f"Failed to execute 'search_functions': {e}")
+
+
+def search_executions(
+        limit: int = 10,
+        filters: Optional[Dict[str, Any]] = None,
+        sort_by: Optional[str] = "timestamp_utc",
+        sort_ascending: bool = False
+) -> List[Dict[str, Any]]:
+    """
+    Searches execution logs from the [VectorWaveExecutions] collection using filtering and sorting.
+    """
+    try:
+        settings: WeaviateSettings = get_weaviate_settings()
+        client: weaviate.WeaviateClient = get_cached_client()
+
+        collection = client.collections.get(settings.EXECUTION_COLLECTION_NAME)
+        weaviate_filter = _build_weaviate_filters(filters)
+        weaviate_sort = None
+
+        if sort_by:
+            weaviate_sort = wvc.query.Sort.by_property(
+                name=sort_by,
+                ascending=sort_ascending
+            )
+
+        response = collection.query.fetch_objects(
+            limit=limit,
+            filters=weaviate_filter,
+            sort=weaviate_sort
+        )
+        results = []
+        for obj in response.objects:
+            props = obj.properties.copy()
+            for key, value in props.items():
+                if isinstance(value, uuid.UUID) or isinstance(value, datetime):
+                    props[key] = str(value)
+            results.append(props)
+
+        return results
+
+    except Exception as e:
+        raise WeaviateConnectionError(f"Failed to execute 'search_executions': {e}")

vectorwave/exception/exceptions.py

@@ -0,0 +1,22 @@
+"""
+Defines custom exceptions for the VectorWave project.
+"""
+
+class VectorWaveError(Exception):
+    """Base exception class for the VectorWave library."""
+    pass
+
+
+class WeaviateConnectionError(VectorWaveError):
+    """Raised when an error occurs while attempting to connect to the Weaviate server."""
+    pass
+
+
+class WeaviateNotReadyError(VectorWaveError):
+    """Raised when connected to Weaviate, but the server is not in a ready state."""
+    pass
+
+
+class SchemaCreationError(VectorWaveError):
+    """Raised when an error occurs during Weaviate collection schema creation."""
+    pass

vectorwave/models/db_config.py

@@ -0,0 +1,92 @@
+import logging
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from functools import lru_cache
+from typing import Dict, Optional, Any
+import json
+import os
+
+# Create module-level logger
+logger = logging.getLogger(__name__)
+
+class WeaviateSettings(BaseSettings):
+    """
+    Manages Weaviate database connection settings.
+
+    Reads values from environment variables or a .env file.
+    (e.g., WEAVIATE_HOST=10.0.0.1)
+    """
+    # If environment variables are not set, these default values will be used.
+    WEAVIATE_HOST: str = "localhost"
+    WEAVIATE_PORT: int = 8080
+    WEAVIATE_GRPC_PORT: int = 50051
+    COLLECTION_NAME: str = "VectorWaveFunctions"
+    EXECUTION_COLLECTION_NAME: str = "VectorWaveExecutions"
+    IS_VECTORIZE_COLLECTION_NAME: bool = True
+
+    # "weaviate_module", "huggingface", "openai_client", "none"
+    VECTORIZER: str = "weaviate_module"
+
+
+    WEAVIATE_VECTORIZER_MODULE: str = "text2vec-openai"
+
+    WEAVIATE_GENERATIVE_MODULE: str = "generative-openai"
+
+    # [신규] Python 클라이언트용 설정
+    OPENAI_API_KEY: Optional[str] = None
+    HF_MODEL_NAME: str = "sentence-transformers/all-MiniLM-L6-v2"
+
+    CUSTOM_PROPERTIES_FILE_PATH: str = ".weaviate_properties"
+    custom_properties: Optional[Dict[str, Dict[str, Any]]] = None
+    global_custom_values: Optional[Dict[str, Any]] = None
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8",extra='ignore')
+
+
+# @lru_cache ensures this function creates the Settings object only once (Singleton pattern)
+# and reuses the cached object on subsequent calls.
+@lru_cache()
+def get_weaviate_settings() -> WeaviateSettings:
+    """
+    Factory function that returns the settings object.
+    """
+    settings = WeaviateSettings()
+
+    file_path = settings.CUSTOM_PROPERTIES_FILE_PATH
+
+    if file_path and os.path.exists(file_path):
+        logger.info("Loading custom properties schema from '%s'", file_path)
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                loaded_data = json.load(f)
+
+                if isinstance(loaded_data, dict):
+                    settings.custom_properties = loaded_data
+                else:
+                    logger.warning(
+                        "Content in '%s' is not a valid dictionary (JSON root), custom properties will not be loaded",
+                        file_path
+                    )
+                    settings.custom_properties = None
+
+        except json.JSONDecodeError as e:
+            logger.warning("Could not parse JSON from '%s': %s", file_path, e)
+            settings.custom_properties = None
+        except Exception as e:
+            logger.warning("Could not read file '%s': %s", file_path, e)
+            settings.custom_properties = None
+
+    elif file_path:
+        logger.debug("Custom properties file not found at '%s', skipping", file_path)
+
+    if settings.custom_properties:
+        settings.global_custom_values = {}
+        logger.debug("Loading global custom values from environment variables")
+
+        for prop_name in settings.custom_properties.keys():
+            env_var_name = prop_name.upper()
+            value = os.environ.get(env_var_name)
+
+            if value:
+                settings.global_custom_values[prop_name] = value
+                logger.debug("Loaded global value for '%s' from env var '%s'", prop_name, env_var_name)
+
+    return settings