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.

16.2 KB
Raw Blame
//! ReadContent tool for reading document content.

use ai_toolset::{ToolAnnotated, ToolAnnotations};
use std::str::FromStr;

use crate::domain::{
    comments::DocumentDiscussion,
    models::LocationQueryParams,
    ports::{DocumentService, create::DocumentCreationService, editing::EditingWorkerService},
    response::LocationResponseV3,
};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use async_trait::async_trait;
use entity_access::domain::{
    models::{EntityAccessReceipt, EntityType, ViewAccessLevel},
    ports::EntityAccessService,
};
use model::document::DocumentBasic;
use model_file_type::{FileAssociation, FileType};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

use super::DocumentToolContext;

/// A single node of a markdown document as seen by the AI.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum MarkdownNode {
    /// A textual content node (paragraph, heading, list, code block, etc.).
    #[serde(rename_all = "camelCase")]
    Generic {
        /// The node id
        node_id: String,
        /// Human readable content
        content: String,
        /// The style on the node, h1, paragraph, code, etc.
        tag: String,
    },
    /// An image hosted at a publicly fetchable URL. Fetch the URL to view it.
    StaticImage {
        /// URL the image can be fetched from.
        url: String,
    },
    /// An image stored in DSS. Pass this id to the read tool to view the image.
    DssImage {
        /// The DSS id of the image. Use the read tool with this id to read it.
        id: String,
    },
}

impl From<lexical_client::types::NewMdNode> for MarkdownNode {
    fn from(value: lexical_client::types::NewMdNode) -> Self {
        use lexical_client::types::NewMdNode;
        match value {
            NewMdNode::Generic(node) => MarkdownNode::Generic {
                node_id: node.node_id,
                content: node.content,
                tag: node.tag,
            },
            NewMdNode::StaticImage { url } => MarkdownNode::StaticImage { url },
            NewMdNode::DssImage { id } => MarkdownNode::DssImage { id },
        }
    }
}

/// The content of the document
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub enum Content {
    /// Simple text content
    Text(String),
    /// All nodes of the markdown file
    Markdown(Vec<MarkdownNode>),
    /// The file is binary or too large to return inline. Fetch the URL to download it.
    #[serde(rename_all = "camelCase")]
    Download {
        /// Short-lived URL the raw file can be downloaded from.
        url: String,
    },
}

/// Files of an unsupported or unknown type are returned inline only when they
/// are UTF-8 text no larger than this; anything else is returned as a download URL.
const MAX_INLINE_TEXT_BYTES: usize = 512 * 1024;

#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ReadContentResponse {
    /// The content of the document
    pub content: Content,
    /// The comment threads on the document, oldest first: inline comments
    /// with the text they are on, and Discussion comments on the whole
    /// document. Each thread lists its first comment followed by the replies.
    pub comments: Vec<DocumentDiscussion>,
}

#[derive(Debug, Deserialize, JsonSchema, Clone, Default)]
#[serde(rename_all = "camelCase")]
#[schemars(
    title = "ReadContent",
    description = "Retrieve a document's content and its comment threads, including inline comments with the text they are on, Discussion comments, replies and resolved state."
)]
pub struct ReadContent {
    #[schemars(description = "The id of the document you want to retrieve content for.")]
    pub document_id: Uuid,
}

impl ToolAnnotated for ReadContent {
    const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("Read document");
}

