cudag 0.3.10__py3-none-any.whl

cudag/core/distribution.py

@@ -0,0 +1,136 @@
+# 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
+
+"""Distribution sampling utilities for task generation.
+
+Provides weighted random sampling from configured distributions,
+commonly used for controlling task type distribution in datasets.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from random import Random
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cudag.core.dataset import DatasetConfig
+
+
+@dataclass
+class DistributionSampler:
+    """Weighted random sampling from a configured distribution.
+
+    This class encapsulates the pattern of sampling from task-specific
+    distributions defined in dataset configuration. Distributions are
+    dictionaries mapping type names to probability weights that must
+    sum to approximately 1.0.
+
+    Attributes:
+        distribution: Mapping of type names to probability weights
+
+    Example:
+        >>> sampler = DistributionSampler({
+        ...     "normal": 0.8,
+        ...     "edge_case": 0.15,
+        ...     "adversarial": 0.05
+        ... })
+        >>> rng = Random(42)
+        >>> sampler.sample(rng)
+        'normal'
+    """
+
+    distribution: dict[str, float]
+
+    def __post_init__(self) -> None:
+        """Validate that probabilities sum to approximately 1.0."""
+        if not self.distribution:
+            raise ValueError("Distribution cannot be empty")
+
+        total = sum(self.distribution.values())
+        if not (0.99 <= total <= 1.01):
+            raise ValueError(
+                f"Distribution probabilities must sum to 1.0, got {total:.4f}. "
+                f"Distribution: {self.distribution}"
+            )
+
+    def sample(self, rng: Random) -> str:
+        """Sample a distribution type based on configured weights.
+
+        Args:
+            rng: Random number generator
+
+        Returns:
+            Sampled distribution type name
+        """
+        rand = rng.random()
+        cumulative = 0.0
+        for dist_type, weight in self.distribution.items():
+            cumulative += weight
+            if rand < cumulative:
+                return dist_type
+        # Fallback to last type (handles floating point edge cases)
+        return list(self.distribution.keys())[-1]
+
+    def sample_n(self, rng: Random, n: int) -> list[str]:
+        """Sample n distribution types.
+
+        Args:
+            rng: Random number generator
+            n: Number of samples to generate
+
+        Returns:
+            List of sampled distribution type names
+        """
+        return [self.sample(rng) for _ in range(n)]
+
+    @classmethod
+    def from_config(
+        cls,
+        config: DatasetConfig,
+        task_type: str,
+        default: dict[str, float] | None = None,
+    ) -> DistributionSampler:
+        """Create sampler from dataset configuration.
+
+        Args:
+            config: Dataset configuration object
+            task_type: Task type to get distribution for
+            default: Default distribution if not in config
+
+        Returns:
+            Configured DistributionSampler instance
+
+        Raises:
+            ValueError: If no distribution found and no default provided
+        """
+        dist = config.get_distribution(task_type)
+        if not dist and default:
+            dist = default
+        if not dist:
+            raise ValueError(
+                f"No distribution found for task type: '{task_type}'. "
+                f"Either add a distribution to your config or provide a default."
+            )
+        return cls(dist)
+
+    @classmethod
+    def uniform(cls, types: list[str]) -> DistributionSampler:
+        """Create a uniform distribution over the given types.
+
+        Args:
+            types: List of type names to distribute uniformly
+
+        Returns:
+            DistributionSampler with equal probability for each type
+
+        Example:
+            >>> sampler = DistributionSampler.uniform(["a", "b", "c"])
+            >>> sampler.distribution
+            {'a': 0.333..., 'b': 0.333..., 'c': 0.333...}
+        """
+        if not types:
+            raise ValueError("Types list cannot be empty")
+        prob = 1.0 / len(types)
+        return cls({t: prob for t in types})

cudag/core/drawing.py

@@ -0,0 +1,75 @@
+# 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
+
+"""Drawing utilities for CUDAG framework."""
+
+from __future__ import annotations
+
+from PIL import Image, ImageDraw
+
+
+def render_scrollbar(
+    content_height: int,
+    visible_height: int,
+    scroll_offset: int,
+    width: int = 12,
+    *,
+    min_thumb: int = 30,
+    track_color: tuple[int, int, int] = (240, 240, 240),
+    thumb_color: tuple[int, int, int] = (100, 100, 100),
+    thumb_width: int = 4,
+) -> Image.Image:
+    """Render a scrollbar track with thumb indicating position.
+
+    Args:
+        content_height: Total content height in pixels.
+        visible_height: Visible viewport height.
+        scroll_offset: Current scroll offset in pixels.
+        width: Scrollbar width.
+        min_thumb: Minimum thumb height in pixels.
+        track_color: RGB color for scrollbar track.
+        thumb_color: RGB color for scrollbar thumb.
+        thumb_width: Width of the thumb in pixels.
+
+    Returns:
+        PIL Image of the scrollbar.
+
+    Example:
+        >>> scrollbar = render_scrollbar(
+        ...     content_height=1000,
+        ...     visible_height=400,
+        ...     scroll_offset=200,
+        ...     width=12,
+        ... )
+        >>> scrollbar.size
+        (12, 400)
+    """
+    track_height = visible_height
+
+    # Create light gray track
+    track = Image.new("RGB", (width, track_height), color=track_color)
+    draw = ImageDraw.Draw(track)
+
+    if content_height <= visible_height:
+        # No scrolling needed - no thumb
+        return track
+
+    # Calculate thumb size proportional to visible content
+    ratio = visible_height / content_height
+    thumb_height = max(min_thumb, int(track_height * ratio))
+
+    # Calculate thumb position
+    max_offset = max(content_height - visible_height, 1)
+    travel = track_height - thumb_height
+    thumb_y = int((scroll_offset / max_offset) * travel) if travel > 0 else 0
+
+    # Draw thumb (centered thin dark rectangle)
+    thumb_x0 = (width - thumb_width) // 2
+    thumb_x1 = thumb_x0 + thumb_width
+    draw.rectangle(
+        [(thumb_x0, thumb_y), (thumb_x1, thumb_y + thumb_height)],
+        fill=thumb_color,
+    )
+
+    return track

cudag/core/fonts.py

@@ -0,0 +1,156 @@
+# 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
+
+"""Font loading utilities with platform-aware fallbacks.
+
+This module provides utilities for loading fonts with automatic fallback
+to system fonts when the primary font is not available.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from PIL import ImageFont
+from PIL.ImageFont import FreeTypeFont
+
+
+# Common system font paths by platform
+SYSTEM_FONTS: dict[str, list[str]] = {
+    "darwin": [
+        "/System/Library/Fonts/Helvetica.ttc",
+        "/System/Library/Fonts/SFNSText.ttf",
+        "/Library/Fonts/Arial.ttf",
+        "/System/Library/Fonts/SFNS.ttf",
+    ],
+    "linux": [
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+        "/usr/share/fonts/TTF/DejaVuSans.ttf",
+        "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
+    ],
+    "win32": [
+        "C:/Windows/Fonts/arial.ttf",
+        "C:/Windows/Fonts/segoeui.ttf",
+        "C:/Windows/Fonts/tahoma.ttf",
+    ],
+}
+
+
+def load_font(
+    primary_path: Path | str,
+    size: int,
+    fallbacks: Sequence[Path | str] | None = None,
+) -> FreeTypeFont:
+    """Load a font with fallback support.
+
+    Tries primary font first, then fallbacks in order, finally falls back
+    to platform-specific system fonts.
+
+    Args:
+        primary_path: Primary font file path (absolute or relative).
+        size: Font size in points.
+        fallbacks: Optional sequence of fallback font paths to try before
+            system fonts.
+
+    Returns:
+        Loaded FreeTypeFont ready for use with PIL ImageDraw.
+
+    Raises:
+        OSError: If no font could be loaded from any path.
+
+    Example:
+        Basic usage::
+
+            font = load_font("assets/fonts/Inter.ttf", size=14)
+
+        With explicit fallbacks::
+
+            font = load_font(
+                self.asset_path("fonts/Inter.ttf"),
+                size=14,
+                fallbacks=["/System/Library/Fonts/Helvetica.ttc"]
+            )
+    """
+    paths_to_try: list[Path] = [Path(primary_path)]
+
+    if fallbacks:
+        paths_to_try.extend(Path(p) for p in fallbacks)
+
+    # Add platform-specific system fonts
+    platform = sys.platform
+    if platform in SYSTEM_FONTS:
+        paths_to_try.extend(Path(p) for p in SYSTEM_FONTS[platform])
+
+    errors: list[str] = []
+    for path in paths_to_try:
+        try:
+            return ImageFont.truetype(str(path), size)
+        except OSError as e:
+            errors.append(f"{path}: {e}")
+            continue
+
+    raise OSError(
+        f"Could not load any font. Tried {len(paths_to_try)} paths:\n"
+        + "\n".join(f"  - {err}" for err in errors[:5])
+        + (f"\n  ... and {len(errors) - 5} more" if len(errors) > 5 else "")
+    )
+
+
+def load_font_family(
+    regular: Path | str,
+    size: int,
+    *,
+    bold: Path | str | None = None,
+    italic: Path | str | None = None,
+    bold_italic: Path | str | None = None,
+    fallbacks: Sequence[Path | str] | None = None,
+) -> dict[str, FreeTypeFont]:
+    """Load a font family with multiple weights/styles.
+
+    Loads regular font and optionally bold, italic, and bold-italic variants.
+    If a variant fails to load, it falls back to regular.
+
+    Args:
+        regular: Path to regular weight font (required).
+        size: Font size in points.
+        bold: Optional path to bold weight font.
+        italic: Optional path to italic font.
+        bold_italic: Optional path to bold-italic font.
+        fallbacks: Optional fallbacks for primary fonts.
+
+    Returns:
+        Dictionary with keys 'regular', 'bold', 'italic', 'bold_italic'.
+        Missing variants fall back to 'regular'.
+
+    Example:
+        ::
+
+            fonts = load_font_family(
+                "fonts/Inter-Regular.ttf",
+                size=14,
+                bold="fonts/Inter-Bold.ttf",
+            )
+            draw.text((10, 10), "Normal", font=fonts["regular"])
+            draw.text((10, 30), "Bold", font=fonts["bold"])
+    """
+    regular_font = load_font(regular, size, fallbacks)
+
+    result: dict[str, FreeTypeFont] = {
+        "regular": regular_font,
+        "bold": regular_font,
+        "italic": regular_font,
+        "bold_italic": regular_font,
+    }
+
+    # Try to load variants, fall back to regular on failure
+    for key, path in [("bold", bold), ("italic", italic), ("bold_italic", bold_italic)]:
+        if path is not None:
+            try:
+                result[key] = ImageFont.truetype(str(path), size)
+            except OSError:
+                pass  # Keep fallback to regular
+
+    return result

