### Start Docker Compose for Databases

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Use this command to start the necessary database services for testing. Ensure you are in the 'storage' directory.

```bash
cd storage

docker compose up -d
```

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

### Gorse Configuration File Example (config.toml)

Source: https://context7.com/gorse-io/gorse/llms.txt

This TOML file demonstrates the configuration structure for Gorse, including database connections, server settings, and recommendation algorithm parameters.

```toml
# Database configuration
[database]
data_store = "mysql://user:pass@tcp(localhost:3306)/gorse?parseTime=true"
cache_store = "redis://localhost:6379/0"

# Master node configuration
[master]
port = 8086
host = "0.0.0.0"
http_port = 8088
http_host = "0.0.0.0"
n_jobs = 4
meta_timeout = "10s"
dashboard_user_name = "admin"
dashboard_password = "secret"

# Server configuration
[server]
default_n = 10
api_key = "your-secret-api-key"
auto_insert_user = true
auto_insert_item = true

# Recommendation configuration
[recommend]
cache_size = 100
cache_expire = "72h"

[recommend.data_source]
positive_feedback_types = ["star", "like", "purchase"]
read_feedback_types = ["view", "click"]
positive_feedback_ttl = 0
item_ttl = 0

[[recommend.item-to-item]]
name = "similar"
type = "embedding"
column = "Labels.embedding"

[[recommend.non-personalized]]
name = "popular"
score = "sum(feedback.Value)"

[recommend.collaborative]
type = "mf"
fit_period = "1h"
fit_epoch = 100

[recommend.ranker]
type = "fm"
fit_period = "1h"

```

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

### Run Gorse Master Node

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Start the master node of Gorse. This command requires a configuration file to be specified.

```bash
go run cmd/gorse-master/main.go --config config/config.toml
```

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

### Fetch Recommendations from Gorse API

Source: https://github.com/gorse-io/gorse/blob/master/README.md

Retrieves a specified number of recommended items for a given user from the Gorse API. This example fetches 10 recommendations for the user 'bob'.

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

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

### Run Gorse Server Node

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Start the server node for Gorse. This node typically handles API requests and serves recommendations.

```bash
go run cmd/gorse-server/main.go
```

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

### Start Gorse in Playground Mode with Docker

Source: https://context7.com/gorse-io/gorse/llms.txt

Launches a Gorse instance in playground mode using Docker, making it accessible at http://localhost:8088. This is useful for quick testing and exploration.

```bash
# Start Gorse in playground mode
docker run -p 8088:8088 zhenghaoz/gorse-in-one --playground

# Dashboard available at http://localhost:8088
```

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

### Run Gorse in Playground Mode with Docker

Source: https://github.com/gorse-io/gorse/blob/master/README.md

Launches Gorse in playground mode using Docker, automatically downloading data from GitRec for a quick start experience. The dashboard will be accessible at http://localhost:8088.

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

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

### Get User

Source: https://context7.com/gorse-io/gorse/llms.txt

Retrieve user profile information by user ID.

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

### Description
Retrieve user profile information by user ID.

### Method
GET

### Endpoint
/api/user/{user_id}

### Path Parameters
- **user_id** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **user_data** (object) - The user profile information.
  - **UserId** (string) - The ID of the user.
  - **Labels** (object) - Key-value pairs for user labels.
  - **Comment** (string) - A comment about the user.

#### Response Example
```json
{"UserId": "user123", "Labels": {"age": 28, "gender": "M"}, "Comment": "Premium subscriber"}
```
```

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

### Run Gorse Worker Node

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Start the worker node for Gorse. This node handles background tasks and processing.

```bash
go run cmd/gorse-worker/main.go
```

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

### Run Unit Tests with Custom MySQL URI

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Override the default MySQL database URI for running unit tests. This example uses TiDB as the test database.

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

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

### Retrieve Collaborative Filtering Recommendations

Source: https://context7.com/gorse-io/gorse/llms.txt

Gets recommendations generated by the collaborative filtering model for a specific user, with an option to filter by category.

```bash
# Get collaborative filtering recommendations
curl "http://127.0.0.1:8088/api/collaborative-filtering/user123?n=10" \
  -H 'X-API-Key: your-api-key'

# Response: [{"Id": "item:cf1", "Score": 0.94}, {"Id": "item:cf2", "Score": 0.89}, ...]
```

```bash
# Filter by category
curl "http://127.0.0.1:8088/api/collaborative-filtering/user123?n=10&category=movies"
```

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

### Session-Based Recommendations API

Source: https://context7.com/gorse-io/gorse/llms.txt

Get real-time recommendations based on anonymous session feedback.

```APIDOC
## POST /api/session/recommend

