glitchlings 0.10.2__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/dlc/gutenberg.py

@@ -0,0 +1,400 @@
+"""Integration helpers for the py-gutenberg library.
+
+This module provides a wrapper around the GutenbergAPI that applies
+glitchlings to book text as it's fetched.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from functools import cached_property
+from typing import Any, Protocol, TypeAlias, cast
+
+from ..util.adapters import coerce_gaggle
+from ..zoo import Gaggle, Glitchling
+from ._shared import corrupt_text_value
+
+#: Default Gutendex API instance URL (public instance hosted at gutendex.com).
+DEFAULT_GUTENDEX_URL = "https://gutendex.com"
+
+
+class PersonProtocol(Protocol):
+    """Minimal interface for py-gutenberg Person objects."""
+
+    name: str
+
+
+class BookProtocol(Protocol):
+    """Minimal interface for py-gutenberg Book objects."""
+
+    id: int
+    title: str
+    authors: list[PersonProtocol]
+    translators: list[PersonProtocol]
+    subjects: list[str]
+    bookshelves: list[str]
+    languages: list[str]
+    copyright: bool
+    media_type: str
+    formats: dict[str, str]
+    download_count: int
+
+    def get_text(self) -> str: ...
+
+
+class GutenbergAPIProtocol(Protocol):
+    """Subset of the py-gutenberg API we rely on."""
+
+    instance_url: str
+
+    def get_all_books(self) -> Iterable[BookProtocol]: ...
+
+    def get_public_domain_books(self) -> Iterable[BookProtocol]: ...
+
+    def get_copyrighted_books(self) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_author(self, author: str) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_ids(self, ids: list[int]) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_language(self, languages: list[str]) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_search(self, query: str) -> Iterable[BookProtocol]: ...
+
+    def get_books_by_mime_type(self, mime_type: str) -> Iterable[BookProtocol]: ...
+
+    def get_books_ascending(self) -> Iterable[BookProtocol]: ...
+
+    def get_oldest(self) -> Iterable[BookProtocol]: ...
+
+    def get_latest(self, topic: str = "recent") -> Iterable[BookProtocol]: ...
+
+    def get_book(self, book_id: int) -> BookProtocol: ...
+
+    def get_book_metadata(self, book_id: int) -> BookProtocol: ...
+
+    def get_book_text(self, book_id: int) -> BookProtocol: ...
+
+
+Person: TypeAlias = PersonProtocol
+Book: TypeAlias = BookProtocol
+GutenbergAPI: TypeAlias = GutenbergAPIProtocol
+
+
+@dataclass
+class GlitchedBook:
+    """A Book wrapper that corrupts text content via glitchlings.
+
+    This class wraps a py-gutenberg Book object but provides corrupted text
+    when accessed. The original Book attributes are preserved.
+
+    Attributes:
+        id: The Gutenberg book ID.
+        title: The corrupted book title.
+        original_title: The original (uncorrupted) book title.
+        authors: List of book authors.
+        translators: List of book translators.
+        subjects: List of subject categories.
+        bookshelves: List of bookshelf categories.
+        languages: List of language codes.
+        copyright: Whether the book is under copyright.
+        media_type: The media type of the book.
+        formats: Dictionary mapping MIME types to download URLs.
+        download_count: Number of times the book has been downloaded.
+    """
+
+    id: int
+    title: str
+    original_title: str
+    authors: list[Person]
+    translators: list[Person]
+    subjects: list[str]
+    bookshelves: list[str]
+    languages: list[str]
+    copyright: bool
+    media_type: str
+    formats: dict[str, str]
+    download_count: int
+    _original_book: Book = field(repr=False)
+    _gaggle: Gaggle = field(repr=False)
+
+    @classmethod
+    def from_book(cls, book: Book, gaggle: Gaggle) -> GlitchedBook:
+        """Create a GlitchedBook from a py-gutenberg Book.
+
+        Args:
+            book: The original Book object from py-gutenberg.
+            gaggle: The gaggle of glitchlings to apply to text.
+
+        Returns:
+            A GlitchedBook that corrupts text with the provided gaggle.
+        """
+        # Use shared utility for consistent corruption; cast tells mypy this is str
+        corrupted_title = cast(str, corrupt_text_value(book.title, gaggle))
+        return cls(
+            id=book.id,
+            title=corrupted_title,
+            original_title=book.title,
+            authors=book.authors,
+            translators=book.translators,
+            subjects=book.subjects,
+            bookshelves=book.bookshelves,
+            languages=book.languages,
+            copyright=book.copyright,
+            media_type=book.media_type,
+            formats=book.formats,
+            download_count=book.download_count,
+            _original_book=book,
+            _gaggle=gaggle,
+        )
+
+    @cached_property
+    def _text_content(self) -> str:
+        """Lazily fetch and corrupt the full text content of the book."""
+        original_text: str = self._original_book.get_text()
+        return cast(str, corrupt_text_value(original_text, self._gaggle))
+
+    def get_text(self) -> str:
+        """Fetch and corrupt the full text content of the book.
+
+        This method fetches the book's text from Project Gutenberg and applies
+        glitchlings corruption to it. The text is fetched fresh on the first call
+        and cached for subsequent calls.
+
+        Returns:
+            The corrupted full text of the book.
+
+        Raises:
+            AttributeError: If the underlying Book doesn't support get_text().
+        """
+        return self._text_content
+
+    def __repr__(self) -> str:
+        """Return a concise representation of the GlitchedBook."""
+        return (
+            f"GlitchedBook(id={self.id}, title={self.title!r}, "
+            f"authors={[a.name for a in self.authors]!r})"
+        )
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the original book."""
+        return getattr(self._original_book, name)
+
+
+class GlitchenbergAPI:
+    """A wrapper around GutenbergAPI that corrupts book text with glitchlings.
+
+    This class provides the same interface as GutenbergAPI but applies
+    glitchlings to corrupt book text as it's fetched.
+
+    Example:
+        >>> from glitchlings.dlc.gutenberg import GlitchenbergAPI
+        >>> from glitchlings import Typogre
+        >>> api = GlitchenbergAPI(Typogre(rate=0.05), seed=42)
+        >>> book = api.get_book(1342)  # Pride and Prejudice
+        >>> print(book.title)  # Title will have typos applied
+    """
+
+    def __init__(
+        self,
+        glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+        *,
+        seed: int = 151,
+        instance_url: str = DEFAULT_GUTENDEX_URL,
+    ) -> None:
+        """Initialize the GlitchenbergAPI.
+
+        Args:
+            glitchlings: A glitchling, gaggle, or specification of glitchlings to apply.
+            seed: RNG seed for deterministic corruption (default: 151).
+            instance_url: The Gutendex instance URL to use for API requests.
+                Defaults to the public instance at gutendex.com. For production use,
+                consider self-hosting Gutendex.
+        """
+        self._gaggle = coerce_gaggle(glitchlings, seed=seed)
+        self._api = _get_gutenberg_api(instance_url)
+
+    @property
+    def instance_url(self) -> str:
+        """Return the Gutendex instance URL."""
+        return str(self._api.instance_url)
+
+    @property
+    def gaggle(self) -> Gaggle:
+        """Return the gaggle used for corruption."""
+        return self._gaggle
+
+    def _corrupt_book(self, book: Book) -> GlitchedBook:
+        """Apply glitchlings to a Book object."""
+        return GlitchedBook.from_book(book, self._gaggle)
+
+    def _corrupt_books(self, books: Iterable[Book]) -> list[GlitchedBook]:
+        """Apply glitchlings to a list of Book objects."""
+        return [self._corrupt_book(book) for book in books]
+
+    def corrupt_books(self, books: list[Book]) -> list[GlitchedBook]:
+        """Apply glitchlings to a list of Book objects.
+
+        This method allows batch corruption of books fetched from other sources
+        or the underlying API.
+
+        Args:
+            books: List of py-gutenberg Book objects to corrupt.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+
+        Example:
+            >>> # Fetch from underlying API and corrupt separately
+            >>> raw_books = api._api.get_books_by_author("Austen")
+            >>> glitched = api.corrupt_books(raw_books)
+        """
+        return self._corrupt_books(books)
+
+    # Methods that return lists of books
+    def get_all_books(self) -> list[GlitchedBook]:
+        """Get all books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_all_books())
+
+    def get_public_domain_books(self) -> list[GlitchedBook]:
+        """Get public domain books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_public_domain_books())
+
+    def get_copyrighted_books(self) -> list[GlitchedBook]:
+        """Get copyrighted books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_copyrighted_books())
+
+    def get_books_by_author(self, author: str) -> list[GlitchedBook]:
+        """Get books by author with glitchling corruption applied.
+
+        Args:
+            author: Author name to search for.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_author(author))
+
+    def get_books_by_ids(self, ids: list[int]) -> list[GlitchedBook]:
+        """Get books by IDs with glitchling corruption applied.
+
+        Args:
+            ids: List of Gutenberg book IDs to retrieve.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_ids(ids))
+
+    def get_books_by_language(self, languages: list[str]) -> list[GlitchedBook]:
+        """Get books by language with glitchling corruption applied.
+
+        Args:
+            languages: List of language codes (e.g., ["en", "fr"]).
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_language(languages))
+
+    def get_books_by_search(self, query: str) -> list[GlitchedBook]:
+        """Search for books with glitchling corruption applied.
+
+        Args:
+            query: Search query string.
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_search(query))
+
+    def get_books_by_mime_type(self, mime_type: str) -> list[GlitchedBook]:
+        """Get books by MIME type with glitchling corruption applied.
+
+        Args:
+            mime_type: MIME type filter (e.g., "text/plain").
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_books_by_mime_type(mime_type))
+
+    def get_books_ascending(self) -> list[GlitchedBook]:
+        """Get books sorted ascending with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_books_ascending())
+
+    def get_oldest(self) -> list[GlitchedBook]:
+        """Get oldest books with glitchling corruption applied."""
+        return self._corrupt_books(self._api.get_oldest())
+
+    def get_latest(self, topic: str = "recent") -> list[GlitchedBook]:
+        """Get latest books by topic with glitchling corruption applied.
+
+        Args:
+            topic: Topic string to filter books by (e.g., "fiction", "science").
+                Defaults to "recent".
+
+        Returns:
+            List of GlitchedBook objects with corrupted text.
+        """
+        return self._corrupt_books(self._api.get_latest(topic))
+
+    # Methods that return single books
+    def get_book(self, book_id: int) -> GlitchedBook:
+        """Get a book by ID with glitchling corruption applied.
+
+        Args:
+            book_id: Gutenberg book ID.
+
+        Returns:
+            GlitchedBook with corrupted text.
+        """
+        return self._corrupt_book(self._api.get_book(book_id))
+
+    def get_book_metadata(self, book_id: int) -> GlitchedBook:
+        """Get book metadata by ID with glitchling corruption applied.
+
+        Args:
+            book_id: Gutenberg book ID.
+
+        Returns:
+            GlitchedBook with corrupted metadata.
+        """
+        return self._corrupt_book(self._api.get_book_metadata(book_id))
+
+    def get_book_text(self, book_id: int) -> GlitchedBook:
+        """Get book text by ID with glitchling corruption applied.
+
+        Args:
+            book_id: Gutenberg book ID.
+
+        Returns:
+            GlitchedBook with corrupted text.
+        """
+        return self._corrupt_book(self._api.get_book_text(book_id))
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the underlying API."""
+        return getattr(self._api, name)
+
+
+def _get_gutenberg_api(instance_url: str) -> GutenbergAPI:
+    """Import and return a GutenbergAPI instance.
+
+    Raises:
+        ImportError: If py-gutenberg is not installed.
+    """
+    try:
+        from gutenberg import GutenbergAPI
+    except ImportError as exc:
+        raise ImportError(
+            "py-gutenberg is required for the GlitchenbergAPI integration. "
+            "Install it with: pip install py-gutenberg"
+        ) from exc
+
+    api = GutenbergAPI(instance_url=instance_url)
+    return cast(GutenbergAPIProtocol, api)
+
+
+__all__ = ["DEFAULT_GUTENDEX_URL", "GlitchenbergAPI", "GlitchedBook"]

