Gorse

https://gorse.io/docs/master/
Admin
Gorse is an open-source recommender system engine that provides collaborative filtering and...
Tokens:37,848
Snippets:213
Trust Score:6.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup Gorse Single Node via Playground

Source: https://gorse.io/docs/master/quick-start

This snippet demonstrates how to quickly set up a single, all-in-one Gorse node using a provided bash script or a direct Docker run command. This is useful for immediate testing and development. The RESTful endpoint for this setup is http://127.0.0.1:8088.

```bash
curl -fsSL https://gorse.io/playground | bash
```

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

--------------------------------

### Setup Gorse Cluster via Docker Compose

Source: https://gorse.io/docs/master/quick-start

This set of commands outlines the process for setting up a multi-node Gorse cluster using Docker Compose. It involves creating a directory, downloading necessary configuration files (docker-compose.yml and config.toml), starting the cluster, and importing sample data.

```bash
# Create a new directory
mkdir gorse
cd gorse

# Download docker-compose.yml and config.toml
wget https://raw.githubusercontent.com/zhenghaoz/gorse/release-0.4/docker-compose.yml
wget https://raw.githubusercontent.com/zhenghaoz/gorse/release-0.4/config/config.toml
```

```bash
docker-compose up -d
```

```bash
# Download sample data.
wget https://cdn.gorse.io/example/github.sql

# Import sample data.
mysql -h 127.0.0.1 -u gorse -pgorse_pass gorse < github.sql
```

```bash
docker-compose restart
```

--------------------------------

### Install PyGorse from PyPI

Source: https://gorse.io/docs/master/api/python-sdk

Installs the Gorse Python SDK using pip from the Python Package Index (PyPI). This is the simplest way to get started with the SDK.

```bash
pip install PyGorse
```

--------------------------------

### Run Gorse-in-one (Linux/macOS)

Source: https://gorse.io/docs/master/deploy/binary

Executes the Gorse-in-one application using a specified configuration file. This command is used to start the Gorse recommender system after installation.

```shell
gorse-in-one -c config.toml
```

--------------------------------

### Setup and Run Integration Tests (Shell)

Source: https://gorse.io/docs/master/contribution-guide

This sequence first sets up Gorse services using Docker Compose and then runs integration tests using a specific Go build tag. Ensure Docker Compose is installed and configured.

```shell
# Setup Gorse
docker-compose up -d

# Test
go test -tags='integrate_test' ./client/
```

--------------------------------

### Install Go SDK

Source: https://gorse.io/docs/master/api/go-sdk

This command installs the Gorse Go SDK. It uses the go get command to fetch the latest version from the master branch. Ensure you have Go installed and configured in your environment.

```bash
go get github.com/zhenghaoz/gorse/client@master

```

--------------------------------

### Install Gorse-in-one (Windows)

Source: https://gorse.io/docs/master/deploy/binary

Installs the Gorse-in-one binary on Windows systems. This involves creating an installation directory, extracting the 'gorse.zip' archive into it, and making the executable accessible.

```powershell
# Create install directory
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/bin

# Extract binaries
Expand-Archive gorse.zip -DestinationPath $env:ProgramFiles/Gorse/bin
```

--------------------------------

### Run Gorse-in-one (Windows)

Source: https://gorse.io/docs/master/deploy/binary

Starts the Gorse-in-one application on Windows using a configuration file. This command assumes the executable and configuration file are in the correct paths.

```powershell
& $env:ProgramFiles/Gorse/bin/gorse-in-one -c config.toml
```

--------------------------------

### Setup Docker Compose for Databases (Shell)

Source: https://gorse.io/docs/master/contribution-guide

This command sets up the necessary databases for running unit tests using Docker Compose. It assumes you are in the 'storage' directory. Ensure Docker and Docker Compose are installed.

```shell
cd storage
docker-compose up -d
```

--------------------------------

### Install Gorse-in-one (Linux/macOS)

Source: https://gorse.io/docs/master/deploy/binary

Installs the Gorse-in-one binary on Linux and macOS systems. It extracts the contents of the 'gorse.zip' file to the '/usr/local/bin' directory, making the executable available system-wide.

```shell
sudo unzip gorse.zip -d /usr/local/bin
```

--------------------------------

### Install Gorse Ruby SDK

Source: https://gorse.io/docs/master/api/ruby-sdk

This snippet shows how to install the Gorse Ruby SDK using the gem command. Ensure you have Ruby and gem installed on your system.

```bash
gem install gorse
```

--------------------------------

### Fetch Recommendations via REST API

Source: https://gorse.io/docs/master/quick-start

This `curl` command retrieves a list of recommended items for a specific user ('bob') from the Gorse API. The `n=10` parameter specifies that the user wants to fetch the top 10 recommendations. This is used after user feedback has been inserted to see the personalized suggestions generated by Gorse.

```bash
curl http://127.0.0.1:8087/api/recommend/bob?n=10
```

--------------------------------