### Description
Generate real-time recommendations based on a sequence of user interactions within a session.

### Method
POST

### Endpoint
/api/session/recommend

### Parameters
#### Request Body
- **Feedback** (array of objects) - Required - A list of feedback events representing the user's session.
  - **FeedbackType** (string) - Required - The type of feedback (e.g., "click", "purchase").
  - **UserId** (string) - Optional - The user ID (can be empty for anonymous sessions).
  - **ItemId** (string) - Required - The ID of the item interacted with.
  - **Timestamp** (string) - Required - The time of the interaction in ISO 8601 format.

#### Query Parameters
- **n** (integer) - Optional - The number of recommendations to return.

### Request Example
```bash
curl -X POST "http://127.0.0.1:8088/api/session/recommend?n=10" \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key' \
  -d "[
    {\"FeedbackType\": \"click\", \"UserId\": \"\", \"ItemId\": \"item:1001\", \"Timestamp\": \"2024-03-15T10:00:00Z\"},
    {\"FeedbackType\": \"click\", \"UserId\": \"\", \"ItemId\": \"item:1002\", \"Timestamp\": \"2024-03-15T10:01:00Z\"},
    {\"FeedbackType\": \"purchase\", \"UserId\": \"\", \"ItemId\": \"item:1003\", \"Timestamp\": \"2024-03-15T10:02:00Z\"}
  ]"
```

### Response
#### Success Response (200)
- **Id** (string) - The ID of the recommended item.
- **Score** (float) - The recommendation score for the item.

#### Response Example
```json
[{"Id": "item:session1", "Score": 0.91}, {"Id": "item:session2", "Score": 0.87}, ...]
```
```

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

### Get a Specific User Profile

Source: https://context7.com/gorse-io/gorse/llms.txt

Retrieves the profile information for a given user ID. Requires the API Key for authentication.

```bash
# Get a specific user
curl "http://127.0.0.1:8088/api/user/user123" \
  -H 'X-API-Key: your-api-key'

# Response: {"UserId": "user123", "Labels": {"age": 28, "gender": "M"}, "Comment": "Premium subscriber"}
```

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

### Retrieve Item Neighbors

Source: https://context7.com/gorse-io/gorse/llms.txt

Gets items similar to a given item, with options to filter by category or use named recommendation algorithms.

```bash
# Get 10 similar items
curl "http://127.0.0.1:8088/api/item/movie:12345/neighbors/?n=10" \
  -H 'X-API-Key: your-api-key'

# Response: [{"Id": "movie:12346", "Score": 0.92}, {"Id": "movie:12347", "Score": 0.85}, ...]
```

```bash
# Get similar items filtered by category
curl "http://127.0.0.1:8088/api/item/movie:12345/neighbors/?n=10&category=Action"
```

```bash
# Named item-to-item recommendation
curl "http://127.0.0.1:8088/api/item-to-item/similar_movies/movie:12345?n=10"
```

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

### Collaborative Filtering Recommendations API

Source: https://context7.com/gorse-io/gorse/llms.txt

Get recommendations generated by the collaborative filtering model for a specific user.

```APIDOC
## GET /api/collaborative-filtering/{user_id}

### Description
Retrieve collaborative filtering recommendations for a given user.

### Method
GET

### Endpoint
/api/collaborative-filtering/{user_id}

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

#### Query Parameters
- **n** (integer) - Optional - The number of recommendations to return.
- **category** (string) - Optional - Filter recommendations by a specific category.

### Request Example
```bash
# Get collaborative filtering recommendations
curl "http://127.0.0.1:8088/api/collaborative-filtering/user123?n=10" \
  -H 'X-API-Key: your-api-key'

# Filter by category
curl "http://127.0.0.1:8088/api/collaborative-filtering/user123?n=10&category=movies"
```

### Response
#### Success Response (200)
- **Id** (string) - The ID of the recommended item.
- **Score** (float) - The recommendation score for the item.

#### Response Example
```json
[{"Id": "item:cf1", "Score": 0.94}, {"Id": "item:cf2", "Score": 0.89}, ...]
```
```

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

### Retrieve Latest Items

Source: https://context7.com/gorse-io/gorse/llms.txt

Gets the most recently added items, with options to filter by category or exclude items already read by a user.

```bash
# Get 10 latest items
curl "http://127.0.0.1:8088/api/latest?n=10"

# Response: [{"Id": "item:newest", "Score": 1709251200}, ...]
```

```bash
# Get latest items in a specific category
curl "http://127.0.0.1:8088/api/latest?n=10&category=electronics"
```

```bash
# Exclude items already read by a user
curl "http://127.0.0.1:8088/api/latest?n=10&user-id=user123"
```

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

### Get Personalized Recommendations

Source: https://context7.com/gorse-io/gorse/llms.txt

Fetch personalized item recommendations for a specific user based on their interaction history and collaborative filtering models.

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

### Description
Fetch personalized item recommendations for a specific user based on their interaction history and collaborative filtering models.

### Method
GET

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

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

### Query Parameters
- **n** (integer) - Optional - The number of recommendations to return. Defaults to 10.
- **category** (string) - Optional - Filter recommendations by a specific category.
- **write-back-type** (string) - Optional - Type of feedback to write back for recommended items (e.g., "recommended").
- **write-back-delay** (string) - Optional - Delay for write-back feedback (e.g., "1h").

### Request Example
```bash
# Get 10 recommended items for user "bob"
curl "http://127.0.0.1:8088/api/recommend/bob?n=10"

# Get recommendations with scores (API version 2)
curl "http://127.0.0.1:8088/api/recommend/bob?n=10" \
  -H 'X-API-Version: 2'

# Get recommendations filtered by category
curl "http://127.0.0.1:8088/api/recommend/bob?n=10&category=electronics"

# Get recommendations with write-back feedback
curl "http://127.0.0.1:8088/api/recommend/bob?n=10&write-back-type=recommended&write-back-delay=1h"
```

### Response
#### Success Response (200)
- **recommendations** (array) - A list of recommended item IDs or objects with scores.
  - If API version is not 2: array of strings (item IDs).
  - If API version is 2: array of objects, each with:
    - **Id** (string) - The ID of the recommended item.
    - **Score** (number) - The recommendation score.

#### Response Example
```json
// API version < 2
["item:2001", "item:2002", "item:2003", ...]

// API version 2
[{"Id": "item:2001", "Score": 0.95}, {"Id": "item:2002", "Score": 0.87}, ...]
```
```

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

### Get Personalized Recommendations for a User

Source: https://context7.com/gorse-io/gorse/llms.txt

Fetches personalized item recommendations for a specific user. The 'n' parameter specifies the number of recommendations. API version 2 returns recommendations with scores.

```bash
# Get 10 recommended items for user "bob"
curl "http://127.0.0.1:8088/api/recommend/bob?n=10"

# Response: ["item:2001", "item:2002", "item:2003", ...]

# Get recommendations with scores (API version 2)
curl "http://127.0.0.1:8088/api/recommend/bob?n=10" \
  -H 'X-API-Version: 2'

# Response: [{"Id": "item:2001", "Score": 0.95}, {"Id": "item:2002", "Score": 0.87}, ...]

# Get recommendations filtered by category
curl "http://127.0.0.1:8088/api/recommend/bob?n=10&category=electronics"

# Get recommendations with write-back feedback (marks items as "recommended")
curl "http://127.0.0.1:8088/api/recommend/bob?n=10&write-back-type=recommended&write-back-delay=1h"
```

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

### Download and Import Sample Data

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Download the sample GitHub data and import it into the MySQL instance. This is useful for populating the database for testing.

```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
```

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

### Gorse Go Client Library Usage

Source: https://context7.com/gorse-io/gorse/llms.txt

This Go code demonstrates how to use the Gorse client library to insert users, items, and feedback, and then retrieve recommendations and similar items. Ensure the Gorse server is running and accessible.

```go
package main

import (
    "context"
    "fmt"
    "time"

    "github.com/gorse-io/gorse-go"
)

func main() {
    ctx := context.Background()
    client := gorse.NewGorseClient("http://localhost:8088", "your-api-key")

    // Insert a user
    _, err := client.InsertUser(ctx, gorse.User{
        UserId: "user001",
        Labels: map[string]interface{}{
            "age":    25,
            "gender": "F",
        },
    })
    if err != nil {
        panic(err)
    }

    // Insert an item
    _, err = client.InsertItem(ctx, gorse.Item{
        ItemId:     "item001",
        Categories: []string{"Electronics", "Phones"},
        Timestamp:  time.Now(),
        Labels: map[string]interface{}{
            "brand": "Apple",
            "price": 999.99,
        },
    })
    if err != nil {
        panic(err)
    }

    // Insert feedback
    _, err = client.InsertFeedback(ctx, []gorse.Feedback{
        {
            FeedbackType: "purchase",
            UserId:       "user001",
            ItemId:       "item001",
            Timestamp:    time.Now(),
        },
    })
    if err != nil {
        panic(err)
    }

    // Get recommendations
    recommendations, err := client.GetRecommend(ctx, "user001", "", 10, 0)
    if err != nil {
        panic(err)
    }
    fmt.Println("Recommendations:", recommendations)

    // Get similar items
    neighbors, err := client.GetNeighbors(ctx, "item001", 5)
    if err != nil {
        panic(err)
    }
    fmt.Println("Similar items:", neighbors)
}

```

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

