The ai_model_usage core model exposes AI model usage events from the observability store.

Like audit_events, it is read-only and intended for analysis, dashboards, and monitoring rather than generic writes.

What This Model Represents¶

Rows include:

• id
• timestamp
• provider
• model_name
• objective
• request_kind
• user_id
• total_tokens
• duration_ms
• success

Detail rows also include:

• session_id
• node_id
• request_id
• correlation_id
• engine
• deployment_mode
• agent_id
• prompt_tokens
• completion_tokens
• error
• channel

Typical Use Cases¶

Use module_sdk.models.ai_model_usage when you need to:

• monitor model usage
• build dashboards for token and latency trends
• inspect failure details for one AI model request

The monitor module uses the model schema for AI model usage tables.

Listing Usage Events¶

Example:

listing = module_sdk.models.ai_model_usage.list(
    page=0,
    page_size=50,
    filters={"provider": "openai", "success": True},
)

Supported filters include:

• provider
• model_name
• objective
• request_kind
• success
• user_id

The default sort is timestamp desc.

Viewing One Usage Event¶

Example:

row = module_sdk.models.ai_model_usage.view(event_id)

Use this for detail pages or support/debug tooling where prompt/completion token counts, node identity, and error fields matter.

Write Operations Are Disabled¶

This model is read-only through the SDK. Usage events are generated by provider/runtime instrumentation, not by module code or ad-hoc CRUD calls.