cudag 0.3.10__py3-none-any.whl

cudag/server/__init__.py

@@ -0,0 +1,21 @@
+# 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
+
+"""CUDAG Server - FastAPI server for annotation-to-generator workflow.
+
+This module provides a local HTTP server that the Annotator UI can call
+to generate CUDAG projects from annotations without using the terminal.
+
+Start the server:
+    cudag serve --port 8420
+
+The server exposes:
+    GET  /health           - Health check
+    POST /api/v1/generate  - Generate project from annotation
+    GET  /api/v1/status/{job_id} - Check generation progress
+"""
+
+from cudag.server.app import create_app, run_server
+
+__all__ = ["create_app", "run_server"]

cudag/server/app.py

@@ -0,0 +1,232 @@
+# 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
+
+"""FastAPI application for CUDAG server."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, HTTPException, BackgroundTasks
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel, Field
+
+from cudag import __version__
+from cudag.server.services.generator import GeneratorService
+
+# In-memory job storage (for MVP - would use Redis/DB in production)
+_jobs: dict[str, dict[str, Any]] = {}
+
+
+class GenerateOptions(BaseModel):
+    """Options for project generation."""
+
+    project_name: str = Field(..., description="Name for the generated project")
+    output_dir: str | None = Field(None, description="Output directory (default: ~/cudag-projects)")
+    num_samples: int = Field(1000, description="Number of samples per task")
+    generate_immediately: bool = Field(True, description="Run generation after scaffolding")
+
+
+class GenerateRequest(BaseModel):
+    """Request body for generate endpoint."""
+
+    annotation: dict = Field(..., description="Full annotation.json data")
+    original_image: str = Field(..., description="Base64 encoded original image")
+    masked_image: str | None = Field(None, description="Base64 encoded masked image")
+    icons: dict[str, str] | None = Field(None, description="Map of icon names to base64 images")
+    options: GenerateOptions
+
+
+class GenerateResponse(BaseModel):
+    """Response from generate endpoint."""
+
+    status: str
+    project_path: str | None = None
+    files_created: list[str] | None = None
+    job_id: str | None = None
+    error: str | None = None
+
+
+class StatusResponse(BaseModel):
+    """Response from status endpoint."""
+
+    progress: int
+    total: int
+    current_task: str | None = None
+    done: bool
+    error: str | None = None
+
+
+class HealthResponse(BaseModel):
+    """Response from health endpoint."""
+
+    status: str
+    version: str
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage application lifespan."""
+    # Startup
+    yield
+    # Shutdown - cleanup jobs
+    _jobs.clear()
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="CUDAG Server",
+        description="Generate CUDAG projects from annotations",
+        version=__version__,
+        lifespan=lifespan,
+    )
+
+    # Configure CORS for local development
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost:3000", "http://127.0.0.1:3000"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.get("/health", response_model=HealthResponse)
+    async def health_check() -> HealthResponse:
+        """Check server health."""
+        return HealthResponse(status="healthy", version=__version__)
+
+    @app.post("/api/v1/generate", response_model=GenerateResponse)
+    async def generate_project(
+        request: GenerateRequest,
+        background_tasks: BackgroundTasks,
+    ) -> GenerateResponse:
+        """Generate a CUDAG project from annotation data."""
+        try:
+            service = GeneratorService()
+
+            # Validate annotation
+            validation_error = service.validate_annotation(request.annotation)
+            if validation_error:
+                return GenerateResponse(status="error", error=validation_error)
+
+            # Determine output directory
+            output_dir = Path(request.options.output_dir or "~/cudag-projects").expanduser()
+            project_dir = output_dir / request.options.project_name
+
+            # Scaffold the project
+            files_created = service.scaffold_project(
+                annotation=request.annotation,
+                original_image=request.original_image,
+                masked_image=request.masked_image,
+                icons=request.icons,
+                project_dir=project_dir,
+            )
+
+            # If generate_immediately, run generation in background
+            if request.options.generate_immediately:
+                job_id = str(uuid.uuid4())
+                _jobs[job_id] = {
+                    "progress": 0,
+                    "total": request.options.num_samples,
+                    "current_task": "Starting generation...",
+                    "done": False,
+                    "error": None,
+                    "project_dir": str(project_dir),
+                }
+
+                background_tasks.add_task(
+                    _run_generation,
+                    job_id=job_id,
+                    project_dir=project_dir,
+                    num_samples=request.options.num_samples,
+                )
+
+                return GenerateResponse(
+                    status="generating",
+                    project_path=str(project_dir),
+                    files_created=files_created,
+                    job_id=job_id,
+                )
+
+            return GenerateResponse(
+                status="success",
+                project_path=str(project_dir),
+                files_created=files_created,
+            )
+
+        except Exception as e:
+            return GenerateResponse(status="error", error=str(e))
+
+    @app.get("/api/v1/status/{job_id}", response_model=StatusResponse)
+    async def get_status(job_id: str) -> StatusResponse:
+        """Get the status of a generation job."""
+        if job_id not in _jobs:
+            raise HTTPException(status_code=404, detail="Job not found")
+
+        job = _jobs[job_id]
+        return StatusResponse(
+            progress=job["progress"],
+            total=job["total"],
+            current_task=job.get("current_task"),
+            done=job["done"],
+            error=job.get("error"),
+        )
+
+    return app
+
+
+async def _run_generation(
+    job_id: str,
+    project_dir: Path,
+    num_samples: int,
+) -> None:
+    """Run dataset generation in background."""
+    try:
+        service = GeneratorService()
+
+        # Update progress callback
+        def on_progress(progress: int, task: str) -> None:
+            if job_id in _jobs:
+                _jobs[job_id]["progress"] = progress
+                _jobs[job_id]["current_task"] = task
+
+        await asyncio.to_thread(
+            service.run_generation,
+            project_dir=project_dir,
+            num_samples=num_samples,
+            progress_callback=on_progress,
+        )
+
+        if job_id in _jobs:
+            _jobs[job_id]["done"] = True
+            _jobs[job_id]["current_task"] = "Generation complete"
+
+    except Exception as e:
+        if job_id in _jobs:
+            _jobs[job_id]["done"] = True
+            _jobs[job_id]["error"] = str(e)
+
+
+def run_server(host: str = "127.0.0.1", port: int = 8420, reload: bool = False) -> None:
+    """Run the CUDAG server.
+
+    Args:
+        host: Host to bind to
+        port: Port to listen on
+        reload: Enable auto-reload for development
+    """
+    import uvicorn
+
+    uvicorn.run(
+        "cudag.server.app:create_app",
+        host=host,
+        port=port,
+        reload=reload,
+        factory=True,
+    )