### Setup Gorse Windows Service using NSSM

Source: https://gorse.io/docs/master/deploy/binary

Configures Gorse to run as a Windows service using the NSSM (Non-Sucking Service Manager) tool. This involves installing the service, setting application parameters, specifying the working directory, and redirecting output logs.

```powershell
nssm install Gorse $env:ProgramFiles\Gorse\bin\gorse-in-one.exe
nssm set Gorse AppParameters -c bin\config.toml --cache-path data\gorse.data
nssm set Gorse AppDirectory $env:ProgramFiles\Gorse
nssm set Gorse AppStdout $env:ProgramFiles\Gorse\log\gorse.log
nssm set Gorse AppStderr $env:ProgramFiles\Gorse\log\gorse.log
nssm start Gorse
```

--------------------------------

### Java SDK Usage Example

Source: https://gorse.io/docs/master/api/java-sdk

Example of how to use the Gorse Java SDK. This snippet demonstrates creating a client instance, inserting user feedback (e.g., reads), and requesting recommendations for a user.

```java
import io.gorse.gorse4j.*;

import java.util.List;

public class Main {

    public static void main(String[] args) {
        // Create a client.
        Gorse client = new Gorse("http://127.0.0.1:8087", "api_key");

        // Insert feedback.
        List<Feedback> feedbacks = List.of(
                new Feedback("read", "100", "300", "2022-11-20T13:55:27Z"),
                new Feedback("read", "100", "400", "2022-11-20T13:55:27Z")
        );
        client.insertFeedback(feedbacks);

        // Get recommendation.
        client.getRecommend("100");
    }
}
```

--------------------------------

### Manage Gorse Systemd Service (Linux)

Source: https://gorse.io/docs/master/deploy/binary

Provides commands to manage the Gorse systemd service on Linux. This includes reloading systemd after configuration changes, enabling the service to start on boot, starting the service immediately, and checking its status.

```shell
sudo systemctl daemon-reload
sudo systemctl enable gorse
sudo systemctl start gorse
systemctl status gorse
```

--------------------------------

### Insert User Feedback via REST API

Source: https://gorse.io/docs/master/quick-start

This command uses `curl` to send a POST request to the Gorse API to insert user feedback data. The data is formatted as a JSON array, specifying feedback types, user IDs, item IDs, and timestamps. This is crucial for populating Gorse with interaction data to generate recommendations.

```bash
read -d '' JSON << EOF
[
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "vuejs:vue", "Timestamp": "2022-02-24" },
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "d3:d3", "Timestamp": "2022-02-25" },
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "dogfalo:materialize", "Timestamp": "2022-02-26" },
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "mozilla:pdf.js", "Timestamp": "2022-02-27" },
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "moment:moment", "Timestamp": "2022-02-28" }
]
EOF

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

--------------------------------

### Install PyGorse from Source

Source: https://gorse.io/docs/master/api/python-sdk

Installs the Gorse Python SDK from its source code repository. This method involves cloning the repository and then installing the package, which is useful for development or when needing the latest unreleased changes.

```bash
git clone https://github.com/gorse-io/PyGorse.git
cd PyGorse
pip install .
```

--------------------------------

### Blocking Client Usage for Gorse Rust SDK

Source: https://gorse.io/docs/master/api/rust-sdk

Illustrates the usage of the blocking client for the Gorse Rust SDK. This example shows how to initialize the client, add feedback, and get recommendations in a standard blocking function.

```rust
use gorse_rs::Feedback;
use gorse_rs::blocking::Gorse;

fn main() {
    // Create a blocking client.
    let client = Gorse::new("http://127.0.0.1:8087", "api_key");

    // Insert feedbacks.
    let feedback = vec![
        Feedback::new("star", "bob", "vuejs:vue", "2022-02-24"),
        Feedback::new("star", "bob", "d3:d3", "2022-02-25"),
        Feedback::new("star", "bob", "dogfalo:materialize", "2022-02-26"),
        Feedback::new("star", "bob", "mozilla:pdf.js", "2022-02-27"),
        Feedback::new("star", "bob", "moment:moment", "2022-02-28")
    ];
    client.insert_feedback(&feedback);

    // Get recommendation.
    client.get_recommend("100");
}

```

--------------------------------

### Install PHP SDK using Composer

Source: https://gorse.io/docs/master/api/php-sdk

This command installs the Gorse PHP SDK using Composer, the dependency manager for PHP. Ensure Composer is installed globally on your system.

```bash
composer require gorse/php-gorse
```

--------------------------------

### Usage Example: Gorse.NET SDK for Feedback and Recommendations

Source: https://gorse.io/docs/master/api/dotnet-sdk

Demonstrates how to use the Gorse.NET SDK to connect to a Gorse instance, insert feedback data, and retrieve recommendations for a user. Requires a running Gorse instance and an API key.

```C#
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="vuejs:vue", Timestamp="2022-02-24"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="d3:d3", Timestamp="2022-02-25"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="dogfalo:materialize", Timestamp="2022-02-26"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="mozilla:pdf.js", Timestamp="2022-02-27"},
    new Feedback{FeedbackType="star", UserId="bob", ItemId="moment:moment", Timestamp="2022-02-28"},
});

client.GetRecommend("10");

```

--------------------------------

### Install Gorse.NET SDK via .NET CLI

Source: https://gorse.io/docs/master/api/dotnet-sdk

Installs the Gorse.NET SDK package using the .NET Command Line Interface. This is a common method for adding dependencies to .NET projects.

```.NET CLI
dotnet add package Gorse.NET
```

--------------------------------

### Override Test Database URI (Shell)

Source: https://gorse.io/docs/master/contribution-guide

Demonstrates how to override the default MySQL URI for running Go unit tests, using TiDB as an example. This allows testing against different database instances or types.

```shell
MYSQL_URI=mysql://root:password@tcp(127.0.0.1:4000)/ go test -v ./...
```

--------------------------------

### Install Gorse.NET SDK via NuGet Package Manager

Source: https://gorse.io/docs/master/api/dotnet-sdk

Installs the Gorse.NET SDK package using the NuGet Package Manager console. This is an alternative method for managing .NET project dependencies.

```NuGet
NuGet\Install-Package Gorse.NET
```

--------------------------------

### Start Gorse Services with Docker Compose

Source: https://gorse.io/docs/master/deploy/docker

Command to start all defined Gorse services in detached mode. This command assumes a valid `docker-compose.yml` file is present in the current directory.

```bash
docker-compose up -d

```

--------------------------------

### Create Gorse Directories (Linux)

Source: https://gorse.io/docs/master/deploy/binary

Creates necessary directories for Gorse on a Linux system. These include directories for configuration, logs, and cache files, ensuring proper organization for the application.

```shell
sudo mkdir -p /etc/gorse/
sudo mkdir -p /var/log/gorse/
sudo mkdir -p /var/lib/gorse/
```

--------------------------------

### Download Gorse-in-one Binary (Windows)

Source: https://gorse.io/docs/master/deploy/binary

Downloads the Gorse-in-one single binary for Windows systems. This command is suitable for both amd64 and arm64 architectures. The downloaded file is saved as 'gorse.zip'.

```powershell
# For amd64 CPU:
Invoke-WebRequest https://github.com/gorse-io/gorse/releases/latest/download/gorse_windows_amd64.zip -OutFile gorse.zip

# For arm64 CPU:
Invoke-WebRequest https://github.com/gorse-io/gorse/releases/latest/download/gorse_windows_arm64.zip -OutFile gorse.zip
```

--------------------------------

### Install Gorse Helm Chart

Source: https://gorse.io/docs/master/deploy/kubernetes

Installs the Gorse application on a Kubernetes cluster using Helm. This process involves adding the necessary Helm repositories and then performing the installation. It deploys Gorse with default configurations.

```shell
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo add gorse-io https://charts.gorse.io
helm install gorse gorse-io/gorse
```

--------------------------------

### Configure Gorse Helm Chart Installation

Source: https://gorse.io/docs/master/deploy/kubernetes

Installs the Gorse Helm chart with specific configurations for dashboard username, dashboard password, and API key. These parameters can be set directly during the installation command or provided via a values file.

```shell
helm install gorse \
  --set gorse.dashboard.username=admin \
  --set gorse.dashboard.password=password \
  --set gorse.api.key=api_key \
    gorse-io/gorse
```

```shell
helm install gorse -f values.yaml gorse-io/gorse
```

--------------------------------

### Install Gorse TypeScript SDK using npm

Source: https://gorse.io/docs/master/api/typescript-sdk

This snippet shows how to install the Gorse TypeScript SDK using the npm package manager. It is a direct command to add the SDK as a dependency to your project.

```bash
npm install gorsejs
```

--------------------------------

### Create Gorse Directories (Windows)

Source: https://gorse.io/docs/master/deploy/binary

Creates log and data directories for Gorse within the Program Files directory on Windows. This ensures that the application has dedicated locations for its operational files.

```powershell
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/log
New-Item -Type Directory -Path $env:ProgramFiles/Gorse/data
```

--------------------------------

### Download Gorse-in-one Binary (Linux)

Source: https://gorse.io/docs/master/deploy/binary

Downloads the Gorse-in-one single binary for Linux systems. It provides separate commands for amd64 and arm64 CPU architectures. The downloaded file is saved as 'gorse.zip'.

```shell
# For amd64 CPU:
wget -O gorse.zip https://github.com/gorse-io/gorse/releases/latest/download/gorse_linux_amd64.zip

# For arm64 CPU:
wget -O gorse.zip https://github.com/gorse-io/gorse/releases/latest/download/gorse_linux_arm64.zip
```

--------------------------------

### Gorse Ruby SDK Usage Example

Source: https://gorse.io/docs/master/api/ruby-sdk

This snippet demonstrates how to use the Gorse Ruby SDK. It includes initializing the Gorse client with an API endpoint and key, and then inserting feedback data. The feedback data is structured using the Feedback.new constructor.

```ruby
require 'gorse'

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

