burnclock 0.1.0__py3-none-any.whl

burnclock-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: burnclock
+Version: 0.1.0
+Summary: Burnclock: see your AI budget runway at a glance — balances, burn, days-left. Estimates, not billing truth.
+Author: Jeremy Silbernagel
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: httpx>=0.27
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: tui
+Requires-Dist: textual>=0.80; extra == "tui"
+
+# Burnclock
+
+**How much AI budget you have left, and how long it lasts — in one glance.**
+
+Burnclock reads each AI provider's own balance/usage endpoint (or your local Hermes usage records),
+then computes what most consoles don't show you: **burn per day, days of paid runway left, and the date
+your monthly budget runs out** — per provider, in one table or one JSON envelope.
+
+> **Estimates, not billing truth.** Every dollar is computed locally from provider responses and usage
+> records. It is not a bill, not a guarantee, and not affiliated with any provider.
+
+Example output (synthesized, not a live account):
+
+```text
+┌────────────┬───────┬───────────┬──────────┬───────────────┐
+│ Provider   │ State │ Balance   │ Burn/day │ Runway (paid) │
+├────────────┼───────┼───────────┼──────────┼───────────────┤
+│ DeepSeek   │ OK    │ 20.23 USD │ 2.69     │ 6.0 d         │
+│ OpenRouter │ EMPTY │ -0.09 USD │ 8.08     │ —             │
+└────────────┴───────┴───────────┴──────────┴───────────────┘
+```
+
+## What it answers
+
+- **Do I need to top up today?** Balance + days-left at your current burn, per provider.
+- **Where is my money going?** Burn/day from your actual usage (Hermes `state.db`, deduped logs), not a guess.
+- **When does the month's budget run out?** Budget bars and a projected crossing date.
+- **Is this key dead or just empty?** `KEY_REJECTED` vs `EMPTY` vs `PERMISSION_DENIED` are distinct states.
+
+## Providers
+
+| Provider | Balance source | Verification |
+|---|---|---|
+| DeepSeek | `GET /user/balance` | live-verified |
+| OpenRouter | `GET /api/v1/key` + `/credits` (remaining = credits − usage) | live-verified |
+| Moonshot | `GET /v1/users/me/balance` | doc-unverified, disabled by default |
+| xAI | management API prepaid balance (needs `team_id`) | doc-unverified, disabled by default |
+| MiniMax | `account/query_balance` or `token_plan/remains` (region auto) | doc-unverified, disabled by default |
+| fal | `account/billing` (prepaid/postpaid discriminated) | doc-unverified, disabled by default |
+
+Providers without a balance API still get an honest row: `NO_API` (spend-only, e.g. priced usage records)
+or `NOT_QUERYABLE` (console-only). No state ever fabricates a number.
+
+## Install
+
+Not on PyPI yet — the first release is pending. From source:
+
+```sh
+git clone <repo-url> && cd burnclock
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/burnclock --version
+```
+
+Once released: `pipx install burnclock` or `uv tool install burnclock`.
+
+Requires Python ≥ 3.12. The `watch` TUI needs the optional extra: `pip install 'burnclock[tui]'`.
+
+## Use
+
+```sh
+burnclock                          # human status table
+burnclock status --json            # envelope v1 + script-safe exit codes
+burnclock forecast                 # paid runway, burn/day, budget crossing date
+burnclock dashboard                # every known provider (disabled rows included)
+burnclock budget show              # resolved monthly budgets
+burnclock budget set deepseek 50 --dry-run   # offline preview, never a surprise write
+burnclock watch                    # live TUI on a TTY; plain table when piped
+burnclock completion bash|zsh|fish # print a static shell completion script
+burnclock config show | path       # effective config / config file location
+```
+
+Config lives at `~/.config/burnclock/config.toml` on macOS/Linux and `%APPDATA%\burnclock\config.toml` on
+Windows (the pre-rename location is still read, with a one-time warning). Keys are **never** stored in config: a provider entry names an environment
+variable (e.g. `key_env = "DEEPSEEK_API_KEY"`); a secret-shaped value in config refuses to load.
+
+Exit codes on machine paths: `0` ok · `1` internal · `2` usage · `3` config · `4` auth
+(`KEY_REJECTED`/`PERMISSION_DENIED`) · `5` threshold crossed · `6` unreachable — worst wins, in the order
+`1 > 2 > 3 > 4 > 5 > 6 > 0`. Human views exit 0 whenever output was produced.
+
+`status --min <usd>` and `status --min-days <n>` turn it into an alert (exit 5) for cron and agents.
+
+On an interactive terminal only (never for `--json` or piped output), burnclock checks PyPI at most once a
+day and prints a one-line upgrade hint to stderr; set `BURNCLOCK_NO_UPGRADE_CHECK=1` to opt out.
+
+## States
+
+`OK · LOW · CRITICAL · EMPTY · KEY_REJECTED · PERMISSION_DENIED · NO_API · NOT_QUERYABLE · ERROR · UNREACHABLE`
+
+`KEY_REJECTED` distinguishes a dead/rotated key from a `$0` balance; `PERMISSION_DENIED` means the key is
+valid but under-scoped. `EMPTY` means unknown or zero — never "free".
+
+## Hermes skill
+
+The repo ships a Hermes skill (`hermes-skill/`, packaged as `dist/burnclock-skill.zip`) so an agent session
+can answer "how many tokens do I have left" with real numbers. Its shim reads only the six provider key
+variable **names** from `~/.hermes/.env` — it never sources the file and never prints a value. A daily cron
+suggestion for a runway alert lives in `hermes-skill/CRON.md`.
+
+## Design rules
+
+- **Read-only.** No top-ups, no spending, no provider mutations. Spending endpoints are never called.
+- **Fail-closed.** Missing keys are reported as such; malformed responses are `ERROR`, never `$0`.
+- **No secrets in files.** Config holds env-var names only; the packaged skill is secret-scanned.
+- **Offline floor.** With zero keys it still reports what your local Hermes usage records know.
+- **Estimates, not billing truth.** Runway is a range: bursty usage moves it, and providers change prices.
+
+## Development
+
+```sh
+.venv/bin/pytest -q                            # full suite (synthetic fixtures only, no network)
+bash hermes-skill/scripts/build-skill-zip.sh   # package + secret-scan the skill
+```
+
+Tests never touch a real provider: transports are faked and every fixture is synthetic. Timing protocol and
+recorded numbers live in [BENCH.md](BENCH.md); release history in [CHANGELOG.md](CHANGELOG.md).
+
+MIT licensed. Built by Jeremy Silbernagel.

