cudag 0.3.10__py3-none-any.whl

cudag/core/__init__.py

@@ -0,0 +1,364 @@
+# 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
+
+"""Core framework classes and DSL functions."""
+
+from cudag.core.coords import (
+    RU_MAX,
+    bounds_to_tolerance,
+    calculate_tolerance_ru,
+    clamp_coord,
+    coord_distance,
+    coord_within_tolerance,
+    get_normalized_bounds,
+    normalize_coord,
+    pixel_from_normalized,
+    tolerance_to_ru,
+)
+from cudag.core.button import (
+    DIALOG_CANCEL,
+    DIALOG_OK,
+    LARGE_RECT,
+    LARGE_SQUARE,
+    MEDIUM_RECT,
+    MEDIUM_SQUARE,
+    NAV_BUTTON,
+    SMALL_RECT,
+    SMALL_SQUARE,
+    TOOLBAR_BUTTON,
+    ButtonPlacement,
+    ButtonShape,
+    ButtonSpec,
+)
+from cudag.core.canvas import CanvasConfig, RegionConfig
+from cudag.core.grid import Grid, GridCell, GridGeometry
+from cudag.core.scrollable_grid import (
+    ColumnDef,
+    RowLayout,
+    ScrollableGrid,
+    ScrollableGridGeometry,
+    ScrollState as GridScrollState,
+)
+from cudag.core.data_grid import (
+    ColumnDef as DataColumnDef,
+    Grid as DataGrid,
+    GridGeometry as DataGridGeometry,
+    RowLayout as DataRowLayout,
+    ScrollableGrid as DataScrollableGrid,
+    ScrollState as DataScrollState,
+    SelectableRowGrid,
+    SelectionState,
+    wrap_text as grid_wrap_text,
+)
+from cudag.core.icon import (
+    APP_ICON_LARGE,
+    APP_ICON_SMALL,
+    DESKTOP_ICON,
+    TASKBAR_ICON,
+    TOOLBAR_ICON,
+    IconLayout,
+    IconPlacement,
+    IconSpec,
+)
+from cudag.core.taskbar import TaskbarRenderer, TaskbarState
+from cudag.core.dataset import DatasetBuilder, DatasetConfig
+from cudag.core.distribution import DistributionSampler
+from cudag.core.scroll_task import ScrollTaskBase, ScrollTaskConfig
+from cudag.core.iconlist_task import IconListTaskBase, make_tool_call
+from cudag.core.grounding_task import GroundingTaskBase, bbox_to_ru, scale_bbox
+from cudag.core.models import (
+    # Classes
+    Attachment,
+    BelongsToRel,
+    BoolField,
+    ChoiceField,
+    Claim,
+    ComputedField,
+    DateField,
+    Field,
+    FloatField,
+    HasManyRel,
+    HasOneRel,
+    IntField,
+    ListField,
+    Model,
+    ModelGenerator,
+    MoneyField,
+    Patient,
+    Procedure,
+    Provider,
+    Relationship,
+    StringField,
+    TimeField,
+    # DSL functions
+    attribute,
+    belongs_to,
+    boolean,
+    choice,
+    computed,
+    date_field,
+    decimal,
+    get_first_name,
+    get_last_name,
+    has_many,
+    has_one,
+    integer,
+    list_of,
+    money,
+    string,
+    time_field,
+    years_since,
+    # Semantic field types
+    City,
+    ClaimNumber,
+    ClaimStatus,
+    DOB,
+    Email,
+    Fee,
+    FirstName,
+    FullName,
+    LastName,
+    LicenseNumber,
+    MemberID,
+    NPI,
+    Phone,
+    ProcedureCode,
+    SSN,
+    Specialty,
+    State,
+    Street,
+    ZipCode,
+)
+from cudag.core.renderer import BaseRenderer
+from cudag.core.screen import (
+    # Classes
+    Bounds,
+    ButtonRegion,
+    ClickRegion,
+    DropdownRegion,
+    GridRegion,
+    Region,
+    Screen,
+    ScreenBase,
+    ScreenMeta,
+    ScrollRegion,
+    # DSL functions
+    button,
+    dropdown,
+    grid,
+    region,
+    scrollable,
+)
+from cudag.core.config import get_config_path, load_yaml_config
+from cudag.core.drawing import render_scrollbar
+from cudag.core.fonts import SYSTEM_FONTS, load_font, load_font_family
+from cudag.core.generator import run_generator
+from cudag.core.random import amount, choose, date_in_range, weighted_choice
+from cudag.core.state import BaseState, ScrollState
+from cudag.core.task import BaseTask, TaskContext, TaskSample, TestCase
+from cudag.core.text import (
+    center_text_position,
+    draw_centered_text,
+    measure_text,
+    ordinal_suffix,
+    truncate_text,
+    wrap_text,
+)
+from cudag.core.utils import check_script_invocation, get_researcher_name
+
+__all__ = [
+    # Coordinates
+    "RU_MAX",
+    "normalize_coord",
+    "pixel_from_normalized",
+    "get_normalized_bounds",
+    "clamp_coord",
+    "coord_distance",
+    "coord_within_tolerance",
+    "tolerance_to_ru",
+    "bounds_to_tolerance",
+    "calculate_tolerance_ru",
+    # Screen DSL - classes
+    "Screen",
+    "ScreenBase",
+    "ScreenMeta",
+    "Region",
+    "Bounds",
+    "ClickRegion",
+    "ButtonRegion",
+    "GridRegion",
+    "ScrollRegion",
+    "DropdownRegion",
+    # Screen DSL - functions
+    "region",
+    "button",
+    "grid",
+    "scrollable",
+    "dropdown",
+    # Canvas/Region
+    "CanvasConfig",
+    "RegionConfig",
+    # Grid
+    "Grid",
+    "GridCell",
+    "GridGeometry",
+    # Scrollable Grid (legacy)
+    "ScrollableGrid",
+    "ScrollableGridGeometry",
+    "ColumnDef",
+    "RowLayout",
+    "GridScrollState",
+    # Data Grid (composable)
+    "DataGrid",
+    "DataGridGeometry",
+    "DataColumnDef",
+    "DataRowLayout",
+    "DataScrollableGrid",
+    "DataScrollState",
+    "SelectableRowGrid",
+    "SelectionState",
+    "grid_wrap_text",
+    # Icons
+    "IconSpec",
+    "IconPlacement",
+    "IconLayout",
+    "DESKTOP_ICON",
+    "TASKBAR_ICON",
+    "TOOLBAR_ICON",
+    "APP_ICON_LARGE",
+    "APP_ICON_SMALL",
+    # Taskbar
+    "TaskbarState",
+    "TaskbarRenderer",
+    # Buttons
+    "ButtonSpec",
+    "ButtonPlacement",
+    "ButtonShape",
+    "SMALL_SQUARE",
+    "MEDIUM_SQUARE",
+    "LARGE_SQUARE",
+    "SMALL_RECT",
+    "MEDIUM_RECT",
+    "LARGE_RECT",
+    "NAV_BUTTON",
+    "TOOLBAR_BUTTON",
+    "DIALOG_OK",
+    "DIALOG_CANCEL",
+    # State
+    "BaseState",
+    "ScrollState",
+    # Renderer
+    "BaseRenderer",
+    # Task
+    "BaseTask",
+    "TaskSample",
+    "TaskContext",
+    "TestCase",
+    # Dataset
+    "DatasetBuilder",
+    "DatasetConfig",
+    # Distribution
+    "DistributionSampler",
+    # Scroll Tasks
+    "ScrollTaskBase",
+    "ScrollTaskConfig",
+    # IconList Tasks
+    "IconListTaskBase",
+    "make_tool_call",
+    # Grounding Tasks
+    "GroundingTaskBase",
+    "bbox_to_ru",
+    "scale_bbox",
+    # Model DSL - classes
+    "Model",
+    "ModelGenerator",
+    "Field",
+    "StringField",
+    "IntField",
+    "FloatField",
+    "BoolField",
+    "DateField",
+    "TimeField",
+    "ChoiceField",
+    "ListField",
+    "MoneyField",
+    "ComputedField",
+    # Model DSL - functions
+    "attribute",
+    "string",
+    "integer",
+    "decimal",
+    "money",
+    "date_field",
+    "time_field",
+    "boolean",
+    "choice",
+    "list_of",
+    "computed",
+    "years_since",
+    # Name generation functions
+    "get_first_name",
+    "get_last_name",
+    # Relationship DSL - classes
+    "Relationship",
+    "HasManyRel",
+    "BelongsToRel",
+    "HasOneRel",
+    # Relationship DSL - functions
+    "has_many",
+    "belongs_to",
+    "has_one",
+    # Common healthcare models
+    "Patient",
+    "Provider",
+    "Procedure",
+    "Claim",
+    "Attachment",
+    # Semantic field types
+    "FirstName",
+    "LastName",
+    "FullName",
+    "DOB",
+    "NPI",
+    "SSN",
+    "Phone",
+    "Email",
+    "Street",
+    "City",
+    "State",
+    "ZipCode",
+    "MemberID",
+    "ClaimNumber",
+    "ProcedureCode",
+    "LicenseNumber",
+    "Specialty",
+    "ClaimStatus",
+    "Fee",
+    # Utils
+    "check_script_invocation",
+    "get_researcher_name",
+    # Generator
+    "run_generator",
+    # Fonts
+    "load_font",
+    "load_font_family",
+    "SYSTEM_FONTS",
+    # Random utilities
+    "choose",
+    "date_in_range",
+    "amount",
+    "weighted_choice",
+    # Text utilities
+    "measure_text",
+    "center_text_position",
+    "draw_centered_text",
+    "wrap_text",
+    "truncate_text",
+    "ordinal_suffix",
+    # Drawing utilities
+    "render_scrollbar",
+    # Config utilities
+    "load_yaml_config",
+    "get_config_path",
+]

