maze update

app.py

@@ -37,12 +37,9 @@ import gc
 # Import functions from modules
 from utils.file_utils import (
     cleanup_temp_files, 
-    get_file_parts
+    get_file_parts,
+    generate_permalink_from_urls
 )
-from utils.storage import (
-    generate_permalink_from_urls,
-    upload_files_to_repo,
-    )
 
 from utils.color_utils import (
     hex_to_rgb,
@@ -119,16 +116,18 @@ from diffusers import (
     FluxFillPipeline,
     DiffusionPipeline, 
     AutoencoderTiny, 
-    AutoencoderKL
+    AutoencoderKL,
+    Flux2Pipeline, AutoModel
 )
 
 PIPELINE_CLASSES = {
     "FluxPipeline": FluxPipeline,
     "FluxImg2ImgPipeline": FluxImg2ImgPipeline,
     "FluxControlPipeline": FluxControlPipeline,
-    "FluxFillPipeline": FluxFillPipeline
+    "FluxFillPipeline": FluxFillPipeline,
+    "Flux2Pipeline": Flux2Pipeline
 }
-
+from utils.mazlib.cli import run_maze as run_maze_maker
 import utils.version_info as version_info
 
 #from utils.depth_estimation import (get_depth_map_from_state)
@@ -819,6 +818,79 @@ def replace_with_sketch_image(sketch_image, replace_current_lut_example_img: boo
     if replace_current_lut_example_img:
         current_lut_example_img = sketch
     return sketch
+
+def update_maze_maker_shape_visibility(shape):
+    shape_key = (shape or "rect").lower()
+    is_hex = shape_key in ("hex", "hexagon", "hexagonal")
+    # show width/height for non-hex, show radius for hex
+    return (
+        gr.update(visible=not is_hex),
+        gr.update(visible=not is_hex),
+        gr.update(visible=is_hex),
+    )
+
+
+def generate_and_apply_maze_to_input(shape, width, height, radius, cell_size, use_iterative, show_solution, show_doors, input_image, opacity_percent):
+    shape_key = (shape or "rect").lower()
+
+    if shape_key in ("hex", "hexagon", "hexagonal"):
+        normalized_size = max(1, int(radius))
+    else:
+        w = max(5, int(width))
+        h = max(5, int(height))
+        if w % 2 == 0:
+            w += 1
+        if h % 2 == 0:
+            h += 1
+        normalized_size = (w, h)
+
+    with NamedTemporaryFile(delete=False, suffix=".png", prefix="maze_maker_") as tmp_maze:
+        maze_output_path = tmp_maze.name
+
+    try:
+        _, solution_path = run_maze_maker(
+            shape=shape_key,
+            size=normalized_size,
+            cell=max(4, int(cell_size)),
+            use_iterative=bool(use_iterative),
+            draw=True,
+            output=maze_output_path,
+            show_solution=bool(show_solution),
+            show_doors=bool(show_doors),
+        )
+        constants.temp_files.append(maze_output_path)
+    except Exception as ex:
+        raise gr.Error(f"Failed to generate maze: {ex}")
+
+    path_info = f"path nodes: {len(solution_path)}" if solution_path else "no solution path found"
+    status = f"Maze created ({shape_key}, size={normalized_size}, {path_info}) and applied to Input Image."
+
+    # If there's no input image provided, return the generated maze image path
+    # (returning a file path avoids Gradio creating temporary PIL files which
+    # previously led to intermittent FileNotFoundError on chained calls).
+    if not input_image:
+        return maze_output_path, status
+
+    try:
+        base_img = open_image(input_image) if isinstance(input_image, str) else input_image
+        overlay = open_image(maze_output_path)
+        # ensure RGBA and resize overlay to match base image
+        if overlay.mode != 'RGBA':
+            overlay = overlay.convert('RGBA')
+        if overlay.size != base_img.size:
+            overlay = overlay.resize(base_img.size, Image.LANCZOS)
+
+        result = alpha_composite_with_control(base_img, overlay, opacity_percent)
+
+        # save to temp file and return path
+        with NamedTemporaryFile(delete=False, suffix=".png", prefix="maze_composite_") as outf:
+            result.convert('RGBA').save(outf.name, format='PNG')
+            constants.temp_files.append(outf.name)
+            return outf.name, status
+    except Exception as ex:
+        # fallback: return generated maze image if compositing fails
+        print(f"Maze compositing failed: {ex}")
+        return maze_output_path, status
 ################################################################## DEPTH ESTIMATION ###############################################################################
 
 @spaces.GPU(progress=gr.Progress(track_tqdm=True))
@@ -1794,6 +1866,24 @@ with gr.Blocks(title=title, delete_cache=(21600,86400)) as hexaGrid:
         outputs=[input_image], scroll_to_output=True
     )
 
+    # Maze Maker handlers
+    maze_shape.change(
+        fn=update_maze_maker_shape_visibility,
+        inputs=[maze_shape],
+        outputs=[maze_width, maze_height, maze_radius]
+    )
+
+    maze_apply_button.click(
+        fn=generate_and_apply_maze_to_input,
+        inputs=[maze_shape, maze_width, maze_height, maze_radius, maze_cell_size, maze_use_iterative, maze_show_solution, maze_show_doors, input_image, maze_opacity],
+        outputs=[input_image, maze_status],
+        scroll_to_output=True
+    ).then(
+        fn=update_sketch_dimensions,
+        inputs=[input_image, sketch_image],
+        outputs=[sketch_image, sketch_image]
+    )
+
     ##################### model #######################################
     model_textbox.change(
         fn=update_prompt_notes,

requirements.txt

@@ -106,3 +106,10 @@ https://huggingface.co/spaces/Surn/HexaGrid/resolve/main/wheels/diff_gaussian_ra
 #https://github.com/PozzettiAndrea/cuda-wheels/releases/download/nvdiffrast-latest/nvdiffrast-0.4.0%2Bcu128torch2.9-cp312-cp312-win_amd64.whl
 
 #https://github.com/PozzettiAndrea/cuda-wheels/releases/download/nvdiffrast-latest/nvdiffrast-0.4.0%2Bcu128torch2.10-cp312-cp312-win_amd64.whl
+
+# kaolin update
+
+tornado
+flask
+kaolin @ https://huggingface.co/spaces/Surn/HexaGrid/resolve/main/wheels/kaolin-0.18.0-cp312-cp312-linux_x86_64.whl ; sys_platform == "linux"
+kaolin @ https://huggingface.co/spaces/Surn/HexaGrid/resolve/main/wheels/kaolin-0.18.0-cp312-cp312-win_amd64.whl ; sys_platform == "win32"

style_20250314.css

@@ -21,7 +21,7 @@
     /*background-color: rgba(242, 218, 163, 0.62);*/
 }
 
-.dark .gradio-container.gradio-container-5-29-1 .contain .intro .prose {
+.dark .gradio-container.gradio-container-6-10-0 .contain .intro .prose {
     /*background-color: rgba(41, 18, 5, 0.38) !important;*/
 }
 .toast-body.info {

utils/constants.py

@@ -68,7 +68,6 @@ TMPDIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'tmp')
 os.makedirs(TMPDIR, exist_ok=True)
 
 
-
 PROMPTS = {
     "Mecha Wasteland Arena": "Regional overhead view, directly from above, centered on the map, orthographic Mecha battlefield map. post-industrial wasteland with crumbling structures, volcanic ridges, scrapyards, and ash plains. Features elevated overwatch positions for long-range combat and tight brawling areas for close-quarters engagements. Partial edge hexes are black. Colors: red, gray, muted orange, ash white, dark brown.",
     "BorderBlack": "Planetary overhead view, directly from above, centered on the planet’s surface, orthographic hexagon-based alien world map with black borders. Features rivers, mountains, volcanoes, and polar snow regions. Colors: light blue, green, tan, brown. No reflections or shadows. Partial edge hexes are black.",
@@ -209,7 +208,8 @@ MODELS = [
     "black-forest-labs/FLUX.1-schnell",
     "black-forest-labs/FLUX.1-dev",
     "ostris/Flex.1-alpha",
-    "black-forest-labs/FLUX.1-Fill-dev"
+    "black-forest-labs/FLUX.1-Fill-dev",
+    "diffusers/FLUX.2-dev-bnb-4bit",
 ]
 # Available LoRA weights
 LORA_WEIGHTS = [
@@ -227,6 +227,8 @@ LORA_WEIGHTS = [
     "gokaygokay/Flux-Seamless-Texture-LoRA",
     "gokaygokay/Flux-Game-Assets-LoRA-v2",
     "lrzjason/ObjectRemovalFluxFill",
+    "strangerzonehf/Flux-Super-Realism-LoRA",
+    "fal/FLUX.2-dev-Turbo",
 ]
 
 # Map each LoRA weight to its corresponding model
@@ -246,6 +248,8 @@ LORA_TO_MODEL = {
     "gokaygokay/Flux-Seamless-Texture-LoRA":"black-forest-labs/FLUX.1-dev",
     "gokaygokay/Flux-Game-Assets-LoRA-v2":"black-forest-labs/FLUX.1-dev",
     "lrzjason/ObjectRemovalFluxFill":"black-forest-labs/FLUX.1-Fill-dev",
+    "fal/FLUX.2-dev-Turbo": "black-forest-labs/FLUX.2-dev-Turbo",
+    "strangerzonehf/Flux-Super-Realism-LoRA": "black-forest-labs/FLUX.2-dev-Turbo"
 }
 condition_type = ["depth", "canny", "subject", "coloring", "deblurring", "fill", "redux"]
 
@@ -489,7 +493,7 @@ LORA_DETAILS = {
         },
         {
             "thumbnail": "https://huggingface.co/Borcherding/FLUX.1-dev-LoRA-FractalLand-v0.1/resolve/main/images/example_e2zoqwftv.png",
-            "show_in_gallery": True
+            "show_in_gallery": False
         }
     ],
     "strangerzonehf/Flux-Cute-3D-Kawaii-LoRA": [
@@ -585,6 +589,22 @@ LORA_DETAILS = {
             "show_in_gallery": False
         }
     ],
+    "fal/FLUX.2-dev-Turbo": [
+        {"weight_name": "flux.2-turbo-lora.safetensors"},
+        {"title": "FLUX.2 Turbo"},
+        {"trigger_words": "https://huggingface.co/spaces/Surn/HexaGrid/resolve/main/images/prerendered/flux2-turbo-lora.png"},
+        {"notes": "Turbo LoRA for 8-step fast generation."},
+        {"parameters": {"num_inference_steps": "8", "guidance_scale": "2.5"}},
+        {"thumbnail": "images/prerendered/flux2-turbo-lora.png", "show_in_gallery": True}
+    ],
+    "strangerzonehf/Flux-Super-Realism-LoRA": [
+        {"trigger_words": "Super Realism, "},
+        {"weight_name": "super-realism.safetensors"},
+        {"title": "Super Realism"},
+        {"notes": "Excellent photorealism. Use 'realistic, photoreal' keywords too."},
+        {"parameters": {"num_inference_steps": "28", "guidance_scale": "3.5"}},
+        {"thumbnail": "https://huggingface.co/strangerzonehf/Flux-Super-Realism-LoRA/resolve/main/images/sz.png", "show_in_gallery": True}
+    ]
 }
 
 def sort_loras(sortby):
@@ -686,4 +706,9 @@ audio_extensions = {".mp3", ".wav", ".ogg", ".flac", ".aac"}
 audio_extensions_list = list(audio_extensions)
 video_extensions = {".mp4"}
 video_extensions_list = list(video_extensions)
-upload_file_types = model_extensions_list + image_extensions_list + audio_extensions_list + video_extensions_list
+# BattleWords storage module expects document types to be part of uploadable types.
+# Keep this minimal for HexaGrid: JSON is used by the URL shortener registry.
+doc_extensions = {".json"}
+doc_extensions_list = list(doc_extensions)
+
+upload_file_types = model_extensions_list + image_extensions_list + audio_extensions_list + video_extensions_list + doc_extensions_list

utils/file_utils.py

@@ -103,4 +103,23 @@ def get_unique_file_path(directory, filename, file_ext, counter=0):
         return get_unique_file_path(directory, filename, file_ext, counter + 1)
 
 # Example usage:
-# new_file_path = get_unique_file_path(video_dir, title_file_name, video_new_ext)
+# new_file_path = get_unique_file_path(video_dir, title_file_name, video_new_ext)
+
+def generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_url="surn-3d-viewer.hf.space"):
+    """
+    Constructs and returns a permalink URL with query string parameters for the viewer.
+    Each parameter is passed separately so that the image positions remain consistent.
+    
+    Parameters:
+        model_url (str): Processed URL for the 3D model.
+        hm_url (str): Processed URL for the height map image.
+        img_url (str): Processed URL for the main image.
+        permalink_viewer_url (str): The base viewer URL.
+    
+    Returns:
+        str: The generated permalink URL.
+    """
+    import urllib.parse
+    params = {"3d": model_url, "hm": hm_url, "image": img_url}
+    query_str = urllib.parse.urlencode(params)
+    return f"https://{permalink_viewer_url}/?{query_str}"

utils/image_utils.py

@@ -6,7 +6,7 @@ import base64
 import numpy as np
 import rembg
 #from decimal import ROUND_CEILING
-from PIL import Image, ImageChops, ImageDraw, ImageEnhance, ImageFilter, ImageDraw, ImageOps, ImageMath
+from PIL import Image, ImageChops, ImageDraw, ImageEnhance, ImageFilter, ImageDraw, ImageOps, ImageMath, ImageFont
 from typing import List, Union, is_typeddict
 #import numpy as np
 #import math
@@ -1444,4 +1444,98 @@ def combine_depth_map_with_Image(image:Image, depth_img:Image, width:int, height
     resized_depth_image = resize_image_with_aspect_ratio(depth_img, width, height)
     depth_no_background = rembg.remove(resized_depth_image, session = rembg.new_session(rembg_session_name))
     combined_depth_img = multiply_and_blend_images(image, depth_no_background, (alpha / 100))
-    return combined_depth_img
+    return combined_depth_img
+
+def add_watermark(
+    original_img: "Image.Image",
+    watermark_img: "Image.Image",
+    overlay_text: str = "",
+    watermark_size: tuple[int, int] = (100, 100),
+    watermark_position: tuple[int, int] = None,
+    text_position: tuple[str, str] = ("bottom", "right"),
+    text_color: tuple[int, int, int, int] = (107, 78, 156, 255),
+    text_font_path: str = "fonts/Roboto-Regular.ttf",
+    text_font_size: int = 20,
+    blend_alpha: float = 0.4,
+    dpi: tuple[int, int] = None
+) -> "Image.Image":
+    """
+    Adds a watermark overlay onto the original image by pasting the watermark image
+    (resized to watermark_size) and overlaying the provided text.
+
+    Parameters:
+        original_img (Image.Image): The input image to watermark. Expected in RGBA mode.
+        watermark_img (Image.Image): The watermark image to overlay. Expected in RGBA mode.
+        overlay_text (str): Optional text to overlay on the image.
+        watermark_size (tuple[int, int]): The desired size for the watermark image.
+        watermark_position (tuple[int, int]): The position (x, y) where the watermark image will be placed.
+        text_position (tuple[str, str]): (vertical, horizontal) position: ("top"|"middle"|"center"|"bottom", "left"|"center"|"middle"|"right")
+        text_color (tuple[int, int, int, int]): The RGBA color for the overlay text.
+        text_font_path (str): Path to the TTF font file used for the overlay text.
+        text_font_size (int): Font size for the overlay text.
+        blend_alpha (float): The alpha value (0.0 to 1.0) for blending the watermark layer with the original image.
+        dpi (tuple[int, int]): DPI to use for output. If None, uses original image DPI if available.
+
+    Returns:
+        Image.Image: The watermarked image.
+    """
+    # Ensure original is RGBA
+    original = original_img.convert("RGBA")
+    width, height = original.size
+
+    # Set default positions if not provided
+    margin = 10
+    if watermark_position is None:
+        watermark_position = (width - watermark_size[0] - margin, height - watermark_size[1] - margin)
+
+    # Resize watermark image
+    watermark_resized = watermark_img.resize(watermark_size, Image.Resampling.LANCZOS)
+
+    # Create an empty transparent layer for watermark
+    watermark_layer = Image.new("RGBA", original.size, (0, 0, 0, 0))
+    # Paste the watermark image onto the watermark layer at the specified position
+    watermark_layer.paste(watermark_resized, watermark_position, watermark_resized)
+
+    # Draw overlay text if provided
+    if overlay_text:
+        draw = ImageDraw.Draw(watermark_layer)
+        try:
+            font = ImageFont.truetype(text_font_path, text_font_size)
+        except Exception as e:
+            print(f"Failed to load font {text_font_path}: {e}")
+            font = ImageFont.load_default()
+        # Calculate text size
+        text_bbox = draw.textbbox((0, 0), overlay_text, font=font)
+        text_width = text_bbox[2] - text_bbox[0]
+        text_height = text_bbox[3] - text_bbox[1]
+        # Determine text position based on (vertical, horizontal) keywords
+        vertical, horizontal = text_position
+        # Place text over the watermark image
+        wm_x, wm_y = watermark_position
+        wm_w, wm_h = watermark_size
+        # Default to center of watermark
+        x = wm_x + (wm_w - text_width) // 2
+        y = wm_y + (wm_h - text_height) // 2
+        if vertical == "top":
+            y = wm_y + margin
+        elif vertical in ("middle", "center"):
+            y = wm_y + (wm_h - text_height) // 2
+        elif vertical == "bottom":
+            y = wm_y + wm_h - text_height - margin
+        if horizontal == "left":
+            x = wm_x + margin
+        elif horizontal in ("middle", "center"):
+            x = wm_x + (wm_w - text_width) // 2
+        elif horizontal == "right":
+            x = wm_x + wm_w - text_width - margin
+        draw.text((x, y), overlay_text, fill=text_color, font=font)
+
+    # Blend the watermark layer over the original image using the specified alpha
+    watermarked = Image.blend(original, watermark_layer, alpha=blend_alpha)
+    # Preserve DPI if possible
+    if dpi is None:
+        dpi = original.info.get("dpi", (72, 72))
+    # Ensure output image has original size
+    watermarked = watermarked.resize((width, height), Image.Resampling.LANCZOS)
+    watermarked.info["dpi"] = dpi
+    return watermarked

utils/mazlib/README.md

@@ -0,0 +1,169 @@
+
+# Maze Maker
+
+Generate, solve, and render mazes in Python.
+
+## Features
+
+- Rectangular mazes (recursive or iterative DFS)
+- Triangular mazes
+- Hexagonal mazes (axial coordinates)
+- Shortest-path solving with BFS
+- Image rendering with Pillow
+- CLI and Python API support
+- Deterministic generation via --seed / seed parameter (non‑zero)
+
+## Installation
+
+Requirements:
+
+- Python 3.8+
+- Pillow>=9.0
+
+Install from source:
+
+```sh
+git clone https://github.com/Oncorporation/maze_maker.git
+cd maze_maker
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+Optional editable install:
+
+```sh
+pip install -e .
+```
+
+## Usage
+
+CLI:
+
+```sh
+python -m mazlib.cli --help
+python -m mazlib.cli -s rect -z 31x21 -c 20 -O out --show-solution
+```
+
+Python API:
+
+```python
+from mazlib.cli import run_maze
+
+# non-deterministic (seed=0 uses system randomness)
+maze, path = run_maze(shape="rect", size=(31, 21), cell=20, draw=True)
+
+# deterministic: pass a non-zero seed
+maze, path = run_maze(shape="rect", size=(31, 21), cell=20, draw=True, seed=42)
+```
+
+### `run_maze` parameters
+
+`run_maze(shape='rect', size=(30,20), cell=20, use_iterative=False, draw=True, output=None, show_solution=True, show_doors=False, seed=0)`
+
+- `shape` (`str`): maze shape.
+  - Canonical values: `rect`, `tri`, `hex`
+  - Also accepted by `run_maze`: `rectangle`, `grid`, `triangle`, `triangular`, `hexagon`, `hexagonal`
+- `size` (`tuple|int`):
+  - Rect/Tri: `(width, height)` or single `int` (square)
+  - Hex: `int` radius
+- `cell` (`int`): cell size in pixels (`cell_size` for hex drawing internally).
+- `use_iterative` (`bool`): use iterative generator variant.
+- `draw` (`bool`): when `True`, render maze image.
+- `output` (`str|None`): output image path. If `None`, no file is saved and the image is shown (when drawing).
+- `show_solution` (`bool`): when `True`, include the solved path overlay in rendering.
+- `show_doors` (`bool`): draw light outline guides/cell boundaries.
+- `seed` (`int`): optional random seed. Non-zero seeds produce deterministic mazes; `0` (default) uses system randomness.
+
+Return value:
+
+- `(maze, path)`
+  - `maze`: list of lists (rect) or dict (tri/hex)
+  - `path`: list of coordinates for the solution path
+
+Notes on determinism and seeding
+
+- Passing a non-zero `seed` to `run_maze` or the individual generators (`generate_maze`,
+  `generate_maze_iterative`, `generate_hex_maze_iterative`, `generate_tri_maze`, etc.)
+  uses a private Random instance seeded with that value. That makes generation deterministic
+  and repeatable across runs when the same seed is used.
+
+### Valid shapes in CLI vs API
+
+- CLI `--shape` accepted values: `rect`, `tri`, `hex`
+- Python `run_maze(shape=...)` accepts the aliases listed above
+
+### Image file naming with `mazlib.cli`
+
+`run_maze` supports two output modes from the CLI:
+
+- `-o/--output`: use an exact filename you provide.
+- `-O/--out-dir`: auto-generate a filename in the given directory.
+
+Auto-generated filename patterns (when using `-O`):
+
+- Rectangular: `maze_rect_<width>x<height>_<YYYYMMDD_HHMMSS>.png`
+- Triangular: `maze_tri_<width>x<height>_<YYYYMMDD_HHMMSS>.png`
+- Hexagonal: `maze_hex_r<radius>_<YYYYMMDD_HHMMSS>.png`
+
+When a non-zero `--seed` is provided to the CLI, the seed is appended to the
+auto-generated filename as `_s<seed>` (for example `maze_rect_31x21_20230101_123000_s42.png`) so
+deterministic outputs are easy to correlate with their seed.
+
+Examples:
+
+```sh
+# Explicit filename
+python -m mazlib.cli -s rect -z 31x21 -o my_custom_maze.png
+
+# Auto-generated filename in ./out with deterministic seed appended
+python -m mazlib.cli -s rect -z 31x21 -O out --seed 42
+```
+
+### Drawing customization and colors
+
+The CLI exposes options to control drawing appearance and colors. Use `--show-doors` to draw thin outlines for cell/hex/triangle doors. You can override individual colors with these flags:
+
+- `--color-wall` (default: `black`)
+- `--color-floor` (default: `white`)
+- `--color-start` (default: `green`)
+- `--color-door` (default: `#B0B0B0`)
+- `--color-path` (default: `red`)
+
+Example (custom colors):
+
+```sh
+python -m mazlib.cli -s rect -z 31x21 -O out --show-doors --color-wall navy --color-start lime --color-path orange
+```
+
+Programmatic API users can pass a color_dict to `run_maze` or to the draw functions:
+
+```python
+colors = {'wall':'navy', 'floor':'#f8f8f8', 'start':'lime', 'door':'#cccccc', 'path':'orange'}
+maze, path = run_maze(shape='rect', size=(31,21), draw=True, seed=42, color_dict=colors)
+```
+
+### Drawing notes
+
+- The triangular maze drawing now reliably marks the starting triangle in green
+  (same visual cue used by rectangular and hex drawing functions).
+
+## Git Submodule (quick reference)
+
+Add:
+
+```sh
+git submodule add https://github.com/Oncorporation/maze_maker.git submodules/maze_maker
+```
+
+Clone with submodules:
+
+```sh
+git clone --recurse-submodules <parent-repo-url>
+```
+
+Update after clone:
+
+```sh
+git submodule update --init --recursive
+```
+

utils/mazlib/__init__.py

@@ -0,0 +1,34 @@
+"""Public API for mazlib package.
+
+Re-exports generators, solvers and drawing helpers for rectangular and hex
+mazes. This package is a lightweight refactor of the original top-level
+maz.py to make the code easier to test and reuse.
+"""
+from .grid import (
+    generate_maze,
+    generate_maze_iterative,
+    solve_maze,
+)
+from .hex import (
+    generate_hex_maze,
+    generate_hex_maze_iterative,
+    solve_hex_maze,
+)
+from .draw import (
+    draw_maze,
+    draw_hex_maze,
+    draw_tri_maze,
+)
+from .tri import (
+    generate_tri_maze,
+    generate_tri_maze_iterative,
+    solve_tri_maze,    
+)
+from .cli import run_maze
+
+__all__ = [
+    'generate_maze', 'generate_maze_iterative', 'solve_maze',
+    'generate_hex_maze', 'generate_hex_maze_iterative', 'solve_hex_maze',
+    'draw_maze', 'draw_hex_maze', 'run_maze',
+    'generate_tri_maze', 'generate_tri_maze_iterative', 'solve_tri_maze', 'draw_tri_maze',
+]

utils/mazlib/cli.py

@@ -0,0 +1,231 @@
+from .grid import generate_maze, generate_maze_iterative, solve_maze
+from .hex import generate_hex_maze, generate_hex_maze_iterative, solve_hex_maze
+from .draw import draw_maze, draw_hex_maze, draw_tri_maze
+from .tri import generate_tri_maze, generate_tri_maze_iterative, solve_tri_maze
+import argparse
+import sys
+import logging
+import os
+import time
+from pathlib import Path
+
+
+def run_maze(shape='rect', size=(30,20), cell=20, use_iterative=False, draw=True, output=None, show_solution=True, show_doors=False, seed=0, color_dict={'wall':'black', 'floor':'white', 'start':'green', 'door':'#B0B0B0', 'path':'red'}):
+    """
+    Control function to generate, solve, and optionally draw a maze.
+
+    Args:
+        shape (str): 'rect' for rectangular grid mazes or 'hex' for hexagonal mazes.
+        size (tuple|int): For 'rect', a (width, height) tuple. For 'hex', an integer radius.
+        cell (int): Cell size in pixels for drawing (rect) or approximate hex size (hex).
+        use_iterative (bool): If True and shape is 'rect', use the iterative DFS generator.
+        draw (bool): If True, render the maze and path with PIL; otherwise only return data.
+        output (str|None): If provided, save the rendered image to this path; if None, show the image.
+        show_solution (bool): If True, overlay the solution path on the drawn maze.
+        show_doors (bool): If True, draw thin grey outlines around each cell to show doors.
+        seed (int): Random seed for maze generation (0 for random).
+        color_dict (dict): Optional dict to specify colors for 'wall', 'floor', 'start', 'door', and 'path' in drawing.
+
+    Returns:
+        tuple: (maze, path) where maze is either a 2D list (rect) or dict (hex), and
+               path is a list of coordinates in the corresponding coordinate system.
+    """
+    logging.debug('run_maze called: shape=%s size=%s cell=%s iterative=%s draw=%s output=%s show_solution=%s',
+                  shape, size, cell, use_iterative, draw, output, show_solution)
+    shape_key = (shape or 'rect').lower()
+    if shape_key in ('rect', 'rectangle', 'grid'):
+        # Normalize size into (w, h)
+        if isinstance(size, int):
+            w, h = size, size
+        else:
+            try:
+                w, h = int(size[0]), int(size[1])
+            except Exception:
+                raise ValueError("For rect shape, size must be an int or a (w,h) tuple")
+        if use_iterative:
+            maze = generate_maze_iterative(w, h, seed=seed)
+        else:
+            maze = generate_maze(w, h, seed=seed)
+        path = solve_maze(maze)
+        if draw:
+            draw_maze(maze, path if show_solution else [], cell=cell, save_path=output, show_doors=show_doors, color_dict=color_dict)
+        return maze, path
+
+    if shape_key in ('tri', 'triangle', 'triangular'):
+        # triangular grids are currently implemented as rectangular compatibility wrappers
+        if isinstance(size, int):
+            w, h = size, size
+        else:
+            try:
+                w, h = int(size[0]), int(size[1])
+            except Exception:
+                raise ValueError("For tri shape, size must be an int or a (w,h) tuple")
+        if use_iterative:
+            maze = generate_tri_maze_iterative(w, h, seed=seed)
+        else:
+            maze = generate_tri_maze(w, h, seed=seed)
+        path = solve_tri_maze(maze)
+        if draw:
+            draw_tri_maze(maze, path if show_solution else [], cell=cell, save_path=output, show_doors=show_doors, color_dict=color_dict)
+        return maze, path
+
+    if shape_key in ('hex', 'hexagon', 'hexagonal'):
+        try:
+            radius = int(size)
+        except Exception:
+            raise ValueError("For hex shape, size must be an integer radius")
+        # allow choosing iterative implementation explicitly
+        if use_iterative:
+            maze = generate_hex_maze_iterative(radius, seed=seed)
+        else:
+            maze = generate_hex_maze(radius, seed=seed)
+        path = solve_hex_maze(maze)
+        if draw:
+            draw_hex_maze(maze, path if show_solution else [], cell_size=cell, save_path=output, show_doors=show_doors, color_dict=color_dict)
+        return maze, path
+
+    raise ValueError(f"Unknown shape: {shape}")
+
+
+def _parse_size_arg(shape, size_str):
+    """Parse the --size CLI argument into the appropriate value for run_maze.
+
+    For rectangular mazes accept either an integer (square) or WIDTHxHEIGHT.
+    For hex mazes accept a single integer radius.
+    """
+    if shape in ('rect', 'rectangle', 'grid', 'tri', 'triangle', 'triangular'):
+        if isinstance(size_str, (list, tuple)):
+            return int(size_str[0]), int(size_str[1])
+        s = str(size_str)
+        if 'x' in s.lower():
+            parts = s.lower().split('x')
+            if len(parts) != 2:
+                raise ValueError("Invalid rect size format, expected WIDTHxHEIGHT")
+            return int(parts[0]), int(parts[1])
+        return int(s)
+    # hex
+    return int(size_str)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='run_maze', description='Generate/solve/draw mazes')
+    parser.add_argument('-s', '--shape', choices=['rect', 'hex', 'tri'], default='rect', help='Maze shape')
+    parser.add_argument('-z', '--size', default='30x20', help='Size: for rect WIDTHxHEIGHT or N; for hex radius')
+    parser.add_argument('-c', '--cell', type=int, default=20, help='Cell size in pixels')
+    parser.add_argument('-i', '--iterative', action='store_true', help='Use iterative generator')
+    parser.add_argument('--no-draw', dest='draw', action='store_false', help="Don't render the maze")
+    group = parser.add_mutually_exclusive_group()
+    group.add_argument('-o', '--output', default=None, help='Path to save rendered image (if omitted, image will be shown)')
+    group.add_argument('-O', '--out-dir', default=None, help='Directory to save rendered image(s); filename auto-generated')
+    parser.add_argument('-v', '--verbose', action='count', default=0, help='Increase verbosity (use -v or -vv)')
+    parser.add_argument('--show-solution', action='store_true', default=False,
+                        help='Print path length and endpoints after solving')
+    parser.add_argument('--seed', type=int, default=0, help='Random seed (0 for random)')
+    parser.add_argument('--show-doors', action='store_true', default=False, help='Draw thin grey outlines for doors')
+    parser.add_argument('--color-wall', default='black', help='Color for walls in drawing')
+    parser.add_argument('--color-floor', default='white', help='Color for floors in drawing')
+    parser.add_argument('--color-start', default='green', help='Color for start cell in drawing')
+    parser.add_argument('--color-door', default='#B0B0B0', help='Color for doors in drawing')
+    parser.add_argument('--color-path', default='red', help='Color for solution path in drawing')
+    args = parser.parse_args(argv)
+
+    # configure logging according to verbosity
+    if args.verbose >= 2:
+        level = logging.DEBUG
+    elif args.verbose == 1:
+        level = logging.INFO
+    else:
+        level = logging.WARNING
+    logging.basicConfig(level=level, format='%(levelname)s: %(message)s')
+
+    try:
+        size = _parse_size_arg(args.shape, args.size)
+    except Exception as e:
+        parser.error(str(e))
+
+    # Ensure rectangular mazes have odd dimensions to allow a valid path
+    if args.shape in ('rect', 'rectangle', 'grid', 'tri', 'triangle', 'triangular'):
+        if isinstance(size, (list, tuple)):
+            w, h = int(size[0]), int(size[1])
+            changed = False
+            if w % 2 == 0:
+                w += 1
+                changed = True
+            if h % 2 == 0:
+                h += 1
+                changed = True
+            if changed:
+                logging.info("Adjusted rectangular size to odd dimensions: %dx%d", w, h)
+            size = (w, h)
+        else:
+            s = int(size)
+            if s % 2 == 0:
+                s += 1
+                logging.info("Adjusted rectangular size to odd dimension: %d", s)
+            size = s
+
+    # determine output path: explicit output > out_dir auto-generated > None
+    output_path = None
+    if args.output:
+        output_path = args.output
+    elif args.out_dir:
+        outdir = Path(args.out_dir)
+        try:
+            outdir.mkdir(parents=True, exist_ok=True)
+        except Exception as e:
+            parser.error(f"Failed to create out-dir '{args.out_dir}': {e}")
+        ts = time.strftime('%Y%m%d_%H%M%S')
+        shape_key = args.shape.lower()
+        if shape_key in ('rect', 'rectangle', 'grid', 'tri', 'triangle', 'triangular'):
+            if isinstance(size, tuple):
+                w, h = size
+                if shape_key in ('tri', 'triangle', 'triangular'):
+                    fname = f"maze_tri_{w}x{h}_{ts}.png"
+                else:
+                    fname = f"maze_rect_{w}x{h}_{ts}.png"
+            else:
+                s = int(size)
+                if shape_key in ('tri', 'triangle', 'triangular'):
+                    fname = f"maze_tri_{s}x{s}_{ts}.png"
+                else:
+                    fname = f"maze_rect_{s}x{s}_{ts}.png"
+        else:
+            # hex
+            radius = int(size)
+            fname = f"maze_hex_r{radius}_{ts}.png"
+        # append seed to filename when a non-zero seed is provided
+        if args.seed:
+            name, ext = os.path.splitext(fname)
+            fname = f"{name}_s{args.seed}{ext}"
+        output_path = str(outdir / fname)
+        logging.info("Auto-generated output path: %s", output_path)
+
+    color_dict = {
+        'wall': args.color_wall,
+        'floor': args.color_floor,
+        'start': args.color_start,
+        'door': args.color_door,
+        'path': args.color_path
+    }
+
+    maze, path = run_maze(shape=args.shape, size=size, cell=args.cell, use_iterative=args.iterative, draw=args.draw, output=output_path, show_solution=args.show_solution, seed=args.seed, color_dict=color_dict)
+
+    if args.show_solution:
+        if not path:
+            print("No solution path found.")
+        else:
+            try:
+                start = path[0]
+                end = path[-1]
+                print(f"Path length: {len(path)}")
+                print(f"Start: {start}")
+                print(f"End:   {end}")
+            except Exception:
+                # Fallback: print minimal info
+                print(f"Path length: {len(path)}; start/end unavailable")
+
+    return maze, path
+
+
+if __name__ == '__main__':
+    main()

utils/mazlib/draw.py

@@ -0,0 +1,255 @@
+import math
+import logging
+from PIL import Image, ImageDraw
+
+
+def draw_maze(maze, path, cell=20, save_path=None, show_doors=False, color_dict={'wall':'black', 'floor':'white', 'start':'green', 'door':'#B0B0B0', 'path':'red'}):
+    """
+    Draw the maze and an optional path using PIL.
+
+    Args:
+        maze (list[list[int]]): 2D grid with 1 for walls and 0 for open cells.
+        path (list[tuple[int,int]]): sequence of (x, y) coordinates forming a path through the maze.
+        cell (int): pixel size of one maze cell when rendering. Default is 20.
+        save_path (str|None): if given, save the rendered image to this file path; if None, show the image instead.
+        show_doors (bool): if True, draw thin grey outlines around each cell to indicate doors.
+        color_dict (dict): optional dict to specify colors for 'wall', 'floor', 'start', 'door', and 'path'.
+    """
+    h,w = len(maze),len(maze[0])
+    img = Image.new('RGB', (w*cell,h*cell), color_dict.get('floor', 'white'))
+    draw = ImageDraw.Draw(img)
+
+    # fill start cell (0,0) with green floor
+    draw.rectangle([0, 0, cell, cell], fill=color_dict.get('start', 'green'))
+    # Optional thin grey outlines for each cell (like hex show_doors)
+    if show_doors:
+        for y in range(h):
+            for x in range(w):
+                draw.rectangle(
+                    [x * cell, y * cell, (x + 1) * cell, (y + 1) * cell],
+                    outline=color_dict.get('door', '#B0B0B0'),
+                    width=1
+                )
+
+    # Draw solid walls
+    for y in range(h):
+        for x in range(w):
+            if maze[y][x]:
+                draw.rectangle([x*cell,y*cell,(x+1)*cell,(y+1)*cell], fill=color_dict.get('wall', 'black'))
+
+    # Draw 2px exterior border, leaving an opening at the exit cell (w-1, h-1)
+    img_w, img_h = w * cell, h * cell
+    border_width = 4
+    draw.rectangle([0, 0, img_w - 1, img_h - 1], outline=color_dict.get('wall', 'black'), width=border_width)
+    ex0, ey0 = (w - 1) * cell, (h - 1) * cell
+    draw.line([(img_w - 1, ey0), (img_w - 1, ey0 + cell)], fill=color_dict.get('door', '#B0B0B0'), width=border_width + 2)
+    draw.line([(ex0, img_h - 1), (ex0 + cell, img_h - 1)], fill=color_dict.get('door', '#B0B0B0'), width=border_width + 2)
+
+    if path:
+        for i in range(len(path)-1):
+            x1,y1 = path[i]; x2,y2 = path[i+1]
+            draw.line([(x1*cell+cell//2,y1*cell+cell//2),(x2*cell+cell//2,y2*cell+cell//2)], fill=color_dict.get('path', 'red'), width=3)
+    if save_path:
+        try:
+            img.save(save_path)
+            logging.info("Saved rectangular maze image to %s", save_path)
+        except Exception:
+            logging.exception("Failed to save image to %s", save_path)
+    return img
+
+
+def draw_hex_maze(maze, path, cell_size=45, rotation_degrees=0, save_path=None, show_doors=False, color_dict={'wall':'black', 'floor':'white', 'start':'green', 'door':'#B0B0B0', 'path':'red'}):
+    """
+    Draw a hex maze (walls only where no passage) and optional path using PIL.
+
+    Args:
+        maze (dict): mapping (q, r) -> list of (dq, dr) neighbor offsets.
+        path (list[tuple[int,int]]): sequence of axial coordinates to draw as red line.
+        cell_size (int): approximate pixel size of a hex cell.
+        save_path (str|None): if given, save image to file instead of showing.
+        rotation_degrees (float): rotation of hexagons in degrees (default 0 = flat-topped).
+        save_path (str|None): if provided, save the rendered image to this path; if None, show the image.
+        show_doors (bool): if True, draw thin grey outlines around each hex to show doors.
+        color_dict (dict): optional dict to specify colors for 'wall', 'floor', 'start', and 'door'.
+    """
+    rot = math.radians(rotation_degrees)
+    if not maze: return
+    r_max = max((max(abs(q),abs(r)) for q,r in maze), default=5)
+    w = int(3*(r_max+2)*cell_size)
+    h = int(math.sqrt(3)*2*(r_max+2)*cell_size)
+    img = Image.new('RGB', (w,h), color_dict.get('floor', 'white'))
+    d = ImageDraw.Draw(img)
+    dirs = [(1,0),(0,1),(-1,1),(-1,0),(0,-1),(1,-1)]
+
+    if show_doors:
+        for q,r in maze:  # light grey outlines
+            cx = cell_size*1.5*q + w//2
+            cy = cell_size*math.sqrt(3)*(r + q/2) + h//2
+            pts = [(cx + cell_size*math.cos(rot + i*math.pi/3),
+                    cy + cell_size*math.sin(rot + i*math.pi/3)) for i in range(6)]
+            d.polygon(pts, outline=color_dict.get('door', '#B0B0B0'), width=2)
+    # fill start hex (0,0) with green floor so the starting cell is visibly marked
+    if (0, 0) in maze:
+        cx = w//2
+        cy = h//2
+        start_pts = [(cx + cell_size*math.cos(rot + i*math.pi/3),
+                      cy + cell_size*math.sin(rot + i*math.pi/3)) for i in range(6)]
+        d.polygon(start_pts, fill=color_dict.get('start', 'green'))
+
+    for q,r in maze:  # black blocked walls
+        cx = cell_size*1.5*q + w//2
+        cy = cell_size*math.sqrt(3)*(r + q/2) + h//2
+        for i,(dq,dr) in enumerate(dirs):
+            if (dq,dr) not in maze.get((q,r),[]):
+                a = rot + i*math.pi/3
+                x1 = cx + cell_size*math.cos(a)
+                y1 = cy + cell_size*math.sin(a)
+                x2 = cx + cell_size*math.cos(a+math.pi/3)
+                y2 = cy + cell_size*math.sin(a+math.pi/3)
+                d.line([(x1,y1),(x2,y2)], fill=color_dict.get('wall', 'black'), width=6)
+
+    # force clear exit to outside on end cell (outer side with no neighbor)
+    end = max(maze, key=lambda p: abs(p[0])+abs(p[1])+abs(p[0]+p[1]))
+    cx = cell_size*1.5*end[0] + w//2
+    cy = cell_size*math.sqrt(3)*(end[1] + end[0]/2) + h//2
+    for i,(dq,dr) in enumerate(dirs):
+        neigh = (end[0]+dq, end[1]+dr)
+        if neigh not in maze:  # outer side
+            a = rot + i*math.pi/3
+            x1 = cx + cell_size*math.cos(a)
+            y1 = cy + cell_size*math.sin(a)
+            x2 = cx + cell_size*math.cos(a+math.pi/3)
+            y2 = cy + cell_size*math.sin(a+math.pi/3)
+            d.line([(x1,y1),(x2,y2)], fill=color_dict.get('floor', 'white'), width=26)
+            break
+
+    if path:
+        pts = [(cell_size*1.5*q + w//2, cell_size*math.sqrt(3)*(r + q/2) + h//2) for q,r in path]
+        d.line(pts, fill=color_dict.get('path', 'red'), width=7)
+
+    if save_path:
+        try:
+            img.save(save_path)
+            logging.info("Saved hex maze image to %s", save_path)
+        except Exception:
+            logging.exception("Failed to save image to %s", save_path)
+    return img
+
+
+def draw_tri_maze(maze, path, cell=40, save_path=None, show_doors=False, color_dict={'wall':'black', 'floor':'white', 'start':'green', 'door':'#B0B0B0', 'path':'red'}):
+    """
+    Draw a triangular-grid maze using PIL.
+
+    Maze format expected:
+        maze (dict): mapping (x, y) -> list of (dx, dy) neighbor offsets that are open.
+    Each cell is an equilateral triangle. Coordinates are grid indices (x:col, y:row).
+
+    Args:
+        maze (dict): triangle adjacency mapping.
+        path (list[tuple[int,int]]): list of (x,y) cells forming a path.
+        cell (int): side length of each triangle in pixels.
+        save_path (str|None): save to file if provided, otherwise show.
+        show_doors (bool): if True draw thin grey outlines around each triangle.
+        color_dict (dict): optional dict to specify colors for 'wall', 'floor', 'start', 'door', and 'path'.
+    """
+    if not maze:
+        return
+    # determine bounds
+    xs = [p[0] for p in maze]
+    ys = [p[1] for p in maze]
+    min_x, max_x = min(xs), max(xs)
+    min_y, max_y = min(ys), max(ys)
+    w = max_x - min_x + 1
+    h = max_y - min_y + 1
+
+    side = cell
+    h_tri = side * math.sqrt(3) / 2.0
+    offset_x = side  # margin
+    offset_y = side
+
+    img_w = int(offset_x*2 + (w-1) * (side/2.0) + side + 0.5)
+    img_h = int(offset_y*2 + h * h_tri + 0.5)
+    img = Image.new('RGB', (img_w, img_h), color_dict.get('floor', 'white'))
+    d = ImageDraw.Draw(img)
+
+    def cell_vertices(x,y):
+        cx = offset_x + (x - min_x) * (side/2.0)
+        cy = offset_y + (y - min_y) * h_tri
+        up = ((x + y) % 2 == 0)
+        if up:
+            v0 = (cx, cy)
+            v1 = (cx - side/2.0, cy + h_tri)
+            v2 = (cx + side/2.0, cy + h_tri)
+        else:
+            v0 = (cx, cy + h_tri)
+            v1 = (cx - side/2.0, cy)
+            v2 = (cx + side/2.0, cy)
+        return up, v0, v1, v2
+
+    # fill start triangle (0,0) with green floor so the starting cell is visibly marked
+    if (0, 0) in maze:
+        _, v0_0, v1_0, v2_0 = cell_vertices(0, 0)
+        d.polygon([v0_0, v1_0, v2_0], fill=color_dict.get('start', 'green'))
+
+    # optional thin grey outlines for each triangle
+    if show_doors:
+        for (x,y) in maze:
+            up, v0, v1, v2 = cell_vertices(x,y)
+            pts = [v0, v1, v2]
+            d.polygon(pts, outline=color_dict.get('door', '#B0B0B0'), width=1)
+
+    # draw black walls where no passage
+    for (x,y) in maze:
+        up, v0, v1, v2 = cell_vertices(x,y)
+        # map direction offsets to edge vertex pairs
+        if up:
+            edge_map = {
+                (-1,0): (v0, v1),  # left
+                (1,0): (v0, v2),   # right
+                (0,1): (v1, v2),   # down/base
+            }
+        else:
+            edge_map = {
+                (-1,0): (v1, v0),  # left
+                (1,0): (v2, v0),   # right
+                (0,-1): (v1, v2),  # up/base
+            }
+        for off,verts in edge_map.items():
+            if off not in maze.get((x,y), []):
+                d.line([verts[0], verts[1]], fill=color_dict.get('wall', 'black'), width=6)
+
+    # force clear exit on end cell (outer side with no neighbor)
+    # choose end as max by x+y
+    end = max(maze, key=lambda p: p[0] + p[1])
+    ex, ey = end
+    up, v0, v1, v2 = cell_vertices(ex, ey)
+    if up:
+        dir_order = [(-1,0),(1,0),(0,1)]
+        edge_order = [(v0,v1),(v0,v2),(v1,v2)]
+    else:
+        dir_order = [(-1,0),(1,0),(0,-1)]
+        edge_order = [(v1,v0),(v2,v0),(v1,v2)]
+    for off,edge in zip(dir_order, edge_order):
+        neigh = (ex + off[0], ey + off[1])
+        if neigh not in maze:
+            d.line([edge[0], edge[1]], fill=color_dict.get('floor', 'white'), width=26)
+            break
+
+    # draw path if provided (connect centroids)
+    if path:
+        pts = []
+        for x,y in path:
+            up, v0, v1, v2 = cell_vertices(x,y)
+            # centroid average of vertices
+            cx = (v0[0] + v1[0] + v2[0]) / 3.0
+            cy = (v0[1] + v1[1] + v2[1]) / 3.0
+            pts.append((cx, cy))
+        d.line(pts, fill=color_dict.get('path', 'red'), width=7)
+
+    if save_path:
+        try:
+            img.save(save_path)
+            logging.info("Saved triangular maze image to %s", save_path)
+        except Exception:
+            logging.exception("Failed to save tri image to %s", save_path)
+    return img

utils/mazlib/grid.py

@@ -0,0 +1,139 @@
+import random
+from collections import deque
+
+
+def generate_maze(w, h, seed=0):
+    """
+    Generate a randomized perfect maze using depth-first search.
+
+    Args:
+        w (int): width of the maze in cells (number of columns).
+        h (int): height of the maze in cells (number of rows).
+
+    Returns:
+        list[list[int]]: 2D grid representing the maze where 1 indicates a wall
+        and 0 indicates an open cell. The start is at (0,0) and the goal is at (w-1,h-1).
+    """
+    maze = [[1]*w for _ in range(h)]
+    rng = random.Random(seed) if seed else None
+
+    def dfs(x, y):
+        maze[y][x] = 0
+        dirs = [(0,2),(2,0),(0,-2),(-2,0)]
+        (rng.shuffle(dirs) if rng is not None else random.shuffle(dirs))
+        for dx,dy in dirs:
+            nx,ny = x+dx,y+dy
+            if 0<=nx<w and 0<=ny<h and maze[ny][nx]:
+                maze[y+dy//2][x+dx//2] = 0
+                dfs(nx,ny)
+                # occasional extra random connection (10%) to introduce loops and increase difficulty
+                if (rng.random() if rng is not None else random.random()) < 0.1:
+                    extra_dirs = [d for d in dirs if d != (dx,dy)]
+                    (rng.shuffle(extra_dirs) if rng is not None else random.shuffle(extra_dirs))
+                    for edx, edy in extra_dirs:
+                        enx, eny = x+edx, y+edy
+                        # ensure within bounds and target already open
+                        if 0<=enx<w and 0<=eny<h and maze[eny][enx]==0:
+                            # open the wall between (x,y) and (enx,eny) if it's closed
+                            wx, wy = x+edx//2, y+edy//2
+                            if maze[wy][wx]:
+                                maze[wy][wx] = 0
+                            break
+
+    dfs(0,0)
+    maze[0][0] = maze[h-1][w-1] = 0
+    # ensure starting cell has one extra open neighbour if possible (not an external wall)
+    dirs = [(0,2),(2,0),(0,-2),(-2,0)]
+    random.shuffle(dirs)
+    for dx,dy in dirs:
+        nx,ny = dx,dy
+        if 0<=nx<w and 0<=ny<h and maze[ny][nx]==1:
+            # open the intermediate wall and the target cell
+            maze[dy//2][dx//2] = 0
+            maze[ny][nx] = 0
+            break
+    return maze
+
+
+def generate_maze_iterative(w, h, seed=0):
+    """
+    Generate a randomized perfect maze using an explicit stack (iterative DFS).
+
+    Args:
+        w (int): width of the maze in cells (number of columns).
+        h (int): height of the maze in cells (number of rows).
+
+    Returns:
+        list[list[int]]: 2D grid representing the maze where 1 indicates a wall
+        and 0 indicates an open cell.
+    """
+    maze = [[1]*w for _ in range(h)]
+    rng = random.Random(seed) if seed else None
+    stack = [(0, 0)]
+    maze[0][0] = 0
+    dirs = [(0,2),(2,0),(0,-2),(-2,0)]
+    while stack:
+        x,y = stack[-1]
+        (rng.shuffle(dirs) if rng is not None else random.shuffle(dirs))
+        for dx,dy in dirs:
+            nx,ny = x+dx,y+dy
+            if 0<=nx<w and 0<=ny<h and maze[ny][nx]:
+                maze[y+dy//2][x+dx//2] = 0
+                maze[ny][nx] = 0
+                stack.append((nx,ny))
+                # occasional extra random connection (10%) to introduce loops and increase difficulty
+                if (rng.random() if rng is not None else random.random()) < 0.1:
+                    extra_dirs = [d for d in dirs if d != (dx,dy)]
+                    (rng.shuffle(extra_dirs) if rng is not None else random.shuffle(extra_dirs))
+                    for edx, edy in extra_dirs:
+                        enx, eny = x+edx, y+edy
+                        if 0<=enx<w and 0<=eny<h and maze[eny][enx]==0:
+                            wx, wy = x+edx//2, y+edy//2
+                            if maze[wy][wx]:
+                                maze[wy][wx] = 0
+                            break
+                break
+        else:
+            stack.pop()
+    maze[0][0] = maze[h-1][w-1] = 0
+    # ensure starting cell has one extra open neighbour if possible (not an external wall)
+    dirs = [(0,2),(2,0),(0,-2),(-2,0)]
+    (rng.shuffle(dirs) if rng is not None else random.shuffle(dirs))
+    for dx,dy in dirs:
+        nx,ny = 0+dx, 0+dy
+        if 0<=nx<w and 0<=ny<h and maze[ny][nx]==1:
+            # open the intermediate wall and the target cell
+            maze[dy//2][dx//2] = 0
+            maze[ny][nx] = 0
+            break
+    return maze
+
+
+def solve_maze(maze):
+    """
+    Solve a maze grid using breadth-first search to produce the shortest path.
+
+    Args:
+        maze (list[list[int]]): 2D grid where 1 indicates a wall and 0 indicates open space.
+
+    Returns:
+        list[tuple[int,int]]: list of (x, y) coordinates from start (0,0) to goal (w-1,h-1).
+    """
+    h,w = len(maze),len(maze[0])
+    q = deque([(0,0)])
+    parent = {(0,0):None}
+    while q:
+        x,y = q.popleft()
+        if (x,y)==(w-1,h-1):
+            break
+        for dx,dy in [(0,1),(1,0),(0,-1),(-1,0)]:
+            nx,ny = x+dx,y+dy
+            if 0<=nx<w and 0<=ny<h and maze[ny][nx]==0 and (nx,ny) not in parent:
+                parent[(nx,ny)] = (x,y)
+                q.append((nx,ny))
+    path = []
+    at = (w-1,h-1)
+    while at:
+        path.append(at)
+        at = parent.get(at)
+    return path[::-1]

utils/mazlib/hex.py

@@ -0,0 +1,104 @@
+import random
+from collections import deque
+
+
+def generate_hex_maze(radius, seed=0):
+    """Backwards-compatible wrapper that uses the iterative implementation."""
+    return generate_hex_maze_iterative(radius, seed=seed)
+
+
+def generate_hex_maze_iterative(radius, seed=0):
+    """
+    Generate a hexagonal maze using an explicit stack (iterative DFS) on axial coords.
+
+    Args:
+        radius (int): maximum radius (in hex steps) from the origin to include.
+
+    Returns:
+        dict: mapping (q, r) -> list of (dq, dr) neighbor offsets for open edges.
+    """
+    maze = {}
+    visited = set()
+    stack = [(0, 0)]
+    visited.add((0, 0))
+    dirs = [(1,0),(0,1),(-1,1),(-1,0),(0,-1),(1,-1)]
+    rng = random.Random(seed) if seed else None
+    while stack:
+        q,r = stack[-1]
+        directions = dirs[:]                    # ← fixed: copy before shuffle
+        (rng.shuffle(directions) if rng is not None else random.shuffle(directions))
+        moved = False
+        for dq,dr in directions:
+            nq,nr = q+dq,r+dr
+            if (nq,nr) not in visited and max(abs(nq),abs(nr),abs(nq+nr)) <= radius:
+                visited.add((nq,nr))
+                stack.append((nq,nr))
+                maze.setdefault((q,r),[]).append((dq,dr))
+                maze.setdefault((nq,nr),[]).append((-dq,-dr))
+                # occasional extra random connection (10%) to introduce loops and increase difficulty
+                if (rng.random() if rng is not None else random.random()) < 0.1:
+                    # prefer connecting to an already visited neighbor so we create a loop
+                    extra_dirs = [d for d in dirs if d != (dq,dr)]
+                    (rng.shuffle(extra_dirs) if rng is not None else random.shuffle(extra_dirs))
+                    for edq,edr in extra_dirs:
+                        enq,enr = q+edq, r+edr
+                        # only connect to already visited neighbours to avoid creating isolated cells
+                        if (enq,enr) in visited and (edq,edr) not in maze.get((q,r), []):
+                            maze.setdefault((q,r),[]).append((edq,edr))
+                            maze.setdefault((enq,enr),[]).append((-edq,-edr))
+                            break
+                moved = True
+                break
+        if not moved:
+            stack.pop()
+    # Ensure the starting hex has two additional neighbor offsets if possible.
+    # This makes the maze entry/exit from the center more open and increases difficulty.
+    # (If there are not enough valid neighbours within the radius, add as many as possible.)
+    if (0, 0) not in maze:
+        maze.setdefault((0, 0), [])
+    # choose up to two directions not already open from the start
+    available = [d for d in dirs if d not in maze.get((0, 0), []) and max(abs(d[0]), abs(d[1]), abs(d[0] + d[1])) <= radius]
+    (rng.shuffle(available) if rng is not None else random.shuffle(available))
+    for dq, dr in available[:2]:
+        nq, nr = dq, dr
+        # add reciprocal entries even if the neighbour wasn't previously in the maze
+        if (dq, dr) not in maze.get((0, 0), []):
+            maze.setdefault((0, 0), []).append((dq, dr))
+            maze.setdefault((nq, nr), []).append((-dq, -dr))
+
+    return maze
+
+
+def solve_hex_maze(maze):
+    """
+    Solve a hex maze (produced by generate_hex_maze) using breadth-first search.
+
+    Args:
+        maze (dict): mapping (q, r) -> list of (dq, dr) neighbor offsets.
+
+    Returns:
+        list[tuple[int,int]]: sequence of axial coordinates from the origin to the
+        farthest cell (heuristic goal) in the generated maze. Returns empty list
+        for an empty maze.
+    """
+    if not maze:
+        return []
+    start = (0,0)
+    end = max(maze, key=lambda p: abs(p[0])+abs(p[1])+abs(p[0]+p[1]))
+    queue = deque([start])
+    parent = {start: None}
+    while queue:
+        curr = queue.popleft()
+        if curr == end:
+            break
+        for dq,dr in maze.get(curr,[]):
+            neigh = (curr[0]+dq, curr[1]+dr)
+            if neigh not in parent:
+                parent[neigh] = curr
+                queue.append(neigh)
+    path = []
+    at = end
+    while at:
+        path.append(at)
+        at = parent.get(at)
+    return path[::-1]

utils/mazlib/requirements.txt

@@ -0,0 +1 @@
+Pillow>=9.0

utils/mazlib/tri.py

@@ -0,0 +1,138 @@
+"""Triangle-grid maze helpers.
+
+This module implements a simple triangular-grid maze generator (randomized
+depth-first search), a BFS solver and a drawing helper that renders the
+triangular tiling with walls and optional thin grey outlines for doors.
+
+Maze representation:
+    dict mapping (x,y) -> list of (dx,dy) neighbor offsets that are open.
+
+Coordinates:
+    x: column index, 0..w-1
+    y: row index, 0..h-1
+
+Triangle orientation alternates with parity: up when (x+y) % 2 == 0,
+otherwise down.
+"""
+import random
+from collections import deque
+from .draw import draw_tri_maze as _draw_tri
+
+
+def _neighbor_offsets(x, y, w, h):
+    """Return valid neighbor offsets for triangle at (x,y) based on orientation."""
+    up = ((x + y) % 2 == 0)
+    if up:
+        candidates = [(-1, 0), (1, 0), (0, 1)]
+    else:
+        candidates = [(-1, 0), (1, 0), (0, -1)]
+    valid = []
+    for dx, dy in candidates:
+        nx, ny = x + dx, y + dy
+        if 0 <= nx < w and 0 <= ny < h:
+            valid.append((dx, dy))
+    return valid
+
+
+def generate_tri_maze(w, h=None, seed=0):
+    """Generate a triangular maze using randomized DFS.
+
+    Args:
+        w (int): number of columns.
+        h (int|None): number of rows (if None, equals w).
+
+    Returns:
+        dict: mapping (x,y) -> list of neighbor offsets (dx,dy) that are open.
+    """
+    if h is None:
+        h = w
+    # initialize empty adjacency
+    maze = {(x, y): [] for x in range(w) for y in range(h)}
+    rng = random.Random(seed) if seed else None
+    visited = set()
+
+    stack = [(0, 0)]
+    visited.add((0, 0))
+
+    while stack:
+        x, y = stack[-1]
+        offs = _neighbor_offsets(x, y, w, h)
+        # filter to unvisited neighbours
+        nbrs = [(dx, dy) for dx, dy in offs if (x + dx, y + dy) not in visited]
+        if nbrs:
+            dx, dy = (rng.choice(nbrs) if rng is not None else random.choice(nbrs))
+            nx, ny = x + dx, y + dy
+            # carve passage both ways (store offsets)
+            maze[(x, y)].append((dx, dy))
+            maze[(nx, ny)].append((-dx, -dy))
+            visited.add((nx, ny))
+            stack.append((nx, ny))
+            # occasional extra random connection (10%) to introduce loops and increase difficulty
+            if (rng.random() if rng is not None else random.random()) < 0.1:
+                extra_offs = [o for o in offs if o != (dx, dy)]
+                (rng.shuffle(extra_offs) if rng is not None else random.shuffle(extra_offs))
+                for edx, edy in extra_offs:
+                    enx, eny = x + edx, y + edy
+                    # connect only to already visited neighbours to avoid isolating cells
+                    if (enx, eny) in visited and (edx, edy) not in maze.get((x, y), []):
+                        maze[(x, y)].append((edx, edy))
+                        maze[(enx, eny)].append((-edx, -edy))
+                        break
+        else:
+            stack.pop()
+    # ensure the starting triangle (0,0) has one additional neighbour offset if possible
+    start_offs = _neighbor_offsets(0, 0, w, h)
+    candidates = [o for o in start_offs if o not in maze.get((0, 0), [])]
+    if candidates:
+        edx, edy = (rng.choice(candidates) if rng is not None else random.choice(candidates))
+        nx, ny = 0 + edx, 0 + edy
+        if (edx, edy) not in maze.get((0, 0), []):
+            maze[(0, 0)].append((edx, edy))
+            maze[(nx, ny)].append((-edx, -edy))
+
+    return maze
+
+
+def generate_tri_maze_iterative(w, h=None, seed=0):
+    """Alias for generate_tri_maze; generation is already iterative.
+
+    Kept for API symmetry with other generators.
+    """
+    return generate_tri_maze(w, h, seed=seed)
+
+
+def solve_tri_maze(maze):
+    """Solve a triangular maze returning a path from start to end.
+
+    Start is assumed at (0,0). End is chosen as the cell with the maximum
+    x+y (bottom-right-like) so it aligns with the drawing and CLI examples.
+
+    Returns:
+        list[(x,y)]: path from start to end (inclusive) or empty list if none.
+    """
+    if not maze:
+        return []
+    start = (0, 0)
+    end = max(maze, key=lambda p: p[0] + p[1])
+
+    q = deque([start])
+    parent = {start: None}
+    while q:
+        cur = q.popleft()
+        if cur == end:
+            break
+        x, y = cur
+        for dx, dy in maze.get((x, y), []):
+            nx, ny = x + dx, y + dy
+            if (nx, ny) not in parent:
+                parent[(nx, ny)] = (x, y)
+                q.append((nx, ny))
+    if end not in parent:
+        return []
+    # reconstruct path
+    path = []
+    at = end
+    while at is not None:
+        path.append(at)
+        at = parent.get(at)
+    return path[::-1]

utils/storage.md

@@ -1,4 +1,4 @@
-# Storage Module (`modules/storage.py`) Usage Guide
+# Storage Module (`utils/storage.py`) Usage Guide
 
 The `storage.py` module provides helper functions for:
 - Generating permalinks for 3D viewer projects.
@@ -12,7 +12,7 @@ The `storage.py` module provides helper functions for:
 ### 1. `generate_permalink(valid_files, base_url_external, permalink_viewer_url="surn-3d-viewer.hf.space")`
 - **Purpose:**  
   Given a list of file paths, it looks for exactly one model file (with an extension defined in `model_extensions`) and exactly two image files (extensions defined in `image_extensions`). If the criteria are met, it returns a permalink URL built from the base URL and query parameters.
-- **Usage Example:**from modules.storage import generate_permalink
+- **Usage Example:**from utils.storage import generate_permalink
 
 valid_files = [
     "models/3d_model.glb",
@@ -26,7 +26,7 @@ if permalink:
 ### 2. `generate_permalink_from_urls(model_url, hm_url, img_url, permalink_viewer_url="surn-3d-viewer.hf.space")`
 - **Purpose:**  
   Constructs a permalink URL by combining individual URLs for a 3D model (`model_url`), height map (`hm_url`), and image (`img_url`) into a single URL with corresponding query parameters.
-- **Usage Example:**from modules.storage import generate_permalink_from_urls
+- **Usage Example:**from utils.storage import generate_permalink_from_urls
 
 model_url = "https://example.com/model.glb"
 hm_url = "https://example.com/heightmap.png"
@@ -48,7 +48,7 @@ print("Generated Permalink:", permalink)
   - If no valid files are provided, it returns an empty list `[]` (this case should ideally also return the dictionary with empty/None values for consistency, but currently returns `[]` as per the code).
 - **Usage Example:**
 
-  **a. Uploading with permalink creation:**from modules.storage import upload_files_to_repo
+  **a. Uploading with permalink creation:**from utils.storage import upload_files_to_repo
 
 files_for_permalink = [
     "local/path/to/model.glb",
@@ -75,7 +75,7 @@ elif upload_result: # Check if list is not empty
         print(f"  Response: {res}, Link: {link}")
 else:
     print("No files uploaded or error occurred.")
-  **b. Uploading without permalink creation (or if conditions for permalink are not met):**from modules.storage import upload_files_to_repo
+  **b. Uploading without permalink creation (or if conditions for permalink are not met):**from utils.storage import upload_files_to_repo
 
 files_individual = [
     "local/path/to/another_model.obj",
@@ -113,8 +113,8 @@ If both short URL ID and full URL are provided, it checks consistency and either
 - **Returns:** A tuple `(status_message, result_url)`, where `status_message` indicates the outcome (e.g., `"success_retrieved_full"`, `"created_short"`) and `result_url` is the relevant URL (full or short ID).
 - **Usage Examples:**
 
-  **a. Convert a full URL into a short URL ID:**from modules.storage import gen_full_url
-from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
+  **a. Convert a full URL into a short URL ID:**from utils.storage import gen_full_url
+from utils.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
 
 full_permalink = "https://surn-3d-viewer.hf.space/?3d=https%3A%2F%2Fexample.com%2Fmodel.glb&hm=https%3A%2F%2Fexample.com%2Fheightmap.png&image=https%3A%2F%2Fexample.com%2Fsource.png"
 
@@ -130,8 +130,67 @@ if status == "created_short" or status == "success_retrieved_short":
     # permalink_viewer_url = "surn-3d-viewer.hf.space" # Or from constants
     # shareable_short_url = f"https://{permalink_viewer_url}/?sid={short_id}"
     # print("Shareable Short URL:", shareable_short_url)
-  **b. Retrieve the full URL from a short URL ID:**from modules.storage import gen_full_url
-from modules.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
+  **b. Retrieve the full URL from a short URL ID:**from utils.storage import gen_full_url
+from utils.constants import HF_REPO_ID, SHORTENER_JSON_FILE # Assuming these are defined
+
+## 📁 Repository Folder Listing Functions
+
+### 5. `_list_repo_folders(repo_id, path_prefix, repo_type="dataset")`
+- **Purpose:**  
+  List folder names under a given path in a HuggingFace repository. Enables folder-based discovery without index files.
+- **Parameters:**
+  - `repo_id` (str): The repository ID on Hugging Face
+  - `path_prefix` (str): The path prefix to list folders under
+  - `repo_type` (str): Repository type. Default is `"dataset"`.
+- **Returns:** `List[str]` - List of folder names found under the path_prefix.
+- **Usage Example:**
+```python
+from utils.storage import _list_repo_folders
+
+# List all date folders in daily leaderboards
+folders = _list_repo_folders("Surn/Wrdler-Data", "games/leaderboards/daily")
+print("Available dates:", folders)
+```
+
+### 6. `_list_repo_files_in_folder(repo_id, folder_path, repo_type="dataset")`
+- **Purpose:**  
+  List file names directly under a folder in a HuggingFace repository.
+- **Parameters:**
+  - `repo_id` (str): The repository ID on Hugging Face
+  - `folder_path` (str): The folder path to list files under
+  - `repo_type` (str): Repository type. Default is `"dataset"`.
+- **Returns:** `List[str]` - List of file names found directly in the folder.
+- **Usage Example:**
+```python
+from utils.storage import _list_repo_files_in_folder
+
+files = _list_repo_files_in_folder(
+    "Surn/Wrdler-Data",
+    "games/leaderboards/daily/2025-01-27/classic-classic-0",
+)
+print("Files:", files)
+```
+
+## 🔑 Cryptographic Key Management Functions
+
+### 7. `store_issuer_keypair(issuer_id, public_key, private_key, repo_id=None)`
+- **Purpose:**  
+  Store cryptographic keys for an issuer in a private Hugging Face repository. Private keys are encrypted before storage.
+- **⚠️ IMPORTANT:** This requires a PRIVATE Hugging Face repository. Do not use this with public repositories.
+- **Returns:** `bool` - True if keys were stored successfully, False otherwise.
+
+### 8. `get_issuer_keypair(issuer_id, repo_id=None)`
+- **Purpose:**  
+  Retrieve and decrypt stored cryptographic keys for an issuer.
+- **Returns:** `Tuple[Optional[str], Optional[str]]` - (public_key, private_key) or (None, None) if not found.
+
+### 9. `get_verification_methods_registry(repo_id=None)`
+- **Purpose:**  
+  Retrieve the global verification methods registry containing all registered issuer public keys.
+
+### 10. `list_issuer_ids(repo_id=None)`
+- **Purpose:**  
+  List all issuer IDs that have stored keys in the repository.
 
 short_id_to_lookup = "aBcDeFg1"  # Example short URL ID
 
@@ -144,8 +203,9 @@ print("Status:", status)
 if status == "success_retrieved_full":
     print("Retrieved Full URL:", retrieved_full_url)
 ## Notes
-- **Authentication:** All functions that interact with Hugging Face Hub use the HF API token defined as `HF_API_TOKEN` in `modules/constants.py`. Ensure this environment variable is correctly set.
-- **Constants:** Functions like `gen_full_url` and `upload_files_to_repo` (when creating short links) rely on `HF_REPO_ID` and `SHORTENER_JSON_FILE` from `modules/constants.py` for the URL shortening feature.
+- **Authentication:** All functions that interact with Hugging Face Hub use the HF API token defined as `HF_API_TOKEN` in `utils/constants.py`. Ensure this environment variable is correctly set.
+- **Constants:** Functions like `gen_full_url` and `upload_files_to_repo` (when creating short links) rely on `HF_REPO_ID` and `SHORTENER_JSON_FILE` from `utils/constants.py` for the URL shortening feature.
+- **🔐 Private Repository Requirement:** Key management functions require a PRIVATE Hugging Face repository to ensure the security of stored encrypted private keys. Never use these functions with public repositories.
 - **File Types:** Only files with extensions included in `upload_file_types` (a combination of `model_extensions` and `image_extensions` from `modules/constants.py`) are processed by `upload_files_to_repo`.
 - **Repository Configuration:** When using URL shortening and file uploads, ensure that the specified Hugging Face repository (e.g., defined by `HF_REPO_ID`) exists and that you have write permissions.
 - **Temporary Directory:** `upload_files_to_repo` temporarily copies files to a local directory (configured by `TMPDIR` in `modules/constants.py`) before uploading.

utils/storage.py

@@ -1,15 +1,42 @@
-# utils/storage.py
-__version__ = "0.1.1" # Added version
+"""Hugging Face Hub storage helpers.
+
+This module is a port of the BattleWords `modules/storage.py` implementation.
+It supports:
+- Batch uploading files via `upload_folder`
+- Generating permalinks to a 3D viewer
+- URL-shortener mapping stored in a JSON file in a HF dataset repo
+- Listing repo folders/files
+- Optional issuer keypair storage (requires PRIVATE repo; demo encryption)
+"""
+
+__version__ = "0.1.6"
+
 import os
 import urllib.parse
 import tempfile
 import shutil
 import json
 import base64
+import logging
+from datetime import datetime, timezone
 from huggingface_hub import login, upload_folder, hf_hub_download, HfApi
 from huggingface_hub.utils import RepositoryNotFoundError, EntryNotFoundError
-from utils.constants import HF_API_TOKEN, upload_file_types, model_extensions, image_extensions, audio_extensions, video_extensions, HF_REPO_ID, SHORTENER_JSON_FILE
-from typing import Any, Dict, List, Tuple, Union
+from utils.constants import (
+    HF_API_TOKEN,
+    upload_file_types,
+    model_extensions,
+    image_extensions,
+    audio_extensions,
+    video_extensions,
+    doc_extensions,
+    HF_REPO_ID,
+    SHORTENER_JSON_FILE,
+)
+from typing import Any, Dict, List, Tuple, Union, Optional
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
 
 # see storage.md for detailed information about the storage module and its functions.
 
@@ -23,6 +50,7 @@ def generate_permalink(valid_files, base_url_external, permalink_viewer_url="sur
     images_links = []
     audio_links = []
     video_links = []
+    doc_links = []
     for f in valid_files:
         filename = os.path.basename(f)
         ext = os.path.splitext(filename)[1].lower()
@@ -35,6 +63,8 @@ def generate_permalink(valid_files, base_url_external, permalink_viewer_url="sur
             audio_links.append(f"{base_url_external}/{filename}")
         elif ext in video_extensions:
             video_links.append(f"{base_url_external}/{filename}")
+        elif ext in doc_extensions:
+            doc_links.append(f"{base_url_external}/{filename}")
     if model_link and len(images_links) == 2:
         # Construct a permalink to the viewer project with query parameters.
         permalink_viewer_url = f"https://{permalink_viewer_url}/"
@@ -94,8 +124,14 @@ def upload_files_to_repo(
             Otherwise:
                 list: A list of tuples (response, permalink) for each file.
     """
+    logger.info(f"Starting batch upload to repository: {repo_id}")
+
     # Log in using the HF API token.
-    login(token=HF_API_TOKEN)
+    try:
+        login(token=HF_API_TOKEN)
+    except Exception as e:
+        logger.error(f"Authentication failed: {e}")
+        return {"response": "Authentication failed", "permalink": None, "short_permalink": None} if create_permalink else []
     
     valid_files = []
     permalink_short = None
@@ -131,13 +167,17 @@ def upload_files_to_repo(
         
         # Batch upload all files in the temporary folder.
         # Files will be uploaded under the folder (path_in_repo) given by folder_name.
-        response = upload_folder(
-            folder_path=temp_dir,
-            repo_id=repo_id,
-            repo_type=repo_type,
-            path_in_repo=folder_name,
-            commit_message="Batch upload files"
-        )
+        try:
+            response = upload_folder(
+                folder_path=temp_dir,
+                repo_id=repo_id,
+                repo_type=repo_type,
+                path_in_repo=folder_name,
+                commit_message="Batch upload files",
+            )
+        except Exception as e:
+            logger.error(f"Batch upload failed: {e}")
+            return {"response": f"Upload failed: {e}", "permalink": None, "short_permalink": None} if create_permalink else []
     
     # Construct external URLs for each uploaded file.
     base_url_external = f"https://huggingface.co/datasets/{repo_id}/resolve/main/{folder_name}"
@@ -160,8 +200,8 @@ def upload_files_to_repo(
             if status in ["created_short", "success_retrieved_short", "exists_match"]:
                 permalink_short = f"https://{permalink_viewer_url}/?sid={short_id}"
             else: # Shortening failed or conflict not resolved to a usable short_id
-                permalink_short = None 
-                print(f"URL shortening status: {status} for {permalink}")
+                permalink_short = None
+                logger.warning(f"URL shortening status: {status} for {permalink}")
 
             return {
                 "response": response,
@@ -178,6 +218,33 @@ def upload_files_to_repo(
     # Otherwise, return individual tuples for each file.
     return [(response, link) for link in individual_links]
 
+
+def _get_files_from_repo(repo_id, file_name, repo_type="dataset"):
+    """Downloads a file from the repo. File must be in upload_file_types."""
+    filename = os.path.basename(file_name)
+    ext = os.path.splitext(file_name)[1].lower()
+    if ext not in upload_file_types:
+        logger.error(f"File {filename} with extension {ext} is not allowed for upload.")
+        return None
+    try:
+        login(token=HF_API_TOKEN)
+        file_path = hf_hub_download(
+            repo_id=repo_id,
+            filename=file_name,
+            repo_type=repo_type,
+            token=HF_API_TOKEN,
+        )
+        return file_path or None
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return None
+    except EntryNotFoundError:
+        logger.warning(f"file {file_name} not found in {repo_id}.")
+        return None
+    except Exception as e:
+        logger.error(f"Error fetching {file_name} from {repo_id}: {e}")
+        return None
+
 def _generate_short_id(length=8):
     """Generates a random base64 URL-safe string."""
     return base64.urlsafe_b64encode(os.urandom(length * 2))[:length].decode('utf-8')
@@ -197,16 +264,16 @@ def _get_json_from_repo(repo_id, json_file_name, repo_type="dataset"):
         os.remove(json_path) # Clean up downloaded file
         return data
     except RepositoryNotFoundError:
-        print(f"Repository {repo_id} not found.")
+        logger.warning(f"Repository {repo_id} not found.")
         return []
     except EntryNotFoundError:
-        print(f"JSON file {json_file_name} not found in {repo_id}. Initializing with empty list.")
+        logger.warning(f"JSON file {json_file_name} not found in {repo_id}. Initializing with empty list.")
         return []
     except json.JSONDecodeError:
-        print(f"Error decoding JSON from {json_file_name}. Returning empty list.")
+        logger.error(f"Error decoding JSON from {json_file_name}. Returning empty list.")
         return []
     except Exception as e:
-        print(f"An unexpected error occurred while fetching {json_file_name}: {e}")
+        logger.error(f"An unexpected error occurred while fetching {json_file_name}: {e}")
         return []
 
 def _upload_json_to_repo(data, repo_id, json_file_name, repo_type="dataset"):
@@ -232,7 +299,7 @@ def _upload_json_to_repo(data, repo_id, json_file_name, repo_type="dataset"):
         os.remove(tmp_file_path) # Clean up temporary file
         return True
     except Exception as e:
-        print(f"Failed to upload {json_file_name} to {repo_id}: {e}")
+        logger.error(f"Failed to upload {json_file_name} to {repo_id}: {e}")
         if 'tmp_file_path' in locals() and os.path.exists(tmp_file_path):
             os.remove(tmp_file_path) # Ensure cleanup on error too
         return False
@@ -325,3 +392,174 @@ def gen_full_url(short_url=None, full_url=None, repo_id=None, repo_type="dataset
             return "error_upload", None
                 
     return "error_unhandled_case", None # Should not be reached
+
+
+def _encrypt_private_key(private_key: str, password: str = None) -> str:
+    """Basic XOR encryption for demo purposes only."""
+    if not password:
+        password = "default_encryption_key"
+    encrypted_bytes = [ord(char) ^ ord(password[i % len(password)]) for i, char in enumerate(private_key)]
+    return base64.b64encode(bytes(encrypted_bytes)).decode("utf-8")
+
+
+def _decrypt_private_key(encrypted_private_key: str, password: str = None) -> str:
+    """Basic XOR decryption for demo purposes only."""
+    if not password:
+        password = "default_encryption_key"
+    encrypted_data = base64.b64decode(encrypted_private_key)
+    decrypted_chars = [chr(byte ^ ord(password[i % len(password)])) for i, byte in enumerate(encrypted_data)]
+    return "".join(decrypted_chars)
+
+
+def store_issuer_keypair(issuer_id: str, public_key: str, private_key: str, repo_id: str = None) -> bool:
+    """Store issuer keypair in HF dataset repo (PRIVATE repo strongly recommended)."""
+    if not issuer_id or not public_key or not private_key:
+        raise ValueError("issuer_id, public_key, and private_key are required")
+
+    if not repo_id:
+        repo_id = HF_REPO_ID
+
+    safe_issuer_id = issuer_id.replace("https://", "").replace("http://", "").replace("/", "_").replace(":", "_")
+
+    encrypted_private_key = _encrypt_private_key(private_key)
+    private_key_data = {
+        "issuer_id": issuer_id,
+        "encrypted_private_key": encrypted_private_key,
+        "key_type": "Ed25519VerificationKey2020",
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "encryption_method": "basic_xor",
+    }
+    public_key_data = {
+        "issuer_id": issuer_id,
+        "public_key": public_key,
+        "key_type": "Ed25519VerificationKey2020",
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    private_key_path = f"keys/issuers/{safe_issuer_id}/private_key.json"
+    public_key_path = f"keys/issuers/{safe_issuer_id}/public_key.json"
+
+    private_ok = _upload_json_to_repo(private_key_data, repo_id, private_key_path, "dataset")
+    public_ok = _upload_json_to_repo(public_key_data, repo_id, public_key_path, "dataset")
+    if private_ok and public_ok:
+        _update_verification_methods_registry(issuer_id, safe_issuer_id, public_key, repo_id)
+    return private_ok and public_ok
+
+
+def get_issuer_keypair(issuer_id: str, repo_id: str = None) -> Tuple[Optional[str], Optional[str]]:
+    """Retrieve stored issuer keypair from HF dataset repo."""
+    if not issuer_id:
+        raise ValueError("issuer_id is required")
+
+    if not repo_id:
+        repo_id = HF_REPO_ID
+
+    safe_issuer_id = issuer_id.replace("https://", "").replace("http://", "").replace("/", "_").replace(":", "_")
+
+    public_key_path = f"keys/issuers/{safe_issuer_id}/public_key.json"
+    private_key_path = f"keys/issuers/{safe_issuer_id}/private_key.json"
+    public_key_data = _get_json_from_repo(repo_id, public_key_path, "dataset")
+    private_key_data = _get_json_from_repo(repo_id, private_key_path, "dataset")
+    if not public_key_data or not private_key_data:
+        return None, None
+
+    encrypted_private_key = private_key_data.get("encrypted_private_key")
+    if not encrypted_private_key:
+        return None, None
+
+    return public_key_data.get("public_key"), _decrypt_private_key(encrypted_private_key)
+
+
+def _update_verification_methods_registry(issuer_id: str, safe_issuer_id: str, public_key: str, repo_id: str):
+    try:
+        registry_path = "keys/global/verification_methods.json"
+        registry_data = _get_json_from_repo(repo_id, registry_path, "dataset")
+
+        if not registry_data:
+            registry_data = {"verification_methods": []}
+
+        existing_entry = None
+        for i, method in enumerate(registry_data.get("verification_methods", [])):
+            if method.get("issuer_id") == issuer_id:
+                existing_entry = i
+                break
+
+        verification_method = {
+            "issuer_id": issuer_id,
+            "safe_issuer_id": safe_issuer_id,
+            "public_key": public_key,
+            "key_type": "Ed25519VerificationKey2020",
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+        }
+
+        if existing_entry is not None:
+            registry_data["verification_methods"][existing_entry] = verification_method
+        else:
+            registry_data["verification_methods"].append(verification_method)
+
+        _upload_json_to_repo(registry_data, repo_id, registry_path, "dataset")
+    except Exception as e:
+        logger.error(f"Error updating verification methods registry: {e}")
+
+
+def get_verification_methods_registry(repo_id: str = None) -> Dict[str, Any]:
+    if not repo_id:
+        repo_id = HF_REPO_ID
+    registry_path = "keys/global/verification_methods.json"
+    registry_data = _get_json_from_repo(repo_id, registry_path, "dataset")
+    return registry_data if registry_data else {"verification_methods": []}
+
+
+def list_issuer_ids(repo_id: str = None) -> List[str]:
+    if not repo_id:
+        repo_id = HF_REPO_ID
+    registry = get_verification_methods_registry(repo_id)
+    return [method["issuer_id"] for method in registry.get("verification_methods", [])]
+
+
+def _list_repo_folders(repo_id: str, path_prefix: str, repo_type: str = "dataset") -> List[str]:
+    try:
+        login(token=HF_API_TOKEN)
+        api = HfApi()
+        all_files = api.list_repo_files(repo_id=repo_id, repo_type=repo_type, token=HF_API_TOKEN)
+
+        if path_prefix and not path_prefix.endswith("/"):
+            path_prefix = path_prefix + "/"
+
+        folders = set()
+        for file_path in all_files:
+            if file_path.startswith(path_prefix):
+                relative_path = file_path[len(path_prefix) :]
+                if "/" in relative_path:
+                    folders.add(relative_path.split("/")[0])
+        return sorted(list(folders))
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return []
+    except Exception as e:
+        logger.error(f"Error listing folders in {repo_id}/{path_prefix}: {e}")
+        return []
+
+
+def _list_repo_files_in_folder(repo_id: str, folder_path: str, repo_type: str = "dataset") -> List[str]:
+    try:
+        login(token=HF_API_TOKEN)
+        api = HfApi()
+        all_files = api.list_repo_files(repo_id=repo_id, repo_type=repo_type, token=HF_API_TOKEN)
+
+        if folder_path and not folder_path.endswith("/"):
+            folder_path = folder_path + "/"
+
+        files: List[str] = []
+        for file_path in all_files:
+            if file_path.startswith(folder_path):
+                relative_path = file_path[len(folder_path) :]
+                if "/" not in relative_path and relative_path:
+                    files.append(relative_path)
+        return sorted(files)
+    except RepositoryNotFoundError:
+        logger.warning(f"Repository {repo_id} not found.")
+        return []
+    except Exception as e:
+        logger.error(f"Error listing files in {repo_id}/{folder_path}: {e}")
+        return []