copilot-session-usage 0.9.1__tar.gz → 0.9.3__tar.gz

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: copilot-session-usage
-Version: 0.9.1
+Version: 0.9.3
 Summary: Usage and cost analytics for GitHub Copilot and Copilot-CLI session logs
 Project-URL: Homepage, https://github.com/gsemet/copilot-session-usage
 Project-URL: Documentation, https://copilot-session-usage.readthedocs.io/en/stable/

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/docs/source/explanation/how-cost-estimation-works.md

@@ -126,6 +126,7 @@ Subagent names are extracted from the JSONL filename
 (`runSubagent-<Name>-functions.runSubagent:<id>.jsonl`) and from
 `child_session_ref` events in `main.jsonl`.
 
+(skill-attribution)=
 ## Skill attribution
 
 Skills are detected from four sources in the debug logs:
@@ -237,22 +238,25 @@ provider's use of `copilotUsageNanoAiu` (1 nanoAIU = 1e-11 USD):
   cumulative across resumes (the largest value from the last
   `session.shutdown` or `session.usage_checkpoint`).
 - Each `model_breakdown` row uses that model's `totalNanoAiu`. Without it, the
-  model's tokens are priced exactly: `inputTokens` includes cache reads and
-  cache writes, so fresh input is `inputTokens - cacheReadTokens -
-  cacheWriteTokens`, and only `cacheWriteTokens` are charged at the
-  cache-write rate. The pricing tier is chosen from the average request size,
-  not the session sum.
+  model's tokens are priced using the reported cache-write count:
+  `inputTokens` includes cache reads and cache writes, so fresh input is
+  `inputTokens - cacheReadTokens - cacheWriteTokens`, and only
+  `cacheWriteTokens` are charged at the cache-write rate. The pricing tier is
+  chosen from the average request size, not the session sum. This fallback
+  remains an estimate because individual request sizes and discounts are absent.
 - `subagents` lists the main agent and each subagent from
   `session.shutdown.agentMetrics`, with their own billed `totalNanoAiu`.
