Mixins

This file contains the mixins for the provider model.

class smarter.apps.provider.services.text_completion.lib.mixins.ChatDbMixin(*args, **kwargs)[source]

Bases: AccountMixin

Mixin for database-related methods for provider models.

This mixin provides database access and persistence logic for prompt provider models, including management of prompt sessions, prompt history, plugin/tool usage, and charge records. It is intended to be used as a base class for provider implementations that require integration with the Smarter database models. This provides layers of abstraction for asynchronously creating history and charge records resulting from provider requests.

Key Features:

Manages retrieval and caching of prompt, prompt history, tool calls, plugin usage, and charge records.

Provides properties for accessing and updating prompt-related data.

Supports insertion of new tool call, plugin usage, and charge records via asynchronous tasks.

Aggregates token usage statistics for billing and analytics.

Usage:

Inherit from this mixin in a provider class to enable database-backed prompt session and usage tracking.

Example:

class MyProvider(ChatDbMixin):
    def custom_method(self):
        # Access prompt history
        history = self.prompt_history
        # Insert a charge
        self.db_insert_charge(...)

__init__(*args, **kwargs)[source]

Initialize the ChatDbMixin.

This constructor sets up the database-related attributes for the provider model, including prompt session, tool call, plugin usage, charge, and prompt history references. It attempts to retrieve the current prompt session using a session key if provided, or falls back to a prompt object in kwargs.

Parameters:

*args (tuple) – Positional arguments passed to the superclass constructor.
**kwargs (dict) –
Keyword arguments passed to the superclass constructor. Recognized keys:
- SMARTER_CHAT_SESSION_KEY_NAME (str): Default is ‘session_key’. Session key for the prompt session.
- prompt (Prompt): Prompt instance to use if session key is not provided.

Example

mixin = ChatDbMixin(prompt=my_chat)
# or
mixin = ChatDbMixin(session_key="abc123")

property db_charges: QuerySet

Get the queryset of charge records for the current prompt session and UserProfile.

This property returns a Django QuerySet of Charge objects filtered by the current user profile and prompt session key. If either the user profile or prompt is not set, returns None. The queryset is cached for efficiency.

Each Charge record typically contains fields such as:

prompt_tokens (int): Number of prompt tokens used.
completion_tokens (int): Number of completion tokens used.
total_tokens (int): Total tokens used.

Returns:: QuerySet of charge records for the current session, or None if unavailable.
Return type:: QuerySet[Charge] or None

Example

charges = provider.db_charges
if charges is not None:
    for charge in charges:
        print(charge.prompt_tokens, charge.completion_tokens, charge.total_tokens)

property db_chat_plugin_usage: QuerySet

Get the prompt plugin usage instance for the current prompt session.

This property returns the PromptPluginUsage object associated with the current prompt session, if available. The result is cached for efficiency. If no prompt is set or no plugin usage exists, returns None.

Returns:: The prompt plugin usage instance for the current prompt, or None if unavailable.
Return type:: PromptPluginUsage or None

Example

plugin_usage = provider.db_chat_plugin_usage
if plugin_usage is not None:
    print(plugin_usage.plugin, plugin_usage.input_text)

property db_chat_tool_call: QuerySet

Get the queryset of prompt tool call records for the current prompt session.

This property returns a Django QuerySet of PromptToolCall objects associated with the current prompt session. If no prompt is set, returns an empty queryset. The queryset is cached for efficiency.

Returns:: QuerySet of prompt tool call records for the current prompt session, or an empty queryset if unavailable.
Return type:: QuerySet[PromptToolCall]

Example

tool_calls = provider.db_chat_tool_call
for tool_call in tool_calls:
    print(tool_call.function_name, tool_call.created_at)

db_insert_charge(provider, charge_type, completion_tokens, prompt_tokens, total_tokens, model, reference)[source]

Insert a new charge record for the current account and prompt session.

This method asynchronously creates a new Charge record associated with the current account, user, and prompt session. It is typically used to persist billing or usage information for a model completion or related operation.

Parameters:

provider (str) – The name of the provider (e.g., “openai”, “anthropic”).
charge_type (str) – The type of charge (e.g., “completion”, “plugin”).
completion_tokens (int) – The number of completion tokens used.
prompt_tokens (int) – The number of prompt tokens used.
total_tokens (int) – The total number of tokens used.
model (str) – The model name or identifier (e.g., “gpt-4”).
reference (str) – An external reference or identifier for the charge (e.g., request ID).

Raises:

SmarterValueError – If the account or prompt is not set.

Example

provider.db_insert_charge(
    provider="openai",
    charge_type="completion",
    completion_tokens=42,
    prompt_tokens=58,
    total_tokens=100,
    model="gpt-4",
    reference="req-12345"
)

db_insert_chat_plugin_usage(*args, **kwargs)[source]

Insert a prompt plugin usage record for the specified prompt session.

This method creates a new PromptPluginUsage record associated with the given prompt session. The insertion is performed asynchronously using a background task. If no prompt is provided, the method logs a warning and returns without action.

Parameters:

prompt (Prompt, required) – The prompt instance for which to record plugin usage.
plugin (Plugin, optional) – The plugin instance used in the prompt (default: None).
input_text (str, optional) – The input text sent to the plugin (default: None).

Example

