import { Doc, FieldType } from '../../../../../fields/Doc'; import { DocData } from '../../../../../fields/DocSymbols'; import { Observation } from '../types/types'; import { ParametersType, ToolInfo, Parameter } from '../types/tool_types'; import { BaseTool } from './BaseTool'; import { DocumentOptions } from '../../../../documents/Documents'; import { CollectionFreeFormDocumentView } from '../../../nodes/CollectionFreeFormDocumentView'; import { v4 as uuidv4 } from 'uuid'; import { LinkManager } from '../../../../util/LinkManager'; import { DocCast, StrCast } from '../../../../../fields/Types'; import { supportedDocTypes } from './CreateDocumentTool'; import { parsedDoc } from '../chatboxcomponents/ChatBox'; // Define the parameters for the DocumentMetadataTool const parameterDefinitions: ReadonlyArray = [ { name: 'action', type: 'string', required: true, description: 'The action to perform: "get" to retrieve metadata, "edit" to modify metadata, "list" to enumerate documents, "getFieldOptions" to retrieve all available field options, or "create" to create a new document', }, { name: 'documentId', type: 'string', required: false, description: 'The ID of the document to get or edit metadata for. Required for "edit", optional for "get", ignored for "list", "getFieldOptions", and "create"', }, { name: 'fieldName', type: 'string', required: false, description: 'The name of the field to edit. Required for single field edits. Ignored if fieldEdits is provided', }, { name: 'fieldValue', type: 'string', required: false, description: 'The new value for the field. Required for single field edits. Can be a string, number, or boolean value depending on the field type', }, { name: 'fieldEdits', type: 'string', required: false, description: 'JSON array of field edits for editing multiple fields at once. Each item should have fieldName and fieldValue. Example: [{"fieldName":"layout_autoHeight","fieldValue":false},{"fieldName":"height","fieldValue":300}]', }, { name: 'title', type: 'string', required: false, description: 'The title of the document to create. Required for "create" action', }, { name: 'data', type: 'string', required: false, description: 'The data content for the document to create. Required for "create" action', }, { name: 'doc_type', type: 'string', required: false, description: `The type of document to create. Required for "create" action. Options: ${Object.keys(supportedDocTypes).join(',')}`, } ] as const; type DocumentMetadataToolParamsType = typeof parameterDefinitions; // Detailed description with usage guidelines for the DocumentMetadataTool const toolDescription = `Extracts and modifies metadata from documents in the same Freeform view as the ChatBox, and can create new documents. This tool helps you work with document properties, understand available fields, edit document metadata, and create new documents. The Dash document system organizes fields in two locations: 1. Layout documents: contain visual properties like position, dimensions, and appearance 2. Data documents: contain the actual content and document-specific data This tool provides the following capabilities: - Get metadata from all documents in the current Freeform view - Get metadata from a specific document - Edit metadata fields on documents (in either layout or data documents) - Edit multiple fields at once (useful for updating dependent fields together) - List all available documents in the current view - Retrieve all available field options with metadata (IMPORTANT: always call this before editing) - Understand which fields are stored where (layout vs data document) - Get detailed information about all available document fields - Support for all value types: strings, numbers, and booleans - Create new documents with basic properties DOCUMENT CREATION: - Use action="create" to create new documents with a simplified approach - Required parameters: title, data, and doc_type - The tool will create the document with sensible defaults and link it to the current view - After creation, you can use the edit action to update its properties IMPORTANT: Before editing any document metadata, first call 'getFieldOptions' to understand: - Which fields are available - The data type of each field - Special dependencies between fields (like layout_autoHeight and height) - Proper naming conventions (with or without underscores) IMPORTANT: Some fields have dependencies that must be handled for edits to work correctly: - When editing "height", first set "layout_autoHeight" to false (as a boolean value, not a string) - When editing "width", first set "layout_autoWidth" to false (as a boolean value, not a string) - Check document metadata to identify other similar dependencies - You can edit dependent fields in a single operation using the fieldEdits parameter Example: To change document height, first disable auto-height: 1. { action: "edit", documentId: "doc123", fieldName: "layout_autoHeight", fieldValue: false } 2. { action: "edit", documentId: "doc123", fieldName: "height", fieldValue: 300 } OR using multi-field edit (recommended for dependent fields): { action: "edit", documentId: "doc123", fieldEdits: [ { fieldName: "layout_autoHeight", fieldValue: false }, { fieldName: "height", fieldValue: 300 } ]}`; // Extensive usage guidelines for the tool const citationRules = `USAGE GUIDELINES: To GET document metadata: - Use action="get" with optional documentId to return metadata for one or all documents - Returns field values, field definitions, and location information (layout vs data document) To GET ALL FIELD OPTIONS (call this first): - Use action="getFieldOptions" to retrieve metadata about all available document fields - No additional parameters are required - Returns structured metadata with field names, types, descriptions, and dependencies - ALWAYS call this before attempting to edit document metadata - Use this information to understand which fields need special handling To CREATE a new document: - Use action="create" with the following required parameters: - title: The title of the document to create - data: The content data for the document (text content, URL, etc.) - doc_type: The type of document to create (text, web, image, etc.) - Example: { action: "create", title: "My Notes", data: "This is the content", doc_type: "text" } - After creation, you can edit the document with more specific properties To EDIT document metadata: - Use action="edit" with required documentId, and either: 1. fieldName + fieldValue for single field edits, OR 2. fieldEdits for updating multiple fields at once - The tool will determine the correct document location automatically - Field names can be provided with or without leading underscores (e.g., both "width" and "_width" work) - Common fields like "width" and "height" are automatically mapped to "_width" and "_height" - All value types are supported: strings, numbers, and booleans - The tool will apply the edit to the correct document (layout or data) based on existing fields SPECIAL FIELD HANDLING: - Text fields: When editing the 'text' field, provide simple plain text Example: { action: "edit", documentId: "doc123", fieldName: "text", fieldValue: "Hello world" } The tool will automatically convert your text to the proper RichTextField format - Width/Height: Set layout_autoHeight/layout_autoWidth to false before editing RECOMMENDED WORKFLOW: 1. First call action="list" to identify available documents 2. Then call action="getFieldOptions" to understand available fields 3. Get document metadata with action="get" to see current values 4. Edit fields with action="edit" using proper dependencies OR 1. Create a new document with action="create" 2. Get its ID from the response 3. Edit the document's properties with action="edit" HANDLING DEPENDENT FIELDS: - When editing some fields, you may need to update related dependent fields - For example, when changing "height", you should also set "layout_autoHeight" to false - Use the fieldEdits parameter to update dependent fields in a single operation (recommended): { action: "edit", documentId: "doc123", fieldEdits: [ { fieldName: "layout_autoHeight", fieldValue: false }, { fieldName: "height", fieldValue: 300 } ]} - Always check for dependent fields that might affect your edits, such as: - height → layout_autoHeight (set to false to allow manual height) - width → layout_autoWidth (set to false to allow manual width) - Other auto-sizing related properties To LIST available documents: - Use action="list" to get a simple list of all documents in the current view - This is useful when you need to identify documents before getting details or editing them Editing fields follows these rules: 1. First checks if the field exists on the layout document using Doc.Get 2. If it exists on the layout document, it's updated there 3. If it has an underscore prefix (_), it's created/updated on the layout document 4. Otherwise, the field is created/updated on the data document 5. Fields with leading underscores are automatically handled correctly Examples: - To get field options: { action: "getFieldOptions" } - To list all documents: { action: "list" } - To get all document metadata: { action: "get" } - To get metadata for a specific document: { action: "get", documentId: "doc123" } - To edit a single field: { action: "edit", documentId: "doc123", fieldName: "backgroundColor", fieldValue: "#ff0000" } - To edit a width property: { action: "edit", documentId: "doc123", fieldName: "width", fieldValue: 300 } - To edit text content: { action: "edit", documentId: "doc123", fieldName: "text", fieldValue: "Simple plain text goes here" } - To disable auto-height: { action: "edit", documentId: "doc123", fieldName: "layout_autoHeight", fieldValue: false } - To create a text document: { action: "create", title: "My Notes", data: "This is my note content", doc_type: "text" } - To create a web document: { action: "create", title: "Google", data: "https://www.google.com", doc_type: "web" } - To edit height with its dependent field together (recommended): { action: "edit", documentId: "doc123", fieldEdits: [ { fieldName: "layout_autoHeight", fieldValue: false }, { fieldName: "height", fieldValue: 200 } ]}`; const documentMetadataToolInfo: ToolInfo = { name: 'documentMetadata', description: toolDescription, parameterRules: parameterDefinitions, citationRules: citationRules, }; /** * A tool for extracting and modifying metadata from documents in a Freeform view. * This tool collects metadata from both layout and data documents in a Freeform view * and allows for editing document fields in the correct location. */ export class DocumentMetadataTool extends BaseTool { private freeformView: any; private chatBox: any; private chatBoxDocument: Doc | null = null; private documentsById: Map = new Map(); private layoutDocsById: Map = new Map(); private dataDocsById: Map = new Map(); private fieldMetadata: Record = {}; private readonly DOCUMENT_ID_FIELD = '_dash_document_id'; constructor(chatBox: any) { super(documentMetadataToolInfo); this.chatBox = chatBox; // Store a direct reference to the ChatBox document if (chatBox && chatBox.Document) { this.chatBoxDocument = chatBox.Document; if (this.chatBoxDocument && this.chatBoxDocument.id) { console.log('DocumentMetadataTool initialized with ChatBox Document:', this.chatBoxDocument.id); } else { console.log('DocumentMetadataTool initialized with ChatBox Document (no ID)'); } } else if (chatBox && chatBox.props && chatBox.props.Document) { this.chatBoxDocument = chatBox.props.Document; if (this.chatBoxDocument && this.chatBoxDocument.id) { console.log('DocumentMetadataTool initialized with ChatBox props.Document:', this.chatBoxDocument.id); } else { console.log('DocumentMetadataTool initialized with ChatBox props.Document (no ID)'); } } else { console.warn('DocumentMetadataTool initialized without valid ChatBox Document reference'); } this.initializeFieldMetadata(); } /** * Extracts field metadata from DocumentOptions class */ private initializeFieldMetadata() { // Parse DocumentOptions to extract field definitions const documentOptionsInstance = new DocumentOptions(); const documentOptionsEntries = Object.entries(documentOptionsInstance); for (const [fieldName, fieldInfo] of documentOptionsEntries) { // Extract field information const fieldData: Record = { name: fieldName, withoutUnderscore: fieldName.startsWith('_') ? fieldName.substring(1) : fieldName, description: '', type: 'unknown', required: false, defaultValue: undefined, possibleValues: [], }; // Check if fieldInfo has description property (it's likely a FInfo instance) if (fieldInfo && typeof fieldInfo === 'object' && 'description' in fieldInfo) { fieldData.description = fieldInfo.description; // Extract field type if available if ('fieldType' in fieldInfo) { fieldData.type = fieldInfo.fieldType; } // Extract possible values if available if ('values' in fieldInfo && Array.isArray(fieldInfo.values)) { fieldData.possibleValues = fieldInfo.values; } } this.fieldMetadata[fieldName] = fieldData; } } /** * Gets all documents in the same Freeform view as the ChatBox * Uses the LinkManager to get all linked documents, similar to how ChatBox does it */ private findDocumentsInFreeformView() { // Reset collections this.documentsById.clear(); this.layoutDocsById.clear(); this.dataDocsById.clear(); try { // Use the LinkManager approach which is proven to work in ChatBox if (this.chatBoxDocument) { console.log('Finding documents linked to ChatBox document with ID:', this.chatBoxDocument.id); // Get directly linked documents via LinkManager const linkedDocs = LinkManager.Instance.getAllRelatedLinks(this.chatBoxDocument) .map(d => DocCast(LinkManager.getOppositeAnchor(d, this.chatBoxDocument!))) .map(d => DocCast(d?.annotationOn, d)) .filter(d => d); console.log(`Found ${linkedDocs.length} linked documents via LinkManager`); // Process the linked documents linkedDocs.forEach((doc: Doc) => { if (doc) { this.processDocument(doc); } }); // Include the ChatBox document itself this.processDocument(this.chatBoxDocument); // If we have access to the Document's parent, try to find sibling documents if (this.chatBoxDocument.parent) { const parent = this.chatBoxDocument.parent; console.log('Found parent document, checking for siblings'); // Check if parent is a Doc type and has a childDocs function if (parent && typeof parent === 'object' && 'childDocs' in parent && typeof parent.childDocs === 'function') { try { const siblingDocs = parent.childDocs(); if (Array.isArray(siblingDocs)) { console.log(`Found ${siblingDocs.length} sibling documents via parent.childDocs()`); siblingDocs.forEach((doc: Doc) => { if (doc) { this.processDocument(doc); } }); } } catch (e) { console.warn('Error accessing parent.childDocs:', e); } } } } else if (this.chatBox && this.chatBox.linkedDocs) { // If we have direct access to the linkedDocs computed property from ChatBox console.log('Using ChatBox.linkedDocs directly'); const linkedDocs = this.chatBox.linkedDocs; if (Array.isArray(linkedDocs)) { console.log(`Found ${linkedDocs.length} documents via ChatBox.linkedDocs`); linkedDocs.forEach((doc: Doc) => { if (doc) { this.processDocument(doc); } }); } // Process the ChatBox document if available if (this.chatBox.Document) { this.processDocument(this.chatBox.Document); } } else { console.warn('No ChatBox document reference available for finding linked documents'); } console.log(`DocumentMetadataTool found ${this.documentsById.size} total documents`); // If we didn't find any documents, try a fallback method if (this.documentsById.size === 0 && this.chatBox) { console.log('No documents found, trying fallback method'); // Try to access any field that might contain documents if (this.chatBox.props && this.chatBox.props.documents) { const documents = this.chatBox.props.documents; if (Array.isArray(documents)) { console.log(`Found ${documents.length} documents via ChatBox.props.documents`); documents.forEach((doc: Doc) => { if (doc) { this.processDocument(doc); } }); } } } } catch (error) { console.error('Error finding documents in Freeform view:', error); } } /** * Process a document by ensuring it has an ID and adding it to the appropriate collections * @param doc The document to process */ private processDocument(doc: Doc) { // Ensure document has a persistent ID const docId = this.ensureDocumentId(doc); // Only add if we haven't already processed this document if (!this.documentsById.has(docId)) { this.documentsById.set(docId, doc); // Get layout doc (the document itself or its layout) const layoutDoc = Doc.Layout(doc); if (layoutDoc) { this.layoutDocsById.set(docId, layoutDoc); } // Get data doc const dataDoc = doc[DocData]; if (dataDoc) { this.dataDocsById.set(docId, dataDoc); } } } /** * Ensures a document has a persistent ID stored in its metadata * @param doc The document to ensure has an ID * @returns The document's ID */ private ensureDocumentId(doc: Doc): string { let docId: string | undefined; // First try to get the ID from our custom field if (doc[this.DOCUMENT_ID_FIELD]) { docId = String(doc[this.DOCUMENT_ID_FIELD]); return docId; } // Try different ways to get a document ID // 1. Try the direct id property if it exists if (doc.id && typeof doc.id === 'string') { docId = doc.id; } // 2. Try doc._id if it exists else if (doc._id && typeof doc._id === 'string') { docId = doc._id; } // 3. Try doc.data?.id if it exists else if (doc.data && typeof doc.data === 'object' && 'id' in doc.data && typeof doc.data.id === 'string') { docId = doc.data.id; } // 4. If none of the above work, generate a UUID else { docId = uuidv4(); console.log(`Generated new UUID for document with title: ${doc.title || 'Untitled'}`); } // Store the ID in the document's metadata so it persists try { doc[this.DOCUMENT_ID_FIELD] = docId; } catch (e) { console.warn(`Could not assign ID to document property`, e); } return docId; } /** * Extracts metadata from a specific document * @param docId The ID of the document to extract metadata from * @returns An object containing the document's metadata */ private extractDocumentMetadata(docId: string) { const doc = this.documentsById.get(docId); if (!doc) { return null; } const layoutDoc = this.layoutDocsById.get(docId); const dataDoc = this.dataDocsById.get(docId); const metadata: Record = { id: docId, title: doc.title || '', type: doc.type || '', fields: { layout: {}, data: {}, }, fieldLocationMap: {}, }; // Process all known field definitions Object.keys(this.fieldMetadata).forEach(fieldName => { const fieldDef = this.fieldMetadata[fieldName]; const strippedName = fieldName.startsWith('_') ? fieldName.substring(1) : fieldName; // Check if field exists on layout document let layoutValue = undefined; if (layoutDoc) { layoutValue = layoutDoc[fieldName]; if (layoutValue !== undefined) { // Field exists on layout document metadata.fields.layout[fieldName] = this.formatFieldValue(layoutValue); metadata.fieldLocationMap[strippedName] = 'layout'; } } // Check if field exists on data document let dataValue = undefined; if (dataDoc) { dataValue = dataDoc[fieldName]; if (dataValue !== undefined) { // Field exists on data document metadata.fields.data[fieldName] = this.formatFieldValue(dataValue); if (!metadata.fieldLocationMap[strippedName]) { metadata.fieldLocationMap[strippedName] = 'data'; } } } // For fields with stripped names (without leading underscore), // also check if they exist on documents without the underscore if (fieldName.startsWith('_')) { const nonUnderscoreFieldName = fieldName.substring(1); if (layoutDoc) { const nonUnderscoreLayoutValue = layoutDoc[nonUnderscoreFieldName]; if (nonUnderscoreLayoutValue !== undefined) { metadata.fields.layout[nonUnderscoreFieldName] = this.formatFieldValue(nonUnderscoreLayoutValue); metadata.fieldLocationMap[nonUnderscoreFieldName] = 'layout'; } } if (dataDoc) { const nonUnderscoreDataValue = dataDoc[nonUnderscoreFieldName]; if (nonUnderscoreDataValue !== undefined) { metadata.fields.data[nonUnderscoreFieldName] = this.formatFieldValue(nonUnderscoreDataValue); if (!metadata.fieldLocationMap[nonUnderscoreFieldName]) { metadata.fieldLocationMap[nonUnderscoreFieldName] = 'data'; } } } } }); // Add common field aliases for easier discovery // This helps users understand both width and _width refer to the same property if (metadata.fields.layout._width !== undefined && metadata.fields.layout.width === undefined) { metadata.fields.layout.width = metadata.fields.layout._width; metadata.fieldLocationMap.width = 'layout'; } if (metadata.fields.layout._height !== undefined && metadata.fields.layout.height === undefined) { metadata.fields.layout.height = metadata.fields.layout._height; metadata.fieldLocationMap.height = 'layout'; } return metadata; } /** * Edits a specific field on a document * @param docId The ID of the document to edit * @param fieldName The name of the field to edit * @param fieldValue The new value for the field (string, number, or boolean) * @returns Object with success status, message, and additional information */ private editDocumentField(docId: string, fieldName: string, fieldValue: string | number | boolean): { success: boolean; message: string; fieldName?: string; originalFieldName?: string; newValue?: any; warning?: string; } { // Normalize field name (handle with/without underscore) let normalizedFieldName = fieldName.startsWith('_') ? fieldName : fieldName; const strippedFieldName = fieldName.startsWith('_') ? fieldName.substring(1) : fieldName; // Handle common field name aliases (width → _width, height → _height) // Many document fields use '_' prefix for layout properties if (fieldName === 'width') { normalizedFieldName = '_width'; } else if (fieldName === 'height') { normalizedFieldName = '_height'; } // Get the documents const doc = this.documentsById.get(docId); if (!doc) { return { success: false, message: `Document with ID ${docId} not found` }; } const layoutDoc = this.layoutDocsById.get(docId); const dataDoc = this.dataDocsById.get(docId); if (!layoutDoc && !dataDoc) { return { success: false, message: `Could not find layout or data document for document with ID ${docId}` }; } try { // Convert the field value to the appropriate type based on field metadata const convertedValue = this.convertFieldValue(normalizedFieldName, fieldValue); let targetDoc: Doc | undefined; let targetLocation: string; // First, check if field exists on layout document using Doc.Get if (layoutDoc) { const fieldExistsOnLayout = Doc.Get(layoutDoc, normalizedFieldName, true) !== undefined; // If it exists on layout document, update it there if (fieldExistsOnLayout) { targetDoc = layoutDoc; targetLocation = 'layout'; } // If it has an underscore prefix, it's likely a layout property even if not yet set else if (normalizedFieldName.startsWith('_')) { targetDoc = layoutDoc; targetLocation = 'layout'; } // Otherwise, look for or create on data document else if (dataDoc) { targetDoc = dataDoc; targetLocation = 'data'; } // If no data document available, default to layout else { targetDoc = layoutDoc; targetLocation = 'layout'; } } // If no layout document, use data document else if (dataDoc) { targetDoc = dataDoc; targetLocation = 'data'; } else { return { success: false, message: `No valid document found for editing` }; } if (!targetDoc) { return { success: false, message: `Target document not available` }; } // Set the field value on the target document targetDoc[normalizedFieldName] = convertedValue; return { success: true, message: `Successfully updated field '${normalizedFieldName}' on ${targetLocation} document (ID: ${docId})`, fieldName: normalizedFieldName, originalFieldName: fieldName, newValue: convertedValue }; } catch (error) { console.error('Error editing document field:', error); return { success: false, message: `Error updating field: ${error instanceof Error ? error.message : String(error)}` }; } } /** * Converts a string field value to the appropriate type based on field metadata * @param fieldName The name of the field * @param fieldValue The string value to convert * @returns The converted value with the appropriate type */ private convertFieldValue(fieldName: string, fieldValue: any): any { // If fieldValue is already a number or boolean, we don't need to convert it from string if (typeof fieldValue === 'number' || typeof fieldValue === 'boolean') { return fieldValue; } // If fieldValue is a string "true" or "false", convert to boolean if (typeof fieldValue === 'string') { if (fieldValue.toLowerCase() === 'true') { return true; } if (fieldValue.toLowerCase() === 'false') { return false; } } // If fieldValue is not a string (and not a number or boolean), convert it to string if (typeof fieldValue !== 'string') { fieldValue = String(fieldValue); } // Special handling for text field - convert to proper RichTextField format if (fieldName === 'text') { try { // Check if it's already a valid JSON RichTextField JSON.parse(fieldValue); return fieldValue; } catch (e) { // It's a plain text string, so convert it to RichTextField format const rtf = { doc: { type: 'doc', content: [ { type: 'paragraph', content: [ { type: 'text', text: fieldValue, }, ], }, ], }, }; return JSON.stringify(rtf); } } // Get field metadata const normalizedFieldName = fieldName.startsWith('_') ? fieldName : `_${fieldName}`; const strippedFieldName = fieldName.startsWith('_') ? fieldName.substring(1) : fieldName; // Check both versions of the field name in metadata const fieldMeta = this.fieldMetadata[normalizedFieldName] || this.fieldMetadata[strippedFieldName]; // Special handling for width and height without metadata if (!fieldMeta && (fieldName === '_width' || fieldName === '_height' || fieldName === 'width' || fieldName === 'height')) { const num = Number(fieldValue); return isNaN(num) ? fieldValue : num; } if (!fieldMeta) { // If no metadata found, just return the string value return fieldValue; } // Convert based on field type const fieldType = fieldMeta.type; if (fieldType === 'boolean') { // Convert to boolean return fieldValue.toLowerCase() === 'true'; } else if (fieldType === 'number') { // Convert to number const num = Number(fieldValue); return isNaN(num) ? fieldValue : num; } else if (fieldType === 'date') { // Try to convert to date (stored as number timestamp) try { return new Date(fieldValue).getTime(); } catch (e) { return fieldValue; } } else if (fieldType.includes('list') || fieldType.includes('array')) { // Try to parse as JSON array try { return JSON.parse(fieldValue); } catch (e) { return fieldValue; } } else if (fieldType === 'json' || fieldType === 'object') { // Try to parse as JSON object try { return JSON.parse(fieldValue); } catch (e) { return fieldValue; } } // Default to string return fieldValue; } /** * Formats a field value for JSON output * @param value The field value to format * @returns A JSON-friendly representation of the field value */ private formatFieldValue(value: any): any { if (value === undefined || value === null) { return null; } // Handle Doc objects if (value instanceof Doc) { return { type: 'Doc', id: value.id || this.ensureDocumentId(value), title: value.title || '', docType: value.type || '', }; } // Handle RichTextField (try to extract plain text) if (typeof value === 'string' && value.includes('"type":"doc"') && value.includes('"content":')) { try { const rtfObj = JSON.parse(value); // If this looks like a rich text field structure if (rtfObj.doc && rtfObj.doc.content) { // Recursively extract text from the content let plainText = ''; const extractText = (node: any) => { if (node.text) { plainText += node.text; } if (node.content && Array.isArray(node.content)) { node.content.forEach((child: any) => extractText(child)); } }; extractText(rtfObj.doc); // If we successfully extracted text, show it, but also preserve the original value if (plainText) { return { type: 'RichText', text: plainText, length: plainText.length, // Don't include the full value as it can be very large }; } } } catch (e) { // If parsing fails, just treat as a regular string } } // Handle arrays and complex objects if (typeof value === 'object') { // If the object has a toString method, use it if (value.toString && value.toString !== Object.prototype.toString) { return value.toString(); } try { // Try to convert to JSON string return JSON.stringify(value); } catch (e) { return '[Complex Object]'; } } // Return primitive values as is return value; } /** * Extracts all field metadata from DocumentOptions * @returns A structured object containing metadata about all available document fields */ private getAllFieldMetadata() { // Start with our already populated fieldMetadata from the DocumentOptions class const result: Record = { fieldCount: Object.keys(this.fieldMetadata).length, fields: {}, fieldsByType: { string: [], number: [], boolean: [], doc: [], list: [], date: [], enumeration: [], other: [] }, fieldNameMappings: {}, commonFields: { appearance: [], position: [], size: [], content: [], behavior: [], layout: [] } }; // Process each field in the metadata Object.entries(this.fieldMetadata).forEach(([fieldName, fieldInfo]) => { const strippedName = fieldName.startsWith('_') ? fieldName.substring(1) : fieldName; // Add to fieldNameMappings if (fieldName.startsWith('_')) { result.fieldNameMappings[strippedName] = fieldName; } // Create structured field metadata const fieldData: Record = { name: fieldName, displayName: strippedName, description: fieldInfo.description || '', type: fieldInfo.fieldType || 'unknown', possibleValues: fieldInfo.values || [], }; // Add field to fields collection result.fields[fieldName] = fieldData; // Categorize by field type const type = fieldInfo.fieldType?.toLowerCase() || 'unknown'; if (type === 'string') { result.fieldsByType.string.push(fieldName); } else if (type === 'number') { result.fieldsByType.number.push(fieldName); } else if (type === 'boolean') { result.fieldsByType.boolean.push(fieldName); } else if (type === 'doc') { result.fieldsByType.doc.push(fieldName); } else if (type === 'list') { result.fieldsByType.list.push(fieldName); } else if (type === 'date') { result.fieldsByType.date.push(fieldName); } else if (type === 'enumeration') { result.fieldsByType.enumeration.push(fieldName); } else { result.fieldsByType.other.push(fieldName); } // Categorize by field purpose if (fieldName.includes('width') || fieldName.includes('height') || fieldName.includes('size')) { result.commonFields.size.push(fieldName); } else if (fieldName.includes('color') || fieldName.includes('background') || fieldName.includes('border')) { result.commonFields.appearance.push(fieldName); } else if (fieldName.includes('x') || fieldName.includes('y') || fieldName.includes('position') || fieldName.includes('pan')) { result.commonFields.position.push(fieldName); } else if (fieldName.includes('text') || fieldName.includes('title') || fieldName.includes('data')) { result.commonFields.content.push(fieldName); } else if (fieldName.includes('action') || fieldName.includes('click') || fieldName.includes('event')) { result.commonFields.behavior.push(fieldName); } else if (fieldName.includes('layout')) { result.commonFields.layout.push(fieldName); } }); // Add special section for auto-sizing related fields result.autoSizingFields = { height: { autoHeightField: '_layout_autoHeight', heightField: '_height', displayName: 'height', usage: 'To manually set height, first set layout_autoHeight to false' }, width: { autoWidthField: '_layout_autoWidth', widthField: '_width', displayName: 'width', usage: 'To manually set width, first set layout_autoWidth to false' } }; // Add special section for text field format result.specialFields = { text: { name: 'text', description: 'Document text content', format: 'RichTextField', note: 'When setting text, provide plain text - it will be automatically converted to the correct format', example: 'For setting: "Hello world" (plain text); For getting: Will be converted to plaintext for display' } }; return result; } /** * Executes the document metadata tool * @param args The arguments for the tool * @returns An observation with the results of the tool execution */ async execute(args: ParametersType): Promise { console.log('DocumentMetadataTool: Executing with args:', args); // Find all documents in the Freeform view this.findDocumentsInFreeformView(); try { // Validate required input parameters based on action if (!this.inputValidator(args)) { return [{ type: 'text', text: `Error: Invalid or missing parameters for action "${args.action}". ${this.getParameterRequirementsByAction(String(args.action))}` }]; } // Ensure the action is valid and convert to string const action = String(args.action); if (!['get', 'edit', 'list', 'getFieldOptions', 'create'].includes(action)) { return [{ type: 'text', text: 'Error: Invalid action. Valid actions are "get", "edit", "list", "getFieldOptions", or "create".' }]; } // Safely convert documentId to string or undefined const documentId = args.documentId ? String(args.documentId) : undefined; // Perform the specified action switch (action) { case 'get': { // Get metadata for a specific document or all documents const result = this.getDocumentMetadata(documentId); console.log('DocumentMetadataTool: Get metadata result:', result); return [{ type: 'text', text: `Document metadata ${documentId ? 'for document ' + documentId : ''} retrieved successfully:\n${JSON.stringify(result, null, 2)}` }]; } case 'edit': { // Edit a specific field on a document if (!documentId) { return [{ type: 'text', text: 'Error: Document ID is required for edit actions.' }]; } // Ensure document exists if (!this.documentsById.has(documentId)) { return [{ type: 'text', text: `Error: Document with ID ${documentId} not found.` }]; } // Check if we're doing a multi-field edit or a single field edit if (args.fieldEdits) { try { // Parse fieldEdits array const edits = JSON.parse(String(args.fieldEdits)); if (!Array.isArray(edits) || edits.length === 0) { return [{ type: 'text', text: 'Error: fieldEdits must be a non-empty array of field edits.' }]; } // Track results for all edits const results: { success: boolean; message: string; fieldName?: string; originalFieldName?: string; newValue?: any; warning?: string; }[] = []; let allSuccessful = true; // Process each edit for (const edit of edits) { // Get fieldValue in its original form let fieldValue = edit.fieldValue; // Only convert to string if it's neither boolean nor number if (typeof fieldValue !== 'boolean' && typeof fieldValue !== 'number') { fieldValue = String(fieldValue); } const fieldName = String(edit.fieldName); // Edit the field const result = this.editDocumentField( documentId, fieldName, fieldValue ); console.log(`DocumentMetadataTool: Edit field result for ${fieldName}:`, result); // Add to results results.push(result); // Update success status if (!result.success) { allSuccessful = false; } } // Format response based on results let responseText = ''; if (allSuccessful) { responseText = `Successfully edited ${results.length} fields on document ${documentId}:\n`; results.forEach(result => { responseText += `- Field '${result.originalFieldName}': updated to ${JSON.stringify(result.newValue)}\n`; // Add any warnings if (result.warning) { responseText += ` Warning: ${result.warning}\n`; } }); } else { responseText = `Errors occurred while editing fields on document ${documentId}:\n`; results.forEach(result => { if (result.success) { responseText += `- Field '${result.originalFieldName}': updated to ${JSON.stringify(result.newValue)}\n`; // Add any warnings if (result.warning) { responseText += ` Warning: ${result.warning}\n`; } } else { responseText += `- Error editing '${result.originalFieldName}': ${result.message}\n`; } }); } // Get the updated metadata to return const updatedMetadata = this.getDocumentMetadata(documentId); return [{ type: 'text', text: `${responseText}\nUpdated metadata:\n${JSON.stringify(updatedMetadata, null, 2)}` }]; } catch (error) { return [{ type: 'text', text: `Error processing fieldEdits: ${error instanceof Error ? error.message : String(error)}` }]; } } else { // Single field edit (original behavior) if (!args.fieldName) { return [{ type: 'text', text: 'Error: Field name and field value are required for edit actions.' }]; } // Get fieldValue in its original form - we'll handle conversion in editDocumentField let fieldValue = args.fieldValue; // Only convert to string if it's neither boolean nor number if (typeof fieldValue !== 'boolean' && typeof fieldValue !== 'number') { fieldValue = String(fieldValue); } const fieldName = String(args.fieldName); // Edit the field const result = this.editDocumentField( documentId, fieldName, fieldValue ); console.log('DocumentMetadataTool: Edit field result:', result); if (!result.success) { return [{ type: 'text', text: result.message }]; } // Include warning if present let responseText = result.message; if (result.warning) { responseText += `\n\n${result.warning}`; } // Get the updated metadata to return const updatedMetadata = this.getDocumentMetadata(documentId); return [{ type: 'text', text: `${responseText}\nUpdated metadata:\n${JSON.stringify(updatedMetadata, null, 2)}` }]; } } case 'list': { // List all available documents in simple format const docs = Array.from(this.documentsById.entries()).map(([id, doc]) => ({ id, title: doc.title || 'Untitled Document', type: doc.type || 'Unknown Type' })); if (docs.length === 0) { return [{ type: 'text', text: 'No documents found in the current view.' }]; } return [{ type: 'text', text: `Found ${docs.length} document(s) in the current view:\n${JSON.stringify(docs, null, 2)}` }]; } case 'getFieldOptions': { // Get all available field options with metadata const fieldOptions = this.getAllFieldMetadata(); return [{ type: 'text', text: `Document field options retrieved successfully.\nThis information should be consulted before editing document fields to understand available options and dependencies:\n${JSON.stringify(fieldOptions, null, 2)}` }]; } case 'create': { // Create a new document if (!args.title || !args.data || !args.doc_type) { return [{ type: 'text', text: 'Error: Title, data, and doc_type are required for create action.' }]; } const docType = String(args.doc_type); const title = String(args.title); const data = String(args.data); // Validate doc_type if (!this.isValidDocType(docType)) { return [{ type: 'text', text: `Error: Invalid doc_type. Valid options are: ${Object.keys(supportedDocTypes).join(',')}` }]; } try { // Create simple document with just title and data const simpleDoc: parsedDoc = { doc_type: docType, title: title, data: data, x: 0, y: 0, _width: 300, _height: 300, _layout_fitWidth: false, _layout_autoHeight: true }; // Use the chatBox's createDocInDash method to create and link the document if (!this.chatBox || !this.chatBox.createDocInDash) { return [{ type: 'text', text: 'Error: Could not access document creation functionality.' }]; } const createdDoc = this.chatBox.createDocInDash(simpleDoc); if (!createdDoc) { return [{ type: 'text', text: 'Error: Failed to create document.' }]; } // Update our local document maps with the new document this.processDocument(createdDoc); // Get the created document's metadata const createdMetadata = this.getDocumentMetadata(createdDoc.id); return [{ type: 'text', text: `Document created successfully. Document ID: ${createdDoc.id} Type: ${docType} Title: "${title}" The document has been created with default dimensions and positioning. You can now use the "edit" action to modify additional properties of this document. Next steps: 1. Use the "getFieldOptions" action to understand available editable/addable fields/properties and their dependencies. 2. To modify this document, use: { action: "edit", documentId: "${createdDoc.id}", fieldName: "property", fieldValue: "value" } 3. To add styling, consider setting backgroundColor, fontColor, or other properties 4. For text documents, you can edit the content with: { action: "edit", documentId: "${createdDoc.id}", fieldName: "text", fieldValue: "New content" } Full metadata for the created document: ${JSON.stringify(createdMetadata, null, 2)}` }]; } catch (error) { return [{ type: 'text', text: `Error creating document: ${error instanceof Error ? error.message : String(error)}` }]; } } default: return [{ type: 'text', text: 'Error: Unknown action. Valid actions are "get", "edit", "list", "getFieldOptions", or "create".' }]; } } catch (error) { console.error('DocumentMetadataTool execution error:', error); return [{ type: 'text', text: `Error executing DocumentMetadataTool: ${error instanceof Error ? error.message : String(error)}` }]; } } /** * Validates the input parameters for the DocumentMetadataTool * This custom validator allows numbers and booleans to be passed for fieldValue * while maintaining compatibility with the standard validation * * @param params The parameters to validate * @returns True if the parameters are valid, false otherwise */ inputValidator(params: ParametersType): boolean { // Default validation for required fields if (params.action === undefined) { return false; } // For create action, validate required parameters if (params.action === 'create') { return !!(params.title && params.data && params.doc_type); } // For edit action, validate either single field edit or multiple field edits if (params.action === 'edit') { // If fieldEdits is provided, it must be valid and we'll ignore fieldName/fieldValue if (params.fieldEdits) { try { // Parse fieldEdits and validate its structure const edits = JSON.parse(String(params.fieldEdits)); // Ensure it's an array if (!Array.isArray(edits)) { console.log('fieldEdits is not an array'); return false; } // Ensure each item has fieldName and fieldValue for (const edit of edits) { if (!edit.fieldName) { console.log('An edit is missing fieldName'); return false; } if (edit.fieldValue === undefined) { console.log('An edit is missing fieldValue'); return false; } } // Everything looks good with fieldEdits return !!params.documentId; // Just ensure documentId is provided } catch (error) { console.log('Error parsing fieldEdits:', error); return false; } } else { // Traditional single field edit if (!params.documentId || !params.fieldName || params.fieldValue === undefined) { return false; } } } // For get action with documentId, documentId is required if (params.action === 'get' && params.documentId === '') { return false; } // getFieldOptions action doesn't require any additional parameters if (params.action === 'getFieldOptions') { return true; } // list action doesn't require any additional parameters if (params.action === 'list') { return true; } // Allow for numeric or boolean fieldValue even though the type is defined as string if (params.fieldValue !== undefined) { if (typeof params.fieldValue === 'number') { console.log('Numeric fieldValue detected, will be converted to string'); // We'll convert it later, so don't fail validation return true; } if (typeof params.fieldValue === 'boolean') { console.log('Boolean fieldValue detected, will be converted appropriately'); // We'll handle boolean conversion in the execute method return true; } } return true; } /** * Returns the parameter requirements for a specific action * @param action The action to get requirements for * @returns A string describing the required parameters */ private getParameterRequirementsByAction(action?: string): string { if (!action) { return 'Please specify an action: "get", "edit", "list", "getFieldOptions", or "create".'; } switch (action.toLowerCase()) { case 'get': return 'The "get" action accepts an optional documentId parameter.'; case 'edit': return 'The "edit" action requires documentId, fieldName, and fieldValue parameters, or documentId and fieldEdits parameters for multi-field edits.'; case 'list': return 'The "list" action does not require any additional parameters.'; case 'getFieldOptions': return 'The "getFieldOptions" action does not require any additional parameters. It returns metadata about all available document fields.'; case 'create': return 'The "create" action requires title, data, and doc_type parameters.'; default: return `Unknown action "${action}". Valid actions are "get", "edit", "list", "getFieldOptions", or "create".`; } } /** * Gets metadata for a specific document or all documents * @param documentId Optional ID of a specific document to get metadata for * @returns Document metadata or metadata for all documents */ private getDocumentMetadata(documentId?: string): any { if (documentId) { // Get metadata for a specific document return this.extractDocumentMetadata(documentId); } else { // Get metadata for all documents const documentsMetadata: Record = {}; for (const docId of this.documentsById.keys()) { documentsMetadata[docId] = this.extractDocumentMetadata(docId); } return { documentCount: this.documentsById.size, documents: documentsMetadata, fieldDefinitions: this.fieldMetadata }; } } /** * Helper method to validate a document type and ensure it's a valid supportedDocType * @param docType The document type to validate * @returns True if the document type is valid, false otherwise */ private isValidDocType(docType: string): boolean { return Object.values(supportedDocTypes).includes(docType as supportedDocTypes); } }