Consumption Report

ConsumptionReport Schema v1.0-beta1

Overview

The Consumption schema tracks resource usage across different services, APIs, and infrastructure providers. It's designed to capture granular consumption metrics for billing, cost analysis, and usage monitoring.

Use Cases

Cost Tracking: Monitor API usage costs across multiple providers (OpenAI, Anthropic, AWS, etc.)
Resource Monitoring: Track consumption patterns for capacity planning
Billing & Chargeback: Attribute costs to specific users, sessions, or applications
Usage Analytics: Analyze consumption trends and optimize resource usage
Multi-Cloud Management: Unified tracking across different cloud providers and services

Schema Structure

Root Properties

Field	Type	Required	Description
`schema_type`	string	✅	Must be `"consumption-report"`
`schema_version`	string	✅	Schema version (e.g., `"v1.0-beta1"`)
`id`	string	✅	Unique identifier for this consumption batch
`timestamp`	string (ISO 8601)	✅	When this consumption batch was recorded
`context`	object	❌	Contextual information about the batch
`records`	array	✅	List of consumption records (min 1)
`metadata`	object	❌	Additional metadata (flexible key-value pairs)

Context Object

Optional contextual information about the consumption batch:

Field	Type	Description
`session_id`	string	Session or request identifier
`user_id`	string	User or account identifier
`environment`	enum	Environment: `production`, `staging`, `development`, `test`
`application`	string	Application or service name

Consumption Record

Each record represents a single resource consumption event:

Field	Type	Required	Description
`task_name`	string	✅	Task type (e.g., `"llm_completion"`, `"transcription"`)
`provider`	string	✅	Service provider (e.g., `"openai"`, `"anthropic"`, `"aws"`)
`service`	string	✅	Specific service/API (e.g., `"chat_completion_input_tokens"`)
`variant`	string	❌	Model name, region, or tier (e.g., `"gpt-4-turbo"`)
`count`	number	✅	Quantity consumed (≥ 0)
`unit`	string	✅	Unit of measurement (e.g., `"tokens"`, `"seconds"`)
`cost`	object	❌	Cost information (amount + currency)
`timestamp`	string (ISO 8601)	❌	When this specific consumption occurred
`metadata`	object	❌	Record-level metadata

Cost Object

Optional cost tracking for each record:

Field	Type	Required	Description
`amount`	number	✅	Cost amount (can be negative for credits)
`currency`	string	✅	ISO 4217 currency code (e.g., `"USD"`, `"EUR"`)

Common Task Names

Task Name	Description	Typical Units
`llm_completion`	LLM text generation	tokens
`transcription`	Speech-to-text	seconds, minutes
`translation`	Text translation	characters, words
`image_generation`	AI image creation	images, requests
`tts_synthesis`	Text-to-speech	characters, seconds
`embeddings_generation`	Vector embeddings	tokens
`audio_analysis`	Audio processing	seconds, minutes
`video_processing`	Video encoding/analysis	seconds, minutes

Common Providers

Provider	Common Services
`openai`	chat_completion, embeddings_api, whisper_api, dall-e_api, tts_api
`anthropic`	chat_completion_input_tokens, chat_completion_output_tokens
`aws`	s3_storage, lambda_invocations, transcribe_api, bedrock_api
`gcp`	cloud_storage, speech_to_text, vertex_ai
`azure`	openai_service, cognitive_services, storage
`elevenlabs`	tts_api
`deepgram`	transcription_api

Common Units

Unit	Description	Used For
`tokens`	Token count	LLM input/output, embeddings
`seconds`	Time duration	Audio/video processing
`minutes`	Time duration	Audio/video processing
`bytes` / `megabytes` / `gigabytes`	Data size	Storage, data transfer
`requests`	API calls	General API usage
`invocations`	Function executions	Serverless functions
`characters`	Character count	Translation, TTS
`images`	Image count	Image generation

Examples

Example 1: LLM Completion Tracking

{
  "schema_type": "consumption-report",
  "schema_version": "v1.0-beta1",
  "id": "batch-20240101-001",
  "timestamp": "2024-01-01T10:30:00Z",
  "context": {
    "session_id": "session-abc-123",
    "user_id": "user-456",
    "environment": "production",
    "application": "customer-support-ai"
  },
  "records": [
    {
      "task_name": "llm_completion",
      "provider": "openai",
      "service": "chat_completion_input_tokens",
      "variant": "gpt-4-turbo",
      "count": 1500,
      "unit": "tokens",
      "cost": {
        "amount": 0.015,
        "currency": "USD"
      }
    },
    {
      "task_name": "llm_completion",
      "provider": "openai",
      "service": "chat_completion_output_tokens",
      "variant": "gpt-4-turbo",
      "count": 500,
      "unit": "tokens",
      "cost": {
        "amount": 0.015,
        "currency": "USD"
      }
    }
  ]
}

Example 2: Multi-Provider Audio Processing

{
  "schema_type": "consumption-report",
  "schema_version": "v1.0-beta1",
  "id": "batch-20240101-audio-001",
  "timestamp": "2024-01-01T14:00:00Z",
  "context": {
    "session_id": "audio-session-xyz",
    "environment": "production",
    "application": "call-analyzer"
  },
  "records": [
    {
      "task_name": "transcription",
      "provider": "deepgram",
      "service": "transcription_api",
      "variant": "nova-2",
      "count": 300,
      "unit": "seconds",
      "cost": {
        "amount": 0.45,
        "currency": "USD"
      }
    },
    {
      "task_name": "llm_completion",
      "provider": "anthropic",
      "service": "chat_completion_input_tokens",
      "variant": "claude-sonnet-3.5",
      "count": 5000,
      "unit": "tokens",
      "cost": {
        "amount": 0.015,
        "currency": "USD"
      }
    },
    {
      "task_name": "llm_completion",
      "provider": "anthropic",
      "service": "chat_completion_output_tokens",
      "variant": "claude-sonnet-3.5",
      "count": 2000,
      "unit": "tokens",
      "cost": {
        "amount": 0.030,
        "currency": "USD"
      }
    }
  ],
  "metadata": {
    "cost_center": "customer-support",
    "interaction_id": "call-550e8400",
    "tags": ["audio-analysis", "customer-interaction"]
  }
}

Example 3: Cloud Infrastructure Usage

{
  "schema_type": "consumption-report",
  "schema_version": "v1.0-beta1",
  "id": "batch-20240101-infra-001",
  "timestamp": "2024-01-01T23:59:59Z",
  "context": {
    "environment": "production",
    "application": "data-pipeline"
  },
  "records": [
    {
      "task_name": "storage",
      "provider": "aws",
      "service": "s3_storage",
      "variant": "us-east-1",
      "count": 500,
      "unit": "gigabytes",
      "cost": {
        "amount": 11.50,
        "currency": "USD"
      }
    },
    {
      "task_name": "compute",
      "provider": "aws",
      "service": "lambda_invocations",
      "variant": "512mb-1s",
      "count": 1000000,
      "unit": "invocations",
      "cost": {
        "amount": 2.00,
        "currency": "USD"
      }
    }
  ],
  "metadata": {
    "billing_period": "2024-01",
    "cost_center": "data-engineering"
  }
}

Design Principles

1. Provider Agnostic

The schema is intentionally provider-agnostic. It can track consumption from:

AI/ML providers (OpenAI, Anthropic, Cohere, etc.)
Cloud platforms (AWS, GCP, Azure)
Specialized services (Deepgram, ElevenLabs, etc.)
Custom internal services

2. Flexible Units

Units are free-form strings to support diverse consumption types:

Token-based billing (LLMs, embeddings)
Time-based billing (audio/video processing)
Volume-based billing (storage, data transfer)
Request-based billing (API calls)

3. Granular Tracking

Each record captures a single service usage instance, allowing for:

Detailed cost attribution
Granular analytics
Accurate billing reconciliation

4. Batch Organization

Records are organized in batches with shared context:

Efficient data collection
Session/user attribution
Environment tracking

5. Cost Optional

Cost information is optional because:

Not all services provide immediate cost data
Costs may be calculated separately
Usage tracking may be independent of billing

Integration Patterns

Pattern 1: Real-Time Logging

Log consumption records as they occur:

def track_llm_usage(model, prompt_tokens, completion_tokens):
    consumption = {
        "schema_type": "consumption-report",
        "schema_version": "v1.0-beta1",
        "id": generate_id(),
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "records": [
            {
                "task_name": "llm_completion",
                "provider": "openai",
                "service": "chat_completion_input_tokens",
                "variant": model,
                "count": float(prompt_tokens),
                "unit": "tokens"
            },
            {
                "task_name": "llm_completion",
                "provider": "openai",
                "service": "chat_completion_output_tokens",
                "variant": model,
                "count": float(completion_tokens),
                "unit": "tokens"
            }
        ]
    }
    logger.info(json.dumps(consumption))

Pattern 2: Batch Collection

Collect multiple consumption events and submit as batch:

class ConsumptionCollector:
    def __init__(self, context):
        self.records = []
        self.context = context

    def record(self, task_name, provider, service, variant, count, unit):
        self.records.append({
            "task_name": task_name,
            "provider": provider,
            "service": service,
            "variant": variant,
            "count": count,
            "unit": unit
        })

    def flush(self):
        consumption = {
            "schema_type": "consumption-report",
            "schema_version": "v1.0-beta1",
            "id": generate_id(),
            "timestamp": datetime.utcnow().isoformat() + "Z",
            "context": self.context,
            "records": self.records
        }
        submit_to_analytics(consumption)
        self.records = []

Pattern 3: Cost Calculation

Add cost information post-hoc using pricing tables:

def enrich_with_costs(consumption_batch, pricing_table):
    for record in consumption_batch["records"]:
        key = (record["provider"], record["service"], record["variant"])
        if key in pricing_table:
            rate = pricing_table[key]
            record["cost"] = {
                "amount": record["count"] * rate,
                "currency": "USD"
            }
    return consumption_batch

Validation Rules

Required Fields

All root-level required fields must be present
Each record must have: task_name, provider, service, count, unit
count must be ≥ 0
schema_type must exactly match "consumption-report"

Format Constraints

timestamp must be valid ISO 8601 format
schema_version must match pattern ^v\\d+\\.\\d+(-(alpha|beta|rc)\\d+)?$
Currency codes must be 3 uppercase letters (ISO 4217)

Data Integrity

If cost is provided, both amount and currency are required
metadata values must be valid JSON types
additionalProperties: false ensures no unexpected fields

Migration Notes

From v1.0-alpha (if existed)

This is the first beta version. Key design decisions:

Batch-oriented structure for efficient collection
Provider-agnostic design for multi-cloud support
Optional cost tracking for flexible use cases
Extensible metadata at both batch and record level

Future Compatibility

Consider forward compatibility when:

Adding new providers or services (use metadata for custom fields)
Extending with new task types (no schema change needed)
Adding cost calculation methods (use metadata)

Best Practices

1. Use Descriptive Task Names

Choose task names that clearly indicate what was consumed:

✅ llm_completion, transcription, translation
❌ task1, api_call, process

2. Consistent Provider Naming

Use lowercase, standardized provider names:

✅ openai, anthropic, aws, gcp
❌ OpenAI, ANTHROPIC, Amazon Web Services

3. Granular Service Names

Be specific about which service/API was used:

✅ chat_completion_input_tokens, chat_completion_output_tokens
❌ api_tokens, tokens

4. Track Input and Output Separately

For LLM usage, create separate records for input and output tokens to:

Enable accurate cost calculation (different pricing)
Support detailed usage analytics
Match provider billing structures

5. Include Context for Attribution

Always provide context when available:

session_id: For session-level cost tracking
user_id: For user-level chargeback
application: For service-level monitoring
environment: For cost allocation by environment

6. Use Metadata for Custom Fields

For provider-specific or application-specific data:

Store in metadata rather than extending the schema
Maintains schema compatibility
Supports custom analytics

customer-interaction: Consumption records may reference interaction IDs
audit-result: Audit processes may generate consumption records

Schema Evolution

Current Version: v1.0-beta1

Initial beta release
Core consumption tracking structure
Provider-agnostic design

Planned for v1.0

Stabilize after beta feedback
Finalize common provider/service names
Lock schema structure

Future Considerations (v2.0+)

Rate limiting information
Quota tracking
Aggregated summaries
Cost forecasting metadata

Available Views

View	Description	Projection
`one-liner`	Single-line consumption report identification	`{ id: id, records_count: length(records) }`
`summary`	Consumption overview with context and record summary	`{ id: id, timestamp: timestamp, environment: context.envi...`
`full`	Complete consumption report with all records and costs	`@`

Use the SDK to render views:

from ontopix_schemas import SchemaInstance

instance = SchemaInstance(data)
print(instance.view("one-liner"))
print(instance.view("summary"))
print(instance.view("full"))

AuditResult v1.0-beta1

Schema Type: audit-resultVersion: v1.0-beta1JSON Schema URL: https://schemas.platform.ontopix.ai/audit-result/v1.0-beta1.json

CustomerInteraction v1.0

Schema Type: customer-interactionVersion: v1.0JSON Schema: https://schemas.platform.ontopix.ai/customer-interaction/v1.0.jsonViews: https://schemas.platform.ontopix.ai/customer-interaction/v1.0.views.json