Skip to content

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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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);
+ });
+}