"""Access helpers for the Compendium of starting creatures.

The data lives in compendium_data.COMPENDIUM (Claude-authored box-layouts). This
module is the only thing the UI imports — it turns entries into freeform Genomes
and provides lookup / random sampling for seeding and the compendium picker.
"""
from __future__ import annotations
import random

from .compendium_data import COMPENDIUM
from .genome import freeform_genome, Genome


def all_entries() -> list[dict]:
    return list(COMPENDIUM)


def get(entry_id: str) -> dict | None:
    return next((e for e in COMPENDIUM if e["id"] == entry_id), None)


def random_sample(n: int) -> list[dict]:
    """Up to n distinct random entries (fewer if the compendium is smaller)."""
    return random.sample(COMPENDIUM, min(max(0, n), len(COMPENDIUM)))


def as_genome(entry: dict) -> Genome:
    """Build a freeform Genome from a compendium entry."""
    return freeform_genome(entry["name"], list(entry["boxes"]))