### Setup Local Gorse Cluster for Testing

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

Downloads and starts a local Gorse cluster using a script. This is necessary for integration testing against a live server.

```bash
curl -sL https://github.com/gorse-io/gorse/raw/refs/heads/master/client/setup-test.sh | bash
```

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

### Install Gorse Go SDK

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

Use this command to install the Gorse Go SDK. Ensure you have Go installed and configured.

```bash
go get github.com/gorse-io/gorse-go
```

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

### Gorse Go SDK Usage Example

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

This example demonstrates how to use the Gorse Go SDK to interact with the Gorse recommender system. It covers client creation, inserting users, items, and feedback, and fetching recommendations. Ensure the Gorse server is running and accessible.

```go
package main

import (
    "context"
    "log"
    "time"

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

func main() {
    // Create client
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Insert a user
    if _, err := gorse.InsertUser(ctx, client.User{
        UserId:  "bob",
        Labels:  map[string]any{"age": 30, "gender": "M"},
        Comment: "new user",
    }); err != nil {
        log.Fatal(err)
    }

    // Insert an item
    if _, err := gorse.InsertItem(ctx, client.Item{
        ItemId:     "movie_1",
        IsHidden:   false,
        Labels:     map[string]any{"embedding": []any{0.1, 0.2, 0.3}},
        Categories: []string{"Comedy"},
        Timestamp:  time.Now().UTC().Truncate(time.Second),
        Comment:    "Example Movie (2024)",
    }); err != nil {
        log.Fatal(err)
    }

    // Insert feedback (timestamps are time.Time)
    if _, err := gorse.InsertFeedback(ctx, []client.Feedback{
        {FeedbackType: "watch", UserId: "bob", ItemId: "movie_1", Value: 1.0, Timestamp: time.Now().UTC().Truncate(time.Second)},
    }); err != nil {
        log.Fatal(err)
    }

    // Get recommendations
    recs, err := gorse.GetRecommend(ctx, "bob", "", 10, 0)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("recommendations: %v", recs)
}
```

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

### Verify Go Installation

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

Run this command to check if Go is installed and verify the version.

```bash
go version
```

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

### Get Similar Items

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

Retrieves similar items to a given item ID. Useful for 'more like this' features. Requires a Gorse client instance.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get similar items to "Toy Story"
    neighbors, err := gorse.GetNeighbors(ctx, "movie_001", 5)
    if err != nil {
        log.Fatal(err)
    }
    log.Println("Items similar to Toy Story:")
    for _, neighbor := range neighbors {
        log.Printf("  - %s (Similarity: %.4f)", neighbor.Id, neighbor.Score)
    }
    // Output:
    // Items similar to Toy Story:
    //   - movie_1060 (Similarity: 0.8234)
    //   - movie_404 (Similarity: 0.7891)
    //   - movie_1219 (Similarity: 0.7456)
}
```

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

### Get Paginated Items in Gorse Go

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

Retrieves a paginated list of items using cursor-based pagination. Fetches the first page and demonstrates how to continue to the next page.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Fetch first page of items
    iterator, err := gorse.GetItems(ctx, 10, "")
    if err != nil {
        log.Fatal(err)
    }
    for _, item := range iterator.Items {
        log.Printf("Item: %s - %s (%v)", item.ItemId, item.Comment, item.Categories)
    }

    // Continue with next page if available
    if iterator.Cursor != "" {
        nextPage, _ := gorse.GetItems(ctx, 10, iterator.Cursor)
        log.Printf("Next page has %d items", len(nextPage.Items))
    }
}
```

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

### Get Session-Based Recommendations

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

Provides session-based recommendations for anonymous users using their recent interactions. Requires a slice of feedback events and the desired number of recommendations. Ensure the Gorse client is initialized.

