switch-trust-cli 1.7.0__py3-none-any.whl

switch_trust/eval/core/models/response_schema.py

@@ -0,0 +1,148 @@
+"""Structured-output schema plumbing shared across model adapters.
+
+Judge/generator callers pass a Pydantic ``BaseModel`` subclass as the
+``output_schema`` argument to :meth:`Model.generate`. Each provider adapter
+translates it to that provider's native structured-output mechanism:
+
+- OpenAI / OpenAI-compatible (vLLM, Azure, ...) → ``json_schema`` response format
+- Ollama → the native ``format`` JSON-schema parameter
+- Gemini → ``response_mime_type`` + ``response_schema``
+- LiteLLM → ``response_format`` (the Pydantic class, translated per provider)
+- Anthropic → a single forced tool whose ``input_schema`` is the target schema
+
+:func:`parse_model_response` deserialises the model output back into the schema,
+with a best-effort fallback for the model-under-test and any provider that could
+not hard-enforce the shape.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from switch_trust.eval.core.models.model import (
+    ModelResponse,
+    extract_text_from_message,
+)
+
+
+class ModelResponseParseError(ValueError):
+    """A model/judge response could not be parsed into the target schema.
+
+    A ``ValueError`` subclass, so any existing ``except ValueError`` handling
+    keeps working unchanged; the distinct type lets the worker's error
+    categorization (see ``platform/worker.py::_classify_error_category``)
+    distinguish this from other permanent failures for dashboard/log
+    discoverability.
+    """
+
+
+logger = logging.getLogger(__name__)
+
+# TypeVar rather than PEP 695 `[T: BaseModel]` syntax: eval/core is exported to
+# the flintai-cli wheel (requires-python >= 3.11), and PEP 695 type parameters
+# are a syntax error before 3.12.
+T = TypeVar("T", bound=BaseModel)
+
+# Name of the forced tool used by providers that emit structured output via
+# tool calling (Anthropic).
+STRUCTURED_OUTPUT_TOOL_NAME = "emit_structured_output"
+
+
+def to_json_schema(schema: type[BaseModel]) -> dict[str, Any]:
+    """Return the plain JSON Schema for a Pydantic model."""
+    return schema.model_json_schema()
+
+
+def to_strict_json_schema(schema: type[BaseModel]) -> dict[str, Any]:
+    """Return a JSON Schema tightened for OpenAI-style strict decoding.
+
+    Strict ``json_schema`` response formats require every object to set
+    ``additionalProperties: false`` and to list all of its properties in
+    ``required``. Pydantic emits ``required`` but not ``additionalProperties``,
+    so we walk the schema and add what the strict validator expects.
+    """
+    return _tighten(schema.model_json_schema())
+
+
+def _tighten(node: Any) -> Any:
+    if isinstance(node, dict):
+        tightened = {key: _tighten(value) for key, value in node.items()}
+        if tightened.get("type") == "object" and "properties" in tightened:
+            tightened["additionalProperties"] = False
+            tightened["required"] = list(tightened["properties"].keys())
+        return tightened
+    if isinstance(node, list):
+        return [_tighten(item) for item in node]
+    return node
+
+
+def to_openai_response_format(schema: type[BaseModel]) -> dict[str, Any]:
+    """Build an OpenAI / vLLM ``response_format`` for ``schema``."""
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": schema.__name__,
+            "schema": to_strict_json_schema(schema),
+            "strict": True,
+        },
+    }
+
+
+def to_anthropic_tool(
+    schema: type[BaseModel],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Build a forced-tool definition and ``tool_choice`` for ``schema``.
+
+    Anthropic has no cross-version ``response_format``, so forcing a single
+    tool whose ``input_schema`` is the target schema makes the model emit the
+    payload as the tool input, which the adapter reads back as JSON.
+    """
+    tool = {
+        "name": STRUCTURED_OUTPUT_TOOL_NAME,
+        "description": (
+            "Record the final structured result. Always call this tool with "
+            "the result and nothing else."
+        ),
+        "input_schema": to_json_schema(schema),
+    }
+    tool_choice = {"type": "tool", "name": STRUCTURED_OUTPUT_TOOL_NAME}
+    return tool, tool_choice
+
+
+def parse_model_response(response: ModelResponse, schema: type[T]) -> T:  # noqa: UP047
+    """Deserialise a model response into ``schema``.
+
+    Providers that hard-enforce the schema return exactly the JSON payload;
+    those that cannot may wrap it in prose or markdown fences, so we fall back
+    to extracting the first ``{...}`` block. Raises ``ValueError`` if nothing
+    parses.
+    """
+    if response.message is None:
+        raise ModelResponseParseError("model returned no message to parse")
+    return parse_json_text(extract_text_from_message(response.message), schema)
+
+
+def parse_json_text(text: str, schema: type[T]) -> T:  # noqa: UP047
+    """Parse ``text`` into ``schema``, tolerating fences and surrounding prose."""
+    stripped = text.strip()
+    try:
+        return schema.model_validate_json(stripped)
+    except ValidationError as first_error:
+        match = re.search(r"\{.*\}", stripped, re.DOTALL)
+        if match is not None:
+            try:
+                return schema.model_validate_json(match.group())
+            except ValidationError:
+                pass
+        logger.debug(
+            "Failed to parse %s from model output: %r",
+            schema.__name__,
+            text,
+        )
+        raise ModelResponseParseError(
+            f"model output did not match schema {schema.__name__}"
+        ) from first_error

