@ngocsangairvds/vsaf 3.2.13 → 3.2.15

package/tools/vds-scripts/audit_orchestrator/src/vds_audit_orchestrator/agents/toolsets/vector_evidence.py

@@ -1,842 +0,0 @@
-"""State-backed vector evidence toolset for agentic investigations.
-
-Provides read-only hybrid/vector retrieval over centralized-state corpus chunks.
-"""
-
-from __future__ import annotations
-
-import os
-import re
-from datetime import datetime
-from typing import TYPE_CHECKING, Any
-
-from pydantic_ai.toolsets import FunctionToolset
-from structlog import get_logger
-from vds_platform_core.credentials import resolve_secret
-
-from vds_audit_orchestrator.config import get_config
-from vds_audit_orchestrator.evidence.embedding_client import OllamaEmbeddingClient
-from vds_audit_orchestrator.state.store import PostgresStateStore
-
-if TYPE_CHECKING:
-    from pydantic_ai import RunContext
-
-logger = get_logger()
-
-_STATE_DSN_ENV_VAR = "VDS_AUDIT_STATE_DSN"
-
-
-def _get_agentic_settings(ctx: RunContext[Any]) -> dict[str, Any]:
-    deps = getattr(ctx, "deps", None)
-    settings = getattr(deps, "settings", None)
-    if not isinstance(settings, dict):
-        return {}
-    agentic = settings.get("agentic")
-    return agentic if isinstance(agentic, dict) else {}
-
-
-def _vector_search_signature(
-    tool_name: str,
-    query: str,
-    *,
-    limit: int,
-    project_key: str | None,
-    repo_key: str | None,
-) -> str:
-    normalized_query = str(query or "").strip()
-    normalized_project = str(project_key or "").strip()
-    normalized_repo = str(repo_key or "").strip()
-    return f"{tool_name}:{normalized_query}|{limit}|{normalized_project}|{normalized_repo}"
-
-
-def _get_state_context(ctx: RunContext[Any]) -> dict[str, Any]:
-    deps = getattr(ctx, "deps", None)
-    settings = getattr(deps, "settings", None)
-    if isinstance(settings, dict):
-        state_context = settings.get("state_context")
-        if isinstance(state_context, dict):
-            return state_context
-    return {}
-
-
-def _first_non_empty(*values: object) -> str:
-    for value in values:
-        if isinstance(value, str):
-            text = value.strip()
-            if text:
-                return text
-    return ""
-
-
-def _resolve_state_dsn(state_context: dict[str, Any]) -> str:
-    return _first_non_empty(state_context.get("state_dsn"), os.getenv(_STATE_DSN_ENV_VAR, ""))
-
-
-def _infer_project_key_from_corpus(ctx: RunContext[Any]) -> str:
-    deps = getattr(ctx, "deps", None)
-    corpus = getattr(deps, "evidence_corpus", None)
-    documents = getattr(corpus, "documents", None)
-    if not isinstance(documents, list):
-        return ""
-
-    for doc in documents:
-        source_path = str(getattr(doc, "source_path", "") or "")
-        # Typical layout: <evidence-dir>/docs/<project_storage_key>/...
-        match = re.search(r"/docs/([^/]+)/", source_path)
-        if match and match.group(1).strip():
-            return match.group(1).strip()
-    return ""
-
-
-def _resolve_project_key(ctx: RunContext[Any], state_context: dict[str, Any], project_key: str | None) -> str:
-    return _first_non_empty(
-        project_key,
-        state_context.get("project_storage_key"),
-        state_context.get("project_key"),
-        state_context.get("project_id"),
-        _infer_project_key_from_corpus(ctx),
-        getattr(getattr(ctx, "deps", None), "project_id", ""),
-    )
-
-
-def _resolve_repo_key(state_context: dict[str, Any], repo_key: str | None) -> str | None:
-    resolved = _first_non_empty(
-        repo_key,
-        state_context.get("repo_storage_key"),
-        state_context.get("repo_key"),
-    )
-    return resolved or None
-
-
-def _coerce_snapshot_int(value: object) -> int:
-    if isinstance(value, int):
-        return max(0, value)
-    if isinstance(value, str):
-        text = value.strip()
-        if text.isdigit():
-            return int(text)
-    return 0
-
-
-def _snapshot_selection_score(snapshot: dict[str, Any]) -> tuple[int, int, int, int, int, float]:
-    key = _first_non_empty(snapshot.get("snapshot_key")).casefold()
-    if key.endswith("project_corpus"):
-        key_priority = 3
-    elif key.endswith("smoke_probe"):
-        key_priority = 1
-    else:
-        key_priority = 2
-    lexical_priority = 0 if bool(snapshot.get("lexical_only", False)) else 1
-    chunk_count = _coerce_snapshot_int(snapshot.get("chunk_count"))
-    changed_chunk_count = _coerce_snapshot_int(snapshot.get("changed_chunk_count"))
-    state_version = _coerce_snapshot_int(snapshot.get("state_version"))
-    updated_raw = snapshot.get("updated_at")
-    updated_ts = updated_raw.timestamp() if isinstance(updated_raw, datetime) else 0.0
-    return (
-        lexical_priority,
-        key_priority,
-        chunk_count + changed_chunk_count,
-        chunk_count,
-        state_version,
-        updated_ts,
-    )
-
-
-def _load_latest_snapshot(
-    store: PostgresStateStore,
-    *,
-    project_key: str,
-    repo_key: str | None,
-) -> tuple[dict[str, Any] | None, str | None]:
-    """Load latest retrieval snapshot for the exact requested scope.
-
-    This helper is strict by design: it never relaxes repo scope to project scope.
-    """
-
-    def _validate_snapshot(
-        snapshot: dict[str, Any],
-        *,
-        expected_project_key: str,
-        expected_repo_key: str | None,
-    ) -> bool:
-        snapshot_project_key = _first_non_empty(snapshot.get("project_key"))
-        snapshot_repo_key = _first_non_empty(snapshot.get("repo_key")) or None
-        if snapshot_project_key != expected_project_key:
-            logger.warning(
-                "vector_snapshot_scope_mismatch",
-                requested_project_key=expected_project_key,
-                requested_repo_key=expected_repo_key,
-                snapshot_project_key=snapshot_project_key,
-                snapshot_repo_key=snapshot_repo_key,
-            )
-            return False
-        if snapshot_repo_key != expected_repo_key:
-            logger.warning(
-                "vector_snapshot_scope_mismatch",
-                requested_project_key=expected_project_key,
-                requested_repo_key=expected_repo_key,
-                snapshot_project_key=snapshot_project_key,
-                snapshot_repo_key=snapshot_repo_key,
-            )
-            return False
-        return True
-
-    snapshots = store.list_retrieval_snapshots(project_key=project_key, repo_key=repo_key, limit=50)
-    if snapshots:
-        snapshot = max(snapshots, key=_snapshot_selection_score)
-        if _validate_snapshot(
-            snapshot,
-            expected_project_key=project_key,
-            expected_repo_key=repo_key,
-        ):
-            return snapshot, repo_key
-
-    return None, repo_key
-
-
-def _resolve_embedding_client() -> OllamaEmbeddingClient:
-    config = get_config()
-    embedding_api_key = getattr(config.embedding, "api_key", None)
-    embedding_api_key_value = resolve_secret(embedding_api_key)
-    base_url = (
-        str(config.embedding.base_url or "").strip()
-        or str(config.llm.base_url or "").strip()
-        or "http://127.0.0.1:11434"
-    )
-    return OllamaEmbeddingClient(
-        base_url=base_url,
-        model=config.embedding.model,
-        api_key=embedding_api_key_value,
-        timeout_seconds=config.embedding.timeout_seconds,
-        batch_size=config.embedding.batch_size,
-        retries=config.embedding.retries,
-    )
-
-
-def _summarize_result(index: int, row: dict[str, Any], query: str) -> str:
-    content = str(row.get("content_text") or "").strip().replace("\n", " ")
-    if query:
-        query_lower = query.lower()
-        pos = content.lower().find(query_lower)
-        if pos >= 0:
-            start = max(0, pos - 120)
-            content = content[start : start + 280]
-    snippet = content[:280] or "<empty>"
-    source_uri = str(row.get("source_uri") or "").strip() or "<none>"
-    page_id = str(row.get("page_id") or "").strip() or "<none>"
-    return (
-        f"{index}. doc={row.get('document_id')} chunk={row.get('chunk_id')} "
-        f"rrf={float(row.get('rrf_score', 0.0)):.4f} "
-        f"lexical_rank={row.get('lexical_rank')} vector_rank={row.get('vector_rank')}\n"
-        f"   source_uri={source_uri} page_id={page_id}\n"
-        f"   snippet={snippet}..."
-    )
-
-
-def _extract_query_terms(query: str) -> list[str]:
-    stopwords = {
-        "and",
-        "for",
-        "with",
-        "the",
-        "from",
-        "that",
-        "this",
-        "và",
-        "va",
-        "cho",
-        "với",
-        "voi",
-        "của",
-        "cua",
-    }
-    terms: list[str] = []
-    for token in re.findall(r"\w+", str(query or "").lower(), flags=re.UNICODE):
-        if len(token) < 4 or token in stopwords or token.isdigit():
-            continue
-        if token not in terms:
-            terms.append(token)
-    return terms[:8]
-
-
-def _build_query_variants(query: str) -> list[str]:
-    normalized = str(query or "").strip()
-    if not normalized:
-        return []
-    variants = [normalized]
-    terms = _extract_query_terms(normalized)
-    for term in terms[:2]:
-        if term not in variants:
-            variants.append(term)
-    if len(terms) >= 2:
-        phrase = f"{terms[0]} {terms[1]}".strip()
-        if phrase and phrase not in variants:
-            variants.append(phrase)
-    return variants[:4]
-
-
-def _coverage_ratio(*, query_terms: list[str], row: dict[str, Any]) -> float:
-    if not query_terms:
-        return 0.0
-    haystack = " ".join(
-        [
-            str(row.get("content_text") or ""),
-            str(row.get("source_uri") or ""),
-            str(row.get("document_id") or ""),
-        ]
-    ).lower()
-    hits = sum(1 for term in query_terms if term in haystack)
-    return float(hits) / float(len(query_terms))
-
-
-def _rank_hybrid_result(
-    *,
-    query_terms: list[str],
-    row: dict[str, Any],
-    variant_weight: float,
-) -> float:
-    rrf_score = max(0.0, min(1.0, float(row.get("rrf_score") or 0.0)))
-    coverage = _coverage_ratio(query_terms=query_terms, row=row)
-    return max(0.0, min(1.0, (0.55 * rrf_score) + (0.30 * coverage) + (0.15 * variant_weight)))
-
-
-def _result_identity(row: dict[str, Any]) -> tuple[str, str]:
-    document_id = str(row.get("document_id") or "").strip() or "<unknown_doc>"
-    chunk_id = str(row.get("chunk_id") or "").strip() or "<unknown_chunk>"
-    return document_id, chunk_id
-
-
-def _source_identity(row: dict[str, Any]) -> str:
-    source_uri = str(row.get("source_uri") or "").strip()
-    if source_uri:
-        return source_uri
-    return str(row.get("document_id") or "").strip() or "<unknown_source>"
-
-
-def _select_diversified_results(
-    *,
-    ranked_rows: list[dict[str, Any]],
-    top_k: int,
-) -> list[dict[str, Any]]:
-    if len(ranked_rows) <= top_k:
-        return ranked_rows
-
-    selected: list[dict[str, Any]] = []
-    per_source_counts: dict[str, int] = {}
-    max_per_source = 2
-
-    for row in ranked_rows:
-        source_key = _source_identity(row)
-        if per_source_counts.get(source_key, 0) >= max_per_source:
-            continue
-        selected.append(row)
-        per_source_counts[source_key] = per_source_counts.get(source_key, 0) + 1
-        if len(selected) >= top_k:
-            return selected
-
-    for row in ranked_rows:
-        if row in selected:
-            continue
-        selected.append(row)
-        if len(selected) >= top_k:
-            break
-    return selected
-
-
-def _is_code_scoped_result(row: dict[str, Any]) -> bool:
-    metadata = row.get("metadata")
-    metadata_dict = metadata if isinstance(metadata, dict) else {}
-    source_type = str(metadata_dict.get("source_type") or row.get("source_type") or "").strip().casefold()
-    doc_class = str(metadata_dict.get("doc_class") or "").strip().casefold()
-    source_uri = str(row.get("source_uri") or "").strip().casefold()
-    document_id = str(row.get("document_id") or "").strip().casefold()
-    if source_type in {"code_file", "code_evidence_pack", "bitbucket_readme", "code"}:
-        return True
-    if "code" in doc_class:
-        return True
-    if source_uri.startswith("repo://") or source_uri.startswith("bitbucket://"):
-        return True
-    return ":/" in document_id or ":" in document_id
-
-
-def _matches_scope(row: dict[str, Any], *, scope: str) -> bool:
-    normalized_scope = str(scope or "").strip().casefold()
-    if normalized_scope == "code":
-        return _is_code_scoped_result(row)
-    if normalized_scope == "docs":
-        return not _is_code_scoped_result(row)
-    return True
-
-
-async def _vector_retrieval_status(
-    ctx: RunContext[Any],
-    project_key: str | None = None,
-    repo_key: str | None = None,
-) -> str:
-    """Show vector retrieval readiness for current state context."""
-    state_context = _get_state_context(ctx)
-    state_dsn = _resolve_state_dsn(state_context)
-    if not state_dsn:
-        return f"[ERROR] Missing state DSN. Set {_STATE_DSN_ENV_VAR} or provide deps.settings.state_context.state_dsn"
-
-    resolved_project_key = _resolve_project_key(ctx, state_context, project_key)
-    if not resolved_project_key:
-        return "[ERROR] Missing project key for vector retrieval context."
-
-    resolved_repo_key = _resolve_repo_key(state_context, repo_key)
-
-    store = PostgresStateStore(state_dsn)
-    try:
-        diagnostics = store.vector_index_diagnostics()
-        snapshot, effective_repo_key = _load_latest_snapshot(
-            store,
-            project_key=resolved_project_key,
-            repo_key=resolved_repo_key,
-        )
-        project_docs_snapshot: dict[str, Any] | None = None
-        if resolved_repo_key is not None:
-            project_docs_snapshot, _ = _load_latest_snapshot(
-                store,
-                project_key=resolved_project_key,
-                repo_key=None,
-            )
-    finally:
-        store.close()
-
-    repo_display = resolved_repo_key or "<project>"
-    header = f"Vector retrieval status: project_key={resolved_project_key} repo_key={repo_display}"
-    scope_strict = effective_repo_key == resolved_repo_key
-    if not snapshot:
-        if resolved_repo_key is not None:
-            return (
-                f"{header}\n"
-                "snapshot_found=False\n"
-                f"scope_strict={scope_strict}\n"
-                f"project_docs_snapshot_found={bool(project_docs_snapshot)}\n"
-                f"vector_extension_ready={bool(diagnostics.get('extension_version_ok'))}\n"
-                f"vector_index_ready={bool(diagnostics.get('hnsw_index_ready') or diagnostics.get('ivfflat_index_ready'))}"
-            )
-        return (
-            f"{header}\n"
-            "snapshot_found=False\n"
-            f"scope_strict={scope_strict}\n"
-            f"vector_extension_ready={bool(diagnostics.get('extension_version_ok'))}\n"
-            f"vector_index_ready={bool(diagnostics.get('hnsw_index_ready') or diagnostics.get('ivfflat_index_ready'))}"
-        )
-
-    return (
-        f"{header}\n"
-        "snapshot_found=True\n"
-        f"scope_strict={scope_strict}\n"
-        f"project_docs_snapshot_found={bool(project_docs_snapshot) if resolved_repo_key is not None else False}\n"
-        f"effective_repo_key={effective_repo_key or '<project>'}\n"
-        f"snapshot_key={snapshot.get('snapshot_key')} snapshot_id={snapshot.get('id')}\n"
-        f"lexical_only={bool(snapshot.get('lexical_only'))} index_type={snapshot.get('index_type')}\n"
-        f"embedding_model={snapshot.get('embedding_model_name')} dims={snapshot.get('embedding_dimensions')}\n"
-        f"chunk_count={snapshot.get('chunk_count')}"
-    )
-
-
-async def _search_vector_scope(
-    ctx: RunContext[Any],
-    query: str = "",
-    limit: int = 5,
-    project_key: str | None = None,
-    repo_key: str | None = None,
-    *,
-    source_scope: str,
-) -> str:
-    """Run vector-backed hybrid retrieval over centralized-state evidence chunks."""
-    q = query.strip()
-    if not q:
-        return "[ERROR] query must not be empty"
-
-    state_context = _get_state_context(ctx)
-    state_dsn = _resolve_state_dsn(state_context)
-    if not state_dsn:
-        return f"[ERROR] Missing state DSN. Set {_STATE_DSN_ENV_VAR} or provide deps.settings.state_context.state_dsn"
-
-    resolved_project_key = _resolve_project_key(ctx, state_context, project_key)
-    if not resolved_project_key:
-        return "[ERROR] Missing project key for vector retrieval context."
-
-    resolved_repo_key = _resolve_repo_key(state_context, repo_key)
-    top_k = max(1, min(20, limit))
-    query_variants = _build_query_variants(q)
-    if not query_variants:
-        return "[ERROR] query must not be empty"
-    query_terms = _extract_query_terms(q)
-
-    embedding_client = _resolve_embedding_client()
-    try:
-        embedding_result = embedding_client.embed_texts(query_variants)
-    except Exception as exc:
-        logger.warning(
-            "vector_evidence_embedding_failed",
-            exception_type=type(exc).__name__,
-            exception_message=str(exc),
-            fallback_mode="non_vector",
-        )
-        return f"[ERROR] Failed to embed query for vector retrieval: {exc}"
-    if not embedding_result.vectors:
-        return "[ERROR] Failed to embed query for vector retrieval."
-    vectors = list(embedding_result.vectors)
-    if len(vectors) < len(query_variants):
-        query_variants = query_variants[: len(vectors)]
-    if not query_variants:
-        return "[ERROR] Failed to embed query for vector retrieval."
-
-    store = PostgresStateStore(state_dsn)
-    try:
-        snapshot, effective_repo_key = _load_latest_snapshot(
-            store,
-            project_key=resolved_project_key,
-            repo_key=resolved_repo_key,
-        )
-        search_repo_key = effective_repo_key
-        raw_snapshot_candidates: list[dict[str, Any]] = []
-        if snapshot:
-            raw_snapshot_candidates.append(snapshot)
-
-        if source_scope == "docs" and resolved_repo_key is not None:
-            project_snapshot, _ = _load_latest_snapshot(
-                store,
-                project_key=resolved_project_key,
-                repo_key=None,
-            )
-            if project_snapshot:
-                repo_snapshot_id = int(snapshot.get("id") or 0) if snapshot else 0
-                project_snapshot_id = int(project_snapshot.get("id") or 0)
-                if project_snapshot_id and (repo_snapshot_id == 0 or project_snapshot_id != repo_snapshot_id):
-                    raw_snapshot_candidates.append(project_snapshot)
-                    logger.info(
-                        "vector_docs_scope_includes_project_snapshot",
-                        project_key=resolved_project_key,
-                        repo_key=resolved_repo_key,
-                        repo_snapshot_id=repo_snapshot_id,
-                        project_snapshot_id=project_snapshot_id,
-                    )
-
-        if not raw_snapshot_candidates:
-            return (
-                f"[ERROR] No retrieval snapshot found for project_key={resolved_project_key} "
-                f"repo_key={resolved_repo_key or '<project>'}."
-            )
-
-        snapshot_candidates = [
-            candidate for candidate in raw_snapshot_candidates if not bool(candidate.get("lexical_only"))
-        ]
-        if not snapshot_candidates:
-            return (
-                "[ERROR] Retrieval snapshot is lexical-only; vector retrieval is unavailable. "
-                "Refresh retrieval snapshot with embedding indexing first."
-            )
-
-        merged: dict[tuple[str, str], tuple[float, dict[str, Any]]] = {}
-        for index, variant in enumerate(query_variants):
-            variant_embedding = vectors[index]
-            variant_weight = 1.0 if index == 0 else 0.75
-            variant_top_k = min(25, max(top_k * 2, 8)) if index == 0 else min(15, max(top_k, 5))
-            for candidate_snapshot in snapshot_candidates:
-                variant_rows = store.hybrid_search(
-                    project_key=resolved_project_key,
-                    repo_key=search_repo_key,
-                    query_text=variant,
-                    query_embedding=variant_embedding,
-                    top_k=variant_top_k,
-                    snapshot_id=int(candidate_snapshot.get("id") or 0) or None,
-                )
-                for row in variant_rows:
-                    if not _matches_scope(row, scope=source_scope):
-                        continue
-                    rank_score = _rank_hybrid_result(
-                        query_terms=query_terms,
-                        row=row,
-                        variant_weight=variant_weight,
-                    )
-                    key = _result_identity(row)
-                    existing = merged.get(key)
-                    if existing is None or rank_score > existing[0]:
-                        merged[key] = (rank_score, row)
-    finally:
-        store.close()
-
-    ranked_results = sorted(merged.values(), key=lambda item: item[0], reverse=True)
-    results = _select_diversified_results(
-        ranked_rows=[row for _score, row in ranked_results],
-        top_k=top_k,
-    )
-    if not results:
-        return f"No vector evidence results matched query: {q!r}"
-
-    scope_strict = effective_repo_key == resolved_repo_key
-    lines = [
-        (
-            f"Vector evidence results for {q!r} "
-            f"(scope={source_scope}, project_key={resolved_project_key}, repo_key={effective_repo_key or '<project>'}, top_k={top_k}, scope_strict={scope_strict}):"
-        )
-    ]
-    for idx, row in enumerate(results, start=1):
-        lines.append(_summarize_result(idx, row, q))
-    return "\n".join(lines)
-
-
-async def _search_evidence_vector(
-    ctx: RunContext[Any],
-    query: str = "",
-    limit: int = 5,
-    top_k: int | None = None,
-    project_key: str | None = None,
-    repo_key: str | None = None,
-) -> str:
-    """Run docs-biased vector-backed hybrid retrieval over centralized-state evidence chunks."""
-    resolved_limit = top_k if top_k is not None else limit
-    return await _search_vector_scope(
-        ctx,
-        query=query,
-        limit=resolved_limit,
-        project_key=project_key,
-        repo_key=repo_key,
-        source_scope="docs",
-    )
-
-
-async def _search_code_vector(
-    ctx: RunContext[Any],
-    query: str = "",
-    limit: int = 5,
-    top_k: int | None = None,
-    project_key: str | None = None,
-    repo_key: str | None = None,
-) -> str:
-    """Run code-biased vector-backed hybrid retrieval over centralized-state evidence chunks."""
-    resolved_limit = top_k if top_k is not None else limit
-    return await _search_vector_scope(
-        ctx,
-        query=query,
-        limit=resolved_limit,
-        project_key=project_key,
-        repo_key=repo_key,
-        source_scope="code",
-    )
-
-
-def is_vector_evidence_ready(*, deps: Any) -> bool:
-    """Return True when state context supports vector retrieval for current scope.
-
-    FR-74 / TSK-641.8: Infrastructure failures (connection refused, timeout,
-    auth errors) are logged at WARNING level so operators can distinguish
-    "vector not configured" from "vector infrastructure down".  Expected
-    "not configured" states remain at DEBUG.
-    """
-    settings = getattr(deps, "settings", None)
-    state_context = settings.get("state_context") if isinstance(settings, dict) else None
-    if not isinstance(state_context, dict):
-        return False
-
-    state_dsn = _resolve_state_dsn(state_context)
-    if not state_dsn:
-        return False
-
-    project_key = _first_non_empty(
-        state_context.get("project_storage_key"),
-        state_context.get("project_key"),
-        state_context.get("project_id"),
-        getattr(deps, "project_id", ""),
-    )
-    if not project_key:
-        return False
-
-    repo_key = _resolve_repo_key(state_context, None)
-    store = PostgresStateStore(state_dsn)
-    try:
-        snapshot, _effective_repo_key = _load_latest_snapshot(
-            store,
-            project_key=project_key,
-            repo_key=repo_key,
-        )
-    except (ConnectionRefusedError, TimeoutError, OSError) as exc:
-        # Infrastructure failures — operator-actionable, log at WARNING.
-        logger.warning(
-            "vector_evidence_infrastructure_failure",
-            exception_type=type(exc).__name__,
-            exception_message=str(exc),
-            fallback_mode="non_vector",
-        )
-        return False
-    except Exception as exc:
-        # Catch-all for unexpected errors (e.g. missing table, driver issues).
-        # Distinguish known psycopg/asyncpg operational errors from truly
-        # benign "not configured" states by checking the exception hierarchy.
-        _exc_name = type(exc).__name__
-        _is_db_operational = (
-            _exc_name
-            in (
-                "OperationalError",
-                "InterfaceError",
-                "DatabaseError",
-                "InternalError",
-            )
-            or "connection" in str(exc).lower()
-            or "timeout" in str(exc).lower()
-        )
-        if _is_db_operational:
-            logger.warning(
-                "vector_evidence_infrastructure_failure",
-                exception_type=_exc_name,
-                exception_message=str(exc),
-                fallback_mode="non_vector",
-            )
-        else:
-            logger.debug(
-                "vector_evidence_not_configured",
-                exception_type=_exc_name,
-                reason=str(exc),
-            )
-        return False
-    finally:
-        store.close()
-
-    if not snapshot:
-        return False
-    return not bool(snapshot.get("lexical_only"))
-
-
-def create_vector_evidence_toolset() -> FunctionToolset:
-    """Create FunctionToolset for vector-backed evidence retrieval."""
-    vector_search_calls = 0
-    vector_signature_counts: dict[str, int] = {}
-
-    async def _search_evidence_vector_wrapped(
-        ctx: RunContext[Any],
-        query: str = "",
-        limit: int = 5,
-        top_k: int | None = None,
-        project_key: str | None = None,
-        repo_key: str | None = None,
-        **extra: Any,
-    ) -> str:
-        nonlocal vector_search_calls
-        if extra:
-            logger.debug("vector_tool_ignored_extra_args", tool_name="search_evidence_vector", extra_keys=sorted(extra))
-        vector_search_calls += 1
-        agentic = _get_agentic_settings(ctx)
-        call_limit = int(agentic.get("vector_search_call_limit", 8) or 8)
-        call_limit = max(2, min(50, call_limit))
-        signature_limit = int(agentic.get("repeated_vector_signature_limit", 2) or 2)
-        signature_limit = max(1, min(8, signature_limit))
-        resolved_limit = top_k if top_k is not None else limit
-        signature = _vector_search_signature(
-            "search_evidence_vector",
-            query,
-            limit=resolved_limit,
-            project_key=project_key,
-            repo_key=repo_key,
-        )
-        vector_signature_counts[signature] = int(vector_signature_counts.get(signature, 0) or 0) + 1
-        if vector_signature_counts[signature] > signature_limit:
-            logger.warning(
-                "vector_search_signature_limit_exceeded",
-                tool_name="search_evidence_vector",
-                query=query,
-                limit=resolved_limit,
-                project_key=project_key,
-                repo_key=repo_key,
-                signature=signature,
-                signature_count=vector_signature_counts[signature],
-                signature_limit=signature_limit,
-            )
-            return (
-                "[ERROR] repeated identical vector search pattern limit reached for this analysis turn. "
-                "Pivot to read_evidence_document/read_file on concrete hits or finalize with current evidence."
-            )
-        if vector_search_calls > call_limit:
-            logger.warning(
-                "vector_search_call_limit_exceeded",
-                tool_name="search_evidence_vector",
-                vector_search_calls=vector_search_calls,
-                vector_search_call_limit=call_limit,
-            )
-            return (
-                "[ERROR] vector search call limit reached for this analysis turn. "
-                "Pivot to concrete evidence reads or synthesis."
-            )
-        return await _search_evidence_vector(
-            ctx,
-            query=query,
-            limit=resolved_limit,
-            project_key=project_key,
-            repo_key=repo_key,
-        )
-
-    async def _search_code_vector_wrapped(
-        ctx: RunContext[Any],
-        query: str = "",
-        limit: int = 5,
-        top_k: int | None = None,
-        project_key: str | None = None,
-        repo_key: str | None = None,
-        **extra: Any,
-    ) -> str:
-        nonlocal vector_search_calls
-        if extra:
-            logger.debug("vector_tool_ignored_extra_args", tool_name="search_code_vector", extra_keys=sorted(extra))
-        vector_search_calls += 1
-        agentic = _get_agentic_settings(ctx)
-        call_limit = int(agentic.get("vector_search_call_limit", 8) or 8)
-        call_limit = max(2, min(50, call_limit))
-        signature_limit = int(agentic.get("repeated_vector_signature_limit", 2) or 2)
-        signature_limit = max(1, min(8, signature_limit))
-        resolved_limit = top_k if top_k is not None else limit
-        signature = _vector_search_signature(
-            "search_code_vector",
-            query,
-            limit=resolved_limit,
-            project_key=project_key,
-            repo_key=repo_key,
-        )
-        vector_signature_counts[signature] = int(vector_signature_counts.get(signature, 0) or 0) + 1
-        if vector_signature_counts[signature] > signature_limit:
-            logger.warning(
-                "vector_search_signature_limit_exceeded",
-                tool_name="search_code_vector",
-                query=query,
-                limit=resolved_limit,
-                project_key=project_key,
-                repo_key=repo_key,
-                signature=signature,
-                signature_count=vector_signature_counts[signature],
-                signature_limit=signature_limit,
-            )
-            return (
-                "[ERROR] repeated identical vector search pattern limit reached for this analysis turn. "
-                "Pivot to read_file/read_evidence_document on concrete hits or finalize with current evidence."
-            )
-        if vector_search_calls > call_limit:
-            logger.warning(
-                "vector_search_call_limit_exceeded",
-                tool_name="search_code_vector",
-                vector_search_calls=vector_search_calls,
-                vector_search_call_limit=call_limit,
-            )
-            return (
-                "[ERROR] vector search call limit reached for this analysis turn. "
-                "Pivot to concrete evidence reads or synthesis."
-            )
-        return await _search_code_vector(
-            ctx,
-            query=query,
-            limit=resolved_limit,
-            project_key=project_key,
-            repo_key=repo_key,
-        )
-
-    _vector_retrieval_status.__name__ = "vector_retrieval_status"
-    _search_evidence_vector_wrapped.__name__ = "search_evidence_vector"
-    _search_code_vector_wrapped.__name__ = "search_code_vector"
-
-    toolset: FunctionToolset[Any] = FunctionToolset(
-        [_vector_retrieval_status, _search_evidence_vector_wrapped, _search_code_vector_wrapped]
-    )
-    logger.info("vector_evidence_toolset_created")
-    return toolset