Overview

As described in KPI Concepts , there are two steps to managing KPIs in Pay-i. The first is to define the KPI for a use case, and the second is to provide the scores, or data, for those KPIs.

You can accomplish both steps either in the Pay-i UI or via the SDK. However, since data entry for the KPIs would be extremely manual, it is highly recommended to set the KPI scores in your application's code.

🕹️Managing Use Cases and KPIs in the UI

The following interactive tutorial walks through how to manage use cases and KPIs in the Pay-i UI.

For the best experience, maximize the interactive tutorial and turn on audio.

Managing KPIs in your Application Code

The SDK provides methods for:

• Creating KPI definitions for use case types
• Recording KPI values for specific use case instances
• Retrieving, updating, and deleting KPI data

As with all Pay-i types, KPI definition is idempotent, and repeated creation calls will not result in failures or duplication.

from payi import Payi

client = Payi()

# Step 1: Define a KPI for a use case type
client.use_cases.definitions.kpis.create(
    use_case_name="Chat-Bot",
    kpi_name="Deflection Rate",
    description="Tracks when AI resolves issues without human intervention",
    kpi_type="boolean",
    goal=0.25
)

# Step 2: Record a score for a specific instance
client.use_cases.kpis.create(
    kpi_name="Deflection Rate",
    use_case_id="uc_123456789",
    score=True
)

Use Case Instance IDs

KPI scores are always associated with a specific use case instance, identified by a use_case_id. This connection ensures that your custom metrics are linked to the exact context in which they were generated, providing a comprehensive view alongside the standard metrics Pay-i already tracks:

client.use_cases.kpis.create(
    kpi_name="Customer Satisfaction",  	# Likert5 KPI
    use_case_id=use_case_id, 						# ID of the instance to set the score
    score=4  														# Rating on 1-5 scale
)

If you did not define the use_case_id when creating the instance, then Pay-i will automatically assign one for you. The generated use_case_id can be retrieved using get_context().

 from payi.lib.instrument import get_context

def print_use_case_info():
  context = get_context()
    
  if context.get("use_case_name", ''):
      print(
          f"Current use case: {context.get('use_case_name')} "
          f"(ID: {context.get('use_case_id', '')}, "
          f"Version: {context.get('use_case_version', '')})"
      )

      if context.get("use_case_step"):
          print(f"Current step: {context.get('use_case_step')}")
  else:
      print("No use case active in current context")

KPI Types and Scores

The scores for each KPI Type must be represented in the following value types.

Ingesting KPI scores from other systems

Your KPI data may live in a variety of systems that live apart from your GenAI code or the Pay-i library. The API to set KPI scores is available via a standard REST interface so that it can be called from virtually anywhere and from any programming language, without the need for the Pay-i SDK.

Note that the use_case_id and kpi_name are represented in the URL path.

curl --request PUT \
     --url https://api.pay-i.com/api/v1/use_cases/instances/your_use_case_id/kpis/your_kpi_name \
     --header 'accept: application/json' \
     --header 'content-type: application/*+json' \
     --header 'xProxy-api-key: your_payi_api_key' \
     --data '{"score":123}'