Charge Model

Account Charge Model and Constants

This module defines the Charge model for tracking periodic billing events associated with user profiles. It also provides constants for charge types and providers, and emits a signal when a new charge is created.

Classes & Constants

Charge: Represents a single billing event for a user profile, including provider, charge type, token usage, and references.
CHARGE_TYPES: List of available charge types (completion, plugin, tool).
PROVIDERS: List of supported LLM providers (OpenAI, Meta AI, Google AI).
CHARGE_TYPE_PROMPT_COMPLETION, CHARGE_TYPE_PLUGIN, CHARGE_TYPE_TOOL: Charge type constants.

Key Features

Tracks provider, charge type, token usage, and references for each billing event.
Emits a signal (new_charge_created) when a new charge is created for downstream processing.
Integrates with Smarter logging and signal systems.

Example

from smarter.apps.account.models import Charge

charge = Charge.objects.create(
    user_profile=user_profile,
    provider="openai",
    charge_type="completion",
    prompt_tokens=100,
    completion_tokens=200,
    total_tokens=300,
    model="gpt-4",
    reference="invoice-123"
)

class smarter.apps.account.models.charge.Charge(*args, **kwargs)[source]

Bases: TimestampedModel

Charge model for tracking periodic account billing events.

Represents a single billing event for a UserProfile, including provider, charge type, token usage, and reference details.

Parameters:

user_profile – ForeignKey to UserProfile. The user profile associated with the charge.
session_key – String. Optional session identifier for the charge.
provider – String. The LLM provider (e.g., OpenAI).
charge_type – String. The type of charge (e.g., completion, plugin, tool).
prompt_tokens – Integer. Number of prompt tokens used.
completion_tokens – Integer. Number of completion tokens used.
total_tokens – Integer. Total tokens used.
model – String. The model name.
reference – String. Reference identifier for the charge.

Note

A signal is emitted when a new charge is created, enabling downstream billing and analytics workflows.

Example usage:

charge = Charge.objects.create(
    user_profile=user_profile,
    provider="openai",
    charge_type="completion",
    prompt_tokens=100,
    completion_tokens=200,
    total_tokens=300,
    model="gpt-4",
    reference="invoice-123"
)

See also

UserProfile, LLMPrices

Parameters:

id (Unknown) – Primary key: ID
created_at (Unknown) – Created at
updated_at (Unknown) – Updated at

exception DoesNotExist: Bases: ObjectDoesNotExist

exception MultipleObjectsReturned: Bases: MultipleObjectsReturned

exception NotUpdated: Bases: ObjectNotUpdated, DatabaseError

charge_type

CharField

Charge type

Choices:

completion
plugin
tool

Type:: Type

completion_tokens

IntegerField

Completion tokens

Type:: Type

created_at

DateTimeField

Created at

Timestamp indicating when the model instance was created.

This field is automatically set to the current date and time when the instance is first created. It is indexed in the database for efficient querying.

Type:: Type

get_charge_type_display(*, field=<django.db.models.CharField: charge_type>): Shows the label of the charge_type. See get_FOO_display() for more information.

get_provider_display(*, field=<django.db.models.CharField: provider>): Shows the label of the provider. See get_FOO_display() for more information.

id

BigAutoField

Primary key: ID

Type:: Type

model

CharField

Model

Type:: Type

objects = <django.db.models.Manager object>

prompt_tokens

IntegerField

Prompt tokens

Type:: Type

provider

CharField

Provider

Choices:

openai
metaai
googleai

Type:: Type

reference

CharField

Reference

Type:: Type

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

Save the model instance to the database, performing validation before the actual save.

This method overrides the default save() behavior of Django models to ensure that the model is validated by calling validate() before any data is written to the database. If validation fails, a django.core.exceptions.ValidationError is raised with detailed information about the error, the arguments passed, the model class, and the current field values.

Parameters:

*args – Positional arguments passed to the parent save() method. These are forwarded to Django’s ORM.
**kwargs – Keyword arguments passed to the parent save() method. These are forwarded to Django’s ORM.

Examples

obj = MyModel(name="Example")
obj.save()  # Will call validate() before saving

Note

The validate() method is intended to be overridden in subclasses to provide custom validation logic.
If validate() raises a ValidationError, the save operation is aborted and the error is propagated.
The error message includes the arguments, keyword arguments, model class, and current field values for easier debugging.

Important

If you override this method in a subclass, always call super().save(*args, **kwargs) to retain validation and timestamp functionality.
If validation fails, no data will be saved to the database.

session_key

CharField

Session key

Type:: Type

total_tokens

IntegerField

Total tokens

Type:: Type

updated_at

DateTimeField

Updated at

Timestamp indicating when the model instance was last updated.

This field is automatically updated to the current date and time whenever the instance is saved. It is indexed in the database for efficient querying.

Type:: Type

user_profile

ForeignKey to UserProfile

User profile (related name: charge)

Type:: Type

user_profile_id: Internal field, use user_profile instead.