```go
package main

import (
    "context"
    "log"
    "time"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Session-based recommendations for anonymous user
    sessionFeedback := []client.Feedback{
        {FeedbackType: "view", ItemId: "movie_001", Timestamp: time.Now().UTC()},
        {FeedbackType: "view", ItemId: "movie_045", Timestamp: time.Now().UTC()},
        {FeedbackType: "click", ItemId: "movie_001", Timestamp: time.Now().UTC()},
    }
    recommendations, err := gorse.SessionRecommend(ctx, sessionFeedback, 10)
    if err != nil {
        log.Fatal(err)
    }
    for _, rec := range recommendations {
        log.Printf("Session recommendation: %s (Score: %.4f)", rec.Id, rec.Score)
    }
}
```

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

### Get Latest Items

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

Retrieves the most recently added items. Can be filtered by category and personalized for a user. Requires an initialized Gorse client.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get latest items across all categories
    latestItems, err := gorse.GetLatestItems(ctx, "", "", 10, 0)
    if err != nil {
        log.Fatal(err)
    }
    for _, item := range latestItems {
        log.Printf("Latest: %s (Score: %.4f)", item.Id, item.Score)
    }

    // Get latest items in "Action" category for a specific user
    latestAction, err := gorse.GetLatestItems(ctx, "user_001", "Action", 5, 0)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Latest action items for user: %d", len(latestAction))
}
```

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

### Get Collaborative Filtering Recommendations

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

Retrieves recommendations based purely on the collaborative filtering algorithm. Supports category filtering and pagination. Ensure the Gorse client is properly configured.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get collaborative filtering recommendations
    cfRecs, err := gorse.GetCollaborativeFiltering(ctx, "user_001", "", 10, 0)
    if err != nil {
        log.Fatal(err)
    }
    for _, rec := range cfRecs {
        log.Printf("CF Recommendation: %s (Score: %.4f)", rec.Id, rec.Score)
    }

    // Get CF recommendations for a specific category
    cfDrama, err := gorse.GetCollaborativeFiltering(ctx, "user_001", "Drama", 5, 0)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Drama CF recommendations: %d", len(cfDrama))
}
```

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

### User Management - Get User

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

Retrieves a single user by their user ID, including all labels and metadata.

```APIDOC
## User Management

### GetUser

Retrieves a single user by their user ID including all labels and metadata.

### Method
GET

### Endpoint
/users/{user_id}

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

### Response
#### Success Response (200)
- **UserId** (string) - The unique identifier for the user.
- **Labels** (map[string]any) - Key-value pairs for user profiling.
- **Comment** (string) - A comment or description for the user.

### Response Example
```json
{
  "UserId": "user_001",
  "Labels": {"age": 24, "gender": "M", "occupation": "engineer", "zip_code": "94102"},
  "Comment": "Premium subscriber"
}
```

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Retrieve user by ID
    user, err := gorse.GetUser(ctx, "user_001")
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("User: %s, Labels: %v, Comment: %s", user.UserId, user.Labels, user.Comment)
    // Output: User: user_001, Labels: map[age:24 gender:M occupation:engineer zip_code:94102], Comment: Premium subscriber
}
```
```

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

### Get Similar Users

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

Retrieves users similar to a given user ID based on interaction patterns. Useful for social recommendations or personalized content.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get users similar to user_001
    similarUsers, err := gorse.GetNeighborsUsers(ctx, "user_001", 10, 0)
    if err != nil {
        log.Fatal(err)
    }
    log.Println("Similar users:")
    for _, user := range similarUsers {
        log.Printf("  - User %s (Similarity: %.4f)", user.Id, user.Score)
    }
}
```

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

### Get Similar Items in Category

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

