vectorwave 0.1.5__tar.gz → 0.1.7__tar.gz

{vectorwave-0.1.5/src/vectorwave.egg-info → vectorwave-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vectorwave
-Version: 0.1.5
+Version: 0.1.7
 Summary: VectorWave: Seamless Auto-Vectorization Framework
 Author-email: junyeonggim <junyeonggim5@gmail.com>
 License-Expression: MIT
@@ -24,7 +24,6 @@ Requires-Dist: requests
 Dynamic: license-file
 
 
-
 # VectorWave: Seamless Auto-Vectorization Framework
 
 [](https://opensource.org/licenses/MIT)
@@ -40,6 +39,9 @@ Dynamic: license-file
 * **`@vectorize` Decorator:**
   1.  **Static Data Collection:** Upon script load, the function's source code, docstring, and metadata are saved once to the `VectorWaveFunctions` collection.
   2.  **Dynamic Data Logging:** Each time the function is called, its execution time, success/failure status, error logs, and "dynamic tags" are recorded in the `VectorWaveExecutions` collection.
+* **Semantic Caching and Performance Optimization:**
+    * Determines cache hits based on the **semantic similarity** of function inputs, bypassing actual execution for identical or highly similar inputs and returning stored results immediately.
+    * This significantly **reduces latency** and costs, especially for high-cost computation functions (e.g., LLM calls, complex data processing).
 * **Distributed Tracing:** Combines `@vectorize` and `@trace_span` decorators to bundle the execution of complex, multi-step workflows under a single **`trace_id`** for analysis.
 * **Search Interface:** Provides `search_functions` and `search_executions` to query the stored vector data (function definitions) and logs (execution history), facilitating the construction of RAG and monitoring systems.
 
@@ -69,7 +71,7 @@ try:
 except Exception as e:
     print(f"DB initialization failed: {e}")
     exit()
-```
+````
 
 ### 2\. [Storage] Using `@vectorize` and Distributed Tracing
 
@@ -118,6 +120,37 @@ print("Now calling 'process_payment'...")
 process_payment("user_789", 5000)
 ```
 
+#### Semantic Caching Example
+
+Configure a function to return a cached result if the input is semantically similar to a previous execution.
+
+```python
+from vectorwave import vectorize
+import time
+
+@vectorize(
+    search_description="High-cost LLM summarization task",
+    sequence_narrative="LLM Summarization Step",
+    semantic_cache=True,            # Enable caching
+    cache_threshold=0.95,           # Cache hit if similarity >= 0.95
+    capture_return_value=True       # Required to save the result
+)
+def summarize_document(document_text: str):
+    # Simulate an LLM call or heavy computation (e.g., 0.5 sec delay)
+    time.sleep(0.5)
+    print("--- [Cache Miss] Document is being summarized by LLM...")
+    return f"Summary of: {document_text[:20]}..."
+
+# First call (Cache Miss) - takes ~0.5s, saves result to DB
+result_1 = summarize_document("The first quarter results showed strong growth in Europe and Asia...")
+
+# Second call (Cache Hit) - takes ~0.0s, returns cached value
+# "Q1 results" is semantically similar to "first quarter results"
+result_2 = summarize_document("The Q1 results demonstrated strong growth in Europe and Asia...") 
+
+# result_2 returns the stored value without executing the function's body.
+```
+
 ### 3\. [Retrieval ①] Search Function Definitions (for RAG)
 
 ```python
@@ -185,7 +218,12 @@ You can select the text vectorization method via the `VECTORIZER` environment va
 | **`weaviate_module`** | (Docker Delegate) Delegates vectorization to Weaviate's built-in module (e.g., `text2vec-openai`). | `WEAVIATE_VECTORIZER_MODULE`, `OPENAI_API_KEY` |
 | **`none`** | Disables vectorization. Data is stored without vectors. | None |
 
------
+#### ⚠️ Semantic Caching Prerequisites and Configuration
+
+To use `semantic_cache=True`, the following conditions must be met:
+
+* **Vectorizer Required:** A **Python-based vectorizer** (`huggingface` or `openai_client`) must be configured in your environment (`VECTORIZER` environment variable). Caching is automatically disabled if set to `weaviate_module` or `none`.
+* **Return Value Capture:** The `capture_return_value` parameter is automatically set to `True` when `semantic_cache=True` is enabled.
 
 ### .env File Examples
 
@@ -266,8 +304,6 @@ FAILURE_MAPPING_FILE_PATH=.vectorwave_errors.json
 RUN_ID=test-run-001
 ```
 
------
-
 ### 🚀 Advanced Failure Tracing (Error Code)
 
 This enhances `VectorWaveExecutions` logs beyond a simple `status: "ERROR"`. An `error_code` property is added to the schema for granular failure analysis.
@@ -396,7 +432,6 @@ def other_function():
     pass
 ```
 
-
 1.  **Validation (Important):** Tags (global or function-specific) will **only** be saved to Weaviate if their key (e.g., `run_id`, `team`, `priority`) was first defined in the `.weaviate_properties` file (Step 1). Tags not defined in the schema are **ignored**, and a warning is logged at startup.
 
 2.  **Priority (Override):** If a tag key is defined in both places (e.g., global `RUN_ID` in `.env` and `run_id="override-xyz"` in the decorator), the **function-specific tag from the decorator always wins**.
@@ -413,6 +448,7 @@ def other_function():
 Beyond just logging, `VectorWave` can send **real-time notifications via webhook** the instant an error occurs. This functionality is built directly into the tracer and can be activated simply by updating your `.env` file.
 
 **How it Works:**
+
 1.  An exception is raised within a function decorated by `@trace_span` or `@vectorize`.
 2.  The tracer catches the exception in its `except` block and immediately calls the `alerter` object.
 3.  The alerter reads the `.env` configuration and uses the `WebhookAlerter` to dispatch the error details to your specified URL.
@@ -432,8 +468,6 @@ ALERTER_WEBHOOK_URL="[https://discord.com/api/webhooks/YOUR_HOOK_ID/](https://di
 With just these two lines, running test_ex/example.py will now instantly send a Discord alert when the CustomValueError is raised.
 
 Extensibility (Strategy Pattern): The alerting system is built on a Strategy Pattern. You can easily extend it by implementing the BaseAlerter interface to support other channels like email, PagerDuty, or more.
-
-**Tag Merging and Validation Rules**
 ```
 
 ## 🤝 Contributing

{vectorwave-0.1.5 → vectorwave-0.1.7}/Readme.md

@@ -1,5 +1,4 @@
 
-
 # VectorWave: Seamless Auto-Vectorization Framework
 
 [](https://opensource.org/licenses/MIT)
@@ -15,6 +14,9 @@
 * **`@vectorize` Decorator:**
   1.  **Static Data Collection:** Upon script load, the function's source code, docstring, and metadata are saved once to the `VectorWaveFunctions` collection.
   2.  **Dynamic Data Logging:** Each time the function is called, its execution time, success/failure status, error logs, and "dynamic tags" are recorded in the `VectorWaveExecutions` collection.
+* **Semantic Caching and Performance Optimization:**
+    * Determines cache hits based on the **semantic similarity** of function inputs, bypassing actual execution for identical or highly similar inputs and returning stored results immediately.
+    * This significantly **reduces latency** and costs, especially for high-cost computation functions (e.g., LLM calls, complex data processing).
 * **Distributed Tracing:** Combines `@vectorize` and `@trace_span` decorators to bundle the execution of complex, multi-step workflows under a single **`trace_id`** for analysis.
 * **Search Interface:** Provides `search_functions` and `search_executions` to query the stored vector data (function definitions) and logs (execution history), facilitating the construction of RAG and monitoring systems.
 
@@ -44,7 +46,7 @@ try:
 except Exception as e:
     print(f"DB initialization failed: {e}")
     exit()
-```
+````
 
 ### 2\. [Storage] Using `@vectorize` and Distributed Tracing
 
@@ -93,6 +95,37 @@ print("Now calling 'process_payment'...")
 process_payment("user_789", 5000)
 ```
 
+#### Semantic Caching Example
+
+Configure a function to return a cached result if the input is semantically similar to a previous execution.
+
+```python
+from vectorwave import vectorize
+import time
+
+@vectorize(
+    search_description="High-cost LLM summarization task",
+    sequence_narrative="LLM Summarization Step",
+    semantic_cache=True,            # Enable caching
+    cache_threshold=0.95,           # Cache hit if similarity >= 0.95
+    capture_return_value=True       # Required to save the result
+)
+def summarize_document(document_text: str):
+    # Simulate an LLM call or heavy computation (e.g., 0.5 sec delay)
+    time.sleep(0.5)
+    print("--- [Cache Miss] Document is being summarized by LLM...")
+    return f"Summary of: {document_text[:20]}..."
+
+# First call (Cache Miss) - takes ~0.5s, saves result to DB
+result_1 = summarize_document("The first quarter results showed strong growth in Europe and Asia...")
+
+# Second call (Cache Hit) - takes ~0.0s, returns cached value
+# "Q1 results" is semantically similar to "first quarter results"
+result_2 = summarize_document("The Q1 results demonstrated strong growth in Europe and Asia...") 
+
+# result_2 returns the stored value without executing the function's body.
+```
+
 ### 3\. [Retrieval ①] Search Function Definitions (for RAG)
 
 ```python
@@ -160,7 +193,12 @@ You can select the text vectorization method via the `VECTORIZER` environment va
 | **`weaviate_module`** | (Docker Delegate) Delegates vectorization to Weaviate's built-in module (e.g., `text2vec-openai`). | `WEAVIATE_VECTORIZER_MODULE`, `OPENAI_API_KEY` |
 | **`none`** | Disables vectorization. Data is stored without vectors. | None |
 
------
+#### ⚠️ Semantic Caching Prerequisites and Configuration
+
+To use `semantic_cache=True`, the following conditions must be met:
+
+* **Vectorizer Required:** A **Python-based vectorizer** (`huggingface` or `openai_client`) must be configured in your environment (`VECTORIZER` environment variable). Caching is automatically disabled if set to `weaviate_module` or `none`.
+* **Return Value Capture:** The `capture_return_value` parameter is automatically set to `True` when `semantic_cache=True` is enabled.
 
 ### .env File Examples
 
@@ -241,8 +279,6 @@ FAILURE_MAPPING_FILE_PATH=.vectorwave_errors.json
 RUN_ID=test-run-001
 ```
 
------
-
 ### 🚀 Advanced Failure Tracing (Error Code)
 
 This enhances `VectorWaveExecutions` logs beyond a simple `status: "ERROR"`. An `error_code` property is added to the schema for granular failure analysis.
@@ -371,7 +407,6 @@ def other_function():
     pass
 ```
 
-
 1.  **Validation (Important):** Tags (global or function-specific) will **only** be saved to Weaviate if their key (e.g., `run_id`, `team`, `priority`) was first defined in the `.weaviate_properties` file (Step 1). Tags not defined in the schema are **ignored**, and a warning is logged at startup.
 
 2.  **Priority (Override):** If a tag key is defined in both places (e.g., global `RUN_ID` in `.env` and `run_id="override-xyz"` in the decorator), the **function-specific tag from the decorator always wins**.
@@ -388,6 +423,7 @@ def other_function():
 Beyond just logging, `VectorWave` can send **real-time notifications via webhook** the instant an error occurs. This functionality is built directly into the tracer and can be activated simply by updating your `.env` file.
 
 **How it Works:**
+
 1.  An exception is raised within a function decorated by `@trace_span` or `@vectorize`.
 2.  The tracer catches the exception in its `except` block and immediately calls the `alerter` object.
 3.  The alerter reads the `.env` configuration and uses the `WebhookAlerter` to dispatch the error details to your specified URL.
@@ -407,8 +443,6 @@ ALERTER_WEBHOOK_URL="[https://discord.com/api/webhooks/YOUR_HOOK_ID/](https://di
 With just these two lines, running test_ex/example.py will now instantly send a Discord alert when the CustomValueError is raised.
 
 Extensibility (Strategy Pattern): The alerting system is built on a Strategy Pattern. You can easily extend it by implementing the BaseAlerter interface to support other channels like email, PagerDuty, or more.
-
-**Tag Merging and Validation Rules**
 ```
 
 ## 🤝 Contributing

{vectorwave-0.1.5 → vectorwave-0.1.7}/pyproject.toml

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

{vectorwave-0.1.5 → vectorwave-0.1.7}/src/tests/batch/test_batch.py

@@ -1,4 +1,4 @@
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, call, ANY
 
 import pytest
 from vectorwave.batch.batch import get_batch_manager
@@ -23,6 +23,9 @@ def mock_deps(monkeypatch):
     mock_collection.data = mock_collection_data
     mock_client.collections.get = MagicMock(return_value=mock_collection)
 
+    mock_batch_context = MagicMock()
+    mock_client.batch.dynamic.return_value.__enter__.return_value = mock_batch_context
+
     # Mock get_weaviate_client
     mock_get_client = MagicMock(return_value=mock_client)
     monkeypatch.setattr("vectorwave.batch.batch.get_weaviate_client", mock_get_client)
@@ -36,6 +39,9 @@ def mock_deps(monkeypatch):
     mock_atexit_register = MagicMock()
     monkeypatch.setattr("atexit.register", mock_atexit_register)
 
+    mock_thread = MagicMock()
+    monkeypatch.setattr("threading.Thread", mock_thread)
+
     # Clear lru_cache
     get_batch_manager.cache_clear()
 
@@ -44,7 +50,8 @@ def mock_deps(monkeypatch):
         "get_settings": mock_get_settings,
         "client": mock_client,
         "settings": mock_settings,
-        "atexit": mock_atexit_register
+        "atexit": mock_atexit_register,
+        "batch_context": mock_batch_context
     }
 
 def test_get_batch_manager_is_singleton(mock_deps):
@@ -80,19 +87,75 @@ def test_batch_manager_init_failure(monkeypatch):
     # The _initialized flag should be False if initialization fails
     assert manager._initialized is False
 
-def test_add_object_calls_client_batch(mock_deps):
+def test_add_object_enqueues_item(mock_deps):
     """
-    Case 4: Test if add_object() correctly calls client.batch.add_object
+    [Updated] Case 4: Test if add_object() puts the item into the local queue (Non-blocking)
+    Instead of calling client directly.
     """
     manager = get_batch_manager()
     props = {"key": "value"}
 
-    manager.add_object(collection="TestCollection", properties=props, uuid="test-uuid")
+    assert manager.queue.empty()
+
+    manager.add_object(collection="TestCollection", properties=props, uuid="test-uuid", vector=[0.1])
+
+    # 1. Should NOT call DB directly
+    mock_deps["client"].collections.get.assert_not_called()
+
+    # 2. Should be in the Queue
+    assert manager.queue.qsize() == 1
+    item = manager.queue.get()
+
+    assert item["collection"] == "TestCollection"
+    assert item["properties"] == props
+    assert item["uuid"] == "test-uuid"
+    assert item["vector"] == [0.1]
+
+def test_flush_batch_sends_to_weaviate(mock_deps):
+    """
+    [New] Case 5: Test if _flush_batch sends items using client.batch.dynamic context
+    """
+    manager = get_batch_manager()
+
+    items = [
+        {"collection": "C1", "properties": {"p": 1}, "uuid": "u1", "vector": None},
+        {"collection": "C2", "properties": {"p": 2}, "uuid": "u2", "vector": [1.0]}
+    ]
+
+    # Manually trigger flush
+    manager._flush_batch(items)
+
+    # Check if dynamic batch context was entered
+    mock_deps["client"].batch.dynamic.assert_called_once()
+
+    # Check if batch.add_object was called for each item
+    mock_batch_ctx = mock_deps["batch_context"]
+    assert mock_batch_ctx.add_object.call_count == 2
+
+    mock_batch_ctx.add_object.assert_has_calls([
+        call(collection="C1", properties={"p": 1}, uuid="u1", vector=None),
+        call(collection="C2", properties={"p": 2}, uuid="u2", vector=[1.0])
+    ])
+
+def test_flush_batch_reconnects_if_disconnected(mock_deps):
+    """
+    [New] Case 6: Test reconnection logic when client is not initialized
+    """
+    manager = get_batch_manager()
+
+    # Simulate disconnection
+    manager._initialized = False
+    manager.client = None
+
+    # Reset mocks
+    mock_deps["get_client"].reset_mock()
+
+    items = [{"collection": "C1", "properties": {}, "uuid": "u1", "vector": None}]
 
-    mock_deps["client"].collections.get.assert_called_once_with("TestCollection")
+    # Trigger flush
+    manager._flush_batch(items)
 
-    mock_deps["client"].collections.get.return_value.data.insert.assert_called_once_with(
-        properties=props,
-        uuid="test-uuid",
-        vector=None
-)
+    # Should try to reconnect
+    mock_deps["get_client"].assert_called_once()
+    # And then send
+    mock_deps["client"].batch.dynamic.assert_called_once()

vectorwave-0.1.7/src/tests/conftest.py

@@ -0,0 +1,27 @@
+import pytest
+import os
+import logging
+
+CACHE_FILE_PATH = ".vectorwave_functions_cache.json"
+logger = logging.getLogger(__name__)
+
+
+def _delete_cache():
+    """Helper function to remove the cache file if it exists."""
+    if os.path.exists(CACHE_FILE_PATH):
+        try:
+            os.remove(CACHE_FILE_PATH)
+        except OSError as e:
+            print(f"\n[CacheFixture Error] Failed to remove {CACHE_FILE_PATH}: {e}")
+
+
+@pytest.fixture(autouse=True, scope="function")
+def atomic_function_cache():
+    # --- SETUP (Before Test) ---
+    _delete_cache()
+
+    # --- Run the test ---
+    yield
+
+    # --- TEARDOWN (After Test) ---
+    _delete_cache()