Intelligent Search¶

Overview¶

Intelligent Search provides AI-powered question answering over your content. Out of the box it indexes your Sulu pages and articles, and a custom ingest-provider extension point lets you add any other source — databases, external APIs, file systems. Users ask natural-language questions and receive answers with citations linking back to the source documents.

The sulu.ai platform handles the AI processing: it stores your ingested content, performs semantic retrieval when a question is asked, and generates answers grounded in your actual content. The bundle provides the integration layer — ingesting content from Sulu and any custom-provider sources into the platform, exposing search functionality via CLI, services, and a public API endpoint, persisting search interactions for feedback, and surfacing them in the Sulu admin UI.

How it works:

Ingestion — Content from Sulu (pages, articles) and any custom providers is extracted, chunked, and sent to the sulu.ai platform for indexing
Search — A user asks a question; the platform retrieves relevant content and generates an answer with citations
Delivery — Answers are streamed in real-time via Server-Sent Events (SSE), or returned as a single JSON response
Feedback — Each search is persisted; users can submit thumbs-up/down feedback, which content editors review in the Sulu admin

Setup¶

1. Enable Intelligent Search¶

Intelligent search is disabled by default. Enable it in your config/packages/sulu_ai_platform.yaml:

sulu_ai_platform:
    intelligent_search:
        enabled: true

When enabled is true, the bundle registers the intelligent search services, CLI commands, public routes, event subscriber for auto-indexing, and admin feedback views. When false, none of these are loaded.

2. Add Public Routes¶

Import the bundle's website routes from your application's website routing file (typically config/routes/sulu_website.yaml or a webspace-scoped file):

sulu_ai_platform_website:
    resource: "@SuluAiPlatformBundle/config/routes_website.yaml"

This registers (all conditional on intelligent_search.enabled):

Route	Method	Description
`/api/intelligent-search`	GET	Search endpoint (SSE stream by default, JSON via `format=json`)
`/api/intelligent-search/feedback`	POST	Submit thumbs-up/down feedback for a previous search
`/ai-search`	GET	Built-in demo UI (additionally requires `example_ui.enabled: true`)

3. Update Database Schema¶

The feedback persistence requires the ai_search_feedback table:

php bin/console doctrine:schema:update --dump-sql --force

4. Ingest Your Content¶

Index your Sulu content into the sulu.ai platform:

php bin/console sulu:ai:intelligent-search:ingest

When --locale is omitted, all locales declared in your webspace configuration are ingested. See Ingestion for all options.

5. Verify¶

Test from the CLI:

php bin/console sulu:ai:intelligent-search:search "How do I get started?" --locale=en

Optional: Demo UI and Rate Limiting¶

The bundle ships a built-in demo search UI and per-IP rate limiting for the public search endpoint. The demo UI is disabled by default and can be enabled via example_ui.enabled; the rate limiter is enabled by default and can be tuned or disabled via ip_rate_limit:

sulu_ai_platform:
    base_uri: '%env(SULU_AI_PLATFORM_BASE_URI)%'
    api_key: '%env(SULU_AI_PLATFORM_API_KEY)%'
    contact_email: '%env(SULU_AI_CONTACT_EMAIL)%'
    webhook:
        secret: '%env(SULU_AI_WEBHOOK_SECRET)%'
    intelligent_search:
        enabled: true
        example_ui:
            enabled: true
        ip_rate_limit:
            enabled: true           # default: true
            limit: 10               # max requests per interval and IP (default: 10)
            interval: 60            # interval in seconds (default: 60)

With example_ui.enabled: true, the demo UI is available at /ai-search. With the rate limiter enabled, each IP may send at most limit requests per interval seconds to the public search endpoint. See Configuration below for all options and defaults.

Configuration¶

Configure intelligent search under sulu_ai_platform.intelligent_search and content chunking under sulu_ai_platform.ingestion:

# config/packages/sulu_ai_platform.yaml
sulu_ai_platform:
    intelligent_search:
        enabled: true               # Enable intelligent search (default: false)
        identifier: ~               # Optional intelligent search UUID to target (default: null → project default)
        example_ui:
            enabled: false          # Expose the demo UI at /ai-search (default: false)
        ip_rate_limit:
            enabled: true           # Enable per-IP rate limiting (default: true)
            limit: 10               # Max requests per interval (default: 10)
            interval: 60            # Interval in seconds (default: 60)

    ingestion:
        chunker: markdown           # "markdown" (default), "section", or a service ID
        chunker_options:
            word_limit: 200         # Target max words per chunk for the markdown chunker (default: 200)

The example UI is only mounted when both intelligent_search.enabled and intelligent_search.example_ui.enabled are true.

intelligent_search.identifier is optional. A project on the sulu.ai platform can have several intelligent search instances; set this to the UUID of the instance this Sulu project should use for search, ingestion, and deletion. When omitted, the platform uses the project's default instance.

For details on swapping or implementing chunkers, see Ingestion → Chunking.

Permissions¶

The admin feedback list and detail views are gated by the sulu.ai.intelligent_search_feedback security context (registered under the existing Sulu AI security category) with VIEW and DELETE permission types. Assign these to the user roles that should be able to review search interactions.

Next Steps¶

Ingestion — How to index your Sulu content, configure chunking, and rely on automatic re-ingestion
Custom Ingestion Providers — How to ingest content from custom sources
Searching — How to query via the public API, services, and CLI
Feedback — How searches are persisted and reviewed in the admin UI