Retrieves similar items within a specific category for a given item ID, with pagination support. Useful for category-specific recommendations.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get similar Animation movies to "Toy Story"
    neighbors, err := gorse.GetNeighborsCategory(ctx, "movie_001", "Animation", 10, 0)
    if err != nil {
        log.Fatal(err)
    }
    log.Println("Similar Animation movies:")
    for _, neighbor := range neighbors {
        log.Printf("  - %s (Similarity: %.4f)", neighbor.Id, neighbor.Score)
    }
}
```

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

### Retrieve Paginated Users

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

Fetch users in pages using cursor-based pagination, which is efficient for large datasets. You can specify the number of users per page and use the cursor to get subsequent pages.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Fetch first page of users (3 per page)
    cursor, err := gorse.GetUsers(ctx, 3, "")
    if err != nil {
        log.Fatal(err)
    }
    for _, user := range cursor.Users {
        log.Printf("User ID: %s, Labels: %v", user.UserId, user.Labels)
    }

    // Fetch next page using cursor
    if cursor.Cursor != "" {
        nextPage, err := gorse.GetUsers(ctx, 3, cursor.Cursor)
        if err != nil {
            log.Fatal(err)
        }
        log.Printf("Next page has %d users", len(nextPage.Users))
    }
}
```

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

### Get Personalized Recommendations

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

Retrieves personalized recommendations for a user. Supports optional category filtering and pagination. Ensure the Gorse client is initialized with the correct endpoint and API key.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get top 10 recommendations for a user
    recommendations, err := gorse.GetRecommend(ctx, "user_001", "", 10, 0)
    if err != nil {
        log.Fatal(err)
    }
    for i, rec := range recommendations {
        log.Printf("%d. Item: %s (Score: %.4f)", i+1, rec.Id, rec.Score)
    }
    // Output:
    // 1. Item: movie_315 (Score: 0.9523)
    // 2. Item: movie_1432 (Score: 0.8891)
    // 3. Item: movie_918 (Score: 0.8456)

    // Get recommendations for a specific category with offset
    comedyRecs, err := gorse.GetRecommend(ctx, "user_001", "Comedy", 5, 0)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Comedy recommendations: %d items", len(comedyRecs))
}
```

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

### User Management - Get Users (Paginated)

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

Retrieves a paginated list of users using cursor-based pagination for large datasets. Returns a list of users and a cursor for the next page.

```APIDOC
## User Management

### GetUsers

Retrieves a paginated list of users using cursor-based pagination for large datasets.

### Method
GET

### Endpoint
/users

#### Query Parameters
- **limit** (int) - Optional - The maximum number of users to return per page. Defaults to 20.
- **cursor** (string) - Optional - The cursor for the next page of results. If omitted, the first page is returned.

### Response
#### Success Response (200)
- **Users** (array of User objects) - A list of user objects.
  - **UserId** (string) - The unique identifier for the user.
  - **Labels** (map[string]any) - Key-value pairs for user profiling.
  - **Comment** (string) - A comment or description for the user.
- **Cursor** (string) - A cursor string to fetch the next page of results. Empty if there are no more pages.

### Response Example
```json
{
  "Users": [
    {
      "UserId": "user_001",
      "Labels": {"age": 24, "gender": "M"},
      "Comment": "Premium subscriber"
    },
    {
      "UserId": "user_002",
      "Labels": {"age": 30, "gender": "F"},
      "Comment": "Standard user"
    }
  ],
  "Cursor": "some_cursor_string"
}
```

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Fetch first page of users (3 per page)
    cursor, err := gorse.GetUsers(ctx, 3, "")
    if err != nil {
        log.Fatal(err)
    }
    for _, user := range cursor.Users {
        log.Printf("User ID: %s, Labels: %v", user.UserId, user.Labels)
    }

    // Fetch next page using cursor
    if cursor.Cursor != "" {
        nextPage, err := gorse.GetUsers(ctx, 3, cursor.Cursor)
        if err != nil {
            log.Fatal(err)
        }
        log.Printf("Next page has %d users", len(nextPage.Users))
    }
}
```
```

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

### Get Single Item in Gorse Go

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

Retrieves a single item by its item ID. Returns the item's metadata, categories, and other details.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Retrieve item by ID
    item, err := gorse.GetItem(ctx, "movie_1234")
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Item: %s, Categories: %v, Timestamp: %v, Comment: %s",
        item.ItemId, item.Categories, item.Timestamp, item.Comment)
    // Output: Item: movie_1234, Categories: [Sci-Fi Action Thriller], Timestamp: 2024-07-21 00:00:00 +0000 UTC, Comment: Inception (2010)
}
```

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

### Get Non-Personalized Recommendations

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

Retrieves non-personalized recommendations from a named source (e.g., popular, trending). Supports category filtering and user context for some sources. Requires an initialized Gorse client.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get popular items (non-personalized)
    popular, err := gorse.GetNonPersonalized(ctx, "popular", "", 10, 0, "")
    if err != nil {
        log.Fatal(err)
    }
    for _, item := range popular {
        log.Printf("Popular: %s (Score: %.4f)", item.Id, item.Score)
    }

    // Get trending items in Comedy category
    trending, err := gorse.GetNonPersonalized(ctx, "trending", "Comedy", 5, 0, "user_001")
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Trending comedy items: %d", len(trending))
}
```

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

### Initialize or Tidy Go Modules

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

Ensures all module dependencies are correctly managed.

```bash
go mod tidy
```

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

### Client Initialization

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

Initializes the Gorse client with the server endpoint and API key for authentication. The client is then ready to make API calls.

```APIDOC
## Client Initialization

### NewGorseClient

Creates a new Gorse client instance with the server endpoint and API key for authentication.

```go
package main

import (
    "context"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    // Initialize the Gorse client with server endpoint and API key
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "your-api-key")
    ctx := context.Background()

    // Client is now ready to make API calls
    user, err := gorse.GetUser(ctx, "user123")
    if err != nil {
        // Handle error
    }
}
```
```

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

### Initialize Gorse Client

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

Create a new Gorse client instance by providing the server endpoint and your API key. This client is then used to make API calls.

```go
package main

import (
    "context"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    // Initialize the Gorse client with server endpoint and API key
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "your-api-key")
    ctx := context.Background()

    // Client is now ready to make API calls
    user, err := gorse.GetUser(ctx, "user123")
    if err != nil {
        // Handle error
    }
}
```

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

### Format Code with go fmt

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

Applies standard Go formatting to all files in the project. This should be run before submitting a pull request.

```bash
go fmt ./...
```

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

### Run Unit Tests

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

Executes all unit tests within the project. Ensure tests are deterministic and use mocks when external dependencies are not required.

```bash
go test ./...
```

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

### List User Feedbacks by Type with Gorse Go Client

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

Retrieves all feedback events of a specific type for a given user. Useful for analyzing user behavior.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Get all "watch" feedback for a user
    feedbacks, err := gorse.ListFeedbacks(ctx, "watch", "user_001")
    if err != nil {
        log.Fatal(err)
    }
    for _, fb := range feedbacks {
        log.Printf("User %s watched %s at %v (value: %.1f)", fb.UserId, fb.ItemId, fb.Timestamp, fb.Value)
    }
    // Output:
    // User user_001 watched movie_001 at 2024-01-15 10:30:00 +0000 UTC (value: 1.0)
    // User user_001 watched movie_002 at 2024-01-15 10:35:00 +0000 UTC (value: 1.0)
}
```

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

### Perform Static Analysis with go vet

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

Runs static analysis checks to catch potential errors and suspicious constructs. This is part of the pre-PR checks.

```bash
go vet ./...
```

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

### Insert User Feedback with Gorse Go Client

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

Inserts multiple user feedback events, such as clicks, views, or ratings, to train the recommendation model. Each feedback event requires a type, user ID, item ID, and optionally a value and timestamp.

```go
package main

import (
    "context"
    "log"
    "time"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Insert multiple feedback events
    feedbacks := []client.Feedback{
        {FeedbackType: "watch", UserId: "user_001", ItemId: "movie_001", Value: 1.0, Timestamp: time.Now().UTC().Truncate(time.Second)},
        {FeedbackType: "like", UserId: "user_001", ItemId: "movie_001", Value: 1.0, Timestamp: time.Now().UTC().Truncate(time.Second)},
        {FeedbackType: "watch", UserId: "user_001", ItemId: "movie_002", Value: 1.0, Timestamp: time.Now().UTC().Truncate(time.Second)},
        {FeedbackType: "rating", UserId: "user_001", ItemId: "movie_002", Value: 4.5, Timestamp: time.Now().UTC().Truncate(time.Second)},
    }
    rowAffected, err := gorse.InsertFeedback(ctx, feedbacks)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Feedback events inserted: %d", rowAffected.RowAffected)
    // Output: Feedback events inserted: 4
}
```

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

### Insert Multiple Items in Gorse Go

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

Inserts multiple items in a single batch request for efficient catalog ingestion. Handles a slice of Item objects.

```go
package main

import (
    "context"
    "log"
    "time"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Batch insert multiple items
    items := []client.Item{
        {ItemId: "movie_001", Categories: []string{"Animation", "Comedy"}, Timestamp: time.Date(1995, 1, 1, 0, 0, 0, 0, time.UTC), Comment: "Toy Story (1995)"},
        {ItemId: "movie_002", Categories: []string{"Drama", "War"}, Timestamp: time.Date(1996, 1, 22, 0, 0, 0, 0, time.UTC), Comment: "Richard III (1995)"},
        {ItemId: "movie_003", Categories: []string{"Crime", "Drama", "Thriller"}, Timestamp: time.Date(1997, 2, 14, 0, 0, 0, 0, time.UTC), Comment: "Fargo (1996)"},
    }
    rowAffected, err := gorse.InsertItems(ctx, items)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Items inserted: %d", rowAffected.RowAffected)
    // Output: Items inserted: 3
}
```

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

### User Data Model

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

Defines the structure for a user in the Gorse system, including ID, labels, and comments.

```go
type User struct {
    UserId  string `json:"UserId"`   // Unique user identifier
    Labels  any    `json:"Labels"`   // User attributes (map[string]any for demographics, preferences)
    Comment string `json:"Comment"`  // Optional user description
}
```

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

### Retrieve Single User

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

Fetch a user's details, including their ID, labels, and comments, by providing their unique user ID.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Retrieve user by ID
    user, err := gorse.GetUser(ctx, "user_001")
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("User: %s, Labels: %v, Comment: %s", user.UserId, user.Labels, user.Comment)
    // Output: User: user_001, Labels: map[age:24 gender:M occupation:engineer zip_code:94102], Comment: Premium subscriber
}
```

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

### Feedback Data Model

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

Defines the structure for user-item interaction events, including type, user/item IDs, value, and timestamp.

```go
type Feedback struct {
    FeedbackType string    `json:"FeedbackType"` // Type of interaction (watch, like, purchase, rating)
    UserId       string    `json:"UserId"`       // User who performed the action
    ItemId       string    `json:"ItemId"`       // Item that was interacted with
    Value        float64   `json:"Value"`        // Interaction strength (1.0 for binary, rating value for ratings)
    Timestamp    time.Time `json:"Timestamp"`    // When the interaction occurred
}
```

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

### Insert Multiple Users

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

Efficiently insert multiple users in a single batch request. The function returns the number of users inserted.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Batch insert multiple users
    users := []client.User{
        {UserId: "user_101", Labels: map[string]any{"age": 30, "gender": "F"}, Comment: "User A"},
        {UserId: "user_102", Labels: map[string]any{"age": 25, "gender": "M"}, Comment: "User B"},
        {UserId: "user_103", Labels: map[string]any{"age": 35, "gender": "F"}, Comment: "User C"},
    }
    rowAffected, err := gorse.InsertUsers(ctx, users)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Users inserted: %d", rowAffected.RowAffected)
    // Output: Users inserted: 3
}
```

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

### Item Data Model

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

Defines the structure for an item in the Gorse system, including ID, visibility, labels, categories, and timestamp.

```go
type Item struct {
    ItemId     string    `json:"ItemId"`     // Unique item identifier
    IsHidden   bool      `json:"IsHidden"`   // Whether item is hidden from recommendations
    Labels     any       `json:"Labels"`     // Item attributes (embeddings, metadata)
    Categories []string  `json:"Categories"` // Item categories for filtering
    Timestamp  time.Time `json:"Timestamp"`  // Item creation/publish time
    Comment    string    `json:"Comment"`    // Item description
}
```

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

### User Management API

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

APIs for managing users within the Gorse system, including updating and deleting users.

```APIDOC
## UpdateUser

