Using Experiences

High-Level Flow

1. Define one or more Experience Types.
2. At runtime, create an instance of an Experience Type, called an Experience, which has an associated experience-id.
3. Make any number of requests or Ingest any number of events associated with the experience while passing in the experience-id.

Example Scenario

David, a developer using Pay-i, defines two Experience Types for his application:

1. Document_Summarization, which is performed using a series of API calls to accomplish a complex summarization scenario.
2. Document_Chatbot, which is a bot that allows a user to ask questions/converse with their documents.

Before summarizing a document, David calls the Pay-i API to create a new instance of the Document_Summarization Experience Type, receiving an experience-id. Then, when making the API calls to summarize a document, he passes in that experience-id. The next time he needs to summarize a document, he creates a new instance of the Document_Summarization Experience Type, generating a fresh experience-id, and passes this new ID along to each of the calls.

David does the same for each new conversation his users have with the chatbot. At the start of the conversation, he creates a new experience-id of the Document_Chatbot experience and passes it in for each call made as part of the conversations. Pay-i takes care of the rest!

Experience Types

An Experience Type represents an end-to-end scenario in your product or service which is composed of multiple cost-generating actions, such as API calls to Resources. It may make sense to align your Experience Types with your billable features.

Creating an Experience Type is as simple as defining the experience_name and a plaintext description of the type (used for display purposes).

exp_name="quickstart_experience"
# Create an experience type
exp_type_response = payi_client.experiences.types.create(
    name=exp_name,
    description="An example experience type."
)

Once created, instances of that Experience Type, called Experiences, are used to track its overall cost statistics.

Creating Experiences

Once you have created the type, there are several ways to create an experience and generate a new experience_id.

When making any requests that are a part of this experience, simply pass the experience_id in as the value for the xProxy-Experience-Id header and Pay-i takes care of the rest. Once generated, experiences do not ever need to be “closed” or “terminated”. The experience_id can simply be discarded when it is no longer needed (such as when the task or workflow has completed).

1. Generate an ID as part of a Request

The easiest way to create a new experience is when making the first request that is part of that experience.

You can pass in an experience_name in the xProxy-Experience-Name header and Pay-i will automatically create a new experience of that type, execute the request normally as part of the experience, and then return the new experience_id in the xproxy_result so it can be used for future API calls that are part of that experience.

This approach is recommended because it removes the need for an extra roundtrip to the Pay-i service just to create a new experience_id.

2. Explicitly Generate an ID

You can call the Create New Experience API to generate an experience_id given an experience_name.

# Create an experience of the type
exp_response = payi_client.experiences.create(
    experience_name=exp_name,
)
experience_id = exp_response.experience_id

This method is recommended for when you want to make multiple, simultaneous API calls that are part of the same experience and need to have the experience_id upfront to do so.

3. Pass in your own GUID

When making a request, you can specify any valid GUID as the value for the xProxy-Experience-Id header. This will be treated as the experience_id as-is. Note that using your own values for the experience_id means you will need to ensure that the GUIDs you pass in are unique between separate experiences.

If you pass in an invalid GUID as the experience_id, Pay-i will generate a valid experience_id for the request automatically and return it in the xproxy_result. We are seeking feedback on this behavior, so please feel free to mail us at [email protected] with comments or suggestions.

This method is recommended for when you want to have Pay-i's records match your software's records for validation and audit purposes, or for when you want to Ingest historical data where the requests have already been made.

Making Requests with Experiences

The experience_id is passed in via the xProxy-Experience-Id header when making requests or Ingesting events. If you are using the Pay-i SDK, then the experience_id can simply be passed in with the create_headers method:

exp_response = payi_client.experiences.create(
    experience_name=exp_name,
)
response = oai_client.chat.completions.create(
    model="gpt-3.5-turbo", 
    messages=[{"role": "user", "content": "Say 'this is a test'"}],
    extra_headers=create_headers(
        experience_id=exp_response.experience_id
    )
)

That’s it! All the cost calculation and attribution is automatically handled by Pay-i.

Versioning

As your Experiences continue to evolve you will likely want to track their different versions explicitly. Pay-i supports this with Experience Versioning.