Implement LLM-WP-0008: provider-scoped account balance CLI
Add pluggable balance registry, OpenRouter credits/key limit client, and llm-connect balance with one-shot --provider that does not change library defaults.
This commit is contained in:
parent
c0d5c4ad08
commit
ed7c632155
11 changed files with 783 additions and 14 deletions
44
contracts/functional/account-balance.md
Normal file
44
contracts/functional/account-balance.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
# Provider Account Balance
|
||||
|
||||
`llm_connect.balance` reports **prepaid / key remaining** for a selected
|
||||
inference **backend**. Balance is never assumed to be OpenRouter unless that
|
||||
backend is selected (explicitly or as the current default provider).
|
||||
|
||||
## Selection rules
|
||||
|
||||
```python
|
||||
from llm_connect import get_account_balance, resolve_balance_provider
|
||||
|
||||
resolve_balance_provider(None) # → LLMConfig().provider (today openrouter)
|
||||
resolve_balance_provider("openrouter") # one-shot; does not mutate defaults
|
||||
get_account_balance() # default backend
|
||||
get_account_balance("openrouter") # explicit backend for this call only
|
||||
```
|
||||
|
||||
- Explicit `provider` / CLI `--provider` is **invocation-only**.
|
||||
- It must not rewrite config files, env, `LLMConfig` class defaults, or
|
||||
OpenRouter model defaults.
|
||||
- Unspecified → current default provider via `resolve_balance_provider(None)`.
|
||||
|
||||
## Contract
|
||||
|
||||
- `AccountBalance` carries optional wallet fields (`credits_*`) and optional
|
||||
key-limit fields (`limit`, `limit_remaining`, `limit_reset`, `usage`).
|
||||
- EUR display fields use the same FX resolution as cost estimates.
|
||||
- `BalanceClientRegistry` maps provider id → client factory.
|
||||
- Unsupported providers raise `LLMBalanceUnsupportedError` listing supported
|
||||
backends (do not fall back to OpenRouter).
|
||||
|
||||
## OpenRouter (v1)
|
||||
|
||||
- `GET /api/v1/credits` → account prepaid: remaining = total_credits − total_usage
|
||||
- `GET /api/v1/auth/key` → key limit remaining / reset policy
|
||||
- Both are fetched best-effort; one may fail while the other succeeds.
|
||||
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
llm-connect balance
|
||||
llm-connect balance --provider openrouter
|
||||
llm-connect balance --json
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue