DEV Community

Cover image for Zator Tutorial: Automate AI Content Pipelines with a Specialized DSL
4ds-dev
4ds-dev

Posted on

Zator Tutorial: Automate AI Content Pipelines with a Specialized DSL

#tutorial #ai #zator #programming

Learn how to build powerful text and image generation workflows using Zator, the domain-specific language for KoboldCpp.

In the world of Generative AI, we often find ourselves writing repetitive "glue code" in Python just to connect an LLM to an image generator, process the output, and save the files. What if you could describe your entire generative pipeline in a concise, purpose-built script?

Welcome to the Zator Tutorial. In this guide, we will explore Zator, a specialized programming language designed specifically for orchestrating AI content creation via KoboldCpp. Whether you need to generate fantasy stories, create game assets with transparent backgrounds, or trigger external webhooks, Zator allows you to do it with minimal syntax and maximum control.

🧠 What is Zator?

Zator is a Domain-Specific Language (DSL) that treats AI generation as a first-class citizen. Unlike general-purpose languages, it comes with built-in commands for:

  • 🤖 Text & Image Generation: Native support for KoboldCpp's text and Stable Diffusion APIs.
  • 🎨 Image Processing: Built-in chroma keying (green screen removal) and scaling.
  • 🌐 System Integration: Execute HTTP requests (request) and shell commands (exec_cmd).
  • ⚙️ Modularity: Define reusable functions with parameters and import external modules.

New in Version 0.0.2: Function parameters, improved execution flow, exec_cmd for system tasks, enhanced f-string support, and cross-platform HTTP requests.

🛠️ Prerequisites & Setup

Before starting this tutorial, ensure your environment is ready. Zator acts as a client, so it requires a running server.

1. The Engine: KoboldCpp

You must have KoboldCpp running with the following APIs enabled:

  • /api/v1/generate (for Text)
  • /sdapi/v1/txt2img (for Images via Stable Diffusion)

Default Connection: http://localhost:5001

2. System Dependencies

  • OS: Windows 10/11, Linux, or macOS.
  • Libraries: libpng, zlib, and curl (required for image handling and HTTP requests).
  • Hardware: A GPU is highly recommended for reasonable image generation speeds.

3. Running Your First Script

Save your code as script.zator and run:

zator.exe script.zator
Enter fullscreen mode Exit fullscreen mode

📝 Syntax Crash Course

Zator combines the simplicity of scripting languages with specific constructs for AI tasks.

Variables & Types

Zator handles three core types automatically:

var greeting = "Hello, World!"              # String (VAR_STRING)
var max_tokens = 250                        # Integer (VAR_INT)
var hero_portrait = generate_img(...)       # Image Object (VAR_IMAGE)
Enter fullscreen mode Exit fullscreen mode

The Power of F-Strings

Just like in Python, you can inject variables directly into strings, file paths, API prompts, and function arguments:

var char_name = "Garrick"
var prompt = "A portrait of {char_name}, a brave knight, digital art"
var filename = "output/{char_name}.png"

var img = generate_img(prompt, context, 512, 512)
save_img(img, filename)
Enter fullscreen mode Exit fullscreen mode

Tip: To print literal braces, use escaping: \{variable\}.

Context is King

Set a global context variable to prepend instructions to every AI generation call, ensuring consistent tone and style:

context = "You are a creative assistant specializing in dark fantasy lore."
Enter fullscreen mode Exit fullscreen mode

🎨 Core Workflows

1. Generating Text & Images

The bread and butter of Zator.

# Text Generation
var story_intro = generate_text("Write a hook for a mystery novel", context, 150)
save_txt(story_intro, "stories/mystery_hook.txt")

# Image Generation
# Note: Dimensions should ideally be multiples of 64 for SD compatibility
var landscape = generate_img("Cyberpunk city street at night, neon rain", context, 768, 512)
save_img(landscape, "art/cyberpunk_city.png")
Enter fullscreen mode Exit fullscreen mode

2. Advanced Image Processing: Chroma Key & Scaling

One of Zator's standout features is its ability to process images immediately after generation. This is perfect for creating game assets.

Scenario: Generate a character on a green screen, remove the background, and create an icon.

# 1. Generate on green background
var raw_char = generate_img("Kobold wizard casting a spell, solid green background", context, 512, 512)