### Run All Go Unit Tests

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Execute all unit tests within the Gorse project. This command runs tests verbosely.

```bash
go test -v ./...
```

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

### Run All-in-one Gorse Node

Source: https://github.com/gorse-io/gorse/blob/master/CONTRIBUTING.md

Execute this command to run a single Gorse node that includes all functionalities. A configuration file is required.

```bash
go run cmd/gorse-in-one/main.go --config config/config.toml
```

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

### Retrieve Item Details

Source: https://context7.com/gorse-io/gorse/llms.txt

Fetches details for a specific item using its ID. Also shows how to list items with pagination.

```bash
# Get a specific item
curl "http://127.0.0.1:8088/api/item/movie:12345" \
  -H 'X-API-Key: your-api-key'

# Response: {"ItemId": "movie:12345", "Categories": ["Action", "Sci-Fi"], "Timestamp": "2024-03-01T10:00:00Z", ...}
```

```bash
# List items with pagination
curl "http://127.0.0.1:8088/api/items?n=20&cursor=" \
  -H 'X-API-Key: your-api-key'

# Response: {"Cursor": "next_page_token", "Items": [...]}
```

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

### Insert a Single User with Labels via API

Source: https://context7.com/gorse-io/gorse/llms.txt

Creates or updates a user profile, optionally including labels for demographic or preference data. The API expects a JSON object representing the user.

```bash
# Insert a single user with labels
curl -X POST http://127.0.0.1:8088/api/user \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key' \
  -d '{ 
    "UserId": "user123",
    "Labels": {
      "age": 28,
      "gender": "M",
      "interests": ["technology", "gaming"]
    },
    "Comment": "Premium subscriber"
  }'

# Response: {"RowAffected": 1}
```

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

### Deploy Gorse Cluster with Docker Compose

Source: https://context7.com/gorse-io/gorse/llms.txt

Use this Docker Compose file to set up a multi-node Gorse cluster with Redis for caching and MySQL for data storage. Ensure you have a local config.toml file for the master node.

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

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

  gorse-master:
    image: zhenghaoz/gorse-master
    restart: unless-stopped
    ports:
      - "8086:8086"   # gRPC port
      - "8088:8088"   # HTTP port (dashboard)
    environment:
      GORSE_CACHE_STORE: redis://redis:6379
      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:
      - ./config.toml:/etc/gorse/config.toml
    depends_on:
      - redis
      - mysql

  gorse-server:
    image: zhenghaoz/gorse-server
    restart: unless-stopped
    ports:
      - "8087:8087"
    environment:
      GORSE_CACHE_STORE: redis://redis:6379
      GORSE_DATA_STORE: mysql://gorse:gorse_pass@tcp(mysql:3306)/gorse?parseTime=true
      GORSE_MASTER_HOST: gorse-master
      GORSE_MASTER_PORT: 8086
    command: >
      --log-path /var/log/gorse/server.log
      --cache-path /var/lib/gorse/server_cache.data
    depends_on:
      - gorse-master

  gorse-worker:
    image: zhenghaoz/gorse-worker
    restart: unless-stopped
    environment:
      GORSE_CACHE_STORE: redis://redis:6379
      GORSE_DATA_STORE: mysql://gorse:gorse_pass@tcp(mysql:3306)/gorse?parseTime=true
      GORSE_MASTER_HOST: gorse-master
      GORSE_MASTER_PORT: 8086
    command: >
      --log-path /var/log/gorse/worker.log
      --cache-path /var/lib/gorse/worker_cache.data
      -j 4
    depends_on:
      - gorse-master

