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, compute).

  • Actuals, get_actuals(): what a resource has actually spent in a period of time.

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.Actuals(records=0, prompt_tokens=0, completion_tokens=0, total_tokens=0, total_cost=Decimal('0'))[source]

Bases: object

What a resource has actually spent in a period of time.

__init__(records=0, prompt_tokens=0, completion_tokens=0, total_tokens=0, total_cost=Decimal('0'))
add(row)[source]

Add an aggregate row of Charge or AggregatedCharges sums.

Return type:

None

completion_tokens: int = 0
prompt_tokens: int = 0
records: int = 0
total_cost: Decimal = Decimal('0')
total_tokens: int = 0
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

  • compute

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

  • compute

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.

The charge types are:

  • PROMPT_COMPLETION: a prompt completion charge.

  • PLUGIN: a plugin charge.

  • TOOL: a tool charge.

  • COMPUTE: an hour of infrastructure, e.g. the nodes of an LLMHostCompute. It has no tokens.

COMPUTE = 'compute'
PLUGIN = 'plugin'
PROMPT_COMPLETION = 'completion'
TOOL = 'tool'
smarter.apps.account.models.charge.get_actuals(resource_locator, start=None, end=None)[source]

What a resource has spent from start up to end, from its charges whether aggregated or not.

AggregatedCharges have the precision of an hour, so an hour is counted if it begins at or after start, and before end. Charges of a previous month are rolled up into days.

Parameters:

  • resource_locator (str) – The TimestampedModel.record_locator of the resource.

  • start (datetime | None) – The beginning of the period. None means the beginning of time.

  • end (datetime | None) – The end of the period, exclusive. None means now.

Return type:

Actuals