-- Per-model and per-agent metrics omit segments that ended without a
-  `session.shutdown` (a crash or kill before a resume). That remainder is
-  reported as `total.unattributed_usd`, with a diagnostic, so
-  breakdowns plus `unattributed_usd` always equal the total.
-
-Across 101 local CLI/App sessions, totals matched the billed `totalNanoAiu`
-exactly and breakdowns reconciled with it. Pricing tokens with the exact
-cache-write count reproduced per-model billed amounts for 89 of 96 models;
-the rest included long-context requests or discounts invisible in aggregates.
+- Per-model and per-agent metrics can omit segments that ended without a
+  `session.shutdown` (a crash or kill before a resume). A positive remainder
+  between session billing and attributed model costs is reported as
+  `total.unattributed_usd`, with a diagnostic. Displayed totals and breakdowns
+  are rounded to different precisions.
+
+A local investigation on 2026-10-07 found that billed totals and breakdowns
+reconciled across 101 CLI/App sessions. Pricing tokens with the reported
+cache-write count at the base tier reproduced per-model billed amounts for
+89 of 96 model entries. These are dated observations, not guarantees for future
+sessions; see the [recorded finding](https://github.com/gsemet/copilot-session-usage/blob/5142026b2ec4c46432c4ff037ebea37030f3b56f/knowledge/findings/2026.10.07-17.30-cli-billed-nanoaiu-and-cache-write.md).
 
 ### When usage is unavailable
 
@@ -264,6 +268,7 @@ has no `session.shutdown` event. In that case:
   fabricated zero.
 - If a `session.usage_checkpoint` exists, its cumulative `totalNanoAiu`
   provides `total.estimated_usd`, entirely reported as `unattributed_usd`.
+  Token totals and cache ratio remain unavailable.
 - `diagnostics` explains exactly what is unavailable and why.
 - Batch/aggregate operations exclude sessions with unavailable evidence from
   their sums (rather than counting them as zero) and report how many were

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/docs/source/how-to/analyze-specific-session.md

@@ -109,7 +109,7 @@ invocation. It assigns the whole request context, not just the skill text or usa
 caused by that skill. Automatically loaded skills, overlapping skills, and later
 unrelated work cannot be reliably separated; requests before any invocation are
 grouped under `unknown`. CLI/App per-skill tokens and costs remain unavailable.
-See [How cost estimation works](../explanation/how-cost-estimation-works.md).
+See [Skill attribution](../explanation/how-cost-estimation-works.md#skill-attribution).
 :::
 
 ```bash

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/docs/source/reference/pricing.md

@@ -189,21 +189,27 @@ matching pricing prefix. Aggregate-only CLI summaries cannot recover individual
 request context sizes; without a billed figure, their tier is chosen from the
 average request size.
 
+Pricing row order does not affect tier selection, including at the boundary.
+Supported thresholds are the current `≤`/`<=` and `>` comparisons, plus inclusive
+`≥`/`>=`, with integer token counts and optional `K` or `M` suffixes.
+Missing or `Not applicable` thresholds remain unbounded. Other syntax is rejected;
+range expressions and future multi-tier formats are not inferred.
+
 ## Copilot CLI/App limitations
 
-CLI/App costs use Copilot's billed `totalNanoAiu` (session, per model, per
-agent), so totals are dollar-accurate. The event log has only cumulative
-usage, so:
+When reported, Copilot CLI/App costs use `totalNanoAiu` for the session, each
+model, and each agent rather than token-based estimates. The event log has
+cumulative usage rather than per-request token counts:
 
 - **No per-skill cost.** There is no per-request usage to split by skill;
   `skills.breakdown` is empty. Detected skills and tool counts remain.
-- **Unattributed remainder.** Per-model and per-agent metrics omit session
+- **Unattributed remainder.** Per-model and per-agent metrics can omit session
   segments that ended without `session.shutdown` (crash or kill before a
   resume). That cost is in `total.unattributed_usd`, not in any breakdown.
-- **Active sessions** report only the latest checkpoint total, entirely
-  unattributed.
+- **Active sessions** report the latest checkpoint total when available,
+  entirely unattributed, with token totals remaining unavailable.
 - **Token fallback** (no billed figure) cannot see per-request long-context
-  tiers or discounts and is an estimate.
+  tiers or discounts and is an estimate. Reported costs are rounded.
 
 ## Custom pricing
 

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/src/copilot_session_usage/_internal/core.py

@@ -151,23 +151,22 @@ def _clean_model_display_name(name: str) -> str:
     return cleaned.strip()
 
 
-def _parse_threshold(threshold: str) -> int | None:
-    """Parse a threshold string from the YAML into a token count.
-
-    Examples:
-        "≤ 272K" → 272_000
-        "> 272K" → None  (unbounded / long-context tier)
-        "Not applicable" → None
-    """
-    if not threshold or threshold.lower() in ("not applicable", "n/a", ""):
-        return None
-    match = re.search(r"([0-9]+(?:\.[0-9]+)?)\s*([KM]?)", threshold)
-    if not match:
-        return None
-    value = float(match.group(1))
-    suffix = match.group(2).upper()
-    multiplier = {"K": 1_000, "M": 1_000_000}.get(suffix, 1)
-    return int(value * multiplier)
+def _parse_threshold(threshold: str | None) -> tuple[int, int | None]:
+    """Parse current pricing comparisons into inclusive integer-token bounds."""
+    if threshold is None:
+        return 0, None
+    if not isinstance(threshold, str):
+        raise ValueError(f"unsupported pricing threshold: {threshold!r}")
+    if threshold.strip().lower() in ("not applicable", "n/a", ""):
+        return 0, None
+    match = re.fullmatch(r"\s*(<=|≤|>=|≥|>)\s*([0-9]+)\s*([KM]?)\s*", threshold, re.IGNORECASE)
+    if match is None:
+        raise ValueError(f"unsupported pricing threshold: {threshold!r}")
+    operator, amount, suffix = match.groups()
+    tokens = int(amount) * {"K": 1_000, "M": 1_000_000}.get(suffix.upper(), 1)
+    if operator in ("<=", "≤"):
+        return 0, tokens
+    return tokens + (operator == ">"), None
 
 
 def _parse_price(price: str) -> float:
@@ -382,13 +381,15 @@ def _build_pricing_from_yaml(entries: list[dict], source: str) -> dict:
             continue
         name = _normalize_model_name(raw_name)
         display_name = _clean_model_display_name(raw_name)
+        lower, upper = _parse_threshold(entry.get("threshold", ""))
         tier = {
             "input_per_m": _parse_price(entry.get("input", "0")),
             "output_per_m": _parse_price(entry.get("output", "0")),
             "cache_per_m": _parse_price(entry.get("cached_input", "0")),
             "cache_write_per_m": _parse_price(entry.get("cache_write", "0")),
             "tier": entry.get("tier", "Default"),
-            "threshold_tokens": _parse_threshold(entry.get("threshold", "")),
+            "threshold_tokens": upper,
+            "min_threshold_tokens": lower,
             "provider": entry.get("provider", "unknown"),
             "display_name": display_name,
         }
@@ -759,14 +760,22 @@ def _get_model_rates(model: str, input_tok: int, pricing: dict[str, Any]) -> dic
     if tiers is None:
         tiers = models.get("default", [{}])
 
-    if len(tiers) == 1:
-        return tiers[0]  # type: ignore[no-any-return]
-
-    for tier in tiers:
-        threshold = tier.get("threshold_tokens")
-        if threshold is not None and input_tok <= threshold:
-            return tier  # type: ignore[no-any-return]
-    return tiers[-1]  # type: ignore[no-any-return]
+    matches = [
+        tier
+        for tier in tiers
+        if input_tok >= tier.get("min_threshold_tokens", 0)
+        and (tier.get("threshold_tokens") is None or input_tok <= tier["threshold_tokens"])
+    ]
+    if not matches:
+        raise ValueError(f"no pricing tier for {model} at {input_tok} input tokens")
+    return min(  # type: ignore[no-any-return]
+        matches,
+        key=lambda tier: (
+            tier.get("threshold_tokens") is None,
+            tier.get("threshold_tokens") or 0,
+            -tier.get("min_threshold_tokens", 0),
+        ),
+    )
 
 
 def model_uses_fallback_pricing(model: str, pricing: dict[str, Any]) -> bool:

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/src/copilot_session_usage/data/models-and-pricing.lock

@@ -1,7 +1,7 @@
 {
-  "_captured": "2026-10-08T09:01:09.111216+00:00",
+  "_captured": "2026-10-19T07:49:42.570898+00:00",
   "_source": "https://raw.githubusercontent.com/github/docs/main/data/tables/copilot/models-and-pricing.yml",
   "_yaml_path": "/home/runner/work/copilot-session-usage/copilot-session-usage/src/copilot_session_usage/data/models-and-pricing.yml",
-  "model_count": 45,
-  "checksum": "d1c7540b412c58b3"
+  "model_count": 46,
+  "checksum": "c03a304b103a3dd1"
 }

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/src/copilot_session_usage/data/models-and-pricing.yml

@@ -406,6 +406,19 @@
   cached_input: $0.075
   output: $3.75
 
+# Promotional pricing expires 2026-12-01. Google hasn't shared post-promo pricing yet.
+# When it does, update input, cached_input, and output below, then remove the
+# [^gemini-4-argon-promo] footnote here and in models-and-pricing.md.
+- model: 'Gemini 4 Argon[^gemini-4-argon-promo]'
+  provider: google
+  release_status: GA
+  category: Powerful
+  threshold: 'Not applicable'
+  tier: 'Default'
+  input: $2.00
+  cached_input: $0.10
+  output: $10.00
+
 # xAI
 - model: 'Grok 4.5'
   provider: xai

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/tests/test_core.py

@@ -304,6 +304,48 @@ def test_threshold_aware_pricing_exact_boundary():
     assert rates["input_per_m"] == 2.50
 
 
+@pytest.mark.parametrize("reverse", [False, True])
+@pytest.mark.parametrize(
+    ("upper", "lower", "boundary"),
+    [
+        ("≤ 272K", "> 272K", 272_000),
+        ("<= 272K", "> 272K", 272_000),
+        ("<= 271999", ">= 272K", 271_999),
+        ("≤ 271999", "≥ 272K", 271_999),
+    ],
+)
+def test_threshold_aware_pricing_is_order_independent(reverse, upper, lower, boundary):
+    text = core._read_data_file("models-and-pricing.yml")
+    assert text is not None
+    rows = [
+        row
+        for row in core._parse_pricing_entries(text, "test")
+        if core._normalize_model_name(row.get("model", "")) == "gpt-5.4"
+    ]
+    assert len(rows) == 2
+    rows = [{**rows[0], "threshold": upper}, {**rows[1], "threshold": lower}]
+    pricing = core._build_pricing_from_yaml(list(reversed(rows)) if reverse else rows, "test")
+    pricing["models"]["gpt-5.4"].reverse()
+    for tokens in [0, boundary - 1, boundary, boundary + 1, 500_000]:
+        expected = rows[0] if tokens <= boundary else rows[1]
+        assert core._get_model_rates("gpt-5.4", tokens, pricing)["tier"] == expected["tier"]
+        cached = tokens // 2
+        expected_cost = (
+            (tokens - cached) * core._parse_price(expected["input"])
+            + cached * core._parse_price(expected["cached_input"])
+            + 1000 * core._parse_price(expected["output"])
+        ) / 1e6
+        assert core.estimate_cost(tokens, 1000, cached, "gpt-5.4", pricing) == pytest.approx(
+            expected_cost
+        )
+
+
+def test_threshold_aware_pricing_does_not_ignore_lower_bound():
+    pricing = core._build_pricing_from_yaml([{"model": "Test", "threshold": ">= 100K"}], "test")
+    with pytest.raises(ValueError, match="no pricing tier"):
+        core._get_model_rates("test", 99_999, pricing)
+
+
 def test_estimate_cost_with_threshold():
     pricing = {
         "models": {

{copilot_session_usage-0.9.1 → copilot_session_usage-0.9.3}/tests/test_rendering.py

@@ -13,19 +13,53 @@ from copilot_session_usage._internal import core
 
 
 def test_parse_threshold_not_applicable():
-    assert core._parse_threshold("Not applicable") is None
-    assert core._parse_threshold("n/a") is None
-    assert core._parse_threshold("") is None
-    assert core._parse_threshold(None) is None
+    assert core._parse_threshold("Not applicable") == (0, None)
+    assert core._parse_threshold("n/a") == (0, None)
+    assert core._parse_threshold("") == (0, None)
+    assert core._parse_threshold(None) == (0, None)
 
 
 def test_parse_threshold_unbounded():
-    # "> 272K" is parsed as 272000 by the regex; the docstring is aspirational
-    assert core._parse_threshold("> 272K") == 272_000
+    assert core._parse_threshold("> 272K") == (272_001, None)
 
 
 def test_parse_threshold_no_match():
-    assert core._parse_threshold("abc") is None
+    with pytest.raises(ValueError, match="threshold"):
+        core._parse_threshold("abc")
+
+
+@pytest.mark.parametrize(
+    ("threshold", "expected"),
+    [
+        ("<= 100K", (0, 100_000)),
+        (">= 100K", (100_000, None)),
+        ("  > 100k  ", (100_001, None)),
+        ("≤ 100K", (0, 100_000)),
+        ("≥ 100K", (100_000, None)),
+        ("<= 1M", (0, 1_000_000)),
+    ],
+)
+def test_parse_threshold_conditions(threshold, expected):
+    assert core._parse_threshold(threshold) == expected
+
+
+@pytest.mark.parametrize(
+    "threshold",
+    [
+        "garbage 100K",
+        ">=",
+        "100K trailing",
+        "200K-100K",
+        "< 0",
+        "> 2 and < 3",
+        ">= 0.5M",
+        100_000,
+        True,
+    ],
+)
+def test_parse_threshold_invalid_conditions(threshold):
+    with pytest.raises(ValueError, match="threshold"):
+        core._parse_threshold(threshold)
 
 
 # ─── _parse_price edge cases ──────────────────────────────────────────────────