#[async_trait]
impl<DSvc, ESvc, EDSvc> AsyncTool<DocumentToolContext<DSvc, ESvc, EDSvc>> for ReadContent
where
    DSvc: DocumentService + DocumentCreationService,
    ESvc: EntityAccessService,
    EDSvc: EditingWorkerService,
{
    type Output = ReadContentResponse;

    #[tracing::instrument(skip_all, fields(user_id=?request_context.user_id, document_id=?self.document_id), err)]
    async fn call(
        &self,
        service_context: ServiceContext<DocumentToolContext<DSvc, ESvc, EDSvc>>,
        request_context: RequestContext,
    ) -> ToolResult<Self::Output> {
        tracing::info!(params=?self, "Read metadata");

        // System skills are static, code-defined content with well-known ids
        // rather than documents; serve them before any document lookup or
        // access check (they are visible to every user).
        if let Some(skill) = system_skills::system_skill(self.document_id) {
            return Ok(ReadContentResponse {
                content: Content::Text(skill.render_content()),
                comments: Vec::new(),
            });
        }

        // Get EntityAccessReceipt
        let entity_access_receipt = service_context
            .entity_access_service
            .generate_entity_access_receipt(
                &request_context.user_id,
                None,
                &self.document_id.to_string(),
                EntityType::Document,
            )
            .await
            .map_err(|e| ToolCallError {
                description: "unable to get the entity access receipt".to_string(),
                internal_error: e.into(),
            })?;

        // SAFETY: This is allowed because we have the entity_access_receipt call right above to
        // ensure the user has access.
        let document_context = service_context
            .service
            .internal_get_basic_document(&self.document_id.to_string())
            .await
            .map_err(|e| ToolCallError {
                description: "unable to get the document context".to_string(),
                internal_error: e.into(),
            })?;

        let file_type = document_context
            .file_type
            .as_deref()
            .and_then(|file_type| FileType::from_str(file_type).ok());

        let content: Content = if file_type == Some(FileType::Spreadsheet) {
            let result = service_context
                .spreadsheet
                .read(
                    entity_access_receipt.clone(),
                    &request_context.user_id,
                    service_context.actor.into_storage_id().as_ref(),
                    crate::domain::spreadsheet::SpreadsheetRequest::Read {
                        sheet_id: None,
                        ranges: None,
                        include_styles: None,
                    },
                )
                .await
                .map_err(|e| ToolCallError {
                    description: e.to_string(),
                    internal_error: e,
                })?;
            Content::Text(serde_json::to_string(&result).map_err(|e| ToolCallError {
                description: "unable to serialize spreadsheet overview".to_string(),
                internal_error: e.into(),
            })?)
        } else if file_type == Some(FileType::Pptx) {
            // Slides, shape ids, and text as ReadPresentation describes them.
            Content::Text(
                service_context
                    .presentations
                    .read(entity_access_receipt.clone(), None)
                    .await
                    .map_err(|e| ToolCallError {
                        description: format!("unable to read the presentation: {e:#}"),
                        internal_error: e,
                    })?,
            )
        } else if file_type == Some(FileType::Fig) {
            // Pages, frames, text, and components as ReadDesign describes them.
            Content::Text(
                service_context
                    .designs
                    .read(entity_access_receipt.clone(), None)
                    .await
                    .map_err(|e| ToolCallError {
                        description: format!("unable to read the design: {e:#}"),
                        internal_error: e,
                    })?,
            )
        } else if matches!(file_type, Some(FileType::Psd | FileType::Psb)) {
            // The canvas, layers, and text as ReadPhotoshopDocument describes them.
            Content::Text(
                service_context
                    .photoshop_documents
                    .read(entity_access_receipt.clone())
                    .await
                    .map_err(|e| ToolCallError {
                        description: format!("unable to read the Photoshop document: {e:#}"),
                        internal_error: e,
                    })?,
            )
        } else if file_type == Some(FileType::Ai) {
            // Artboards, layers, and text as ReadIllustratorDocument describes them.
            Content::Text(
                service_context
                    .illustrator_documents
                    .read(entity_access_receipt.clone())
                    .await
                    .map_err(|e| ToolCallError {
                        description: format!("unable to read the Illustrator document: {e:#}"),
                        internal_error: e,
                    })?,
            )
        } else {
            match file_type.map(|file_type| file_type.macro_app_path()) {
                Some(FileAssociation::Pdf(_)) | Some(FileAssociation::Write(_)) => Content::Text(
                    service_context
                        .service
                        .get_document_text(entity_access_receipt.clone())
                        .await
                        .map_err(|e| ToolCallError {
                            description: "unable to get document text".to_string(),
                            internal_error: e.into(),
                        })?,
                ),
                Some(FileAssociation::Md(_)) => Content::Markdown(
                    service_context
                        .lexical_client
                        .parse_cognition_v2(&self.document_id.to_string())
                        .await
                        .map_err(|e| ToolCallError {
                            description: "unable to parse markdown".to_string(),
                            internal_error: e,
                        })?
                        .data
                        .into_iter()
                        .map(|i| i.into())
                        .collect(),
                ),
                Some(FileAssociation::Code(_)) | Some(FileAssociation::Document(_)) => {
                    Content::Text(
                        get_document_content_from_location(
                            service_context.clone(),
                            &document_context,
                            entity_access_receipt.clone(),
                        )
                        .await
                        .map_err(|e| ToolCallError {
                            description: "unable to get document content using location"
                                .to_string(),
                            internal_error: e,
                        })?,
                    )
                }
                _ => get_document_inline_text_or_download(
                    service_context.clone(),
                    &document_context,
                    entity_access_receipt.clone(),
                )
                .await
                .map_err(|e| ToolCallError {
                    description: "unable to download document".to_string(),
                    internal_error: e,
                })?,
            }
        };

        let comments = service_context
            .comments
            .discussions(entity_access_receipt)
            .await
            .map_err(|e| ToolCallError {
                description: "unable to get document comments".to_string(),
                internal_error: e.into(),
            })?;

        Ok(ReadContentResponse { content, comments })
    }
}

