High-Level Flow

1. Define one or more use cases.
2. Associate use_case_id with a use case, either implicitly or explicitly.

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 usinguse_case_name in a payi instrumentation call and Pay-i will automatically create the use case defintion.

Use Case Naming Requirements

Use case names must follow these requirements:

• Must be unique within your application
• Must contain only alphanumeric characters, periods (.), hyphens (-), and underscores (_)
• No spaces are allowed
• Maximum length is 64 characters
• Names are case-sensitive when referenced in code

Pay-i's convention is to use lowercase with underscores (snake_case) for use case names.

Example Use Case 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.

When summarizing a document, David calls passes use_case_name = document_summarization to either track_context() or @track or In the context of these payi instrumentation functions, he makes N inference calls to summarize a document. Each of these calls will be assocated with the same use_case_id. The next time the same code executes a newuse_case_id will be used.

David does the same for each new conversation his users have with the chatbot. At the start of the conversation, he calls @track or track_context()with use_case_name=document_chatbotand Pay-i takes care of the rest!

Controlling how use_case_id values are created

Once you have created the use case, there are several ways to specify use_case_id. Creation and association of a use_case_id with your inference calls is flexible and meant to be easily added to your existing workflow.

Use case instances do not have an explicit end or delete management API. Simply, use use_case_id for as long as it makes sense for your implementation. The timespan between two uses of a use_case_id value can be seconds, minutes, or days.

1. Automaticuse_case_id values

When calling track_context() or @track and passing use_case_name , but not specifying ause_case_id value, the Pay- instrumentation will create a use_case_id that will be applied to all inference calls in the scope of these function contexts. This works very well for one shot executions that exit after executing or when the use_case_id does not need to be correlated with an another identifier.

from payi.lib.instrument import payi_instrument
from payi.lib.instrument import track, track_context

payi_instrument()

def make_inference_call():
  with track_context(use_case_name="quickstart_usecase"):
    # inference call
    ...
    
@track(use_case_name="quickstart_usecase")
def decorated_make_inference_call():
  # inference call
  ...

2. Specifying your own use_case_id value

You can specify your ownuse_case_id value intead of the automatically created one. The actual use_case_id value is completely up to you, there are no restrictions . For instance, the use_case_id can be an external correlation identifier, like a service ticket identifier, or a user session identifier in a web server middleware.

This pattern works when your inference calls

1. Should be correlated with an external identifier
2. Are a part of a web server
3. Are part of a workflow where a broadly scoped payi instrumentation context cannot be used.

from payi.lib.instrument import payi_instrument
from payi.lib.instrument import track_context

payi_instrument()

def make_inference_call(service_ticket_id: str):
  with track_context(use_case_name="quickstart_usecase", use_case_id=service_ticket_id):
    # inference call
    ...

3. Other ways to create a use_case_id

The following ways to create a use_case_id are not recommend for normal use. They are documented to provide a complete picture of how to manage use_case_id creation.

1. Explicitly generating an ID

Call the Create New Use Case API to generate a use_case_id for a use_case_name. This is functionally equivalent specifying a use_case_id value as described above.

from payi import Payi

# Initialize the client
payi_client = Payi()  # API key loaded from environment variable

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

2. The payi service generates a use_case_id during request processing

When ause_case_name is passed in to ingest or a proxied request, but use_case_id is not specified, the Pay-i service will automatically create a new use case instance and return the new use_case_id in the xproxy_result so it can be used for future API calls. Your code must then store the returned use_case_id and specify it on subsequent inference calls. Because of the complicated logic to check, store, and reuse this approach is not recommended for normal.

Explicitly creating use case definitions

For information on explicitly creating and initializing use case defnitions, see the Payi Clients documentation.

from payi import Payi

payi_client = Payi()  

uc_response = payi_client.use_cases.definitions.create(
    name="quickstart_usecase",
    description="An example use case."
)