```

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

### Check Gorse Server Readiness with cURL

Source: https://context7.com/gorse-io/gorse/llms.txt

This cURL command checks the readiness probe of the Gorse server, indicating if the server is ready to handle requests. It returns a 200 status code if ready, and 503 if not.

```bash
# Readiness probe (server can handle requests)
curl "http://127.0.0.1:8088/api/health/ready"
```

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

### List Users with Pagination

Source: https://context7.com/gorse-io/gorse/llms.txt

Retrieves a list of users with support for pagination. The 'cursor' parameter is used to fetch subsequent pages of results.

```bash
# List users with pagination
curl "http://127.0.0.1:8088/api/users?n=20&cursor=" \
  -H 'X-API-Key: your-api-key'

# Response: {"Cursor": "next_page_token", "Users": [...]}
```

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

### Insert a Single Item with Metadata via API

Source: https://context7.com/gorse-io/gorse/llms.txt

Creates or updates an item in the Gorse system, including categories, labels, timestamps, and visibility status. The API expects a JSON object for the item.

```bash
# Insert a single item with metadata
curl -X POST http://127.0.0.1:8088/api/item \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key' \
  -d '{ 
    "ItemId": "movie:12345",
    "Categories": ["Action", "Sci-Fi"],
    "Timestamp": "2024-03-01T10:00:00Z",
    "Labels": {
      "director": "Christopher Nolan",
      "year": 2024,
      "embedding": [0.1, 0.2, 0.3, 0.4]
    },
    "Comment": "Interstellar 2",
    "IsHidden": false
  }'

# Response: {"RowAffected": 1}
```

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

### Insert Users (Batch)

Source: https://context7.com/gorse-io/gorse/llms.txt

Create or update multiple user profiles in a single request.

```APIDOC
## POST /api/users

### Description
Create or update multiple user profiles in a single request.

### Method
POST

### Endpoint
/api/users

### Request Body
- **user_list** (array) - Required - A list of user data objects.
  - Each object should have:
    - **UserId** (string) - Required - The unique ID of the user.
    - **Labels** (object) - Optional - Key-value pairs for user labels.
    - **Comment** (string) - Optional - A comment about the user.

### Request Example
```json
[
  {"UserId": "user124", "Labels": {"age": 35}},
  {"UserId": "user125", "Labels": {"age": 42}}
]
```

### Response
#### Success Response (200)
- **RowAffected** (integer) - The number of users affected.

#### Response Example
```json
{"RowAffected": 2}
```
```

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

### Insert Multiple Users in Batch via API

Source: https://context7.com/gorse-io/gorse/llms.txt

Creates or updates multiple user profiles in a single API call. This is more efficient for bulk operations than inserting users individually.

```bash
# Insert multiple users in batch
curl -X POST http://127.0.0.1:8088/api/users \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key' \
  -d '[
    {"UserId": "user124", "Labels": {"age": 35}},
    {"UserId": "user125", "Labels": {"age": 42}}
  ]'
```

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

### Insert User

Source: https://context7.com/gorse-io/gorse/llms.txt

Create or update a user profile with optional labels for demographic or preference data.

```APIDOC
## POST /api/user

### Description
Create or update a user profile with optional labels for demographic or preference data.

### Method
POST

### Endpoint
/api/user

### Request Body
- **user_data** (object) - Required - The user data.
  - **UserId** (string) - Required - The unique ID of the user.
  - **Labels** (object) - Optional - Key-value pairs for user labels (e.g., demographics, preferences).
  - **Comment** (string) - Optional - A comment about the user.

### Request Example
```json
{
  "UserId": "user123",
  "Labels": {
    "age": 28,
    "gender": "M",
    "interests": ["technology", "gaming"]
  },
  "Comment": "Premium subscriber"
}
```

### Response
#### Success Response (200)
- **RowAffected** (integer) - The number of users affected (usually 1).

#### Response Example
```json
{"RowAffected": 1}
```
```

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

### Insert Multiple Feedback Records via API

Source: https://context7.com/gorse-io/gorse/llms.txt

Records user interactions with items by posting feedback data to the Gorse API. Ensure the Content-Type and API Key headers are correctly set. The API accepts an array of feedback objects.

```bash
# Insert multiple feedback records for a user
curl -X POST http://127.0.0.1:8088/api/feedback \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key' \
  -d '[
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "item:1001", "Value": 1.0, "Timestamp": "2024-01-15" },
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "item:1002", "Value": 1.0, "Timestamp": "2024-01-16" },
    { "FeedbackType": "star", "UserId": "bob", "ItemId": "item:1003", "Value": 1.0, "Timestamp": "2024-01-17" }
  ]'

