# AI Search

{% hint style="info" %}
**Requires AI Search Plugin.** This feature requires the [AI Search](https://eagle.cool/support/article/ai-search) plugin to be installed and running.
{% endhint %}

***

## 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:

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```javascript
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

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

{% hint style="info" %}
**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.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.eagle.cool/plugin-api/extra-module/ai-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.