Turn a ~$5 AliExpress clock into a physical AI usage dashboard (Claude, Codex, multi-account). No firmware flashing.
"""Small, explicit usage windows. Missing measurements stay missing."""
import math
from datetime import datetime
def timestamp(value):
if isinstance(value, (int, float)) and not isinstance(value, bool):
return int(value) if math.isfinite(value) and value > 0 else None
if isinstance(value, str):
try:
parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
return int(parsed.timestamp()) if parsed.tzinfo else None
except ValueError:
pass
return None
class FormatChanged(ValueError):
"""A reply in a shape TokenTV does not read: the service changed its format (TokenTV needs an update)."""
def part(data, key):
"""`data[key]` when it is an object, {} when it is missing; FormatChanged when either is something else."""
if not isinstance(data, dict):
raise FormatChanged(key)
value = data.get(key)
if value is None:
return {}
if not isinstance(value, dict):
raise FormatChanged(key)
return value
def window(label, percent, reset=None, duration=None):
if isinstance(percent, bool) or not isinstance(percent, (int, float)):
return None
if not math.isfinite(percent) or percent < 0:
return None
if not isinstance(duration, int) or isinstance(duration, bool) or duration <= 0:
duration = None
return {"label": label, "used_percent": float(percent),
"resets_at": timestamp(reset), "duration_minutes": duration}
NAMED_DAYS = {"WEEK": 7, "MONTH": 30, "BUDGET": 30, "DAY": 1} # a window's length by its name, when it gives none
def window_minutes(value):
"""How long a window is, in minutes: as its service says, else by its name (5H, WEEK, DAY; a month or a budget as
30 days); None when neither says (CHAT, WINDOW)."""
minutes = value.get("duration_minutes")
if isinstance(minutes, int) and not isinstance(minutes, bool) and minutes > 0:
return minutes
label = str(value.get("label", "")).rstrip("2")
return 300 if label == "5H" else NAMED_DAYS[label] * 1440 if label in NAMED_DAYS else None
def five_hour(windows):
"""The 5-hour window among `windows`, or None."""
return min((w for w in windows if window_minutes(w) == 300), key=lambda w: str(w.get("label")), default=None)
def long_window(windows):
"""The long window among `windows` (a survival HUD's hunger): the week, else the longest other one but the 5-hour
one (a month, a budget), else any other; None when there is none. The same whatever order they come in."""
def rank(w):
minutes = window_minutes(w)
return minutes != 10080, minutes is None, -(minutes or 0), str(w.get("label"))
return min((w for w in windows if window_minutes(w) != 300), key=rank, default=None)
def today_window(windows):
"""The window today's use is read from: the longest of a known length (a week over a 5-hour one), None when no
window says how long it is."""
return min((w for w in windows if window_minutes(w)), key=lambda w: (-window_minutes(w), str(w.get("label"))),
default=None)
def even_day(minutes):
"""The used % an even day takes of a window `minutes` long: a seventh of a week, a thirtieth of a month, and of
a window of a day or less (5 hours) all of it, one a day; None for a window of unknown length."""
if not minutes:
return None
return 100 * 1440 / minutes if minutes >= 1440 else 100
def normalize_claude(data):
result = []
for key, label, duration in (("five_hour", "5H", 300), ("seven_day", "WEEK", 10080)):
value = part(data, key)
item = window(label, value.get("utilization"), value.get("resets_at"), duration)
if item:
result.append(item)
return result
def normalize_codex(data):
result = []
limits = part(data, "rateLimits")
for key in ("primary", "secondary"):
value = part(limits, key)
duration = value.get("windowDurationMins")
if not isinstance(duration, int) or isinstance(duration, bool) or duration <= 0:
duration = None
label = {300: "5H", 10080: "WEEK"}.get(duration, "WINDOW")
item = window(label, value.get("usedPercent"), value.get("resetsAt"), duration)
if item:
result.append(item)
return result
def reset_credits(data):
"""Codex's saved limit resets: {'count', 'expires_at'} with the soonest expiry of those still
available, or None when the reply has no such record."""
record = data.get("rateLimitResetCredits") if isinstance(data, dict) else None
count = record.get("availableCount") if isinstance(record, dict) else None
if not isinstance(count, int) or isinstance(count, bool) or count < 0:
return None
expiry = [timestamp(item.get("expiresAt")) for item in record.get("credits") or []
if isinstance(item, dict) and str(item.get("status", "")).lower() == "available"]
expiry = [at for at in expiry if at]
return {"count": count, "expires_at": min(expiry) if expiry else None}
def normalize_codexbar(entry):
"""One provider entry of CodexBar's usage JSON (`codexbar usage --format json`, `serve` GET /usage).
Only the primary and secondary slots: tertiary and extra windows are model-scoped and would
overwrite the weekly reading if they shared its label."""
result, labels = [], []
usage = part(entry, "usage")
# Copilot's slots carry no length: the primary is the monthly premium-request allowance, the secondary chat.
unnamed = {"primary": "MONTH", "secondary": "CHAT"} if entry.get("provider") == "copilot" else {}
for key in ("primary", "secondary"):
value = part(usage, key)
if not value:
continue
duration = value.get("windowMinutes")
if not isinstance(duration, int) or isinstance(duration, bool) or duration <= 0:
duration = None
label = {300: "5H", 1440: "DAY", 10080: "WEEK"}.get(duration) or unnamed.get(key, "WINDOW")
# Readings are compared window by window, so a window keeps one name: an unnamed second window is always
# WINDOW2, and a second window as long as the first gets a 2.
if label in labels or (key == "secondary" and label == "WINDOW"):
label += "2"
labels.append(label)
item = window(label, value.get("usedPercent"), value.get("resetsAt"), duration)
if item:
result.append(item)
return result
def normalize_grok(data):
config = part(data, "config")
percent = config.get("creditUsagePercent")
cycle = part(config, "currentPeriod")
reset = cycle.get("end") or config.get("billingPeriodEnd")
item = window("BUDGET", percent, reset)
if item:
return [item]
# CLI credits are a billing budget, not a fabricated web-message quota.
limit = part(data, "monthlyLimit").get("val")
used = part(part(data, "usage"), "includedUsed").get("val")
if isinstance(limit, (int, float)) and limit > 0 and isinstance(used, (int, float)):
item = window("BUDGET", used / limit * 100, part(data, "billingCycle").get("billingPeriodEnd"))
if item:
return [item]
return []