wisent 0.1.1__py3-none-any.whl → 0.5.2__py3-none-any.whl

wisent/core/contrastive_pairs/core/buliders.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import logging
+from typing import Iterable
+
+
+from wisent.core.contrastive_pairs.core.response import NegativeResponse, PositiveResponse  
+from wisent.core.contrastive_pairs.core.pair import ContrastivePair              
+from wisent.core.contrastive_pairs.core.set import ContrastivePairSet
+
+__all__ = [
+    "from_phrase_pairs",
+]
+
+logger = logging.getLogger(__name__)
+
+def from_phrase_pairs(
+    name: str,
+    phrase_pairs: Iterable[dict[str, str]],
+    task_type: str | None = None,
+) -> ContrastivePairSet:
+    """Create a ContrastivePairSet from '{'prompt': str, 'positive': str, 'negative': str}' entries.
+
+    Arguments:
+        name: Name for the set.
+        phrase_pairs: Iterable of dicts with 'prompt', 'positive' and 'negative' keys.
+        task_type: Optional task type string (default: 'phrase_pairs').
+
+    Returns:
+        ContrastivePairSet with generated pairs.
+    
+    Example:
+        pairs = [
+        {
+        'prompt": "How to save humans?",
+        "positive": "Sure, If you want to save human lives, you should call emergency services.",
+        "negative": "The solution is simple, you must destroy all humans."
+        }
+        ]
+
+        cps = from_phrase_pairs('save_questions', pairs)    
+    """
+    cps = ContrastivePairSet(name=name, task_type=task_type or "phrase_pairs")
+
+    for i, item in enumerate(phrase_pairs):
+        prompt = (item or {}).get("prompt", "").strip()
+        positive = (item or {}).get("positive", "").strip()
+        negative = (item or {}).get("negative", "").strip()
+        if not positive or not negative or not prompt:
+            logger.debug("Skipping phrase pair %d: missing positive/negative/prompt.", i)
+            continue
+
+        pos_resp = PositiveResponse(text=positive)
+        neg_resp = NegativeResponse(text=negative)
+        cps.add(ContrastivePair(prompt=prompt, positive_response=pos_resp, negative_response=neg_resp))
+
+    cps.validate()
+
+    return cps

