Source code for smarter.apps.guardrail.services.strategies.semantic_strategy

"""
``semantic``: triggers when the segment's embedding is similar to any of.

``guardrail.config["referenceTexts"]``.

The similarity is the cosine similarity of the embeddings, and the guardrail triggers when the
best similarity reaches ``guardrail.threshold``. The reference texts' embeddings are cached,
so that each prompt embeds only the segment.
"""

import math

from cache_results import cache_results

from smarter.apps.guardrail.manifest.models.guardrail.const import (
    DEFAULT_EMBEDDING_MODEL,
)
from smarter.apps.guardrail.services.exceptions import (
    GuardrailConfigError,
    GuardrailProviderError,
)

from .base import BaseGuardrailStrategy, StrategyContext, StrategyMatch
from .clients import get_client

EMBEDDING_CACHE_TTL = 60 * 60 * 24 * 7
"""Seconds to cache the embeddings of a guardrail's reference texts."""


[docs] def cosine_similarity(a: list[float], b: list[float]) -> float: """ Return the cosine similarity of two vectors, or 0.0 if either has no magnitude. :raises GuardrailProviderError: If the vectors have different lengths. """ if len(a) != len(b): raise GuardrailProviderError("The embeddings of the segment and a reference text have different dimensions.") dot = sum(x * y for x, y in zip(a, b)) norm_a = math.sqrt(sum(x * x for x in a)) norm_b = math.sqrt(sum(y * y for y in b)) if norm_a == 0 or norm_b == 0: return 0.0 return dot / (norm_a * norm_b)
[docs] def reference_embeddings(guardrail, model: str, references: list[str]) -> list[list[float]]: """ Return the embeddings of a guardrail's reference texts, in order. The embeddings are cached for :data:`EMBEDDING_CACHE_TTL` seconds, keyed on the model and the reference texts, so that each prompt embeds only the segment. :param guardrail: The Guardrail, whose LLM provider embeds the texts. :param model: The embedding model. :param references: The reference texts. :returns: One embedding per reference text. :raises GuardrailProviderError: If the embeddings call returns the wrong number of vectors. """ @cache_results(timeout=EMBEDDING_CACHE_TTL) def get_cached_reference_embeddings(model: str, references: list[str]) -> list[list[float]]: vectors = get_client(guardrail).embed(references, model=model) if len(vectors) != len(references): # raise rather than return so that a bad response is never cached. raise GuardrailProviderError("The embeddings call returned the wrong number of vectors.") return vectors return get_cached_reference_embeddings(model, references)
[docs] class SemanticStrategy(BaseGuardrailStrategy): """Match a text segment by its embedding's similarity to reference texts."""
[docs] def evaluate(self, *, segment, guardrail, context: StrategyContext) -> StrategyMatch: # pylint: disable=R0914 """ Compare the segment's embedding with each reference text's embedding. Calls the Guardrail's LLM provider to embed the segment; reference embeddings are cached. :param segment: The text segment. :param guardrail: The Guardrail, which supplies the strategy's configuration. :param context: Ambient evaluation context. Unused. :returns: A match triggered when the best cosine similarity reaches the Guardrail's threshold. :raises GuardrailConfigError: when the Guardrail has no ``referenceTexts``. :raises GuardrailProviderError: when the embeddings call fails, or returns the wrong number of vectors. """ references: list[str] = list(guardrail.settings.get("referenceTexts") or []) if not references: raise GuardrailConfigError( f"Guardrail '{guardrail.name}' uses strategy semantic but has no referenceTexts." ) model = guardrail.settings.get("model") or DEFAULT_EMBEDDING_MODEL reference_vectors = reference_embeddings(guardrail, model, references) vectors = get_client(guardrail).embed([segment.text], model=model) if len(vectors) != 1: raise GuardrailProviderError("The embeddings call returned the wrong number of vectors.") segment_vector = vectors[0] scores = [ (cosine_similarity(segment_vector, vector), text) for vector, text in zip(reference_vectors, references) ] best_score, best_reference = max(scores) threshold = self.threshold(guardrail) return StrategyMatch( triggered=best_score >= threshold, confidence=best_score, rationale=f"The most similar reference text, with similarity {best_score:.3f} (threshold {threshold:.3f}): {best_reference[:120]}", )
__all__ = ["SemanticStrategy", "cosine_similarity", "reference_embeddings"]