provider.db_insert_chat_plugin_usage(
    prompt=my_chat,
    plugin=my_plugin,
    input_text="search for weather"
)

db_insert_chat_tool_call(*args, **kwargs)[source]

Insert a prompt tool call record for the current prompt session.

This method creates a new PromptToolCall record associated with the current prompt session. The insertion is performed asynchronously using a background task. If no prompt is set, the method returns without action.

Parameters:

plugin (Plugin, optional) – The plugin instance associated with the tool call (default: None).
function_name (str, optional) – The name of the function called (default: None).
function_args (dict or str, optional) – Arguments passed to the function (default: None).
request (dict or str, optional) – The request payload (default: None).
response (dict or str, optional) – The response payload (default: None).

Example

provider.db_insert_chat_tool_call(
    plugin=my_plugin,
    function_name="my_function",
    function_args={"arg1": 123},
    request={"input": "foo"},
    response={"output": "bar"}
)

property db_message_history: list[dict] | None

Get the most recently persisted messages in the prompt history.

This property returns the latest list of messages stored in the prompt history for the current prompt session. If no messages are available, returns None. The result is cached for efficiency.

Returns:: The most recent list of message dictionaries from prompt history, or None if unavailable.
Return type:: list[dict] or None

Example

messages = provider.db_message_history
if messages:
    for msg in messages:
        print(msg['role'], msg['content'])

db_refresh()[source]

Refresh the provider instance and its cached database attributes.

This method refreshes the prompt instance from the database and resets the cached charges queryset. Use this method to ensure the provider has the latest data after external changes to the prompt or related records.

Example

provider.db_refresh()
# Now provider.db_charges and related properties are up to date

property db_total_completion_tokens: int

Get the total number of completion tokens used in the current prompt session.

This property aggregates the completion_tokens field across all charge records for the current prompt session and account. If no charges are available, returns 0.

Returns:: The total number of completion tokens used, or 0 if unavailable.
Return type:: int

Example

total_completion = provider.db_total_completion_tokens
print(f"Completion tokens used: {total_completion}")

property db_total_prompt_tokens: int

Get the total number of prompt tokens used in the current prompt session.

This property aggregates the prompt_tokens field across all charge records for the current prompt session and account. If no charges are available, returns 0.

Returns:: The total number of prompt tokens used, or 0 if unavailable.
Return type:: int

Example

total_prompt = provider.db_total_prompt_tokens
print(f"Prompt tokens used: {total_prompt}")

property db_total_tokens: dict | None

Get a dictionary containing the total prompt, completion, and overall tokens used.

This property returns a dictionary with the total number of prompt tokens, completion tokens, and overall tokens used in the current prompt session. The values are aggregated from all charge records for the session.

Returns:: A dictionary with keys ‘prompt_tokens’, ‘completion_tokens’, and ‘total_tokens’, or None if no charge data is available.
Return type:: dict or None

Example

totals = provider.db_total_tokens
if totals:
    print(f"Prompt: {totals['prompt_tokens']}, Completion: {totals['completion_tokens']}, Total: {totals['total_tokens']}")

property db_total_total_tokens: int

Get the total number of tokens used in the current prompt session.

This property aggregates the total_tokens field across all charge records for the current prompt session and account. If no charges are available, returns 0.

Returns:: The total number of tokens used, or 0 if unavailable.
Return type:: int

Example

total_tokens = provider.db_total_total_tokens
print(f"Total tokens used: {total_tokens}")

property prompt: Prompt | None

Get the current prompt session instance.

This property returns the active Prompt object associated with the provider, or None if no prompt session is set. It is used to access prompt-specific data and operations throughout the provider’s logic.

Returns:: The current prompt session instance, or None if not set.
Return type:: Prompt or None

Example

prompt = provider.prompt
if prompt is not None:
    print(prompt.session_key)

property prompt_history: QuerySet | None

Get the prompt history queryset for the current prompt session.

This property returns a Django QuerySet of PromptHistory objects associated with the current prompt session. If no prompt is set, or if there is no history, returns None. The queryset is cached for efficiency.

Returns:: QuerySet of prompt history records for the current prompt, or None if unavailable.
Return type:: QuerySet[PromptHistory] or None

Example

history_qs = provider.prompt_history
if history_qs is not None:
    for record in history_qs:
        print(record.created_at, record.messages)

property provider: Provider | None

Get the Provider instance associated with this provider model.

This property returns the Provider object that represents the provider configuration for this model. It is typically used to access provider-specific settings and information.

Returns:: The Provider instance associated with this model, or None if not set.
Return type:: Provider or None

Example

provider_instance = provider.provider
if provider_instance:
    print(provider_instance.name)

property provider_name: str | None

Get the provider name associated with this provider model.

This property returns the name of the provider that this model is configured to use. It is typically used to determine which provider’s handler to invoke for prompt completions.

Returns:: The name of the provider, or None if not set.
Return type:: str or None

Example

print(provider.provider_name)

property ready: bool

Indicates whether the mixin and its dependencies are ready for use.

This property checks if both the superclass and the prompt instance are ready. It is useful for determining if the provider is fully initialized and can interact with the database and prompt session.

Returns:: True if both the superclass and prompt are ready, False otherwise.
Return type:: bool

Example

if provider.ready:
    # Safe to proceed with database operations
    ...