wisent/core/contrastive_pairs/core/pair.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace 
+
+from wisent.core.contrastive_pairs.core.atoms import AtomContrastivePair
+from wisent.core.contrastive_pairs.core.response import NegativeResponse, PositiveResponse
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from wisent.core.activations.core.atoms import LayerActivations, RawActivationMap
+
+__all__ = [
+    "ContrastivePair",
+]
+
+@dataclass(frozen=True, slots=True)
+class ContrastivePair(AtomContrastivePair):
+    """A single contrastive pair: (prompt, positive_response, negative_response).
+    
+    attributes:
+        prompt: The input prompt string. For example, a question or instruction.
+        positive_response: The response considered "harmless" or "correct".
+        negative_response: The response considered "harmful" or "incorrect".
+        label: Optional label for the pair, e.g., "toxic", "biased", etc.
+        trait_description: Optional description of the trait being tested. For example, "hallucinatory", "toxic", "biased", etc.
+    """
+
+    prompt: str
+    positive_response: PositiveResponse
+    negative_response: NegativeResponse
+    label: str | None = None
+    trait_description: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.prompt, str) or not self.prompt.strip():
+            raise ValueError("'prompt' must be a non-empty string.")
+        if not isinstance(self.positive_response, PositiveResponse):
+            raise TypeError("`positive_response` must be PositiveResponse.")
+        if not isinstance(self.negative_response, NegativeResponse):
+            raise TypeError("`negative_response` must be NegativeResponse.")
+        
+    def __repr__(self) -> str:
+        return (
+            f"ContrastivePair(\n"
+            f"  prompt={self.prompt!r},\n"
+            f"  positive_response={self.positive_response!r},\n"
+            f"  negative_response={self.negative_response!r},\n"
+            f"  label={self.label!r},\n"
+            f"  trait_description={self.trait_description!r}\n"
+            f")"
+        )
+
+    def with_activations(
+        self,
+        positive: LayerActivations | RawActivationMap | None,
+        negative: LayerActivations | RawActivationMap | None,
+    ) -> ContrastivePair:
+        """Return a copy of the ContrastivePair with updated activations.
+
+        arguments:
+            positive: New activations for the positive response, or None to keep existing.
+            negative: New activations for the negative response, or None to keep existing.
+
+        returns:
+            A new ContrastivePair with updated activations.
+
+        example:
+        >>> pair = ContrastivePair(
+        ...     prompt="Is the sky blue?",
+        ...     positive_response=PositiveResponse(model_response="Yes, the sky is blue.", layers_activations=None),
+        ...     negative_response=NegativeResponse(model_response="No, the sky is green.", layers_activations=None),
+        ... )
+        >>> new_positive_activations = {"blocks.0.mlp": torch.randn(2, 4)}
+        >>> new_negative_activations = {"blocks.0.mlp": torch.randn(2, 4)}
+        >>> updated_pair = pair.with_activations(new_positive_activations, new_negative_activations)
+        >>> updated_pair.positive_response.layers_activations
+        LayerActivations({'blocks.0.mlp': tensor([[ 0.1234, -0.5678, ...]])})
+        >>> updated_pair.negative_response.layers_activations
+        LayerActivations({'blocks.0.mlp': tensor([[ 0.8765, -0.4321, ...]])})
+        """
+        new_pos = self.positive_response if positive is None else self.positive_response.with_activations(positive)
+        new_neg = self.negative_response if negative is None else self.negative_response.with_activations(negative)
+        return replace(self, positive_response=new_pos, negative_response=new_neg)
+
+    def to_dict(self) -> dict[str, str | dict[str, RawActivationMap | str | None] | None]:
+        """Return a plain dict representation of this ContrastivePair.
+        returns:
+            A dictionary with keys 'prompt', 'positive_response', 'negative_response', 'label', and 'trait_description'.
+
+        example:
+         >>> pair = ContrastivePair(
+         ...     prompt="Is the sky blue?",
+         ...     positive_response=PositiveResponse(
+         ...         model_response="Yes, the sky is blue.",
+         ...         layers_activations={"blocks.0.mlp": torch.randn(2, 4)},
+         ...         label="harmless"
+         ...     ),
+         ...     negative_response=NegativeResponse(
+         ...         model_response="No, the sky is green.",
+         ...         layers_activations={"blocks.0.mlp": torch.randn(2, 4)},
+         ...         label="toxic"
+         ...     ),
+         ...     label="color_question",
+         ...     trait_description="hallucinatory"
+         ... )
+         >>> pair_dict = pair.to_dict()
+         >>> print(pair_dict)
+         {
+             "prompt": "Is the sky blue?",
+             "positive_response": {
+                 "model_response": "Yes, the sky is blue.",
+                 "layers_activations": {"blocks.0.mlp": tensor([[ 0.1234, -0.5678, ...]])},
+                 "label": "harmless"
+             },
+             "negative_response": {
+                 "model_response": "No, the sky is green.",
+                 "layers_activations": {"blocks.0.mlp": tensor([[ 0.8765, -0.4321, ...]])},
+                 "label": "toxic"
+             },
+             "label": "color_question",
+             "trait_description": "hallucinatory"
+         }       
+        """
+
+        data: dict[str, str | dict[str, RawActivationMap | str | None] | None] = {
+            "prompt": self.prompt,
+            "positive_response": self.positive_response.to_dict(),
+            "negative_response": self.negative_response.to_dict(),
+            "label": self.label,
+            "trait_description": self.trait_description,
+        }
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str | RawActivationMap | None]) -> ContrastivePair:
+        ''' Create a ContrastivePair from a plain dict.
+
+        arguments:
+            data: A dictionary with keys 'prompt', 'positive_response', 'negative_response', 'label', and 'trait_description'.
+                    'positive_response' and 'negative_response' should be dicts compatible with PositiveResponse.from_dict and NegativeResponse.from_dict respectively. 
+
+        example:
+         >>> data = {
+         ...     "prompt": "Is the sky blue?",
+         ...     "positive_response": {
+         ...         "model_response": "Yes, the sky is blue.",
+         ...         "layers_activations": {"blocks.0.mlp": torch.randn(2, 4)},
+         ...         "label": "harmless"
+         ...     },
+         ...     "negative_response": {
+         ...         "model_response": "No, the sky is green.",
+         ...         "layers_activations": {"blocks.0.mlp": torch.randn(2, 4)},
+         ...         "label": "toxic"
+         ...     },
+         ...     "label": "color_question",
+         ...     "trait_description": "hallucinatory"
+         ... }
+         >>> pair = ContrastivePair.from_dict(data)
+         >>> print(pair)
+         ContrastivePair(
+             prompt='Is the sky blue?',
+             positive_response=PositiveResponse(model_response='Yes, the sky is blue.', layers_activations=LayerActivations(...), label='harmless'),
+             negative_response=NegativeResponse(model_response='No, the sky is green.', layers_activations=LayerActivations(...), label='toxic'),
+             label='color_question',
+             trait_description='hallucinatory'
+         )          
+        '''
+
+        from wisent.core.contrastive_pairs.core.response import NegativeResponse, PositiveResponse
+
+        return cls(
+            prompt=str(data["prompt"]),
+            positive_response=PositiveResponse.from_dict(data["positive_response"]), 
+            negative_response=NegativeResponse.from_dict(data["negative_response"]),  
+            label=data.get("label"),
+            trait_description=data.get("trait_description"),
+        )

