High-Level Flow

1. Define one or more Use Cases.
2. At runtime, create an Instance of a Use Case, which has an associated use_case_id.
3. Make any number of requests or Ingest any number of events associated with the use case while passing in the use_case_id.

Example Scenario

David, a developer using Pay-i, defines two Use Cases 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 Use Case, receiving a use_case_id. Then, when making the API calls to summarize a document, he passes in that use_case_id. The next time he needs to summarize a document, he creates a new Instance of the Document_Summarization Use Case, generating a fresh use_case_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 use_case_id of the Document_Chatbot use case and passes it in for each call made as part of the conversations. Pay-i takes care of the rest!

Use Cases

A Use Case 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 Use Cases with your billable features.

Creating a Use Case is as simple as defining the use_case_name and a plaintext description of the type (used for display purposes).

uc_name="quickstart_usecase"
# Create a use case
uc_response = payi_client.usecases.types.create(
    name=uc_name,
    description="An example use case."
)

Once created, Instances of that Use Case are used to track its overall cost statistics.

Creating Use Case Instances

Once you have created the Use Case, there are several ways to create a Use Case Instance and generate a new use_case_id.

When making any requests that are a part of this Use Case, simply pass the use_case_id in as the value for the xProxy-UseCase-ID header and Pay-i takes care of the rest. Once generated, Use Case Instances do not ever need to be “closed” or “terminated”. The use_case_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 Instance is when making the first request that is part of that Use Case.

You can pass in an use_case_name in the xProxy-UseCase-Name header and Pay-i will automatically create a new Use Case Instance, execute the request normally as part of the Use Case, and then return the new use_case_id in the xproxy_result so it can be used for future API calls that are part of that Use Case.

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

2. Explicitly Generate an ID

You can call the Create New Use Case API to generate a use_case_id given a use_case_name.

# Create a use case instance
uc_response = payi_client.usecases.create(
    use_case_name=uc_name,
)
uc_id = uc_response.use_case_id

This method is recommended for when you want to make multiple, simultaneous API calls that are part of the same Use Case and need to have the use_case_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-UseCase-ID header. This will be treated as the use_case_id as-is. Note that using your own values for the use_case_id means you will need to ensure that the GUIDs you pass in are unique between separate use case instances.

If you pass in an invalid GUID as the use_case_id, Pay-i will generate a valid use_case_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 Use Case Requests

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

uc_response = payi_client.usecases.create(
    use_case_name=uc_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(
        uc_id=uc_response.use_case_id
    )
)

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

Versioning

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