@extrafemi-ai/lodestone 0.3.1 → 0.5.0

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.
@@ -3,6 +3,13 @@ const part = (p) => (p.type === 'text' ? { type: 'text', text: p.text } : { type
3
3
  const wire = (m) => ({ role: m.role, content: typeof m.content === 'string' ? m.content : m.content.map(part) });
4
4
  export function openrouter(opts = {}) {
5
5
  const f = opts.fetch ?? fetch;
6
+ const reasoningFor = (model) => {
7
+ if (opts.reasoning) {
8
+ const r = opts.reasoning(model);
9
+ return r ? { reasoning: r } : {};
10
+ }
11
+ return opts.lowReasoning === false ? {} : { reasoning: { effort: 'low', exclude: true } };
12
+ };
6
13
  return {
7
14
  name: 'openrouter',
8
15
  vision: true,
@@ -17,9 +24,12 @@ export function openrouter(opts = {}) {
17
24
  },
18
25
  body: JSON.stringify({
19
26
  model: req.model,
27
+ usage: { include: true }, // asks OpenRouter to report what the call cost
20
28
  ...(req.temperature === undefined ? {} : { temperature: req.temperature }),
21
29
  max_tokens: req.maxTokens,
22
- ...(opts.lowReasoning === false ? {} : { reasoning: { effort: 'low', exclude: true } }),
30
+ ...reasoningFor(req.model),
31
+ // Only providers that do not keep or train on prompts. Many free models cannot meet this, so the request fails and the next model is tried.
32
+ ...(req.privacy === 'strict' ? { provider: { data_collection: 'deny' } } : {}),
23
33
  messages: [...(req.system ? [{ role: 'system', content: req.system }] : []), ...req.messages.map(wire)],
24
34
  }),
25
35
  signal: req.signal,
@@ -29,7 +39,7 @@ export function openrouter(opts = {}) {
29
39
  const data = (await res.json());
30
40
  return {
31
41
  text: data.choices?.[0]?.message?.content ?? '',
32
- usage: data.usage ? { inputTokens: data.usage.prompt_tokens ?? 0, outputTokens: data.usage.completion_tokens ?? 0 } : undefined,
42
+ usage: data.usage ? { inputTokens: data.usage.prompt_tokens ?? 0, outputTokens: data.usage.completion_tokens ?? 0, ...(typeof data.usage.cost === 'number' ? { costUsd: data.usage.cost } : {}) } : undefined,
33
43
  };
34
44
  },
35
45
  };
package/dist/stats.js CHANGED
@@ -8,6 +8,8 @@ export function createStats(opts = {}) {
8
8
  let state = {};
9
9
  return {
10
10
  record(e) {
11
+ if (e.outcome === 'skipped')
12
+ return; // not tried, so nothing to count
11
13
  const k = key(e.provider, e.model);
12
14
  const list = (state[k] ??= []);
13
15
  list.push({ ok: e.outcome === 'ok', ms: e.ms, at: now() });
@@ -0,0 +1,43 @@
1
+ import type { CatalogModel } from './catalog.js';
2
+ /** What may be used, and what may be added by itself. There is no vulnerability feed for hosted models,
3
+ * so this does not claim one. It checks what can really be checked, from what providers publish in
4
+ * their model lists and what the app decides:
5
+ *
6
+ * - who made it: a model found by discovery is only used if its publisher is on a list of well-known
7
+ * labs (the app's own curated lists are its own decision and are not held to this);
8
+ * - what happens to the prompt: a model its provider says is trained on, or keeps prompts longer than
9
+ * allowed, is refused (Requesty publishes both for every model);
10
+ * - that it is not about to disappear: a model with an expiry date within a week is dropped;
11
+ * - an explicit block list. */
12
+ /** Well-known labs. A discovered model from anyone else is not added by itself. */
13
+ export declare const DEFAULT_PUBLISHERS: string[];
14
+ export interface TrustPolicy {
15
+ /** Who a discovered model may come from. Default: DEFAULT_PUBLISHERS. 'any' turns the check off. */
16
+ publishers?: string[] | 'any';
17
+ /** Never use these: exact model ids, or a publisher followed by a slash ("shady-lab/"). Applies to every model, curated or discovered. */
18
+ block?: string[];
19
+ /** Refuse a model its provider says is used for training. Where the provider does not say, a discovered model is refused and a curated one is allowed. */
20
+ requireNoTraining?: boolean;
21
+ /** Refuse a model that keeps prompts longer than this. Unknown is treated like requireNoTraining treats it. */
22
+ maxRetentionDays?: number;
23
+ /** Drop a model that stops being offered within this many days. Default 7. */
24
+ expiringWithinDays?: number;
25
+ }
26
+ export interface VetContext {
27
+ /** Found by discovery, not named by the app. */
28
+ discovered: boolean;
29
+ /** Treat unknown privacy facts as a refusal even for a curated model (a call marked private). */
30
+ strict?: boolean;
31
+ now: number;
32
+ }
33
+ export type Verdict = {
34
+ ok: true;
35
+ } | {
36
+ ok: false;
37
+ reason: 'blocked' | 'untrusted-publisher' | 'trains-on-data' | 'unknown-data-policy' | 'retention' | 'expiring';
38
+ };
39
+ export declare const publisherOf: (m: {
40
+ id: string;
41
+ publisher?: string;
42
+ }) => string;
43
+ export declare function vet(m: CatalogModel, policy: TrustPolicy | undefined, ctx: VetContext): Verdict;
package/dist/trust.js ADDED
@@ -0,0 +1,42 @@
1
+ /** What may be used, and what may be added by itself. There is no vulnerability feed for hosted models,
2
+ * so this does not claim one. It checks what can really be checked, from what providers publish in
3
+ * their model lists and what the app decides:
4
+ *
5
+ * - who made it: a model found by discovery is only used if its publisher is on a list of well-known
6
+ * labs (the app's own curated lists are its own decision and are not held to this);
7
+ * - what happens to the prompt: a model its provider says is trained on, or keeps prompts longer than
8
+ * allowed, is refused (Requesty publishes both for every model);
9
+ * - that it is not about to disappear: a model with an expiry date within a week is dropped;
10
+ * - an explicit block list. */
11
+ /** Well-known labs. A discovered model from anyone else is not added by itself. */
12
+ export const DEFAULT_PUBLISHERS = ['anthropic', 'google', 'openai', 'meta-llama', 'mistralai', 'nvidia', 'qwen', 'deepseek', 'microsoft', 'cohere', 'x-ai', 'amazon'];
13
+ /** The same lab goes by different names in different lists (Requesty says "mistral", OpenRouter "mistralai"; LLM API says "gemini-flash"). */
14
+ const ALIASES = { mistral: 'mistralai', meta: 'meta-llama', xai: 'x-ai', 'x.ai': 'x-ai', claude: 'anthropic', gemini: 'google', 'gemini-flash': 'google', 'gemini-pro': 'google', gemma: 'google', gpt: 'openai' };
15
+ export const publisherOf = (m) => { const raw = (m.publisher ?? m.id.split('/')[0]).toLowerCase(); return ALIASES[raw] ?? raw; };
16
+ export function vet(m, policy, ctx) {
17
+ const p = policy ?? {};
18
+ const pub = publisherOf(m);
19
+ if ((p.block ?? []).some((b) => (b.endsWith('/') ? m.id.toLowerCase().startsWith(b.toLowerCase()) || pub === b.slice(0, -1).toLowerCase() : m.id === b)))
20
+ return { ok: false, reason: 'blocked' };
21
+ if (m.expiration_date) {
22
+ const at = Date.parse(m.expiration_date);
23
+ if (Number.isFinite(at) && at - ctx.now < (p.expiringWithinDays ?? 7) * 86_400_000)
24
+ return { ok: false, reason: 'expiring' };
25
+ }
26
+ const unknownRefused = ctx.discovered || ctx.strict;
27
+ if (p.requireNoTraining) {
28
+ if (m.data_used_for_training === true)
29
+ return { ok: false, reason: 'trains-on-data' };
30
+ if (m.data_used_for_training === undefined && unknownRefused)
31
+ return { ok: false, reason: 'unknown-data-policy' };
32
+ }
33
+ if (p.maxRetentionDays !== undefined) {
34
+ if (m.data_retention_days !== undefined && m.data_retention_days > p.maxRetentionDays)
35
+ return { ok: false, reason: 'retention' };
36
+ if (m.data_retention_days === undefined && unknownRefused)
37
+ return { ok: false, reason: 'unknown-data-policy' };
38
+ }
39
+ if (ctx.discovered && p.publishers !== 'any' && !(p.publishers ?? DEFAULT_PUBLISHERS).map((x) => x.toLowerCase()).includes(pub))
40
+ return { ok: false, reason: 'untrusted-publisher' };
41
+ return { ok: true };
42
+ }
package/dist/types.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { CatalogModel } from './catalog.js';
1
2
  export type Tier = 'fast' | 'strong' | 'vision';
2
3
  export type ContentPart = {
3
4
  type: 'text';
@@ -13,6 +14,8 @@ export interface Message {
13
14
  export interface Usage {
14
15
  inputTokens: number;
15
16
  outputTokens: number;
17
+ /** What the provider charged for this call, in US dollars, when it says (OpenRouter does). */
18
+ costUsd?: number;
16
19
  }
17
20
  /** What a provider adapter is asked to do: one model, one request. */
18
21
  export interface ProviderRequest {
@@ -23,6 +26,8 @@ export interface ProviderRequest {
23
26
  /** Left out when the caller did not set one, so the provider's own default applies. */
24
27
  temperature?: number;
25
28
  apiKey: string;
29
+ /** 'strict': the prompt must not be kept or used for training. A provider that can enforce it does (OpenRouter); the rest rely on Lodestone choosing only models whose list says so. */
30
+ privacy?: 'strict';
26
31
  signal: AbortSignal;
27
32
  }
28
33
  export interface ProviderReply {
@@ -34,6 +39,8 @@ export interface Provider {
34
39
  /** Can this provider read images? */
35
40
  vision: boolean;
36
41
  call(req: ProviderRequest): Promise<ProviderReply>;
42
+ /** The models the provider offers right now, with price and what it does with prompts where it says. Lets Lodestone drop a model that has gone and find others. */
43
+ listModels?(apiKey: string, signal?: AbortSignal): Promise<CatalogModel[] | null>;
37
44
  }
38
45
  /** Where Lodestone keeps the model catalogue and cached answers. Anything that can
39
46
  * get and set JSON by key will do: Netlify Blobs, Redis, a SQLite table, a Map. */
@@ -0,0 +1,26 @@
1
+ // Redundancy: OpenRouter first, then two other gateways and a free tier, each with its own key, so one
2
+ // provider's outage does not take the tool down. Discovery keeps each list alive and keeps it short.
3
+ import { createLodestone, groq, llmapi, requesty } from '@extrafemi-ai/lodestone';
4
+
5
+ const CHEAP = { maxPromptUsdPerMTok: 1, maxCompletionUsdPerMTok: 5 };
6
+
7
+ export const ai = createLodestone({
8
+ openrouter: { apiKey: process.env.OPENROUTER_API_KEY, allowPaid: true, paidFirst: true, paidModels: ['anthropic/claude-haiku-5.5'] },
9
+ fallbacks: [
10
+ // Model ids are each gateway's own. Models a gateway stops listing are dropped, and if the list is short it is
11
+ // topped up (never above 3) with trusted-lab models under the price limit.
12
+ { provider: requesty(), apiKey: process.env.REQUESTY_API_KEY ?? '', models: ['bedrock/claude-haiku-5-5', 'vertex/gemini-3.8-flash'], discover: { fill: CHEAP, max: 3 } },
13
+ { provider: llmapi(), apiKey: process.env.LLMAPI_API_KEY ?? '', models: ['claude-haiku-5-5', 'gemini-3.8-flash'], discover: { fill: CHEAP, max: 3 } },
14
+ // A free tier costs nothing, so it is never counted against a spend limit.
15
+ { provider: groq(), apiKey: process.env.GROQ_API_KEY ?? '', models: ['llama-3.3-70b-versatile'], free: true },
16
+ ], // a fallback with no key is skipped, so only the ones you have keys for are used
17
+ trust: {
18
+ requireNoTraining: true, // refuse a model its provider says is trained on (Requesty publishes this for every model)
19
+ maxRetentionDays: 30,
20
+ block: [], // exact model ids, or a lab followed by a slash
21
+ },
22
+ });
23
+
24
+ // For something sensitive, like a CV: OpenRouter is told to use only providers that do not keep or train on it,
25
+ // and other models are used only if their provider's list says the same.
26
+ export const summariseCv = (cv: string) => ai.json({ prompt: `Summarise:\n${cv}`, private: true });
@@ -0,0 +1,13 @@
1
+ // Run once a day. Saves the current model catalogues, so a withdrawn or retiring model is replaced
2
+ // without anyone editing a list, and says what it found. Reported as a failure (so your monitor
3
+ // notices) only when a catalogue cannot be read or a tier is left with fewer than two models.
4
+ import { ai } from './netlify-function.js';
5
+
6
+ export const config = { schedule: '0 4 * * *' };
7
+
8
+ export const handler = async () => {
9
+ const r = await ai.checkModels();
10
+ console.log(`models: ${r.catalogSize ?? 0} in the catalogue; withdrawn: ${r.withdrawn?.join(', ') || 'none'}; retiring soon: ${r.expiring?.join(', ') || 'none'}`);
11
+ for (const [name, p] of Object.entries(r.providers ?? {})) console.log(`${name}: ${p.error ?? `${p.models} models; withdrawn: ${p.withdrawn.join(', ') || 'none'}; retiring: ${p.expiring.join(', ') || 'none'}`}`);
12
+ return { statusCode: 200, body: JSON.stringify(r) }; // body.ok === false is what a monitor should alert on
13
+ };
@@ -0,0 +1,35 @@
1
+ // A Netlify function that asks a model for JSON, written so it keeps working when a model is
2
+ // withdrawn, slow or rate-limited. Needs OPENROUTER_API_KEY (and, for a second route, GROQ_API_KEY).
3
+ import { createHealth, createLodestone, explain, groq, LodestoneError } from '@extrafemi-ai/lodestone';
4
+ import { getStore } from '@netlify/blobs';
5
+ import type { Handler } from '@netlify/functions';
6
+
7
+ // Where Lodestone keeps what it learns: the model catalogue, which models are failing, saved answers.
8
+ // Blob keys cannot contain colons, so they are made simple.
9
+ const blobs = getStore('lodestone');
10
+ const simple = (k: string) => k.replace(/[^a-z0-9._-]/gi, '-');
11
+ export const store = { get: (k: string) => blobs.get(simple(k), { type: 'json' }), set: (k: string, v: unknown) => blobs.setJSON(simple(k), v) };
12
+
13
+ export const ai = createLodestone({
14
+ openrouter: { apiKey: process.env.OPENROUTER_API_KEY },
15
+ fallbacks: process.env.GROQ_API_KEY ? [{ provider: groq(), apiKey: process.env.GROQ_API_KEY, models: ['llama-3.3-70b-versatile'], free: true }] : [],
16
+ store,
17
+ health: createHealth({ store }), // a model that keeps failing is skipped by every function until it recovers
18
+ budgetMs: 24_000, // Netlify cuts a function off at 30 seconds
19
+ });
20
+
21
+ interface Summary { title: string; points: string[] }
22
+ const isSummary = (v: unknown): v is Summary => typeof v === 'object' && v !== null && typeof (v as Summary).title === 'string' && Array.isArray((v as Summary).points);
23
+
24
+ export const handler: Handler = async (event) => {
25
+ try {
26
+ const { text } = JSON.parse(event.body ?? '{}') as { text?: string };
27
+ if (!text) return { statusCode: 400, body: JSON.stringify({ error: 'text is required' }) };
28
+ // A model whose answer is not valid JSON of this shape is skipped for the next one.
29
+ const r = await ai.json<Summary>({ prompt: `Summarise as JSON {"title": string, "points": string[]}:\n\n${text}`, tier: 'fast', validate: isSummary });
30
+ return { statusCode: 200, body: JSON.stringify(r.data) };
31
+ } catch (err) {
32
+ // A sentence a person can be shown, not a stack trace.
33
+ return { statusCode: err instanceof LodestoneError && err.kind === 'rate_limit' ? 429 : 502, body: JSON.stringify({ error: explain(err, { product: 'MyApp' }) }) };
34
+ }
35
+ };
@@ -0,0 +1,7 @@
1
+ // Just enough of the Netlify packages for the examples to be type-checked here without installing them.
2
+ declare module '@netlify/blobs' {
3
+ export function getStore(name: string): { get(key: string, opts: { type: 'json' }): Promise<unknown>; setJSON(key: string, value: unknown): Promise<void> };
4
+ }
5
+ declare module '@netlify/functions' {
6
+ export type Handler = (event: { httpMethod: string; headers: Record<string, string | undefined>; body: string | null }) => Promise<{ statusCode: number; headers?: Record<string, string>; body: string }>;
7
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@extrafemi-ai/lodestone",
3
- "version": "0.3.1",
4
- "description": "Calls AI models so your tool keeps working when a model is withdrawn, slow or rate-limited.",
3
+ "version": "0.5.0",
4
+ "description": "Calls AI models so your tool keeps working when a model is withdrawn, slow, rate-limited or down: failover across providers, self-updating model lists, spend limits.",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
@@ -24,7 +24,10 @@
24
24
  "files": [
25
25
  "dist",
26
26
  "docs",
27
+ "examples",
27
28
  "README.md",
29
+ "CHANGELOG.md",
30
+ "SECURITY.md",
28
31
  "LICENSE"
29
32
  ],
30
33
  "sideEffects": false,
@@ -35,7 +38,8 @@
35
38
  "build": "tsc -p tsconfig.build.json",
36
39
  "typecheck": "tsc --noEmit",
37
40
  "test": "vitest run",
38
- "prepublishOnly": "npm run typecheck && npm test && npm run build"
41
+ "prepublishOnly": "npm run typecheck && npm run typecheck:examples && npm test && npm run build",
42
+ "typecheck:examples": "tsc -p tsconfig.examples.json"
39
43
  },
40
44
  "devDependencies": {
41
45
  "@types/node": "^22.10.0",
@@ -44,12 +48,17 @@
44
48
  },
45
49
  "keywords": [
46
50
  "ai",
47
- "llm",
48
- "openrouter",
49
51
  "anthropic",
50
- "gemini",
52
+ "circuit-breaker",
53
+ "failover",
51
54
  "fallback",
52
- "model-routing"
55
+ "gemini",
56
+ "groq",
57
+ "llm",
58
+ "llm-gateway",
59
+ "model-routing",
60
+ "openrouter",
61
+ "requesty"
53
62
  ],
54
63
  "publishConfig": {
55
64
  "access": "public",