https://github.com/snowlaboratory/laravel-mirror
Laravel recommendation engine - take your blog to the next level!
https://github.com/snowlaboratory/laravel-mirror
content-suggest embeddings laravel-package recommendation-engine recommendation-system
Last synced: 6 months ago
JSON representation
Laravel recommendation engine - take your blog to the next level!
- Host: GitHub
- URL: https://github.com/snowlaboratory/laravel-mirror
- Owner: SnowLaboratory
- License: mit
- Created: 2023-08-06T15:01:07.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2023-09-17T02:02:04.000Z (about 2 years ago)
- Last Synced: 2025-03-24T12:56:23.145Z (7 months ago)
- Topics: content-suggest, embeddings, laravel-package, recommendation-engine, recommendation-system
- Language: PHP
- Homepage:
- Size: 183 KB
- Stars: 14
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
- [Introduction](#introduction)
- [Installation](#installation)
- [Usage](#usage)
- [Weighted Averages](#weighted-averages)
- [Compare Different Properties](different-properties-in-the-same-calculation)
- [Custom Scoring Algorithms](#custom-scoring-algorithms)
- [Combining Weights & Custom Algorithms](#combining-weights-with-custom-algorithms)
- [Organizing Code](#managing-multiple-algorithms-and-weights)
- [Macros](#macros-extracting-algorithms)
- [Relationships](#relationships)
- [Generate Recommendations](#generate)
- [Roadmap](#roadmap)
- [Testing](#testing)
- [Changelog](#changelog)
- [Contributing](#contributing)
- [Security Vulnerabilities](#security)
- [Code of Conduct](#code-of-conduct)
- [License](#license)
## Introduction
Bring your user experience to the next level! Laravel Mirror lets you suggest content to your users intelligently! Easily recommend blog posts, products, recipes, books, etc., with pure PHP! Start by registering a recommendation strategy and routinely updating recommendations in a CRON job!
You can install the package via composer:
```bash
composer require "snowbuilds/laravel-mirror:^0.0.3-alpha"
```
```bash
php artisan vendor:publish --provider="SnowBuilds\Mirror\MirrorServiceProvider"
```
## Usage
Registering a strategy is as simple as comparing two values! We added some utilities for convenience. For example, recommending blog posts with similar titles:
```php
use SnowBuilds\Mirror\Concerns\Recommendations;
use SnowBuilds\Mirror\Mirror;
class Post extends Model
{
use Recommendations;
public function registerRecommendations(): void
{
$this->registerStrategy(Post::class)
->levenshtein('title');
}
}
```
### Weighted Averages
It is possible to combine algorithms! For example, suggesting posts with similar titles and tags. Adding weights will give fields precedence. Larger numbers have higher precedence. We made the title field score higher in a recommendation engine than the tags:
```php
public function registerRecommendations(): void
{
$this->registerStrategy(Post::class)
->levenshtein('title', 2)
->euclidean('tags', 1);
}
```
### Different Properties in the Same Calculation
You can add a second parameter to the utility method when comparing properties with different names. For example, users should see posts based on their biography and followed communities:
```php
class User extends Model
{
use Recommendations;
public function registerRecommendations(): void
{
$this->registerStrategy(Post::class)
->levenshtein('biography', 'title', 1) // compare biography to post title
->euclidean('communities', 'tags', 3); // compare communities to post tags
}
}
```
### Custom Scoring algorithms
When the helper utilities are insufficient, you can invoke custom algorithms using the `using` method. The first value, `$a`, is the model that has recommendations, and the second value, `$b`, is the model being suggested:
```php
class User extends Model
{
public function registerRecommendations(): void
{
$this->registerStrategy(Post::class)
->using(function (User $a, Post $b) {
return Algorithm::levenshtein($a->name, $b->name);
});
}
}
```
### Combining Weights with Custom Algorithms
Weights can also be applied to custom algorithms. The weights are applied in the order that the algorithm was registered. Our custom title comparator will take precedence over our tag comparator:
```php
public function registerRecommendations(): void
{
$this->registerStrategy(Post::class)
->using(function ($a, $b) {
return Algorithm::levenshtein($a->title, $b->title);
})
->using(function ($a, $b) {
return Algorithm::euclidean($a->tags, $b->tags);
})
->weights([2,1]);
}
```
### Managing Multiple Algorithms and Weights
The code becomes hard to read when using multiple custom algorithms and weights. If you use an associative array, you can keep your algorithms and weights organized:
```php
public function registerRecommendations(): void
{
$this->registerStrategy(Post::class)
->using([
'titles' => fn ($a, $b) => Algorithm::levenshtein($a->title, $b->title),
'tags' => fn ($a, $b) => Algorithm::levenshtein($a->tags, $b->tags),
])
->weights([
'titles' => 2,
'tags' => 1,
]);
}
```
### Macros - Extracting Algorithms
When your custom algorithm is too cumbersome, you can extract it into a macro. We use an internal utility for registering algorithms, which you are free to use in your macros. This will create a clean utility API `->huggingFace` for our user model:
```php
// ServiceProvider.php
ScoringStrategy::macro('huggingFace', function (...$args) {
return $this->registerAlgorithm(
fn($a, $b) => HuggingFace::invokeEmbedding($a, $b),
...$args
);
});
// Model.php
class User extends Model
{
public function registerRecommendations(): void
{
$this->registerStrategy(User::class)
->euclidean('follewers')
->huggingFace('activity')
->levenshtein('bio');
}
}
```
## Relationships
You can define a relationship between the model and the suggested content using the `morphsRecommendation` method. The content is ordered by the most suggested content:
```php
class User extends Authenticatable
{
use Recommendations;
public function recommendedRecipes() {
return $this->morphRecommendation(Recipe::class);
}
}
```
## Generating Recommendation Matrix
Calculating recommendations is resource-intensive. Laravel Mirror provides a command for syncing recommendations. After syncing, the recommendations are stored in the database and you will be able to fetch related suggestions:
```bash
php artisan mirror:sync
```
In production, this should be a CRON job or registered in the Laravel kernel.
```php
class Kernel extends ConsoleKernel
{
protected function schedule(Schedule $schedule): void
{
$schedule->command('mirror:sync')->daily();
}
}
```
## Roadmap
- [x] Blazingly Fast!
- [x] Polymorphic recommendations
- [x] Recommendation collections
- [x] Common comparison algorithms
- [x] Sync command
- [ ] Testing
- [ ] Programmatically invoke syncing actions
- [x] Simplified API for weights and faceted algorithms
- [ ] Queueing
- [ ] More algorithms
- [ ] More settings
```bash
composer test
```
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
If you discover any security-related issues, please email dev@snowlaboratory.com instead of using the issue tracker.
In order to ensure that the Laravel community is welcoming to all, please review and abide by the [Code of Conduct](https://laravel.com/docs/contributions#code-of-conduct).
- [Snow Labs](https://github.com/snowbuilds)
- [Inspiration for Laravel Mirror](https://oliverlundquist.com/2019/03/11/recommender-system-with-ml-in-laravel.html)
- [All Contributors](../../contributors)
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.