vectorwave 0.1.9__tar.gz → 0.2.1__tar.gz

{vectorwave-0.1.9/src/vectorwave.egg-info → vectorwave-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectorwave
-Version: 0.1.9
+Version: 0.2.1
 Summary: VectorWave: Seamless Auto-Vectorization Framework
 Author-email: junyeonggim <junyeonggim5@gmail.com>
 License-Expression: MIT

{vectorwave-0.1.9 → vectorwave-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vectorwave"
-version = "0.1.9"
+version = "0.2.01"
 authors = [
     { name = "junyeonggim", email = "junyeonggim5@gmail.com" },
 ]

vectorwave-0.2.1/src/tests/core/llm/test_token_usage.py

@@ -0,0 +1,112 @@
+import pytest
+from unittest.mock import MagicMock, patch
+from vectorwave.core.llm.openai_client import VectorWaveOpenAIClient
+
+@pytest.fixture
+def mock_deps(monkeypatch):
+    """
+    Mocks the dependencies (BatchManager, OpenAI, Settings) of VectorWaveOpenAIClient.
+    """
+    # 1. Mock BatchManager (Target for verifying token usage persistence)
+    mock_batch = MagicMock()
+    mock_batch.add_object = MagicMock()
+    mock_get_batch = MagicMock(return_value=mock_batch)
+    monkeypatch.setattr("vectorwave.core.llm.openai_client.get_batch_manager", mock_get_batch)
+
+    # 2. Mock Settings (Bypasses API Key check)
+    mock_settings = MagicMock()
+    mock_settings.OPENAI_API_KEY = "sk-test-key"
+    mock_get_settings = MagicMock(return_value=mock_settings)
+    monkeypatch.setattr("vectorwave.core.llm.openai_client.get_weaviate_settings", mock_get_settings)
+
+    # 3. Mock OpenAI Class (Bypasses actual API calls)
+    mock_openai_cls = MagicMock()
+    monkeypatch.setattr("vectorwave.core.llm.openai_client.OpenAI", mock_openai_cls)
+
+    # Note: Clearing the lru_cache for the singleton instance is typically
+    # needed if the client is imported globally. We assume the current test
+    # setup allows for fresh initialization here.
+
+    return {
+        "batch": mock_batch,
+        "openai_cls": mock_openai_cls
+    }
+
+def test_chat_completion_logs_token_usage(mock_deps):
+    """
+    [Case 1] Verify that token usage is logged as 'generation' type during chat completion.
+    """
+    # Arrange
+    # Get the mock client instance returned when OpenAI() is called
+    mock_client_instance = mock_deps["openai_cls"].return_value
+
+    # Mock OpenAI Response structure
+    mock_response = MagicMock()
+    mock_response.choices = [MagicMock(message=MagicMock(content="Test response"))]
+    mock_response.usage.total_tokens = 123  # Token count to test
+    mock_client_instance.chat.completions.create.return_value = mock_response
+
+    # Act
+    # Create a new client instance for the test
+    client = VectorWaveOpenAIClient()
+    result = client.create_chat_completion(
+        messages=[{"role": "user", "content": "Hi"}],
+        model="gpt-4-test",
+        category="test_chat_category"
+    )
+
+    # Assert
+    # 1. Verify that the function returns the expected result
+    assert result == "Test response"
+
+    # 2. Verify that BatchManager.add_object was called (log saved)
+    mock_batch = mock_deps["batch"]
+    mock_batch.add_object.assert_called_once()
+
+    # 3. Verify the properties of the saved log entry
+    call_kwargs = mock_batch.add_object.call_args.kwargs
+    props = call_kwargs["properties"]
+
+    assert call_kwargs["collection"] == "VectorWaveTokenUsage"
+    assert props["tokens"] == 123
+    assert props["model"] == "gpt-4-test"
+    assert props["category"] == "test_chat_category"
+    assert props["usage_type"] == "generation"
+
+def test_create_embedding_logs_token_usage(mock_deps):
+    """
+    [Case 2] Verify that token usage is logged as 'embedding' type during embedding creation.
+    """
+    # Arrange
+    mock_client_instance = mock_deps["openai_cls"].return_value
+
+    # Mock OpenAI Response structure
+    mock_response = MagicMock()
+    mock_response.data = [MagicMock(embedding=[0.1, 0.2, 0.3])]
+    mock_response.usage.total_tokens = 45  # Token count to test
+    mock_client_instance.embeddings.create.return_value = mock_response
+
+    # Act
+    client = VectorWaveOpenAIClient()
+    result = client.create_embedding(
+        text="Test text",
+        model="text-embedding-3-small",
+        category="test_embed_category"
+    )
+
+    # Assert
+    # 1. Verify that the function returns the expected result
+    assert result == [0.1, 0.2, 0.3]
+
+    # 2. Verify that BatchManager.add_object was called
+    mock_batch = mock_deps["batch"]
+    mock_batch.add_object.assert_called_once()
+
+    # 3. Verify the properties of the saved log entry
+    call_kwargs = mock_batch.add_object.call_args.kwargs
+    props = call_kwargs["properties"]
+
+    assert call_kwargs["collection"] == "VectorWaveTokenUsage"
+    assert props["tokens"] == 45
+    assert props["usage_type"] == "embedding"
+    assert props["category"] == "test_embed_category"

vectorwave-0.2.1/src/tests/utils/test_return_caching.py

@@ -0,0 +1,126 @@
+import pytest
+from unittest.mock import MagicMock, patch
+import json
+from vectorwave.utils.return_caching_utils import _check_and_return_cached_result
+from vectorwave.models.db_config import WeaviateSettings
+
+
+# --- Mock Fixtures ---
+
+@pytest.fixture
+def mock_caching_utils_deps(monkeypatch):
+    """
+    Mocks external dependencies of return_caching_utils.py (BatchManager, Tracer, DB search, etc.).
+    """
+    # 1. Mock Settings
+    mock_settings = WeaviateSettings(
+        EXECUTION_COLLECTION_NAME="TestExecutions",
+        global_custom_values={"run_id": "test-run-123"}
+    )
+    mock_get_settings = MagicMock(return_value=mock_settings)
+
+    # 2. Mock Batch Manager (Key verification target)
+    mock_batch_manager = MagicMock()
+    mock_batch_manager.add_object = MagicMock()
+    mock_get_batch = MagicMock(return_value=mock_batch_manager)
+
+    # 3. Mock Vectorizer
+    mock_vectorizer = MagicMock()
+    mock_vectorizer.embed.return_value = [0.1, 0.2, 0.3]  # Dummy Vector
+    mock_get_vectorizer = MagicMock(return_value=mock_vectorizer)
+
+    # 4. Mock Tracer Context (Provides current Trace ID)
+    mock_tracer = MagicMock()
+    mock_tracer.trace_id = "existing-trace-id-abc"
+
+    # 5. Apply Monkeypatches
+    TARGET_MODULE = "vectorwave.utils.return_caching_utils"
+
+    monkeypatch.setattr(f"{TARGET_MODULE}.get_weaviate_settings", mock_get_settings)
+    monkeypatch.setattr(f"{TARGET_MODULE}.get_batch_manager", mock_get_batch)
+    monkeypatch.setattr(f"{TARGET_MODULE}.get_vectorizer", mock_get_vectorizer)
+
+    return {
+        "batch_manager": mock_batch_manager,
+        "vectorizer": mock_vectorizer,
+        "tracer_obj": mock_tracer
+    }
+
+
+def test_check_and_return_cached_result_cache_hit_logging(mock_caching_utils_deps):
+    """
+    [Case 1] Verify that DB logging is correctly performed with 'CACHE_HIT' status upon a cache hit.
+    """
+    # Arrange
+    # 1. Mock cache search result (Log found in DB)
+    mock_cached_log = {
+        "return_value": json.dumps({"result": "cached_data"}),
+        "metadata": {"distance": 0.1},
+        "uuid": "cached-log-uuid"
+    }
+
+    # 2. Mock search_similar_execution to return the above result (Simulate Cache Hit)
+    with patch("vectorwave.utils.return_caching_utils.search_similar_execution", return_value=mock_cached_log):
+        # [Fix] Instead of directly patching the .get method of the ContextVar object, replace the variable itself with a Mock object.
+        with patch("vectorwave.utils.return_caching_utils.current_tracer_var") as mock_tracer_var:
+            with patch("vectorwave.utils.return_caching_utils.current_span_id_var") as mock_span_var:
+                # Set return value for .get() call on the Mock object
+                mock_tracer_var.get.return_value = mock_caching_utils_deps["tracer_obj"]
+                mock_span_var.get.return_value = "parent-span-123"
+
+                # 4. Execute the target function
+                def dummy_func(a, b): pass  # Target function
+
+                result = _check_and_return_cached_result(
+                    func=dummy_func,
+                    args=(10,),
+                    kwargs={"b": 20},
+                    function_name="dummy_func",
+                    cache_threshold=0.9,
+                    is_async=False
+                )
+
+    # Assert
+    # 1. Was the cached result returned correctly?
+    assert result == {"result": "cached_data"}
+
+    # 2. [Core] Was BatchManager.add_object called? (Check if logging occurred)
+    mock_batch = mock_caching_utils_deps["batch_manager"]
+    mock_batch.add_object.assert_called_once()
+
+    # 3. [Core] Verify properties of the saved log
+    call_kwargs = mock_batch.add_object.call_args.kwargs
+    props = call_kwargs["properties"]
+
+    assert props["status"] == "CACHE_HIT"  # Check if status is CACHE_HIT
+    assert props["duration_ms"] == 0.0  # Check if duration is 0
+    assert props["trace_id"] == "existing-trace-id-abc"  # Check if existing Trace ID is maintained
+    assert props["parent_span_id"] == "parent-span-123"  # Check for parent Span ID maintenance
+    assert props["function_name"] == "dummy_func"
+    assert props["run_id"] == "test-run-123"  # Check for inclusion of global tags
+
+
+def test_check_and_return_cached_result_cache_miss(mock_caching_utils_deps):
+    """
+    [Case 2] Verify that None is returned without logging upon a cache miss.
+    """
+    # Arrange
+    # Set search_similar_execution to return None (Cache Miss)
+    with patch("vectorwave.utils.return_caching_utils.search_similar_execution", return_value=None):
+        def dummy_func(): pass
+
+        result = _check_and_return_cached_result(
+            func=dummy_func,
+            args=(),
+            kwargs={},
+            function_name="dummy_func",
+            cache_threshold=0.9,
+            is_async=False
+        )
+
+    # Assert
+    # 1. Result should be None (To proceed to actual function execution)
+    assert result is None
+
+    # 2. BatchManager.add_object should not be called
+    mock_caching_utils_deps["batch_manager"].add_object.assert_not_called()

{vectorwave-0.1.9 → vectorwave-0.2.1}/src/vectorwave/__init__.py

@@ -5,6 +5,9 @@ from .database.db_search import search_functions, search_executions, search_erro
 from .monitoring.tracer import trace_span
 from .search.rag_search import search_and_answer, analyze_trace_log
 from .core.generator import generate_and_register_metadata
+from .utils.healer import VectorWaveHealer
+from .utils.replayer import VectorWaveReplayer
+from .utils.replayer_semantic import SemanticReplayer
 
 __all__ = [
     'vectorize',
@@ -16,5 +19,8 @@ __all__ = [
     'trace_span',
     'search_and_answer',
     'analyze_trace_log',
-    'generate_and_register_metadata'
+    'generate_and_register_metadata',
+    'VectorWaveHealer',
+    'VectorWaveReplayer',
+    'SemanticReplayer'
 ]

{vectorwave-0.1.9 → vectorwave-0.2.1}/src/vectorwave/core/generator.py

@@ -7,6 +7,7 @@ from ..models.db_config import get_weaviate_settings
 from ..batch.batch import get_batch_manager
 from ..vectorizer.factory import get_vectorizer
 from .decorator import PENDING_FUNCTIONS
+from .llm.factory import get_llm_client
 
 logger = logging.getLogger(__name__)
 
@@ -15,20 +16,11 @@ try:
 except ImportError:
     OpenAI = None
 
-def _get_openai_client(settings):
-    if OpenAI is None:
-        logger.error("OpenAI library not installed. Install with 'pip install openai'.")
-        return None
-    if not settings.OPENAI_API_KEY:
-        logger.error("OPENAI_API_KEY is missing in .env.")
-        return None
-    return OpenAI(api_key=settings.OPENAI_API_KEY)
-
 
 def generate_metadata_via_llm(source_code: str, func_name: str) -> Optional[Dict[str, str]]:
     """Call LLM to generate description and narrative from source code."""
     settings = get_weaviate_settings()
-    client = _get_openai_client(settings)
+    client = get_llm_client()
     if not client:
         return None
 
@@ -47,17 +39,22 @@ def generate_metadata_via_llm(source_code: str, func_name: str) -> Optional[Dict
     """
 
     try:
-        response = client.chat.completions.create(
+        # Refactored to use BaseLLMClient interface
+        response_text = client.create_chat_completion(
             model="gpt-4o-mini",
             messages=[
                 {"role": "system", "content": "You are a technical documentation assistant. Output only JSON."},
                 {"role": "user", "content": prompt}
             ],
             temperature=0.0,
-            response_format={"type": "json_object"}
+            response_format={"type": "json_object"},
+            category="auto_doc"
         )
-        content = response.choices[0].message.content
-        return json.loads(content)
+
+        if response_text:
+            return json.loads(response_text)
+        return None
+
     except Exception as e:
         logger.error(f"LLM generation failed for '{func_name}': {e}")
         return None

vectorwave-0.2.1/src/vectorwave/core/llm/base.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+from typing import List, Dict, Optional
+
+class BaseLLMClient(ABC):
+    """
+    Abstract interface that all LLM Providers (OpenAI, Anthropic, etc.) must implement.
+    Implementations must handle internal token usage logging.
+    """
+
+    @abstractmethod
+    def create_embedding(self, text: str, model: str, category: str = "default") -> Optional[List[float]]:
+        """
+        Generates text embeddings.
+
+        Args:
+            text: The text to embed.
+            model: The name of the model to use.
+            category: Category for aggregating token usage (e.g., 'execution_log', 'auto_doc').
+
+        Returns:
+            The generated list of embedding vectors (None on failure).
+        """
+        pass
+
+    @abstractmethod
+    def create_chat_completion(
+            self,
+            messages: List[Dict],
+            model: str,
+            temperature: float = 0.1,
+            response_format: Optional[Dict] = None,
+            category: str = "default"
+    ) -> Optional[str]:
+        """
+        Generates a chat completion (response).
+
+        Args:
+            messages: List of conversation messages [{"role": "user", "content": "..."}].
+            model: The name of the model to use.
+            temperature: Parameter for controlling generation diversity.
+            response_format: Response format (e.g., {"type": "json_object"}).
+            category: Category for aggregating token usage (e.g., 'execution_log', 'auto_doc').
+
+        Returns:
+            The generated text response (None on failure).
+        """
+        pass

vectorwave-0.2.1/src/vectorwave/core/llm/factory.py

@@ -0,0 +1,13 @@
+from .base import BaseLLMClient
+from .openai_client import VectorWaveOpenAIClient
+
+_llm_instance: BaseLLMClient = None
+
+
+def get_llm_client() -> BaseLLMClient:
+    """Returns the singleton LLM client instance."""
+    global _llm_instance
+    if _llm_instance is None:
+        # Can be extended later to return different clients (Anthropic, etc.) based on settings (VECTORIZER, etc.)
+        _llm_instance = VectorWaveOpenAIClient()
+    return _llm_instance

vectorwave-0.2.1/src/vectorwave/core/llm/openai_client.py

@@ -0,0 +1,79 @@
+# src/vectorwave/core/llm/openai_client.py
+import logging
+from typing import List, Dict, Optional
+from datetime import datetime, timezone
+from ...models.db_config import get_weaviate_settings
+from ...batch.batch import get_batch_manager  # [추가]
+from .base import BaseLLMClient
+
+logger = logging.getLogger(__name__)
+
+try:
+    from openai import OpenAI
+except ImportError:
+    OpenAI = None
+
+
+class VectorWaveOpenAIClient(BaseLLMClient):
+    def __init__(self):
+        self.settings = get_weaviate_settings()
+        self.batch_manager = get_batch_manager()
+
+        if OpenAI is None or not self.settings.OPENAI_API_KEY:
+            self.client = None
+        else:
+            self.client = OpenAI(api_key=self.settings.OPENAI_API_KEY)
+
+    def _log_usage(self, tokens: int, model: str, usage_type: str, category: str):
+        if tokens > 0:
+            try:
+                self.batch_manager.add_object(
+                    collection="VectorWaveTokenUsage",
+                    properties={
+                        "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+                        "model": model,
+                        "usage_type": usage_type,
+                        "category": category,
+                        "tokens": tokens
+                    }
+                )
+            except Exception as e:
+                logger.warning(f"Failed to log token usage: {e}")
+
+    def create_embedding(self, text: str, model: str = "text-embedding-3-small", category: str = "default") -> Optional[
+        List[float]]:
+        """
+        Returns: Vector list only (Tokens are logged internally)
+        """
+        if not self.client: return None
+        try:
+            text = text.replace("\n", " ")
+            res = self.client.embeddings.create(input=[text], model=model)
+
+            tokens = res.usage.total_tokens if res.usage else 0
+            self._log_usage(tokens, model, "embedding", category)
+
+            return res.data[0].embedding
+        except Exception as e:
+            logger.error(f"Embedding error: {e}")
+            return None
+
+    def create_chat_completion(self, messages: List[Dict], model: str = "gpt-4-turbo", temperature: float = 0.1,
+                               response_format=None, category: str = "default") -> Optional[str]:
+        """
+        Returns: Content string only (Tokens are logged internally)
+        """
+        if not self.client: return None
+        try:
+            kwargs = {"model": model, "messages": messages, "temperature": temperature}
+            if response_format: kwargs["response_format"] = response_format
+
+            res = self.client.chat.completions.create(**kwargs)
+
+            tokens = res.usage.total_tokens if res.usage else 0
+            self._log_usage(tokens, model, "generation", category)
+
+            return res.choices[0].message.content
+        except Exception as e:
+            logger.error(f"Completion error: {e}")
+            return None

{vectorwave-0.1.9 → vectorwave-0.2.1}/src/vectorwave/database/db.py

@@ -16,6 +16,7 @@ from weaviate.exceptions import WeaviateConnectionError as WeaviateClientConnect
 # Create module-level logger
 logger = logging.getLogger(__name__)
 
+
 # Code based on Weaviate v4 (latest) client.
 
 def get_weaviate_client(settings: WeaviateSettings) -> weaviate.WeaviateClient:
@@ -324,6 +325,36 @@ def create_execution_schema(client: weaviate.WeaviateClient, settings: WeaviateS
         raise SchemaCreationError(f"Error during execution schema creation: {e}")
 
 
+def create_usage_schema(client: weaviate.WeaviateClient, settings: WeaviateSettings):
+    """
+    API call token analysis schema
+    """
+    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),  # "embedding", "generation" 등
+        wvc.Property(name="category", data_type=wvc.DataType.TEXT),  # "execution_log", "auto_doc" 등
+        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:
+        logger.error(f"Error creating usage schema: {e}")
+        raise SchemaCreationError(f"Error during usage schema creation: {e}")
+
+
 def initialize_database():
     """
     Helper function to initialize both the client and the two schemas.
@@ -334,8 +365,8 @@ def initialize_database():
         if client:
             create_vectorwave_schema(client, settings)
             create_execution_schema(client, settings)
+            create_usage_schema(client, settings)
             return client
     except Exception as e:
         logger.error("Failed to initialize VectorWave database: %s", e)
         return None
-

{vectorwave-0.1.9 → vectorwave-0.2.1}/src/vectorwave/database/db_search.py

@@ -10,6 +10,7 @@ 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
+from weaviate.classes.aggregate import Metrics
 
 import uuid
 from datetime import datetime
@@ -409,3 +410,86 @@ def check_semantic_drift(
     except Exception as e:
         logger.error(f"Failed to check semantic drift: {e}")
         return False, 0.0, None
+
+
+def simulate_drift_check(
+        text: str,
+        function_name: str,
+        threshold: Optional[float] = None,
+        k: Optional[int] = None
+) -> Dict[str, Any]:
+    """
+    Simulates drift detection for a hypothetical input string without executing the function.
+    Useful for 'Drift Radar' or debugging.
+    """
+    try:
+        settings = get_weaviate_settings()
+        vectorizer = get_vectorizer()
+
+        if not vectorizer:
+            return {"error": "No vectorizer configured."}
+
+        # 1. Set defaults from settings if not provided
+        if threshold is None:
+            threshold = settings.DRIFT_DISTANCE_THRESHOLD
+        if k is None:
+            k = settings.DRIFT_NEIGHBOR_AMOUNT
+
+        # 2. Vectorize the input text
+        try:
+            vector = vectorizer.embed(text)
+        except Exception as e:
+            return {"error": f"Vectorization failed: {e}"}
+
+        # 3. Perform the check using the existing logic
+        is_drift, avg_distance, nearest_uuid = check_semantic_drift(
+            vector=vector,
+            function_name=function_name,
+            threshold=threshold,
+            k=k
+        )
+
+        return {
+            "function_name": function_name,
+            "input_text": text,
+            "is_drift": is_drift,
+            "avg_distance": avg_distance,
+            "threshold": threshold,
+            "nearest_neighbor_uuid": nearest_uuid,
+            "status": "ANOMALY" if is_drift else "NORMAL"
+        }
+
+    except Exception as e:
+        logger.error(f"Simulation failed: {e}")
+        return {"error": str(e)}
+
+
+def get_token_usage_stats() -> Dict[str, int]:
+    """VectorWaveTokenUsage collections based analysis"""
+    try:
+        client = get_cached_client()
+        if not client.collections.exists("VectorWaveTokenUsage"):
+            logger.warning("VectorWaveTokenUsage collection does not exist.")
+            return {"total_tokens": 0}
+
+        usage_col = client.collections.get("VectorWaveTokenUsage")
+
+        total_tokens = 0
+        stats = {}
+
+        for obj in usage_col.iterator():
+            props = obj.properties
+            tokens = int(props.get("tokens", 0))
+            category = props.get("category", "unknown")
+
+            total_tokens += tokens
+
+            cat_key = f"{category}_tokens"
+            stats[cat_key] = stats.get(cat_key, 0) + tokens
+
+        stats["total_tokens"] = total_tokens
+        return stats
+
+    except Exception as e:
+        logger.error(f"Stats error: {e}", exc_info=True)
+        return {}