@extrafemi-ai/lodestone 0.0.0-stage → 0.1.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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Extrafemi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,92 @@
1
- # Temporary Holding Version
1
+ # Lodestone
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Calls AI models so your tool keeps working when a model is withdrawn, slow or rate-limited.
4
+
5
+ Free and cheap models come and go. A hard-coded model id breaks without warning, one slow model can use your whole time limit, and "429" can mean four different things that need four different messages. Lodestone handles those so each tool doesn't have to.
6
+
7
+ - **Replaces withdrawn models by itself.** Your lists are preferences. They are checked against OpenRouter's live catalogue, and any model that has gone is swapped for a current one of the same kind.
8
+ - **Keeps inside a time budget.** Each model gets a slice of it. A slow or failing model is skipped for the next, so a function never hits its gateway limit with an unreadable error.
9
+ - **Falls back across providers.** OpenRouter's free models, then a low-cost paid model, then Anthropic or Google on their own keys.
10
+ - **Explains failures in plain words.** A daily limit, a per-minute limit, a busy upstream provider, a bad key and a slow model are different errors with different advice.
11
+ - **Checks the answer.** `json()` skips a model whose answer isn't valid JSON, or doesn't pass your validator.
12
+ - **Bring your own key.** A caller's key replaces the platform's and allows the paid fallback, without touching the platform's budget.
13
+ - **No dependencies.** Plain `fetch`. Node 20+.
14
+
15
+ ## Use
16
+
17
+ ```ts
18
+ import { anthropic, createLodestone, explain } from '@extrafemi-ai/lodestone';
19
+
20
+ const ai = createLodestone({
21
+ openrouter: { apiKey: process.env.OPENROUTER_API_KEY },
22
+ fallbacks: [
23
+ { provider: anthropic(), apiKey: process.env.ANTHROPIC_API_KEY!, models: ['claude-haiku-5-5'] },
24
+ ],
25
+ profiles: {
26
+ 'extract-job': { tier: 'fast', maxTokens: 1500 },
27
+ 'write-cv': { tier: 'strong', maxTokens: 3500, temperature: 0.4 },
28
+ },
29
+ });
30
+
31
+ try {
32
+ const { data } = await ai.json<Job>({ task: 'extract-job', prompt, validate: isJob });
33
+ } catch (err) {
34
+ // A message you can show a person.
35
+ return explain(err, { product: 'MyApp', settingsHint: 'in Settings' });
36
+ }
37
+ ```
38
+
39
+ `import { anthropic, google, openrouter, mock } from '@extrafemi-ai/lodestone'` for the provider adapters.
40
+
41
+ ### Tiers
42
+
43
+ `fast` (extraction, classification), `strong` (writing, judgement) and `vision` (reading images). A call picks one through its `task` profile or `tier`, and uses `vision` by itself when the messages contain an image.
44
+
45
+ ### Phases
46
+
47
+ For each call, in order, until one answers:
48
+
49
+ 1. OpenRouter's free models for the tier (current ones, per the catalogue).
50
+ 2. A low-cost paid OpenRouter model, only if the caller supplied their own key or you set `allowPaid`. With no credit OpenRouter refuses it and nothing is spent.
51
+ 3. Each `fallbacks` provider, with its own key.
52
+
53
+ When a later phase exists, the free models get a short turn (9 s in all by default), so there is always time left for it. The whole call stays inside `budgetMs` (24 s by default, under a 30 s gateway limit).
54
+
55
+ ### Keeping the catalogue fresh
56
+
57
+ Give it somewhere to keep the catalogue (anything that can get and set JSON by key; the default is memory), and run `checkModels()` once a day:
58
+
59
+ ```ts
60
+ const ai = createLodestone({ store: { get: (k) => blobs.get(k, { type: 'json' }), set: (k, v) => blobs.setJSON(k, v) }, /* ... */ });
61
+
62
+ // daily
63
+ const { ok, withdrawn, shortTiers } = await ai.checkModels();
64
+ ```
65
+
66
+ `withdrawn` lists preferred models that have gone. That is harmless, they are already replaced. `ok` is false only when the catalogue can't be read or a tier is left with fewer than two real models. Without a daily run, a request that finds the saved catalogue over a day old refreshes it in the background.
67
+
68
+ ### Caching
69
+
70
+ Pass `cacheKey` for a pure, repeatable task (for example a hash of a job page) and the answer is saved in the store and reused for `cacheTtlMs` (a day by default). Failures are never cached.
71
+
72
+ ### Observing it
73
+
74
+ `onAttempt` is called after every model attempt with the provider, model, phase, outcome, status and time. It never receives prompts or answers. Lodestone doesn't log prompts or answers anywhere.
75
+
76
+ ## Errors
77
+
78
+ `complete()` and `json()` throw a `LodestoneError` whose `kind` is one of `auth`, `rate_limit`, `slow`, `credit`, `withdrawn`, `unavailable`, `bad_output`, `not_configured` or `other`. `detail` carries the HTTP status and, for rate limits, which kind it was. `explain(err, { product, settingsHint })` turns any of them into a message for a person.
79
+
80
+ ## Develop
81
+
82
+ ```bash
83
+ npm install
84
+ npm test
85
+ npm run build
86
+ ```
87
+
88
+ Releases: bump `version` in `package.json`, then push a tag (`git tag v0.1.0 && git push --tags`). The release workflow tests, builds and publishes to npm with provenance. It needs an `NPM_TOKEN` secret on the repository.
89
+
90
+ ## Licence
91
+
92
+ MIT
@@ -0,0 +1,30 @@
1
+ import type { KeyValueStore, Tier } from './types.js';
2
+ /** Works out which models to ask for from OpenRouter's own catalogue, so a model
3
+ * that has been withdrawn is dropped and a current one takes its place without
4
+ * anyone editing a list. The lists you pass in are preferences: they are used
5
+ * while they exist. What is left over is filled from the catalogue. */
6
+ export interface CatalogModel {
7
+ id: string;
8
+ context_length?: number;
9
+ architecture?: {
10
+ input_modalities?: string[];
11
+ output_modalities?: string[];
12
+ };
13
+ pricing?: {
14
+ prompt?: string | number;
15
+ completion?: string | number;
16
+ };
17
+ }
18
+ export declare const ROUTER = "openrouter/free";
19
+ export declare function eligible(catalog: CatalogModel[], tier: Tier): CatalogModel[];
20
+ /** The ids to send, best first: preferred models that still exist, then the best
21
+ * others by tier, then the router; at most three. With no catalogue at all, the
22
+ * preferences are returned as they are. */
23
+ export declare function pickModels(tier: Tier, catalog: CatalogModel[] | null, preferences: string[]): string[];
24
+ export interface Catalog {
25
+ /** Fetches OpenRouter's catalogue and saves it. Returns null if it can't be read. */
26
+ refresh(): Promise<CatalogModel[] | null>;
27
+ /** The saved catalogue (six-hour copy in memory; refreshed in the background if over a day old). Never waits on the network unless nothing is saved. */
28
+ load(): Promise<CatalogModel[] | null>;
29
+ }
30
+ export declare function createCatalog(store: KeyValueStore, fetchImpl: typeof fetch, now?: () => number): Catalog;
@@ -0,0 +1,69 @@
1
+ export const ROUTER = 'openrouter/free';
2
+ const MAX_ENTRIES = 3;
3
+ const isFree = (m) => m.id.endsWith(':free') || (Number(m.pricing?.prompt) === 0 && Number(m.pricing?.completion) === 0 && m.id !== ROUTER);
4
+ const textOut = (m) => (m.architecture?.output_modalities ?? ['text']).join() === 'text';
5
+ const takesImages = (m) => (m.architecture?.input_modalities ?? []).includes('image');
6
+ // Safety classifiers, audio and music models, code-only models and embedders are not for writing or reading text.
7
+ const EXCLUDE = /safety|guard|moderation|lyria|embed|rerank|tts|whisper|code|coder|preview-audio|ocr/i;
8
+ /** "550b" or "26b" in an id: bigger is the stronger pick. */
9
+ const size = (id) => Number(id.match(/(\d{2,4})b\b/i)?.[1] ?? 0);
10
+ const LIGHT = /lightning|flash|mini|small|nano|lite|fast/i;
11
+ export function eligible(catalog, tier) {
12
+ return catalog.filter((m) => isFree(m) && textOut(m) && (m.context_length ?? 0) >= 32_000 && !EXCLUDE.test(m.id) && (tier !== 'vision' || takesImages(m)));
13
+ }
14
+ /** The ids to send, best first: preferred models that still exist, then the best
15
+ * others by tier, then the router; at most three. With no catalogue at all, the
16
+ * preferences are returned as they are. */
17
+ export function pickModels(tier, catalog, preferences) {
18
+ if (!catalog || catalog.length === 0)
19
+ return preferences.slice(0, MAX_ENTRIES);
20
+ const ok = new Map(eligible(catalog, tier).map((m) => [m.id, m]));
21
+ const out = preferences.filter((id) => id !== ROUTER && ok.has(id));
22
+ const rest = [...ok.values()]
23
+ .filter((m) => !out.includes(m.id))
24
+ .sort((a, b) => (tier === 'strong' ? size(b.id) - size(a.id) : tier === 'fast' ? Number(LIGHT.test(b.id)) - Number(LIGHT.test(a.id)) || size(a.id) - size(b.id) : size(b.id) - size(a.id)) || (b.context_length ?? 0) - (a.context_length ?? 0));
25
+ for (const m of rest) {
26
+ if (out.length >= MAX_ENTRIES - 1)
27
+ break;
28
+ out.push(m.id);
29
+ }
30
+ return [...out.slice(0, MAX_ENTRIES - 1), ROUTER];
31
+ }
32
+ const KEY = 'lodestone:model-catalog';
33
+ const MEMORY_MS = 6 * 3_600_000;
34
+ const STALE_MS = 24 * 3_600_000;
35
+ export function createCatalog(store, fetchImpl, now = Date.now) {
36
+ let memory = null;
37
+ const refresh = async () => {
38
+ const res = await fetchImpl('https://openrouter.ai/api/v1/models', { signal: AbortSignal.timeout(8_000) });
39
+ if (!res.ok)
40
+ return null;
41
+ const models = ((await res.json()).data ?? []).map((m) => ({
42
+ id: m.id,
43
+ context_length: m.context_length,
44
+ architecture: m.architecture && { input_modalities: m.architecture.input_modalities, output_modalities: m.architecture.output_modalities },
45
+ pricing: m.pricing && { prompt: m.pricing.prompt, completion: m.pricing.completion },
46
+ }));
47
+ if (models.length === 0)
48
+ return null;
49
+ await store.set(KEY, { at: new Date(now()).toISOString(), models }).catch(() => { });
50
+ memory = { at: now(), models };
51
+ return models;
52
+ };
53
+ const load = async () => {
54
+ if (memory && now() - memory.at < MEMORY_MS)
55
+ return memory.models;
56
+ try {
57
+ const saved = (await store.get(KEY));
58
+ if (saved?.models?.length) {
59
+ memory = { at: now(), models: saved.models };
60
+ if (now() - Date.parse(saved.at) > STALE_MS)
61
+ refresh().catch(() => { });
62
+ return saved.models;
63
+ }
64
+ }
65
+ catch { /* an unreadable store is the same as an empty one */ }
66
+ return null;
67
+ };
68
+ return { refresh, load };
69
+ }
@@ -0,0 +1,41 @@
1
+ import type { RateLimitReading } from './rateLimit.js';
2
+ /** A provider answered with an error status (or the request itself failed: status 599). */
3
+ export declare class ProviderError extends Error {
4
+ status: number;
5
+ body: string;
6
+ constructor(status: number, body: string);
7
+ }
8
+ export type FailureKind =
9
+ /** The key was rejected. Another model on the same key will not differ. */
10
+ 'auth'
11
+ /** Rate limited. See `rateLimit` for which kind. */
12
+ | 'rate_limit'
13
+ /** Every attempt timed out. */
14
+ | 'slow'
15
+ /** The account has no credit for the paid fallback. */
16
+ | 'credit'
17
+ /** Models the provider no longer has (404). */
18
+ | 'withdrawn'
19
+ /** The provider returned a server error. */
20
+ | 'unavailable'
21
+ /** A model answered but the answer was not usable (empty, not valid JSON, failed validation). */
22
+ | 'bad_output'
23
+ /** No provider has a key. */
24
+ | 'not_configured' | 'other';
25
+ /** Thrown when no model could answer. `kind` says why, so the caller can decide what
26
+ * to tell the person; `explain()` has a ready-made plain-language message. */
27
+ export declare class LodestoneError extends Error {
28
+ kind: FailureKind;
29
+ detail: {
30
+ status?: number;
31
+ rateLimit?: RateLimitReading;
32
+ ownKey?: boolean;
33
+ needsCredit?: boolean;
34
+ };
35
+ constructor(kind: FailureKind, detail?: {
36
+ status?: number;
37
+ rateLimit?: RateLimitReading;
38
+ ownKey?: boolean;
39
+ needsCredit?: boolean;
40
+ });
41
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,23 @@
1
+ /** A provider answered with an error status (or the request itself failed: status 599). */
2
+ export class ProviderError extends Error {
3
+ status;
4
+ body;
5
+ constructor(status, body) {
6
+ super(`provider error ${status}`);
7
+ this.status = status;
8
+ this.body = body;
9
+ this.name = 'ProviderError';
10
+ }
11
+ }
12
+ /** Thrown when no model could answer. `kind` says why, so the caller can decide what
13
+ * to tell the person; `explain()` has a ready-made plain-language message. */
14
+ export class LodestoneError extends Error {
15
+ kind;
16
+ detail;
17
+ constructor(kind, detail = {}) {
18
+ super(`no model could answer: ${kind}`);
19
+ this.kind = kind;
20
+ this.detail = detail;
21
+ this.name = 'LodestoneError';
22
+ }
23
+ }
@@ -0,0 +1,9 @@
1
+ export interface ExplainOptions {
2
+ /** What to call the product in messages. Default: "the app". */
3
+ product?: string;
4
+ /** Where a person can add their own key, e.g. "in Settings". Omit if there is none. */
5
+ settingsHint?: string;
6
+ }
7
+ /** A plain-language message a person can be shown for a failure. Written for the
8
+ * person, not the developer: it says what happened and what to try. */
9
+ export declare function explain(err: unknown, opts?: ExplainOptions): string;
@@ -0,0 +1,50 @@
1
+ import { LodestoneError } from './errors.js';
2
+ /** A plain-language message a person can be shown for a failure. Written for the
3
+ * person, not the developer: it says what happened and what to try. */
4
+ export function explain(err, opts = {}) {
5
+ const product = opts.product ?? 'the app';
6
+ const settings = opts.settingsHint ? ` ${opts.settingsHint}` : '';
7
+ if (!(err instanceof LodestoneError))
8
+ return 'Something went wrong talking to the AI provider. Try again in a moment.';
9
+ const { kind, detail } = err;
10
+ const own = Boolean(detail.ownKey);
11
+ switch (kind) {
12
+ case 'slow':
13
+ return 'The AI is slow right now and did not answer in time. Try again in a minute.';
14
+ case 'auth':
15
+ return own
16
+ ? `Your OpenRouter key was rejected. Double-check it${settings}, or remove it to use ${product}'s shared AI.`
17
+ : `${product}'s AI provider isn't configured correctly right now. This isn't something you can fix. Try again shortly.`;
18
+ case 'rate_limit': {
19
+ const r = detail.rateLimit;
20
+ const when = r?.resetAt ? ` It resets around ${r.resetAt.toUTCString().slice(17, 22)} UTC.` : '';
21
+ const credit = detail.needsCredit && own ? ' If you add a little credit (even $1) on openrouter.ai, a very low-cost model will be used on your key whenever the free ones are busy.' : '';
22
+ switch (r?.kind) {
23
+ case 'daily':
24
+ return (own
25
+ ? `Your OpenRouter account has used its free-model allowance for today${r.limit ? ` (${r.limit} requests)` : ''}.${when} Adding a little credit on openrouter.ai raises it a lot, or try again tomorrow.`
26
+ : `${product}'s shared AI budget for today is used up. Try again after midnight UTC${opts.settingsHint ? `, or add your own OpenRouter key${settings}` : ''}.`) + credit;
27
+ case 'minute':
28
+ return 'Too many AI requests in a minute. Wait about a minute and try again.' + credit;
29
+ case 'upstream':
30
+ return 'The free AI models are busy right now: the provider behind them is limiting requests, not your key. Try again in a minute.' + credit;
31
+ default:
32
+ return (own
33
+ ? 'OpenRouter is limiting requests for your key right now. This is often the free models being busy rather than your own limit, so try again in a minute.'
34
+ : `${product}'s shared AI budget is under heavy load right now. Try again shortly${opts.settingsHint ? `, or add your own OpenRouter key${settings} to skip the wait` : ''}.`) + credit;
35
+ }
36
+ }
37
+ case 'withdrawn':
38
+ return `The AI models ${product} uses just changed on the provider's side. Try again in a few minutes.`;
39
+ case 'unavailable':
40
+ return `The AI provider is having issues right now, not ${product}. Try again in a few minutes.`;
41
+ case 'bad_output':
42
+ return "The AI gave back something that couldn't be read. Try again; it usually works on a second attempt.";
43
+ case 'credit':
44
+ return 'The AI account has no credit for the backup model. Add a little credit and try again.';
45
+ case 'not_configured':
46
+ return `${product}'s AI isn't set up yet.`;
47
+ default:
48
+ return 'Something went wrong talking to the AI provider. Try again in a moment.';
49
+ }
50
+ }
@@ -0,0 +1,18 @@
1
+ export { createLodestone } from './lodestone.js';
2
+ export type { Lodestone, LodestoneConfig, CompleteOptions, CompleteResult, Profile, FallbackConfig, AttemptEvent } from './lodestone.js';
3
+ export { LodestoneError, ProviderError } from './errors.js';
4
+ export type { FailureKind } from './errors.js';
5
+ export { explain } from './explain.js';
6
+ export type { ExplainOptions } from './explain.js';
7
+ export { readRateLimit } from './rateLimit.js';
8
+ export type { RateLimitKind, RateLimitReading } from './rateLimit.js';
9
+ export { pickModels, eligible, ROUTER } from './catalog.js';
10
+ export type { CatalogModel } from './catalog.js';
11
+ export { DEFAULT_MODELS, DEFAULT_PAID_MODELS } from './models.js';
12
+ export { tryParseJson } from './json.js';
13
+ export { memoryStore } from './store.js';
14
+ export { openrouter } from './providers/openrouter.js';
15
+ export { anthropic } from './providers/anthropic.js';
16
+ export { google } from './providers/google.js';
17
+ export { mock } from './providers/mock.js';
18
+ export type { Tier, Message, ContentPart, Provider, ProviderRequest, ProviderReply, KeyValueStore, Usage } from './types.js';
package/dist/index.js ADDED
@@ -0,0 +1,12 @@
1
+ export { createLodestone } from './lodestone.js';
2
+ export { LodestoneError, ProviderError } from './errors.js';
3
+ export { explain } from './explain.js';
4
+ export { readRateLimit } from './rateLimit.js';
5
+ export { pickModels, eligible, ROUTER } from './catalog.js';
6
+ export { DEFAULT_MODELS, DEFAULT_PAID_MODELS } from './models.js';
7
+ export { tryParseJson } from './json.js';
8
+ export { memoryStore } from './store.js';
9
+ export { openrouter } from './providers/openrouter.js';
10
+ export { anthropic } from './providers/anthropic.js';
11
+ export { google } from './providers/google.js';
12
+ export { mock } from './providers/mock.js';
package/dist/json.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ /** Strips the ```json fences models like to wrap answers in, then parses. Returns
2
+ * undefined when it is not valid JSON. */
3
+ export declare function tryParseJson<T = unknown>(raw: string): T | undefined;
package/dist/json.js ADDED
@@ -0,0 +1,11 @@
1
+ /** Strips the ```json fences models like to wrap answers in, then parses. Returns
2
+ * undefined when it is not valid JSON. */
3
+ export function tryParseJson(raw) {
4
+ const cleaned = raw.trim().replace(/^```json/i, '').replace(/^```/, '').replace(/```$/, '').trim();
5
+ try {
6
+ return JSON.parse(cleaned);
7
+ }
8
+ catch {
9
+ return undefined;
10
+ }
11
+ }
@@ -0,0 +1,95 @@
1
+ import { type CatalogModel } from './catalog.js';
2
+ import type { KeyValueStore, Message, Provider, Tier, Usage } from './types.js';
3
+ export interface Profile {
4
+ tier: Tier;
5
+ maxTokens?: number;
6
+ temperature?: number;
7
+ }
8
+ export interface FallbackConfig {
9
+ provider: Provider;
10
+ apiKey: string;
11
+ /** Tried in order. */
12
+ models: string[];
13
+ }
14
+ export interface AttemptEvent {
15
+ provider: string;
16
+ model: string;
17
+ phase: 'free' | 'paid' | 'fallback';
18
+ outcome: 'ok' | 'timeout' | 'failed';
19
+ status?: number;
20
+ ms: number;
21
+ }
22
+ export interface LodestoneConfig {
23
+ openrouter?: {
24
+ /** The platform's key. A caller's own key (`apiKey` on a call) takes priority. */
25
+ apiKey?: string;
26
+ /** Use the paid models after the free ones fail, on the platform's key. A caller's own key always allows it. */
27
+ allowPaid?: boolean;
28
+ models?: Partial<Record<Tier, string[]>>;
29
+ paidModels?: string[];
30
+ /** Replace the OpenRouter adapter (tests, proxies). */
31
+ provider?: Provider;
32
+ };
33
+ /** Other providers, each with its own key, tried after OpenRouter has failed. */
34
+ fallbacks?: FallbackConfig[];
35
+ /** Named tasks, so calls say what they are doing and not which model to use. */
36
+ profiles?: Record<string, Profile>;
37
+ /** Where the model catalogue and cached answers are kept. Default: memory. */
38
+ store?: KeyValueStore;
39
+ /** Everything has to finish inside this. Default 24 000 ms, under a 30 s gateway limit. */
40
+ budgetMs?: number;
41
+ /** Time limits for tuning and tests. */
42
+ timing?: {
43
+ freeSliceMs?: number;
44
+ freeSliceWithLaterMs?: number;
45
+ freePhaseWithLaterMs?: number;
46
+ minSliceMs?: number;
47
+ };
48
+ fetch?: typeof fetch;
49
+ now?: () => number;
50
+ /** Called after every model attempt: for logs and metrics. Never receives prompts or answers. */
51
+ onAttempt?: (e: AttemptEvent) => void;
52
+ }
53
+ export interface CompleteOptions {
54
+ /** A key in `profiles`. */
55
+ task?: string;
56
+ /** Overrides the profile's tier. Default: 'vision' if the messages contain an image, else 'fast'. */
57
+ tier?: Tier;
58
+ prompt?: string;
59
+ messages?: Message[];
60
+ system?: string;
61
+ maxTokens?: number;
62
+ temperature?: number;
63
+ /** The caller's own OpenRouter key (bring your own key). Used instead of the platform's, and allows the paid fallback. */
64
+ apiKey?: string;
65
+ /** An answer that fails this check counts as a failed attempt, and the next model is tried. */
66
+ accept?: (text: string) => boolean;
67
+ /** Same key, same answer: the answer is saved and reused. Only for pure, repeatable tasks. */
68
+ cacheKey?: string;
69
+ cacheTtlMs?: number;
70
+ }
71
+ export interface CompleteResult {
72
+ text: string;
73
+ provider: string;
74
+ model: string;
75
+ usage?: Usage;
76
+ cached?: boolean;
77
+ }
78
+ export declare function createLodestone(config?: LodestoneConfig): {
79
+ complete: (opts: CompleteOptions) => Promise<CompleteResult>;
80
+ json: <T = unknown>(opts: CompleteOptions & {
81
+ validate?: (value: unknown) => value is T;
82
+ }) => Promise<CompleteResult & {
83
+ data: T;
84
+ }>;
85
+ resolveModels: (tier: Tier) => Promise<string[]>;
86
+ refreshCatalog: () => Promise<CatalogModel[] | null>;
87
+ checkModels: () => Promise<{
88
+ ok: boolean;
89
+ error?: string;
90
+ catalogSize?: number;
91
+ withdrawn?: string[];
92
+ shortTiers?: Tier[];
93
+ }>;
94
+ };
95
+ export type Lodestone = ReturnType<typeof createLodestone>;
@@ -0,0 +1,194 @@
1
+ import { createCatalog, pickModels, ROUTER } from './catalog.js';
2
+ import { LodestoneError, ProviderError } from './errors.js';
3
+ import { tryParseJson } from './json.js';
4
+ import { DEFAULT_MODELS, DEFAULT_PAID_MODELS } from './models.js';
5
+ import { readRateLimit } from './rateLimit.js';
6
+ import { openrouter } from './providers/openrouter.js';
7
+ import { memoryStore } from './store.js';
8
+ const hasImage = (messages) => messages.some((m) => Array.isArray(m.content) && m.content.some((p) => p.type === 'image'));
9
+ export function createLodestone(config = {}) {
10
+ const budget = config.budgetMs ?? 24_000;
11
+ const t = {
12
+ freeSlice: config.timing?.freeSliceMs ?? 11_000,
13
+ freeSliceLater: config.timing?.freeSliceWithLaterMs ?? 5_000,
14
+ freePhaseLater: config.timing?.freePhaseWithLaterMs ?? 9_000,
15
+ minSlice: config.timing?.minSliceMs ?? 3_000,
16
+ };
17
+ const now = config.now ?? Date.now;
18
+ const store = config.store ?? memoryStore();
19
+ const fetchImpl = config.fetch ?? fetch;
20
+ const catalog = createCatalog(store, fetchImpl, now);
21
+ const router = config.openrouter?.provider ?? openrouter({ fetch: fetchImpl });
22
+ const prefs = { ...DEFAULT_MODELS, ...config.openrouter?.models };
23
+ const paidModels = config.openrouter?.paidModels ?? DEFAULT_PAID_MODELS;
24
+ const fallbacks = config.fallbacks ?? [];
25
+ /** The ids to send for a tier: preferences that still exist, plus current replacements. Never throws, never waits on the network. */
26
+ async function resolveModels(tier) {
27
+ try {
28
+ return pickModels(tier, await catalog.load(), prefs[tier]);
29
+ }
30
+ catch {
31
+ return prefs[tier];
32
+ }
33
+ }
34
+ async function complete(opts) {
35
+ const messages = opts.messages ?? (opts.prompt !== undefined ? [{ role: 'user', content: opts.prompt }] : []);
36
+ if (messages.length === 0)
37
+ throw new Error('complete() needs a prompt or messages');
38
+ const profile = opts.task ? config.profiles?.[opts.task] : undefined;
39
+ if (opts.task && !profile)
40
+ throw new Error(`Unknown task "${opts.task}"`);
41
+ const images = hasImage(messages);
42
+ const tier = opts.tier ?? profile?.tier ?? (images ? 'vision' : 'fast');
43
+ const maxTokens = opts.maxTokens ?? profile?.maxTokens ?? 3500;
44
+ const temperature = opts.temperature ?? profile?.temperature ?? 0.2;
45
+ const cacheSlot = opts.cacheKey ? `lodestone:cache:${opts.cacheKey}` : null;
46
+ if (cacheSlot) {
47
+ try {
48
+ const hit = (await store.get(cacheSlot));
49
+ if (hit?.text && now() - hit.at < (opts.cacheTtlMs ?? 24 * 3_600_000) && (!opts.accept || opts.accept(hit.text)))
50
+ return { text: hit.text, provider: hit.provider, model: hit.model, cached: true };
51
+ }
52
+ catch { /* a store that cannot be read is a cache miss */ }
53
+ }
54
+ const started = now();
55
+ const left = () => budget - (now() - started);
56
+ const orKey = opts.apiKey || config.openrouter?.apiKey;
57
+ const paidAllowed = Boolean(opts.apiKey) || Boolean(config.openrouter?.allowPaid);
58
+ const fbs = fallbacks.filter((f) => f.apiKey && (!images || f.provider.vision));
59
+ const paidAvailable = Boolean(orKey) && paidAllowed && paidModels.length > 0;
60
+ const later = paidAvailable || fbs.length > 0;
61
+ const freeEnds = later ? t.freePhaseLater : budget;
62
+ const freeLeft = () => Math.min(left(), freeEnds - (now() - started));
63
+ let attempted = false;
64
+ let last = null;
65
+ let rateLimited = null;
66
+ let authFailed = false;
67
+ let needsCredit = false;
68
+ const attempt = async (provider, apiKey, model, phase, ms) => {
69
+ attempted = true;
70
+ const at = now();
71
+ let out;
72
+ try {
73
+ const reply = await provider.call({ model, system: opts.system, messages, maxTokens, temperature, apiKey, signal: AbortSignal.timeout(ms) });
74
+ if (!reply.text.trim())
75
+ out = { kind: 'fail', status: 502, body: 'empty answer', unusable: true };
76
+ else if (opts.accept && !opts.accept(reply.text))
77
+ out = { kind: 'fail', status: 422, body: 'answer failed the check', unusable: true };
78
+ else
79
+ out = { kind: 'ok', reply };
80
+ }
81
+ catch (e) {
82
+ const name = e.name;
83
+ if (name === 'TimeoutError' || name === 'AbortError')
84
+ out = { kind: 'timeout' };
85
+ else if (e instanceof ProviderError)
86
+ out = { kind: 'fail', status: e.status, body: e.body };
87
+ else
88
+ out = { kind: 'fail', status: 599, body: e.message };
89
+ }
90
+ config.onAttempt?.({ provider: provider.name, model, phase, outcome: out.kind === 'ok' ? 'ok' : out.kind === 'timeout' ? 'timeout' : 'failed', status: out.kind === 'fail' ? out.status : undefined, ms: now() - at });
91
+ last = out;
92
+ return out;
93
+ };
94
+ const finish = async (provider, model, reply) => {
95
+ const result = { text: reply.text, provider: provider.name, model, usage: reply.usage };
96
+ if (cacheSlot)
97
+ await store.set(cacheSlot, { ...result, at: now() }).catch(() => { });
98
+ return result;
99
+ };
100
+ // Phase 1: OpenRouter's free models. A withdrawn one has already been replaced by resolveModels.
101
+ if (orKey) {
102
+ const models = await resolveModels(tier);
103
+ for (let i = 0; i < models.length && freeLeft() >= t.minSlice; i++) {
104
+ const slice = i >= models.length - 1 ? freeLeft() : Math.min(later ? t.freeSliceLater : t.freeSlice, freeLeft());
105
+ const out = await attempt(router, orKey, models[i], 'free', slice);
106
+ if (out.kind === 'ok')
107
+ return finish(router, models[i], out.reply);
108
+ if (out.kind === 'fail') {
109
+ if (out.status === 401) {
110
+ authFailed = true;
111
+ break;
112
+ } // the key is wrong: no other model will differ
113
+ if (out.status === 429)
114
+ rateLimited = out;
115
+ }
116
+ }
117
+ // Phase 2: a low-cost paid model, which is not under the free-model limits.
118
+ if (paidAvailable && !authFailed) {
119
+ for (const m of paidModels) {
120
+ if (left() < t.minSlice)
121
+ break;
122
+ const out = await attempt(router, orKey, m, 'paid', left());
123
+ if (out.kind === 'ok')
124
+ return finish(router, m, out.reply);
125
+ if (out.kind === 'fail') {
126
+ if (out.status === 402) {
127
+ needsCredit = true;
128
+ break;
129
+ }
130
+ if (out.status === 401)
131
+ break;
132
+ }
133
+ }
134
+ }
135
+ }
136
+ // Phase 3: other providers, with their own keys.
137
+ for (const fb of fbs) {
138
+ for (const m of fb.models) {
139
+ if (left() < t.minSlice)
140
+ break;
141
+ const out = await attempt(fb.provider, fb.apiKey, m, 'fallback', left());
142
+ if (out.kind === 'ok')
143
+ return finish(fb.provider, m, out.reply);
144
+ if (out.kind === 'fail' && out.status === 401)
145
+ break; // this provider's key is wrong: skip its other models
146
+ }
147
+ }
148
+ // Nothing answered. Say why, using what the first useful failure told us.
149
+ const ownKey = Boolean(opts.apiKey);
150
+ if (!attempted)
151
+ throw new LodestoneError('not_configured');
152
+ const lastFail = last;
153
+ if (!rateLimited && lastFail?.kind === 'timeout')
154
+ throw new LodestoneError('slow');
155
+ const failure = rateLimited ?? (lastFail?.kind === 'fail' ? lastFail : null);
156
+ const status = failure?.status ?? 0;
157
+ const kind = failure?.unusable ? 'bad_output'
158
+ : authFailed || status === 401 ? 'auth'
159
+ : status === 429 ? 'rate_limit'
160
+ : status === 404 ? 'withdrawn'
161
+ : status >= 500 ? 'unavailable'
162
+ : 'other';
163
+ const rateLimit = status === 429 && failure ? readRateLimit(failure.body) : undefined;
164
+ throw new LodestoneError(kind, { status, rateLimit, ownKey, needsCredit });
165
+ }
166
+ /** Like complete(), but the answer must be JSON (and pass `validate`, if given). A model whose answer isn't is skipped for the next. */
167
+ async function json(opts) {
168
+ const ok = (text) => {
169
+ const v = tryParseJson(text);
170
+ return v !== undefined && (!opts.validate || opts.validate(v));
171
+ };
172
+ const { validate: _v, ...rest } = opts;
173
+ const accept = opts.accept ? (s) => ok(s) && opts.accept(s) : ok;
174
+ const result = await complete({ ...rest, accept });
175
+ return { ...result, data: tryParseJson(result.text) };
176
+ }
177
+ /** Fetches and saves OpenRouter's current catalogue. Run it daily. */
178
+ const refreshCatalog = () => catalog.refresh();
179
+ /** The daily health check: saves the catalogue, and says which preferred models have
180
+ * been withdrawn (harmless, they are replaced) and which tiers are left with fewer
181
+ * than two real models to try (not harmless). `ok` is false only when the
182
+ * catalogue cannot be read or a tier is short. */
183
+ async function checkModels() {
184
+ const models = await catalog.refresh().catch(() => null);
185
+ if (!models)
186
+ return { ok: false, error: 'could not read the OpenRouter catalogue' };
187
+ const ids = new Set(models.map((m) => m.id));
188
+ const all = [...new Set([...Object.values(prefs).flat(), ...paidModels])].filter((m) => m !== ROUTER);
189
+ const withdrawn = all.filter((m) => !ids.has(m));
190
+ const shortTiers = Object.keys(prefs).filter((tier) => pickModels(tier, models, prefs[tier]).filter((m) => m !== ROUTER).length < 2);
191
+ return { ok: shortTiers.length === 0, catalogSize: models.length, withdrawn, shortTiers };
192
+ }
193
+ return { complete, json, resolveModels, refreshCatalog, checkModels };
194
+ }
@@ -0,0 +1,11 @@
1
+ import type { Tier } from './types.js';
2
+ /** Starting preferences, tried in order. They are only preferences: Lodestone checks
3
+ * them against OpenRouter's catalogue and replaces any that have been withdrawn, so
4
+ * these going out of date is expected and harmless. Override per tier in the config.
5
+ * Every free list ends with `openrouter/free`, OpenRouter's own router, which picks
6
+ * whichever free model is available at that moment. */
7
+ export declare const DEFAULT_MODELS: Record<Tier, string[]>;
8
+ /** Tried only when paid use is allowed (a person's own key, or `allowPaid`) and the
9
+ * free models failed. Fractions of a cent per request; with no credit OpenRouter
10
+ * refuses and nothing is spent. */
11
+ export declare const DEFAULT_PAID_MODELS: string[];
package/dist/models.js ADDED
@@ -0,0 +1,14 @@
1
+ /** Starting preferences, tried in order. They are only preferences: Lodestone checks
2
+ * them against OpenRouter's catalogue and replaces any that have been withdrawn, so
3
+ * these going out of date is expected and harmless. Override per tier in the config.
4
+ * Every free list ends with `openrouter/free`, OpenRouter's own router, which picks
5
+ * whichever free model is available at that moment. */
6
+ export const DEFAULT_MODELS = {
7
+ fast: ['google/gemma-4-26b-a4b-it:free', 'nvidia/nemotron-3.5-lightning:free', 'openrouter/free'],
8
+ strong: ['nvidia/nemotron-3-ultra-550b-a55b:free', 'google/gemma-4-31b-it:free', 'openrouter/free'],
9
+ vision: ['google/gemma-4-31b-it:free', 'nvidia/nemotron-3.5-super-vl:free', 'openrouter/free'],
10
+ };
11
+ /** Tried only when paid use is allowed (a person's own key, or `allowPaid`) and the
12
+ * free models failed. Fractions of a cent per request; with no credit OpenRouter
13
+ * refuses and nothing is spent. */
14
+ export const DEFAULT_PAID_MODELS = ['qwen/qwen3.7-flash', 'mistralai/mistral-small-3.2-24b-instruct'];
@@ -0,0 +1,6 @@
1
+ import type { Provider } from '../types.js';
2
+ export interface AnthropicOptions {
3
+ fetch?: typeof fetch;
4
+ }
5
+ /** Anthropic's own API, for use as a fallback with a separate key from OpenRouter. */
6
+ export declare function anthropic(opts?: AnthropicOptions): Provider;
@@ -0,0 +1,40 @@
1
+ import { ProviderError } from '../errors.js';
2
+ const IMAGE = /^data:(image\/(?:jpeg|png|gif|webp));base64,(.+)$/s;
3
+ function part(p) {
4
+ if (p.type === 'text')
5
+ return { type: 'text', text: p.text };
6
+ const m = IMAGE.exec(p.dataUrl);
7
+ if (!m)
8
+ throw new ProviderError(400, 'image must be a base64 data URL (jpeg, png, gif or webp)');
9
+ return { type: 'image', source: { type: 'base64', media_type: m[1], data: m[2] } };
10
+ }
11
+ const wire = (m) => ({ role: m.role, content: typeof m.content === 'string' ? m.content : m.content.map(part) });
12
+ /** Anthropic's own API, for use as a fallback with a separate key from OpenRouter. */
13
+ export function anthropic(opts = {}) {
14
+ const f = opts.fetch ?? fetch;
15
+ return {
16
+ name: 'anthropic',
17
+ vision: true,
18
+ async call(req) {
19
+ const res = await f('https://api.anthropic.com/v1/messages', {
20
+ method: 'POST',
21
+ headers: { 'Content-Type': 'application/json', 'x-api-key': req.apiKey, 'anthropic-version': '2023-06-01' },
22
+ body: JSON.stringify({
23
+ model: req.model,
24
+ max_tokens: req.maxTokens,
25
+ temperature: req.temperature,
26
+ ...(req.system ? { system: req.system } : {}),
27
+ messages: req.messages.map(wire),
28
+ }),
29
+ signal: req.signal,
30
+ });
31
+ if (!res.ok)
32
+ throw new ProviderError(res.status, await res.text());
33
+ const data = (await res.json());
34
+ return {
35
+ text: (data.content ?? []).filter((c) => c.type === 'text').map((c) => c.text ?? '').join(''),
36
+ usage: data.usage ? { inputTokens: data.usage.input_tokens ?? 0, outputTokens: data.usage.output_tokens ?? 0 } : undefined,
37
+ };
38
+ },
39
+ };
40
+ }
@@ -0,0 +1,6 @@
1
+ import type { Provider } from '../types.js';
2
+ export interface GoogleOptions {
3
+ fetch?: typeof fetch;
4
+ }
5
+ /** Google's Gemini API directly, for use as a fallback with a separate key from OpenRouter. */
6
+ export declare function google(opts?: GoogleOptions): Provider;
@@ -0,0 +1,39 @@
1
+ import { ProviderError } from '../errors.js';
2
+ const IMAGE = /^data:(image\/[a-z+.-]+);base64,(.+)$/is;
3
+ function part(p) {
4
+ if (p.type === 'text')
5
+ return { text: p.text };
6
+ const m = IMAGE.exec(p.dataUrl);
7
+ if (!m)
8
+ throw new ProviderError(400, 'image must be a base64 data URL');
9
+ return { inlineData: { mimeType: m[1], data: m[2] } };
10
+ }
11
+ // Gemini has no assistant role: it calls it "model".
12
+ const wire = (m) => ({ role: m.role === 'assistant' ? 'model' : 'user', parts: typeof m.content === 'string' ? [{ text: m.content }] : m.content.map(part) });
13
+ /** Google's Gemini API directly, for use as a fallback with a separate key from OpenRouter. */
14
+ export function google(opts = {}) {
15
+ const f = opts.fetch ?? fetch;
16
+ return {
17
+ name: 'google',
18
+ vision: true,
19
+ async call(req) {
20
+ const res = await f(`https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(req.model)}:generateContent`, {
21
+ method: 'POST',
22
+ headers: { 'Content-Type': 'application/json', 'x-goog-api-key': req.apiKey },
23
+ body: JSON.stringify({
24
+ ...(req.system ? { system_instruction: { parts: [{ text: req.system }] } } : {}),
25
+ contents: req.messages.map(wire),
26
+ generationConfig: { maxOutputTokens: req.maxTokens, temperature: req.temperature },
27
+ }),
28
+ signal: req.signal,
29
+ });
30
+ if (!res.ok)
31
+ throw new ProviderError(res.status, await res.text());
32
+ const data = (await res.json());
33
+ return {
34
+ text: (data.candidates?.[0]?.content?.parts ?? []).map((p) => p.text ?? '').join(''),
35
+ usage: data.usageMetadata ? { inputTokens: data.usageMetadata.promptTokenCount ?? 0, outputTokens: data.usageMetadata.candidatesTokenCount ?? 0 } : undefined,
36
+ };
37
+ },
38
+ };
39
+ }
@@ -0,0 +1,6 @@
1
+ import type { Provider, ProviderReply, ProviderRequest } from '../types.js';
2
+ /** A provider that answers without any network, for tests and offline development.
3
+ * Pass a function to control the answer, or throw from it to simulate a failure. */
4
+ export declare function mock(reply?: string | ((req: ProviderRequest) => ProviderReply | string | Promise<ProviderReply | string>)): Provider & {
5
+ calls: ProviderRequest[];
6
+ };
@@ -0,0 +1,15 @@
1
+ /** A provider that answers without any network, for tests and offline development.
2
+ * Pass a function to control the answer, or throw from it to simulate a failure. */
3
+ export function mock(reply = '[mock answer]') {
4
+ const calls = [];
5
+ return {
6
+ name: 'mock',
7
+ vision: true,
8
+ calls,
9
+ async call(req) {
10
+ calls.push(req);
11
+ const r = typeof reply === 'function' ? await reply(req) : reply;
12
+ return typeof r === 'string' ? { text: r } : r;
13
+ },
14
+ };
15
+ }
@@ -0,0 +1,10 @@
1
+ import type { Provider } from '../types.js';
2
+ export interface OpenRouterOptions {
3
+ fetch?: typeof fetch;
4
+ /** Ask the model not to think at length. Default true: most tasks need an answer, not a long chain of thought, and thinking is what made some free models slower than the time allowed. */
5
+ lowReasoning?: boolean;
6
+ /** Sent as HTTP-Referer and X-Title, which OpenRouter uses to credit apps. */
7
+ referer?: string;
8
+ title?: string;
9
+ }
10
+ export declare function openrouter(opts?: OpenRouterOptions): Provider;
@@ -0,0 +1,36 @@
1
+ import { ProviderError } from '../errors.js';
2
+ const part = (p) => (p.type === 'text' ? { type: 'text', text: p.text } : { type: 'image_url', image_url: { url: p.dataUrl } });
3
+ const wire = (m) => ({ role: m.role, content: typeof m.content === 'string' ? m.content : m.content.map(part) });
4
+ export function openrouter(opts = {}) {
5
+ const f = opts.fetch ?? fetch;
6
+ return {
7
+ name: 'openrouter',
8
+ vision: true,
9
+ async call(req) {
10
+ const res = await f('https://openrouter.ai/api/v1/chat/completions', {
11
+ method: 'POST',
12
+ headers: {
13
+ Authorization: `Bearer ${req.apiKey}`,
14
+ 'Content-Type': 'application/json',
15
+ ...(opts.referer ? { 'HTTP-Referer': opts.referer } : {}),
16
+ ...(opts.title ? { 'X-Title': opts.title } : {}),
17
+ },
18
+ body: JSON.stringify({
19
+ model: req.model,
20
+ temperature: req.temperature,
21
+ max_tokens: req.maxTokens,
22
+ ...(opts.lowReasoning === false ? {} : { reasoning: { effort: 'low', exclude: true } }),
23
+ messages: [...(req.system ? [{ role: 'system', content: req.system }] : []), ...req.messages.map(wire)],
24
+ }),
25
+ signal: req.signal,
26
+ });
27
+ if (!res.ok)
28
+ throw new ProviderError(res.status, await res.text());
29
+ const data = (await res.json());
30
+ return {
31
+ text: data.choices?.[0]?.message?.content ?? '',
32
+ usage: data.usage ? { inputTokens: data.usage.prompt_tokens ?? 0, outputTokens: data.usage.completion_tokens ?? 0 } : undefined,
33
+ };
34
+ },
35
+ };
36
+ }
@@ -0,0 +1,11 @@
1
+ /** Says which kind of 429 OpenRouter returned, because they mean different things
2
+ * and need different advice: a brand-new key is far more likely to meet the free
3
+ * models being busy upstream, or the account's daily free-model allowance, than a
4
+ * per-key limit of its own. Reads only the error body the provider sends. */
5
+ export type RateLimitKind = 'daily' | 'minute' | 'upstream' | 'other';
6
+ export interface RateLimitReading {
7
+ kind: RateLimitKind;
8
+ resetAt?: Date;
9
+ limit?: number;
10
+ }
11
+ export declare function readRateLimit(rawBody: string): RateLimitReading;
@@ -0,0 +1,24 @@
1
+ /** Says which kind of 429 OpenRouter returned, because they mean different things
2
+ * and need different advice: a brand-new key is far more likely to meet the free
3
+ * models being busy upstream, or the account's daily free-model allowance, than a
4
+ * per-key limit of its own. Reads only the error body the provider sends. */
5
+ export function readRateLimit(rawBody) {
6
+ let body = {};
7
+ try {
8
+ body = JSON.parse(rawBody);
9
+ }
10
+ catch { /* not JSON: judged by its text */ }
11
+ const msg = `${body.error?.message ?? ''} ${body.error?.metadata?.raw ?? ''} ${rawBody.slice(0, 400)}`.toLowerCase();
12
+ const headers = body.error?.metadata?.headers ?? {};
13
+ const resetMs = Number(headers['X-RateLimit-Reset'] ?? headers['x-ratelimit-reset']);
14
+ const limit = Number(headers['X-RateLimit-Limit'] ?? headers['x-ratelimit-limit']);
15
+ const resetAt = Number.isFinite(resetMs) && resetMs > 1e12 ? new Date(resetMs) : undefined;
16
+ const extra = { ...(resetAt ? { resetAt } : {}), ...(Number.isFinite(limit) && limit > 0 ? { limit } : {}) };
17
+ if (/per-day|per day|free-models-per-day|daily/.test(msg))
18
+ return { kind: 'daily', ...extra };
19
+ if (/per-minute|per minute|requests per minute/.test(msg))
20
+ return { kind: 'minute', ...extra };
21
+ if (/upstream|provider returned error|temporarily rate-limited|provider_name/.test(msg) || body.error?.metadata?.provider_name)
22
+ return { kind: 'upstream', ...extra };
23
+ return { kind: 'other', ...extra };
24
+ }
@@ -0,0 +1,3 @@
1
+ import type { KeyValueStore } from './types.js';
2
+ /** A store that lives in memory. The default; lost when the process ends. */
3
+ export declare function memoryStore(): KeyValueStore;
package/dist/store.js ADDED
@@ -0,0 +1,8 @@
1
+ /** A store that lives in memory. The default; lost when the process ends. */
2
+ export function memoryStore() {
3
+ const data = new Map();
4
+ return {
5
+ get: async (key) => data.get(key) ?? null,
6
+ set: async (key, value) => { data.set(key, value); },
7
+ };
8
+ }
@@ -0,0 +1,42 @@
1
+ export type Tier = 'fast' | 'strong' | 'vision';
2
+ export type ContentPart = {
3
+ type: 'text';
4
+ text: string;
5
+ } | {
6
+ type: 'image';
7
+ dataUrl: string;
8
+ };
9
+ export interface Message {
10
+ role: 'user' | 'assistant';
11
+ content: string | ContentPart[];
12
+ }
13
+ export interface Usage {
14
+ inputTokens: number;
15
+ outputTokens: number;
16
+ }
17
+ /** What a provider adapter is asked to do: one model, one request. */
18
+ export interface ProviderRequest {
19
+ model: string;
20
+ system?: string;
21
+ messages: Message[];
22
+ maxTokens: number;
23
+ temperature: number;
24
+ apiKey: string;
25
+ signal: AbortSignal;
26
+ }
27
+ export interface ProviderReply {
28
+ text: string;
29
+ usage?: Usage;
30
+ }
31
+ export interface Provider {
32
+ name: string;
33
+ /** Can this provider read images? */
34
+ vision: boolean;
35
+ call(req: ProviderRequest): Promise<ProviderReply>;
36
+ }
37
+ /** Where Lodestone keeps the model catalogue and cached answers. Anything that can
38
+ * get and set JSON by key will do: Netlify Blobs, Redis, a SQLite table, a Map. */
39
+ export interface KeyValueStore {
40
+ get(key: string): Promise<unknown>;
41
+ set(key: string, value: unknown): Promise<void>;
42
+ }
package/dist/types.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "@extrafemi-ai/lodestone",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Calls AI models so your tool keeps working when a model is withdrawn, slow or rate-limited.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/obasaolorunfemi-ai/lodestone.git"
9
+ },
10
+ "homepage": "https://github.com/obasaolorunfemi-ai/lodestone#readme",
11
+ "bugs": {
12
+ "url": "https://github.com/obasaolorunfemi-ai/lodestone/issues"
13
+ },
14
+ "author": "Extrafemi",
15
+ "type": "module",
16
+ "main": "./dist/index.js",
17
+ "types": "./dist/index.d.ts",
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ }
23
+ },
24
+ "files": [
25
+ "dist",
26
+ "README.md",
27
+ "LICENSE"
28
+ ],
29
+ "sideEffects": false,
30
+ "engines": {
31
+ "node": ">=20"
32
+ },
33
+ "scripts": {
34
+ "build": "tsc -p tsconfig.build.json",
35
+ "typecheck": "tsc --noEmit",
36
+ "test": "vitest run",
37
+ "prepublishOnly": "npm run typecheck && npm test && npm run build"
38
+ },
39
+ "devDependencies": {
40
+ "@types/node": "^22.10.0",
41
+ "typescript": "^5.6.0",
42
+ "vitest": "^2.1.0"
43
+ },
44
+ "keywords": [
45
+ "ai",
46
+ "llm",
47
+ "openrouter",
48
+ "anthropic",
49
+ "gemini",
50
+ "fallback",
51
+ "model-routing"
52
+ ],
53
+ "publishConfig": {
54
+ "access": "public",
55
+ "provenance": true
56
+ }
57
+ }