agentcore-metering 0.1.0__py3-none-any.whl

agentcore_metering/__init__.py

@@ -0,0 +1,6 @@
+"""
+agentcore_metering: unified observability for LLM/text, image, and video calls.
+Django app lives under adapters.django.
+"""
+
+__version__ = "0.1.0"

agentcore_metering/adapters/__init__.py

@@ -0,0 +1 @@
+# Adapters (Django, future FastAPI, etc.)

agentcore_metering/adapters/django/__init__.py

@@ -0,0 +1,14 @@
+# Django adapter: full Django app for LLM metering.
+# Public API: import LLMTracker from here or from
+# agentcore_metering.adapters.django.trackers / .trackers.llm.
+# Lazy import so that importing this package does not load Django models before
+# django.setup() / apps are ready (avoids AppRegistryNotReady).
+
+__all__ = ["LLMTracker"]
+
+
+def __getattr__(name):
+    if name == "LLMTracker":
+        from agentcore_metering.adapters.django.trackers import LLMTracker
+        return LLMTracker
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

agentcore_metering/adapters/django/admin.py

@@ -0,0 +1,64 @@
+"""Admin for LLM usage and config (agentcore_metering Django adapter)."""
+from django.contrib import admin
+
+from agentcore_metering.adapters.django.models import (
+    LLMConfig,
+    LLMUsage,
+    MeteringConfig,
+)
+
+
+@admin.register(LLMUsage)
+class LLMUsageAdmin(admin.ModelAdmin):
+    """Admin interface for LLMUsage model."""
+
+    list_display = (
+        "id",
+        "model",
+        "user",
+        "total_tokens",
+        "cost",
+        "cost_currency",
+        "prompt_tokens",
+        "completion_tokens",
+        "success",
+        "created_at",
+    )
+    list_filter = ("success", "model", "created_at")
+    search_fields = ("model", "user__username", "metadata")
+    readonly_fields = (
+        "id",
+        "user",
+        "model",
+        "prompt_tokens",
+        "completion_tokens",
+        "total_tokens",
+        "cost",
+        "cost_currency",
+        "cached_tokens",
+        "reasoning_tokens",
+        "success",
+        "error",
+        "metadata",
+        "created_at",
+    )
+    ordering = ["-created_at"]
+
+
+@admin.register(MeteringConfig)
+class MeteringConfigAdmin(admin.ModelAdmin):
+    """Admin interface for MeteringConfig (global retention, cleanup, cron)."""
+
+    list_display = ("scope", "key", "value", "updated_at")
+    list_filter = ("scope", "key")
+    ordering = ["scope", "key"]
+
+
+@admin.register(LLMConfig)
+class LLMConfigAdmin(admin.ModelAdmin):
+    """Admin interface for LLMConfig (global and per-user)."""
+
+    list_display = ("id", "scope", "user", "provider", "updated_at")
+    list_filter = ("scope", "provider")
+    search_fields = ("user__username",)
+    ordering = ["-updated_at"]

agentcore_metering/adapters/django/apps.py

