AI Search

Provides AI semantic search capabilities, including text search and image-based search.

This feature is not yet released: This feature requires Eagle 4.0 build18+ and the future "AI Search" plugin to be installed. Please follow the Eagle website for release updates.

---

Introduction to AI Search Plugin

"AI Search" is a plugin that provides AI semantic search capabilities, supporting text-based semantic search and image-based similarity search. By integrating this plugin, developers can easily implement powerful AI search functionality in their own plugins.

Key Features

• Text Semantic Search - Search for related images using natural language descriptions

• Image-based Search - Find similar images using an image

• Item ID Search - Find similar images based on existing items

---

How to Use AI Search

Use eagle.extraModule.aiSearch to access the AI Search plugin functionality.

Status Queries

Before calling search methods, it's recommended to check the service status:

eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // Check if the plugin is installed
    const isInstalled = await aiSearch.isInstalled();
    console.log('Installed:', isInstalled);

    // Check if the service is ready
    const isReady = await aiSearch.isReady();
    console.log('Service Ready:', isReady);

    // Check if the service is starting
    const isStarting = await aiSearch.isStarting();
    console.log('Starting:', isStarting);

    // Check if data is syncing
    const isSyncing = await aiSearch.isSyncing();
    console.log('Syncing:', isSyncing);
});

Service Control

eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // Open AI Search plugin (will prompt installation if not installed)
    await aiSearch.open();

    // Check service health
    const isHealthy = await aiSearch.checkServiceHealth();
    console.log('Service Healthy:', isHealthy);

    // Get sync status details
    const syncStatus = await aiSearch.getSyncStatus();
    console.log('Sync Status:', syncStatus);
});

---

Search Methods

searchByText(query, options) - Text Semantic Search

Search for related images using natural language descriptions.

• query string - Search keywords or description

• options Object (optional) - Search options

  • limit number - Result count limit, default 20

• Returns Promise<Object> - Search results

  • results Array - Array of search results

    • item Item - Complete Item object

    • score number - Similarity score

eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // Check if service is ready
    if (!await aiSearch.isReady()) {
        console.log('AI Search service is not ready');
        return;
    }

    // Text semantic search
    const result = await aiSearch.searchByText('an orange cat', {
        limit: 10
    });

    // Iterate through search results
    result.results.forEach(r => {
        console.log('Similarity:', r.score);
        console.log('File Name:', r.item.name);
        console.log('Tags:', r.item.tags);
    });
});

searchByBase64(base64, options) - Base64 Image Search

Search for similar images using a Base64 encoded image.

• base64 string - Base64 encoded image string

• options Object (optional) - Search options

  • limit number - Result count limit, default 20

• Returns Promise<Object> - Search results

eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // Search using Base64 image
    const base64Image = 'data:image/jpeg;base64,/9j/4AAQSkZJRg...';
    const result = await aiSearch.searchByBase64(base64Image, {
        limit: 20
    });

    console.log('Found', result.results.length, 'similar images');

    result.results.forEach(r => {
        console.log(`${r.item.name} - Similarity: ${(r.score * 100).toFixed(1)}%`);
    });
});

searchByItemId(itemId, options) - Search by Existing Item

Search for similar images using an existing Eagle item ID.

• itemId string - Eagle item ID

• options Object (optional) - Search options

  • limit number - Result count limit, default 20

• Returns Promise<Object> - Search results

eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // Get currently selected items
    const selectedItems = await eagle.item.get({ isSelected: true });

    if (selectedItems.length === 0) {
        console.log('Please select an item first');
        return;
    }

    // Search for similar images using the selected item's ID
    const result = await aiSearch.searchByItemId(selectedItems[0].id, {
        limit: 30
    });

    console.log('Found', result.results.length, 'similar images');

    // The item in results is a complete Item object with all methods available
    for (const r of result.results) {
        console.log(`${r.item.name} (${r.item.ext}) - Similarity: ${r.score}`);

        // You can directly use Item methods
        // await r.item.save();
    }
});

---

Complete Example

Building a Similar Image Search Feature

eagle.onPluginCreate(async (plugin) => {
    const aiSearch = eagle.extraModule.aiSearch;

    // 1. Check service status
    if (!await aiSearch.isInstalled()) {
        // Open installation prompt
        await aiSearch.open();
        return;
    }

    if (!await aiSearch.isReady()) {
        console.log('Please wait for AI Search service to start');
        return;
    }

    // 2. Execute search
    try {
        const result = await aiSearch.searchByText('sunset beach scenery');

        if (result.results.length === 0) {
            console.log('No related images found');
            return;
        }

        // 3. Process search results
        const topResults = result.results
            .filter(r => r.score > 0.5)  // Keep only results with similarity > 50%
            .slice(0, 10);               // Take top 10

        console.log(`Found ${topResults.length} highly relevant images:`);

        topResults.forEach((r, index) => {
            console.log(`${index + 1}. ${r.item.name}`);
            console.log(`   Similarity: ${(r.score * 100).toFixed(1)}%`);
            console.log(`   Size: ${r.item.width} x ${r.item.height}`);
            console.log(`   Tags: ${r.item.tags.join(', ') || 'None'}`);
        });

        // 4. Further operations on these items
        // For example: select these items
        const itemIds = topResults.map(r => r.item.id);
        await eagle.item.select(itemIds);

    } catch (error) {
        console.error('Search failed:', error.message);
    }
});

---

API Reference

Status Query Methods

Method	Return Type	Description
isInstalled()	Promise<boolean>	Check if AI Search plugin is installed
isReady()	Promise<boolean>	Check if service is ready
isStarting()	Promise<boolean>	Check if service is starting
isSyncing()	Promise<boolean>	Check if data is syncing

Service Control Methods

Method	Return Type	Description
open()	Promise<void>	Open AI Search plugin
checkServiceHealth()	Promise<boolean>	Check service health status
getSyncStatus()	Promise<Object>	Get detailed sync status

Search Methods

Method	Return Type	Description
searchByText(query, options?)	Promise<Object>	Text semantic search
searchByBase64(base64, options?)	Promise<Object>	Base64 image search
searchByItemId(itemId, options?)	Promise<Object>	Search similar images by item ID

Search Result Format

{
    // ... other fields
    results: [
        {
            item: Item,    // Complete Item object with all properties and methods
            score: number  // Similarity score (0-1)
        },
        // ...
    ]
}

Tip: The item in search results is a complete Item object instance. You can directly use methods like save(), refreshThumbnail(), and all other Item methods.