# Response: {"RowAffected": 3}
```

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

### Insert Multiple Items in Batch via API

Source: https://context7.com/gorse-io/gorse/llms.txt

Adds or updates multiple items in the Gorse system concurrently. This endpoint is suitable for bulk item ingestion.

```bash
# Insert multiple items in batch
curl -X POST http://127.0.0.1:8088/api/items \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key' \
  -d '[
    {"ItemId": "movie:12346", "Categories": ["Comedy"], "Timestamp": "2024-03-02"},
    {"ItemId": "movie:12347", "Categories": ["Drama"], "Timestamp": "2024-03-03"}
  ]'
```

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

### Session-Based Recommendations

Source: https://context7.com/gorse-io/gorse/llms.txt

Provides real-time recommendations based on anonymous session feedback without needing a persistent user profile. Requires POST request with JSON payload.

```bash
# Get recommendations based on session interactions
curl -X POST "http://127.0.0.1:8088/api/session/recommend?n=10" \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your-api-key' \
  -d '[
    {"FeedbackType": "click", "UserId": "", "ItemId": "item:1001", "Timestamp": "2024-03-15T10:00:00Z"},
    {"FeedbackType": "click", "UserId": "", "ItemId": "item:1002", "Timestamp": "2024-03-15T10:01:00Z"},
    {"FeedbackType": "purchase", "UserId": "", "ItemId": "item:1003", "Timestamp": "2024-03-15T10:02:00Z"}
  ]'

# Response: [{"Id": "item:session1", "Score": 0.91}, {"Id": "item:session2", "Score": 0.87}, ...]
```

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

### Insert User Feedback via Gorse API

Source: https://github.com/gorse-io/gorse/blob/master/README.md

Inserts user feedback data, such as 'star' ratings for GitHub repositories, into Gorse using a POST request to the /api/feedback endpoint. Ensure the timestamp format is correct.

```bash
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"
```

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

### Check Gorse Server Liveness with cURL

Source: https://context7.com/gorse-io/gorse/llms.txt

This cURL command checks the liveness probe of the Gorse server, indicating if the server process is running.

```bash
# Liveness probe (server is running)
curl "http://127.0.0.1:8088/api/health/live"
```

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

### List Users

Source: https://context7.com/gorse-io/gorse/llms.txt

Retrieve a list of users with pagination support.

```APIDOC
## GET /api/users

### Description
Retrieve a list of users with pagination support.

### Method
GET

### Endpoint
/api/users

### Query Parameters
- **n** (integer) - Optional - The maximum number of users to return per page. Defaults to 20.
- **cursor** (string) - Optional - The cursor for pagination, indicating the starting point for the next page of results.

### Response
#### Success Response (200)
- **Cursor** (string) - The cursor for the next page of results. Empty if there are no more pages.
- **Users** (array) - A list of user objects.
  - Each object contains user profile information (UserId, Labels, Comment).

#### Response Example
```json
{"Cursor": "next_page_token", "Users": [...]}
```
```

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

### Insert Items (Batch)

Source: https://context7.com/gorse-io/gorse/llms.txt

Create or update multiple items in a single request.

```APIDOC
## POST /api/items

### Description
Create or update multiple items in a single request.

### Method
POST

### Endpoint
/api/items

### Request Body
- **item_list** (array) - Required - A list of item data objects.
  - Each object should have properties similar to the single item insertion endpoint (ItemId, Categories, Timestamp, Labels, Comment, IsHidden).

### Request Example
```json
[
  {"ItemId": "movie:12346", "Categories": ["Comedy"], "Timestamp": "2024-03-02"},
  {"ItemId": "movie:12347", "Categories": ["Drama"], "Timestamp": "2024-03-03"}
]
```

### Response
#### Success Response (200)
- **RowAffected** (integer) - The number of items affected.

#### Response Example
```json
{"RowAffected": 2}
```
```

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

### Insert Feedback

Source: https://context7.com/gorse-io/gorse/llms.txt

Record user interactions with items by posting feedback data. Feedback includes a type (e.g., "star", "like", "purchase"), user ID, item ID, and timestamp.

```APIDOC
## POST /api/feedback

### Description
Record user interactions with items by posting feedback data. Feedback includes a type (e.g., "star", "like", "purchase"), user ID, item ID, and timestamp.

### Method
POST

### Endpoint
/api/feedback

### Request Body
- **feedback_list** (array) - Required - A list of feedback objects.
  - **FeedbackType** (string) - Required - The type of feedback (e.g., "star", "like", "purchase").
  - **UserId** (string) - Required - The ID of the user.
  - **ItemId** (string) - Required - The ID of the item.
  - **Value** (number) - Optional - The value of the feedback (e.g., rating).
  - **Timestamp** (string) - Optional - The timestamp of the feedback.

### Request Example
```json
[
  { "FeedbackType": "star", "UserId": "bob", "ItemId": "item:1001", "Value": 1.0, "Timestamp": "2024-01-15" },
  { "FeedbackType": "star", "UserId": "bob", "ItemId": "item:1002", "Value": 1.0, "Timestamp": "2024-01-16" },
  { "FeedbackType": "star", "UserId": "bob", "ItemId": "item:1003", "Value": 1.0, "Timestamp": "2024-01-17" }
]
```

### Response
#### Success Response (200)
- **RowAffected** (integer) - The number of feedback records inserted.

#### Response Example
```json
{"RowAffected": 3}
```
```

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

### Retrieve User Neighbors

Source: https://context7.com/gorse-io/gorse/llms.txt

Fetches users similar to a given user, with an option for named user-to-user recommendation algorithms.

```bash
# Get 10 similar users
curl "http://127.0.0.1:8088/api/user/user123/neighbors/?n=10" \
  -H 'X-API-Key: your-api-key'

# Response: [{"Id": "user456", "Score": 0.88}, {"Id": "user789", "Score": 0.76}, ...]
```

```bash
# Named user-to-user recommendation
curl "http://127.0.0.1:8088/api/user-to-user/similar_users/user123?n=10"
```

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

### Retrieve User Feedback

Source: https://context7.com/gorse-io/gorse/llms.txt

Fetches all feedback submitted by a specific user, with an option to filter feedback by type.

```bash
# Get all feedback by user
curl "http://127.0.0.1:8088/api/user/user123/feedback" \
  -H 'X-API-Key: your-api-key'

# Response: [{"FeedbackType": "star", "UserId": "user123", "ItemId": "item:1001", "Timestamp": "...", "Value": 1.0}, ...]
```

```bash
# Get feedback by type
curl "http://127.0.0.1:8088/api/user/user123/feedback/star" \
  -H 'X-API-Key: your-api-key'
```

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

### Insert Item

Source: https://context7.com/gorse-io/gorse/llms.txt

Create or update an item with categories, labels, timestamps, and optional hidden status.

```APIDOC
## POST /api/item

### Description
Create or update an item with categories, labels, timestamps, and optional hidden status.

### Method
POST

### Endpoint
/api/item

### Request Body
- **item_data** (object) - Required - The item data.
  - **ItemId** (string) - Required - The unique ID of the item.
  - **Categories** (array of strings) - Optional - A list of categories the item belongs to.
  - **Timestamp** (string) - Optional - The timestamp of the item (e.g., creation date, release date).
  - **Labels** (object) - Optional - Key-value pairs for item metadata, including embeddings.
  - **Comment** (string) - Optional - A comment about the item.
  - **IsHidden** (boolean) - Optional - Whether the item is hidden from recommendations.

### Request Example
```json
{
  "ItemId": "movie:12345",
  "Categories": ["Action", "Sci-Fi"],
  "Timestamp": "2024-03-01T10:00:00Z",
  "Labels": {
    "director": "Christopher Nolan",
    "year": 2024,
    "embedding": [0.1, 0.2, 0.3, 0.4]
  },
  "Comment": "Interstellar 2",
  "IsHidden": false
}
```

### Response
#### Success Response (200)
- **RowAffected** (integer) - The number of items affected (usually 1).

#### Response Example
```json
{"RowAffected": 1}
```
```

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

### Item Retrieval API

Source: https://context7.com/gorse-io/gorse/llms.txt

Endpoints for retrieving individual item details and listing items with pagination.

```APIDOC
## GET /api/item/{item_id}

### Description
Retrieve details for a specific item using its unique ID.

### Method
GET

### Endpoint
/api/item/{item_id}

### Parameters
#### Path Parameters
- **item_id** (string) - Required - The unique identifier of the item.

### Request Example
```bash
curl "http://127.0.0.1:8088/api/item/movie:12345" \
  -H 'X-API-Key: your-api-key'
```

### Response
#### Success Response (200)
- **ItemId** (string) - The unique identifier of the item.
- **Categories** (array of strings) - List of categories the item belongs to.
- **Timestamp** (string) - The timestamp when the item was added or last updated.