burnclock-0.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+burnclock_cli/__init__.py,sha256=AaQXy1QzKy2Bn2Kvf4N17yP6UthNUduRSiIZ0leueqE,83
+burnclock_cli/completions.py,sha256=K-euw8a07QFDHfh-vuGraWuzs6_dha7jSh9t_p7IZo8,6117
+burnclock_cli/main.py,sha256=OGHPlIi4Y7VzkeB1yZQQt-MtOifS-YizdUkoqGWZCVM,57637
+burnclock_core/__init__.py,sha256=13T6e2YdeGK08krQDbJ3ygwUz3gTG4pwhjHJJB5bNoo,192
+burnclock_core/burn.py,sha256=yQVTgdyyUqPkB4Si6qZcvXTWcs0KgXUYSrrg5fcQVR0,13109
+burnclock_core/config.py,sha256=ZGTdF2opa3zTSnZUOlLDr1OfHFMoBfViMzyDmQ_pTxY,24279
+burnclock_core/envelope.py,sha256=yyTW0YqpC9UxreQ3HMJ8r7cJbj27fe8b7oJLkYWIXvI,12207
+burnclock_core/forecast.py,sha256=ttpbkxe7mJzdNwVgK14drPniGPesHdojxPXR8bbTV1A,5437
+burnclock_core/pricing.py,sha256=7ku3rRZdVY7Hcf4bXN04ctd_ImkeRMXflLmFMIB85bs,17936
+burnclock_core/schema.py,sha256=zVuxfQwWoBAFPOeptFnm5y0TnjP5phXhM-heeoKF1-A,4764
+burnclock_core/upgrade.py,sha256=DrMM6I472AJxzLgRQOzrGc5vVOpEp9i5R57Fqr0BSN0,8078
+burnclock_core/usage.py,sha256=pYuTvk6y1qX_Pqi7UVWwDCGzLsu3C3wMceNAhTW7CpM,9484
+burnclock_core/providers/__init__.py,sha256=RYx9-aeu1pX8K1_qza40IELbdD0p_zDSy1aUGJe2LUE,80
+burnclock_core/providers/deepseek.py,sha256=ZRy1PuVzZUJn4DBx1C-428bz-DA25xo7hv1z2k0ORpw,14499
+burnclock_core/providers/fal.py,sha256=rj5yveD5X6DbrzBz7keo-sdg5SRAO_iDpSw4IezJZK8,19580
+burnclock_core/providers/minimax.py,sha256=OUURVNM7sOUNwiqq-zA6V2LnoyTTgi5kQlrQKhAuTpc,19392
+burnclock_core/providers/moonshot.py,sha256=XK4srkVxMh_muqRJU6BaSHOFrseBFydVht8hKckCHSg,12294
+burnclock_core/providers/openrouter.py,sha256=fDqXF7YbI1RWC037D3OW4ld01LV0cmVvqUJVdP_3eF4,9399
+burnclock_core/providers/xai.py,sha256=gbbEeMgOLqdUVQ0869YfawtlqISm1W34zhyKZMJjKLU,10252
+burnclock-0.1.0.dist-info/METADATA,sha256=ENY3R6ZhRpa2QRrjI8aS18YmvByo430mtTKn3XyifBg,6833
+burnclock-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+burnclock-0.1.0.dist-info/entry_points.txt,sha256=Pu3zaqBJMVN1VbaG0mY7PetAHB1jE_ufGKmB4Rt0G0c,53
+burnclock-0.1.0.dist-info/top_level.txt,sha256=s8KB0J8w7pA1EVYltmg1HZNn8T7Pwxs0tlY-QjGj1bE,29
+burnclock-0.1.0.dist-info/RECORD,,

burnclock-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

burnclock-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+burnclock = burnclock_cli.main:run

burnclock-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+burnclock_cli
+burnclock_core

burnclock_cli/__init__.py

@@ -0,0 +1 @@
+"""burnclock_cli — thin Typer + Rich CLI over burnclock_core. No TUI imports."""

burnclock_cli/completions.py

@@ -0,0 +1,159 @@
+"""Static shell-completion scripts for `burnclock completion <shell>` (B5-B1).
+
+Pure stdlib strings: importing this module must never pull in typer, rich, or
+httpx — the completion path stays as light as the scripts it prints. Nothing
+here is generated at runtime from the Typer app; the command/option lists are
+deliberate, reviewed text so a completion can never leak ANSI styling or a
+startup side effect.
+"""
+
+from __future__ import annotations
+
+SUPPORTED_SHELLS: tuple[str, ...] = ("bash", "zsh", "fish")
+
+# The full command surface the scripts complete (B5-B1 brief §1).
+SUBCOMMANDS: tuple[str, ...] = (
+    "status",
+    "forecast",
+    "dashboard",
+    "watch",
+    "version",
+    "config",
+    "budget",
+    "completion",
+)
+
+# Long options shared by the commands (help + machine/human switches + tuning).
+LONG_OPTIONS: tuple[str, ...] = (
+    "--json",
+    "--min",
+    "--min-days",
+    "--interval",
+    "--config",
+    "--help",
+)
+
+_BASH_SCRIPT = """\
+# burnclock bash completion (static; generated by `burnclock completion bash`)
+_burnclock_completion() {
+    local cur prev
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    local commands="status forecast dashboard watch version config budget completion"
+    local options="--json --min --min-days --interval --config --help"
+
+    if [[ "${cur}" == -* ]]; then
+        COMPREPLY=( $(compgen -W "${options}" -- "${cur}") )
+        return 0
+    fi
+
+    case "${prev}" in
+        completion)
+            COMPREPLY=( $(compgen -W "bash zsh fish" -- "${cur}") )
+            return 0
+            ;;
+        config)
+            COMPREPLY=( $(compgen -W "show path" -- "${cur}") )
+            return 0
+            ;;
+        budget)
+            COMPREPLY=( $(compgen -W "show get set unset" -- "${cur}") )
+            return 0
+            ;;
+    esac
+
+    COMPREPLY=( $(compgen -W "${commands} ${options}" -- "${cur}") )
+    return 0
+}
+complete -F _burnclock_completion burnclock
+"""
+
+_ZSH_SCRIPT = """\
+#compdef burnclock
+# burnclock zsh completion (static; generated by `burnclock completion zsh`)
+
+_burnclock() {
+    _arguments -C \\
+        '(-h --help)'{-h,--help}'[show help and exit]' \\
+        '--json[machine-readable envelope output]' \\
+        '--min[alert below this USD balance]:usd:' \\
+        '--min-days[alert below this many days of paid runway]:days:' \\
+        '--interval[watch refresh interval in seconds]:seconds:' \\
+        '--config[path to config.toml]:file:_files' \\
+        '1:command:->command' \\
+        '*::argument:->argument'
+
+    case "$state" in
+        command)
+            _values 'burnclock command' \\
+                'status[provider status table or JSON envelope]' \\
+                'forecast[paid runway, burn per day, budget crossing]' \\
+                'dashboard[every known provider, disabled rows included]' \\
+                'watch[live refresh loop (TUI on a terminal)]' \\
+                'version[print the burnclock version]' \\
+                'config[inspect configuration (show, path)]' \\
+                'budget[view or set per-provider monthly budgets]' \\
+                'completion[print a shell completion script]'
+            ;;
+        argument)
+            case "${words[CURRENT-1]}" in
+                completion)
+                    _values 'shell' bash zsh fish
+                    ;;
+                config)
+                    _values 'config subcommand' show path
+                    ;;
+                budget)
+                    _values 'budget subcommand' show get set unset
+                    ;;
+                *)
+                    # compadd: the leading dashes would be parsed as _values
+                    # options, and after `--` they are plain completions.
+                    compadd -- --json --min --min-days --interval --config --help
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_burnclock "$@"
+"""
+
+_FISH_SCRIPT = """\
+# burnclock fish completion (static; generated by `burnclock completion fish`)
+complete -c burnclock -f
+complete -c burnclock -n '__fish_use_subcommand' -a status -d 'provider status table or JSON envelope'
+complete -c burnclock -n '__fish_use_subcommand' -a forecast -d 'paid runway, burn per day, budget crossing'
+complete -c burnclock -n '__fish_use_subcommand' -a dashboard -d 'every known provider, disabled rows included'
+complete -c burnclock -n '__fish_use_subcommand' -a watch -d 'live refresh loop (TUI on a terminal)'
+complete -c burnclock -n '__fish_use_subcommand' -a version -d 'print the burnclock version'
+complete -c burnclock -n '__fish_use_subcommand' -a config -d 'inspect configuration (show, path)'
+complete -c burnclock -n '__fish_use_subcommand' -a budget -d 'view or set per-provider monthly budgets'
+complete -c burnclock -n '__fish_use_subcommand' -a completion -d 'print a shell completion script'
+complete -c burnclock -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish' -d 'shell'
+complete -c burnclock -n '__fish_seen_subcommand_from config' -a 'show path' -d 'config subcommand'
+complete -c burnclock -n '__fish_seen_subcommand_from budget' -a 'show get set unset' -d 'budget subcommand'
+complete -c burnclock -l json -d 'machine-readable envelope output'
+complete -c burnclock -l min -r -d 'alert below this USD balance'
+complete -c burnclock -l min-days -r -d 'alert below this many days of paid runway'
+complete -c burnclock -l interval -r -d 'watch refresh interval in seconds'
+complete -c burnclock -l config -r -d 'path to config.toml'
+complete -c burnclock -l help -d 'show help and exit'
+"""
+
+_SCRIPTS: dict[str, str] = {
+    "bash": _BASH_SCRIPT,
+    "zsh": _ZSH_SCRIPT,
+    "fish": _FISH_SCRIPT,
+}
+
+
+def completion_script(shell: str) -> str | None:
+    """Return the static completion script for `shell`, or None if unsupported.
+
+    Case/whitespace tolerant so `BASH` and ` bash ` both work; an unknown name
+    returns None and the CLI turns that into exit 2 (EXIT_USAGE). The returned
+    text is pure ASCII/UTF-8 plain text with no ANSI or Rich markup.
+    """
+    key = (shell or "").strip().lower()
+    return _SCRIPTS.get(key)