Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Image requests, generated bytes, and provider errors.
use model::document::FileType;
/// The shape of image the model is asked for, as the model vocabulary calls
/// it. The closed set keeps the agent from inventing ratios the provider
/// rejects.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImageAspectRatio {
/// 1:1
Square,
/// 4:3
Landscape,
/// 3:4
Portrait,
/// 16:9
Widescreen,
/// 9:16
Tall,
}
impl ImageAspectRatio {
/// The `width:height` form image providers accept.
pub fn as_ratio(self) -> &'static str {
match self {
Self::Square => "1:1",
Self::Landscape => "4:3",
Self::Portrait => "3:4",
Self::Widescreen => "16:9",
Self::Tall => "9:16",
}
}
}
/// What to generate.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImageGenerationRequest {
/// Natural-language description of the image.
pub prompt: String,
/// Requested shape; the provider default when `None`.
pub aspect_ratio: Option<ImageAspectRatio>,
/// Reference photos in the order the prompt refers to them.
pub reference_images: Vec<ReferenceImage>,
}
/// A saved image the caller wants to use as a reference.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImageReference {
/// A Macro document, read with the caller's document permissions.
Document(uuid::Uuid),
/// An uploaded static file, identified by its public capability ID.
StaticFile(uuid::Uuid),
}
/// Image bytes resolved internally for the provider, never returned in tool output.
#[derive(Clone, PartialEq, Eq)]
pub struct ReferenceImage {
/// Encoded image bytes.
pub bytes: Vec<u8>,
/// Media type of the encoded bytes.
pub mime_type: String,
}
impl std::fmt::Debug for ReferenceImage {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ReferenceImage")
.field("size_bytes", &self.bytes.len())
.field("mime_type", &self.mime_type)
.finish()
}
}
/// Why a reference photo could not be loaded.
#[derive(Debug, thiserror::Error)]
pub enum ReadImageError {
/// This host has no reference reader configured.
#[error("reference images are not available on this host")]
Unavailable,
/// The caller cannot read the requested source.
#[error("reference image is missing or you do not have access to it")]
Unauthorized,
/// The reference does not resolve to one image.
#[error("reference must identify an image file")]
NotImage,
/// Storage or image decoding failed.
#[error("could not read the reference image: {0}")]
Internal(rootcause::Report),
}
/// A generated image, as the provider returned it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct GeneratedImage {
/// Encoded image bytes in the format `mime_type` names.
pub bytes: Vec<u8>,
/// IANA media type of `bytes`, e.g. `image/png`.
pub mime_type: String,
/// Intrinsic pixel width of the generated image.
pub width: u32,
/// Intrinsic pixel height of the generated image.
pub height: u32,
/// Any commentary the model produced alongside the image.
pub note: Option<String>,
}
impl GeneratedImage {
/// The Macro file type for `mime_type`; `None` for a media type Macro
/// does not know as an image.
pub fn file_type(&self) -> Option<FileType> {
match self.mime_type.as_str() {
"image/png" => Some(FileType::Png),
"image/jpeg" | "image/jpg" => Some(FileType::Jpg),
"image/webp" => Some(FileType::Webp),
"image/gif" => Some(FileType::Gif),
_ => None,
}
}
}
/// Why an image could not be generated.
#[derive(Debug, thiserror::Error)]
pub enum ImageGenerationError {
/// No provider is configured in this host.
#[error("image generation is not configured")]
Unavailable,
/// The provider declined to render this prompt (safety filters, or the
/// model answered in text instead of an image). The message is written
/// for the agent that asked.
#[error("{0}")]
Refused(String),
/// The provider call failed: transport, authentication, quota, or an
/// unparseable response.
#[error("image provider request failed")]
Provider(#[source] anyhow::Error),
}
/// Longest prompt forwarded to the provider, in bytes.
pub const MAX_PROMPT_BYTES: usize = 8 * 1024;
/// Product limit matching the image model's recommended reference count.
pub const MAX_REFERENCE_IMAGES: usize = 3;
/// Total encoded image bytes before Base64 expansion, below the provider's 20 MB request limit.
pub const MAX_REFERENCE_BYTES: usize = 12 * 1024 * 1024;
/// An image to generate and store as a static file.
pub struct NewGeneratedImage {
/// Natural-language description of the image.
pub prompt: String,
/// Requested shape; the provider default when `None`.
pub aspect_ratio: Option<ImageAspectRatio>,
/// Reference images, resolved under the creating principal before generation.
pub reference_images: Vec<ImageReference>,
}
/// A generated image stored in static file service.
#[derive(Debug)]
pub struct StoredGeneratedImage {
/// Dimension-preserving channel markup composed by the editor service.
pub markdown: String,
/// The stored static file.
pub static_file: StoredImage,
/// IANA media type of the stored bytes.
pub mime_type: String,
/// Number of stored bytes.
pub size_bytes: usize,
/// Intrinsic pixel width of the generated image.
pub width: u32,
/// Intrinsic pixel height of the generated image.
pub height: u32,
/// Any commentary the model produced alongside the image.
pub note: Option<String>,
}
/// Why a generated image was not created.
#[derive(Debug, thiserror::Error)]
pub enum GenerateImageError {
/// The prompt is invalid.
#[error("{0}")]
BadRequest(String),
/// A requested reference image could not be loaded.
#[error(transparent)]
Reference(#[from] ReadImageError),
/// The image could not be generated.
#[error(transparent)]
Generation(#[from] ImageGenerationError),
/// The image was generated but not stored.
#[error(transparent)]
Storage(#[from] SaveImageError),
/// The saved image could not be composed into channel markup.
#[error(transparent)]
Markup(#[from] ComposeImageError),
/// The acting user's AI allowance refused new work.
#[error(transparent)]
Admission(#[from] ai_billing::AiAdmissionError),
/// A team bot with no acting user has no allowance to admit against.
#[error("image generation needs a user to bill; act for a user")]
UserRequired,
}
impl GenerateImageError {
/// Explanation for the caller, without provider or storage diagnostics.
pub fn public_message(&self) -> String {
match self {
Self::BadRequest(message) => message.clone(),
Self::Reference(ReadImageError::Internal(_)) => {
"could not read a reference image; check its ID and access, then retry".to_string()
}
Self::Reference(error) => error.to_string(),
Self::Generation(ImageGenerationError::Unavailable) => {
"image generation is not available in this workspace".to_string()
}
Self::Generation(ImageGenerationError::Refused(reason)) => {
format!("the image model did not return an image: {reason}")
}
Self::Generation(ImageGenerationError::Provider(_)) => {
"the image model request failed; try again shortly".to_string()
}
Self::Markup(_) => {
"the image was saved but its channel markup could not be composed".to_string()
}
Self::Storage(_) => {
"the image was generated but could not be saved to Macro".to_string()
}
Self::Admission(error) => error.to_string(),
Self::UserRequired => self.to_string(),
}
}
}
/// Generated bytes and media type to persist in static file service.
pub struct NewStaticImage {
/// Encoded image bytes.
pub bytes: Vec<u8>,
/// IANA media type of the encoded bytes.
pub mime_type: String,
}
/// A successfully uploaded static image.
#[derive(Debug)]
pub struct StoredImage {
/// Static file ID, reusable as a reference image.
pub id: uuid::Uuid,
/// Permanent URL of the uploaded image.
pub url: String,
}
/// Failure returned by the image-saving capability.
#[derive(Debug, thiserror::Error)]
pub enum SaveImageError {
/// Static file persistence failed.
#[error("could not save the generated image: {0}")]
Internal(rootcause::Report),
}
/// Failure to compose a saved image through the editor service.
#[derive(Debug, thiserror::Error)]
#[error("could not compose image markup: {0}")]
pub struct ComposeImageError(pub rootcause::Report);