cudag/core/generator.py

@@ -0,0 +1,163 @@
+# 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
+
+"""Generator entry point helper for CUDAG projects.
+
+This module provides a standard entry point for dataset generation that
+handles boilerplate like argument parsing, config loading, and dataset naming.
+"""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+from cudag.core.dataset import DatasetBuilder, DatasetConfig
+from cudag.core.utils import check_script_invocation, get_researcher_name
+
+if TYPE_CHECKING:
+    from cudag.core.renderer import BaseRenderer
+    from cudag.core.task import BaseTask
+
+
+def run_generator(
+    renderer: BaseRenderer[Any],
+    tasks: list[BaseTask],
+    *,
+    config_path: Path | str = "config/dataset.yaml",
+    description: str = "Generate training dataset",
+    extra_args: list[tuple[str, dict[str, Any]]] | None = None,
+    config_modifier: Callable[[DatasetConfig, argparse.Namespace], None] | None = None,
+    post_build: Callable[[Path, BaseRenderer[Any]], None] | None = None,
+) -> Path:
+    """Standard dataset generation entry point.
+
+    Handles common boilerplate:
+    - Script invocation check (warning if not run via ./scripts/generate.sh)
+    - Argument parsing (--config, --seed, plus custom args)
+    - Config loading from YAML
+    - Dataset naming ({prefix}--{researcher}--{timestamp})
+    - Dataset building and test generation
+
+    Args:
+        renderer: Initialized renderer instance for generating images.
+        tasks: List of task instances to generate samples from.
+        config_path: Default path to config YAML file. Defaults to
+            "config/dataset.yaml".
+        description: CLI description shown in --help. Defaults to
+            "Generate training dataset".
+        extra_args: Additional CLI arguments as list of (name, kwargs) tuples.
+            Each tuple is passed to argparser.add_argument(name, **kwargs).
+        config_modifier: Optional callback to modify config after loading.
+            Called with (config, args) after config is loaded but before
+            dataset name is generated. Use this to apply custom logic.
+        post_build: Optional callback after dataset is built. Called with
+            (output_dir, renderer). Use for debug images, validation, etc.
+
+    Returns:
+        Path to the generated dataset output directory.
+
+    Example:
+        Basic usage::
+
+            from cudag import run_generator
+            from .renderer import MyRenderer
+            from .tasks import ClickTask, ScrollTask
+
+            def main() -> None:
+                renderer = MyRenderer(assets_dir=Path("assets"))
+                tasks = [ClickTask(config={}, renderer=renderer)]
+                run_generator(renderer, tasks)
+
+        With custom arguments::
+
+            def main() -> None:
+                renderer = MyRenderer(assets_dir=Path("assets"))
+                tasks = [ClickTask(config={}, renderer=renderer)]
+                run_generator(
+                    renderer,
+                    tasks,
+                    extra_args=[
+                        ("--debug", {"action": "store_true", "help": "Enable debug"}),
+                    ],
+                )
+
+        With config modification::
+
+            def modify_config(config, args):
+                if args.debug:
+                    config.task_counts = {"click-day": 10}
+
+            def main() -> None:
+                renderer = MyRenderer(assets_dir=Path("assets"))
+                tasks = [ClickTask(config={}, renderer=renderer)]
+                run_generator(
+                    renderer,
+                    tasks,
+                    config_modifier=modify_config,
+                )
+    """
+    check_script_invocation()
+
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=Path(config_path),
+        help="Path to dataset config YAML",
+    )
+    parser.add_argument(
+        "--seed",
+        type=int,
+        default=None,
+        help="Override random seed from config",
+    )
+
+    # Add any extra arguments
+    if extra_args:
+        for name, kwargs in extra_args:
+            parser.add_argument(name, **kwargs)
+
+    args = parser.parse_args()
+
+    # Load config
+    config = DatasetConfig.from_yaml(args.config)
+    if args.seed is not None:
+        config.seed = args.seed
+
+    # Allow custom config modification
+    if config_modifier:
+        config_modifier(config, args)
+
+    # Build dataset name: {prefix}--{researcher}--{timestamp}
+    # Using "--" delimiter to disambiguate from hyphens in expert names
+    researcher = get_researcher_name()
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    name_parts = [config.name_prefix]
+    if researcher:
+        name_parts.append(researcher)
+    name_parts.append(timestamp)
+    dataset_name = "--".join(name_parts)
+
+    config.output_dir = Path("datasets") / dataset_name
+
+    print(f"Loaded config: {config.name_prefix}")
+    print(f"Tasks: {config.task_counts}")
+
+    # Build dataset
+    builder = DatasetBuilder(config=config, tasks=tasks)
+    output_dir = builder.build()
+
+    # Build tests
+    builder.build_tests()
+
+    # Optional post-build callback
+    if post_build:
+        post_build(output_dir, renderer)
+
+    print(f"\nDataset generated at: {output_dir}")
+
+    return output_dir