client.insert_feedback([
    Feedback.new("star", "bob", "vuejs:vue", "2022-02-24"),
    Feedback.new("star", "bob", "d3:d3", "2022-02-25"),
    Feedback.new("star", "bob", "dogfalo:materialize", "2022-02-26"),
    Feedback.new("star", "bob", "mozilla:pdf.js", "2022-02-27"),
    Feedback.new("star", "bob", "moment:moment", "2022-02-28")
])

client.get_recommend('10')
```

--------------------------------

### Install Gorse TypeScript SDK using yarn

Source: https://gorse.io/docs/master/api/typescript-sdk

This snippet demonstrates how to install the Gorse TypeScript SDK using the yarn package manager. It's an alternative command for adding the SDK to your project's dependencies.

```bash
yarn add gorsejs
```

--------------------------------

### Gorse Systemd Service Configuration (Linux)

Source: https://gorse.io/docs/master/deploy/binary

Sets up Gorse as a systemd service on Linux. This includes defining the service unit, specifying dependencies, restart behavior, and the executable path with its arguments, including configuration and log paths.

```ini
[Unit]
Description=Gorse, an open source recommender system service written in Go.
After=network.target

[Service]
Type=simple
Restart=always
ExecStart=/usr/local/bin/gorse-in-one -c /etc/gorse/config.toml \
    --log-path /var/log/gorse/gorse.log \
    --cache-path /var/lib/gorse/gorse.data

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Gorse Python SDK - Asynchronous Client Usage

Source: https://gorse.io/docs/master/api/python-sdk

Demonstrates how to use the asynchronous client of the Gorse Python SDK. It covers initializing the client, inserting feedback, and getting recommendations within an async function context.

```python
import asyncio

from gorse import AsyncGorse

async def main():
    # Create an async client.
    client = AsyncGorse('http://127.0.0.1:8087', 'api_key')

    # Insert feedbacks.
    await client.insert_feedbacks([
        { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'vuejs:vue', 'Timestamp': '2022-02-24' },
        { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'd3:d3', 'Timestamp': '2022-02-25' },
        { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'dogfalo:materialize', 'Timestamp': '2022-02-26' },
        { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'mozilla:pdf.js', 'Timestamp': '2022-02-27' },
        { 'FeedbackType': 'star', 'UserId': 'bob', 'ItemId': 'moment:moment', 'Timestamp': '2022-02-28' }
    ])

    # Get recommendation.
    await client.get_recommend('bob', n=10)

asyncio.run(main())
```

--------------------------------

### Download Gorse-in-one Binary (macOS)

Source: https://gorse.io/docs/master/deploy/binary

Downloads the Gorse-in-one single binary for macOS systems. It offers commands for both amd64 and arm64 CPU architectures. The downloaded archive is named 'gorse.zip'.

```shell
# For amd64 CPU:
wget -O gorse.zip https://github.com/gorse-io/gorse/releases/latest/download/gorse_darwin_amd64.zip

# For arm64 CPU:
wget -O gorse.zip https://github.com/gorse-io/gorse/releases/latest/download/gorse_darwin_arm64.zip
```

--------------------------------

### Move Configuration File (Linux)

Source: https://gorse.io/docs/master/deploy/binary

Moves the Gorse configuration file ('config.toml') to the '/etc/gorse/' directory. This is a standard location for application configurations on Linux systems.

```shell
sudo mv config.toml /etc/gorse/
```

--------------------------------

### Move Configuration File (Windows)

Source: https://gorse.io/docs/master/deploy/binary

Moves the Gorse configuration file ('config.toml') to the Gorse 'bin' directory within Program Files. This places the configuration alongside the executable for easier management.

```powershell
Move-Item config.toml -Destination $env:ProgramFiles/Gorse/bin
```

--------------------------------

### Install Gorse Rust SDK

Source: https://gorse.io/docs/master/api/rust-sdk

This snippet shows how to add the Gorse Rust SDK as a dependency in your Cargo.toml file. It specifies the version to be used.

```toml
[dependencies]
gorse_rs = "0.4.1"

```

--------------------------------

### Starting Gorse Services with Docker Compose CLI

Source: https://gorse.io/docs/master/deploy/docker

This command initiates the Docker containers defined in the `docker-compose.yaml` file in detached mode. This is the final step after creating the necessary configuration files for a Gorse deployment.

```bash
docker-compose up -d
```

--------------------------------

### Install Gorse Java SDK with Gradle

Source: https://gorse.io/docs/master/api/java-sdk

Dependency declaration for the Gorse Java SDK using Gradle. This snippet enables the integration of the Gorse client library into your Gradle-based Java projects.

```gradle
implementation 'io.gorse:gorse-client:0.4.0'
```

--------------------------------

### Item-to-Item Recommender Configuration Example (JSON)

Source: https://gorse.io/docs/master/concepts/item-to-item

This JSON snippet demonstrates the structure of an item configuration for Gorse's item-to-item recommenders. It includes fields for ItemId, IsHidden, Categories, Timestamp, Labels (with embedding vectors and topics), and Comment.

```json
{
    "ItemId": "gorse-io:gorse",
    "IsHidden": false,
    "Categories": [],
    "Timestamp": "2022-10-23T03:50:24Z",
    "Labels": {
        "embedding": [0.0017246103, -0.009725488, 0.005806058, -0.0187753, -0.015343021, ...],
        "topics": ["machine-learning", "service", "recommender", "go", "recommender-system", "knn", "collaborative-filtering"]
    },
    "Comment": "An open source recommender system service written in Go"

}
```

--------------------------------

### Run Unit Tests (Go Shell)

Source: https://gorse.io/docs/master/contribution-guide

Executes all unit tests within the Gorse project. Requires Go version 1.18+ and Docker Compose for default database connections. Test database URIs can be overridden via environment variables.

```shell
go test -v ./...
```

--------------------------------

### Recommendation APIs

Source: https://gorse.io/docs/master/concepts/data-objects

This section details the various GET endpoints for retrieving recommendations, popular items, and neighboring items, with support for category filtering.

```APIDOC
## GET /api/latest

### Description
Get the latest items globally.

### Method
GET

### Endpoint
/api/latest

### Parameters
#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **items** (array) - A list of latest items.

#### Response Example
```json
{
  "items": [
    {
      "ItemId": "item1",
      "IsHidden": false,
      "Categories": ["cat1"],
      "Timestamp": "2023-10-27T10:00:00Z",
      "Labels": ["label1"],
      "Comment": "Example item"
    }
  ]
}
```
```

```APIDOC
## GET /api/latest/{category}

### Description
Get the latest items within a specified category.

### Method
GET

### Endpoint
/api/latest/{category}

### Parameters
#### Path Parameters
- **category** (string) - Required - The category to filter latest items by.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **items** (array) - A list of latest items in the specified category.

#### Response Example
```json
{
  "items": [
    {
      "ItemId": "item1",
      "IsHidden": false,
      "Categories": ["cat1"],
      "Timestamp": "2023-10-27T10:00:00Z",
      "Labels": ["label1"],
      "Comment": "Example item"
    }
  ]
}
```
```

```APIDOC
## GET /api/popular

### Description
Get the most popular items globally.

### Method
GET

### Endpoint
/api/popular

### Parameters
#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **items** (array) - A list of popular items.

#### Response Example
```json
{
  "items": [
    {
      "ItemId": "item2",
      "IsHidden": false,
      "Categories": ["cat2"],
      "Timestamp": "2023-10-26T10:00:00Z",
      "Labels": ["label2"],
      "Comment": "Another item"
    }
  ]
}
```
```

```APIDOC
## GET /api/popular/{category}

### Description
Get the most popular items within a specified category.

### Method
GET

### Endpoint
/api/popular/{category}

### Parameters
#### Path Parameters
- **category** (string) - Required - The category to filter popular items by.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **items** (array) - A list of popular items in the specified category.

#### Response Example
```json
{
  "items": [
    {
      "ItemId": "item2",
      "IsHidden": false,
      "Categories": ["cat2"],
      "Timestamp": "2023-10-26T10:00:00Z",
      "Labels": ["label2"],
      "Comment": "Another item"
    }
  ]
}
```
```

```APIDOC
## GET /api/recommend/{user-id}

### Description
Get personalized recommendations for a given user ID.

### Method
GET

### Endpoint
/api/recommend/{user-id}

### Parameters
#### Path Parameters
- **user-id** (string) - Required - The ID of the user for whom to generate recommendations.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **recommendations** (array) - A list of recommended items for the user.

#### Response Example
```json
{
  "recommendations": [
    {
      "ItemId": "item3",
      "IsHidden": false,
      "Categories": ["cat3"],
      "Timestamp": "2023-10-25T10:00:00Z",
      "Labels": ["label3"],
      "Comment": "Recommended item"
    }
  ]
}
```
```

```APIDOC
## GET /api/recommend/{user-id}/{category}

### Description
Get personalized recommendations for a given user ID within a specified category.

### Method
GET

### Endpoint
/api/recommend/{user-id}/{category}

### Parameters
#### Path Parameters
- **user-id** (string) - Required - The ID of the user for whom to generate recommendations.
- **category** (string) - Required - The category to filter recommendations by.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **recommendations** (array) - A list of recommended items for the user in the specified category.

#### Response Example
```json
{
  "recommendations": [
    {
      "ItemId": "item3",
      "IsHidden": false,
      "Categories": ["cat3"],
      "Timestamp": "2023-10-25T10:00:00Z",
      "Labels": ["label3"],
      "Comment": "Recommended item"
    }
  ]
}
```
```

```APIDOC
## GET /api/item/{item-id}/neighbors

### Description
Get items similar to a given item ID.

### Method
GET

### Endpoint
/api/item/{item-id}/neighbors

### Parameters
#### Path Parameters
- **item-id** (string) - Required - The ID of the item for which to find neighbors.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **neighbors** (array) - A list of items similar to the specified item.

#### Response Example
```json
{
  "neighbors": [
    {
      "ItemId": "item4",
      "IsHidden": false,
      "Categories": ["cat4"],
      "Timestamp": "2023-10-24T10:00:00Z",
      "Labels": ["label4"],
      "Comment": "Similar item"
    }
  ]
}
```
```

```APIDOC
## GET /api/item/{item-id}/neighbors/{category}

### Description
Get items similar to a given item ID within a specified category.

### Method
GET

### Endpoint
/api/item/{item-id}/neighbors/{category}

### Parameters
#### Path Parameters
- **item-id** (string) - Required - The ID of the item for which to find neighbors.
- **category** (string) - Required - The category to filter neighbors by.

#### Query Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **neighbors** (array) - A list of items similar to the specified item in the specified category.

#### Response Example
```json
{
  "neighbors": [
    {
      "ItemId": "item4",
      "IsHidden": false,
      "Categories": ["cat4"],
      "Timestamp": "2023-10-24T10:00:00Z",
      "Labels": ["label4"],
      "Comment": "Similar item"
    }
  ]
}
```
```

--------------------------------

### Install Gorse Java SDK with Maven

Source: https://gorse.io/docs/master/api/java-sdk

Dependency declaration for the Gorse Java SDK using Maven. This allows you to include the Gorse client library in your Maven project for recommendation system integration.

```xml
<dependency>
    <groupId>io.gorse</groupId>
    <artifactId>gorse-client</artifactId>
    <version>0.4.0</version>
</dependency>
```

--------------------------------

### Install Gorse Java SDK with Leiningen

Source: https://gorse.io/docs/master/api/java-sdk

Dependency declaration for the Gorse Java SDK using Leiningen. This format is used in Clojure projects to specify external libraries, including the Gorse client.

```clojure
[io.gorse/gorse-client "0.4.0"]
```

--------------------------------

### Install Gorse Java SDK with SBT

Source: https://gorse.io/docs/master/api/java-sdk

Dependency declaration for the Gorse Java SDK using SBT. Add this to your build.sbt file to include the Gorse client library in your Scala or Java projects managed by SBT.

```scala
libraryDependencies += "io.gorse" % "gorse-client" % "0.4.0"
```

--------------------------------

### Docker Compose Configuration for Gorse

Source: https://gorse.io/docs/master/deploy/docker

Defines the Docker Compose setup for Gorse, including service definitions, volume mounts, and dependencies. This configuration allows for running Gorse master, server, and worker nodes with persistent storage and logging.

```yaml
volumes:
  worker_data:
  server_data:
  master_data:
  gorse_log:
  mysql_data:
  # postgres_data:
  # mongo_data:
  # clickhouse_data:

services:
  master:
    image: gorse/gorse
    container_name: gorse-master
    ports:
      - "8086:8086"
    volumes:
      - ./config/config.toml:/etc/gorse/config.toml
      - gorse_log:/var/log/gorse
      - master_data:/var/lib/gorse
    command: gorse master --cache-path /var/lib/gorse/master_cache.data
    depends_on:
      - redis
      - mysql
      # - postgres
      # - mongo
      # - clickhouse
  server:
    image: gorse/gorse
    container_name: gorse-server
    ports:
      - "8087:8087"
    volumes:
      - ./config/config.toml:/etc/gorse/config.toml
      - gorse_log:/var/log/gorse
      - server_data:/var/lib/gorse
    environment:
      - MASTER_HOST=127.0.0.1
      - MASTER_PORT=8086
    command: gorse server --http-host 127.0.0.1 --http-port 8087 --master-host 127.0.0.1 --master-port 8086
    depends_on:
      - master
  worker:
    image: gorse/gorse
    container_name: gorse-worker
    volumes:
      - ./config/config.toml:/etc/gorse/config.toml
      - gorse_log:/var/log/gorse
      - worker_data:/var/lib/gorse
    environment:
      - MASTER_HOST=127.0.0.1
      - MASTER_PORT=8086
    command: gorse worker --jobs 1 --master-host 127.0.0.1 --master-port 8086
    depends_on:
      - master
  redis:
    image: redis:alpine
    container_name: gorse-redis
    volumes:
      - mysql_data:/data
  mysql:
    image: mysql:5.7
    container_name: gorse-mysql
    environment:
      MYSQL_ROOT_PASSWORD: root
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql

```

--------------------------------

### GET /api/recommend/{user_id} - Full-screen mode feedback

Source: https://gorse.io/docs/master/concepts/data-objects

In full-screen mode, this endpoint retrieves recommendations and immediately marks them as 'read' to prevent them from appearing again. This is useful when content is presented one at a time and viewed.

