path: root/src/client/views/nodes/chatbot/tools/DocumentMetadataTool.ts

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<Parameter> = [
    {
        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<DocumentMetadataToolParamsType> = {
    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<DocumentMetadataToolParamsType> {
    private freeformView: any;
    private chatBox: any;
    private chatBoxDocument: Doc | null = null;
    private documentsById: Map<string, Doc> = new Map();
    private layoutDocsById: Map<string, Doc> = new Map();
    private dataDocsById: Map<string, Doc> = new Map();
    private fieldMetadata: Record<string, any> = {};
    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<string, any> = {
                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<string, any> = {
            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<string, any> = {
            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<string, any> = {
                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<DocumentMetadataToolParamsType>): Promise<Observation[]> {
        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<DocumentMetadataToolParamsType>): 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<string, any> = {};
            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);
    }
}