Skip to content
Bria-AIPublic

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

9 stars

Watchers

1 watching

Forks

Repository files navigation

VGL β€” Visual Generation Language

VGL turns a text prompt, or images plus a prompt, into a structured JSON description of a scene: objects, background, lighting, aesthetics, camera, and text. The result is a typed Pydantic model that an image model like FIBO takes as its prompt.

Install

pip install bria-vgl

The default LLM is Gemini through Google AI Studio. For other providers, install the extra:

pip install 'bria-vgl[vertex]'     # Gemini on Vertex AI
pip install 'bria-vgl[bedrock]'    # Claude on AWS Bedrock

Authenticate

Provider llm= Set
Google AI Studio (default) gemini/gemini-3.5-flash-lite GEMINI_API_KEY (get one)
Vertex AI vertex_ai/gemini-3.5-flash-lite VERTEXAI_PROJECT, VERTEXAI_LOCATION, GOOGLE_APPLICATION_CREDENTIALS (a service account JSON)
AWS Bedrock e.g. bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0 the usual AWS credentials and AWS_REGION_NAME

llm takes any litellm model id, but the prompts are tuned for Gemini.

Quickstart

Create a scene from a prompt

import bria_vgl
from bria_vgl.dialects.thales import Generate

scene = bria_vgl.create(Generate(prompt="a red fox in snow at dusk"))
print(scene.short_description)
print(scene.model_dump_json(indent=2, exclude_none=True))

Create a scene inspired by an image

The image is a visual reference only. The VGL describes the scene the prompt asks for, not the image.

import bria_vgl
from bria_vgl.dialects.thales import Inspire

scene = bria_vgl.create(Inspire(prompt="the same fox, at the beach", image=fox))

Describe an image

No prompt: the VGL describes the image itself.

from bria_vgl.dialects.thales import Caption

scene = bria_vgl.create(Caption(image=fox))

Refine a VGL

No image: the prompt changes an existing VGL, and the fields it doesn't affect are kept.

from bria_vgl.dialects.thales import Generate, Refine

scene = bria_vgl.create(Generate(prompt="a cosy living room"))
night = bria_vgl.modify(Refine(prompt="make it night", input_vgl=scene))

bria_vgl.create(Refine(...)) works too, and takes the create() options.

Edit from images

from PIL import Image
from bria_vgl.dialects.thales import EditImages

room = Image.open("room.jpg")
lamp = Image.open("lamp.jpg")

scene = bria_vgl.modify(EditImages(prompt="make it night", images=[room]))
scene = bria_vgl.modify(EditImages(prompt="put the lamp from <image_2> in <image_1>", images=[room, lamp]))
print(scene.edit_instruction)

Up to 4 images. The prompt refers to them as <image_1> to <image_4>, in list order.

Edit a masked area

from bria_vgl.dialects.thales import EditImageWithMask

mask = Image.open("mask.png")  # white is the area to change; same size as the image
scene = bria_vgl.modify(EditImageWithMask(prompt="replace it with a cat", image=room, mask=mask))

Edit with the image's VGL

If you have the VGL that an image was generated from, pass it as input_image_vgl. The edit then keeps everything the prompt doesn't change, rather than re-describing the image from scratch. vgl doesn't check that it matches the image.

scene = bria_vgl.create(Generate(prompt="a cosy living room"))
image = ...  # generate the image from `scene` with FIBO
night = bria_vgl.modify(EditImages(prompt="make it night", images=[image], input_image_vgl=scene))

Runnable versions are in examples/.

Options

bria_vgl.create(payload, llm="vertex_ai/gemini-3.5-flash-lite", seed=7, style_preset_prompt="Muted film colours, soft grain.")
bria_vgl.modify(payload, llm=..., seed=...)
  • llm: the litellm model id; see Authenticate.
  • seed: makes a call repeatable, on models that accept one.
  • style_preset_prompt: style guidelines added to the system prompt. Applies to create only; modify ignores it.

create also takes overrides for the payload's defaults. Each is optional, and leaving it out keeps the default:

  • system_prompt: replaces the system prompt. {llm_input_schema} and {style_preset_block} in it are still filled.
  • final_prompt: replaces the final (user) prompt. Its placeholders, such as {user_prompt}, are still filled.
  • input_schema: the field guide filled into {llm_input_schema}.
  • response_schema: the JSON schema the model must follow, in Gemini's format. Extra keys in the reply are dropped from the VGL.
  • thinking_level: a bria_vgl.ThinkingLevel or its string, "minimal", "low", "medium" or "high", on Gemini 3+. Anything else, or a level on an older Gemini, raises ValueError before the call. By default thinking is as low as the model allows.
  • temperature and max_output_tokens: thinking tokens count against max_output_tokens, so raise it with a high thinking level.

A Gemini call that keeps failing (3 attempts) or hits a rate limit (429, not retried) moves to gemini-3.1-flash-lite on the same provider.

Logging

bria-vgl logs structured records: a constant message, with the data as extra fields on the record (model, duration_seconds, attempt, error, …). Use a formatter that emits record attributes (e.g. a JSON formatter) to see them; a plain %(message)s formatter shows only the message.

By default each module logs under the bria_vgl hierarchy (bria_vgl.gateway, bria_vgl.prompting, …); configure it the standard way, e.g. logging.getLogger("bria_vgl").setLevel(logging.INFO).

To route everything to your own logger, e.g. one carrying request context:

adapter = logging.LoggerAdapter(logging.getLogger("my_service"), {"request_id": rid}, merge_extra=True)
bria_vgl.set_logger(adapter)   # set_logger(None) restores the default

A plain LoggerAdapter replaces bria-vgl's extra fields with its own. Pass merge_extra=True (Python 3.13+) or override process() to keep both.

Errors

Everything bria-vgl raises inherits from bria_vgl.exceptions.VGLError, except a bad payload, which raises pydantic.ValidationError before any LLM call. The classes below all live in bria_vgl.exceptions.

Error Means
AuthenticationError the provider rejected your credentials, e.g. a missing or wrong API key
RateLimitError the provider returned 429 (quota exhausted), on the Gemini fallback too
ContentFilteredError the provider's safety filter blocked the prompt or the reply
LLMError any other provider failure, after retries and the fallback
InvalidResponseError the model's reply isn't a valid VGL
UnusableReplyError the model twice replied without a valid VGL, which reads as a refusal; it is both a ContentFilteredError and an InvalidResponseError
MaxTokensError the model ran out of output tokens mid-reply
PromptNotFoundError a bundled prompt is missing; a packaging fault, please report it

A reply that isn't a valid VGL is asked for once more, with the next seed. A model that won't depict a prompt often answers with JSON that leaves out the scene, or with prose, rather than a filtered reply, so a second such reply raises UnusableReplyError.

Dialects

A dialect is a small variant of VGL, with its own model, payloads, and prompts. The payload you import decides the dialect. vgl ships the Thales dialect: no aesthetic scores, and every edit states its change in edit_instruction.

More

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

9 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages