Skip to content

flurdy/agent-skills / skills/pi-spend

pi-spend

Verified

Read-only estimate of Pi model cost by provider and model for today, this week, this month, and all recorded history, separating metered credit usage from flat-rate subscription usage.

FileKindSize
SKILL.mdskill md6.1 KB
scripts/pi_spend.pyexecutablescript21.2 KB
tests/test_pi_spend.pyscript26.4 KB

scripts/pi_spend.py

View on GitHub
#!/usr/bin/env python3
"""Report Pi model cost estimates by period, grouped by provider and model.

Reads Pi session transcripts only. Cost values are Pi's own catalog estimates
recorded per assistant response, not provider invoices.
"""
from __future__ import annotations

import argparse
import json
import os
import sys
from collections import defaultdict
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from pathlib import Path
from zoneinfo import TZPATH, ZoneInfo, ZoneInfoNotFoundError

SCHEMA_VERSION = 2
BILLING_POLICY_SCHEMA_VERSION = 1
DEFAULT_SESSIONS_DIR = "~/.pi/agent/sessions"
DEFAULT_BILLING_POLICY = "~/.pi/agent/pi-spend-billing-policy.json"
PERIODS = ("today", "week", "month", "all")

METERED = "metered"
SUBSCRIPTION = "subscription"
UNKNOWN = "unknown"
EFFECTIVE_POLICY = "effective-dated-policy"
LEGACY_POLICY = "legacy-current-router-policy"
UNKNOWN_POLICY = "unknown"
MAX_POLICY_DIAGNOSTICS = 20


@dataclass(frozen=True)
class BillingInterval:
    effective_from: datetime
    effective_until: datetime | None
    billing: str


@dataclass(frozen=True)
class BillingPolicy:
    source: str
    status: str
    diagnostics: tuple[str, ...]
    models: dict[str, tuple[BillingInterval, ...]]

    def classify(self, provider, model, when):
        for interval in self.models.get(f"{provider}/{model}", ()):
            if when >= interval.effective_from and (
                interval.effective_until is None or when < interval.effective_until
            ):
                return interval.billing, self.source
        return UNKNOWN, UNKNOWN_POLICY


def policy_diagnostic(diagnostics, code):
    if code not in diagnostics and len(diagnostics) < MAX_POLICY_DIAGNOSTICS:
        diagnostics.append(code)


def parse_utc_timestamp(value):
    if not isinstance(value, str):
        return None
    try:
        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
    except ValueError:
        return None
    if parsed.tzinfo is None or parsed.utcoffset() != timedelta(0):
        return None
    return parsed.astimezone(timezone.utc)


def exact_model_key(value):
    return (
        isinstance(value, str)
        and "/" in value
        and all(part and not any(character.isspace() for character in part)
                for part in value.split("/", 1))
    )


def missing_policy(source, code):
    return BillingPolicy(source, "missing", (code,), {})


def reject_json_constant(value):
    raise ValueError(f"invalid JSON constant: {value}")


def strict_json_object(pairs):
    result = {}
    for key, value in pairs:
        if key in result:
            raise ValueError(f"duplicate JSON key: {key}")
        result[key] = value
    return result


def read_json_file(path):
    with open(path, encoding="utf-8") as handle:
        return json.load(
            handle,
            object_pairs_hook=strict_json_object,
            parse_constant=reject_json_constant,
        )


def load_billing_policy(path):
    expanded = os.path.expanduser(path)
    try:
        payload = read_json_file(expanded)
    except FileNotFoundError:
        return missing_policy(EFFECTIVE_POLICY, "billing-policy-missing")
    except (OSError, ValueError):
        return BillingPolicy(EFFECTIVE_POLICY, "invalid", ("billing-policy-invalid",), {})
    return parse_billing_policy(payload)


def parse_billing_policy(payload):
    """Validate an in-memory policy with the same rules as the telemetry reader."""
    if (
        not isinstance(payload, dict)
        or type(payload.get("schemaVersion")) is not int
        or payload["schemaVersion"] != BILLING_POLICY_SCHEMA_VERSION
    ):
        return BillingPolicy(EFFECTIVE_POLICY, "invalid", ("billing-policy-invalid",), {})
    configured_models = payload.get("models")
    if not isinstance(configured_models, dict):
        return BillingPolicy(EFFECTIVE_POLICY, "invalid", ("billing-policy-invalid",), {})

    diagnostics = []
    models = {}
    for key, entries in configured_models.items():
        if not exact_model_key(key) or not isinstance(entries, list) or not entries:
            policy_diagnostic(diagnostics, "invalid-model-policy")
            continue
        intervals = []
        invalid = False
        for entry in entries:
            if (
                not isinstance(entry, dict)
                or not {"effectiveFrom", "effectiveUntil", "billing"}.issubset(entry)
                or not isinstance(entry.get("billing"), str)
                or entry["billing"] not in {METERED, SUBSCRIPTION}
            ):
                invalid = True
                break
            effective_from = parse_utc_timestamp(entry.get("effectiveFrom"))
            effective_until = (
                None if entry.get("effectiveUntil") is None
                else parse_utc_timestamp(entry.get("effectiveUntil"))
            )
            if effective_from is None or (
                entry.get("effectiveUntil") is not None and effective_until is None
            ) or (effective_until is not None and effective_until <= effective_from):
                invalid = True
                break
            intervals.append(BillingInterval(
                effective_from, effective_until, entry["billing"]
            ))
        if invalid:
            policy_diagnostic(diagnostics, "invalid-interval")
            continue
        intervals.sort(key=lambda interval: interval.effective_from)
        overlaps = any(
            previous.effective_until is None
            or current.effective_from < previous.effective_until
            for previous, current in zip(intervals, intervals[1:], strict=False)
        )
        if overlaps:
            policy_diagnostic(diagnostics, "overlapping-intervals")
            continue
        models[key] = tuple(intervals)
    return BillingPolicy(
        EFFECTIVE_POLICY,
        "partial" if diagnostics else "complete",
        tuple(diagnostics),
        models,
    )


def load_legacy_router_policy(path):
    expanded = os.path.expanduser(path)
    try:
        payload = read_json_file(expanded)
    except FileNotFoundError:
        return missing_policy(LEGACY_POLICY, "legacy-router-policy-missing")
    except (OSError, ValueError):
        return BillingPolicy(LEGACY_POLICY, "invalid", ("legacy-router-policy-invalid",), {})
    configured = payload.get("modelPolicies") if isinstance(payload, dict) else None
    if not isinstance(configured, dict):
        return BillingPolicy(LEGACY_POLICY, "invalid", ("legacy-router-policy-invalid",), {})
    diagnostics = []
    models = {}
    beginning = datetime.min.replace(tzinfo=timezone.utc)
    for key, policy in configured.items():
        if not exact_model_key(key) or not isinstance(policy, dict) or not isinstance(policy.get("metered"), bool):
            policy_diagnostic(diagnostics, "invalid-legacy-model-policy")
            continue
        billing = METERED if policy["metered"] else SUBSCRIPTION
        models[key] = (BillingInterval(beginning, None, billing),)
    return BillingPolicy(
        LEGACY_POLICY,
        "partial" if diagnostics else "complete",
        tuple(diagnostics),
        models,
    )


class Row:
    __slots__ = ("provider", "model", "billing", "billing_source", "requests",
                 "input", "cache_read", "cache_write", "output", "reasoning",
                 "cost", "cost_missing")

    def __init__(self, provider, model, billing, billing_source):
        self.provider = provider
        self.model = model
        self.billing = billing
        self.billing_source = billing_source
        self.requests = 0
        self.input = 0
        self.cache_read = 0
        self.cache_write = 0
        self.output = 0
        self.reasoning = 0
        self.cost = 0.0
        self.cost_missing = 0

    @property
    def key(self):
        return f"{self.provider}/{self.model}"

    def add(self, usage, cost):
        self.requests += 1
        self.input += usage.get("input") or 0
        self.cache_read += usage.get("cacheRead") or 0
        self.cache_write += usage.get("cacheWrite") or 0
        self.output += usage.get("output") or 0
        self.reasoning += usage.get("reasoning") or 0
        if cost is None:
            self.cost_missing += 1
        else:
            self.cost += cost

    def as_dict(self):
        return {
            "provider": self.provider,
            "model": self.model,
            "billing": self.billing,
            "billingSource": self.billing_source,
            "requests": self.requests,
            "input": self.input,
            "cacheRead": self.cache_read,
            "cacheWrite": self.cache_write,
            "output": self.output,
            "reasoning": self.reasoning,
            "estimatedCost": round(self.cost, 6),
            "responsesMissingCost": self.cost_missing,
        }


def local_timezone(
    environment=None,
    localtime_path="/etc/localtime",
    timezone_path="/etc/timezone",
    zoneinfo_paths=TZPATH,
):
    environment = os.environ if environment is None else environment
    candidates = []
    configured = environment.get("TZ")
    if configured:
        candidates.append(configured.removeprefix(":"))
    try:
        configured_file = Path(timezone_path).read_text(encoding="utf-8").strip()
        if configured_file:
            candidates.append(configured_file)
    except OSError:
        pass

    resolved_localtime = None
    try:
        resolved_localtime = Path(localtime_path).resolve(strict=True)
    except OSError:
        pass
    if resolved_localtime is not None:
        for root_value in zoneinfo_paths:
            try:
                relative = resolved_localtime.relative_to(Path(root_value).resolve())
                candidates.append(relative.as_posix())
                break
            except (OSError, ValueError):
                continue
    for candidate in candidates:
        try:
            return ZoneInfo(candidate)
        except (ZoneInfoNotFoundError, ValueError):
            continue

    try:
        localtime = Path(localtime_path).read_bytes()
    except OSError:
        localtime = None
    if localtime is not None:
        for root_value in zoneinfo_paths:
            root = Path(root_value)
            try:
                files = sorted(path for path in root.rglob("*") if path.is_file())
            except OSError:
                continue
            for path in files[:5000]:
                try:
                    if path.stat().st_size != len(localtime) or path.read_bytes() != localtime:
                        continue
                    return ZoneInfo(path.relative_to(root).as_posix())
                except (OSError, ValueError, ZoneInfoNotFoundError):
                    continue
    return datetime.now().astimezone().tzinfo or timezone.utc


def period_starts(now):
    midnight = now.replace(hour=0, minute=0, second=0, microsecond=0)
    return {
        "today": midnight,
        "week": midnight - timedelta(days=midnight.weekday()),
        "month": midnight.replace(day=1),
        "all": datetime.fromtimestamp(0, tz=timezone.utc),
    }


def parse_timestamp(record, message, tzinfo):
    raw = record.get("timestamp") or message.get("timestamp")
    if isinstance(raw, (int, float)):
        return datetime.fromtimestamp(raw / 1000, tz=timezone.utc).astimezone(tzinfo)
    if isinstance(raw, str):
        try:
            parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
        except ValueError:
            return None
        if parsed.tzinfo is None or parsed.utcoffset() is None:
            return None
        return parsed.astimezone(tzinfo)
    return None


def iter_session_files(root):
    for dirpath, _, filenames in os.walk(root):
        for name in sorted(filenames):
            if name.endswith(".jsonl"):
                yield os.path.join(dirpath, name)


def collect(sessions_dir, policy, now, tzinfo):
    starts = period_starts(now)
    totals = {period: {} for period in PERIODS}
    stats = {
        "files": 0,
        "responses": 0,
        "duplicates": 0,
        "unparsable": 0,
        "undated": 0,
        "future": 0,
        "billingUnknownResponses": 0,
        "legacyProjectedResponses": 0,
    }
    seen = set()

    for path in iter_session_files(sessions_dir):
        stats["files"] += 1
        try:
            handle = open(path, encoding="utf-8", errors="replace")
        except OSError:
            continue
        with handle:
            for line in handle:
                if '"assistant"' not in line:
                    continue
                try:
                    record = json.loads(line)
                except ValueError:
                    stats["unparsable"] += 1
                    continue
                if not isinstance(record, dict):
                    stats["unparsable"] += 1
                    continue
                message = record.get("message")
                if not isinstance(message, dict) or message.get("role") != "assistant":
                    continue
                usage = message.get("usage")
                if not isinstance(usage, dict):
                    continue
                response_id = message.get("responseId")
                if response_id:
                    if response_id in seen:
                        stats["duplicates"] += 1
                        continue
                    seen.add(response_id)
                when = parse_timestamp(record, message, tzinfo)
                if when is None:
                    stats["undated"] += 1
                    continue
                if when > now:
                    stats["future"] += 1
                    continue

                provider_value = message.get("provider")
                model_value = message.get("model")
                valid_identity = (
                    isinstance(provider_value, str)
                    and bool(provider_value)
                    and isinstance(model_value, str)
                    and bool(model_value)
                )
                provider = provider_value if isinstance(provider_value, str) and provider_value else "unknown"
                model = model_value if isinstance(model_value, str) and model_value else "unknown"
                billing, billing_source = (
                    policy.classify(provider, model, when)
                    if valid_identity
                    else (UNKNOWN, UNKNOWN_POLICY)
                )
                cost_block = usage.get("cost")
                cost = cost_block.get("total") if isinstance(cost_block, dict) else None
                if not isinstance(cost, (int, float)):
                    cost = None
                stats["responses"] += 1
                if billing == UNKNOWN:
                    stats["billingUnknownResponses"] += 1
                if billing_source == LEGACY_POLICY:
                    stats["legacyProjectedResponses"] += 1

                key = (provider, model, billing, billing_source)
                for period, start in starts.items():
                    if when < start:
                        continue
                    bucket = totals[period]
                    if key not in bucket:
                        bucket[key] = Row(provider, model, billing, billing_source)
                    bucket[key].add(usage, cost)

    return totals, starts, stats


def summarise(rows):
    by_class = defaultdict(float)
    for row in rows:
        by_class[row.billing] += row.cost
    return by_class


def billing_policy_payload(policy):
    return {
        "source": policy.source,
        "status": policy.status,
        "diagnostics": list(policy.diagnostics),
    }


def render_text(totals, starts, stats, periods, metered_only, now, policy):
    out = []
    out.append(f"Pi model spend estimate  ·  generated {now:%Y-%m-%d %H:%M %Z}")
    out.append(
        f"Sources: {stats['files']} session files, {stats['responses']} responses"
        f" ({stats['duplicates']} duplicate, {stats['unparsable']} unparsable,"
        f" {stats['undated']} undated, {stats['future']} future)"
    )
    diagnostic = ",".join(policy.diagnostics) if policy.diagnostics else "none"
    out.append(
        f"Billing policy: {policy.source} ({policy.status}; diagnostics: {diagnostic})"
    )
    out.append(
        f"Classification: {stats['billingUnknownResponses']} unknown, "
        f"{stats['legacyProjectedResponses']} legacy current-policy projection"
    )

    for period in periods:
        rows = [row for row in totals[period].values()]
        if metered_only:
            rows = [row for row in rows if row.billing == METERED]
        label = "all recorded history" if period == "all" else f"since {starts[period]:%Y-%m-%d %H:%M %Z}"
        out.append("")
        out.append(f"== {period.upper()} ==  ({label})")
        if not rows:
            out.append("  no recorded responses")
            continue

        rows.sort(key=lambda r: (-r.cost, r.key, r.billing, r.billing_source))
        header = (
            f"{'provider/model':<38} {'bill':<12} {'policy':<28} {'reqs':>6}"
            f" {'input':>12} {'cacheRead':>13} {'output':>10} {'est USD':>9}"
        )
        out.append(header)
        out.append("-" * len(header))
        for row in rows:
            out.append(
                f"{row.key:<38} {row.billing:<12} {row.billing_source:<28}"
                f" {row.requests:>6} {row.input:>12,} {row.cache_read:>13,}"
                f" {row.output:>10,} {row.cost:>9.2f}"
            )
        by_class = summarise(rows)
        out.append("-" * len(header))
        out.append(
            f"{'TOTAL':<38} {'':<12} {'':<28} {'':>6} {'':>12} {'':>13}"
            f" {'':>10} {sum(by_class.values()):>9.2f}"
        )
        for billing in (METERED, SUBSCRIPTION, UNKNOWN):
            if billing in by_class:
                out.append(
                    f"{'  ' + billing:<38} {'':<12} {'':<28} {'':>6} {'':>12}"
                    f" {'':>13} {'':>10} {by_class[billing]:>9.2f}"
                )
        missing = sum(row.cost_missing for row in rows)
        if missing:
            out.append(f"  {missing} response(s) recorded no cost and are excluded from the estimate")

    out.append("")
    out.append("Estimates are Pi's own catalog pricing per response, not a provider invoice.")
    if policy.source == LEGACY_POLICY:
        out.append("LEGACY: classifications are current router-policy projections and may relabel history.")
    else:
        out.append("Billing class comes from the effective-dated local policy; uncovered responses remain unknown.")
    return "\n".join(out)


