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.

  • ChargeTypes: List of available charge types (completion, plugin, tool).

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(
    charge_type="completion",
    prompt_tokens=100,
    completion_tokens=200,
    total_tokens=300,
)
class smarter.apps.account.models.charge.AggregatedCharges(*args, **kwargs)[source]

Bases: TimestampedModel

AggregatedCharges model for tracking aggregated account billing events.

Represents aggregated billing data for a specific time period.

Parameters:

  • year – Integer. The year of the aggregated data.

  • month – Integer. The month of the aggregated data.

  • day – Integer. The day of the aggregated data.

  • hour – Integer. The hour of the aggregated data.

  • id (Unknown) – Primary key: ID

  • created_at (Unknown) – Created at

  • updated_at (Unknown) – Updated at

  • resource_locator (Unknown) – Resource locator. The TimestampedModel.resource_locator of the resource that this charge is associated with.

  • charge_type (Unknown) – Charge type

  • records (Unknown) – Records

  • prompt_tokens (Unknown) – Prompt tokens

  • completion_tokens (Unknown) – Completion tokens

  • total_tokens (Unknown) – Total tokens

  • total_cost (Unknown) – Total cost

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

day

SmallIntegerField

Day

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.

hour

SmallIntegerField

Hour

Type:

Type

id

BigAutoField

Primary key: ID

Type:

Type

month

SmallIntegerField

Month

Type:

Type

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

IntegerField

Prompt tokens

Type:

Type

records

IntegerField

Records

Type:

Type

resource_locator

CharField

Resource locator. The TimestampedModel.resource_locator of the resource that this charge is associated with.

Type:

Type

total_cost

DecimalField

Total cost

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

year

SmallIntegerField

Year

Type:

Type

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

Bases: TimestampedModel

Charge model for tracking periodic account billing events.

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

Represents a single billing event for a resource.

Parameters:

  • resource_locator – String. The TimestampedModel.resource_locator of the resource that this charge is associated with.

  • 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.

Example usage:

charge = Charge.objects.create(
    resource_locator=resource_locator,
    charge_type="completion",
    prompt_tokens=100,
    completion_tokens=200,
    total_tokens=300,
)
Parameters:

  • id (Unknown) – Primary key: ID

  • created_at (Unknown) – Created at

  • updated_at (Unknown) – Updated at

  • total_cost (Unknown) – Total cost

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.

id

BigAutoField

Primary key: ID

Type:

Type

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

IntegerField

Prompt tokens

Type:

Type

resource_locator

CharField

Resource locator. The TimestampedModel.resource_locator of the resource that this charge is associated with.

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.

total_cost

DecimalField

Total cost

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

class smarter.apps.account.models.charge.ChargeTypes(*values)[source]

Bases: SmarterEnumAbstract

Charge types enumeration.

This enumeration defines the different types of charges that can be associated with user profiles. Each charge type corresponds to a specific billing event, such as prompt completion, plugin usage, or tool usage.

PROMPT_COMPLETION

Represents a prompt completion charge type.

PLUGIN

Represents a plugin charge type.

TOOL

Represents a tool charge type.

PLUGIN = 'plugin'
PROMPT_COMPLETION = 'completion'
TOOL = 'tool'