7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.
TypeScript
feat(quota): daily balance forecast + low-balance warning endpoint (#1104) (#1111)
suantea (asuan_suan)2558c9f91da9
diff --git a/server/src/__tests__/services/quota-forecast.test.ts b/server/src/__tests__/services/quota-forecast.test.tsnew file mode 100644index 00000000..c78f8062--- /dev/null+++ b/server/src/__tests__/services/quota-forecast.test.ts@@ -0,0 +1,119 @@+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';+import { initDb, getDb } from '../../db/index.js';+import { getQuotaForecast } from '../../services/quota-forecast.js';++function insertState(row: {+ platform: string;+ keyId: number;+ pool: string;+ metric: string;+ limit: number | null;+ remaining: number | null;+ resetAt: string | null;+}) {+ getDb().prepare(`+ INSERT INTO provider_quota_state+ (platform, key_id, quota_pool_key, metric, limit_value, remaining_value, reset_at, observed_at, updated_at)+ VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))+ `).run(row.platform, row.keyId, row.pool, row.metric, row.limit, row.remaining, row.resetAt);+}++const future = () => new Date(Date.now() + 12 * 3600 * 1000).toISOString(); // 12h ahead → within today++describe('quota-forecast: daily balance aggregation (#1104)', () => {+ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ });++ beforeEach(() => {+ getDb().prepare('DELETE FROM provider_quota_state').run();+ });++ it('reports used/remaining/pct/reset for a request pool with a known limit', () => {+ insertState({ platform: 'groq', keyId: 1, pool: 'groq::account', metric: 'requests', limit: 100, remaining: 60, resetAt: future() });++ const forecast = getQuotaForecast();+ expect(forecast).toHaveLength(1);+ const e = forecast[0];+ expect(e.platform).toBe('groq');+ expect(e.pool).toBe('groq::account');+ expect(e.used).toBe(40);+ expect(e.remaining).toBe(60);+ expect(e.limit).toBe(100);+ expect(e.remaining_pct).toBe(60);+ expect(e.low_balance).toBe(false);+ expect(e.seconds_until_reset).toBeGreaterThan(0);+ });++ it('flags low_balance below the 10% threshold', () => {+ insertState({ platform: 'openai', keyId: 1, pool: 'openai::account', metric: 'requests', limit: 100, remaining: 8, resetAt: future() });++ const e = getQuotaForecast()[0];+ expect(e.remaining_pct).toBe(8);+ expect(e.low_balance).toBe(true);+ });++ it('flags low_balance on the absolute floor even when pct looks fine', () => {+ insertState({ platform: 'openrouter', keyId: 1, pool: 'openrouter::free', metric: 'requests', limit: 10000, remaining: 15, resetAt: future() });++ const e = getQuotaForecast()[0];+ expect(e.remaining_pct).toBe(0); // 15/10000 rounds to 0+ expect(e.low_balance).toBe(true);+ });++ it('dedupes multi-key shared pools to the tightest remaining', () => {+ insertState({ platform: 'groq', keyId: 1, pool: 'groq::account', metric: 'requests', limit: 100, remaining: 90, resetAt: future() });+ insertState({ platform: 'groq', keyId: 2, pool: 'groq::account', metric: 'requests', limit: 100, remaining: 20, resetAt: future() });++ const forecast = getQuotaForecast();+ expect(forecast).toHaveLength(1);+ expect(forecast[0].remaining).toBe(20); // tightest wins+ // 20 of 100 is a fifth of the window, and 100 is below the absolute+ // floor's minimum, so nothing here is low.+ expect(forecast[0].low_balance).toBe(false);+ });++ it('does not apply the absolute floor to a small window', () => {+ // A 30/day tier with 25 left has five sixths of its window: the absolute+ // floor of 20 would call that low, which is the bug this guards.+ insertState({ platform: 'cerebras', keyId: 1, pool: 'cerebras::account', metric: 'requests', limit: 30, remaining: 25, resetAt: future() });++ const e = getQuotaForecast()[0];+ expect(e.remaining_pct).toBe(83);+ expect(e.low_balance).toBe(false);+ });++ it('still warns on a small window once the percentage rule bites', () => {+ insertState({ platform: 'cerebras', keyId: 1, pool: 'cerebras::account', metric: 'requests', limit: 30, remaining: 2, resetAt: future() });++ expect(getQuotaForecast()[0].low_balance).toBe(true);+ });++ it('leaves used null when the provider reported no remaining', () => {+ insertState({ platform: 'groq', keyId: 1, pool: 'groq::account', metric: 'requests', limit: 100, remaining: null, resetAt: future() });++ const e = getQuotaForecast()[0];+ expect(e.used).toBeNull();+ expect(e.remaining).toBeNull();+ expect(e.remaining_pct).toBeNull();+ expect(e.low_balance).toBe(false);+ });++ it('keys the dedupe on the pool alone, which already names its platform', () => {+ insertState({ platform: 'groq', keyId: 1, pool: 'groq::account', metric: 'requests', limit: 1000, remaining: 900, resetAt: future() });+ insertState({ platform: 'groq', keyId: 2, pool: 'groq::batch', metric: 'requests', limit: 1000, remaining: 800, resetAt: future() });++ const pools = getQuotaForecast().map(e => e.pool);+ expect(pools).toContain('groq::account');+ expect(pools).toContain('groq::batch');+ });++ it('ignores non-request metrics and unknown limits', () => {+ insertState({ platform: 'groq', keyId: 1, pool: 'groq::account', metric: 'tokens', limit: 1000, remaining: 500, resetAt: future() });+ insertState({ platform: 'ollama', keyId: 1, pool: 'ollama::account', metric: 'requests', limit: null, remaining: null, resetAt: null });++ const forecast = getQuotaForecast();+ expect(forecast).toHaveLength(0);+ });+});diff --git a/server/src/routes/status.ts b/server/src/routes/status.tsindex 4c216585..4abb2c30 100644--- a/server/src/routes/status.ts+++ b/server/src/routes/status.ts@@ -7,6 +7,12 @@ import { extractApiToken, timingSafeStringEqual } from './proxy.js';import { getProvider } from '../providers/index.js';import { getSoonestCooldownExpiry } from '../services/ratelimit.js';import { getQuotaStateForKeys } from '../services/provider-quota.js';+import {+ getQuotaForecast,+ LOW_BALANCE_THRESHOLD,+ LOW_BALANCE_ABSOLUTE,+ LOW_BALANCE_ABSOLUTE_MIN_LIMIT,+} from '../services/quota-forecast.js';import { openapiSpec } from '../docs/openapi.js';// Machine-readable operational endpoints for meta-gateways / orchestrators that@@ -206,3 +212,28 @@ providersRouter.get('/providers', (req: Request, res: Response) => {res.json({ providers, counts });});++// GET /quota-forecast — per-pool daily headroom + low-balance warning (#1104).+// Machine-readable sibling of /v1/providers: same unified-key auth, no key+// material, no PII. A meta-gateway can gate its own routing on `low_balance`+// BEFORE spending a request that would 429, and know `seconds_until_reset` for+// "the window resets soon, hold off" scheduling.+providersRouter.get('/quota-forecast', (req: Request, res: Response) => {+ const token = extractApiToken(req);+ const unifiedKey = getUnifiedApiKey();+ if (!token || !timingSafeStringEqual(token, unifiedKey)) {+ res.status(401).json({ error: { message: 'Invalid API key', type: 'authentication_error' } });+ return;+ }++ const forecast = getQuotaForecast();+ res.json({+ generated_at: new Date().toISOString(),+ low_balance_threshold: {+ pct: LOW_BALANCE_THRESHOLD,+ absolute: LOW_BALANCE_ABSOLUTE,+ absolute_min_limit: LOW_BALANCE_ABSOLUTE_MIN_LIMIT,+ },+ pools: forecast,+ });+});diff --git a/server/src/services/quota-forecast.ts b/server/src/services/quota-forecast.tsnew file mode 100644index 00000000..582c76d1--- /dev/null+++ b/server/src/services/quota-forecast.ts@@ -0,0 +1,110 @@+import type { QuotaObservationView } from './provider-quota.js';+import { getQuotaStateForKeys } from './provider-quota.js';++// Daily free-tier balance forecast (#1104). Free tiers reset on a per-account+// window (usually UTC midnight) and the only way to know how much headroom is+// left before that reset is to read what the providers themselves reported.+// This is a pure aggregation over `getQuotaStateForKeys()` — no new tables, no+// extra probes — so it costs nothing beyond the query the health view already+// runs.+//+// The value it adds over the raw rows: one number per platform that answers+// "can I keep calling this platform for the rest of today?", plus a+// low-balance warning an agent can gate on BEFORE sending a request that would+// 429.++export const LOW_BALANCE_THRESHOLD = 0.1; // <10% of the daily window left → warn+export const LOW_BALANCE_ABSOLUTE = 20; // ...or fewer than 20 requests left+// The absolute floor is a statement about big windows: "20 left" is alarming+// out of 14400/day and unremarkable out of 30/day. Below this limit the+// percentage rule alone decides, otherwise a small tier would warn from its+// first request onwards and the flag would mean nothing.+export const LOW_BALANCE_ABSOLUTE_MIN_LIMIT = 200;++export interface QuotaForecastEntry {+ /** Platform the pool belongs to, e.g. 'groq'. */+ platform: string;+ /** Human-readable pool label (platform::scope), e.g. 'groq::account'. */+ pool: string;+ /** Requests used in the current window. Null when `remaining` is unknown,+ * since used is only ever derived from it. */+ used: number | null;+ /** Requests remaining in the current window. Null when unknown. */+ remaining: number | null;+ /** Window total. Null when the provider never reported a limit. */+ limit: number | null;+ /** 0..100 share of the window still available (best-effort). */+ remaining_pct: number | null;+ /** ISO timestamp of the window reset, or null when never observed. */+ reset_at: string | null;+ /** True when less than LOW_BALANCE_THRESHOLD of the window remains, or —+ * on a window of at least LOW_BALANCE_ABSOLUTE_MIN_LIMIT — fewer than+ * LOW_BALANCE_ABSOLUTE requests do. Always false when remaining is unknown. */+ low_balance: boolean;+ /** Seconds until reset_at, or null when reset_at is unknown/expired. */+ seconds_until_reset: number | null;+}++function secondsUntilReset(resetAt: string | null): number | null {+ if (!resetAt) return null;+ const ms = new Date(resetAt).getTime() - Date.now();+ if (Number.isNaN(ms) || ms <= 0) return null;+ return Math.floor(ms / 1000);+}++function entryFor(row: QuotaObservationView): QuotaForecastEntry | null {+ // Only request-based windows are predictable from quota headers; token pools+ // reset semantics vary too much across providers to forecast honestly.+ if (row.metric !== 'requests') return null;+ // Without a known limit there is no window to forecast — nothing to warn on.+ if (typeof row.limit !== 'number' || row.limit <= 0) return null;++ const limit = row.limit;+ const remaining = typeof row.remaining === 'number' ? row.remaining : null;++ // An unknown `remaining` says nothing about consumption: reporting the whole+ // limit as used would read as an exhausted pool when it may be untouched.+ const used = remaining === null ? null : Math.max(0, limit - remaining);+ let remainingPct: number | null = null;+ let lowBalance = false;+ if (remaining !== null) {+ remainingPct = Math.max(0, Math.min(100, Math.round((remaining / limit) * 100)));+ const absoluteApplies = limit >= LOW_BALANCE_ABSOLUTE_MIN_LIMIT;+ lowBalance = (absoluteApplies && remaining <= LOW_BALANCE_ABSOLUTE)+ || remaining / limit < LOW_BALANCE_THRESHOLD;+ }++ return {+ platform: row.platform,+ pool: row.quotaPoolKey ?? `${row.platform}::default`,+ used,+ remaining,+ limit,+ remaining_pct: remainingPct,+ reset_at: row.resetAt ?? null,+ low_balance: lowBalance,+ seconds_until_reset: secondsUntilReset(row.resetAt ?? null),+ };+}++// Dedupe to the TIGHTEST row per platform+pool: a platform with several keys+// sharing one account pool reports the same window per key, and the number that+// matters for "can I keep calling" is the least headroom left.+export function getQuotaForecast(): QuotaForecastEntry[] {+ const byKey = new Map<string, QuotaForecastEntry>();+ for (const row of getQuotaStateForKeys()) {+ const entry = entryFor(row);+ if (!entry) continue;+ // `pool` already carries its platform ("groq::account"), so it is the key.+ const key = entry.pool;+ const prev = byKey.get(key);+ if (!prev || (entry.remaining_pct ?? Infinity) < (prev.remaining_pct ?? Infinity)) {+ byKey.set(key, entry);+ }+ }+ return [...byKey.values()].sort((a, b) => {+ // Low-balance pools first — the ones the caller most needs to see.+ if (a.low_balance !== b.low_balance) return a.low_balance ? -1 : 1;+ return a.platform.localeCompare(b.platform);+ });+}