Download the PHP package dgtlss/semantica without Composer

Semantica

A Laravel package that enables semantic search using vector embeddings for better relevance in content-heavy applications like blogs, e-commerce, or knowledge bases. Supports multiple AI providers including OpenAI, Google Gemini, and local Ollama models, with comprehensive security features and static analysis.

Features

• Generate text embeddings using multiple AI providers (OpenAI, Gemini, Ollama)
• Automatic embedding generation for Eloquent models with HasEmbeddings trait
• Semantic search with configurable similarity metrics (cosine, euclidean, dot product)
• Configurable similarity thresholds and result caching
• Batch processing for performance optimization
• Artisan commands for indexing and reindexing existing data
• Comprehensive security features and input validation
• Static analysis with PHPStan and automated code quality tools
• Support for both cloud and local embedding models

Installation

Install via Composer:

Publish the configuration and migration:

Run the migration:

Configuration

Choose your embedding provider and set the appropriate API keys in your .env file:

OpenAI (Default)

Anthropic

Gemini (Google)

Ollama (Local Models)

Additional Configuration

Usage

Automatic Embedding

Models using the HasEmbeddings trait will automatically have embeddings generated when saved only if SEMANTICA_AUTO_EMBED=true is set in your environment file. This is disabled by default for security reasons.

Manual Embedding

Use the service directly:

Semantic Search

Use the facade for searching:

Commands

Index existing records:

Reindex models:

Model Trait

To enable automatic embeddings for a model, use the HasEmbeddings trait:

Security Considerations

API Keys and Authentication

• API keys are stored securely in environment variables and never logged
• The package validates API key presence at service initialization
• Supports multiple providers with proper key validation

Data Privacy and Protection

• Auto-embedding is disabled by default - must be explicitly enabled via SEMANTICA_AUTO_EMBED=true
• Text content is sanitized before sending to external APIs (HTML tags removed, whitespace normalized)
• Input validation prevents empty or malicious text from being processed
• Embeddings are hidden from model JSON serialization by default

Input Validation and Sanitization

• Search queries are trimmed and validated for emptiness
• Model class names are validated to prevent class injection attacks
• Configured models are verified to be valid Eloquent classes
• Text length is limited to prevent abuse (8KB max)

Performance and Abuse Prevention

• Embedding generation is rate-limited by external API constraints
• Batch processing limits prevent memory exhaustion
• Search results are capped (max 100 results)
• Similarity thresholds are clamped between 0.0 and 1.0

Network Security

• HTTPS is enforced for API communications
• HTTP client includes retry logic for resilience
• Timeouts prevent hanging requests

Configuration Security

• Sensitive configuration values are properly typed and validated
• Unsupported providers throw exceptions instead of falling back silently

Logging and Monitoring

• Errors are logged without exposing sensitive information
• API failures include status codes but not response bodies in logs
• Performance metrics (text length, provider, model) are logged for monitoring

Best Practices

• Regularly rotate API keys
• Monitor API usage and costs
• Use caching to reduce external API calls
• Test with mock providers in development
• Keep dependencies updated for security patches

Supported Providers

• OpenAI: High-quality embeddings with multiple models available
• Anthropic: Currently not supported for embeddings (API doesn't provide embedding endpoints) - placeholder implementation
• Gemini: Google's embedding models via Generative AI API
• Ollama: Run embedding models locally using Ollama

API Reference

Facade Methods

Service Methods

Extending Providers

To add support for additional embedding providers, implement the EmbeddingProviderInterface:

Then update the service provider to register your provider.

Development and Quality Assurance

Static Analysis

This package uses PHPStan for static analysis to ensure code quality:

Code Quality Tools

• PHPStan: Static analysis with strict level 8 configuration
• Rector: Automated code refactoring (run with vendor/bin/rector process)
• Larastan: Laravel-specific PHPStan extensions
• Pest: Modern PHP testing framework

Testing

Run tests with Pest:

Troubleshooting

Common Issues

1. API Key Not Found: Ensure your API key is set in .env file with the correct name for your provider.

2. Embedding Generation Fails: Check your API key validity and network connectivity. For Ollama, ensure the service is running.

3. Model Not Found During Search: Ensure models using HasEmbeddings trait have been properly indexed using the artisan commands.

4. Low Similarity Scores: Adjust the similarity threshold or check if your content is being embedded correctly.

Debug Commands

Index specific models:

Reindex all models:

Check embeddings table:

Requirements

• PHP 8.1+
• Laravel 10.0+ or 11.0+
• API key for chosen provider (OpenAI or Gemini) or Ollama installation for local models

License

MIT License