vectorwave 1.0.2__cp313-cp313-win_amd64.whl

vectorwave/__init__.py

@@ -0,0 +1,35 @@
+from . import runtime as _runtime
+# Light up the visible indicator (stderr banner + PID file) on first import.
+# Silence with VECTORWAVE_QUIET=1.
+_runtime.activate()
+
+from .core.decorator import vectorize
+from .database.db import initialize_database, update_database_schema
+from .database.db_search import search_functions, search_executions, search_errors_by_message, search_functions_hybrid
+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
+from .database.dataset import VectorWaveDatasetManager
+from .core.auto_injector import VectorWaveAutoInjector
+
+__all__ = [
+    'vectorize',
+    'initialize_database',
+    'search_functions',
+    'search_functions_hybrid',
+    'search_executions',
+    'search_errors_by_message',
+    'trace_span',
+    'search_and_answer',
+    'analyze_trace_log',
+    'generate_and_register_metadata',
+    'VectorWaveHealer',
+    'VectorWaveReplayer',
+    'SemanticReplayer',
+    'VectorWaveDatasetManager',
+    'VectorWaveAutoInjector',
+    'update_database_schema'
+]

vectorwave/batch/batch.py

@@ -0,0 +1,257 @@
+import os
+import weaviate
+import atexit
+import logging
+import threading
+import queue
+import time
+from functools import lru_cache
+from typing import Optional, List, Dict, Any
+
+from ..models.db_config import get_weaviate_settings, WeaviateSettings
+from ..database.db import get_weaviate_client
+
+# Rust Core 모듈 Import 시도
+
+
+logger = logging.getLogger(__name__)
+
+try:
+    from vectorwave.vectorwave_core import RustBatchManager
+    USE_RUST_CORE = True
+except ImportError:
+    USE_RUST_CORE = False
+
+class WeaviateBatchManager:
+    """
+    Manages Weaviate batch imports.
+    Uses High-Performance Rust Core if available, otherwise falls back to Python.
+    """
+
+    def __init__(self, host: Optional[str] = None, port: Optional[int] = None,
+                 grpc_port: Optional[int] = None, api_key: Optional[str] = None):
+        self._initialized = False
+        self._shutdown_done = False
+        self.settings: WeaviateSettings = get_weaviate_settings()
+        self.client: Optional[weaviate.WeaviateClient] = None
+
+        # Lite mode (LanceDB local file store) skips the Weaviate client entirely.
+        # When VECTORWAVE_MODE=lite, _flush_batch_core delegates to the
+        # configured VectorStore so no Docker / Weaviate connection is needed.
+        self._lite_mode = os.environ.get("VECTORWAVE_MODE", "pro").lower() == "lite"
+
+        # Store dynamic connection params
+        self._host = host
+        self._port = port
+        self._grpc_port = grpc_port
+        self._api_key = api_key
+
+        # Batch Configuration
+        self.batch_threshold = self.settings.BATCH_THRESHOLD
+        self.flush_interval = self.settings.FLUSH_INTERVAL_SECONDS
+
+        # Connect to DB
+        self._connect_client()
+
+        if USE_RUST_CORE:
+            logger.info(f"🚀 [VectorWave] Rust Core Activated! (Threshold: {self.batch_threshold}, Interval: {self.flush_interval}s)")
+            self._rust_manager = RustBatchManager(
+                self._flush_batch_core,
+                self.batch_threshold,
+                int(self.flush_interval * 1000) # ms 단위 변환
+            )
+            self._worker_thread = None
+        else:
+            logger.warning("⚠️ [VectorWave] Rust Core not found. Using slower Python implementation.")
+            # --- Legacy Python Implementation ---
+            self.queue = queue.Queue(maxsize=10000)
+            self._stop_event = threading.Event()
+            self._start_python_worker()
+
+        # Register shutdown handler
+        atexit.register(self.shutdown)
+
+    def _connect_client(self):
+        """Attempts to connect to the configured backend (Weaviate or Lite store)."""
+        if self._lite_mode:
+            try:
+                from ..store import get_vector_store
+                store = get_vector_store()
+                if store.is_ready():
+                    self._initialized = True
+                    self.client = None  # not used in Lite mode
+            except Exception as e:
+                logger.warning(f"Lite store init failed: {e}")
+                self._initialized = False
+            return
+
+        try:
+            if self._host is not None:
+                self.client = get_weaviate_client(
+                    host=self._host, port=self._port,
+                    grpc_port=self._grpc_port, api_key=self._api_key
+                )
+            else:
+                self.client = get_weaviate_client(self.settings)
+            if self.client:
+                self._initialized = True
+        except Exception as e:
+            logger.warning(f"Initial DB connection failed: {e}")
+            self._initialized = False
+
+    def _start_python_worker(self):
+        """Starts the legacy Python background thread."""
+        self._worker_thread = threading.Thread(target=self._python_worker_loop, daemon=True)
+        self._worker_thread.start()
+
+    def add_object(self, collection: str, properties: dict, uuid: str = None, vector: Optional[List[float]] = None):
+        """
+        [Public API] Adds an object to the batch queue.
+        """
+        if USE_RUST_CORE:
+
+            self._rust_manager.add_object(collection, properties, uuid, vector)
+        else:
+            # Python Legacy Queue
+            item = {
+                "collection": collection,
+                "properties": properties,
+                "uuid": uuid,
+                "vector": vector
+            }
+            try:
+                self.queue.put_nowait(item)
+            except queue.Full:
+                logger.warning("🚨 VectorWave Log Queue is FULL. Dropping log.")
+
+    def _flush_batch_core(self, items: List[Dict[str, Any]]):
+        """
+        The actual flush logic called by either Rust or Python worker.
+
+        In Pro mode (default) this uses Weaviate's bulk batch.dynamic() context.
+        In Lite mode it groups items by collection and calls
+        VectorStore.insert_many — LanceDB has no equivalent of Weaviate's
+        single-context bulk write, but per-collection batching is fine for the
+        Lite use case.
+        """
+        if not items:
+            return
+
+        # 1. Check/Retry Connection
+        if not self._initialized or (not self._lite_mode and not self.client):
+            self._connect_client()
+            if not self._initialized:
+                return
+
+        if self._lite_mode:
+            self._flush_via_store(items)
+            return
+
+        # 2. Send Batch via Weaviate Client (Pro mode)
+        try:
+            # Weaviate v4 batch context
+            with self.client.batch.dynamic() as batch:
+                for item in items:
+                    batch.add_object(
+                        collection=item['collection'],
+                        properties=item['properties'],
+                        uuid=item.get('uuid'),
+                        vector=item.get('vector')
+                    )
+
+            if len(self.client.batch.failed_objects) > 0:
+                for failed in self.client.batch.failed_objects:
+                    logger.error(f"⚠️ Batch Item Failed: {failed.message}")
+
+        except RuntimeError:
+            return
+        except Exception as e:
+            msg = str(e).lower()
+            if "shutdown" in msg or "closed" in msg:
+                return
+            logger.error(f"❌ Batch Flush Error: {e}")
+
+    def _flush_via_store(self, items: List[Dict[str, Any]]):
+        """Lite-mode flush: route items through the VectorStore abstraction."""
+        from ..store import get_vector_store
+        try:
+            store = get_vector_store()
+        except Exception as e:
+            logger.error(f"❌ Lite store unavailable: {e}")
+            return
+        by_collection: Dict[str, List[Dict[str, Any]]] = {}
+        for item in items:
+            by_collection.setdefault(item["collection"], []).append({
+                "properties": item["properties"],
+                "uuid": item.get("uuid"),
+                "vector": item.get("vector"),
+            })
+        for collection, batch in by_collection.items():
+            try:
+                # Lite stores create tables lazily, but ensure the schema exists
+                # so writes don't fail with "table not found".
+                if not store.collection_exists(collection):
+                    store.ensure_collection(collection, properties=[])
+                store.insert_many(collection, batch)
+            except Exception as e:
+                logger.error(f"❌ Lite batch flush failed for '{collection}': {e}")
+
+    # --- Legacy Python Worker Methods (Only used if Rust is missing) ---
+    def _python_worker_loop(self):
+        pending_items = []
+        last_flush_time = time.time()
+
+        while not self._stop_event.is_set():
+            try:
+                item = self.queue.get(timeout=0.5)
+                pending_items.append(item)
+            except queue.Empty:
+                pass
+
+            current_time = time.time()
+            if len(pending_items) >= self.batch_threshold or (pending_items and current_time - last_flush_time >= self.flush_interval):
+                self._flush_batch_core(pending_items)
+                pending_items = []
+                last_flush_time = current_time
+
+    def shutdown(self):
+        """Gracefully shuts down. Idempotent — repeated calls are no-ops, so the
+        atexit handler firing after a test-time cache_clear cannot trigger a
+        second shutdown on an already-closed Rust worker or Weaviate client."""
+        if self._shutdown_done:
+            return
+        self._shutdown_done = True
+
+        if USE_RUST_CORE:
+            try:
+                self._rust_manager.shutdown()
+            except Exception as e:
+                logger.debug(f"Rust manager shutdown raised: {e}")
+        else:
+            if not self._stop_event.is_set():
+                self._stop_event.set()
+                if self._worker_thread and self._worker_thread.is_alive():
+                    self._worker_thread.join(timeout=1.0)
+
+                # Flush remaining items
+                remaining = []
+                while not self.queue.empty():
+                    remaining.append(self.queue.get_nowait())
+                if remaining:
+                    self._flush_batch_core(remaining)
+
+        # Close client
+        if self.client:
+            try:
+                self.client.close()
+            except Exception:
+                pass
+
+@lru_cache()
+def get_batch_manager(
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        grpc_port: Optional[int] = None,
+        api_key: Optional[str] = None
+) -> WeaviateBatchManager:
+    return WeaviateBatchManager(host=host, port=port, grpc_port=grpc_port, api_key=api_key)

