aiuse 3.2.2__tar.gz → 3.2.4__tar.gz

{aiuse-3.2.2/src/aiuse.egg-info → aiuse-3.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiuse
-Version: 3.2.2
+Version: 3.2.4
 Summary: Aggregate AI subscription/API usage and flag use-it-or-lose-it allotments
 Author: djbclark
 License-Expression: MIT
@@ -321,6 +321,9 @@ aiuse serve                # loopback HTTP API for agents
 aiuse watch                # full-screen board (q/esc quit; default 10m)
 aiuse watch -i 2m          # faster refresh
 aiuse watch --once         # one frame on stdout (scripts / tmux)
+aiuse attribute            # what spent the quota: points burned beside tokens per client
+aiuse attribute --since 7d --provider clinepass --intervals
+aiuse sample               # scheduled entry point: samples faster while quota is moving
 
 # Faster / partial
 aiuse --providers copilot,grok,codex   # query these separately
@@ -514,6 +517,7 @@ Lapsed subscriptions: `analysis.lapsed_accounts` maps `"provider/account"` to a
 
 ## Further documentation
 
+- [`docs/attribution.md`](docs/attribution.md) — what spent the quota: token ledgers, adaptive sampling (`aiuse sample`), `aiuse attribute`.
 - [`packaging/install-deps.sh`](packaging/install-deps.sh) — install the optional data-source tools.
 - [`docs/json-contract.md`](docs/json-contract.md) — stable JSON fields and exit codes.
 - [`docs/provider-identity.md`](docs/provider-identity.md) — canonical provider id vs config key, and window identity across collectors.

{aiuse-3.2.2 → aiuse-3.2.4}/README.md

@@ -280,6 +280,9 @@ aiuse serve                # loopback HTTP API for agents
 aiuse watch                # full-screen board (q/esc quit; default 10m)
 aiuse watch -i 2m          # faster refresh
 aiuse watch --once         # one frame on stdout (scripts / tmux)
+aiuse attribute            # what spent the quota: points burned beside tokens per client
+aiuse attribute --since 7d --provider clinepass --intervals
+aiuse sample               # scheduled entry point: samples faster while quota is moving
 
 # Faster / partial
 aiuse --providers copilot,grok,codex   # query these separately
@@ -473,6 +476,7 @@ Lapsed subscriptions: `analysis.lapsed_accounts` maps `"provider/account"` to a
 
 ## Further documentation
 
+- [`docs/attribution.md`](docs/attribution.md) — what spent the quota: token ledgers, adaptive sampling (`aiuse sample`), `aiuse attribute`.
 - [`packaging/install-deps.sh`](packaging/install-deps.sh) — install the optional data-source tools.
 - [`docs/json-contract.md`](docs/json-contract.md) — stable JSON fields and exit codes.
 - [`docs/provider-identity.md`](docs/provider-identity.md) — canonical provider id vs config key, and window identity across collectors.

{aiuse-3.2.2 → aiuse-3.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aiuse"
-version = "3.2.2"
+version = "3.2.4"
 description = "Aggregate AI subscription/API usage and flag use-it-or-lose-it allotments"
 readme = "README.md"
 requires-python = ">=3.11"

{aiuse-3.2.2 → aiuse-3.2.4}/src/aiuse/__init__.py

@@ -1,3 +1,3 @@
 """Aggregate provider quotas and flag use-it-or-lose-it allotments."""
 
-__version__ = "3.2.2"
+__version__ = "3.2.4"

{aiuse-3.2.2 → aiuse-3.2.4}/src/aiuse/analysis/selfdescribe.py

@@ -306,10 +306,10 @@ def _reset_fragment(resets_at: Any) -> str:
     dt = parse_dt(resets_at)
     if dt is None:
         return ""
-    local = dt.astimezone()
-    if dt - utcnow() <= timedelta(hours=24):
-        return f", resets {local.strftime('%H:%M')}"
-    return f", resets {local.strftime('%m-%d %H:%M')}"
+    # Local 12-hour time, the same form the watch board uses.
+    from aiuse.report import format_clock
+
+    return f", resets {format_clock(dt, date=dt - utcnow() > timedelta(hours=24))}"
 
 
 def summary_line(pool: Mapping[str, Any]) -> str:

{aiuse-3.2.2 → aiuse-3.2.4}/src/aiuse/attribute.py

@@ -83,6 +83,21 @@ def _quota_series(samples: list[dict[str, Any]]) -> dict[tuple[str, str, str], d
                 provider = canonical_provider(str(account.get("provider") or ""))
                 accounts.setdefault(provider, set()).add(history.account_key(account["account"]))
 
+    # One source may omit a window's duration (CodexBar's Copilot row) that
+    # another reports; the label then says which window it is.
+    durations: dict[tuple[str, str], Any] = {}
+    for sample in samples:
+        for account in sample.get("accounts") or []:
+            if not isinstance(account, dict):
+                continue
+            provider = canonical_provider(str(account.get("provider") or ""))
+            for window in account.get("windows") or []:
+                if isinstance(window, dict):
+                    label = str(window.get("label") or "")
+                    minutes = effective_window_minutes(label, window.get("window_minutes"))
+                    if minutes is not None:
+                        durations.setdefault((provider, label), minutes)
+
     series: dict[tuple[str, str, str], dict[str, Any]] = {}
     for sample in samples:
         when = _time(sample, "collected_at")
@@ -103,6 +118,8 @@ def _quota_series(samples: list[dict[str, Any]]) -> dict[tuple[str, str, str], d
                     continue
                 label = str(window.get("label") or "")
                 minutes = effective_window_minutes(label, window.get("window_minutes"))
+                if minutes is None:
+                    minutes = durations.get((provider, label))
                 key = (provider, owner, history.window_series_key(provider, label, minutes))
                 if key in seen and (seen[key] or not named):
                     continue

{aiuse-3.2.2 → aiuse-3.2.4}/src/aiuse/report.py

@@ -1517,11 +1517,27 @@ def render_clock_matrix(
                 estimated=cell.reset_estimated,
                 compact=layout.compact_deadline,
             )
-            colored = (
-                s.dim(f"{percent:>{w_pct}}")
-                if cell.inferred
-                else _cell_color(s, cell.used_percent)(f"{percent:>{w_pct}}")
-            )
+            # Split percent into used part (before "/") and left part (after "/" but before "l")
+            # Format: "44u/56l" or "44u/56l+" if folded
+            # Keep used part and slash in normal text, color only the left part
+            if "/" in percent:
+                used_part, rest = percent.split("/", 1)
+                # rest is like "56l" or "56l+"
+                left_part = rest.rstrip("l+")
+                mark = "+" if "+" in rest else ""
+                if cell.inferred:
+                    colored_used = s.dim(used_part)
+                    colored_left = s.dim(left_part)
+                else:
+                    colored_used = used_part  # Normal text for used part
+                    colored_left = _cell_color(s, cell.used_percent)(left_part)
+                colored = f"{colored_used}/{colored_left}l{mark}"
+            else:
+                colored = (
+                    s.dim(f"{percent:>{w_pct}}")
+                    if cell.inferred
+                    else _cell_color(s, cell.used_percent)(f"{percent:>{w_pct}}")
+                )
             if span is None:
                 tail.append(colored + (" " * (w_clock - w_pct)))
                 continue

{aiuse-3.2.2 → aiuse-3.2.4}/src/aiuse/sampler.py

@@ -38,6 +38,13 @@ TIERS = ("idle", "active", "burst")
 _SLACK_SECONDS = 15.0
 # Two samples closer than this say nothing reliable about a rate.
 _MIN_RATE_SECONDS = 60.0
+# A burst is judged against a reading at least this fraction of
+# ``active_interval`` old. Meters report whole points, so one tick between two
+# samples four minutes apart reads as 15 points an hour; over nine minutes or
+# more a single tick stays under the threshold and a real sprint does not.
+_BURST_BASELINE_FRACTION = 0.6
+# Readings kept per window for that baseline.
+_HISTORY_SECONDS = 7200.0
 
 
 def state_path() -> Path:
@@ -146,26 +153,54 @@ def advance_state(
     ``burst_pace_ratio`` times the pace that would exactly exhaust it — the
     second test keeps a 5-hour window's ordinary 20 points/hour from reading
     as an emergency while still catching a weekly window at 8.
+    The burst rate is measured from a reading at least 0.6 × ``active_interval``
+    old, never from the sample just before: see ``_BURST_BASELINE_FRACTION``.
     Rising is fast (one sample); falling takes ``cooldown_samples`` quiet ones.
     """
     raw_previous = state.get("last_values")
     previous: dict[str, Any] = raw_previous if isinstance(raw_previous, dict) else {}
     current = _series(snapshot)
+    raw_trail = state.get("history")
+    trail: dict[str, list[list[Any]]] = (
+        {k: list(v) for k, v in raw_trail.items() if isinstance(v, list)} if isinstance(raw_trail, dict) else {}
+    )
+    baseline_age = _BURST_BASELINE_FRACTION * settings["active_interval"]
     moved: list[str] = []
     hot: dict[str, dict[str, str]] = {}
     for key, cur in current.items():
+        readings = trail.setdefault(key, [])
         prev = previous.get(key)
         prev_at = _parse(prev.get("at")) if isinstance(prev, dict) else None
+        if isinstance(prev, dict) and cur["used"] < float(prev.get("used") or 0.0):
+            readings.clear()  # the window reset: older readings are another cycle
+        # Newest reading old enough to judge a rate against.
+        old_enough = [
+            (at, float(used))
+            for at, used in ((_parse(r[0]), r[1]) for r in readings if isinstance(r, list) and len(r) == 2)
+            if at is not None and (snapshot.collected_at - at).total_seconds() >= baseline_age
+        ]
+        readings.append([snapshot.collected_at.isoformat(), cur["used"]])
+        readings[:] = [
+            r
+            for r in readings
+            if (at := _parse(r[0])) is not None and (snapshot.collected_at - at).total_seconds() <= _HISTORY_SECONDS
+        ]
         if prev_at is None or not isinstance(prev, dict):
             continue
         seconds = (snapshot.collected_at - prev_at).total_seconds()
         delta = cur["used"] - float(prev.get("used") or 0.0)
-        if seconds < _MIN_RATE_SECONDS or delta < settings["min_move_percent"]:
-            continue  # too close to judge, flat, or a reset (usage fell)
-        per_hour = delta / (seconds / 3600.0)
+        if seconds >= _MIN_RATE_SECONDS and delta >= settings["min_move_percent"]:
+            moved.append(f"{cur['provider']} {cur['label']} +{delta:.1f} in {seconds / 60.0:.0f}m")
+        if not old_enough:
+            continue
+        base_at, base_used = old_enough[-1]
+        span = (snapshot.collected_at - base_at).total_seconds()
+        rise = cur["used"] - base_used
+        if rise < settings["min_move_percent"]:
+            continue
+        per_hour = rise / (span / 3600.0)
         minutes = cur.get("window_minutes")
-        pace = (delta / 100.0) / ((seconds / 60.0) / float(minutes)) if minutes else float("inf")
-        moved.append(f"{cur['provider']} {cur['label']} +{delta:.1f} ({per_hour:.1f}/h)")
+        pace = (rise / 100.0) / ((span / 60.0) / float(minutes)) if minutes else float("inf")
         if per_hour >= settings["burst_percent_per_hour"] and pace >= settings["burst_pace_ratio"]:
             hot[cur["provider"]] = {"provider": cur["provider"], "source": cur["source"]}
 
@@ -191,6 +226,7 @@ def advance_state(
             "moved": moved,
             # A partial sample only refreshes the windows it collected.
             "last_values": {**previous, **current} if partial else current,
+            "history": trail if partial else {k: v for k, v in trail.items() if k in current},
         }
     )
     if not partial:

{aiuse-3.2.2 → aiuse-3.2.4/src/aiuse.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiuse
-Version: 3.2.2
+Version: 3.2.4
 Summary: Aggregate AI subscription/API usage and flag use-it-or-lose-it allotments
 Author: djbclark
 License-Expression: MIT
@@ -321,6 +321,9 @@ aiuse serve                # loopback HTTP API for agents
 aiuse watch                # full-screen board (q/esc quit; default 10m)
 aiuse watch -i 2m          # faster refresh
 aiuse watch --once         # one frame on stdout (scripts / tmux)
+aiuse attribute            # what spent the quota: points burned beside tokens per client
+aiuse attribute --since 7d --provider clinepass --intervals
+aiuse sample               # scheduled entry point: samples faster while quota is moving
 
 # Faster / partial
 aiuse --providers copilot,grok,codex   # query these separately
@@ -514,6 +517,7 @@ Lapsed subscriptions: `analysis.lapsed_accounts` maps `"provider/account"` to a
 
 ## Further documentation
 
+- [`docs/attribution.md`](docs/attribution.md) — what spent the quota: token ledgers, adaptive sampling (`aiuse sample`), `aiuse attribute`.
 - [`packaging/install-deps.sh`](packaging/install-deps.sh) — install the optional data-source tools.
 - [`docs/json-contract.md`](docs/json-contract.md) — stable JSON fields and exit codes.
 - [`docs/provider-identity.md`](docs/provider-identity.md) — canonical provider id vs config key, and window identity across collectors.

{aiuse-3.2.2 → aiuse-3.2.4}/tests/test_attribution.py

@@ -182,15 +182,59 @@ def test_a_five_hour_window_at_its_ordinary_pace_is_active_not_burst():
 
 def test_tier_steps_down_one_level_only_after_the_cooldown():
     state = sampler.advance_state({}, _snapshot(T0, {"weekly": 4}), SETTINGS, partial=False)
-    state = sampler.advance_state(state, _snapshot(T0 + timedelta(minutes=15), {"weekly": 9}), SETTINGS, partial=False)
+    jump = T0 + timedelta(minutes=15)
+    state = sampler.advance_state(state, _snapshot(jump, {"weekly": 9}), SETTINGS, partial=False)
     assert state["tier"] == "burst"
-    when = T0 + timedelta(minutes=15)
-    for n in range(1, 3):
-        when += timedelta(minutes=3)
-        state = sampler.advance_state(state, _snapshot(when, {"weekly": 9}), SETTINGS, partial=True)
-        assert state["tier"] == "burst" and state["quiet_samples"] == n
-        assert state["hot"], "keeps watching the burning provider while still in burst"
-    state = sampler.advance_state(state, _snapshot(when + timedelta(minutes=3), {"weekly": 9}), SETTINGS, partial=True)
+    tiers = []
+    for n in range(1, 6):  # flat from here on, sampled every 3 minutes
+        flat = _snapshot(jump + timedelta(minutes=3 * n), {"weekly": 9})
+        state = sampler.advance_state(state, flat, SETTINGS, partial=True)
+        tiers.append((state["tier"], state["quiet_samples"], bool(state["hot"])))
+    # Still a burst while the baseline is the pre-jump reading; once the
+    # baseline is the jump itself the samples are quiet, and the third quiet
+    # one steps down a single tier.
+    assert tiers == [
+        ("burst", 0, True),
+        ("burst", 0, True),
+        ("burst", 1, True),
+        ("burst", 2, True),
+        ("active", 0, False),
+    ]
+
+
+def test_one_tick_between_close_samples_is_not_a_burst():
+    """Whole-point meters: +1 in 4 minutes reads as 15/h but is ordinary use."""
+    state = sampler.advance_state({}, _snapshot(T0, {"weekly": 54}), SETTINGS, partial=False)
+    close = _snapshot(T0 + timedelta(minutes=4), {"weekly": 55})
+    state = sampler.advance_state(state, close, SETTINGS, partial=False)
+    assert state["tier"] == "active" and state["hot"] == []
+    # One more tick 15 minutes later is 6.3/h over the 19-minute baseline: still not a burst.
+    later = _snapshot(T0 + timedelta(minutes=19), {"weekly": 56})
+    state = sampler.advance_state(state, later, SETTINGS, partial=False)
+    assert state["tier"] == "active" and state["hot"] == []
+
+
+def test_a_sustained_sprint_stays_in_burst_at_the_three_minute_cadence():
+    """14 points an hour arrives as whole-point ticks; the tier must not flap."""
+    state = sampler.advance_state({}, _snapshot(T0, {"weekly": 4}), SETTINGS, partial=False)
+    state = sampler.advance_state(
+        state, _snapshot(T0 + timedelta(minutes=15), {"weekly": 7.5}), SETTINGS, partial=False
+    )
+    assert state["tier"] == "burst"
+    for n in range(1, 11):
+        minutes = 15 + 3 * n
+        used = float(int(4 + 14 * minutes / 60))  # the meter shows whole points
+        state = sampler.advance_state(
+            state, _snapshot(T0 + timedelta(minutes=minutes), {"weekly": used}), SETTINGS, partial=True
+        )
+        assert state["tier"] == "burst", minutes
+
+
+def test_burst_baseline_does_not_reach_across_a_window_reset():
+    state = sampler.advance_state({}, _snapshot(T0, {"5-hour": 5}), SETTINGS, partial=False)
+    state = sampler.advance_state(state, _snapshot(T0 + timedelta(minutes=15), {"5-hour": 0}), SETTINGS, partial=False)
+    # 0 → 6 in 4 minutes after a reset; the only older reading is from the last cycle.
+    state = sampler.advance_state(state, _snapshot(T0 + timedelta(minutes=19), {"5-hour": 6}), SETTINGS, partial=False)
     assert state["tier"] == "active" and state["hot"] == []
 
 
@@ -375,6 +419,23 @@ def test_a_fall_after_the_reset_moment_is_a_reset():
     assert window["burned_points"] == 5 and window["resets"] == 1
 
 
+def test_a_window_whose_duration_one_source_omits_is_still_one_series():
+    """CodexBar reports Copilot's premium window without a duration; tokscale with one."""
+
+    def copilot(when, source, account, minutes, used):
+        window = QuotaWindow(label="GitHub Copilot premium requests", used_percent=used, window_minutes=minutes)
+        return Snapshot(
+            collected_at=when,
+            accounts=[AccountUsage(source=source, provider="copilot", account=account, windows=[window])],
+        )
+
+    history.save_snapshot(copilot(T0, "tokscale", None, 43800, 20), [])
+    history.save_snapshot(copilot(T0 + timedelta(hours=1), "codexbar", "me (Individual)", None, 22), [])
+    report = attribute.build_report({}, T0 - timedelta(minutes=1), T0 + timedelta(hours=2))
+    (window,) = report["providers"][0]["windows"]
+    assert window["burned_points"] == 2 and window["account"] == "me (Individual)"
+
+
 def test_report_intervals_line_each_step_up_with_who_spent(tmp_path):
     _seed(tmp_path)
     report = attribute.build_report({}, T0 - timedelta(minutes=1), T0 + timedelta(hours=1))

{aiuse-3.2.2 → aiuse-3.2.4}/tests/test_selfdescribe.py

@@ -445,3 +445,16 @@ def test_summary_line_names_the_binary_when_it_differs_from_the_provider_id():
     assert summary_line(cursor).startswith("cursor auto [cursor-agent]: Cursor Auto: ok")
     codex = {"provider": "codex", "pool_family": None, "cli_binary": "codex", "windows": [window]}
     assert summary_line(codex).startswith("codex: ")
+
+
+def test_reset_times_are_local_twelve_hour():
+    from datetime import timedelta
+
+    from aiuse.analysis.selfdescribe import _reset_fragment
+    from aiuse.models import utcnow
+    from aiuse.report import format_clock
+
+    soon, later = utcnow() + timedelta(hours=3), utcnow() + timedelta(days=4)
+    assert _reset_fragment(soon.isoformat()) == f", resets {format_clock(soon)}"
+    assert _reset_fragment(later.isoformat()) == f", resets {format_clock(later, date=True)}"
+    assert _reset_fragment(soon.isoformat()).endswith(("am", "pm"))