Gorse Documentation

Gorse is designed as a single-node training and distributed prediction system. The architecture consists of three main node types:

• Master Node: Responsible for model training, non-personalized recommendation, configuration management, and membership management. It also hosts the GUI dashboard for system monitoring and data management.
• Server Node: Exposes RESTful APIs and handles online real-time recommendation requests.
• Worker Node: Responsible for performing offline recommendations for each user.

Storage Support:

• Primary Data: MySQL (MariaDB), MongoDB, Postgres, or ClickHouse.
• Intermediate Cache: Redis, MySQL (MariaDB), MongoDB, and Postgres.

For beginners, Gorse provides a playground mode via Docker that automatically sets up a recommender system using GitHub repository data from GitRec. This mode includes a GUI dashboard for monitoring and management.

1. Run the playground: Use the Docker command below to start the system.
2. Access the Dashboard: The dashboard is available at http://localhost:8088.
3. Wait for Tasks: Ensure the "Generate item-to-item recommendation" task is completed on the "Tasks" page before proceeding to manual data insertion.

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

You can install the gorse-cli binary on Unix-like systems (Linux or macOS) using the provided installation script. The script automatically detects your operating system and architecture and downloads the appropriate release from GitHub.

Supported Platforms

• Linux: amd64, arm64, loong64, riscv64
• macOS (Darwin): arm64 (Note: darwin_amd64 is currently unsupported)

Configuration via Environment Variables

You can customize the installation by setting the following environment variables before running the script:

• GORSE_REPO: The GitHub repository (defaults to gorse-io/gorse).
• GORSE_CLI_VERSION: The specific version to install (defaults to latest).
• INSTALL_DIR: The directory where the binary will be installed (defaults to /usr/local/bin).
• BINARY_NAME: The name of the installed binary (defaults to gorse-cli).

The gorse-cli allows you to save connection details (endpoint and API key) as named contexts to avoid repeating credentials in every command.

Available context commands:

• gorse-cli context add <name>: Save a new context.
• gorse-cli context use <name>: Switch to a saved context.
• gorse-cli context list: List all saved contexts.
• gorse-cli context delete <name>: Remove a context.
• gorse-cli context current: Show the currently active context.

To run commands, you must provide a Gorse admin endpoint and an API key. You can do this in three ways:

1. Using a saved context: gorse-cli context use <name>
2. Using environment variables:
   • GORSE_ADMIN_ENDPOINT
   • GORSE_ADMIN_API_KEY
3. Using CLI flags (applies to most commands):
   • --endpoint <url>
   • --api-key <key>

You can perform binary backups of all Gorse data using the dump and restore commands.

• Dump: Creates a binary backup file. gorse-cli dump <file>
• Restore: Restores data from a binary backup. Warning: This will overwrite existing users, items, feedback, and cache. You must confirm the action with y. gorse-cli restore <file>

# Dump data to a backup file
gorse-cli dump backup.bin

# Restore data from a backup file
gorse-cli restore backup.bin

Playground mode is designed to quickly set up a functional recommender system with pre-loaded sample data. When this mode is activated, Gorse will:

1. Generate a default configuration file in ~/.gorse/etc/config.toml.
2. Download and import sample datasets.
3. Start the master service.

Supported Playground Datasets

• default: Sets up a recommender system for GitHub repositories using github.bin.gz.
• ml-100k: Sets up a recommender system using the MovieLens 100k dataset (ml-100k.bin.gz).

Upon successful setup, the following endpoints are typically available:

• Dashboard: http://127.0.0.1:<HttpPort>/overview
• RESTful APIs: http://127.0.0.1:<HttpPort>/apidocs

Use the pipeline command group to manage the recommendation engine's configuration.

• gorse-cli pipeline get: Retrieves the current recommendation pipeline configuration.
• gorse-cli pipeline schema: Retrieves the configuration schema (YAML format).
• gorse-cli pipeline patch '<json-patch>': Applies a JSON patch to the recommendation configuration. This is useful for updating specific values without replacing the whole config.
• gorse-cli pipeline reset: Resets the pipeline configuration to the default values defined in the system files.

# Replace a single config value using JSON patch
gorse-cli pipeline patch '[{"op":"replace","path":"/cache_size","value":1000}]'

# Replace multiple config values
gorse-cli pipeline patch '[{"op":"replace","path":"/cache_size","value":1000},{"op":"replace","path":"/data_source/item_ttl","value":72}]'