ImageBriefValidator

ImageBriefValidator is a small, dependency-free Elixir library for checking the structure of an image-generation brief before the brief leaves your application. It validates prompts, dimensions, optional style presets, reference lists, and aspect ratios without making network requests or depending on a particular rendering provider.

Why validate locally first?

Image-generation pipelines often fail before a model receives useful input. A prompt can be empty, a width can arrive as a string, or a reference list can contain a blank value. Those defects are cheap to catch in the calling application and expensive to discover after a remote request has already started.

A local validation boundary provides:

1. Fast feedback before a network round trip.
2. A consistent error shape for forms, jobs, logs, and API responses.
3. A provider-independent contract that can survive changes to a downstream generation workflow.

The library deliberately checks structure rather than creative quality. It cannot decide whether a prompt is interesting or whether reference images are visually coherent.

Installation

Add image_brief_validator to your dependencies:

def deps do
  [
    {:image_brief_validator, "~> 0.1.0"}
  ]
end

Validate a brief

Both atom and string keys are accepted:

brief = %{
  prompt: "A studio product photograph with soft side lighting",
  width: 1200,
  height: 800,
  style: "product_shot",
  references: ["front.png", "detail.png"]
}

ImageBriefValidator.validate(brief)
# => {:ok, brief}

When a brief is malformed, the library returns every detected structural error instead of stopping at the first one:

ImageBriefValidator.validate(%{
  prompt: " ",
  width: 0,
  height: "800",
  style: "unknown",
  references: ["front.png", ""]
})

# => {:error,
#      [
#        prompt: :must_be_present,
#        width: :must_be_a_positive_integer,
#        height: :must_be_a_positive_integer,
#        style: :is_not_supported,
#        references: :must_contain_non_empty_strings
#      ]}

The currently documented style presets are:

• photographic
• illustration
• flat_vector
• product_shot
• poster

Style and references are optional. Prompt, width, and height are required.

Aspect ratios

Use aspect_ratio/2 to reduce positive integer dimensions:

ImageBriefValidator.aspect_ratio(1920, 1080)
# => {:ok, "16:9"}

ImageBriefValidator.aspect_ratio(0, 1080)
# => {:error, :invalid_dimensions}

Where a rendering workflow fits

Validation and rendering should remain separate concerns. This package never calls an image model. Once a brief passes validation, the caller can map it to a provider, a browser workflow, or an internal job format.

For teams preparing product visuals, ads, posters, multilingual layouts, or multi-reference edits, the Seedream 5.0 Pro AI Image Generator is one example of a browser-based structured image workflow that can receive a brief after local validation. That independent tool is included only as a workflow example; this package has no direct integration with it and does not claim current pricing, limits, resolution, or performance.

Design choices

The implementation uses plain pattern matching and small private checks:

• no runtime dependencies
• all errors returned as a keyword list
• original input returned unchanged after successful validation
• no conversion of user-provided string keys into atoms
• no file reads, HTTP calls, or side effects

These choices keep the library suitable for request validation, Oban jobs, LiveView forms, command-line tools, and batch pipelines.

Limitations

Structural validation is not semantic review. The package cannot determine whether an image prompt is truthful, safe, on-brand, or likely to produce a useful result. Style presets are intentionally small and may not match a specific provider. Applications with a changing external schema should add their own adapter layer and tests rather than treating this package as a remote API contract.

License

MIT