vectorwave/check/__init__.py

@@ -0,0 +1,17 @@
+"""VectorWave Check: pytest plugin + CLI for semantic regression testing.
+
+Quick usage (declarative marker):
+
+    @pytest.mark.vectorwave(target="myapp.summarize", strategy="similarity", threshold=0.85)
+    def test_summarize_regression():
+        pass
+
+Quick usage (imperative fixture):
+
+    def test_summarize_regression(vw_replay):
+        result = vw_replay("myapp.summarize", strategy="similarity", threshold=0.85)
+        assert result.passed_all, result.report()
+"""
+from .plugin import ReplayResult
+
+__all__ = ["ReplayResult"]

vectorwave/check/calibrate.py

@@ -0,0 +1,358 @@
+"""Threshold calibration for the vectorwave-check pytest plugin.
+
+Two measurement modes:
+
+* **diversity** (default) — pull existing golden outputs for the target,
+  compute pairwise cosine similarity. Reports how diverse the function's
+  typical outputs are. No function calls, no side effects.
+* **rerun** — sample a few golden inputs, re-execute the function N times
+  per input, compute pairwise similarity within each input group. Reports
+  the function's intrinsic noise floor. Hits the function (and any APIs it
+  calls); skip for functions with side effects.
+
+Both modes emit the same shape so the downstream CLI / pyproject snippet
+generator can stay one path.
+"""
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import importlib
+import inspect
+import logging
+import math
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence
+
+logger = logging.getLogger(__name__)
+
+
+PERCENTILES = (5, 10, 25, 50, 75, 95)
+
+
+@dataclass
+class CalibrationResult:
+    function: str
+    mode: str
+    sample_count: int  # how many goldens (diversity) / inputs sampled (rerun)
+    pair_count: int    # how many similarity pairs computed
+    percentiles: Dict[int, float] = field(default_factory=dict)
+    recommended_threshold: Optional[float] = None
+    recommended_strategy: str = "similarity"
+    notes: List[str] = field(default_factory=list)
+    vectorizer_name: Optional[str] = None
+
+
+def _cosine(v1: Sequence[float], v2: Sequence[float]) -> float:
+    dot = 0.0
+    n1 = 0.0
+    n2 = 0.0
+    for a, b in zip(v1, v2):
+        dot += a * b
+        n1 += a * a
+        n2 += b * b
+    if n1 == 0 or n2 == 0:
+        return 0.0
+    return dot / (math.sqrt(n1) * math.sqrt(n2))
+
+
+def _percentile(sorted_values: List[float], p: int) -> float:
+    if not sorted_values:
+        return 0.0
+    if len(sorted_values) == 1:
+        return sorted_values[0]
+    # linear interpolation between closest ranks
+    k = (len(sorted_values) - 1) * p / 100.0
+    lo = int(math.floor(k))
+    hi = int(math.ceil(k))
+    if lo == hi:
+        return sorted_values[lo]
+    return sorted_values[lo] + (sorted_values[hi] - sorted_values[lo]) * (k - lo)
+
+
+def _pairwise_similarities(embeddings: List[Sequence[float]]) -> List[float]:
+    out: List[float] = []
+    for i in range(len(embeddings)):
+        for j in range(i + 1, len(embeddings)):
+            out.append(_cosine(embeddings[i], embeddings[j]))
+    return out
+
+
+def _embed_all(vectorizer, texts: List[str]) -> List[Sequence[float]]:
+    if hasattr(vectorizer, "embed_batch"):
+        try:
+            return vectorizer.embed_batch(texts)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("embed_batch failed (%s); falling back to per-text embed", e)
+    return [vectorizer.embed(t) for t in texts]
+
+
+def _summarize(
+    function: str,
+    mode: str,
+    sample_count: int,
+    similarities: List[float],
+    vectorizer_name: Optional[str],
+) -> CalibrationResult:
+    sims_sorted = sorted(similarities)
+    percentiles = {p: _percentile(sims_sorted, p) for p in PERCENTILES}
+
+    notes: List[str] = []
+    rec_threshold = percentiles.get(5)
+    rec_strategy = "similarity"
+
+    if not sims_sorted:
+        notes.append("No similarity pairs were computed — recommendation not available.")
+        rec_threshold = None
+    else:
+        p5 = percentiles[5]
+        p95 = percentiles[95]
+        if p5 > 0.99 and p95 > 0.99:
+            rec_strategy = "exact"
+            rec_threshold = None
+            notes.append(
+                "Function appears deterministic (p5 and p95 both >0.99). "
+                "Use `strategy=\"exact\"` instead of similarity."
+            )
+        elif p5 < 0.6:
+            rec_strategy = "llm"
+            notes.append(
+                f"Function is highly variable (p5={p5:.3f} < 0.6). "
+                "Similarity threshold will be noisy; consider `strategy=\"llm\"` "
+                "(LLM-as-a-judge) for more robust regression detection."
+            )
+
+    return CalibrationResult(
+        function=function,
+        mode=mode,
+        sample_count=sample_count,
+        pair_count=len(similarities),
+        percentiles=percentiles,
+        recommended_threshold=rec_threshold,
+        recommended_strategy=rec_strategy,
+        notes=notes,
+        vectorizer_name=vectorizer_name,
+    )
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    try:
+        import json
+        return json.dumps(value, sort_keys=True, default=str)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+def _run_coroutine_safely(coro):
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+        return executor.submit(asyncio.run, coro).result()
+
+
+def _vectorizer_name(vectorizer) -> Optional[str]:
+    if vectorizer is None:
+        return None
+    return type(vectorizer).__name__
+
+
+# ---------------------------------------------------------------------------
+# Mode 1: diversity (cheap, default)
+# ---------------------------------------------------------------------------
+
+def _calibrate_diversity(function_full_name: str, samples: int) -> CalibrationResult:
+    from ..models.db_config import get_weaviate_settings
+    from ..store import get_vector_store
+    from ..utils.serialization import deserialize_return_value
+    from ..vectorizer.factory import get_vectorizer
+
+    func_short_name = function_full_name.rsplit(".", 1)[-1]
+    settings = get_weaviate_settings()
+    store = get_vector_store()
+    vectorizer = get_vectorizer()
+    if vectorizer is None:
+        raise RuntimeError(
+            "Calibration requires a local vectorizer (VECTORIZER=huggingface or openai_client). "
+            "Server-side vectorization (weaviate_module) cannot embed offline."
+        )
+
+    records = store.query(
+        collection=settings.GOLDEN_COLLECTION_NAME,
+        filters={"function_name": func_short_name},
+        limit=samples,
+    )
+
+    outputs: List[str] = []
+    for rec in records:
+        raw = rec.properties.get("return_value")
+        deserialized = deserialize_return_value(raw)
+        outputs.append(_stringify(deserialized))
+
+    if len(outputs) < 2:
+        raise RuntimeError(
+            f"Need at least 2 golden samples for '{function_full_name}', found {len(outputs)}. "
+            "Run the function a few times in production / replay-capture mode first, "
+            "or mark known-good executions as Golden."
+        )
+
+    embeddings = _embed_all(vectorizer, outputs)
+    similarities = _pairwise_similarities(embeddings)
+
+    return _summarize(
+        function=function_full_name,
+        mode="diversity",
+        sample_count=len(outputs),
+        similarities=similarities,
+        vectorizer_name=_vectorizer_name(vectorizer),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Mode 2: rerun (honest noise floor, opt-in)
+# ---------------------------------------------------------------------------
+
+def _calibrate_rerun(
+    function_full_name: str,
+    samples: int,
+    runs: int,
+) -> CalibrationResult:
+    from ..models.db_config import get_weaviate_settings
+    from ..utils.replayer import VectorWaveReplayer
+    from ..vectorizer.factory import get_vectorizer
+
+    module_name, func_short_name = function_full_name.rsplit(".", 1)
+    module = importlib.import_module(module_name)
+    target_func = getattr(module, func_short_name)
+    is_async = inspect.iscoroutinefunction(target_func)
+
+    get_weaviate_settings()  # surface config errors early
+    vectorizer = get_vectorizer()
+    if vectorizer is None:
+        raise RuntimeError(
+            "Calibration requires a local vectorizer (VECTORIZER=huggingface or openai_client)."
+        )
+
+    helper = VectorWaveReplayer()
+    candidates = helper._fetch_test_candidates(func_short_name, limit=samples)
+    if not candidates:
+        raise RuntimeError(
+            f"No golden samples or execution logs found for '{function_full_name}'. "
+            "Rerun calibration needs at least one captured input."
+        )
+
+    all_similarities: List[float] = []
+    sampled = candidates[:samples]
+    for cand in sampled:
+        raw_inputs = cand["inputs"]
+        inputs = helper._extract_inputs(raw_inputs, target_func)
+        outputs: List[str] = []
+        for _ in range(runs):
+            try:
+                if is_async:
+                    out = _run_coroutine_safely(target_func(**inputs))
+                else:
+                    out = target_func(**inputs)
+            except Exception as e:  # noqa: BLE001
+                logger.warning("Calibration run raised %s; skipping this run", e)
+                continue
+            outputs.append(_stringify(out))
+        if len(outputs) >= 2:
+            embeddings = _embed_all(vectorizer, outputs)
+            all_similarities.extend(_pairwise_similarities(embeddings))
+
+    if not all_similarities:
+        raise RuntimeError(
+            "Rerun calibration produced no usable comparisons "
+            "(function raised every time, or only one successful run per input). "
+            "Inspect the function's behavior manually."
+        )
+
+    return _summarize(
+        function=function_full_name,
+        mode="rerun",
+        sample_count=len(sampled),
+        similarities=all_similarities,
+        vectorizer_name=_vectorizer_name(vectorizer),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def calibrate(
+    function_full_name: str,
+    *,
+    rerun: bool = False,
+    samples: Optional[int] = None,
+    runs: int = 10,
+) -> CalibrationResult:
+    """Compute a threshold recommendation for `function_full_name`.
+
+    Args:
+        function_full_name: Fully-qualified target, e.g. `myapp.summarize`.
+        rerun: If True, sample inputs and re-execute the function. Hits APIs
+            and triggers any side effects. If False (default), only pull
+            existing golden outputs and measure diversity — no side effects.
+        samples: Number of goldens to pull (diversity) or inputs to sample
+            (rerun). Defaults to 30 for diversity, 3 for rerun.
+        runs: Re-executions per sampled input. Only used in rerun mode.
+    """
+    if rerun:
+        effective_samples = samples if samples is not None else 3
+        return _calibrate_rerun(function_full_name, samples=effective_samples, runs=runs)
+    effective_samples = samples if samples is not None else 30
+    return _calibrate_diversity(function_full_name, samples=effective_samples)
+
+
+# ---------------------------------------------------------------------------
+# Rendering for CLI
+# ---------------------------------------------------------------------------
+
+def format_pyproject_snippet(result: CalibrationResult) -> str:
+    if result.recommended_strategy == "exact":
+        return (
+            f'[tool.vectorwave.check."{result.function}"]\n'
+            f'strategy = "exact"\n'
+        )
+    threshold = result.recommended_threshold or 0.85
+    return (
+        f'[tool.vectorwave.check."{result.function}"]\n'
+        f'strategy = "{result.recommended_strategy}"\n'
+        f"threshold = {threshold:.3f}\n"
+    )
+
+
+def format_report(result: CalibrationResult) -> str:
+    lines = [
+        f"Calibration for '{result.function}' "
+        f"(mode={result.mode}, vectorizer={result.vectorizer_name or 'n/a'})",
+        f"  samples={result.sample_count}, pairs={result.pair_count}",
+        "",
+    ]
+    for p in PERCENTILES:
+        v = result.percentiles.get(p)
+        if v is not None:
+            lines.append(f"  p{p:<3} {v:.4f}")
+    lines.append("")
+    if result.recommended_threshold is None and result.recommended_strategy == "exact":
+        lines.append("Recommended strategy: exact (no threshold needed)")
+    else:
+        lines.append(
+            f"Recommended: strategy={result.recommended_strategy}, "
+            f"threshold={result.recommended_threshold:.4f}"
+        )
+    if result.notes:
+        lines.append("")
+        for note in result.notes:
+            lines.append(f"  note: {note}")
+    lines.append("")
+    lines.append("Add to pyproject.toml:")
+    lines.append("")
+    for ln in format_pyproject_snippet(result).splitlines():
+        lines.append(f"  {ln}")
+    return "\n".join(lines)