SisGenAI

SisGenAI generates Sisyphus sand table pattern files (.thr) from natural language prompts using AWS Bedrock and Amazon Nova Canvas. It provides a complete pipeline from raw pattern files through AI labeling, model fine-tuning, and pattern generation.

Table of Contents

• Prerequisites
• Installation
• Configuration
• Project Structure
• Core Concepts
• Usage
  • THR File Processing
  • File Conversion
  • Building a Training Dataset
  • Fine-Tuning Nova Canvas
  • Generating Patterns
  • Vision Prompt Optimization
  • Pattern Analysis
• Configuration Reference
• License

Prerequisites

• Python 3.11+
• AWS account with access to:
  • Amazon Bedrock (Claude Sonnet 4.5, Nova Canvas)
  • Amazon S3
  • IAM permissions for Bedrock model customization
• AWS CLI configured with credentials

Installation

git clone <repository-url>
cd SisGenAI
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

Copy the template and fill in your AWS settings:

cp data/config/userconfig.json.template userconfig.json

{
  "aws_region": "us-east-1",
  "s3_training_bucket": "your-training-bucket",
  "s3_output_bucket": "your-output-bucket",
  "log_level": "INFO",
  "processing_batch_size": 10,
  "max_retries": 3,
  "retry_backoff_factor": 1.0
}

All settings can be overridden with environment variables (which take precedence):

export AWS_REGION="us-east-1"
export S3_TRAINING_BUCKET="your-training-bucket"
export S3_OUTPUT_BUCKET="your-output-bucket"

Project Structure

SisGenAI/
├── scripts/               # CLI entry points
├── utils/                 # File I/O, config, errors, PNG/SVG conversion, THR linting
├── finetuning/            # Nova Canvas fine-tuning pipeline
├── prompt_optimization/   # Iterative vision prompt refinement
├── training/              # Training dataset preparation
├── tests/                 # Unit, integration, and fine-tuning tests
└── data/                  # Example patterns and config templates

Core Concepts

THR Files

THR is the native file format for Sisyphus sand tables. Each file contains polar coordinate pairs (theta, rho) that describe the path a steel ball traces through sand:

• theta: angle in radians (0 = top of table, positive = clockwise)
• rho: normalized radius from 0 (center) to 1 (table edge)
• Files begin with two 0 0 entries (hardware initialization)
• All movement is continuous — there is no pen-lift

Pipeline Overview

THR files
  → Lint (remove infrastructure elements)
  → Convert to PNG (2048x2048, gradient rendering)
  → AI labeling via Claude (batch inference)
  → Convert labels to Nova Canvas training format
  → Fine-tune Nova Canvas on Bedrock
  → Generate new patterns from text prompts

Usage

THR File Processing

Parse and validate THR files programmatically:

from utils.file_io import THRProcessor

processor = THRProcessor(strict_validation=True)
coordinates = processor.parse_file(Path("pattern.thr"))

File Conversion

Convert THR files to PNG with a blue-to-purple-to-red gradient showing drawing order:

python3 scripts/convert_thr_to_png_gradient.py pattern.thr
python3 scripts/convert_thr_to_png_gradient.py pattern.thr output.png --width 2048 --height 2048

Convert to PNG with a plain single-color rendering:

python3 scripts/convert_thr_to_png.py pattern.thr

Convert to SVG with automatic spiral interpolation for simple patterns:

python3 scripts/convert_thr_to_svg.py pattern.thr output.svg

THR Linting

Strip hardware infrastructure elements (initialization coordinates, radial lines, large transition spirals) from the first 5 lines of each file:

python3 scripts/lint_thr_files.py \
    --input-dir data/example_patterns_multiple_filetypes \
    --output-dir data/linted_thrs

Building a Training Dataset

The dataset builder runs the full pipeline from raw THR files to a submitted Bedrock batch inference job:

1. Parses and lints THR files
2. Converts to 2048x2048 gradient PNGs
3. Prepares JSONL for batch inference
4. Uploads PNGs, THR files, and JSONL to S3
5. Submits a Claude Sonnet 4.5 batch inference job for AI labeling

python3 scripts/build_training_dataset.py \
    --input-dir data/patterns \
    --s3-bucket my-training-bucket \
    --batch-role-arn arn:aws:iam::123456789012:role/BedrockBatchRole

Fine-Tuning Nova Canvas

After batch inference completes, convert the output to Nova Canvas training format:

python3 scripts/convert_dataset_for_nova.py \
    --batch-output-path s3://my-bucket/batch_output/results.jsonl.out \
    --image-mapping-file image_mapping.json \
    --output-bucket my-models-bucket

For local datasets that don't require S3:

python3 scripts/convert_local_dataset_to_jsonl.py \
    --input-dir ./training_data/output \
    --output-dir ./nova_training_data

Submit a fine-tuning job to Bedrock. The finetuning/ module handles IAM role creation, job submission, progress monitoring, and metrics retrieval automatically. See docs/nova_finetuning.md for the full walkthrough.

Generating Patterns

Generate pattern images from text prompts using a fine-tuned Nova Canvas model:

# Single prompt
python3 scripts/generate_patterns_nova.py \
    --model-arn arn:aws:bedrock:us-east-1:123456789012:custom-model/... \
    --prompt "spiral with radiating lines"

# Batch from file
python3 scripts/generate_patterns_nova.py \
    --model-arn <arn> \
    --prompt-file prompts.txt \
    --output-dir ./output

# With validation against training samples
python3 scripts/generate_patterns_nova.py \
    --model-arn <arn> \
    --prompt "circular pattern" \
    --validate \
    --training-samples-dir ./training_samples

Vision Prompt Optimization

Iteratively refine the vision prompt used for AI labeling. The optimizer selects complex patterns, labels them with competing prompt variants, presents side-by-side comparisons, collects your feedback, and evolves the prompt across generations:

python3 scripts/optimize_vision_prompt.py \
    --dataset-path ./nova_training_data \
    --num-patterns 20 \
    --max-generations 10

Pattern Analysis

Analyze individual pattern images using Claude's vision capabilities:

# Single image
python3 scripts/analyze_pattern.py pattern.png --output labels.json

# Batch
python3 scripts/analyze_pattern.py input_dir/ --batch --output-dir output/

Configuration Reference

Setting	Env Variable	Default	Description
aws_region	AWS_REGION	us-east-1	AWS region for service calls
s3_training_bucket	S3_TRAINING_BUCKET	—	S3 bucket for training data
s3_output_bucket	S3_OUTPUT_BUCKET	—	S3 bucket for processed outputs
log_level	LOG_LEVEL	INFO	Logging level
processing_batch_size	PROCESSING_BATCH_SIZE	10	Files per processing batch
max_retries	MAX_RETRIES	3	AWS call retry attempts
retry_backoff_factor	RETRY_BACKOFF_FACTOR	1.0	Exponential backoff factor

Fine-tuning has its own configuration via finetuning/config.py (NovaConfig), covering Bedrock model IDs, S3 buckets for model artifacts, IAM roles, and hyperparameters. See docs/nova_finetuning.md for details.

License

MIT License — see LICENSE file for details.