agentcore-metering 0.1.0__tar.gz

agentcore_metering-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Cloud2AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

agentcore_metering-0.1.0/MANIFEST.in

@@ -0,0 +1,13 @@
+include LICENSE
+include README.md
+include README.zh-CN.md
+include pyproject.toml
+
+recursive-include agentcore_metering/adapters/django/llm_static *.yaml *.md
+recursive-include agentcore_metering/adapters/django/locale *.po *.mo
+
+recursive-include docs *.md
+recursive-include tests *.py
+
+global-exclude *.py[cod]
+global-exclude __pycache__

agentcore_metering-0.1.0/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: agentcore-metering
+Version: 0.1.0
+Summary: Unified observability for LLM/text, image, and video calls (Django adapter)
+Author: Cloud2AI
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/cloud2ai/agentcore-metering
+Project-URL: Repository, https://github.com/cloud2ai/agentcore-metering
+Project-URL: Issues, https://github.com/cloud2ai/agentcore-metering/issues
+Project-URL: Changelog, https://github.com/cloud2ai/agentcore-metering/releases
+Keywords: django,llm,litellm,metering,observability,cost,agentcore
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Framework :: Celery
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.2
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: drf-spectacular>=0.27.0
+Requires-Dist: litellm<=1.91.3,>=1.0.0
+Requires-Dist: json-repair>=0.25.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: celery>=5.0
+Requires-Dist: agentcore-task>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-django; extra == "dev"
+Dynamic: license-file
+
+# Agentcore Metering
+
+[中文](README.zh-CN.md)
+
+Unified module for AI service invocation and statistics in Django projects.
+
+- Uses **LiteLLM** for completion and cost metering.
+- Stores cost as amount + currency (e.g. `cost`, `cost_currency`).
+- Uses USD as default cost currency from LiteLLM.
+
+---
+
+## Install
+
+- **Not on PyPI**, install only from GitHub.
+
+**From GitHub** (editable after clone):
+```bash
+pip install -e git+https://github.com/cloud2ai/agentcore-metering.git
+```
+Or, when the host project uses it as a submodule, from repo root:
+```bash
+pip install -e path/to/agentcore-metering
+```
+- The host project Dockerfile should iterate over `agentcore/`
+  submodules and run `pip install -e`.
+- See the host project README for details.
+
+---
+
+## Testing
+
+Install with dev extras, then run pytest from the package root:
+
+```bash
+pip install -e ".[dev]"
+pytest tests -v
+```
+
+- Unit tests cover:
+  - `llm_usage_stats` (parse, summary, by_model, series)
+  - `llm_usage` (paginated list and query parsing)
+- API tests cover:
+  - `GET .../token-stats/`
+  - `GET .../llm-usage/`
+  - `llm-config` endpoints (auth and response shape)
+
+---
+
+## Backend: usage
+
+1. **Register**
+   - Add `'agentcore_metering.adapters.django'` to `INSTALLED_APPS`
+   - Add `path('api/v1/admin/', include('agentcore_metering.adapters.django.urls'))` to root URLconf
+2. **Call LLM and persist usage**:
+   ```python
+   from agentcore_metering.adapters.django import LLMTracker
+   content, usage = LLMTracker.call_and_track(
+       messages=[{"role": "user", "content": "..."}],
+       node_name="my_node",
+       state=request_state,
+   )
+   ```
+   - `state` is optional (task/user context).
+   - If `state` contains `user_id`, per-user LLM config (if set) is used. Pass `model_uuid` to use a specific config; otherwise the earliest enabled model is used.
+   - For `json_mode=True` (non-stream), tracker does JSON repair + validation and retries by default (`json_attempts=3`; configurable).
+   - For `stream=True`, JSON repair is skipped (stream output is unchanged).
+3. **Config**
+   - All config can be managed by admin APIs (global defaults + optional per-user overrides).
+   - When model_uuid is not provided, resolution uses the earliest enabled config (by is_default then created_at): user scope -> global scope; no settings fallback, raises if no DB config.
+   - LLM calls go through **LiteLLM**.
+   - Cost (USD) is estimated from LiteLLM reference pricing and stored per call and in stats.
+
+### Supported providers
+
+- Each provider uses a smallest/cheapest default model to reduce
+  misconfiguration cost.
+- You can override `model` and optionally `api_base`/`deployment`
+  in `config`.
+- **All providers support `api_base` (URL)**:
+  - official endpoint when omitted
+  - proxy/forwarding URL when needed
+- If you are using an **official model endpoint**, choose the native provider
+  for that vendor, for example `minimax`.
+- If you are using a **third-party forwarding platform** through an
+  **OpenAI Compatible** endpoint, choose `openai_compatible`.
+- Do not rely on model strings to infer provider automatically; choose the
+  provider based on the actual integration path.
+
+| Provider        | Default model / notes |
+|-----------------|------------------------|
+| `openai`        | gpt-4o-mini (official default URL) |
+| `azure_openai`  | gpt-4o-mini (requires `api_base` and `deployment`) |
+| `gemini`        | gemini-2.0-flash |
+| `anthropic`     | claude-3-5-haiku |
+| `mistral`       | mistral-tiny |
+| `dashscope`     | qwen-turbo (Alibaba Qwen) |
+| `deepseek`      | deepseek-chat |
+| `xai`           | grok-3-mini-beta (Grok) |
+| `meta_llama`    | Llama-3.3-8B-Instruct |
+| `amazon_nova`   | nova-micro-v1 |
+| `nvidia_nim`    | meta/llama3-8b (Nemotron / NIM) |
+| `minimax`       | MiniMax-M2.1 |
+| `openai_compatible` | Depends on the gateway vendor (OpenAI Compatible endpoint) |
+| `moonshot`      | moonshot-v1-8k (Kimi) |
+| `zai`           | glm-4.5-flash (Z.AI GLM) |
+| `volcengine`    | doubao-pro-32k (ByteDance Doubao) |
+| `openrouter`    | google/gemma-2-9b-it:free |
+
+- Config is from DB only (admin API); no Django settings fallback. At least one enabled global or user config is required for calls.
+
+---
+
+## API reference
+
+- Mount under an admin prefix (e.g. `api/v1/admin/`).
+- **Auth**: `IsAdminUser` (staff or superuser), otherwise 403.
+- If the main project uses drf-spectacular, endpoints appear in
+  Swagger UI (e.g. `/swagger`) under **llm-metering**.
+
+### LLM configuration (global and per-user)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `.../llm-config/` | List global LLM configs (ordered by created_at, id) |
+| POST | `.../llm-config/` | Create one config. Body: `provider`, `config` (optional `scope`, `user_id`, `is_active`) |
+| GET | `.../llm-config/all/` | List all LLM configs (global + user). Optional `scope=all|global|user`, `user_id` |
+| GET | `.../llm-config/<pk>/` | Get one config by id |
+| PUT | `.../llm-config/<pk>/` | Update one config by id |
+| DELETE | `.../llm-config/<pk>/` | Delete one config by id |
+| GET | `.../llm-config/providers/` | Per-provider param schema (required/optional/editable keys, default model and api_base) for building provider-specific forms |
+| GET | `.../llm-config/models/` | Provider list and model list with capability tags (text-to-text / vision / code / reasoning, etc.) |
+| POST | `.../llm-config/test/` | Validate credentials without saving. Body: `provider`, `config` |
+| POST | `.../llm-config/test-call/` | Run one completion and persist usage. Body: `config_uuid` (or legacy `config_id`), `prompt`, optional `max_tokens`, optional `stream` (see below) |
+| GET | `.../llm-config/users/` | List per-user configs (optional `?user_id=` filter) |
+| GET | `.../llm-config/users/<user_id>/` | Get one user's config (404 if not set) |
+| PUT | `.../llm-config/users/<user_id>/` | Create or update that user's config |
+| DELETE | `.../llm-config/users/<user_id>/` | Remove user config (they fall back to global default) |
+
+- **POST/PUT body**
+  - `provider` (default `openai`)
+  - `config` (single JSON object, e.g. `api_key`, `model`, `api_base`,
+    `deployment`, `max_tokens`, `temperature`, `top_p`,
+    `request_timeout_seconds`, `num_retries`)
+  - `num_retries` defaults to `3`, accepts `0` to disable retries, and is
+    applied within the single `request_timeout_seconds` budget
+  - for create/list workflows: optional `scope`, `user_id`, `is_active`,
+    optional `model_type`
+  - required/optional keys differ by provider (e.g. Azure needs
+    `api_base` and `deployment`)
+  - use `GET .../llm-config/providers/` to fetch schema
+  - on GET, `config.api_key` and `config.key` are masked (e.g. `sk-**xxxx`); `is_default` is true when this config is the current default (earliest enabled global config used when model_uuid is not set), so the frontend can highlight the default model.
+
+- **GET `.../llm-config/providers/`**
+  - returns `{ "providers": { "<provider>": { "required": [...], "optional": [...], "editable_params": [...], "default_model": "...", "default_api_base": "..." } } }`
+  - use it to render provider-specific forms and placeholders
+
+- **POST `.../llm-config/test/`**
+  - body: `provider`, `config` (same as PUT)
+  - runs a minimal completion to verify key and endpoint
+  - success: `200` + `{ "ok": true }`
+  - validation/completion failure: `200` + `{ "ok": false, "detail": "..." }`
+  - invalid payload: `400`
+
+- **POST `.../llm-config/test-call/`**
+  - body: `config_uuid` (preferred) or legacy `config_id`, `prompt`, optional `max_tokens` (default 512, max 4096), optional `stream` (default false)
+  - when `stream` is false (default): JSON response. success: `{ "ok": true, "content": "...", "usage": { ... } }`; failure: `{ "ok": false, "detail": "..." }`
+  - when `stream` is true: response is SSE (`Content-Type: text/event-stream`). Events: `data: {"type":"chunk","content":"<fragment>"}` for each content fragment; final event `data: {"type":"done","ok":true,"usage":{...}}` or `data: {"type":"done","ok":false,"detail":"..."}`
+  - call is persisted to usage records; streaming calls are recorded with `is_streaming=true` and optional TTFT (`first_chunk_at`)
+
+### GET `.../token-stats/`
+
+- Returns aggregates and optional time series.
+- Query params are all optional:
+
+| Param        | Type   | Description |
+|--------------|--------|-------------|
+| start_date   | string | Start time, ISO or date-only (e.g. 2025-01-01) |
+| end_date     | string | End time; date-only is end of that day |
+| user_id      | int    | Filter by user id |
+| granularity  | string | Time bucket: `day` (hour), `month` (day), `year` (month); omit for no series |
+| use_series   | string | `1` / `true` / `yes`: when set with granularity and date range, also return `series_by_model` from pre-aggregated LLMUsageSeries (for per-model trend charts) |
+
+**200** (JSON):
+
+```json
+{
+  "summary": { ... },
+  "by_model": [ ... ],
+  "series": null,
+  "series_by_model": null
+}
+```
+
+- `series` is non-null only when `granularity` is set:
+  `{ "granularity": "day", "items": [ { "bucket": "...", "total_tokens": 0, ... } ] }`
+- `series_by_model` is non-null only when `use_series=1` (or `true`/`yes`) and `granularity` and `start_date`/`end_date` are set. It is a list of `{ "bucket", "model", "call_count", "success_count", "avg_e2e_latency_sec", "avg_ttft_sec", "avg_output_tps", "total_prompt_tokens", "total_completion_tokens", "total_tokens", "total_cached_tokens", "total_reasoning_tokens", "total_cost", "cost_currency" }` from the pre-aggregated table (global scope; not filtered by `user_id`). Use it for “Token trend by model” and “Cost trend by model” charts.
+- invalid `granularity` returns `400` + `{ "detail": "..." }`
+
+---
+
+### GET / PATCH `.../metering-config/`
+
+- **GET**: Returns effective metering config (retention, cleanup and aggregation schedules).
+- **PATCH**: Update config. Body fields are optional: `retention_days` (1–3650), `cleanup_enabled`, `cleanup_crontab`, `aggregation_crontab` (five-field cron expressions).
+
+**GET 200** (JSON):
+
+```json
+{
+  "retention_days": 365,
+  "cleanup_enabled": true,
+  "cleanup_crontab": "0 2 * * *",
+  "aggregation_crontab": "5 * * * *"
+}
+```
+
+- Used by the admin UI “Data settings” / “Scheduled tasks” page to configure how long to keep data and when cleanup/aggregation run.
+
+---
+
+### GET `.../llm-usage/`
+
+- Returns a paginated usage list.
+- Query params:
+
+| Param      | Type   | Description |
+|------------|--------|-------------|
+| page       | int    | Page number, default 1 |
+| page_size  | int    | Page size, default 20, max 100 |
+| user_id    | int    | Filter by user id |
+| model      | string | Model name (icontains) |
+| success    | string | `true` / `false` |
+| start_date | string | Start time |
+| end_date   | string | End time |
+
+**200** (JSON):
+
+```json
+{
+  "results": [
+    {
+      "id": "uuid",
+      "user_id": "uuid-or-null",
+      "username": "string-or-null",
+      "model": "gpt-4",
+      "prompt_tokens": 100,
+      "completion_tokens": 50,
+      "total_tokens": 150,
+      "cost": 0.0012,
+      "cost_currency": "USD",
+      "success": true,
+      "error": null,
+      "created_at": "2025-01-01T12:00:00+00:00",
+      "metadata": {}
+    }
+  ],
+  "total": 100,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+---
+
+- **UX**
+  - use `token-stats` for dashboards and trend charts
+  - use `llm-usage` for filterable, paginated call logs
+
+---
+
+## Pre-aggregated series (LLMUsageSeries)
+
+- **Table**: `llm_usage_series` stores pre-aggregated usage per **(granularity, bucket, model)**. Granularities: `hour` (for “day” view), `day` (for “month” view), `month` (for “year” view).
+- **Fields per row**: `bucket`, `model`, `call_count`, `success_count`, `avg_e2e_latency_sec`, `avg_ttft_sec`, `avg_output_tps`, token totals (`total_prompt_tokens`, `total_completion_tokens`, `total_tokens`, `total_cached_tokens`, `total_reasoning_tokens`), `total_cost`, `cost_currency`.
+- **Population**: Celery task `aggregate_llm_usage_series_task` (hour + day + month in one run when invoked from beat) aggregates from `llm_tracker_usage` into `llm_usage_series`. Use it for fast “by model” trend charts without querying raw usage on each request.
+- **API**: `GET .../token-stats/?use_series=1&granularity=...&start_date=...&end_date=...` returns `series_by_model` (list of the above rows) for charting.
+
+---
+
+## Metering config and scheduled tasks
+
+- **Config model**: `MeteringConfig` (single row) holds `retention_days` (default 365), `cleanup_enabled`, `cleanup_crontab`, `aggregation_crontab`. API: `GET` / `PATCH` `.../metering-config/` (see above).
+- **Celery tasks** (require Celery and `agentcore-task`; registered with django-celery-beat):
+  - **Cleanup**: `cleanup_old_llm_usage_task` — deletes `llm_tracker_usage` and `llm_usage_series` older than `retention_days`. No-op if `cleanup_enabled` is false.
+  - **Aggregation**: `aggregate_llm_usage_series_task` — runs hour, day, and month aggregation in one go (when called from beat without args); populates `llm_usage_series`.
+- **Task tracking**: Both tasks register with **agentcore-task** `TaskTracker` (module `agentcore_metering`). Executions appear in the unified task list and stats (status, result, error).
+
+---
+
+## Data and layout
+
+- **Tables**: `llm_tracker_usage` (usage records), `llm_usage_series` (pre-aggregated series), `agentcore_metering_llm_config` (LLM provider config), `MeteringConfig` (retention and cron settings).
+- **Package**: `agentcore_metering.adapters.django` is a full Django app (models, views, urls, admin, migrations). The public API for LLM metering lives under `trackers/` (e.g. `trackers/llm.py`); import `LLMTracker` from `agentcore_metering.adapters.django` or `agentcore_metering.adapters.django.trackers.llm`. Additional tracker types may be added under `trackers/` (e.g. `trackers/other.py`).