Gorse

Gorse open-source recommender system engine written in Go

Documentation Live Demo

Multi-source

Recommend items from latest, user-to-user, item-to-item and collaborative filtering and etc.

AutoML

Search the best recommendation model automatically.

Distributed

Support horizontal scaling in the recommendation stage after single node training.

RESTful APIs

Expose RESTful APIs for data CRUD and recommendation requests.

Cross database

Support Redis, MySQL, Postgres, MongoDB, and ClickHouse.

Online evaluation

Analyze online recommendation performance from recently user feedback.

GUI dashboard

Provide GUI dashboard for data management and system monitoring.

Open source

The codebase is released under Apache 2 license and driven by the community.

Gorse is an open-source recommendation system written in Go. Gorse aims to be a universal open-source recommender system that can be easily introduced into a wide variety of online services. By importing items, users and interaction data into Gorse, the system will automatically train models to generate recommendations for each user.

Quick Start

The playground mode has been prepared for beginners. Just set up a recommender system for GitHub repositories by following the commands.

docker run -p 8088:8088 zhenghaoz/gorse-in-one --playground

The playground mode will download data from GitRec and import it into Gorse. The dashboard is available at http://localhost:8088.

After the "Generate item-to-item recommendation" task is completed on the "Tasks" page, try to insert several feedbacks into Gorse. Suppose Bob is a developer who interested in LLM related repositories. We insert his star feedback to Gorse.

HTTP

