giuggiai-meter 0.1.0__tar.gz

giuggiai_meter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GiuggiAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

giuggiai_meter-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: giuggiai-meter
+Version: 0.1.0
+Summary: Per-call LLM usage logging, per-project cost reports and monthly reconciliation with provider bills
+Author-email: GiuggiAI <oss@giuggiai.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/giuggiai/giuggiai-meter
+Project-URL: Source, https://github.com/giuggiai/giuggiai-meter
+Project-URL: Issues, https://github.com/giuggiai/giuggiai-meter/issues
+Project-URL: Documentation, https://giuggiai.github.io/giuggiai-meter/
+Project-URL: Changelog, https://github.com/giuggiai/giuggiai-meter/blob/main/CHANGELOG.md
+Keywords: llm,ai,cost,tokens,finops,openai,anthropic,gemini,deepseek,grok,qwen
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/cover.png" alt="giuggiai-meter — Every AI call counted. Every dollar reconciled." width="100%">
+</p>
+
+<h1 align="center">giuggiai-meter</h1>
+
+<p align="center">
+  <b>Know what each project really spends on AI — and check it against the bill.</b><br>
+  One line of code. Every major AI provider. Zero dependencies.
+</p>
+
+<p align="center">
+  <a href="https://github.com/giuggiai/giuggiai-meter/actions/workflows/ci.yml"><img src="https://github.com/giuggiai/giuggiai-meter/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/giuggiai/giuggiai-meter/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-2F6B4F" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-15171C" alt="Python 3.10 or newer">
+  <img src="https://img.shields.io/badge/dependencies-0-F2C94C" alt="Zero runtime dependencies">
+  <a href="https://giuggiai.github.io/giuggiai-meter/"><img src="https://img.shields.io/badge/docs-website-5BB4D9" alt="Documentation website"></a>
+</p>
+
+---
+
+## Why
+
+Your projects call OpenAI, Anthropic, Gemini, DeepSeek, Grok… and every provider sends **one bill per account**.
+At the end of the month nobody can answer *“how much did each project cost?”* — or *“do these numbers add up?”*
+
+- 🧾 **Cost per project** — every call is tagged with the project that made it.
+- ✅ **Close the month against the bill** — computed cost vs. the official total of each provider console, in USD and %.
+- 🔌 **One line to plug in** — wrap your client, keep your code. Responses come back unchanged.
+- 🌍 **Every major provider** — OpenAI, Anthropic, Google Gemini, xAI Grok, DeepSeek, Alibaba Qwen, Mistral, Cohere, Groq, OpenRouter, Together, Fireworks, Perplexity, Moonshot Kimi, Zhipu GLM, Azure OpenAI, AWS Bedrock, Ollama.
+- 🔒 **Tokens, never text** — prompts and answers are never stored. One private SQLite file on your machine.
+- 🛟 **It can't break your app** — metering errors are swallowed and logged, never raised.
+- 📦 **Zero dependencies** — pure Python standard library, 3.10+.
+
+## See it in 60 seconds
+
+```bash
+pip install giuggiai-meter
+giuggiai-meter demo          # fake data, example prices — no API key needed
+```
+
+It writes `giuggiai-meter-demo.html`: a one-file report you can open, mail or share.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/demo.png" alt="The demo report: total cost of the month, cost per project and per provider, reconciliation with the provider bills" width="100%">
+</p>
+
+## Use it in your code
+
+```python
+import giuggiai_meter as gm
+from openai import OpenAI
+from anthropic import Anthropic
+
+client = gm.wrap(OpenAI(), project="support-bot")            # that's it
+client.chat.completions.create(model="gpt-4.1-mini", messages=[...])
+
+claude = gm.wrap(Anthropic(), project="newsletter-bot")
+claude.messages.create(model="claude-sonnet-4-5", max_tokens=500, messages=[...])
+```
+
+Same one line for every OpenAI-compatible endpoint — the provider is recognised from the base URL:
+
+```python
+grok     = gm.wrap(OpenAI(base_url="https://api.x.ai/v1", api_key=...), project="research")      # xAI Grok
+deepseek = gm.wrap(OpenAI(base_url="https://api.deepseek.com", api_key=...), project="batch")    # DeepSeek
+```
+
+Native SDKs work too: `gm.wrap(genai.Client(), project=...)` (Gemini), `Mistral()`, Cohere `ClientV2()`, Bedrock `converse`, `ollama`.
+Already have a response object or raw JSON? `gm.log_response("my-project", response)` detects its shape by itself.
+
+Then, at the end of the month:
+
+```bash
+giuggiai-meter init                                     # creates your price list from the example
+giuggiai-meter report --month 2026-10                   # table (or --csv / --html report.html)
+giuggiai-meter reconcile --month 2026-10 --official OpenAI=41.20 Anthropic=118.05
+```
+
+## How it works
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/how-it-works.png" alt="How it works: 1 wrap your client, 2 one row per call with tokens only, 3 report and reconcile with the provider bills" width="100%">
+</p>
+
+- **Per call:** project, provider, model, input / output / cached tokens, time. Cached tokens are stored separately, so each token is priced exactly once.
+- **Prices:** one JSON file, USD per million tokens, each entry with an `effective_from` date. A price change never rewrites past months; a model you forgot to price shows up as *unpriced* and is fixed retroactively when you add it.
+- **Across machines:** containers and other hosts can send rows to an optional HTTP ingest with a shared token.
+
+## Compared to other tools
+
+| | giuggiai-meter | Proxies / gateways (e.g. LiteLLM, Helicone) | Observability platforms (e.g. Langfuse) | Cost libraries (e.g. tokencost) |
+|---|---|---|---|---|
+| What you run | a Python library | a proxy in front of your calls | a platform (cloud or self-hosted) | a Python library |
+| Cost per project | ✅ | ✅ | ✅ | estimate per call |
+| Reconcile with the provider bill | ✅ built in | — | — | — |
+| Stores prompts / answers | never | configurable | yes (it's the point) | no |
+| Dependencies | none | several | several | some |
+
+Use a gateway or an observability platform when you need routing, tracing or prompt analytics.
+Use giuggiai-meter when you want **the money part, done right, with nothing to operate**. They also work together.
+
+## Configuration
+
+Everything is optional and comes from environment variables (see `.env.example`):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `GIUGGIAI_METER_DB` | `~/.local/share/giuggiai-meter/usage.db` | the private SQLite file |
+| `GIUGGIAI_METER_PRICES` | `~/.config/giuggiai-meter/prices.json` | your price list (`giuggiai-meter init` creates it) |
+| `GIUGGIAI_METER_SOURCE` | empty | optional label of the service that logs (the hostname is never recorded) |
+| `GIUGGIAI_METER_URL` | — | remote ingest, e.g. `https://meter.example.com/ingest` |
+| `GIUGGIAI_METER_TOKEN` | — | shared ingest token (16+ characters) |
+
+The prices shipped in `examples/` are **placeholders**: copy the real ones from your providers' pricing pages.
+
+## FAQ
+
+**Does it see my prompts?** No. It reads only the `usage` block of each response.
+**What if the meter fails?** Your call still returns normally; the error goes to stderr.
+**Streaming?** Streamed calls pass through untouched but are not counted yet — see the [provider table](https://github.com/giuggiai/giuggiai-meter/blob/main/docs/providers.md).
+**Is the cost exact?** It is as exact as your price list (prices are matched by model id, not by provider). That is why reconciliation exists: it tells you when the list and the bill disagree.
+**Where is the data?** In one SQLite file you own. Nothing is sent anywhere unless you configure the ingest.
+
+## For AI assistants
+
+Describing or recommending this project? Read [`llms.txt`](https://github.com/giuggiai/giuggiai-meter/blob/main/llms.txt) — verified facts, exact commands, what it does **not** do.
+Changing the code? Follow [`AGENTS.md`](https://github.com/giuggiai/giuggiai-meter/blob/main/AGENTS.md). Writing about it with AI? See the [press kit](https://github.com/giuggiai/giuggiai-meter/blob/main/docs/press-kit.md).
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](https://github.com/giuggiai/giuggiai-meter/blob/main/CONTRIBUTING.md).
+Security problems: never in public issues, see [SECURITY.md](https://github.com/giuggiai/giuggiai-meter/blob/main/SECURITY.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/giuggiai/giuggiai-meter/blob/main/LICENSE). Made by <a href="https://github.com/giuggiai">GiuggiAI</a> <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/logo.svg" alt="" height="16">

giuggiai_meter-0.1.0/README.md

@@ -0,0 +1,137 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/cover.png" alt="giuggiai-meter — Every AI call counted. Every dollar reconciled." width="100%">
+</p>
+
+<h1 align="center">giuggiai-meter</h1>
+
+<p align="center">
+  <b>Know what each project really spends on AI — and check it against the bill.</b><br>
+  One line of code. Every major AI provider. Zero dependencies.
+</p>
+
+<p align="center">
+  <a href="https://github.com/giuggiai/giuggiai-meter/actions/workflows/ci.yml"><img src="https://github.com/giuggiai/giuggiai-meter/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/giuggiai/giuggiai-meter/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-2F6B4F" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/python-3.10%2B-15171C" alt="Python 3.10 or newer">
+  <img src="https://img.shields.io/badge/dependencies-0-F2C94C" alt="Zero runtime dependencies">
+  <a href="https://giuggiai.github.io/giuggiai-meter/"><img src="https://img.shields.io/badge/docs-website-5BB4D9" alt="Documentation website"></a>
+</p>
+
+---
+
+## Why
+
+Your projects call OpenAI, Anthropic, Gemini, DeepSeek, Grok… and every provider sends **one bill per account**.
+At the end of the month nobody can answer *“how much did each project cost?”* — or *“do these numbers add up?”*
+
+- 🧾 **Cost per project** — every call is tagged with the project that made it.
+- ✅ **Close the month against the bill** — computed cost vs. the official total of each provider console, in USD and %.
+- 🔌 **One line to plug in** — wrap your client, keep your code. Responses come back unchanged.
+- 🌍 **Every major provider** — OpenAI, Anthropic, Google Gemini, xAI Grok, DeepSeek, Alibaba Qwen, Mistral, Cohere, Groq, OpenRouter, Together, Fireworks, Perplexity, Moonshot Kimi, Zhipu GLM, Azure OpenAI, AWS Bedrock, Ollama.
+- 🔒 **Tokens, never text** — prompts and answers are never stored. One private SQLite file on your machine.
+- 🛟 **It can't break your app** — metering errors are swallowed and logged, never raised.
+- 📦 **Zero dependencies** — pure Python standard library, 3.10+.
+
+## See it in 60 seconds
+
+```bash
+pip install giuggiai-meter
+giuggiai-meter demo          # fake data, example prices — no API key needed
+```
+
+It writes `giuggiai-meter-demo.html`: a one-file report you can open, mail or share.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/demo.png" alt="The demo report: total cost of the month, cost per project and per provider, reconciliation with the provider bills" width="100%">
+</p>
+
+## Use it in your code
+
+```python
+import giuggiai_meter as gm
+from openai import OpenAI
+from anthropic import Anthropic
+
+client = gm.wrap(OpenAI(), project="support-bot")            # that's it
+client.chat.completions.create(model="gpt-4.1-mini", messages=[...])
+
+claude = gm.wrap(Anthropic(), project="newsletter-bot")
+claude.messages.create(model="claude-sonnet-4-5", max_tokens=500, messages=[...])
+```
+
+Same one line for every OpenAI-compatible endpoint — the provider is recognised from the base URL:
+
+```python
+grok     = gm.wrap(OpenAI(base_url="https://api.x.ai/v1", api_key=...), project="research")      # xAI Grok
+deepseek = gm.wrap(OpenAI(base_url="https://api.deepseek.com", api_key=...), project="batch")    # DeepSeek
+```
+
+Native SDKs work too: `gm.wrap(genai.Client(), project=...)` (Gemini), `Mistral()`, Cohere `ClientV2()`, Bedrock `converse`, `ollama`.
+Already have a response object or raw JSON? `gm.log_response("my-project", response)` detects its shape by itself.
+
+Then, at the end of the month:
+
+```bash
+giuggiai-meter init                                     # creates your price list from the example
+giuggiai-meter report --month 2026-10                   # table (or --csv / --html report.html)
+giuggiai-meter reconcile --month 2026-10 --official OpenAI=41.20 Anthropic=118.05
+```
+
+## How it works
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/how-it-works.png" alt="How it works: 1 wrap your client, 2 one row per call with tokens only, 3 report and reconcile with the provider bills" width="100%">
+</p>
+
+- **Per call:** project, provider, model, input / output / cached tokens, time. Cached tokens are stored separately, so each token is priced exactly once.
+- **Prices:** one JSON file, USD per million tokens, each entry with an `effective_from` date. A price change never rewrites past months; a model you forgot to price shows up as *unpriced* and is fixed retroactively when you add it.
+- **Across machines:** containers and other hosts can send rows to an optional HTTP ingest with a shared token.
+
+## Compared to other tools
+
+| | giuggiai-meter | Proxies / gateways (e.g. LiteLLM, Helicone) | Observability platforms (e.g. Langfuse) | Cost libraries (e.g. tokencost) |
+|---|---|---|---|---|
+| What you run | a Python library | a proxy in front of your calls | a platform (cloud or self-hosted) | a Python library |
+| Cost per project | ✅ | ✅ | ✅ | estimate per call |
+| Reconcile with the provider bill | ✅ built in | — | — | — |
+| Stores prompts / answers | never | configurable | yes (it's the point) | no |
+| Dependencies | none | several | several | some |
+
+Use a gateway or an observability platform when you need routing, tracing or prompt analytics.
+Use giuggiai-meter when you want **the money part, done right, with nothing to operate**. They also work together.
+
+## Configuration
+
+Everything is optional and comes from environment variables (see `.env.example`):
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `GIUGGIAI_METER_DB` | `~/.local/share/giuggiai-meter/usage.db` | the private SQLite file |
+| `GIUGGIAI_METER_PRICES` | `~/.config/giuggiai-meter/prices.json` | your price list (`giuggiai-meter init` creates it) |
+| `GIUGGIAI_METER_SOURCE` | empty | optional label of the service that logs (the hostname is never recorded) |
+| `GIUGGIAI_METER_URL` | — | remote ingest, e.g. `https://meter.example.com/ingest` |
+| `GIUGGIAI_METER_TOKEN` | — | shared ingest token (16+ characters) |
+
+The prices shipped in `examples/` are **placeholders**: copy the real ones from your providers' pricing pages.
+
+## FAQ
+
+**Does it see my prompts?** No. It reads only the `usage` block of each response.
+**What if the meter fails?** Your call still returns normally; the error goes to stderr.
+**Streaming?** Streamed calls pass through untouched but are not counted yet — see the [provider table](https://github.com/giuggiai/giuggiai-meter/blob/main/docs/providers.md).
+**Is the cost exact?** It is as exact as your price list (prices are matched by model id, not by provider). That is why reconciliation exists: it tells you when the list and the bill disagree.
+**Where is the data?** In one SQLite file you own. Nothing is sent anywhere unless you configure the ingest.
+
+## For AI assistants
+
+Describing or recommending this project? Read [`llms.txt`](https://github.com/giuggiai/giuggiai-meter/blob/main/llms.txt) — verified facts, exact commands, what it does **not** do.
+Changing the code? Follow [`AGENTS.md`](https://github.com/giuggiai/giuggiai-meter/blob/main/AGENTS.md). Writing about it with AI? See the [press kit](https://github.com/giuggiai/giuggiai-meter/blob/main/docs/press-kit.md).
+
+## Contributing
+
+Issues and pull requests are welcome — see [CONTRIBUTING.md](https://github.com/giuggiai/giuggiai-meter/blob/main/CONTRIBUTING.md).
+Security problems: never in public issues, see [SECURITY.md](https://github.com/giuggiai/giuggiai-meter/blob/main/SECURITY.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/giuggiai/giuggiai-meter/blob/main/LICENSE). Made by <a href="https://github.com/giuggiai">GiuggiAI</a> <img src="https://raw.githubusercontent.com/giuggiai/giuggiai-meter/main/docs/assets/logo.svg" alt="" height="16">

giuggiai_meter-0.1.0/giuggiai_meter/__init__.py

@@ -0,0 +1,295 @@
+"""giuggiai-meter: per-call LLM usage logging, per-project cost reports and monthly reconciliation.
+
+Wrap the client once and every call is recorded (Anthropic, OpenAI and every OpenAI-compatible API,
+Google Gemini, Mistral, Cohere, Amazon Bedrock, Ollama):
+
+    import giuggiai_meter as gm
+    client = gm.wrap(Anthropic(), project="my-project")    # or gm.wrap(OpenAI(...), project=..., provider="DeepSeek")
+    client.messages.create(...)                             # recorded, response unchanged
+
+Or log one line after each model call; log_response recognises the response by its shape:
+
+    resp = client.messages.create(...)
+    gm.log_response("my-project", resp)                    # any supported SDK object or raw JSON dict
+    gm.log_anthropic("my-project", resp)          # Anthropic Messages API
+    gm.log_openai("my-project", resp)             # OpenAI-compatible APIs (OpenAI, DeepSeek, Perplexity, ...)
+
+Design rules:
+- the logger never raises: metering must never break the caller;
+- it stores tokens and metadata only (no prompt or completion text) in a local SQLite file;
+- prices live in one price list (a JSON file), applied when you build reports, not when you log.
+"""
+from __future__ import annotations
+
+import contextlib
+import datetime
+import json
+import os
+import sqlite3
+import sys
+import threading
+import time
+import urllib.parse
+import urllib.request
+import uuid
+from pathlib import Path
+
+__version__ = "0.1.0"
+__all__ = ["connect", "db_path", "log_anthropic", "log_bedrock", "log_cohere", "log_deepseek", "log_gemini", "log_grok",
+           "log_mistral", "log_ollama", "log_openai", "log_perplexity", "log_qwen", "log_response", "log_usage", "wrap"]
+
+_LOCK = threading.Lock()
+
+_DDL = """
+CREATE TABLE IF NOT EXISTS usage(
+  request_id TEXT PRIMARY KEY,
+  log_time TEXT NOT NULL,
+  slug TEXT NOT NULL,
+  provider TEXT,
+  model TEXT,
+  input_tokens INTEGER DEFAULT 0,
+  output_tokens INTEGER DEFAULT 0,
+  cache_creation_tokens INTEGER DEFAULT 0,
+  cache_read_tokens INTEGER DEFAULT 0,
+  workspace TEXT,
+  source TEXT,
+  synced INTEGER DEFAULT 0,
+  sync_error TEXT,
+  created_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_usage_synced ON usage(synced);
+CREATE INDEX IF NOT EXISTS ix_usage_time ON usage(log_time);
+"""
+FIELDS = ("request_id", "log_time", "slug", "provider", "model", "input_tokens", "output_tokens",
+          "cache_creation_tokens", "cache_read_tokens", "workspace", "source", "created_at")
+
+
+def db_path() -> str:
+    """SQLite file: $GIUGGIAI_METER_DB, otherwise ~/.local/share/giuggiai-meter/usage.db."""
+    return os.environ.get("GIUGGIAI_METER_DB") or str(Path.home() / ".local/share/giuggiai-meter/usage.db")
+
+
+def connect(path: str | None = None) -> sqlite3.Connection:
+    """Open (and create if needed) the usage database. The file is made readable by its owner only."""
+    p = path or db_path()
+    os.makedirs(os.path.dirname(os.path.abspath(p)), mode=0o700, exist_ok=True)
+    # create the database, -wal and -shm files as owner-only before SQLite opens them (no process-wide umask change)
+    for f in (p, p + "-wal", p + "-shm"):
+        try:
+            os.close(os.open(f, os.O_CREAT | os.O_WRONLY, 0o600))
+        except OSError:
+            pass
+    c = sqlite3.connect(p, timeout=10)
+    c.execute("PRAGMA journal_mode=WAL;")
+    c.executescript(_DDL)
+    for f in (p, p + "-wal", p + "-shm"):
+        try:
+            os.chmod(f, 0o600)
+        except OSError:
+            pass
+    return c
+
+
+def _norm_provider(p):
+    from .providers import normalize
+    return normalize(p)
+
+
+def _now() -> str:
+    return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _warn(msg: str) -> None:
+    """Write a diagnostic line to stderr. Never raises (stderr may be None under pythonw or some daemons)."""
+    with contextlib.suppress(Exception):
+        sys.stderr.write(msg if msg.endswith("\n") else msg + "\n")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Never follow redirects: the ingest token must not travel to another URL."""
+
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+_HTTP_PAUSE_S = 60  # after a failure the ingest is skipped for this long (rows go to local storage)
+_http_down_until = 0.0
+
+
+def _emit_http(row: dict) -> bool:
+    global _http_down_until
+    url, token = os.environ.get("GIUGGIAI_METER_URL"), os.environ.get("GIUGGIAI_METER_TOKEN")
+    if not (url and token):
+        return False
+    if not url.lower().startswith(("http://", "https://")):
+        _warn("[giuggiai_meter] GIUGGIAI_METER_URL must be http(s); falling back to local storage")
+        return False
+    if time.monotonic() < _http_down_until:
+        return False
+    host = (urllib.parse.urlsplit(url).hostname or "").lower()
+    if url.lower().startswith("http://") and host not in ("localhost", "127.0.0.1", "::1"):
+        _warn("[giuggiai_meter] warning: the ingest token is sent over plain http to a remote host; use https")
+    try:
+        req = urllib.request.Request(url, data=json.dumps(row).encode(), method="POST",
+                                     headers={"Content-Type": "application/json", "X-Meter-Token": token})
+        with _OPENER.open(req, timeout=2) as r:
+            r.read()
+        return True
+    except Exception as e:  # noqa: BLE001 - never break the caller
+        _http_down_until = time.monotonic() + _HTTP_PAUSE_S
+        _warn(f"[giuggiai_meter] HTTP ingest failed ({type(e).__name__}); local storage for the next {_HTTP_PAUSE_S} s")
+        return False
+
+
+def insert_row(row: dict, path: str | None = None) -> None:
+    """Insert a usage row (idempotent on request_id)."""
+    with _LOCK, contextlib.closing(connect(path)) as c, c:
+        c.execute(f"INSERT OR IGNORE INTO usage({','.join(FIELDS)},synced) VALUES({','.join('?' * len(FIELDS))},0)",
+                  [row.get(k) for k in FIELDS])
+
+
+def log_usage(slug, provider=None, model=None, input_tokens=0, output_tokens=0, cache_creation_tokens=0,
+              cache_read_tokens=0, request_id=None, workspace=None, source=None, log_time=None):
+    """Record one model call. Idempotent on request_id. Never raises: returns the request_id or None."""
+    try:
+        row = {
+            "request_id": request_id or f"gm-{uuid.uuid4().hex}",
+            "log_time": log_time or _now(),
+            "slug": str(slug),
+            "provider": _norm_provider(provider),
+            "model": model,
+            "input_tokens": int(input_tokens or 0),
+            "output_tokens": int(output_tokens or 0),
+            "cache_creation_tokens": int(cache_creation_tokens or 0),
+            "cache_read_tokens": int(cache_read_tokens or 0),
+            "workspace": workspace,
+            "source": source or os.environ.get("GIUGGIAI_METER_SOURCE"),  # no hostname by default (privacy)
+            "created_at": _now(),
+        }
+        if _emit_http(row):  # remote ingest first when configured (containers, other hosts)
+            return row["request_id"]
+        insert_row(row)
+        return row["request_id"]
+    except Exception as e:  # noqa: BLE001 - never break the caller
+        _warn(f"[giuggiai_meter] log_usage error: {e}\n")
+        return None
+
+
+def _g(obj, *names, default=0):
+    for n in names:
+        v = getattr(obj, n, None)
+        if v is None and isinstance(obj, dict):
+            v = obj.get(n)
+        if v is not None:
+            return v
+    return default
+
+
+def _rid(response):
+    rid = getattr(response, "id", None) or (response.get("id") if isinstance(response, dict) else None)
+    return "gm-" + (str(rid) if rid else uuid.uuid4().hex)
+
+
+def log_anthropic(slug, response, model=None, workspace=None):
+    """Read `usage` from an Anthropic Messages response and record it. Never raises."""
+    try:
+        u = _g(response, "usage", default={}) or {}
+        return log_usage(slug, provider="Anthropic", model=model or _g(response, "model", default=None),
+                         input_tokens=_g(u, "input_tokens"), output_tokens=_g(u, "output_tokens"),
+                         cache_creation_tokens=_g(u, "cache_creation_input_tokens"),
+                         cache_read_tokens=_g(u, "cache_read_input_tokens"), request_id=_rid(response),
+                         workspace=workspace)
+    except Exception as e:  # noqa: BLE001 - never break the caller
+        _warn(f"[giuggiai_meter] log_anthropic error: {e}\n")
+        return None
+
+
+def log_openai(slug, response, provider="OpenAI", model=None, workspace=None):
+    """Read `usage` from an OpenAI-compatible response (OpenAI, DeepSeek, Perplexity, ...) and record it. Never raises.
+    Works with Chat Completions (prompt/completion tokens) and the Responses API (input/output tokens)."""
+    try:
+        u = _g(response, "usage", default={}) or {}
+        details = _g(u, "prompt_tokens_details", "input_tokens_details", default={}) or {}
+        cached = _g(details, "cached_tokens", default=0) or _g(u, "prompt_cache_hit_tokens", default=0)
+        return log_usage(slug, provider=provider, model=model or _g(response, "model", default=None),
+                         # convention: input_tokens = uncached input (OpenAI-style totals include the cached part)
+                         input_tokens=max(0, int(_g(u, "prompt_tokens", "input_tokens") or 0) - int(cached or 0)),
+                         output_tokens=_g(u, "completion_tokens", "output_tokens"),
+                         cache_read_tokens=cached, request_id=_rid(response), workspace=workspace)
+    except Exception as e:  # noqa: BLE001 - never break the caller
+        _warn(f"[giuggiai_meter] log_openai error: {e}\n")
+        return None
+
+
+def log_deepseek(slug, response, model=None, workspace=None):
+    return log_openai(slug, response, provider="DeepSeek", model=model, workspace=workspace)
+
+
+def log_perplexity(slug, response, model=None, workspace=None):
+    return log_openai(slug, response, provider="Perplexity", model=model, workspace=workspace)
+
+
+def log_response(project, response, provider=None, model=None, workspace=None, fallback_model=None):
+    """Record any supported LLM response, SDK object or raw JSON dict, recognised by its shape. Never raises.
+
+    Shapes: OpenAI Chat Completions and every OpenAI-compatible API (prompt/completion tokens), OpenAI Responses API,
+    Anthropic Messages, Google Gemini (usage_metadata, also camelCase JSON), Cohere (billed_units), Amazon Bedrock
+    Converse (inputTokens/outputTokens), Ollama (prompt_eval_count/eval_count), Alibaba DashScope native.
+    `provider`: who bills the call; when omitted it comes from the shape or the model id (see providers.py).
+    `model` overrides the model in the response; `fallback_model` is used only when the response names none.
+    Returns the request_id, or None when nothing was recorded (no usage in the response, or an error)."""
+    try:
+        from ._usage import extract, resolve_provider
+
+        u = extract(response)
+        if u is None:
+            _warn("[giuggiai_meter] log_response: no token usage found in the response, nothing recorded\n")
+            return None
+        mdl = model or u["model"] or fallback_model
+        rid = "gm-" + (str(u["id"]) if u["id"] else uuid.uuid4().hex)
+        return log_usage(project, provider=resolve_provider(provider, mdl, u["shape"]), model=mdl,
+                         input_tokens=u["input_tokens"], output_tokens=u["output_tokens"],
+                         cache_creation_tokens=u["cache_creation_tokens"], cache_read_tokens=u["cache_read_tokens"],
+                         request_id=rid, workspace=workspace)
+    except Exception as e:  # noqa: BLE001 - never break the caller
+        _warn(f"[giuggiai_meter] log_response error: {e}\n")
+        return None
+
+
+def log_gemini(project, response, model=None, workspace=None):
+    """Google Gemini (google-genai / google-generativeai objects, or REST JSON)."""
+    return log_response(project, response, provider="Google", model=model, workspace=workspace)
+
+
+def log_grok(project, response, model=None, workspace=None):
+    """xAI Grok (OpenAI-compatible API)."""
+    return log_response(project, response, provider="xAI", model=model, workspace=workspace)
+
+
+def log_qwen(project, response, model=None, workspace=None):
+    """Alibaba Qwen: DashScope native or OpenAI-compatible mode."""
+    return log_response(project, response, provider="Alibaba Qwen", model=model, workspace=workspace)
+
+
+def log_mistral(project, response, model=None, workspace=None):
+    """Mistral (mistralai SDK `chat.complete`, or OpenAI-compatible JSON)."""
+    return log_response(project, response, provider="Mistral", model=model, workspace=workspace)
+
+
+def log_cohere(project, response, model=None, workspace=None):
+    """Cohere chat (v1 meta.billed_units or v2 usage.billed_units)."""
+    return log_response(project, response, provider="Cohere", model=model, workspace=workspace)
+
+
+def log_bedrock(project, response, model=None, workspace=None):
+    """Amazon Bedrock Converse API (boto3 `converse`); pass model= (the Converse response does not name it)."""
+    return log_response(project, response, provider="AWS Bedrock", model=model, workspace=workspace)
+
+
+def log_ollama(project, response, model=None, workspace=None):
+    """Ollama native API (`chat` / `generate`)."""
+    return log_response(project, response, provider="Ollama", model=model, workspace=workspace)
+
+
+from ._wrap import wrap  # imported last: it needs the log_* functions above