switch_trust/eval/core/optional_deps.py

@@ -0,0 +1,57 @@
+"""Lazy imports for the optional ``full`` dependency extra.
+
+The published ``switch-trust-cli`` package ships ``transformers[torch]`` and
+``garak`` as an optional extra (``pip install switch-trust-cli[full]``) rather than
+as core dependencies, because they are large (``torch`` alone is ~2 GB and
+on Linux also pulls in Cuda). The helpers here import those packages on demand
+and raise a friendly ``ImportError`` pointing at the extra when they are
+missing, instead of the bare import error a user would otherwise see.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from types import ModuleType
+from typing import Any
+
+_INSTALL_HINT = "Install it with: pip install switch-trust-cli[full]"
+
+
+def require_transformers_pipeline() -> Callable[..., Any]:
+    """Return ``transformers.pipeline``.
+
+    Raises ``ImportError`` with an install hint if ``transformers`` (part of
+    the optional ``full`` extra) is not installed.
+    """
+    try:
+        from transformers import pipeline
+    except ImportError as e:
+        raise ImportError(
+            "transformers is required for HuggingFace models and toxicity "
+            f"detection. {_INSTALL_HINT}"
+        ) from e
+    return pipeline
+
+
+def require_garak() -> ModuleType:
+    """Return the top-level ``garak`` module.
+
+    The submodules the eval engine reaches into (``garak.attempt``,
+    ``garak._plugins``, ``garak.generators.base``, ...) are imported here so
+    they are attribute-accessible on the returned module — a bare
+    ``import garak`` does not guarantee that.
+
+    Raises ``ImportError`` with an install hint if ``garak`` (part of the
+    optional ``full`` extra) is not installed.
+    """
+    try:
+        import garak
+        import garak._config  # noqa: F401
+        import garak._plugins  # noqa: F401
+        import garak.attempt  # noqa: F401
+        import garak.generators.base  # noqa: F401
+    except ImportError as e:
+        raise ImportError(
+            f"garak is required for garak probes and detectors. {_INSTALL_HINT}"
+        ) from e
+    return garak

switch_trust/eval/db/base/common_types.py

@@ -0,0 +1,16 @@
+"""Types shared by every repository's `*_types` module.
+
+Each entity keeps its own ``*SortField`` (the column set differs per table) and
+its own ``*SortOrder`` default, but the direction is the same two values
+everywhere, so it lives here rather than being restated per module.
+
+The per-entity modules re-export what they use, so
+``from ...detectors.detector_types import SortDirection`` keeps working.
+"""
+
+from enum import Enum
+
+
+class SortDirection(str, Enum):
+    ASC = "asc"
+    DESC = "desc"

switch_trust/eval/db/base/detectors/detector_helpers.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from switch_trust.eval.core.detectors.detector import Detector
+from switch_trust.eval.db.base.detectors.detector_types import (
+    DbDetector,
+    DetectorType,
+)
+
+
+def create_detector(
+    db_detector: DbDetector,
+) -> Detector:
+    """Create a Detector instance from a DbDetector."""
+    if db_detector.type == DetectorType.GARAK:
+        if not db_detector.detector_name:
+            raise ValueError("detector_name is required for GARAK detectors")
+        from switch_trust.eval.core.detectors.detector_garak import (  # noqa: PLC0415 - deferred import cost
+            GarakDetector,
+        )
+
+        return GarakDetector(db_detector.detector_name)
+
+    elif db_detector.type == DetectorType.MODEL:
+        from switch_trust.eval.core.detectors.detector_model import (  # noqa: PLC0415 - patched at source in tests
+            ModelDetector,
+        )
+        from switch_trust.eval.core.models.generator_model import (  # noqa: PLC0415 - patched at source in tests
+            get_generator_model,
+        )
+
+        model = get_generator_model()
+        kwargs = {}
+        if db_detector.prompt is not None:
+            kwargs["prompt"] = db_detector.prompt
+        return ModelDetector(model=model, **kwargs)
+
+    elif db_detector.type == DetectorType.ADVERSARIAL_MODEL:
+        from switch_trust.eval.core.detectors.detector_model_adversarial import (  # noqa: PLC0415 - patched at source in tests
+            AdversarialModelDetector,
+        )
+        from switch_trust.eval.core.models.generator_model import (  # noqa: PLC0415 - patched at source in tests
+            get_generator_model,
+        )
+
+        model = get_generator_model()
+        kwargs = {}
+        kwargs["include_conversation"] = db_detector.include_conversation
+        if db_detector.prompt is not None:
+            kwargs["prompt"] = db_detector.prompt
+        return AdversarialModelDetector(model=model, **kwargs)
+
+    elif db_detector.type == DetectorType.PII:
+        from switch_trust.eval.core.detectors.detector_pii import (  # noqa: PLC0415 - patched at source in tests
+            PIIDetector,
+        )
+
+        return PIIDetector()
+
+    elif db_detector.type == DetectorType.SECRET:
+        from switch_trust.eval.core.detectors.detector_secret import (  # noqa: PLC0415 - patched at source in tests
+            SecretDetector,
+        )
+
+        return SecretDetector()
+
+    elif db_detector.type == DetectorType.TOPIC_GUARD:
+        from switch_trust.eval.core.detectors.detector_topic_guard import (  # noqa: PLC0415 - patched at source in tests
+            TopicGuardDetector,
+        )
+        from switch_trust.eval.core.models.generator_model import (  # noqa: PLC0415 - patched at source in tests
+            get_generator_model,
+        )
+
+        if not db_detector.agent_objective and not db_detector.agent_instructions:
+            raise ValueError(
+                "at least one of agent_objective or "
+                "agent_instructions is required for "
+                "TOPIC_GUARD detectors"
+            )
+        model = get_generator_model()
+        return TopicGuardDetector(
+            model=model,
+            agent_objective=db_detector.agent_objective,
+            agent_instructions=db_detector.agent_instructions,
+        )
+
+    else:
+        raise ValueError(f"unknown detector type: {db_detector.type}")

switch_trust/eval/db/base/detectors/detector_repository.py

@@ -0,0 +1,96 @@
+"""
+Abstract interface for a repository of Detectors.
+
+A DetectorRepository manages detector configurations,
+providing CRUD operations over them.  Detectors are
+always referenced by ID.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from switch_trust.eval.core.detectors.detector import Detector
+from switch_trust.eval.db.base.detectors.detector_types import (
+    DbDetector,
+    DetectorListView,
+    DetectorSortOrder,
+)
+
+
+class DetectorRepository(ABC):
+    """Repository that manages Detector configurations."""
+
+    @abstractmethod
+    def list(self) -> list[DbDetector]:
+        """Return all detector configurations in the repository."""
+        pass
+
+    @abstractmethod
+    def search(
+        self,
+        query: str | None = None,
+        types: list[str] | None = None,
+        order: DetectorSortOrder | None = None,
+        offset: int = 0,
+        limit: int = 50,
+    ) -> DetectorListView:
+        """Search detectors with pagination and sorting."""
+        pass
+
+    @abstractmethod
+    def get(self, id: str) -> DbDetector:
+        """Return the detector configuration with the given id.
+
+        Raises KeyError if the detector does not exist.
+        """
+        pass
+
+    @abstractmethod
+    def create(
+        self,
+        config: DbDetector,
+    ) -> DbDetector:
+        """Persist a new detector configuration.
+
+        Raises ValueError if a detector with that name already
+        exists.
+        """
+        pass
+
+    @abstractmethod
+    def update(
+        self,
+        config: DbDetector,
+    ) -> DbDetector:
+        """Replace an existing detector configuration.
+
+        The detector is identified by ``config.id``.
+
+        Raises KeyError if the detector does not exist.
+        """
+        pass
+
+    def get_detector(self, id: str) -> Detector:
+        """Return a Detector instance for the given id.
+
+        Raises KeyError if the detector does not exist.
+        """
+        from switch_trust.eval.db.base.detectors.detector_helpers import (  # noqa: PLC0415 - deferred import cost
+            create_detector,
+        )
+
+        return create_detector(self.get(id))
+
+    @abstractmethod
+    def delete(self, id: str) -> None:
+        """Delete the detector with the given id.
+
+        Raises KeyError if the detector does not exist.
+        """
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove all detectors from the repository."""
+        pass

switch_trust/eval/db/base/detectors/detector_types.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+
+from dataclasses_json import dataclass_json
+
+from switch_trust.eval.common.reference import Reference, ReferenceType
+from switch_trust.eval.common.utils import datetime_config, generate_id, now_utc
+from switch_trust.eval.db.base.common_types import SortDirection
+
+
+class DetectorType(str, Enum):
+    """Discriminator for the kind of Detector."""
+
+    GARAK = "garak"
+    MODEL = "model"
+    ADVERSARIAL_MODEL = "adversarial_model"
+    PII = "pii"
+    SECRET = "secret"
+    TOPIC_GUARD = "topic_guard"
+
+
+@dataclass_json
+@dataclass
+class DbDetector:
+    """JSON-serialisable description of a Detector."""
+
+    type: DetectorType
+    name: str
+    id: str = field(default_factory=generate_id)
+    created: datetime = field(
+        default_factory=now_utc,
+        metadata=datetime_config,
+    )
+    description: str | None = None
+    tags: dict[str, str] = field(default_factory=dict)
+    include_conversation: bool = False
+
+    # -- garak type --
+    detector_name: str | None = None
+
+    # -- model type --
+    prompt: str | None = None
+
+    # -- topic_guard type --
+    agent_objective: str | None = None
+    agent_instructions: str | None = None
+
+    def get_ref(self) -> Reference:
+        return Reference(
+            self.id,
+            self.name,
+            ReferenceType.DETECTOR,
+            self.description,
+        )
+
+
+class DetectorSortField(str, Enum):
+    NAME = "name"
+    CREATED = "created"
+    TYPE = "type"
+
+
+@dataclass_json
+@dataclass
+class DetectorSortOrder:
+    field: DetectorSortField = DetectorSortField.NAME
+    direction: SortDirection = SortDirection.ASC
+
+
+@dataclass_json
+@dataclass
+class DetectorListView:
+    """Paginated list of detector configurations."""
+
+    items: list[DbDetector] = field(default_factory=list)
+    total: int = 0

switch_trust/eval/db/base/eval/eval_helpers.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+from switch_trust.eval.core.eval.evaluation import Evaluation
+from switch_trust.eval.core.models.generator_model import get_generator_model
+from switch_trust.eval.db.base.detectors.detector_repository import DetectorRepository
+from switch_trust.eval.db.base.eval.eval_types import DbEvaluation, EvaluationType
+from switch_trust.eval.db.base.message.message_collection_repository import (
+    MessageCollectionRepository,
+)
+
+
+def create_evaluation(
+    db_evaluation: DbEvaluation,
+    message_collection_repo: MessageCollectionRepository | None = None,
+    detector_repo: DetectorRepository | None = None,
+) -> Evaluation:
+    """Create an Evaluation instance from a DbEvaluation."""
+    if db_evaluation.type == EvaluationType.MESSAGE_COLLECTION:
+        if message_collection_repo is None:
+            raise ValueError(
+                "message_collection_repo is required for MESSAGE_COLLECTION evaluations"
+            )
+        if db_evaluation.message_collection_id is None:
+            raise ValueError("message_collection_id must be set on the DbEvaluation")
+        if detector_repo is None:
+            raise ValueError(
+                "detector_repo is required for MESSAGE_COLLECTION evaluations"
+            )
+        if db_evaluation.detector_id is None:
+            raise ValueError("detector_id must be set on the DbEvaluation")
+        from switch_trust.eval.core.eval.evaluation_message_list import (  # noqa: PLC0415 - patched at source in tests
+            MessageListEvaluation,
+        )
+
+        message_collection = message_collection_repo.get_message_collection(
+            db_evaluation.message_collection_id
+        )
+        messages = message_collection.load()
+        detector = detector_repo.get_detector(
+            db_evaluation.detector_id,
+        )
+        return MessageListEvaluation(
+            messages=messages,
+            detector=detector,
+            num_prompts=db_evaluation.num_prompts,
+        )
+
+    elif db_evaluation.type == EvaluationType.GARAK_PROBE:
+        from switch_trust.eval.core.eval.evaluation_garak_probe import (  # noqa: PLC0415 - patched at source in tests
+            GarakProbeEvaluation,
+        )
+
+        if db_evaluation.probe_name is None:
+            raise ValueError("probe_name must be set on the DbEvaluation")
+        return GarakProbeEvaluation(
+            probe_name=db_evaluation.probe_name,
+        )
+
+    elif db_evaluation.type == EvaluationType.GARAK_MODULE:
+        from switch_trust.eval.core.eval.evaluation_garak_module import (  # noqa: PLC0415 - patched at source in tests
+            GarakModuleEvaluation,
+        )
+
+        if db_evaluation.module_name is None:
+            raise ValueError("module_name must be set on the DbEvaluation")
+        return GarakModuleEvaluation(
+            module_name=db_evaluation.module_name,
+            probe_names=db_evaluation.probe_names,
+        )
+
+    elif db_evaluation.type == EvaluationType.METRIC_TOXICITY:
+        from switch_trust.eval.core.eval.metric_toxicity import (  # noqa: PLC0415 - patched at source in tests
+            ToxicityMetricEvaluation,
+        )
+
+        return ToxicityMetricEvaluation()
+
+    elif db_evaluation.type == EvaluationType.METRIC_CONCISENESS:
+        from switch_trust.eval.core.eval.metric_conciseness import (  # noqa: PLC0415 - patched at source in tests
+            ConcisenessMetricEvaluation,
+        )
+
+        return ConcisenessMetricEvaluation(
+            judge_model=get_generator_model(),
+        )
+
+    elif db_evaluation.type == EvaluationType.METRIC_FACTUAL_ACCURACY:
+        from switch_trust.eval.core.eval.metric_factual_accuracy import (  # noqa: PLC0415 - patched at source in tests
+            FactualAccuracyMetricEvaluation,
+        )
+
+        return FactualAccuracyMetricEvaluation(
+            judge_model=get_generator_model(),
+        )
+
+    elif db_evaluation.type == EvaluationType.METRIC_INSTRUCTION_ADHERENCE:
+        from switch_trust.eval.core.eval.metric_instruction_adherence import (  # noqa: PLC0415 - patched at source in tests
+            InstructionAdherenceMetricEvaluation,
+        )
+
+        return InstructionAdherenceMetricEvaluation(
+            judge_model=get_generator_model(),
+        )
+
+    elif db_evaluation.type == EvaluationType.METRIC_TONE:
+        from switch_trust.eval.core.eval.metric_tone import (  # noqa: PLC0415 - patched at source in tests
+            ToneMetricEvaluation,
+        )
+
+        return ToneMetricEvaluation(
+            judge_model=get_generator_model(),
+        )
+
+    elif db_evaluation.type == EvaluationType.ADVERSARIAL_PROBE:
+        from switch_trust.eval.core.eval.evaluation_adversarial import (  # noqa: PLC0415 - patched at source in tests
+            AdversarialEvaluation,
+        )
+
+        goals: list[str] = []
+        if db_evaluation.message_collection_id and message_collection_repo:
+            mc = message_collection_repo.get_message_collection(
+                db_evaluation.message_collection_id,
+            )
+            messages = mc.load()
+            goals = [
+                part.text
+                for msg in messages
+                for part in msg.content.parts
+                if part.text is not None
+            ]
+
+        if db_evaluation.adversarial_goals:
+            goals.extend(db_evaluation.adversarial_goals)
+
+        if not goals:
+            raise ValueError(
+                "adversarial_goals or "
+                "message_collection_id must be set on "
+                "the DbEvaluation"
+            )
+        if not db_evaluation.attack_techniques:
+            raise ValueError(
+                "attack_techniques must be set on "
+                "the DbEvaluation for adversarial probes"
+            )
+        if detector_repo is None:
+            raise ValueError(
+                "detector_repo is required for ADVERSARIAL_PROBE evaluations"
+            )
+        if not db_evaluation.detector_id:
+            raise ValueError(
+                "detector_id must be set on the DbEvaluation for adversarial probes"
+            )
+        detector = detector_repo.get_detector(
+            db_evaluation.detector_id,
+        )
+        return AdversarialEvaluation(
+            goals=goals,
+            attack_techniques=db_evaluation.attack_techniques,
+            detector=detector,
+            num_prompts=db_evaluation.num_prompts or 5,
+            max_turns=db_evaluation.max_turns or 5,
+            attacker_model=get_generator_model(),
+        )
+
+    elif db_evaluation.type == EvaluationType.TOPIC_GUARD:
+        from switch_trust.eval.core.eval.evaluation_topic_guard import (  # noqa: PLC0415 - patched at source in tests
+            TopicGuardEvaluation,
+        )
+
+        if not db_evaluation.agent_objective and not db_evaluation.agent_instructions:
+            raise ValueError(
+                "at least one of agent_objective or "
+                "agent_instructions must be set on "
+                "the DbEvaluation"
+            )
+        return TopicGuardEvaluation(
+            agent_objective=db_evaluation.agent_objective,
+            agent_instructions=db_evaluation.agent_instructions,
+            num_prompts=db_evaluation.num_prompts or 5,
+            max_turns=db_evaluation.max_turns or 5,
+            attacker_model=get_generator_model(),
+        )
+
+    else:
+        raise ValueError(f"unknown evaluation type: {db_evaluation.type}")