/// Gets the presigned download url for a document stored as a single file
async fn get_document_presigned_url<
    DSvc: DocumentService + DocumentCreationService,
    ESvc: EntityAccessService,
    EDSvc: EditingWorkerService,
>(
    service_context: ServiceContext<DocumentToolContext<DSvc, ESvc, EDSvc>>,
    document_context: &DocumentBasic,
    entity_access_receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> anyhow::Result<String> {
    let location = service_context
        .service
        .get_document_location(
            document_context,
            entity_access_receipt,
            LocationQueryParams {
                get_converted_docx_url: Some(true),
                document_version_id: None,
            },
        )
        .await?;

    match location {
        LocationResponseV3::PresignedUrl {
            presigned_url,
            metadata: _metadata,
            content: _content,
        } => Ok(presigned_url),
        // This should only be called with single-file documents which result in 1 presigned url
        _ => unreachable!(),
    }
}

/// Gets the document content from location
#[tracing::instrument(skip(service_context), err)]
async fn get_document_content_from_location<
    DSvc: DocumentService + DocumentCreationService,
    ESvc: EntityAccessService,
    EDSvc: EditingWorkerService,
>(
    service_context: ServiceContext<DocumentToolContext<DSvc, ESvc, EDSvc>>,
    document_context: &DocumentBasic,
    entity_access_receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> anyhow::Result<String> {
    let presigned_url =
        get_document_presigned_url(service_context, document_context, entity_access_receipt)
            .await?;

    // Download the file and convert to UTF8
    let response = reqwest::get(&presigned_url).await?;

    if !response.status().is_success() {
        anyhow::bail!("Failed to download document: HTTP {}", response.status());
    }

    let bytes = response.bytes().await?;
    let content = String::from_utf8(bytes.to_vec())
        .map_err(|e| anyhow::anyhow!("Document content is not valid UTF-8: {e}"))?;

    Ok(content)
}

/// Reads a document of an unknown or unsupported file type: small UTF-8 files are
/// returned as text, and everything else as a url the caller can download it from.
#[tracing::instrument(skip(service_context), err)]
async fn get_document_inline_text_or_download<
    DSvc: DocumentService + DocumentCreationService,
    ESvc: EntityAccessService,
    EDSvc: EditingWorkerService,
>(
    service_context: ServiceContext<DocumentToolContext<DSvc, ESvc, EDSvc>>,
    document_context: &DocumentBasic,
    entity_access_receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> anyhow::Result<Content> {
    let presigned_url =
        get_document_presigned_url(service_context, document_context, entity_access_receipt)
            .await?;

    let mut response = reqwest::get(&presigned_url).await?;

    if !response.status().is_success() {
        anyhow::bail!("Failed to download document: HTTP {}", response.status());
    }

    let mut bytes = Vec::new();
    while let Some(chunk) = response.chunk().await? {
        bytes.extend_from_slice(&chunk);
        if bytes.len() > MAX_INLINE_TEXT_BYTES {
            return Ok(Content::Download { url: presigned_url });
        }
    }

    Ok(inline_text_or_download(bytes, presigned_url))
}

fn inline_text_or_download(bytes: Vec<u8>, url: String) -> Content {
    if bytes.len() > MAX_INLINE_TEXT_BYTES {
        return Content::Download { url };
    }
    match String::from_utf8(bytes) {
        Ok(text) => Content::Text(text),
        Err(_) => Content::Download { url },
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    const URL: &str = "https://example.com/file";

    #[test]
    fn small_utf8_file_is_returned_as_text() {
        let content = inline_text_or_download(b"{\"traceEvents\":[]}".to_vec(), URL.to_string());
        assert!(matches!(content, Content::Text(text) if text == "{\"traceEvents\":[]}"));
    }

    #[test]
    fn binary_file_is_returned_as_download_url() {
        let content = inline_text_or_download(vec![0x1f, 0x8b, 0x08, 0xff], URL.to_string());
        assert!(matches!(content, Content::Download { url } if url == URL));
    }

    #[test]
    fn oversized_text_file_is_returned_as_download_url() {
        let content =
            inline_text_or_download(vec![b'a'; MAX_INLINE_TEXT_BYTES + 1], URL.to_string());
        assert!(matches!(content, Content::Download { url } if url == URL));
    }
}