```APIDOC
## GET /api/recommend/{user_id}

### Description
Retrieves recommendations for a given user and marks them as 'read' immediately, preventing them from being shown again. This is suitable for full-screen content views.

### Method
GET

### Endpoint
`/api/recommend/{user_id}`

### Parameters
#### Path Parameters
- **user_id** (string) - Required - The unique identifier for the user.

#### Query Parameters
- **write-back-type** (string) - Required - Specifies the type of feedback to write back. Use 'read' for read feedback.
- **n** (integer) - Optional - The number of recommendations to retrieve. Defaults to 1 if not specified.

### Request Example
```bash
curl -X GET "http://172.18.0.3:8087/api/recommend/zhenghaoz?write-back-type=read&n=1" \
    -H "accept: application/json" \
    -H "X-API-Key: 19260817"
```

### Response
#### Success Response (200)
- **recommendations** (array) - A list of recommended items.
- **feedback_status** (string) - Indicates the status of the feedback write-back.
```

--------------------------------

### GET /api/health/live

Source: https://gorse.io/docs/master/api/restful-api

Checks the liveness of the Gorse server node. Returns OK once the server has started.

```APIDOC
## GET /api/health/live

### Description
Checks the liveness of the Gorse server node. Returns OK once the server has started.

### Method
GET

### Endpoint
`/api/health/live`

### Response
#### Success Response (200)
- **CacheStoreConnected** (boolean) - Indicates if the cache store is connected.
- **CacheStoreError** (string) - Error message if the cache store is not connected.
- **DataStoreConnected** (boolean) - Indicates if the data store is connected.
- **DataStoreError** (string) - Error message if the data store is not connected.
- **Ready** (boolean) - Indicates if the server is ready.

#### Response Example
```json
{
  "CacheStoreConnected": false,
  "CacheStoreError": "Nothing's Gonna Stop Us Now",
  "DataStoreConnected": false,
  "DataStoreError": "I Fall to Pieces",
  "Ready": false
}
```
```

--------------------------------

### Full Example Docker Compose for Gorse, Redis, and MySQL

Source: https://gorse.io/docs/master/deploy/docker

This is a complete `docker-compose.yaml` file for setting up a Gorse environment, including the Gorse service itself, a Redis instance for caching, and a MySQL server for data storage. It defines ports, environment variables, volumes, and service dependencies.

```yaml
version: "3"
services:
  redis:
    image: redis
    restart: unless-stopped
    ports:
      - 6379:6379

  mysql:
    image: mysql/mysql-server
    restart: unless-stopped
    ports:
      - 3306:3306
    environment:
      MYSQL_ROOT_PASSWORD: root_pass
      MYSQL_DATABASE: gorse
      MYSQL_USER: gorse
      MYSQL_PASSWORD: gorse_pass

  gorse:
    image: zhenghaoz/gorse-in-one
    restart: unless-stopped
    ports:
      - 8086:8086   # gRPC port
      - 8088:8088   # HTTP port
    environment:
      # Use Redis as cache storage backend.
      GORSE_CACHE_STORE: redis://redis:6379
      # Use MySQL as data storage backend.
      GORSE_DATA_STORE: mysql://gorse:gorse_pass@tcp(mysql:3306)/gorse?parseTime=true
    command: >
      -c /etc/gorse/config.toml 
      --log-path /var/log/gorse/master.log 
      --cache-path /var/lib/gorse/master_cache.data
    volumes:
      # Mount the configuration file.
      - ./config.toml:/etc/gorse/config.toml
    depends_on:
      - redis
      - mysql

```

--------------------------------

### Usage: Go SDK for Gorse Client

Source: https://gorse.io/docs/master/api/go-sdk

Demonstrates how to use the Gorse Go SDK to interact with the recommendation system. It shows how to create a client instance, insert feedback data, and request recommendations for a user. This code requires the gorse client library to be installed.

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

func main() {
    // Create a client
    gorse := client.NewGorseClient("http://127.0.0.1:8087", "api_key")

    // Insert feedback
    gorse.InsertFeedback([]client.Feedback{
        {FeedbackType: "star", UserId: "bob", ItemId: "vuejs:vue", Timestamp: "2022-02-24"},
        {FeedbackType: "star", UserId: "bob", ItemId: "d3:d3", Timestamp: "2022-02-25"},
        {FeedbackType: "star", UserId: "bob", ItemId: "dogfalo:materialize", Timestamp: "2022-02-26"},
        {FeedbackType: "star", UserId: "bob", ItemId: "mozilla:pdf.js", Timestamp: "2022-02-27"},
        {FeedbackType: "star", UserId: "bob", ItemId: "moment:moment", Timestamp: "2022-02-28"},
    })

    // Get recommendation.
    gorse.GetRecommend("bob", "", 10)
}

```

--------------------------------

### GET API Feedback By Type, User, and Item Request/Response Example

Source: https://gorse.io/docs/master/api/restful-api

This snippet shows the request and response for fetching a specific feedback entry identified by feedback type, user ID, and item ID. The response directly returns the feedback object if found.

```json
{
  "Comment": "crocodilia",
  "FeedbackType": "bird",
  "ItemId": "fish",
  "Timestamp": "2020-02-02T20:20:02.02Z",
  "UserId": "crocodilia"
}
```

--------------------------------

### Gorse Cluster Full Example with Multiple Backends

Source: https://gorse.io/docs/master/deploy/docker

This Docker Compose file sets up a Gorse cluster including Redis and MySQL, with commented-out configurations for PostgreSQL, MongoDB, and ClickHouse as alternative backends. It defines services for worker, server, and master nodes, along with persistent volumes for data and logs.

```yaml
version: "3"
services:
  redis:
    image: redis
    restart: unless-stopped
    ports:
      - 6379:6379

  mysql:
    image: mysql/mysql-server
    restart: unless-stopped
    ports:
      - 3306:3306
    environment:
      MYSQL_ROOT_PASSWORD: root_pass
      MYSQL_DATABASE: gorse
      MYSQL_USER: gorse
      MYSQL_PASSWORD: gorse_pass
    volumes:
      - mysql_data:/var/lib/mysql

  # postgres:
  #   image: postgres:10.0
  #   ports:
  #     - 5432:5432
  #   environment:
  #     POSTGRES_DB: gorse
  #     POSTGRES_USER: gorse
  #     POSTGRES_PASSWORD: gorse_pass
  #   volumes:
  #     - postgres_data:/var/lib/postgresql/data

  # mongo:
  #   image: mongo:4.0
  #   ports:
  #     - 27017:27017
  #   environment:
  #     MONGO_INITDB_DATABASE: gorse
  #     MONGO_INITDB_ROOT_USERNAME: root
  #     MONGO_INITDB_ROOT_PASSWORD: password
  #   volumes:
  #     - mongo_data:/data/db

  # clickhouse:
  #   image: yandex/clickhouse-server:21.10
  #   ports:
  #     - 8123:8123
  #   environment:
  #     CLICKHOUSE_DB: gorse
  #     CLICKHOUSE_USER: gorse
  #     CLICKHOUSE_PASSWORD: gorse_pass
  #   volumes:
  #     - clickhouse_data:/var/lib/clickhouse

  worker:
    image: zhenghaoz/gorse-worker
    restart: unless-stopped
    ports:
      - 8089:8089
    command: >
      --master-host master --master-port 8086 
      --http-host 0.0.0.0 --http-port 8089
      --log-path /var/log/gorse/worker.log 
      --cache-path /var/lib/gorse/worker_cache.data
    volumes:
      - gorse_log:/var/log/gorse
      - worker_data:/var/lib/gorse
    depends_on:
      - master

  server:
    image: zhenghaoz/gorse-server
    restart: unless-stopped
    ports:
      - 8087:8087
    command: >
      --master-host master --master-port 8086 
      --http-host 0.0.0.0 --http-port 8087
      --log-path /var/log/gorse/server.log 
      --cache-path /var/lib/gorse/server_cache.data
    volumes:
      - gorse_log:/var/log/gorse
      - server_data:/var/lib/gorse
    depends_on:
      - master

  master:
    image: zhenghaoz/gorse-master
    restart: unless-stopped
    ports:
      - 8086:8086
      - 8088:8088
    environment:
      GORSE_CACHE_STORE: redis://redis:6379
      GORSE_DATA_STORE: mysql://gorse:gorse_pass@tcp(mysql:3306)/gorse
      # GORSE_DATA_STORE: postgres://gorse:gorse_pass@postgres/gorse?sslmode=disable
      # GORSE_DATA_STORE: mongodb://root:password@mongo:27017/gorse?authSource=admin&connect=direct
      # GORSE_DATA_STORE: clickhouse://gorse:gorse_pass@clickhouse:8123/gorse
    command: >
      -c /etc/gorse/config.toml 
      --log-path /var/log/gorse/master.log 
      --cache-path /var/lib/gorse/master_cache.data

```

--------------------------------

### Get Non-personalized Recommendations

Source: https://gorse.io/docs/master/concepts/non-personalized

Retrieves non-personalized recommendations based on a specified recommender name.

```APIDOC
## GET /api/non-personalized/<name>

### Description
Retrieves non-personalized recommendations. The `<name>` parameter specifies which configured non-personalized recommender to use.

### Method
GET

### Endpoint
`/api/non-personalized/<name>`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the non-personalized recommender configuration to use.

### Request Example
```bash
curl http://localhost:8087/api/non-personalized/latest
```

### Response
#### Success Response (200)
- **items** (array) - A list of recommended items.

#### Response Example
```json
{
  "items": [
    {
      "id": "item1",
      "score": 1678886400.0
    },
    {
      "id": "item2",
      "score": 1678800000.0
    }
  ]
}
```
```
Tokens:
Raw