fibcheck 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,125 @@
1
+ import { existsSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ import { CallBudget } from "./budget.js";
4
+ import { ModelClient } from "./client.js";
5
+ import { GeminiProvider } from "./gemini.js";
6
+ import { FallbackProvider, OpenAICompatibleProvider } from "./openai-compatible.js";
7
+ export const DEFAULT_LIMITS = { maxCallsPerRun: 60, maxCallsTotal: 1500 };
8
+ /**
9
+ * The paid backup on NEAR AI Cloud (owner's decision, 2026-11-17), used only when Gemini's free tier refuses
10
+ * or is overloaded. Prices are from NEAR AI's /v1/model/list on 2026-11-17, in dollars per million tokens.
11
+ */
12
+ export const NEAR_BACKUP = {
13
+ baseUrl: "https://cloud-api.near.ai/v1",
14
+ model: "google/gemini-2.5-flash-lite",
15
+ prices: { inputPerMillion: 0.1, outputPerMillion: 0.4 },
16
+ maxUsd: 0.2,
17
+ };
18
+ /** The NEAR AI backup provider, when NEAR_AI_API_KEY is set. Spending is kept in `<cwd>/.fibcheck/near-spend.json`. */
19
+ export function createNearProvider(cwd = process.cwd(), env = process.env) {
20
+ if (!env.NEAR_AI_API_KEY)
21
+ return undefined;
22
+ return new OpenAICompatibleProvider({
23
+ label: "near",
24
+ baseUrl: NEAR_BACKUP.baseUrl,
25
+ apiKey: env.NEAR_AI_API_KEY,
26
+ model: NEAR_BACKUP.model,
27
+ prices: NEAR_BACKUP.prices,
28
+ maxUsd: NEAR_BACKUP.maxUsd,
29
+ spendPath: join(cwd, ".fibcheck", "near-spend.json"),
30
+ });
31
+ }
32
+ /** Dollar cap for a user-chosen model with known prices, unless FIBCHECK_MODEL_MAX_USD says otherwise. */
33
+ export const DEFAULT_MODEL_MAX_USD = 1;
34
+ /**
35
+ * Any OpenAI-compatible model the user chooses with FIBCHECK_MODEL_BASE_URL, FIBCHECK_MODEL_API_KEY and
36
+ * FIBCHECK_MODEL (OpenAI, NEAR AI, OpenRouter, a local Ollama server and others). It replaces Gemini.
37
+ * With FIBCHECK_MODEL_PRICE_INPUT and FIBCHECK_MODEL_PRICE_OUTPUT (dollars per million tokens) a dollar cap
38
+ * applies; without them only the call cap does, and the report says so.
39
+ */
40
+ export function createModelFromEnv(cwd = process.cwd(), env = process.env) {
41
+ const baseUrl = env.FIBCHECK_MODEL_BASE_URL;
42
+ if (!baseUrl)
43
+ return undefined;
44
+ if (!URL.canParse(baseUrl) || !/^https?:$/.test(new URL(baseUrl).protocol)) {
45
+ throw new Error("FIBCHECK_MODEL_BASE_URL must be an http or https address, such as https://api.openai.com/v1.");
46
+ }
47
+ const model = env.FIBCHECK_MODEL;
48
+ if (!model)
49
+ throw new Error("FIBCHECK_MODEL_BASE_URL is set, so FIBCHECK_MODEL must name the model, such as gpt-4.1-mini.");
50
+ const host = new URL(baseUrl).hostname;
51
+ const local = host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".localhost");
52
+ if (!env.FIBCHECK_MODEL_API_KEY && !local) {
53
+ throw new Error(`FIBCHECK_MODEL_API_KEY is missing for ${host}. Only a model on this machine (such as Ollama) can run without a key.`);
54
+ }
55
+ const prices = readPrices(env);
56
+ return new OpenAICompatibleProvider({
57
+ label: host,
58
+ baseUrl,
59
+ apiKey: env.FIBCHECK_MODEL_API_KEY || undefined,
60
+ model,
61
+ prices,
62
+ maxUsd: prices ? positiveNumber(env.FIBCHECK_MODEL_MAX_USD, DEFAULT_MODEL_MAX_USD, "FIBCHECK_MODEL_MAX_USD") : undefined,
63
+ spendPath: prices ? join(cwd, ".fibcheck", "model-spend.json") : undefined,
64
+ });
65
+ }
66
+ function readPrices(env) {
67
+ const input = env.FIBCHECK_MODEL_PRICE_INPUT;
68
+ const output = env.FIBCHECK_MODEL_PRICE_OUTPUT;
69
+ if (!input && !output)
70
+ return undefined;
71
+ if (!input || !output)
72
+ throw new Error("Set both FIBCHECK_MODEL_PRICE_INPUT and FIBCHECK_MODEL_PRICE_OUTPUT, or neither.");
73
+ return {
74
+ inputPerMillion: positiveNumber(input, 0, "FIBCHECK_MODEL_PRICE_INPUT", true),
75
+ outputPerMillion: positiveNumber(output, 0, "FIBCHECK_MODEL_PRICE_OUTPUT", true),
76
+ };
77
+ }
78
+ function positiveNumber(raw, fallback, name, allowZero = false) {
79
+ if (raw === undefined || raw === "")
80
+ return fallback;
81
+ const value = Number(raw);
82
+ if (!Number.isFinite(value) || value < 0 || (!allowZero && value === 0))
83
+ throw new Error(`${name} must be a positive number of US dollars.`);
84
+ return value;
85
+ }
86
+ /** Loads `.env` from the working directory if present. Values are never printed. */
87
+ export function loadDotEnv(cwd = process.cwd()) {
88
+ const path = join(cwd, ".env");
89
+ if (existsSync(path))
90
+ process.loadEnvFile(path);
91
+ }
92
+ export function readLimits(env = process.env) {
93
+ return {
94
+ maxCallsPerRun: positiveInt(env.FIBCHECK_MAX_CALLS_PER_RUN, DEFAULT_LIMITS.maxCallsPerRun, "FIBCHECK_MAX_CALLS_PER_RUN"),
95
+ maxCallsTotal: positiveInt(env.FIBCHECK_MAX_CALLS_TOTAL, DEFAULT_LIMITS.maxCallsTotal, "FIBCHECK_MAX_CALLS_TOTAL"),
96
+ };
97
+ }
98
+ /** Builds the shared model client for one run. Usage files live in `<cwd>/.fibcheck/`. */
99
+ export function createModelClient(runId, cwd = process.cwd(), env = process.env) {
100
+ const dir = join(cwd, ".fibcheck");
101
+ const budget = new CallBudget(readLimits(env), runId, join(dir, "usage-totals.json"), join(dir, "usage-ledger.jsonl"));
102
+ const chosen = createModelFromEnv(cwd, env);
103
+ if (chosen)
104
+ return new ModelClient(chosen, budget);
105
+ if (!env.GEMINI_API_KEY && !env.GOOGLE_API_KEY) {
106
+ throw new Error("No model is configured. Put GEMINI_API_KEY=... in .env (a free key from https://aistudio.google.com/apikey), " +
107
+ "or choose any OpenAI-compatible model with FIBCHECK_MODEL_BASE_URL, FIBCHECK_MODEL_API_KEY and FIBCHECK_MODEL.");
108
+ }
109
+ const gemini = new GeminiProvider({
110
+ apiKey: env.GOOGLE_API_KEY || env.GEMINI_API_KEY,
111
+ model: env.FIBCHECK_GEMINI_MODEL || undefined,
112
+ fallbackModel: env.FIBCHECK_GEMINI_FALLBACK_MODEL || undefined,
113
+ });
114
+ const near = createNearProvider(cwd, env);
115
+ const provider = near ? new FallbackProvider(gemini, near) : gemini;
116
+ return new ModelClient(provider, budget);
117
+ }
118
+ function positiveInt(raw, fallback, name) {
119
+ if (raw === undefined || raw === "")
120
+ return fallback;
121
+ const value = Number(raw);
122
+ if (!Number.isInteger(value) || value <= 0)
123
+ throw new Error(`${name} must be a positive whole number.`);
124
+ return value;
125
+ }
@@ -0,0 +1,100 @@
1
+ import { ApiError, GoogleGenAI } from "@google/genai";
2
+ import { ProviderOverloadedError, RateLimitedError } from "./types.js";
3
+ /**
4
+ * Default models (approval A2). On 2026-11-17 the owner made gemini-3.5-flash-lite the primary model on the
5
+ * free tier, because gemini-3.6-flash reached its daily quota and gemini-4-hydrogen returned capacity errors.
6
+ * Hydrogen is kept out of the call path so no request waits on its retries; the fallback is the same model.
7
+ * gemini-3.8-flash was tried earlier but timed out on the server (HTTP 504 DEADLINE_EXCEEDED) twice on a tiny prompt.
8
+ */
9
+ export const DEFAULT_GEMINI_MODEL = "gemini-3.5-flash-lite";
10
+ export const DEFAULT_GEMINI_FALLBACK_MODEL = "gemini-3.5-flash-lite";
11
+ /** Per-request timeout. Claim extraction on a 250-line part normally answers well within this. */
12
+ export const REQUEST_TIMEOUT_MS = 90_000;
13
+ /**
14
+ * Retries an overloaded or timed-out Gemini request with exponential backoff.
15
+ * After two capacity failures on the main model, the third attempt uses the
16
+ * fallback model (FIBCHECK_GEMINI_FALLBACK_MODEL), which is the same model unless that is set. When that works, subsequent requests on this client use it
17
+ * for the rest of the run. Each HTTP request reserves its own budget slot.
18
+ */
19
+ export class GeminiProvider {
20
+ name = "gemini";
21
+ spendingLimit = "call cap only (Gemini free tier, no dollar cost)";
22
+ fallbackModel;
23
+ api;
24
+ initialRetryDelayMs;
25
+ sleep;
26
+ activeModel;
27
+ constructor(options = {}) {
28
+ this.fallbackModel = options.fallbackModel ?? DEFAULT_GEMINI_FALLBACK_MODEL;
29
+ this.activeModel = options.model ?? DEFAULT_GEMINI_MODEL;
30
+ this.initialRetryDelayMs = options.initialRetryDelayMs ?? 2_000;
31
+ this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
32
+ // One attempt and a timeout: the SDK's default of 5 hidden retries with waits up to
33
+ // 60 seconds would hide rate limits and spend free-tier quota our call limits never see.
34
+ this.api =
35
+ options.api ??
36
+ new GoogleGenAI({ apiKey: options.apiKey, httpOptions: { timeout: REQUEST_TIMEOUT_MS, retryOptions: { attempts: 1 } } }).models;
37
+ }
38
+ async generate(request, beforeAttempt = () => { }) {
39
+ const firstModel = this.activeModel;
40
+ const plan = [firstModel, firstModel, this.fallbackModel];
41
+ let lastError;
42
+ for (const [index, model] of plan.entries()) {
43
+ if (index > 0)
44
+ await this.sleep(this.initialRetryDelayMs * 2 ** (index - 1));
45
+ beforeAttempt();
46
+ try {
47
+ const response = await this.call(model, request);
48
+ if (model === this.fallbackModel)
49
+ this.activeModel = model;
50
+ return response;
51
+ }
52
+ catch (error) {
53
+ lastError = error;
54
+ if (!isCapacityError(error))
55
+ break;
56
+ }
57
+ }
58
+ throw toProviderError(lastError);
59
+ }
60
+ async call(model, request) {
61
+ const response = await this.api.generateContent({
62
+ model,
63
+ contents: request.prompt,
64
+ config: {
65
+ systemInstruction: request.system,
66
+ ...(request.jsonSchema
67
+ ? { responseMimeType: "application/json", responseJsonSchema: request.jsonSchema }
68
+ : {}),
69
+ },
70
+ });
71
+ const usage = response.usageMetadata ?? {};
72
+ return {
73
+ text: response.text ?? "",
74
+ model,
75
+ usage: {
76
+ inputTokens: usage.promptTokenCount ?? 0,
77
+ outputTokens: (usage.candidatesTokenCount ?? 0) + (usage.thoughtsTokenCount ?? 0),
78
+ },
79
+ };
80
+ }
81
+ }
82
+ function isRateLimit(error) {
83
+ return error instanceof ApiError && error.status === 429;
84
+ }
85
+ function isCapacityError(error) {
86
+ return error instanceof ApiError && (error.status === 503 || error.status === 504);
87
+ }
88
+ /** Turns SDK errors into short messages that cannot carry the key or the prompt. */
89
+ function toProviderError(error) {
90
+ if (isRateLimit(error)) {
91
+ return new RateLimitedError("Gemini returned HTTP 429. Wait for the active rate limit or project quota to reset.");
92
+ }
93
+ if (isCapacityError(error)) {
94
+ return new ProviderOverloadedError(`Gemini is overloaded or timing out (HTTP ${error.status}). Try again in a few minutes.`);
95
+ }
96
+ if (error instanceof ApiError) {
97
+ return new Error(`Gemini API error (HTTP ${error.status}).`);
98
+ }
99
+ return error instanceof Error ? error : new Error("Unknown error from the Gemini provider.");
100
+ }
@@ -0,0 +1,146 @@
1
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2
+ import { dirname } from "node:path";
3
+ import { ProviderOverloadedError, RateLimitedError } from "./types.js";
4
+ /** Raised when a request could take spending past the dollar cap. */
5
+ export class SpendCapError extends Error {
6
+ constructor(message) {
7
+ super(message);
8
+ this.name = "SpendCapError";
9
+ }
10
+ }
11
+ /**
12
+ * A provider for OpenAI-compatible chat completion APIs, such as NEAR AI Cloud.
13
+ * Before each request it checks that the worst case (the prompt plus the
14
+ * output-token limit) still fits under the dollar cap, and afterwards it
15
+ * records the actual cost from the response's token usage.
16
+ */
17
+ export class OpenAICompatibleProvider {
18
+ options;
19
+ name;
20
+ spendingLimit;
21
+ maxOutputTokens;
22
+ constructor(options) {
23
+ this.options = options;
24
+ if (options.prices && (options.maxUsd === undefined || !options.spendPath)) {
25
+ throw new Error("A provider with known prices needs a dollar cap and a spend file.");
26
+ }
27
+ this.name = `${options.label}:${options.model}`;
28
+ this.maxOutputTokens = options.maxOutputTokens ?? 16_000;
29
+ this.spendingLimit = options.prices && options.maxUsd !== undefined
30
+ ? `dollar cap $${options.maxUsd.toFixed(2)} in total, at $${options.prices.inputPerMillion} and $${options.prices.outputPerMillion} per million input and output tokens`
31
+ : "call cap only (this model's prices are unknown, so its dollar cost is not tracked)";
32
+ }
33
+ async generate(request, beforeAttempt = () => { }) {
34
+ const spent = this.spent();
35
+ const worstCase = this.cost(estimateTokens(request.system + request.prompt), this.maxOutputTokens);
36
+ const cap = this.options.maxUsd ?? Infinity;
37
+ if (spent + worstCase > cap) {
38
+ throw new SpendCapError(`The ${this.options.label} spending cap of $${cap.toFixed(2)} would be exceeded ($${spent.toFixed(4)} spent).`);
39
+ }
40
+ beforeAttempt();
41
+ let data;
42
+ try {
43
+ data = await this.send(request);
44
+ }
45
+ catch (error) {
46
+ // The request may have been billed even though it failed, so count the worst case.
47
+ this.record(worstCase);
48
+ throw error;
49
+ }
50
+ const inputTokens = data.usage?.prompt_tokens ?? 0;
51
+ const outputTokens = data.usage?.completion_tokens ?? 0;
52
+ this.record(data.usage ? this.cost(inputTokens, outputTokens) : worstCase);
53
+ return { text: data.choices?.[0]?.message?.content ?? "", model: this.name, usage: { inputTokens, outputTokens } };
54
+ }
55
+ async send(request) {
56
+ const response = await (this.options.fetch ?? fetch)(`${this.options.baseUrl.replace(/\/$/, "")}/chat/completions`, {
57
+ method: "POST",
58
+ headers: { "Content-Type": "application/json", ...(this.options.apiKey ? { Authorization: `Bearer ${this.options.apiKey}` } : {}) },
59
+ body: JSON.stringify(this.body(request)),
60
+ signal: AbortSignal.timeout(this.options.timeoutMs ?? 90_000),
61
+ });
62
+ if (!response.ok)
63
+ throw providerError(this.options.label, response.status);
64
+ return (await response.json());
65
+ }
66
+ /** Dollars spent so far across runs. A damaged file refuses further calls rather than resetting the count. */
67
+ spent() {
68
+ if (!this.options.prices || !this.options.spendPath)
69
+ return 0;
70
+ if (!existsSync(this.options.spendPath))
71
+ return 0;
72
+ let value;
73
+ try {
74
+ value = JSON.parse(readFileSync(this.options.spendPath, "utf8")).usd;
75
+ }
76
+ catch {
77
+ value = undefined;
78
+ }
79
+ if (typeof value === "number" && Number.isFinite(value) && value >= 0)
80
+ return value;
81
+ throw new SpendCapError(`The spend file ${this.options.spendPath} is damaged. Fix or delete it on purpose before more paid calls.`);
82
+ }
83
+ body(request) {
84
+ return {
85
+ model: this.options.model,
86
+ messages: [
87
+ { role: "system", content: request.system },
88
+ { role: "user", content: request.prompt },
89
+ ],
90
+ max_tokens: this.maxOutputTokens,
91
+ ...(request.jsonSchema
92
+ ? { response_format: { type: "json_schema", json_schema: { name: "response", schema: request.jsonSchema } } }
93
+ : {}),
94
+ };
95
+ }
96
+ cost(inputTokens, outputTokens) {
97
+ const prices = this.options.prices;
98
+ return prices ? (inputTokens * prices.inputPerMillion + outputTokens * prices.outputPerMillion) / 1_000_000 : 0;
99
+ }
100
+ record(usd) {
101
+ const path = this.options.spendPath;
102
+ if (!this.options.prices || !path)
103
+ return;
104
+ const total = this.spent() + usd;
105
+ mkdirSync(dirname(path), { recursive: true });
106
+ writeFileSync(path, `${JSON.stringify({ usd: total }, null, 2)}\n`);
107
+ }
108
+ }
109
+ /** A cautious token estimate (about 3 characters per token), used only for the worst-case cost check. */
110
+ function estimateTokens(text) {
111
+ return Math.ceil(text.length / 3);
112
+ }
113
+ function providerError(label, status) {
114
+ if (status === 429)
115
+ return new RateLimitedError(`${label} returned HTTP 429. Wait for its rate limit to reset.`);
116
+ if (status === 502 || status === 503 || status === 504)
117
+ return new ProviderOverloadedError(`${label} is overloaded or timing out (HTTP ${status}).`);
118
+ return new Error(`${label} API error (HTTP ${status}).`);
119
+ }
120
+ /**
121
+ * Uses the primary provider, and the backup only when the primary refuses for
122
+ * rate limits or overload. Each provider announces its own requests, so the
123
+ * call budget counts both.
124
+ */
125
+ export class FallbackProvider {
126
+ primary;
127
+ backup;
128
+ name;
129
+ spendingLimit;
130
+ constructor(primary, backup) {
131
+ this.primary = primary;
132
+ this.backup = backup;
133
+ this.name = `${primary.name}, then ${backup.name}`;
134
+ this.spendingLimit = `${primary.name}: ${primary.spendingLimit ?? "call cap only"}; backup ${backup.name}: ${backup.spendingLimit ?? "call cap only"}`;
135
+ }
136
+ async generate(request, beforeAttempt) {
137
+ try {
138
+ return await this.primary.generate(request, beforeAttempt);
139
+ }
140
+ catch (error) {
141
+ if (!(error instanceof RateLimitedError || error instanceof ProviderOverloadedError))
142
+ throw error;
143
+ return await this.backup.generate(request, beforeAttempt);
144
+ }
145
+ }
146
+ }
@@ -0,0 +1,28 @@
1
+ /**
2
+ * The provider-neutral interface for fibcheck's own agent.
3
+ *
4
+ * Everything outside `src/model` talks to a `ModelClient`, never to a
5
+ * provider SDK, so a provider can be swapped (or replaced by an MCP host
6
+ * such as Claude Code or Codex) without touching the rest of the code.
7
+ */
8
+ /** Raised when a model answered but its reply cannot be used (not JSON, or the wrong shape). */
9
+ export class UnusableModelOutputError extends Error {
10
+ constructor(message) {
11
+ super(message);
12
+ this.name = "UnusableModelOutputError";
13
+ }
14
+ }
15
+ /** Raised when a provider is overloaded or timing out (for example HTTP 503 or 504). */
16
+ export class ProviderOverloadedError extends Error {
17
+ constructor(message) {
18
+ super(message);
19
+ this.name = "ProviderOverloadedError";
20
+ }
21
+ }
22
+ /** Raised when a provider rejects a request because of rate limits. */
23
+ export class RateLimitedError extends Error {
24
+ constructor(message) {
25
+ super(message);
26
+ this.name = "RateLimitedError";
27
+ }
28
+ }