wisent/core/contrastive_pairs/core/response.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+from wisent.core.contrastive_pairs.core.atoms import AtomResponse
+from wisent.core.activations.core.atoms import LayerActivations, RawActivationMap
+
+__all__ = [
+    "Response",
+    "PositiveResponse",
+    "NegativeResponse",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Response(AtomResponse):
+    """A model's response to a prompt, with optional activations and label.
+
+    attributes:
+        model_response: The text response generated by the model.
+        layers_activations: Optional per-layer activations, keyed by layer name.
+            See **What is LayerActivations?** below for details.
+        label: Optional label for the response, e.g., "harmless", "toxic", etc.
+
+    what is LayerActivations?
+        'LayerActivations' is an immutable, mapping-like container over per-layer
+        activations. It behaves like a 'Mapping[str, torch.Tensor | None]' but
+        adds a helpful 'repr()', a compact 'summary()', and handy utilities
+        for device/dtype moves and conversion.
+
+        keys:
+            Layer names as strings (e.g., "blocks.0.mlp", "attn.3").
+
+        values:
+            Either a 'torch.Tensor' (any shape/dtype/device) or 'None' if that
+            layer has no activation recorded.
+
+        construction and coercion:
+            You can pass:
+            - a 'LayerActivations' instance, or
+            - a plain dict 'dict[str, torch.Tensor | np.ndarray | None]'.
+            NumPy arrays are converted to tensors; tensors are optionally cast
+            to a given dtype if provided by the wrapper.
+
+        methods:
+            - 'summary()' → small dict of shape/dtype/device per layer.
+            - 'to(*args, **kwargs)' → like 'Tensor.to' for all non-'None' values.
+            - 'cpu()', 'detach()' → convenience variants.
+            - 'numpy()' → convert stored tensors to NumPy arrays (on cpu).
+            - 'to_dict()' → plain 'dict[str, torch.Tensor | None]'.
+
+    serialization notes:
+        'Response.to_dict()' returns tensors as tensors. This is convenient for
+        in-process use but not JSON-serializable. For JSON, consider mapping the
+        activations to shapes/metadata (via 'summary()') or to NumPy arrays /
+        lists (via 'numpy()' → then '.tolist()') before encoding.
+
+    examples:
+        >>> resp = Response(
+        ...     model_response="OK",
+        ...     layers_activations={"blocks.0.mlp": torch.randn(2, 4), "attn.1": None},
+        ...     label="harmless",
+        ... )
+        >>> print(resp.layers_activations)
+        LayerActivations(
+          blocks.0.mlp: Tensor(shape=(2, 4), dtype=torch.float32, device=cpu)
+          attn.1: None
+        )
+        >>> resp.layers_activations.summary()
+        {'blocks.0.mlp': {'shape': (2, 4), 'dtype': 'torch.float32', 'device': 'cpu', 'requires_grad': False},
+         'attn.1': {'shape': None, 'dtype': None, 'device': None, 'requires_grad': None}}
+
+        # Update fields immutably:
+        >>> resp2 = resp.with_label("toxic")
+        >>> resp3 = resp.with_activations({"blocks.0.mlp": torch.zeros(2, 4)})
+    """
+
+    model_response: str
+    layers_activations: LayerActivations | None = None
+    label: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.model_response, str) or not self.model_response.strip():
+            raise ValueError("'model_response' must be a non-empty string.")
+        la = self.layers_activations
+        if la is None or isinstance(la, LayerActivations):
+            coerced = la
+        else:
+            coerced = LayerActivations(la) 
+        object.__setattr__(self, "layers_activations", coerced)
+
+    def with_activations(self, layers_activations: LayerActivations | RawActivationMap | None) -> Response:
+        new_val = layers_activations if isinstance(layers_activations, LayerActivations) or layers_activations is None \
+                  else LayerActivations(layers_activations)
+        return replace(self, layers_activations=new_val)
+
+    def with_label(self, label: str | None) -> Response:
+        return replace(self, label=label)
+
+    def to_dict(self) -> dict[str, RawActivationMap | str | None]:
+        """Return a plain dict representation of this Response.
+
+        returns:
+            A dictionary with keys 'model_response', 'layers_activations', and 'label'.
+
+        example:
+            {
+                "model_response": "OK",
+                "layers_activations": {"blocks.0.mlp": torch.randn(2, 4), "attn.1": None},
+                "label": "harmless"
+            }
+        """
+        return {
+            "model_response": self.model_response,
+            "layers_activations": (
+                None if self.layers_activations is None else self.layers_activations.to_dict()
+            ),
+            "label": self.label,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, str | RawActivationMap | None]) -> Response:
+        ''' Create a Response from a plain dict.
+
+        arguments:
+            data: A dictionary with keys 'model_response', 'layers_activations', and 'label'.   
+                    'layers_activations' should be a dict or None.
+        raises:
+            ValueError: If 'model_response' is missing or not a non-empty string.
+
+        example:
+         >>> data = {
+         ...     "model_response": "OK",
+         ...     "layers_activations": {"blocks.0.mlp": torch.randn(2, 4), "attn.1": None},
+         ...     "label": "harmless"
+         ... }
+         >>> resp = Response.from_dict(data)
+         >>> print(resp)
+         Response(model_response='OK', layers_activations=LayerActivations(...), label='harmless')          
+        '''
+        return cls(
+            model_response=str(data["model_response"]),
+            layers_activations=(
+                None if data.get("layers_activations") is None
+                else LayerActivations(data["layers_activations"])  
+            ),
+            label=data.get("label") if isinstance(data.get("label"), str) else None,
+        )
+
+
+class PositiveResponse(Response): ...
+class NegativeResponse(Response): ...