cudag/server/services/__init__.py

@@ -0,0 +1,9 @@
+# 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
+
+"""Server services for CUDAG."""
+
+from cudag.server.services.generator import GeneratorService
+
+__all__ = ["GeneratorService"]

cudag/server/services/generator.py

@@ -0,0 +1,128 @@
+# 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 service for creating CUDAG projects from annotations."""
+
+from __future__ import annotations
+
+import base64
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any, Callable
+
+from cudag.annotation.loader import AnnotationLoader, ParsedAnnotation
+from cudag.annotation.scaffold import scaffold_generator
+
+
+class GeneratorService:
+    """Service for generating CUDAG projects from annotation data."""
+
+    def __init__(self) -> None:
+        self.loader = AnnotationLoader()
+
+    def validate_annotation(self, annotation: dict[str, Any]) -> str | None:
+        """Validate annotation data.
+
+        Args:
+            annotation: Raw annotation dictionary
+
+        Returns:
+            Error message if invalid, None if valid
+        """
+        required_fields = ["screenName", "imageSize", "elements"]
+        for field in required_fields:
+            if field not in annotation:
+                return f"Missing required field: {field}"
+
+        if not isinstance(annotation["elements"], list):
+            return "elements must be a list"
+
+        if not isinstance(annotation["imageSize"], list) or len(annotation["imageSize"]) != 2:
+            return "imageSize must be a [width, height] array"
+
+        return None
+
+    def scaffold_project(
+        self,
+        annotation: dict[str, Any],
+        original_image: str,
+        masked_image: str | None,
+        icons: dict[str, str] | None,
+        project_dir: Path,
+    ) -> list[str]:
+        """Scaffold a CUDAG project from annotation data.
+
+        Args:
+            annotation: Full annotation.json data
+            original_image: Base64 encoded original image
+            masked_image: Base64 encoded masked image (optional)
+            icons: Map of icon names to base64 images (optional)
+            project_dir: Directory to create project in
+
+        Returns:
+            List of created file paths (relative to project_dir)
+        """
+        # Parse annotation
+        parsed = self.loader.parse_dict(annotation)
+
+        # Decode images
+        original_bytes = base64.b64decode(original_image)
+        masked_bytes = base64.b64decode(masked_image) if masked_image else None
+        icon_bytes = {
+            name: base64.b64decode(data)
+            for name, data in (icons or {}).items()
+        }
+
+        # Scaffold the project
+        created_files = scaffold_generator(
+            name=parsed.screen_name,
+            annotation=parsed,
+            output_dir=project_dir.parent,
+            original_image=original_bytes,
+            masked_image=masked_bytes,
+            icons=icon_bytes,
+        )
+
+        return [str(f.relative_to(project_dir)) for f in created_files]
+
+    def run_generation(
+        self,
+        project_dir: Path,
+        num_samples: int,
+        progress_callback: Callable[[int, str], None] | None = None,
+    ) -> None:
+        """Run dataset generation for a scaffolded project.
+
+        Args:
+            project_dir: Path to the project directory
+            num_samples: Number of samples to generate per task
+            progress_callback: Callback for progress updates (progress, task_name)
+        """
+        generator_script = project_dir / "generator.py"
+        if not generator_script.exists():
+            raise FileNotFoundError(f"Generator script not found: {generator_script}")
+
+        # Run the generator
+        if progress_callback:
+            progress_callback(0, "Starting generator...")
+
+        result = subprocess.run(
+            [
+                sys.executable,
+                str(generator_script),
+                "--samples",
+                str(num_samples),
+            ],
+            cwd=project_dir,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Generation failed: {result.stderr}")
+
+        if progress_callback:
+            progress_callback(num_samples, "Generation complete")

cudag/templates/scripts/archive.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025 Tylt LLC. All rights reserved.
+# Derivative works may be released by researchers,
+# but original files may not be redistributed or used beyond research purposes.
+#
+# DO NOT EDIT THIS FILE - Generated by cudag framework
+
+# Archive a dataset directory into a tar.gz file
+#
+# Usage:
+#   ./scripts/archive.sh [dataset_dir]
+
+set -euo pipefail
+
+DATASET_DIR="${1:-}"
+
+if [[ -z "$DATASET_DIR" ]]; then
+    # Find most recent dataset
+    DATASET_DIR=$(ls -td datasets/*/ 2>/dev/null | head -1)
+    if [[ -z "$DATASET_DIR" ]]; then
+        echo "No dataset directory found. Specify path or run generate.sh first."
+        exit 1
+    fi
+fi
+
+DATASET_NAME=$(basename "$DATASET_DIR")
+ARCHIVE_NAME="datasets/${DATASET_NAME}.tar.gz"
+
+echo "Archiving: $DATASET_DIR"
+echo "Output: $ARCHIVE_NAME"
+
+tar -czvf "$ARCHIVE_NAME" -C "$(dirname "$DATASET_DIR")" "$DATASET_NAME"
+
+echo ""
+echo "Archive created: $ARCHIVE_NAME"

cudag/templates/scripts/build.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025 Tylt LLC. All rights reserved.
+# Derivative works may be released by researchers,
+# but original files may not be redistributed or used beyond research purposes.
+#
+# DO NOT EDIT THIS FILE - Generated by cudag framework
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+"$repo_root/scripts/pre-commit.sh" --all

cudag/templates/scripts/extract.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025 Tylt LLC. All rights reserved.
+# Derivative works may be released by researchers,
+# but original files may not be redistributed or used beyond research purposes.
+#
+# DO NOT EDIT THIS FILE - Generated by cudag framework
+
+# Pipeline: generate.sh -> upload.sh -> extract.sh -> preprocess.sh
+#
+# Usage:
+#   ./scripts/extract.sh --dataset-name <NAME>
+
+set -euo pipefail
+
+DATASET_NAME=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --dataset-name)
+            DATASET_NAME="${2:-}"
+            shift 2
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$DATASET_NAME" ]]; then
+    echo "Error: --dataset-name <NAME> is required"
+    exit 1
+fi
+
+echo "========================================"
+echo "STAGE 3: Extract Dataset"
+echo "========================================"
+echo ""
+echo "Dataset: $DATASET_NAME"
+echo ""
+
+# Find cudag's extract.py location and run via Modal
+CUDAG_PATH=$(uvx --with cudag python -c "import cudag.modal_apps.extract as e; print(e.__file__)")
+uvx modal run "$CUDAG_PATH" --dataset-name "$DATASET_NAME"
+
+echo ""
+echo "Extraction complete for: $DATASET_NAME"
+
+echo ""
+echo "========================================"
+echo "Auto-starting preprocessing..."
+echo "========================================"
+echo ""
+
+exec ./scripts/preprocess.sh --dataset-name "$DATASET_NAME"

cudag/templates/scripts/generate.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025 Tylt LLC. All rights reserved.
+# Derivative works may be released by researchers,
+# but original files may not be redistributed or used beyond research purposes.
+#
+# DO NOT EDIT THIS FILE - Generated by cudag framework
+
+# Usage:
+#   ./scripts/generate.sh [options]           # Generate and auto-upload
+#   ./scripts/generate.sh --dry [options]     # Generate only, no upload
+#   ./scripts/generate.sh --verify            # Generate with interactive verification
+#   ./scripts/generate.sh --verify --verbose  # Verify with streaming output
+
+set -euo pipefail
+
+DRY_RUN=false
+VERIFY_MODE=false
+VERBOSE=false
+EXTRA_ARGS=()
+
+# Parse args - extract --dry, --verify, --verbose, pass everything else through
+for arg in "$@"; do
+    if [[ "$arg" == "--dry" ]]; then
+        DRY_RUN=true
+    elif [[ "$arg" == "--verify" ]]; then
+        VERIFY_MODE=true
+        DRY_RUN=true  # verify implies dry run
+    elif [[ "$arg" == "--verbose" ]] || [[ "$arg" == "-v" ]]; then
+        VERBOSE=true
+    else
+        EXTRA_ARGS+=("$arg")
+    fi
+done
+
+# If verify mode, delegate to verify.py which handles the loop
+if [[ "$VERIFY_MODE" == "true" ]]; then
+    echo "========================================"
+    echo "Interactive Dataset Verification"
+    echo "========================================"
+    echo ""
+
+    # Use prod config by default
+    CONFIG_PATH="config/dataset.prod.yaml"
+    for i in "${!EXTRA_ARGS[@]}"; do
+        if [[ "${EXTRA_ARGS[$i]}" == "--config" ]] && [[ $((i+1)) -lt ${#EXTRA_ARGS[@]} ]]; then
+            CONFIG_PATH="${EXTRA_ARGS[$((i+1))]}"
+            break
+        fi
+    done
+
+    VERIFY_ARGS=(--config "$CONFIG_PATH")
+    if [[ "$VERBOSE" == "true" ]]; then
+        VERIFY_ARGS+=(--verbose)
+    fi
+
+    exec uv run python scripts/verify.py "${VERIFY_ARGS[@]}"
+fi
+
+echo "========================================"
+echo "STAGE 1: Generate Dataset"
+echo "========================================"
+echo ""
+
+if [[ "$DRY_RUN" == "true" ]]; then
+    echo "[DRY RUN] Will generate but NOT upload"
+    echo ""
+fi
+
+# Run the dataset generation using uv run (uses pyproject.toml dependencies)
+# Set env var so generator.py knows it was called from this script
+export CUDAG_FROM_SCRIPT=1
+
+if [[ ${#EXTRA_ARGS[@]} -gt 0 ]]; then
+    uv run python generator.py "${EXTRA_ARGS[@]}"
+else
+    uv run python generator.py
+fi
+
+if [[ $? -ne 0 ]]; then
+    echo ""
+    echo "Dataset generation failed"
+    exit 1
+fi
+
+# Find the most recently created dataset directory
+LATEST_DATASET=$(ls -td datasets/*/ 2>/dev/null | head -1)
+
+if [[ -z "$LATEST_DATASET" ]]; then
+    echo ""
+    echo "No dataset directory found"
+    exit 1
+fi
+
+DATASET_NAME=$(basename "$LATEST_DATASET")
+echo ""
+echo "Generated dataset: $DATASET_NAME"
+
+if [[ "$DRY_RUN" == "true" ]]; then
+    echo ""
+    echo "[DRY RUN] Skipping upload"
+    echo ""
+    echo "To verify interactively:"
+    echo "  ./scripts/generate.sh --verify"
+    echo ""
+    echo "To upload manually:"
+    echo "  ./scripts/upload.sh datasets/$DATASET_NAME"
+    exit 0
+fi
+
+echo ""
+echo "========================================"
+echo "Auto-starting upload..."
+echo "========================================"
+echo ""
+
+exec ./scripts/upload.sh "datasets/$DATASET_NAME"

cudag/templates/scripts/pre-commit.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Copyright (c) 2025 Tylt LLC. All rights reserved.
+# Derivative works may be released by researchers,
+# but original files may not be redistributed or used beyond research purposes.
+#
+# DO NOT EDIT THIS FILE - Generated by cudag framework
+
+set -euo pipefail
+
+mode="${1:-staged}"
+
+if [ "$mode" = "--help" ] || [ "$mode" = "-h" ]; then
+  echo "Usage: $0 [--all]" >&2
+  echo "  --all   Run checks against all tracked Python files instead of staged ones." >&2
+  exit 0
+fi
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$repo_root"
+
+if [ "$mode" = "--all" ]; then
+  py_targets=$(git ls-files -- '*.py' 2>/dev/null || find . -name '*.py' -type f)
+  scope_label="all Python files"
+else
+  py_targets=$(git diff --cached --name-only --diff-filter=ACM -- '*.py' 2>/dev/null || true)
+  scope_label="staged Python files"
+fi
+
+if [ -z "$py_targets" ]; then
+  echo "No ${scope_label}. Skipping lint/type checks."
+  exit 0
+fi
+
+# Use uv run to execute in the project's venv with dev dependencies (Python 3.12)
+UV_RUN="uv run --python 3.12 --extra dev"
+
+echo "Running ruff (lexical checks) on ${scope_label}..."
+printf '%s\n' "$py_targets" | xargs $UV_RUN ruff check
+
+echo "Running mypy (syntax & types) on ${scope_label}..."
+printf '%s\n' "$py_targets" | xargs $UV_RUN mypy
+
+echo ""
+echo "✓ All checks passed!"