glitchlings/dlc/huggingface.py

@@ -0,0 +1,68 @@
+"""Integration helpers for the Hugging Face datasets library."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from ..util.adapters import coerce_gaggle
+from ..zoo import Gaggle, Glitchling
+
+
+def _normalize_columns(column: str | Sequence[str]) -> list[str]:
+    """Normalize a column specification to a list."""
+    if isinstance(column, str):
+        return [column]
+
+    normalized = list(column)
+    if not normalized:
+        raise ValueError("At least one column must be specified")
+    return normalized
+
+
+def _glitch_dataset(
+    dataset: Any,
+    glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+    column: str | Sequence[str],
+    *,
+    seed: int = 151,
+) -> Any:
+    """Apply glitchlings to the provided dataset columns."""
+    columns = _normalize_columns(column)
+    gaggle = coerce_gaggle(glitchlings, seed=seed)
+    return gaggle.corrupt_dataset(dataset, columns)
+
+
+def GlitchedDataset(
+    dataset: Any,
+    glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+    *,
+    column: str | Sequence[str],
+    seed: int = 151,
+) -> Any:
+    """Return a lazily corrupted copy of a Hugging Face dataset.
+
+    This function applies glitchlings to the specified columns of a dataset,
+    returning a new dataset that lazily corrupts data as it's accessed.
+
+    Args:
+        dataset: The Hugging Face Dataset to corrupt.
+        glitchlings: A glitchling, gaggle, or specification of glitchlings to apply.
+        column: The column name (string) or names (sequence of strings) to corrupt.
+        seed: RNG seed for deterministic corruption (default: 151).
+
+    Returns:
+        A new dataset with the specified columns corrupted by the glitchlings.
+
+    Example:
+        >>> from datasets import Dataset
+        >>> from glitchlings.dlc.huggingface import GlitchedDataset
+        >>> dataset = Dataset.from_dict({"text": ["hello", "world"]})
+        >>> corrupted = GlitchedDataset(dataset, "typogre", column="text")
+        >>> list(corrupted)
+        [{'text': 'helo'}, {'text': 'wrold'}]
+    """
+    return _glitch_dataset(dataset, glitchlings, column, seed=seed)
+
+
+__all__ = ["GlitchedDataset"]

glitchlings/dlc/prime.py

@@ -0,0 +1,215 @@
+"""Integration helpers for the optional verifiers prime DLC."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from typing import Any, Callable, Protocol, cast
+
+from ..compat.loaders import require_datasets, require_jellyfish, require_verifiers
+from ..util.adapters import coerce_gaggle
+from ..zoo import Gaggle, Glitchling, Mim1c, Typogre  # noqa: F401
+from ._shared import resolve_columns as _resolve_columns_shared
+
+
+class VerifierEnvironment(Protocol):
+    """Minimal interface for verifiers environments."""
+
+    dataset: Any
+
+
+class VerifierSingleTurnEnv(Protocol):
+    """Minimal interface for single-turn verifier environments."""
+
+    dataset: Any
+    rubric: Any
+
+
+vf = require_verifiers("verifiers is not installed; install glitchlings[prime]")
+_jellyfish = require_jellyfish("jellyfish is not installed; install glitchlings[prime]")
+levenshtein_distance = _jellyfish.levenshtein_distance
+
+
+def _resolve_environment(env: str | VerifierEnvironment) -> VerifierEnvironment:
+    """Return a fully-instantiated verifier environment."""
+    if isinstance(env, str):
+        env = vf.load_environment(env)
+
+    if not isinstance(env, cast(type[Any], vf.Environment)):
+        raise TypeError("Invalid environment type")
+
+    return cast(VerifierEnvironment, env)
+
+
+def _resolve_columns(dataset: Any, columns: Sequence[str] | None) -> list[str]:
+    """Identify which dataset columns should be corrupted."""
+    return _resolve_columns_shared(dataset, columns)
+
+
+def load_environment(
+    env: str | VerifierEnvironment,
+    glitchlings: Iterable[str | Glitchling] | Glitchling | str | Gaggle | None = None,
+    *,
+    seed: int = 151,
+    columns: Sequence[str] | None = None,
+) -> VerifierEnvironment:
+    """Load an environment and optionally corrupt it with glitchlings."""
+    environment = _resolve_environment(env)
+
+    if glitchlings is None:
+        return environment
+
+    gaggle = coerce_gaggle(glitchlings, seed=seed)
+
+    dataset = environment.dataset
+    corrupt_columns = _resolve_columns(dataset, columns)
+    environment.dataset = gaggle.corrupt_dataset(dataset, corrupt_columns)
+    return environment
+
+
+def _as_gaggle(
+    glitchlings: Iterable[str | Glitchling] | Glitchling | str | Gaggle,
+    *,
+    seed: int,
+) -> Gaggle:
+    """Coerce any supported glitchling specification into a :class:`Gaggle`."""
+    return coerce_gaggle(glitchlings, seed=seed)
+
+
+def _extract_completion_text(completion: Any) -> str:
+    """Normalize a completion payload into a plain string."""
+    if isinstance(completion, str):
+        return completion
+
+    if isinstance(completion, list) and completion:
+        first = completion[0]
+        if isinstance(first, dict) and "content" in first:
+            return str(first["content"])
+        return str(first)
+
+    return str(completion)
+
+
+def normalized_edit_distance(
+    _: Any,
+    completion: Any,
+    answer: str,
+) -> float:
+    """Return ``1 - (distance / max_len)`` using Levenshtein distance."""
+    completion_text = _extract_completion_text(completion)
+    target = answer or ""
+    denominator = max(len(completion_text), len(target), 1)
+    distance = cast(int, levenshtein_distance(completion_text, target))
+    score = 1.0 - (distance / denominator)
+    return max(0.0, min(1.0, score))
+
+
+symmetric_levenshtein_similarity = normalized_edit_distance
+
+DEFAULT_CLEANUP_INSTRUCTIONS = (
+    "You are a meticulous copy editor. Restore the provided text to its original form."
+)
+
+
+def echo_chamber(
+    dataset_id: str,
+    column: str,
+    glitchlings: Iterable[str | Glitchling] | Glitchling | str | Gaggle,
+    *,
+    seed: int = 151,
+    instructions: str = DEFAULT_CLEANUP_INSTRUCTIONS,
+    reward_function: Callable[..., float] | None = None,
+    split: str | None = None,
+    **load_dataset_kwargs: Any,
+) -> VerifierSingleTurnEnv:
+    """Create an Echo Chamber Prime environment from a Hugging Face dataset column.
+
+    Args:
+        dataset_id: Identifier of the Hugging Face dataset to load.
+        column: Name of the column whose text should be glitched.
+        glitchlings: Glitchling specifiers that will corrupt the prompts.
+        seed: RNG seed forwarded to :func:`glitchlings.util.adapters.coerce_gaggle`.
+        instructions: System instructions supplied to the environment prompts.
+        reward_function: Optional callable used to score completions. Defaults to
+            :func:`symmetric_levenshtein_similarity` when omitted.
+        split: Optional dataset split to load.
+        **load_dataset_kwargs: Extra keyword arguments forwarded to
+            :func:`datasets.load_dataset`.
+
+    """
+    datasets_module = require_datasets("datasets is required to build an echo chamber")
+    load_dataset = getattr(datasets_module, "load_dataset", None)
+    if load_dataset is None:  # pragma: no cover - defensive
+        message = "datasets is required to build an echo chamber"
+        raise ModuleNotFoundError(message)
+
+    dataset_dict_cls = getattr(datasets_module, "DatasetDict", dict)
+
+    hf_dataset: Any
+    if split is None:
+        hf_dataset = load_dataset(dataset_id, **load_dataset_kwargs)
+        if isinstance(hf_dataset, dataset_dict_cls):
+            try:
+                hf_dataset = next(iter(hf_dataset.values()))
+            except StopIteration as exc:  # pragma: no cover - defensive
+                raise ValueError("The specified dataset does not contain any splits") from exc
+    else:
+        hf_dataset = load_dataset(dataset_id, split=split, **load_dataset_kwargs)
+
+    if isinstance(hf_dataset, dataset_dict_cls):
+        raise ValueError("Specify which split to use when the dataset loads as a DatasetDict.")
+
+    filtered_dataset = hf_dataset.filter(
+        lambda row: row.get(column) is not None,
+        load_from_cache_file=False,
+    )
+
+    source_column_names = list(filtered_dataset.column_names)
+
+    def _build_prompt(row: dict[str, Any]) -> dict[str, Any]:
+        text = str(row[column])
+        prompt = [
+            {"role": "system", "content": instructions},
+            {"role": "user", "content": f"Corrupted text:\n{text}"},
+        ]
+        return {"prompt": prompt, "answer": text}
+
+    base_dataset = filtered_dataset.map(
+        _build_prompt,
+        remove_columns=source_column_names,
+        load_from_cache_file=False,
+    )
+
+    try:
+        dataset_length = len(base_dataset)
+    except TypeError:
+        preview_rows: list[dict[str, Any]]
+        take_fn = getattr(base_dataset, "take", None)
+        if callable(take_fn):
+            preview_rows = list(take_fn(1))
+        else:
+            iterator = iter(base_dataset)
+            try:
+                first_row = next(iterator)
+            except StopIteration:
+                preview_rows = []
+            else:
+                preview_rows = [first_row]
+        if not preview_rows:
+            raise ValueError(
+                f"Column '{column}' did not yield any textual entries in dataset '{dataset_id}'."
+            )
+    else:
+        if dataset_length == 0:
+            raise ValueError(
+                f"Column '{column}' did not yield any textual entries in dataset '{dataset_id}'."
+            )
+
+    gaggle = _as_gaggle(glitchlings, seed=seed)
+    glitched_dataset = gaggle.corrupt_dataset(base_dataset, ["prompt"])
+
+    rubric_func = reward_function or normalized_edit_distance
+    rubric = vf.Rubric(funcs=[rubric_func], weights=[1.0])
+    return cast(
+        VerifierSingleTurnEnv,
+        vf.SingleTurnEnv(dataset=glitched_dataset, rubric=rubric),
+    )