Download the PHP package boehmmatthias/smartsearch without Composer

smart_search

Generic vector embedding, semantic search, and RAG (Retrieval-Augmented Generation) infrastructure for TYPO3.

smart_search gives any TYPO3 extension the building blocks for semantic search and LLM-powered answers — without being tied to any specific data model or AI provider. Drop in the services, embed your content, and get back results ranked by meaning rather than keyword overlap.

Alpha state. SmartSearch is under active development. The API is functional but may change before 1.0. We'd love your feedback: open an issue.

Features

• Vectorization — embed arbitrary text into float vectors via a pluggable client. Change detection via MD5 hashing avoids redundant API calls.
• Semantic search — find the most relevant stored entries for a natural-language query using cosine similarity, ranked by score.
• RAG generation — supply pre-formatted context blocks and get a grounded LLM answer that cites its sources.
• Pluggable backends — ships llama.cpp clients for both embedding and generation; swap in OpenAI, Ollama, or any other HTTP-based model by implementing two small interfaces.
• Collection scoping — multiple extensions can share the same table using distinct collection names without collision.
• PSR-3 logging — all HTTP errors and unexpected responses are logged to the TYPO3 log.

Requirements

Ships with llama.cpp clients out of the box. Any other HTTP-based provider (Ollama, OpenAI, Azure OpenAI, …) works by implementing two small interfaces — see Custom Backend.

Installation

Activate the extension:

Run the database schema update in Admin Tools → Maintenance → Analyze Database Structure to create the tx_smartsearch_vector table.

Server Setup

The extension is provider-agnostic: any server that exposes POST /embedding and POST /v1/chat/completions (OpenAI-compatible) works. Update the URLs in Admin Tools → Settings → Extension Configuration → smart_search to point at your chosen backend.

Production

Point the two configuration URLs at your production inference server — a self-hosted llama.cpp, Ollama, or a hosted API like OpenAI. No bundled scripts are involved.

To use a provider that speaks a different API shape (e.g. OpenAI), implement the two interfaces — see Custom Backend.

Development (llama.sh helper)

The extension ships a llama.sh convenience script for local development only. It manages two llama-server processes, PID files, and log rotation using locally installed llama.cpp binaries.

Prerequisites

Verify both servers are up:

Configuration

All settings are available under Admin Tools → Settings → Extension Configuration → smart_search.

Usage

Inject the services via constructor injection — TYPO3's dependency injection container wires everything automatically.

Storing and updating embeddings

Call VectorService::embedAndStore() whenever content is created or updated. Pass a collection name (a string that scopes your entries), a stable identifier, and the plain text to embed. Strip HTML before calling.

The call is idempotent — if the text has not changed since the last call, the embedding server is not contacted and the database is not written to.

Semantic search

RAG generation (full example)

Removing vectors

Remove individual vectors when records are deleted, or wipe an entire collection before a full reindex:

Checking server availability

Use ModelAvailabilityService to guard features that depend on the llama servers, for example to show or hide a semantic search toggle in the UI:

Results are cached for the duration of the current request (null-coalescing pattern).

Implementing a Custom Backend

The two interfaces make it straightforward to replace the llama.cpp clients with any other embedding or generation provider.

Custom embedding client (example: OpenAI)

Then bind it in your extension's Configuration/Services.yaml:

The same pattern applies to GenerationClientInterface for swapping the chat completion backend.

Note: When using a different embedding model, make sure all vectors in a collection were generated by the same model. Mixing models produces meaningless similarity scores. Use VectorRepository::deleteByCollection() and re-embed when switching models.

Troubleshooting

Search returns empty results

1. Check that the embedding server is running: curl -s http://localhost:8080/health
2. Confirm that embedAndStore() was called for your records.
3. Query the database directly: SELECT COUNT(*) FROM tx_smartsearch_vector WHERE collection = 'your-collection';
4. Lower semanticThreshold temporarily to 0.0 to see all results regardless of score.

Health check fails / server unavailable

• Verify the server is running: ./llama.sh status or check your Docker containers.
• Confirm the URL in Extension Configuration matches the actual server address (especially in DDEV: use http://llama-embed:8080, not localhost).
• Check server logs: tail -f var/log/llama-embed.log

Generated answers are cut off

• Increase generationMaxTokens in the extension configuration.
• Increase generationTimeout — CPU inference for long responses can exceed 300 seconds on slow hardware.

Generation is very slow

• CPU inference speed depends heavily on hardware. A GPU-accelerated llama.cpp build (LLAMA_METAL=1 on macOS, LLAMA_CUDA=1 on Linux) can be 10–50× faster.
• Reduce ragTopK and documentContextLength to pass less context to the model.
• Use a smaller/quantized model (e.g. Q4_K_M instead of Q8_0).

Results have low relevance / wrong ranking

• Make sure you strip HTML and normalise whitespace before calling embedAndStore(). Tags pollute the vector representation.
• Ensure the text passed to embedAndStore() contains the full semantic content, not just a title.
• Verify you are using the same model for both embedding stored content and embedding queries. Mismatched models produce meaningless similarity scores.

Dimension mismatch warning in logs

You switched embedding models without re-indexing. Entries generated by the old model have a different vector dimension than the query vector and are automatically skipped. Run a full reindex:

Known Limitations

• No streaming — generation responses are returned in full after the model finishes. The stream: false flag is hardcoded.
• Single-vector operations — there is no batch embed API; callers must loop over records.
• No metadata fields — the vector table stores only collection, identifier, vector, and a content hash. Extra fields (e.g. source URL, author) must be managed in the consuming extension's own tables.
• PHP 8.4+ only — the extension uses readonly constructor properties and other PHP 8.4 features.
• In-process similarity search — cosine similarity is computed in PHP after fetching all vectors for a collection. This works well up to tens of thousands of entries; for larger datasets consider a dedicated vector database.

Database Schema

Multiple extensions can share the table without collision by using distinct collection names (e.g. news-articles, faq-entries, product-descriptions).

Contributing

1. Fork the repository and create a branch.
2. Install dependencies: composer install
3. Run the test suite: vendor/bin/phpunit packages/smart-search/Tests/Unit/
4. Run static analysis: vendor/bin/phpstan analyse -c packages/smart-search/phpstan.neon
5. Submit a pull request with a clear description of the change.

Please follow the existing code style (strict types, readonly constructors, PSR-12).

Testing

Changelog

See CHANGELOG.md.