cudag 0.3.10__py3-none-any.whl

cudag/core/random.py

@@ -0,0 +1,130 @@
+# Copyright (c) 2025 Tylt LLC. All rights reserved.
+# CONFIDENTIAL AND PROPRIETARY. Unauthorized use, copying, or distribution
+# is strictly prohibited. For licensing inquiries: hello@claimhawk.app
+
+"""Random data generation utilities for CUDAG framework."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from random import Random
+from typing import Any, Sequence, TypeVar
+
+T = TypeVar("T")
+
+
+def choose(rng: Random, values: Sequence[T]) -> T:
+    """Choose a random item from a sequence.
+
+    Args:
+        rng: Random number generator.
+        values: Non-empty sequence of values to choose from.
+
+    Returns:
+        A randomly selected item.
+
+    Raises:
+        ValueError: If values is empty.
+
+    Example:
+        >>> rng = Random(42)
+        >>> choose(rng, ["apple", "banana", "cherry"])
+        'cherry'
+    """
+    if not values:
+        raise ValueError("Cannot choose from empty sequence")
+    return values[rng.randint(0, len(values) - 1)]
+
+
+def date_in_range(
+    rng: Random,
+    start: str,
+    end: str,
+    fmt: str = "%m/%d/%Y",
+    input_fmt: str = "%Y-%m-%d",
+) -> str:
+    """Generate a random date in the given range.
+
+    Args:
+        rng: Random number generator.
+        start: Start date string (input_fmt format, default YYYY-MM-DD).
+        end: End date string (input_fmt format, default YYYY-MM-DD).
+        fmt: Output format string (default MM/DD/YYYY).
+        input_fmt: Input format string (default YYYY-MM-DD).
+
+    Returns:
+        Formatted date string in the specified output format.
+
+    Example:
+        >>> rng = Random(42)
+        >>> date_in_range(rng, "2024-01-01", "2024-12-31")
+        '11/01/2024'
+    """
+    start_date = datetime.strptime(start, input_fmt).date()
+    end_date = datetime.strptime(end, input_fmt).date()
+    delta_days = (end_date - start_date).days
+    if delta_days <= 0:
+        return start_date.strftime(fmt)
+    target = start_date + timedelta(days=rng.randint(0, delta_days))
+    return target.strftime(fmt)
+
+
+def amount(
+    rng: Random,
+    min_val: float,
+    max_val: float,
+    *,
+    allow_zero: bool = False,
+    zero_probability: float = 0.2,
+    decimal_places: int = 2,
+) -> str:
+    """Generate a random monetary amount.
+
+    Args:
+        rng: Random number generator.
+        min_val: Minimum value (inclusive).
+        max_val: Maximum value (inclusive).
+        allow_zero: If True, sometimes return "0.00". Default False.
+        zero_probability: Probability of returning zero when allow_zero=True.
+        decimal_places: Number of decimal places. Default 2.
+
+    Returns:
+        Formatted amount string.
+
+    Example:
+        >>> rng = Random(42)
+        >>> amount(rng, 10.0, 100.0)
+        '69.65'
+    """
+    if allow_zero and rng.random() < zero_probability:
+        return f"{0:.{decimal_places}f}"
+    value = rng.uniform(min_val, max_val)
+    return f"{value:.{decimal_places}f}"
+
+
+def weighted_choice(
+    rng: Random,
+    choices: dict[str, float],
+) -> str:
+    """Choose a random key based on weighted probabilities.
+
+    Args:
+        rng: Random number generator.
+        choices: Dict mapping choice keys to their probabilities (should sum to ~1.0).
+
+    Returns:
+        Selected choice key.
+
+    Example:
+        >>> rng = Random(42)
+        >>> weighted_choice(rng, {"common": 0.8, "rare": 0.15, "legendary": 0.05})
+        'common'
+    """
+    roll = rng.random()
+    cumulative = 0.0
+    for choice, prob in choices.items():
+        cumulative += prob
+        if roll < cumulative:
+            return choice
+    # Fallback to last choice
+    return list(choices.keys())[-1] if choices else ""

cudag/core/renderer.py

@@ -0,0 +1,190 @@
+# Copyright (c) 2025 Tylt LLC. All rights reserved.
+# CONFIDENTIAL AND PROPRIETARY. Unauthorized use, copying, or distribution
+# is strictly prohibited. For licensing inquiries: hello@claimhawk.app
+
+"""Base renderer class for image generation.
+
+A Renderer generates images from Screen + State.
+Like a View in MVC, it handles the visual presentation.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar
+
+from cudag.core.coords import normalize_coord, pixel_from_normalized
+
+if TYPE_CHECKING:
+    from PIL import Image
+
+    from cudag.core.screen import ScreenBase
+    from cudag.core.state import BaseState
+
+# Type variable for state
+S = TypeVar("S", bound="BaseState")
+
+
+class BaseRenderer(ABC, Generic[S]):
+    """Abstract base class for screen renderers.
+
+    A renderer is responsible for:
+    1. Loading base images and assets (fonts, overlays)
+    2. Rendering screen state to images
+    3. Building metadata for the rendered images
+
+    Example:
+        class CalendarRenderer(BaseRenderer[CalendarState]):
+            screen_class = CalendarScreen
+
+            def load_assets(self) -> None:
+                self.font = ImageFont.truetype(self.asset_path("arial.ttf"), 12)
+
+            def render(self, state: CalendarState) -> tuple[Image, dict]:
+                image = self.load_base_image()
+                self.draw_calendar_grid(image, state)
+                return image, {"month": state.month, "year": state.year}
+    """
+
+    screen_class: ClassVar[type[ScreenBase]]
+    """The Screen class this renderer is for."""
+
+    def __init__(self, assets_dir: Path | str) -> None:
+        """Initialize the renderer.
+
+        Args:
+            assets_dir: Path to the assets directory
+        """
+        self.assets_dir = Path(assets_dir)
+        self._base_image: Image.Image | None = None
+        self.load_assets()
+
+    @abstractmethod
+    def load_assets(self) -> None:
+        """Load fonts, base images, and other assets.
+
+        Called during initialization. Override to load your assets.
+        Store loaded assets as instance attributes.
+        """
+        pass
+
+    @abstractmethod
+    def render(self, state: S) -> tuple[Image.Image, dict[str, Any]]:
+        """Render the screen with given state.
+
+        Args:
+            state: Screen state to render
+
+        Returns:
+            Tuple of (PIL Image, metadata dict)
+        """
+        pass
+
+    def asset_path(self, *parts: str) -> Path:
+        """Get path to an asset file.
+
+        Args:
+            *parts: Path components relative to assets_dir
+
+        Returns:
+            Full path to the asset
+        """
+        return self.assets_dir.joinpath(*parts)
+
+    def load_base_image(self) -> Image.Image:
+        """Load and return a copy of the base image.
+
+        Uses the base_image defined in the Screen's Meta class.
+
+        Returns:
+            Copy of the base image (safe to modify)
+        """
+        from PIL import Image
+
+        if self._base_image is None:
+            base_path = self.screen_class.meta().base_image
+            if isinstance(base_path, str):
+                base_path = self.asset_path(base_path)
+            self._base_image = Image.open(base_path).convert("RGB")
+
+        return self._base_image.copy()
+
+    def normalize(
+        self,
+        pixel: tuple[int, int],
+        image_size: tuple[int, int] | None = None,
+    ) -> tuple[int, int]:
+        """Normalize pixel coordinates to RU [0, 1000].
+
+        Args:
+            pixel: (x, y) pixel coordinates
+            image_size: Image dimensions, or use screen size from Meta
+
+        Returns:
+            Normalized (x, y) coordinates
+        """
+        if image_size is None:
+            image_size = self.screen_class.meta().size
+        return normalize_coord(pixel, image_size)
+
+    def to_pixel(
+        self,
+        normalized: tuple[int, int],
+        image_size: tuple[int, int] | None = None,
+    ) -> tuple[int, int]:
+        """Convert normalized RU coordinates to pixels.
+
+        Args:
+            normalized: (x, y) coordinates in [0, 1000]
+            image_size: Image dimensions, or use screen size from Meta
+
+        Returns:
+            Pixel (x, y) coordinates
+        """
+        if image_size is None:
+            image_size = self.screen_class.meta().size
+        return pixel_from_normalized(normalized, image_size)
+
+    def get_region_center(self, region_name: str) -> tuple[int, int]:
+        """Get the center pixel coordinates of a region.
+
+        Args:
+            region_name: Name of the region on the screen
+
+        Returns:
+            (x, y) pixel coordinates of region center
+        """
+        region = self.screen_class.get_region(region_name)
+        return region.bounds.center
+
+    def get_action_point(self, region_name: str, target: Any = None) -> tuple[int, int]:
+        """Get the pixel coordinates for an action on a region.
+
+        Args:
+            region_name: Name of the region
+            target: Optional target (cell index, item, etc.)
+
+        Returns:
+            (x, y) pixel coordinates for the action
+        """
+        region = self.screen_class.get_region(region_name)
+        return region.get_action_point(target)
+
+    def build_metadata(self, state: S, **extra: Any) -> dict[str, Any]:
+        """Build standard metadata dict for a rendered image.
+
+        Args:
+            state: The state that was rendered
+            **extra: Additional metadata fields
+
+        Returns:
+            Metadata dictionary
+        """
+        meta = self.screen_class.meta()
+        return {
+            "screen": meta.name,
+            "image_size": {"width": meta.size[0], "height": meta.size[1]},
+            "state": state.to_dict(),
+            **extra,
+        }