### Description
Updates an existing user's labels or comment using a patch object with optional fields.

### Method
PATCH

### Endpoint
`/users/{userId}`

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user to update.

#### Request Body
- **Labels** (map[string]any) - Optional - A map of labels to associate with the user.
- **Comment** (*string) - Optional - A pointer to a string containing a comment for the user.

### Request Example
```json
{
  "Labels": {"subscription": "premium", "tier": "gold"},
  "Comment": "VIP subscriber since 2024"
}
```

### Response
#### Success Response (200)
- **RowAffected** (int) - The number of rows affected by the update operation.

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

## DeleteUser

### Description
Deletes a user from the Gorse system by their user ID.

### Method
DELETE

### Endpoint
`/users/{userId}`

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user to delete.

### Response
#### Success Response (200)
- **RowAffected** (int) - The number of users deleted.

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

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

### User Management - Insert User

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

Inserts a single user into the Gorse system with optional labels and comments for user profiling. Returns the number of rows affected.

```APIDOC
## User Management

### InsertUser

Inserts a single user into the Gorse system with optional labels and comments for user profiling.

### Method
POST

### Endpoint
/users

### Request Body
- **UserId** (string) - Required - The unique identifier for the user.
- **Labels** (map[string]any) - Optional - Key-value pairs for user profiling.
- **Comment** (string) - Optional - A comment or description for the user.

### Request Example
```json
{
  "UserId": "user_001",
  "Labels": {"age": 24, "gender": "M", "occupation": "engineer", "zip_code": "94102"},
  "Comment": "Premium subscriber"
}
```

### Response
#### Success Response (200)
- **RowAffected** (int64) - The number of rows affected by the insert operation.

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

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Insert a user with demographic labels
    rowAffected, err := gorse.InsertUser(ctx, client.User{
        UserId:  "user_001",
        Labels:  map[string]any{"age": 24, "gender": "M", "occupation": "engineer", "zip_code": "94102"},
        Comment: "Premium subscriber",
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Rows affected: %d", rowAffected.RowAffected)
    // Output: Rows affected: 1
}
```
```

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

### Update User in Gorse Go

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

Updates an existing user's comment and labels. Ensure the user ID exists before attempting an update.

```go
package main

import (
    "context"
    "log"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Update user's comment and labels
    newComment := "VIP subscriber since 2024"
    patch := client.UserPatch{
        Labels:  map[string]any{"subscription": "premium", "tier": "gold"},
        Comment: &newComment,
    }
    rowAffected, err := gorse.UpdateUser(ctx, "user_001", patch)
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Rows affected: %d", rowAffected.RowAffected)
    // Output: Rows affected: 1
}
```

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

### Item Management API

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

APIs for managing items in the Gorse catalog, including insertion, retrieval, and batch operations.

```APIDOC
## InsertItem

### Description
Inserts a single item into the catalog with categories, labels, timestamp, and visibility settings.

### Method
POST

### Endpoint
`/items`

### Request Body
- **ItemId** (string) - Required - The unique identifier for the item.
- **IsHidden** (bool) - Optional - Whether the item is hidden from recommendations.
- **Labels** (map[string]any) - Optional - A map of labels associated with the item.
- **Categories** ([]string) - Optional - A list of categories the item belongs to.
- **Timestamp** (time.Time) - Optional - The timestamp when the item was added or last updated.
- **Comment** (string) - Optional - A descriptive comment for the item.

### Request Example
```json
{
  "ItemId": "movie_1234",
  "IsHidden": false,
  "Labels": {"embedding": [0.1, 0.2, 0.3], "director": "Christopher Nolan"},
  "Categories": ["Sci-Fi", "Action", "Thriller"],
  "Timestamp": "2024-07-21T00:00:00Z",
  "Comment": "Inception (2010)"
}
```

### Response
#### Success Response (200)
- **RowAffected** (int) - The number of items inserted.

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

## InsertItems

### Description
Inserts multiple items in a single batch request for efficient catalog ingestion.

### Method
POST

### Endpoint
`/items/batch`

### Request Body
- **Items** ([]Item) - Required - A list of items to insert.
  - **ItemId** (string) - Required - The unique identifier for the item.
  - **IsHidden** (bool) - Optional - Whether the item is hidden from recommendations.
  - **Labels** (map[string]any) - Optional - A map of labels associated with the item.
  - **Categories** ([]string) - Optional - A list of categories the item belongs to.
  - **Timestamp** (time.Time) - Optional - The timestamp when the item was added or last updated.
  - **Comment** (string) - Optional - A descriptive comment for the item.

### Request Example
```json
[
  {
    "ItemId": "movie_001",
    "Categories": ["Animation", "Comedy"],
    "Timestamp": "1995-01-01T00:00:00Z",
    "Comment": "Toy Story (1995)"
  },
  {
    "ItemId": "movie_002",
    "Categories": ["Drama", "War"],
    "Timestamp": "1996-01-22T00:00:00Z",
    "Comment": "Richard III (1995)"
  },
  {
    "ItemId": "movie_003",
    "Categories": ["Crime", "Drama", "Thriller"],
    "Timestamp": "1997-02-14T00:00:00Z",
    "Comment": "Fargo (1996)"
  }
]
```

### Response
#### Success Response (200)
- **RowAffected** (int) - The number of items inserted.

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

## GetItem

### Description
Retrieves a single item by its item ID including all metadata and categories.

### Method
GET

### Endpoint
`/items/{itemId}`

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

### Response
#### Success Response (200)
- **ItemId** (string) - The unique identifier of the item.
- **IsHidden** (bool) - Whether the item is hidden.
- **Labels** (map[string]any) - Labels associated with the item.
- **Categories** ([]string) - Categories the item belongs to.
- **Timestamp** (time.Time) - The timestamp of the item.
- **Comment** (string) - A descriptive comment for the item.

#### Response Example
```json
{
  "ItemId": "movie_1234",
  "IsHidden": false,
  "Labels": {"embedding": [0.1, 0.2, 0.3], "director": "Christopher Nolan"},
  "Categories": ["Sci-Fi", "Action", "Thriller"],
  "Timestamp": "2024-07-21T00:00:00Z",
  "Comment": "Inception (2010)"
}
```

## GetItems

### Description
Retrieves a paginated list of items using cursor-based pagination.

### Method
GET

### Endpoint
`/items`

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of items to return per page. Defaults to 10.
- **cursor** (string) - Optional - The cursor for fetching the next page of results. If omitted, the first page is returned.

### Response
#### Success Response (200)
- **Items** ([]Item) - A list of items.
  - **ItemId** (string) - The unique identifier of the item.
  - **IsHidden** (bool) - Whether the item is hidden.
  - **Labels** (map[string]any) - Labels associated with the item.
  - **Categories** ([]string) - Categories the item belongs to.
  - **Timestamp** (time.Time) - The timestamp of the item.
  - **Comment** (string) - A descriptive comment for the item.
- **Cursor** (string) - The cursor for fetching the next page of results. An empty string indicates the last page.

#### Response Example
```json
{
  "Items": [
    {
      "ItemId": "movie_1234",
      "IsHidden": false,
      "Labels": {"embedding": [0.1, 0.2, 0.3], "director": "Christopher Nolan"},
      "Categories": ["Sci-Fi", "Action", "Thriller"],
      "Timestamp": "2024-07-21T00:00:00Z",
      "Comment": "Inception (2010)"
    }
  ],
  "Cursor": "some_opaque_cursor_string"
}
```
```

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

### Insert Single Item in Gorse Go

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

Inserts a single item into the catalog. Supports setting categories, labels, timestamp, and visibility.

```go
package main

import (
    "context"
    "log"
    "time"
    client "github.com/gorse-io/gorse-go"
)

func main() {
    gorse := client.NewGorseClient("http://127.0.0.1:8088", "api_key")
    ctx := context.Background()

    // Insert a movie item with embedding labels
    rowAffected, err := gorse.InsertItem(ctx, client.Item{
        ItemId:     "movie_1234",
        IsHidden:   false,
        Labels:     map[string]any{"embedding": []any{0.1, 0.2, 0.3}, "director": "Christopher Nolan"},
        Categories: []string{"Sci-Fi", "Action", "Thriller"},
        Timestamp:  time.Date(2024, 7, 21, 0, 0, 0, 0, time.UTC),
        Comment:    "Inception (2010)",
    })
    if err != nil {
        log.Fatal(err)
    }
    log.Printf("Items inserted: %d", rowAffected.RowAffected)
    // Output: Items inserted: 1
}
```

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

### SessionRecommend API

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

Provides session-based recommendations for anonymous users based on their current session's interactions.

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

### Description
Provides session-based recommendations for anonymous users based on their current session's interactions without requiring a persistent user profile.

### Method
POST

### Endpoint
/api/session-recommend

### Request Body
- **feedback** (array) - Required - A list of user interactions within the current session. Each object should have:
  - **FeedbackType** (string) - Type of interaction (e.g., "view", "click", "purchase").
  - **ItemId** (string) - The ID of the item interacted with.
  - **Timestamp** (string) - The time of the interaction in ISO 8601 format.
- **n** (integer) - Required - The number of recommendations to retrieve.

### Request Example
```json
{
  "feedback": [
    {
      "FeedbackType": "view",
      "ItemId": "movie_001",
      "Timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "FeedbackType": "click",
      "ItemId": "movie_001",
      "Timestamp": "2023-10-27T10:01:00Z"
    }
  ],
  "n": 10
}
```

### Response
#### Success Response (200)
- **recommendations** (array) - A list of recommended items, each with an `Id` (string) and `Score` (float64).

### Response Example
```json
[
  {
    "Id": "movie_045",
    "Score": 0.85
  },
  {
    "Id": "movie_002",
    "Score": 0.82
  }
]
```
```

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

### InsertFeedback

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

Inserts user feedback (interactions) such as clicks, views, purchases, or ratings to train the recommendation model.

```APIDOC
## POST /api/feedback

### Description
Inserts user feedback (interactions) such as clicks, views, purchases, or ratings to train the recommendation model.

### Method
POST

### Endpoint
/api/feedback

### Request Body
- **feedbacks** (array of objects) - Required - A list of feedback events to insert.
  - **FeedbackType** (string) - Required - The type of feedback (e.g., "click", "view", "purchase", "rating").
  - **UserId** (string) - Required - The ID of the user providing the feedback.
  - **ItemId** (string) - Required - The ID of the item the feedback is related to.
  - **Value** (number) - Optional - A numerical value associated with the feedback (e.g., rating score).
  - **Timestamp** (string) - Optional - The timestamp of the feedback event. Format: RFC3339

### Request Example
```json
[
  {"FeedbackType": "watch", "UserId": "user_001", "ItemId": "movie_001", "Value": 1.0, "Timestamp": "2024-01-15T10:30:00Z"},
  {"FeedbackType": "like", "UserId": "user_001", "ItemId": "movie_001", "Value": 1.0, "Timestamp": "2024-01-15T10:31:00Z"},
  {"FeedbackType": "watch", "UserId": "user_001", "ItemId": "movie_002", "Value": 1.0, "Timestamp": "2024-01-15T10:35:00Z"},
  {"FeedbackType": "rating", "UserId": "user_001", "ItemId": "movie_002", "Value": 4.5, "Timestamp": "2024-01-15T10:36:00Z"}
]
```

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

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