@@ -0,0 +1,11 @@
+"""Django app config for agentcore_metering (LLM observability)."""
+from django.apps import AppConfig
+
+
+class AgentcoreMeteringDjangoConfig(AppConfig):
+    """App config for agentcore_metering Django adapter."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "agentcore_metering.adapters.django"
+    label = "agentcore_metering"
+    verbose_name = "Agentcore Metering (LLM)"

agentcore_metering/adapters/django/cleanup.py

@@ -0,0 +1,91 @@
+"""
+Cleanup of old LLM usage and series records.
+
+Uses conf when arguments are omitted. Call directly or via Celery task.
+Default retention: 365 days (configurable via MeteringConfig or settings).
+"""
+import logging
+from datetime import timedelta
+from typing import Any, Dict, Optional
+
+from django.utils import timezone
+
+from agentcore_metering.adapters.django.conf import get_retention_days
+from agentcore_metering.adapters.django.models import LLMUsage, LLMUsageSeries
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BATCH_SIZE = 5000
+
+
+def cleanup_old_llm_usage(
+    retention_days: Optional[int] = None,
+    batch_size: Optional[int] = None,
+) -> Dict[str, Any]:
+    """
+    Delete LLMUsage and LLMUsageSeries older than retention_days.
+
+    Returns dict with deleted_usage, deleted_series, cutoff, retention_days.
+    """
+    if retention_days is None:
+        retention_days = get_retention_days()
+
+    if retention_days <= 0:
+        logger.warning(
+            f"cleanup_old_llm_usage: retention_days={retention_days} <= 0, "
+            "skipping"
+        )
+        return {
+            "deleted_usage": 0,
+            "deleted_series": 0,
+            "cutoff": timezone.now(),
+            "retention_days": retention_days,
+            "skipped": True,
+            "reason": "invalid_retention_days",
+        }
+
+    cutoff = timezone.now() - timedelta(days=retention_days)
+    batch_size = batch_size or DEFAULT_BATCH_SIZE
+
+    deleted_usage = 0
+    if batch_size <= 0:
+        deleted_usage, _ = (
+            LLMUsage.objects.filter(created_at__lt=cutoff).delete()
+        )
+    else:
+        while True:
+            batch = list(
+                LLMUsage.objects.filter(created_at__lt=cutoff)
+                .values_list("pk", flat=True)[:batch_size]
+            )
+            if not batch:
+                break
+            n, _ = LLMUsage.objects.filter(pk__in=batch).delete()
+            deleted_usage += n
+
+    deleted_series = 0
+    if batch_size <= 0:
+        deleted_series, _ = (
+            LLMUsageSeries.objects.filter(bucket__lt=cutoff).delete()
+        )
+    else:
+        while True:
+            batch = list(
+                LLMUsageSeries.objects.filter(bucket__lt=cutoff)
+                .values_list("pk", flat=True)[:batch_size]
+            )
+            if not batch:
+                break
+            n, _ = LLMUsageSeries.objects.filter(pk__in=batch).delete()
+            deleted_series += n
+
+    logger.info(
+        f"cleanup_old_llm_usage: deleted_usage={deleted_usage} "
+        f"deleted_series={deleted_series} retention_days={retention_days}"
+    )
+    return {
+        "deleted_usage": deleted_usage,
+        "deleted_series": deleted_series,
+        "cutoff": cutoff,
+        "retention_days": retention_days,
+    }

agentcore_metering/adapters/django/conf.py

@@ -0,0 +1,174 @@
+"""
+Global config for agentcore_metering: retention, cleanup, aggregation.
+
+Reads from MeteringConfig (DB) first, then Django settings. Used by periodic
+tasks and config API for frontend management.
+"""
+from django.conf import settings
+
+try:
+    from celery.schedules import crontab
+except ImportError:
+    crontab = None
+
+DEFAULT_RETENTION_DAYS = 365
+DEFAULT_CLEANUP_ENABLED = True
+DEFAULT_CLEANUP_CRONTAB = "0 2 * * *"
+DEFAULT_AGGREGATION_CRONTAB = "5 * * * *"
+
+# Timezone for "yesterday" / "last month" when computing aggregation range.
+# Celery may run at 02:00 Shanghai; we aggregate Shanghai's yesterday.
+DEFAULT_AGGREGATION_TIMEZONE = "Asia/Shanghai"
+
+
+def _get_global_config(key: str):
+    # NOTE(Ray): Lazy import to avoid circular import (conf used by
+    # services.__init__, tasks, apps.ready(); metering_config may import conf).
+    from agentcore_metering.adapters.django.services import metering_config
+
+    return metering_config.get_global_config(key)
+
+
+def get_retention_days() -> int:
+    """
+    Retention days for cleanup: MeteringConfig first, else settings.
+    Default 365 days.
+    """
+    val = _get_global_config("retention_days")
+    if isinstance(val, int) and val > 0:
+        return val
+    return getattr(
+        settings,
+        "AGENTCORE_METERING_RETENTION_DAYS",
+        DEFAULT_RETENTION_DAYS,
+    )
+
+
+def get_cleanup_enabled() -> bool:
+    """Whether cleanup beat task is enabled (default True)."""
+    val = _get_global_config("cleanup_enabled")
+    if val is not None:
+        return bool(val)
+    return getattr(
+        settings,
+        "AGENTCORE_METERING_CLEANUP_ENABLED",
+        DEFAULT_CLEANUP_ENABLED,
+    )
+
+
+def get_cleanup_crontab() -> str:
+    """Five-field cron expression for cleanup (default daily 2:00)."""
+    val = _get_global_config("cleanup_crontab")
+    if isinstance(val, str) and val.strip():
+        return val.strip()
+    return getattr(
+        settings,
+        "AGENTCORE_METERING_CLEANUP_CRONTAB",
+        DEFAULT_CLEANUP_CRONTAB,
+    )
+
+
+def get_aggregation_crontab() -> str:
+    """
+    Cron for aggregation task (hour/day/month in one run).
+    Default: minute 5 past each hour (5 * * * *).
+    """
+    val = _get_global_config("aggregation_crontab")
+    if isinstance(val, str) and val.strip():
+        return val.strip()
+    return getattr(
+        settings,
+        "AGENTCORE_METERING_AGGREGATION_CRONTAB",
+        DEFAULT_AGGREGATION_CRONTAB,
+    )
+
+
+def get_aggregation_timezone() -> str:
+    """
+    Timezone for computing aggregation date range (yesterday, last month).
+    Ensures "yesterday" is the calendar day in this timezone; range is then
+    converted to UTC for DB query. Default Asia/Shanghai.
+    """
+    return getattr(
+        settings,
+        "AGENTCORE_METERING_AGGREGATION_TIMEZONE",
+        DEFAULT_AGGREGATION_TIMEZONE,
+    )
+
+
+def _crontab_from_expression(expr: str):
+    """Parse 5-field cron into Celery crontab. On parse error returns None."""
+    if not crontab or not expr:
+        return None
+    parts = str(expr).strip().split()
+    if len(parts) != 5:
+        return None
+    try:
+        return crontab(
+            minute=parts[0],
+            hour=parts[1],
+            day_of_month=parts[2],
+            month_of_year=parts[3],
+            day_of_week=parts[4],
+        )
+    except (TypeError, ValueError):
+        return None
+
+
+def is_valid_crontab_expression(expr: str) -> bool:
+    """Return True if expr is a valid 5-field cron expression."""
+    if not expr or not str(expr).strip():
+        return False
+    return _crontab_from_expression(str(expr).strip()) is not None
+
+
+def get_cleanup_beat_schedule_init():
+    """
+    Build cleanup beat schedule from Django settings only (no DB in init).
+    For use in periodic_tasks.register_periodic_tasks.
+    """
+    task_name = (
+        "agentcore_metering.adapters.django.tasks.cleanup."
+        "cleanup_old_llm_usage_task"
+    )
+    crontab_str = getattr(
+        settings,
+        "AGENTCORE_METERING_CLEANUP_CRONTAB",
+        DEFAULT_CLEANUP_CRONTAB,
+    )
+    schedule = _crontab_from_expression(crontab_str)
+    if schedule is None:
+        schedule = 24 * 3600.0
+    return {
+        "agentcore-metering-cleanup-old-usage": {
+            "task": task_name,
+            "schedule": schedule,
+            "options": {},
+        }
+    }
+
+
+def get_aggregation_beat_schedule_init():
+    """
+    Build single aggregation beat schedule from settings only.
+    One task runs hour + day + month aggregation each time.
+    """
+    task_name = (
+        "agentcore_metering.adapters.django.tasks.aggregate."
+        "aggregate_llm_usage_series_task"
+    )
+    crontab_str = getattr(
+        settings,
+        "AGENTCORE_METERING_AGGREGATION_CRONTAB",
+        DEFAULT_AGGREGATION_CRONTAB,
+    )
+    schedule = _crontab_from_expression(crontab_str)
+    if schedule is None:
+        schedule = 3600.0
+    return {
+        "agentcore-metering-aggregate": {
+            "task": task_name,
+            "schedule": schedule,
+            "options": {},
+        }
+    }

agentcore_metering/adapters/django/llm_static/README.md

@@ -0,0 +1,25 @@
+# LLM static data (YAML)
+
+Capability labels, mode mapping, provider/model lists, and reference pricing. Used by the Django adapter for the LLM config UI and resolution.
+
+## Price update time
+
+Reference prices in `providers/*.yaml` were last updated: **2026-02**. Consider updating periodically from provider docs or [LLM Stats](https://llm-stats.com/).
+
+## Reference pricing (schema)
+
+Prices under `reference_pricing` per model are **reference only** and not used for billing. They help compare cost across providers and models in the UI.
+
+### Data sources
+
+- **Official provider pages**: [OpenAI Pricing](https://openai.com/api/pricing), [Anthropic Pricing](https://docs.anthropic.com/en/docs/about-claude/pricing), [Gemini Pricing](https://ai.google.dev/gemini-api/docs/pricing), [DeepSeek Pricing](https://api-docs.deepseek.com/quick_start/pricing), etc.
+- **Comparison / benchmarks**: [LLM Stats](https://llm-stats.com/) — leaderboards, benchmarks, and cost comparison for many models (LLM, Coding, Image, etc.). Use it to cross-check model names and compare performance vs cost.
+
+### Schema (per model)
+
+Optional `reference_pricing` on a model entry:
+
+- `input_usd_per_1m`: USD per 1M input tokens (optional)
+- `output_usd_per_1m`: USD per 1M output tokens (optional)
+- `source`: URL or short label (e.g. provider pricing page)
+- `updated`: Date string (e.g. `2026-02`) when the price was last checked

agentcore_metering/adapters/django/llm_static/__init__.py

@@ -0,0 +1,2 @@
+# LLM static data (capability labels, mode mapping, providers and models)
+# loaded from YAML. See load.py for the loader API.

agentcore_metering/adapters/django/llm_static/capability_labels.yaml

@@ -0,0 +1,12 @@
+# Capability tag id -> short label for UI (aligned with product tier docs)
+text-to-text: Text-to-Text
+code: Code
+vision: Vision Input
+multimodal: MultiModal
+text-to-image: Text-to-Image
+long-context: Long Context
+low-cost: Low Cost
+embedding: Embedding
+reasoning: Reasoning
+speech-to-text: Speech-to-Text
+text-to-speech: Text-to-Speech

agentcore_metering/adapters/django/llm_static/load.py

@@ -0,0 +1,135 @@
+"""
+Load capability labels, mode->model_type mapping, and provider/model data
+from YAML. Data is under this package (llm_static/*.yaml,
+llm_static/providers/*.yaml). Paths are resolved relative to this file
+so it works when the package is installed.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Optional
+
+import yaml
+
+_THIS_DIR = os.path.dirname(os.path.abspath(__file__))
+
+_capability_labels: Optional[Dict[str, str]] = None
+_mode_to_model_type: Optional[Dict[str, str]] = None
+_providers_with_models: Optional[Dict[str, Any]] = None
+_provider_defaults: Optional[Dict[str, Dict[str, Any]]] = None
+
+
+def _path(*parts: str) -> str:
+    return os.path.join(_THIS_DIR, *parts)
+
+
+def _load_yaml(filename: str) -> Any:
+    with open(_path(filename), encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def get_capability_labels() -> Dict[str, str]:
+    """
+    Load capability tag id -> short label for UI. Cached after first load.
+    """
+    global _capability_labels
+    if _capability_labels is None:
+        _capability_labels = _load_yaml("capability_labels.yaml") or {}
+    return _capability_labels
+
+
+def get_mode_to_model_type() -> Dict[str, str]:
+    """Load mode -> model_type for resolver. Cached after first load."""
+    global _mode_to_model_type
+    if _mode_to_model_type is None:
+        _mode_to_model_type = _load_yaml("mode_to_model_type.yaml") or {}
+    return _mode_to_model_type
+
+
+def _normalize_model(m: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Ensure each model dict has id, label, capabilities, mode;
+    optional max_input/max_output, reference_pricing.
+    """
+    out: Dict[str, Any] = {
+        "id": str(m.get("id", "")),
+        "label": str(m.get("label", "")),
+        "capabilities": list(m.get("capabilities") or []),
+        "max_input_tokens": m.get("max_input_tokens"),
+        "max_output_tokens": m.get("max_output_tokens"),
+        "mode": str(m.get("mode", "chat")),
+    }
+    rp = m.get("reference_pricing")
+    if not isinstance(rp, dict):
+        return out
+    has_input = rp.get("input_usd_per_1m") is not None
+    has_output = rp.get("output_usd_per_1m") is not None
+    if has_input or has_output:
+        out["reference_pricing"] = {
+            "input_usd_per_1m": rp.get("input_usd_per_1m"),
+            "output_usd_per_1m": rp.get("output_usd_per_1m"),
+            "source": rp.get("source"),
+            "updated": rp.get("updated"),
+        }
+    return out
+
+
+def get_providers_with_models() -> Dict[str, Any]:
+    """
+    Load providers list (in index order) with models and capability_labels.
+    Same shape as before: { "providers": [...], "capability_labels": {...} }.
+    Cached.
+    """
+    global _providers_with_models
+    if _providers_with_models is not None:
+        return _providers_with_models
+    index = _load_yaml("providers/index.yaml") or {}
+    provider_ids = index.get("provider_ids") or []
+    providers = []
+    for pid in provider_ids:
+        path = os.path.join("providers", f"{pid}.yaml")
+        if not os.path.isfile(_path(path)):
+            continue
+        data = _load_yaml(path) or {}
+        models = [_normalize_model(m) for m in (data.get("models") or [])]
+        providers.append({
+            "id": str(data.get("id", pid)),
+            "label": str(data.get("label", pid)),
+            "models": models,
+        })
+    _providers_with_models = {
+        "providers": providers,
+        "capability_labels": get_capability_labels(),
+    }
+    return _providers_with_models
+
+
+def get_provider_defaults() -> Dict[str, Dict[str, Any]]:
+    """
+    Load per-provider defaults: default_api_base, default_model,
+    default_temperature, default_top_p, default_max_tokens, settings_key,
+    requires_api_base. Keys are provider ids. Cached. Only includes providers
+    that have a YAML file in providers/.
+    """
+    global _provider_defaults
+    if _provider_defaults is not None:
+        return _provider_defaults
+    index = _load_yaml("providers/index.yaml") or {}
+    provider_ids = index.get("provider_ids") or []
+    out: Dict[str, Dict[str, Any]] = {}
+    for pid in provider_ids:
+        path = os.path.join("providers", f"{pid}.yaml")
+        if not os.path.isfile(_path(path)):
+            continue
+        data = _load_yaml(path) or {}
+        out[pid] = {
+            "default_api_base": data.get("default_api_base"),
+            "default_model": data.get("default_model"),
+            "default_temperature": data.get("default_temperature"),
+            "default_top_p": data.get("default_top_p"),
+            "default_max_tokens": data.get("default_max_tokens"),
+            "settings_key": data.get("settings_key"),
+            "requires_api_base": bool(data.get("requires_api_base", False)),
+        }
+    _provider_defaults = out
+    return _provider_defaults

agentcore_metering/adapters/django/llm_static/mode_to_model_type.yaml

@@ -0,0 +1,7 @@
+# Resolver model_type derived from primary mode
+chat: llm
+completion: llm
+embedding: embedding
+image_generation: image_generation
+audio_transcription: llm
+audio_speech: llm

agentcore_metering/adapters/django/llm_static/providers/amazon_nova.yaml

@@ -0,0 +1,13 @@
+id: amazon_nova
+label: Amazon Nova
+default_api_base: null
+default_model: nova-micro-v1
+settings_key: AMAZON_NOVA_CONFIG
+requires_api_base: false
+models:
+  - id: nova-micro-v1
+    label: Nova Micro v1
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 128000
+    max_output_tokens: 8192
+    mode: chat

agentcore_metering/adapters/django/llm_static/providers/anthropic.yaml

@@ -0,0 +1,59 @@
+id: anthropic
+label: Anthropic
+default_api_base: "https://api.anthropic.com"
+default_model: claude-3-5-haiku-20241022
+settings_key: ANTHROPIC_CONFIG
+requires_api_base: false
+models:
+  - id: claude-opus-4-6
+    label: Claude Opus 4.6
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 200000
+    max_output_tokens: 8192
+    mode: chat
+    reference_pricing:
+      input_usd_per_1m: 5.0
+      output_usd_per_1m: 25.0
+      source: "https://docs.anthropic.com/en/docs/about-claude/pricing"
+      updated: "2026-02"
+  - id: claude-sonnet-4-6
+    label: Claude Sonnet 4.6
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 200000
+    max_output_tokens: 8192
+    mode: chat
+    reference_pricing:
+      input_usd_per_1m: 3.0
+      output_usd_per_1m: 15.0
+      source: "https://docs.anthropic.com/en/docs/about-claude/pricing"
+      updated: "2026-02"
+  - id: claude-opus-4-5-20251101
+    label: Claude Opus 4.5
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 200000
+    max_output_tokens: 8192
+    mode: chat
+  - id: claude-sonnet-4-5-20250929
+    label: Claude Sonnet 4.5
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 200000
+    max_output_tokens: 8192
+    mode: chat
+  - id: claude-sonnet-4-20250514
+    label: Claude Sonnet 4
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 200000
+    max_output_tokens: 8192
+    mode: chat
+  - id: claude-3-5-sonnet-20241022
+    label: Claude 3.5 Sonnet
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 200000
+    max_output_tokens: 8192
+    mode: chat
+  - id: claude-3-5-haiku-20241022
+    label: Claude 3.5 Haiku
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 200000
+    max_output_tokens: 8192
+    mode: chat

agentcore_metering/adapters/django/llm_static/providers/azure_openai.yaml

@@ -0,0 +1,60 @@
+id: azure_openai
+label: Azure OpenAI
+default_model: gpt-4o-mini
+settings_key: AZURE_OPENAI_CONFIG
+requires_api_base: true
+models:
+  - id: gpt-5.2
+    label: GPT-5.2
+    capabilities: [text-to-text, vision, code, multimodal, long-context]
+    max_input_tokens: 128000
+    max_output_tokens: 16384
+    mode: chat
+  - id: gpt-5.2-pro
+    label: GPT-5.2 Pro
+    capabilities: [text-to-text, vision, code, multimodal, long-context]
+    max_input_tokens: 128000
+    max_output_tokens: 16384
+    mode: chat
+  - id: gpt-4-mini
+    label: GPT-4 Mini
+    capabilities: [text-to-text, long-context]
+    max_input_tokens: 128000
+    max_output_tokens: 16384
+    mode: chat
+  - id: gpt-5-mini
+    label: GPT-5 Mini
+    capabilities: [text-to-text, vision, long-context]
+    max_input_tokens: 128000
+    max_output_tokens: 16384
+    mode: chat
+  - id: gpt-5-nano
+    label: GPT-5 Nano
+    capabilities: [text-to-text, low-cost]
+    max_input_tokens: 128000
+    max_output_tokens: 8192
+    mode: chat
+  - id: gpt-4o
+    label: GPT-4o
+    capabilities: [text-to-text, vision, long-context]
+    max_input_tokens: 128000
+    max_output_tokens: 16384
+    mode: chat
+  - id: gpt-4o-mini
+    label: GPT-4o Mini
+    capabilities: [text-to-text, vision, long-context]
+    max_input_tokens: 128000
+    max_output_tokens: 16384
+    mode: chat
+  - id: o1
+    label: O1
+    capabilities: [text-to-text, long-context, reasoning]
+    max_input_tokens: 200000
+    max_output_tokens: 100000
+    mode: chat
+  - id: o1-mini
+    label: O1 Mini
+    capabilities: [text-to-text, long-context, reasoning]
+    max_input_tokens: 128000
+    max_output_tokens: 65536
+    mode: chat