image_brief_validator

# 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:

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

## Validate a brief

Both atom and string keys are accepted:

```elixir
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:

```elixir
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:

```elixir
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](https://seedream50.pro/) 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