def render_json(totals, starts, stats, periods, metered_only, now, policy):
    payload = {
        "schemaVersion": SCHEMA_VERSION,
        "generatedAt": now.isoformat(),
        "timezone": str(now.tzname()),
        "source": "pi-sessions",
        "costAuthority": "pi-catalog-estimate",
        "billingPolicy": billing_policy_payload(policy),
        "stats": stats,
        "periods": {},
    }
    for period in periods:
        rows = list(totals[period].values())
        if metered_only:
            rows = [row for row in rows if row.billing == METERED]
        rows.sort(key=lambda r: (-r.cost, r.key, r.billing, r.billing_source))
        by_class = summarise(rows)
        payload["periods"][period] = {
            "start": None if period == "all" else starts[period].isoformat(),
            "end": now.isoformat(),
            "totalEstimatedCost": round(sum(by_class.values()), 6),
            "estimatedCostByBilling": {k: round(v, 6) for k, v in sorted(by_class.items())},
            "rows": [row.as_dict() for row in rows],
        }
    return json.dumps(payload, indent=2)


def build_parser():
    parser = argparse.ArgumentParser(description="Report Pi model spend estimates by period.")
    parser.add_argument("--period", choices=PERIODS, action="append",
                        help="Limit output to a period; repeatable. Defaults to all four.")
    parser.add_argument("--json", action="store_true", help="Emit normalized JSON instead of a table.")
    parser.add_argument("--metered-only", action="store_true",
                        help="Show only responses classified as metered.")
    parser.add_argument("--sessions-dir", default=DEFAULT_SESSIONS_DIR,
                        help=f"Pi sessions root (default: {DEFAULT_SESSIONS_DIR}).")
    billing_source = parser.add_mutually_exclusive_group()
    billing_source.add_argument(
        "--billing-policy",
        help=f"Effective-dated billing policy (default: {DEFAULT_BILLING_POLICY}).",
    )
    billing_source.add_argument(
        "--router-config",
        help="LEGACY: explicitly project current router modelPolicies across history.",
    )
    return parser


def main(argv=None):
    args = build_parser().parse_args(argv)
    sessions_dir = os.path.expanduser(args.sessions_dir)
    if not os.path.isdir(sessions_dir):
        print(f"ERROR: Pi sessions directory not found: {sessions_dir}", file=sys.stderr)
        return 2

    timezone_info = local_timezone()
    now = datetime.now(timezone_info)
    policy = (
        load_legacy_router_policy(args.router_config)
        if args.router_config
        else load_billing_policy(args.billing_policy or DEFAULT_BILLING_POLICY)
    )
    totals, starts, stats = collect(sessions_dir, policy, now, timezone_info)
    periods = tuple(dict.fromkeys(args.period)) if args.period else PERIODS

    renderer = render_json if args.json else render_text
    print(renderer(totals, starts, stats, periods, args.metered_only, now, policy))
    return 0


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall