Jan 5, 2024

Guidelines

Example Usage

how to use Leora in the real world

Leora’s e-commerce clients can leverage the following example workflow to onboard data, train models, and fetch recommendations.

Sample Data Upload

Assume you have three files in S3:

{
  "profiles": [
    {"user_id": "U1001", "age": 35, "region": "US"},
    {"user_id": "U1002", "age": 27, "region": "EU"}
  ],
  "interactions": [
    {"user_id": "U1001", "item_id": "P5001", "timestamp": "2025-04-20T14:32:00Z", "event_type": "view"},
    {"user_id": "U1001", "item_id": "P3029", "timestamp": "2025-04-20T14:35:00Z", "event_type": "add_to_cart"},
    {"user_id": "U1002", "item_id": "P5001", "timestamp": "2025-04-21T10:10:00Z", "event_type": "purchase"}
  ],
  "content": [
    {"item_id": "P5001", "title": "Wireless Earbuds", "category": "Electronics", "tags": ["audio","bluetooth"], "price": 99.99},
    {"item_id": "P3029", "title": "Running Shoes", "category": "Sportswear", "tags": ["fitness","shoes"]

Sequence of API Calls

0. Authentication (Client Credentials Flow)


Response (200 OK):


1. Create Datastore


Response (201 Created):


2. Start Training


Response (202 Accepted):


3. Check Training Status


Response (200 OK):

{
  "train_job_id": "job_abc123",
  "status": "running",
  "current_epoch": 2,
  "progress_pct": 25.0,
  "elapsed_time_sec": 3600,
  "metrics_history": [
    {"epoch":1, "ndcg@20":0.120, "recall@20":0.200},
    {"epoch":2, "ndcg@20":0.135, "recall@20":0.215}
  ]

4a. Session-Based Recommendations

curl -X GET "https://api.heyleora.com/v1/datastores/ds_ecom123/recommendations/session?session=[\"P5001\",\"P3029\"]

Response (200 OK):

{
  "session": ["P5001","P3029"],
  "recommendations": [
    {"item_id": "P7123", "score": 0.912},
    {"item_id": "P4234", "score": 0.897},
    {"item_id": "P8392", "score": 0.885},
    {"item_id": "P2156", "score": 0.872},
    {"item_id": "P3345", "score": 0.860}
  ],
  "explanations": [
    {"item_id":"P7123","tokens":["audio","wireless"]

4b. User-Based Recommendations


Response (200 OK):

{
  "user_id": "U1001",
  "recommendations": [
    {"item_id": "P3029", "score": 0.975},
    {"item_id": "P5001", "score": 0.962},
    {"item_id": "P8341", "score": 0.948},
    {"item_id": "P1290", "score": 0.934},
    {"item_id": "P6523", "score": 0.920}
  ],
  "explanations": [
    {"item_id":"P3029","tokens":["sportswear","fitness"]

Copyright Leora 2025 - All Right Reserved

Copyright Leora 2025 - All Right Reserved

Copyright Leora 2025 - All Right Reserved