# 2. Remove green background 
# Samples color at x=10, y=10 with 5% tolerance
var clean_char = chroma_key_crop(raw_char, 10, 10, 5.0)

# 3. Create a 64x64 icon using nearest-neighbor scaling
var char_icon = scale_to(clean_char, 64, 64)

# 4. Save results
save_img(clean_char, "assets/kobold_full.png")
save_img(char_icon, "assets/kobold_icon.png")
Enter fullscreen mode Exit fullscreen mode

🧩 Modularity: Functions & Imports

As your pipelines grow, keep them organized. Zator supports user-defined functions with up to 10 parameters.

Defining Functions 

def create_rpg_asset(name, role, bg_color) {
    var prompt = "Character sprite: {name} the {role}, {bg_color} background"
    var img = generate_img(prompt, context, 512, 512)

    # Auto-crop if background is green
    if bg_color == "green" {
        img = chroma_key_crop(img, 0, 0, 5.0)
    }

    save_img(img, "characters/{name}.png")
    print("Created asset for {name}")
}

# Usage
call create_rpg_asset("Elara", "Rogue", "green")
call create_rpg_asset("Thorn", "Warrior", "blue")
Enter fullscreen mode Exit fullscreen mode

Importing Modules

Split your code into libraries (e.g., utils.zator) and import them:

#import "utils.zator"
call some_helper_function()
Enter fullscreen mode Exit fullscreen mode

🌐 Beyond AI: HTTP & System Commands

Zator isn't limited to local generation. You can integrate it into larger workflows.

Making API Requests

Send data to Discord, Telegram, or any webhook using the request function.

var token = "YOUR_BOT_TOKEN"
var msg = "New character generated!"
var body = "{ \"chat_id\": \"12345\", \"text\": \"{msg}\" }"

var response
request("https://api.telegram.org/bot{token}/sendMessage", "POST", response, body)
print("Telegram Status: {response}")
Enter fullscreen mode Exit fullscreen mode

Executing Shell Commands

Need to move files, check disk space, or run a git command? Use exec_cmd.

# Check current directory
var cwd = exec_cmd("pwd")
print("Working in: {cwd}")

# List generated files
var files = exec_cmd("ls -la characters/")
print("Files:\n{files}")

# Command with variable interpolation
var filename = "data.txt"
var content = exec_cmd("cat {filename}")
Enter fullscreen mode Exit fullscreen mode

⚠️ Security Note: Be cautious when using exec_cmd with user input to avoid command injection vulnerabilities.

🎮 Interactive Scripts

Zator supports standard I/O, allowing you to build CLI tools that ask for user input.

print("Enter character name: ")
input(name)

print("Choose class (Mage/Warrior): ")
input(class_type)

var final_prompt = "Portrait of {name}, a powerful {class_type}"
var result = generate_img(final_prompt, context, 512, 512)
save_img(result, "output/{name}.png")
print("Done! Check the output folder.")
Enter fullscreen mode Exit fullscreen mode

💡 Best Practices & Limitations (v0.0.2)

To get the most out of Zator, keep these tips in mind based on the official documentation:

Area Recommendation
Image Sizes Stick to multiples of 64 (e.g., 512, 768) for Stable Diffusion stability.
Token Limits Keep max_tokens under 500 for reliable text generation performance.
Chroma Key Sample the background color from a corner pixel (e.g., 10,10) for best results.
Flow Control Conditional blocks (if) support single commands unless wrapped in {}. Nested repeat loops are not yet supported.
Paths All file paths are relative to the script's location.
Dependencies Ensure curl is installed for HTTP requests to work.

🔮 What's Next?

The Zator roadmap is active. Upcoming features include:

  • Support for nested conditional blocks.
  • Image layering and overlay functions.
  • Native JSON parsing.
  • Support for arrays and lists.
  • Direct integration with DALL-E 3 and Midjourney APIs.

🏁 Conclusion

Zator bridges the gap between prompt engineering and software development. It allows creators to build robust, repeatable AI pipelines without the overhead of a full general-purpose language. Whether you are an indie game dev generating hundreds of assets or a writer prototyping story branches, Zator gives you the control you need with the simplicity you want.

Ready to try it?

  1. Fire up your KoboldCpp instance.
  2. Grab the latest zator.exe binary.
  3. Write your first .zator script and let the AI do the heavy lifting.

Top comments (0)