#### Response Example
```json
{
  "ItemId": "movie:12345", 
  "Categories": ["Action", "Sci-Fi"], 
  "Timestamp": "2024-03-01T10:00:00Z", 
  ...
}
```

## GET /api/items

### Description
Retrieve a list of items with support for pagination.

### Method
GET

### Endpoint
/api/items

### Parameters
#### Query Parameters
- **n** (integer) - Optional - The maximum number of items to return.
- **cursor** (string) - Optional - A token for fetching the next page of results.

### Request Example
```bash
curl "http://127.0.0.1:8088/api/items?n=20&cursor=" \
  -H 'X-API-Key: your-api-key'
```

### Response
#### Success Response (200)
- **Cursor** (string) - A token for fetching the next page of results.
- **Items** (array of objects) - A list of item objects.

#### Response Example
```json
{
  "Cursor": "next_page_token", 
  "Items": [...]
}
```
```

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

### Retrieve Non-Personalized Recommendations

Source: https://context7.com/gorse-io/gorse/llms.txt

Fetches non-personalized recommendations like popular or trending items, optionally filtered by category. Requires configuration of the non-personalized recommender.

```bash
# Get popular items (requires configuration of non-personalized recommender)
curl "http://127.0.0.1:8088/api/non-personalized/popular?n=10"

# Response: [{"Id": "item:popular1", "Score": 1523}, {"Id": "item:popular2", "Score": 1489}, ...]
```

```bash
# Get popular items in category
curl "http://127.0.0.1:8088/api/non-personalized/popular?n=10&category=books"
```

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

### Item Similarity API

Source: https://context7.com/gorse-io/gorse/llms.txt

Endpoints for retrieving items similar to a given item.

```APIDOC
## GET /api/item/{item_id}/neighbors

### Description
Retrieve items similar to a given item based on various recommendation algorithms.

### 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
- **n** (integer) - Optional - The number of similar items to return.
- **category** (string) - Optional - Filter similar items by a specific category.

### Request Example
```bash
# Get 10 similar items
curl "http://127.0.0.1:8088/api/item/movie:12345/neighbors/?n=10" \
  -H 'X-API-Key: your-api-key'

# Get similar items filtered by category
curl "http://127.0.0.1:8088/api/item/movie:12345/neighbors/?n=10&category=Action"
```

### Response
#### Success Response (200)
- **Id** (string) - The ID of the similar item.
- **Score** (float) - The similarity score between the items.

#### Response Example
```json
[{"Id": "movie:12346", "Score": 0.92}, {"Id": "movie:12347", "Score": 0.85}, ...]
```

## GET /api/item-to-item/similar_movies/{item_id}

### Description
Retrieve similar items using a named item-to-item recommendation model.

### Method
GET

### Endpoint
/api/item-to-item/similar_movies/{item_id}

### Parameters
#### Path Parameters
- **item_id** (string) - Required - The ID of the item for which to find similar items.

#### Query Parameters
- **n** (integer) - Optional - The number of similar items to return.

### Request Example
```bash
curl "http://127.0.0.1:8088/api/item-to-item/similar_movies/movie:12345?n=10"
```
```

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

### Add Category to Item with cURL

Source: https://context7.com/gorse-io/gorse/llms.txt

Use this cURL command to add a category to an existing item. Ensure you replace placeholders with your actual item ID and API key.

```bash
# Add a category to an item
curl -X PUT "http://127.0.0.1:8088/api/item/movie:12345/category/Thriller" \
  -H 'X-API-Key: your-api-key'
```

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

### Delete Operations

Source: https://context7.com/gorse-io/gorse/llms.txt

Removes users, items, or specific feedback entries from the system. Deleting a user or item also removes their associated feedback.

```bash
# Delete a user (also deletes their feedback)
curl -X DELETE "http://127.0.0.1:8088/api/user/user123" \
  -H 'X-API-Key: your-api-key'

# Response: {"RowAffected": 1}
```

```bash
# Delete an item (also deletes related feedback)
curl -X DELETE "http://127.0.0.1:8088/api/item/movie:12345" \
  -H 'X-API-Key: your-api-key'
```

```bash
# Delete specific feedback
curl -X DELETE "http://127.0.0.1:8088/api/feedback/star/user123/movie:12345" \
  -H 'X-API-Key: your-api-key'
```

```bash
# Delete all feedback between user and item
curl -X DELETE "http://127.0.0.1:8088/api/feedback/user123/movie:12345" \
  -H 'X-API-Key: your-api-key'
```