meter-lib 0.1.0

meter-lib — Usage Guide

Overview

meter-lib is a lightweight helper library for sending metering events to the Litewave backend and for looking up a customer account by tenant_id.

Requirements

• Python 3.10+

Installation

pip install meter-lib

Parameters Required

tenant_id,
device_id,
meter_id,
kafka_url,
total_usage,
portal_url,
api_key,
start_time,
end_time,
metadata (optional)

Quickstart

from meter_lib import post_meter_usage

tenant_id = "tenant_123"
device_id = "us-east-ing1"
meter_id = "document.basic.page"
kafka_url="https://stream.app.domain.com",
portal_url="https://portal.app.domain.com", 
api_key="sk-lw-40ea6ac9ee3xxxx_305e790xxxx"

result = post_meter_usage(
    tenant_id=tenant_id,
    device_id=device_id,
    meter_id=meter_id,
    kafka_url=kafka_url,
    portal_url=portal_url,
    total_usage=24,  # integer units as defined by your meter
    api_key=api_key, # Use None / Optional if it is internal url
)

With metadata

Use metadata to attach contextual key-value pairs to the event (e.g. rule_id, report_id, batch_id). All values must be strings.

result = post_meter_usage(
    tenant_id=tenant_id,
    device_id=device_id,
    meter_id="rule.executed.small",
    kafka_url=kafka_url,
    portal_url=portal_url,
    api_key=api_key,
    total_usage=1,
    metadata={
        "rule_id": "rule-abc123",
        "batch_id": "batch-999",
    },
)

For AI enabled

from meter_lib import post_ai_meter_usage

tenant_id = "tenant_123"
device_id = "us-east-ing1"
meter_id = "chat.on.time_hours"
kafka_url="https://stream.app.domain.com",
portal_url="https://portal.app.domain.com", 
api_key="sk-lw-40ea6ac9ee3xxxx_305e790xxxx"
start_time = 1759791552000 # Timestamp in milliseconds

result = post_ai_meter_usage(
  tenant_id=tenant_id,
  device_id=device_id,
  meter_id=meter_id,
  kafka_url=kafka_url,
  portal_url=portal_url, # Use None / Optional if it is internal url
  api_key=api_key, # Use None / Optional if it is internal url
  start_time= start_time # Timestamp in milliseconds
)

For AI disabled

from meter_lib import post_ai_meter_usage

tenant_id = "tenant_123"
device_id = "us-east-ing1"
meter_id = "chat.on.time_hours"
kafka_url="https://stream.app.domain.com", 
portal_url="https://portal.app.domain.com", 
api_key="sk-lw-40ea6ac9ee3xxxx_305e790xxxx"
end_time = 1779799552000 # Timestamp in milliseconds

result = post_ai_meter_usage(
  tenant_id=tenant_id,
  device_id=device_id,
  meter_id=meter_id,
  kafka_url=kafka_url,
  portal_url=portal_url, # Use None / Optional if it is internal url
  api_key=api_key, # Use None / Optional if it is internal url
  end_time= end_time # Timestamp in milliseconds
)

if result is None:
    print("Failed to post meter usage event")
else:
    print("Event accepted:", result)

Error Handling

• post_meter_usage returns None for network errors or non-success HTTP statuses.
• Prefer explicit checks for None and add retries or backoff in your application layer if needed.

API Reference

post_meter_usage(tenant_id: str, device_id: str, meter_id: str, kafka_url: str, portal_url: str, api_key: str, total_usage: int, timestamp: int = None, metadata: dict[str, str] = None) -> dict | None

• Description: Posts a metering event for a device and meter under a given tenant.
• Headers:
  • x-tenant-id: the tenant identifier (string)
  • x-device-id: the device identifier (string)
• Payload (JSON):
  • meter_id (string)
  • total_usage (integer)
  • customer_id (string) — auto-filled by the library.`
  • metadata (dict) — optional contextual key-value pairs. Stored in raw_usage_events and queryable via metadata['key'].
• Returns: The backend JSON response (dict) on success, otherwise None.
• Timeout: 10 seconds.
• Notes:
  • If the customer lookup fails, the call is skipped and None is returned.
  • This function is synchronous and will block until the request completes or times out.

post_ai_meter_usage(tenant_id: str, device_id: str, meter_id: str, kafka_url: str, portal_url: str, api_key: str, start_time: int = None, end_time: int = None, metadata: dict[str, str] = None) -> dict | None

• Description: Posts a session boundary event for time-based meters. Call with start_time when a session begins, and again with end_time when it ends.
• metadata: optional key-value context (e.g. session_id). All values must be strings.

List Of Meters:

• meter_id: "page.processed.basic" name: "Basic Document Scanning" type: "volume" description: "Total number of basic pages processed"

• meter_id: "page.processed.advanced" name: "Advanced Document Scanning" type: "volume" description: "Total number of advanced pages processed"

• meter_id: "report.generated.small" name: "Small Report Generation" type: "volume" description: "Total number of small reports generated"

• meter_id: "report.generated.medium" name: "Medium Report Generation" type: "volume" description: "Total number of medium reports generated"

• meter_id: "report.generated.large" name: "Large Report Generation" type: "volume" description: "Total number of large reports generated"

• meter_id: "report.generated.dataquery" name: "Data Query Report Generation" type: "volume" description: "Total number of data query reports generated"

• meter_id: "report.generated.insights" name: "Insights Report Generation" type: "volume" description: "Total number of insights reports generated"

• meter_id: "rule.executed.small" name: "Small Rule Execution" type: "volume" description: "Total number of rules executed with runtime less than 1 minute"

• meter_id: "rule.executed.medium" name: "Medium Rule Execution" type: "volume" description: "Total number of rules executed with runtime between 1 and 3 minutes"

• meter_id: "rule.executed.large" name: "Large Rule Execution" type: "volume" description: "Total number of rules executed with runtime greater than 4 minutes"

• meter_id: "chat.on.time_hours" name: "Litewave AI Assistant Usage (Hours)" type: "performance" description: "Total active chat usage time in hours"

• meter_id: "chat.query.time_secs" name: "Litewave AI Assistant Query Time (Seconds)" type: "performance" description: "Total time spent per query in seconds"

• meter_id: "document.storage.size_gb" name: "Document Storage Size" type: "volume" description: "Total document storage consumed in GB"

• meter_id: "template.processed.small" name: "Small Template Processing" type: "volume" description: "Total number of small templates processed"

• meter_id: "template.processed.medium" name: "Medium Template Processing" type: "volume" description: "Total number of medium templates processed"

• meter_id: "template.processed.large" name: "Large Template Processing" type: "volume" description: "Total number of large templates processed"

• meter_id: "template.processed.count" name: "Template Licensing Count" type: "volume" description: "Total number of licensed templates processed"

• meter_id: "template.licensed.total" name: "Yearly Template Setup" type: "volume" description: "Total yearly template setup count"

Troubleshooting

• Confirm your tenant_id, device_id, meter_id, kafka_url, portal_url, api_key values are correct.

Support

• Homepage: https://github.com/aiorch/meter-lib
• Issues: https://github.com/aiorch/meter-lib/issues