Documentation

Table of Contents

1. Configuration
2. Features
3. Developer Hooks
4. Troubleshooting
5. FAQ

---

Configuration

AI Provider Selection

AI Search supports two embedding providers:

AI Search Service (Recommended)

• Free tier: 10,000 embeddings per month per site
• No API key required
• Automatic token generation
• Usage tracking and quotas

OpenAI API

• Requires your own OpenAI API key
• Uses text-embedding-ada-002 model
• Full control over API usage and billing

Similarity Threshold

The similarity threshold (0.2 – 1.0) controls how closely a post must match the search query:

Range	Description	Use Case
0.2 – 0.4	Low precision	Broad searches, more results
0.4 – 0.6	Balanced	General use (recommended)
0.6 – 0.8	High precision	Specific searches
0.8 – 1.0	Very high precision	Exact matches only

Recommended: 0.3 – 0.5 for most sites.

---

Features

Semantic Search

AI Search uses vector embeddings to understand the meaning behind search queries, not just keyword matching. This means:

• “comfortable summer shoes” matches “breathable sandals for warm weather”
• “budget laptop” matches “affordable notebook computer”

4-Tier Fallback System

When AI search finds no results, the plugin automatically tries:

1. WordPress Default – Standard WordPress search results
2. Broader Search – Individual word matching
3. Unprocessed Posts – Posts without embeddings yet
4. Suggestions – Helpful search term suggestions

WooCommerce Integration

Search through product-specific fields:

• Product descriptions
• Short descriptions
• SKUs
• Categories and tags
• Product attributes (Color, Size, etc.)

Custom Fields Support

Include ACF and custom meta fields in search:

• Text fields
• Textarea/WYSIWYG
• Select/Checkbox/Radio
• Relationship fields
• And more

---

Developer Hooks

Filters

ai_search_searchable_post_types

Customize which post types AI Search will search through.

Parameters:

• $post_type (string|array) – The post type(s) to search
• $query (WP_Query) – The current WP_Query object

Since: 1.9.2

Example: Search only posts and pages

add_filter( 'ai_search_searchable_post_types', function( $post_type, $query ) {
    return [ 'post', 'page' ];
}, 10, 2 );

Example: Search all public post types

add_filter( 'ai_search_searchable_post_types', function( $post_type, $query ) {
    return get_post_types( [ 'public' => true ] );
}, 10, 2 );

Example: Exclude specific post types

add_filter( 'ai_search_searchable_post_types', function( $post_type, $query ) {
    $exclude = [ 'attachment', 'revision' ];

    if ( is_array( $post_type ) ) {
        return array_diff( $post_type, $exclude );
    }

    return in_array( $post_type, $exclude, true ) ? 'post' : $post_type;
}, 10, 2 );

Example: Include custom post types

add_filter( 'ai_search_searchable_post_types', function( $post_type, $query ) {
    return [ 'post', 'page', 'product', 'portfolio', 'testimonial' ];
}, 10, 2 );

Example: Conditional post types based on search context

add_filter( 'ai_search_searchable_post_types', function( $post_type, $query ) {
    $search_term = get_search_query();

    // If searching for "product" or "shop", include WooCommerce products
    if ( strpos( strtolower( $search_term ), 'product' ) !== false
         || strpos( strtolower( $search_term ), 'shop' ) !== false ) {
        return [ 'product' ];
    }

    // Default to posts and pages
    return [ 'post', 'page' ];
}, 10, 2 );

---

Troubleshooting

Embeddings Not Generating

1. Check provider configuration – Ensure your API key or service token is valid
2. Verify post status – Only published posts get embeddings
3. Check quota – AI Search Service has a 10,000 embedding monthly limit
4. Clear cache – Go to Settings > AI Search > Cache Management

Search Not Working

1. Generate embeddings – Go to Settings > AI Search > Generate Embeddings
2. Lower threshold – Try reducing the similarity threshold
3. Check post types – Ensure the post type has embeddings generated

Slow Search Performance

1. Limit post types – Use the ai_search_searchable_post_types filter
2. Clear transient cache – Old cached embeddings may cause issues
3. Regenerate embeddings – Clear and regenerate for better accuracy

---

FAQ

How many embeddings can I generate?

With the free AI Search Service: 10,000 embeddings per month per site. Using your own OpenAI API key: unlimited (based on your OpenAI plan).

Does this work with WooCommerce?

Yes! AI Search fully supports WooCommerce products including descriptions, SKUs, categories, tags, and attributes.

Can I use this with custom post types?

Yes. Use the ai_search_searchable_post_types filter to include any custom post type.

How do I translate the plugin?

AI Search is translation-ready with the text domain ai-search. Place translation files in the /languages directory.

What happens if the AI service is down?

The plugin automatically falls back to WordPress default search, ensuring your site search always works.