Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

8.8 KB
Raw Blame
//! 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);