read -d '' JSON << EOF
[
    { \"FeedbackType\": \"star\", \"UserId\": \"bob\", \"ItemId\": \"ollama:ollama\", \"Value\": 1.0, \"Timestamp\": \"2022-02-24\" },
    { \"FeedbackType\": \"star\", \"UserId\": \"bob\", \"ItemId\": \"huggingface:transformers\", \"Value\": 1.0, \"Timestamp\": \"2022-02-25\" },
    { \"FeedbackType\": \"star\", \"UserId\": \"bob\", \"ItemId\": \"rasbt:llms-from-scratch\", \"Value\": 1.0, \"Timestamp\": \"2022-02-26\" },
    { \"FeedbackType\": \"star\", \"UserId\": \"bob\", \"ItemId\": \"vllm-project:vllm\", \"Value\": 1.0, \"Timestamp\": \"2022-02-27\" },
    { \"FeedbackType\": \"star\", \"UserId\": \"bob\", \"ItemId\": \"hiyouga:llama-factory\", \"Value\": 1.0, \"Timestamp\": \"2022-02-28\" }
]
EOF

curl -X POST http://127.0.0.1:8088/api/feedback \
   -H 'Content-Type: application/json' \
   -d "$JSON"

import "github.com/zhenghaoz/gorse/client"

gorse := client.NewGorseClient("http://127.0.0.1:8088", "")

gorse.InsertFeedback([]client.Feedback{
    {FeedbackType: "star", UserId: "bob", ItemId: "ollama:ollama", Value: 1.0, Timestamp: "2022-02-24"},
    {FeedbackType: "star", UserId: "bob", ItemId: "huggingface:transformers", Value: 1.0, Timestamp: "2022-02-25"},
    {FeedbackType: "star", UserId: "bob", ItemId: "rasbt:llms-from-scratch", Value: 1.0, Timestamp: "2022-02-26"},
    {FeedbackType: "star", UserId: "bob", ItemId: "vllm-project:vllm", Value: 1.0, Timestamp: "2022-02-27"},
    {FeedbackType: "star", UserId: "bob", ItemId: "hiyouga:llama-factory", Value: 1.0, Timestamp: "2022-02-28"},
})

Python

from gorse import Gorse

client = Gorse('http://127.0.0.1:8088', '')

client.insert_feedbacks([
    { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'ollama:ollama', 'Value': 1.0, 'Timestamp': '2022-02-24' },
    { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'huggingface:transformers', 'Value': 1.0, 'Timestamp': '2022-02-25' },
    { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'rasbt:llms-from-scratch', 'Value': 1.0, 'Timestamp': '2022-02-26' },
    { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'vllm-project:vllm', 'Value': 1.0, 'Timestamp': '2022-02-27' },
    { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'hiyouga:llama-factory', 'Value': 1.0, 'Timestamp': '2022-02-28' }
])

TypeScript

import { Gorse } from "gorsejs";

const client = new Gorse({ endpoint: "http://127.0.0.1:8088", secret: "" });

await client.insertFeedbacks([
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'ollama:ollama', Value: 1.0, Timestamp: '2022-02-24' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'huggingface:transformers', Value: 1.0, Timestamp: '2022-02-25' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'rasbt:llms-from-scratch', Value: 1.0, Timestamp: '2022-02-26' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'vllm-project:vllm', Value: 1.0, Timestamp: '2022-02-27' },
    { FeedbackType: 'star', UserId: 'bob', ItemId: 'hiyouga:llama-factory', Value: 1.0, Timestamp: '2022-02-28' }
]);

Java

import io.gorse.gorse4j.*;

Gorse client = new Gorse(GORSE_ENDPOINT, GORSE_API_KEY);

List<Feedback> feedbacks = List.of(
        new Feedback("star", "bob", "ollama:ollama", 1.0, "2022-02-24"),
        new Feedback("star", "bob", "huggingface:transformers", 1.0, "2022-02-25"),
        new Feedback("star", "bob", "rasbt:llms-from-scratch", 1.0, "2022-02-26"),
        new Feedback("star", "bob", "vllm-project:vllm", 1.0, "2022-02-27"),
        new Feedback("star", "bob", "hiyouga:llama-factory", 1.0, "2022-02-28")
);
client.insertFeedback(feedbacks);

Rust

use gorse_rs::{Feedback, Gorse};

let client = Gorse::new("http://127.0.0.1:8088", "");

let feedback = vec![
    Feedback {
        feedback_type: "star".into(),
        user_id: "bob".into(),
        item_id: "ollama:ollama".into(),
        value: 1.0,
        timestamp: "2022-02-24".into(),
    },
    Feedback {
        feedback_type: "star".into(),
        user_id: "bob".into(),
        item_id: "huggingface:transformers".into(),
        value: 1.0,
        timestamp: "2022-02-25".into(),
    },
    Feedback {
        feedback_type: "star".into(),
        user_id: "bob".into(),
        item_id: "rasbt:llms-from-scratch".into(),
        value: 1.0,
        timestamp: "2022-02-26".into(),
    },
    Feedback {
        feedback_type: "star".into(),
        user_id: "bob".into(),
        item_id: "vllm-project:vllm".into(),
        value: 1.0,
        timestamp: "2022-02-27".into(),
    },
    Feedback {
        feedback_type: "star".into(),
        user_id: "bob".into(),
        item_id: "hiyouga:llama-factory".into(),
        value: 1.0,
        timestamp: "2022-02-28".into(),
    },
];
client.insert_feedback(&feedback).await;

Ruby

require 'gorse'

client = Gorse.new('http://127.0.0.1:8088', 'api_key')

client.insert_feedback([
    { 'FeedbackType' => 'star', 'UserId' => 'bob', 'ItemId' => 'ollama:ollama' , 'Value' => 1.0, 'Timestamp' => '2022-02-24' },
    { 'FeedbackType' => 'star', 'UserId' => 'bob', 'ItemId' => 'huggingface:transformers' , 'Value' => 1.0, 'Timestamp' => '2022-02-25' },
    { 'FeedbackType' => 'star', 'UserId' => 'bob', 'ItemId' => 'rasbt:llms-from-scratch', 'Value' => 1.0, 'Timestamp' => '2022-02-26' },
    { 'FeedbackType' => 'star', 'UserId' => 'bob', 'ItemId' => 'vllm-project:vllm', 'Value' => 1.0, 'Timestamp' => '2022-02-27' },
    { 'FeedbackType' => 'star', 'UserId' => 'bob', 'ItemId' => 'hiyouga:llama-factory', 'Value' => 1.0, 'Timestamp' => '2022-02-28' }
])

PHP

$client = new Gorse("http://127.0.0.1:8088/", "api_key");

$rowsAffected = $client->insertFeedback([
    new Feedback("star", "bob", "ollama:ollama", 1.0, "2022-02-24"),
    new Feedback("star", "bob", "huggingface:transformers", 1.0, "2022-02-25"),
    new Feedback("star", "bob", "rasbt:llms-from-scratch", 1.0, "2022-02-26"),
    new Feedback("star", "bob", "vllm-project:vllm", 1.0, "2022-02-27"),
    new Feedback("star", "bob", "hiyouga:llama-factory", 1.0, "2022-02-28")
]);

.NET

using Gorse.NET;

var client = new Gorse("http://127.0.0.1:8087", "api_key");

client.InsertFeedback(new Feedback[]
{
    new Feedback{FeedbackType="star", UserId="bob", ItemId="ollama:ollama", Value=1.0, Timestamp="2022-02-24"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="huggingface:transformers", Value=1.0, Timestamp="2022-02-25"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="rasbt:llms-from-scratch", Value=1.0, Timestamp="2022-02-26"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="vllm-project:vllm", Value=1.0, Timestamp="2022-02-27"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="hiyouga:llama-factory", Value=1.0, Timestamp="2022-02-28"},
});

Then, fetch 10 recommended items from Gorse.