Installing the Shaped SDK

The Shaped SDK simplifies interactions with Shaped's Model Inference APIs making it easier to integrate our services into your applications.

This guide will walk you through the installation process for different programming languages.

Install the SDK

JavaScript

Install

npm install @shaped.ai/client

Python

Install

pip install shaped

Verify Installation

Use the following commands to verify the packages have installed correctly.

JavaScript

npm list @shaped.ai/client

Python

pip show shaped

Rank Endpoint

Rank returns a list of relevant item_ids (from most-relevant to least) for the given request context. Here's how to use the SDK to get recommendations using the Rank endpoint:

JavaScript

const {rank} = require("@shaped.ai/client").Client('your_api_key')

// Get item recommendations for a user.
recommendations = rank({
  model_name: "your_model_name",
  user_id: "user_id",
})

// Get metadata for recommended items.
recommendations = rank({
  model_name: "your_model_name",
  user_id: "user_id",
  return_metadata: true,
})

// Get items with certain features.
recommendations = rank({
  model_name: "your_model_name",
  user_id: "user_id",
  filter_predicate: "category = 'sports' AND price < 100",
})  

// Advanced: Custom Inference Configuration Settings.
recommendations = rank({
  model_name: "your_model_name",
  user_id: "user_id",
  config: {
    exploration_factor: 0.1,
    diversity_factor: 0.1,
    limit: 10,
    retriever_k_override: {
      knn: 300,
      chronological: 100,
      popular: 100,
      trending: 300,
      random: 0,
      cold_start: 300,
    }
  }
})

Python

from shaped import ShapedClient
client = ShapedClient(api_key="your_api_key")

# Get recommended items for a user.
recommendations = client.rank(
    model_name="your_model_name",
    user_id="user_id",
)

# Get metadata for recommended items.
recommendations = client.rank(
  model_name="your_model_name",
  user_id="user_id",
  return_metadata=True,
)

# Get items with certain features.
recommendations = client.rank(
  model_name="your_model_name",
  user_id="user_id",
  filter_predicate="category = 'sports' AND price < 100",
)

# Advanced: Custom Inference Configuration Settings.
recommendations = client.rank(
  model_name="your_model_name",
  user_id="user_id",
  config=shaped.InferenceConfig(
    exploration_factor=0.1,
    diversity_factor=0.1,
    diversity_attributes=["category", "brand"],
    retreieval_k=100,
    retriever_k_override=shaped.RetrieverTopKOverride(
      knn=300,
      chronological=100,
      popular=100,
      trending=300,
      random=0,
      cold_start=300,
    )
    limit=10,
  )
)

Retrieve Endpoint

The retrieve endpoint returns relevant item_ids for the given text_query or user query. It can be used if the filtering, scoring and ordering stages aren't needed for the final ranking. Typically people use this over the rank endpoint if they want to reduce latency or complexity of the ranking pipeline and only need a subset of the functionality, e.g search without personalization. Here's how to use the Retrieve endpoint with the SDK:

Python

from shaped import ShapedClient
client = ShapedClient(api_key="your_api_key")

# Retrieve items for a user.
retrieved_items = client.retrieve(
  model_name="your_model_name",
  user_id="user_id",
)

# Retrieve items with certain features.
retrieved_items = client.retrieve(
  model_name="your_model_name",
  user_id="user_id",
  filter_predicate="category = 'sports' AND price < 100",
)

# Retrieve items using a text query.
retrieved_items = client.retrieve(
  model_name="your_model_name",
  user_id="user_id",
  query="brown cardigans and sweaters",
)

# Advanced: Custom Inference Configuration Settings.
retrieved_items = client.retrieve(
  model_name="your_model_name",
  user_id="user_id",
  config=shaped.InferenceConfig(
    limit=10,
    retriever_k_override=shaped.RetrieverTopKOverride(
      knn=300,
      chronological=100,
      popular=100,
      trending=300,
      random=0,
      cold_start=300,
    )
  )
)