cudag/core/button.py

@@ -0,0 +1,137 @@
+# 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
+
+"""Button abstractions for UI elements.
+
+Provides reusable button definitions for different UI button types:
+- Square buttons (equal width/height)
+- Rectangular buttons (different width/height)
+- Text buttons (with label)
+- Icon buttons (with icon)
+
+Each button type includes natural tolerance calculation (70% of dimensions).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ButtonShape(Enum):
+    """Button shape types."""
+
+    SQUARE = "square"
+    RECT = "rect"
+    PILL = "pill"  # Rounded ends
+
+
+@dataclass
+class ButtonSpec:
+    """Specification for a button type.
+
+    Defines dimensions and characteristics for buttons in UIs.
+    Buttons can be square (equal dimensions) or rectangular.
+
+    Attributes:
+        width: Button width in pixels.
+        height: Button height in pixels.
+        shape: Button shape (square, rect, pill).
+        has_label: Whether button displays text label.
+        has_icon: Whether button displays an icon.
+    """
+
+    width: int
+    height: int
+    shape: ButtonShape = ButtonShape.RECT
+    has_label: bool = False
+    has_icon: bool = False
+
+    @property
+    def is_square(self) -> bool:
+        """Check if button is square."""
+        return self.width == self.height
+
+    @property
+    def tolerance_pixels(self) -> tuple[int, int]:
+        """Calculate natural click tolerance in pixels.
+
+        Returns 70% of dimensions (15% padding on each side).
+        """
+        return (int(self.width * 0.7), int(self.height * 0.7))
+
+    def tolerance_ru(self, image_size: tuple[int, int]) -> tuple[int, int]:
+        """Calculate natural tolerance in RU (Resolution Units).
+
+        Args:
+            image_size: (width, height) of the full image.
+
+        Returns:
+            Tuple of (x_tolerance_ru, y_tolerance_ru) in 0-1000 range.
+        """
+        tol_pixels = self.tolerance_pixels
+        x_ru = (tol_pixels[0] / image_size[0]) * 1000
+        y_ru = (tol_pixels[1] / image_size[1]) * 1000
+        return (int(x_ru), int(y_ru))
+
+
+@dataclass
+class ButtonPlacement:
+    """A button placed at a specific location.
+
+    Attributes:
+        spec: The button specification.
+        x: X position (left edge) in pixels.
+        y: Y position (top edge) in pixels.
+        label: Optional text label for the button.
+        description: Human-readable description of button action.
+    """
+
+    spec: ButtonSpec
+    x: int
+    y: int
+    label: str = ""
+    description: str = ""
+
+    @property
+    def bounds(self) -> tuple[int, int, int, int]:
+        """Get button bounds as (x, y, width, height)."""
+        return (self.x, self.y, self.spec.width, self.spec.height)
+
+    @property
+    def center(self) -> tuple[int, int]:
+        """Get button center coordinates."""
+        return (
+            self.x + self.spec.width // 2,
+            self.y + self.spec.height // 2,
+        )
+
+    @property
+    def tolerance_pixels(self) -> tuple[int, int]:
+        """Get natural tolerance in pixels."""
+        return self.spec.tolerance_pixels
+
+    def tolerance_ru(self, image_size: tuple[int, int]) -> tuple[int, int]:
+        """Get natural tolerance in RU units."""
+        return self.spec.tolerance_ru(image_size)
+
+
+# Common button presets
+SMALL_SQUARE = ButtonSpec(width=16, height=16, shape=ButtonShape.SQUARE, has_icon=True)
+MEDIUM_SQUARE = ButtonSpec(width=24, height=24, shape=ButtonShape.SQUARE, has_icon=True)
+LARGE_SQUARE = ButtonSpec(width=32, height=32, shape=ButtonShape.SQUARE, has_icon=True)
+
+SMALL_RECT = ButtonSpec(width=60, height=24, shape=ButtonShape.RECT, has_label=True)
+MEDIUM_RECT = ButtonSpec(width=80, height=28, shape=ButtonShape.RECT, has_label=True)
+LARGE_RECT = ButtonSpec(width=120, height=32, shape=ButtonShape.RECT, has_label=True)
+
+# Navigation buttons (like calendar back/forward)
+NAV_BUTTON = ButtonSpec(width=20, height=12, shape=ButtonShape.RECT, has_icon=True)
+
+# Toolbar buttons
+TOOLBAR_BUTTON = ButtonSpec(width=24, height=24, shape=ButtonShape.SQUARE, has_icon=True)
+
+# Dialog buttons
+DIALOG_OK = ButtonSpec(width=75, height=23, shape=ButtonShape.RECT, has_label=True)
+DIALOG_CANCEL = ButtonSpec(width=75, height=23, shape=ButtonShape.RECT, has_label=True)

cudag/core/canvas.py

@@ -0,0 +1,222 @@
+# 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
+
+"""Canvas and Region abstractions for screen composition.
+
+Provides a declarative way to define screenshot layouts:
+- Canvas: full screenshot dimensions with base blank image
+- Region: subsection of canvas with optional overlay and generator
+
+Regions can have associated generators for:
+- Grids (calendars, data tables)
+- Icons (desktop icons, toolbars)
+- Content (text, form fields)
+
+Supports loading from YAML/JSON configuration.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class RegionConfig:
+    """Configuration for a region within a canvas."""
+
+    name: str
+    """Unique region identifier."""
+
+    bounds: tuple[int, int, int, int]
+    """Region bounds as (x, y, width, height)."""
+
+    z_index: int = 0
+    """Layer order (higher = on top)."""
+
+    blank_image: str | Path = ""
+    """Optional overlay/blank image for this region."""
+
+    generator_type: str = ""
+    """Generator type: 'grid', 'icons', 'content', etc."""
+
+    generator_config: dict[str, Any] = field(default_factory=dict)
+    """Configuration for the generator."""
+
+    @property
+    def x(self) -> int:
+        return self.bounds[0]
+
+    @property
+    def y(self) -> int:
+        return self.bounds[1]
+
+    @property
+    def width(self) -> int:
+        return self.bounds[2]
+
+    @property
+    def height(self) -> int:
+        return self.bounds[3]
+
+    @property
+    def center(self) -> tuple[int, int]:
+        return (self.x + self.width // 2, self.y + self.height // 2)
+
+    def tolerance_ru(self, image_size: tuple[int, int]) -> tuple[int, int]:
+        """Get natural tolerance in RU units based on region size."""
+        x_ru = (self.width * 0.7 / image_size[0]) * 1000
+        y_ru = (self.height * 0.7 / image_size[1]) * 1000
+        return (int(x_ru), int(y_ru))
+
+
+@dataclass
+class CanvasConfig:
+    """Configuration for a full screenshot canvas."""
+
+    name: str
+    """Canvas identifier."""
+
+    size: tuple[int, int]
+    """Canvas dimensions as (width, height)."""
+
+    blank_image: str | Path
+    """Base blank image for the canvas."""
+
+    regions: list[RegionConfig] = field(default_factory=list)
+    """Regions on this canvas."""
+
+    task_types: list[str] = field(default_factory=list)
+    """Supported task types for this canvas."""
+
+    def get_region(self, name: str) -> RegionConfig | None:
+        """Get a region by name."""
+        for region in self.regions:
+            if region.name == name:
+                return region
+        return None
+
+    def regions_by_z(self) -> list[RegionConfig]:
+        """Get regions sorted by z-index (bottom to top)."""
+        return sorted(self.regions, key=lambda r: r.z_index)
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> CanvasConfig:
+        """Load canvas configuration from YAML file."""
+        with open(path) as f:
+            data = yaml.safe_load(f)
+        return cls.from_dict(data)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CanvasConfig:
+        """Create from dictionary."""
+        regions = []
+        for r in data.get("regions", []):
+            regions.append(
+                RegionConfig(
+                    name=r["name"],
+                    bounds=tuple(r["bounds"]),
+                    z_index=r.get("z_index", 0),
+                    blank_image=r.get("blank_image", ""),
+                    generator_type=r.get("generator", ""),
+                    generator_config=r.get("config", {}),
+                )
+            )
+
+        return cls(
+            name=data["name"],
+            size=tuple(data["size"]),
+            blank_image=data["blank_image"],
+            regions=regions,
+            task_types=data.get("task_types", []),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "name": self.name,
+            "size": list(self.size),
+            "blank_image": str(self.blank_image),
+            "task_types": self.task_types,
+            "regions": [
+                {
+                    "name": r.name,
+                    "bounds": list(r.bounds),
+                    "z_index": r.z_index,
+                    "blank_image": str(r.blank_image) if r.blank_image else "",
+                    "generator": r.generator_type,
+                    "config": r.generator_config,
+                }
+                for r in self.regions
+            ],
+        }
+
+
+# Example YAML format:
+"""
+# canvas.yaml
+name: desktop
+size: [1920, 1080]
+blank_image: assets/blanks/desktop-blank.png
+task_types:
+  - click-desktop-icon
+  - click-taskbar-icon
+
+regions:
+  - name: desktop_area
+    bounds: [0, 0, 1920, 1032]
+    z_index: 0
+    generator: icons
+    config:
+      icon_type: desktop
+      layout: grid
+      cols: 1
+      padding: 20
+
+  - name: taskbar
+    bounds: [0, 1032, 1920, 48]
+    z_index: 1
+    blank_image: assets/blanks/taskbar.png
+    generator: icons
+    config:
+      icon_type: taskbar
+      layout: horizontal
+      start_x: 946
+      padding: 8
+
+# calendar.yaml
+name: calendar
+size: [224, 208]
+blank_image: assets/blanks/calendar-blank.png
+task_types:
+  - click-day
+  - click-back-month
+  - click-forward-month
+
+regions:
+  - name: day_grid
+    bounds: [2, 72, 219, 90]
+    generator: grid
+    config:
+      rows: 6
+      cols: 7
+      cell_width: 24
+      cell_height: 15
+      col_gap: 8
+
+  - name: back_button
+    bounds: [7, 192, 20, 12]
+    generator: button
+    config:
+      label: "Back Month"
+
+  - name: forward_button
+    bounds: [197, 192, 20, 12]
+    generator: button
+    config:
+      label: "Forward Month"
+"""