Recombee Writer for Keboola

A Keboola Writer component that uploads items, users, and interactions to Recombee.

---

✨ Features

• Uploads Items Catalog and Users Catalog
• Supports all standard Recombee interactions:
  • AddDetailView
  • AddPurchase
  • AddRating
  • AddBookmark
  • AddCartAddition
  • SetViewPortion
• Supports optional fields (e.g., timestamp, recomm_id, additional_data)
• Gracefully handles bad data (e.g. NaN, invalid types) and logs summarizations
• Retries on timeouts and server-side errors

---

🔧 Configuration Parameters

Set via Keboola UI or config.json:

{
  "parameters": {
    "database_id": "your-recombee-db-id",
    "#private_token": "your-recombee-private-token",
    "region": "eu-west"
  }
}

---

🧱 Input Structure

Place CSV files in the standard Keboola input directory:
/data/in/tables/

Supported filenames:

Filename	Request Type
items.csv	Set Item Values
users.csv	Set User Values
detail_views.csv	Add Detail View
purchases.csv	Add Purchase
ratings.csv	Add Rating
bookmarks.csv	Add Bookmark
cart_additions.csv	Add Cart Addition
view_portions.csv	Set View Portion

---

📤 Example Input: detail_views.csv

user_id,item_id,timestamp,recomm_id,additional_data
user-1,item-10,2025-07-06T21:12:43Z,644c005f-aa99-4bce-aa55-a0c610e80df0,"{""source"": ""newsletter""}"
user-2,item-09,2025-07-06T21:09:13Z,,"{""source"": ""newsletter""}"
user-3,item-05,2025-07-06T21:14:45Z,2d2eb48f-cd65-421a-943b-0e015055fd8e,"{""source"": ""homepage""}"

📤 Example Input: items.csv

Properties (columns) shall be created in the Recombee Admin UI.

item_id,title,price,available,date_added,tags
item-01,Wireless Mouse,25.99,true,2025-07-20T10:11:49.039302,"[""electronics"", ""accessory"", ""mouse""]"
item-42,Mechanical Keyboard,75.49,false,2025-08-04T10:11:49.039318,"[""electronics"", ""keyboard""]"
item-77,USB-C Hub,34.9,true,2025-08-19T10:11:49.039321,"[""electronics"", ""usb"", ""hub""]"

---

🐳 Local Development

Build the Docker image:

docker build -t recombee-writer .

Run locally with test data:

docker run --rm -v $(pwd)/data:/data recombee-writer

---

📋 Error Handling

• Retries on:
  • ResponseException (5xx status codes)
  • ApiTimeoutException
• Aggregates and logs:
  • Success/failure counts
  • Example errors (up to 5)
  • Error code frequency

---

🛠 Tech Stack

• Python 3.11
• Recombee Python API Client
• Dockerized for Keboola compatibility

---

📄 License

The Recombee Writer for Keboola is provided under the MIT License.