@extrafemi-ai/lodestone 0.1.0 → 0.2.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/README.md +18 -0
- package/dist/errors.d.ts +4 -0
- package/dist/errors.js +11 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/lodestone.d.ts +14 -1
- package/dist/lodestone.js +39 -5
- package/dist/providers/anthropic.js +1 -1
- package/dist/providers/google.js +1 -1
- package/dist/providers/openrouter.js +1 -1
- package/dist/types.d.ts +2 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -42,6 +42,24 @@ try {
|
|
|
42
42
|
|
|
43
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
44
|
|
|
45
|
+
### Choosing the provider and model yourself (`route`)
|
|
46
|
+
|
|
47
|
+
Tiers are for tools that don't care which model answers. A tool that picks its own provider and model per request (a paid model, a customer's own key) passes a `route` instead: exactly these steps, in order, until one answers.
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
await ai.complete({
|
|
51
|
+
system, messages, maxTokens: 900,
|
|
52
|
+
route: [
|
|
53
|
+
{ provider: 'anthropic', model: 'claude-sonnet-4-5', apiKey: customerKey },
|
|
54
|
+
{ provider: 'openrouter', model: 'anthropic/claude-sonnet-4-5', apiKey: backupKey },
|
|
55
|
+
],
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
A step with no key is skipped. A route skips the model lists and the catalogue, leaves temperature to the provider unless you set one, and still gets the time budget, typed failures and usage. `detail.providerMessage` on the error carries the provider's own message. Replace or add provider adapters with the `providers` option, for example `providers: { openrouter: openrouter({ lowReasoning: false }) }`.
|
|
60
|
+
|
|
61
|
+
Keep a customer's own key out of any fallback step: build the route from their key only.
|
|
62
|
+
|
|
45
63
|
### Phases
|
|
46
64
|
|
|
47
65
|
For each call, in order, until one answers:
|
package/dist/errors.d.ts
CHANGED
|
@@ -5,6 +5,8 @@ export declare class ProviderError extends Error {
|
|
|
5
5
|
body: string;
|
|
6
6
|
constructor(status: number, body: string);
|
|
7
7
|
}
|
|
8
|
+
/** The human-readable message inside a provider's error body ({"error":{"message":"..."}} or {"message":"..."}), if it has one. */
|
|
9
|
+
export declare function messageFrom(body: string): string | undefined;
|
|
8
10
|
export type FailureKind =
|
|
9
11
|
/** The key was rejected. Another model on the same key will not differ. */
|
|
10
12
|
'auth'
|
|
@@ -31,11 +33,13 @@ export declare class LodestoneError extends Error {
|
|
|
31
33
|
rateLimit?: RateLimitReading;
|
|
32
34
|
ownKey?: boolean;
|
|
33
35
|
needsCredit?: boolean;
|
|
36
|
+
providerMessage?: string;
|
|
34
37
|
};
|
|
35
38
|
constructor(kind: FailureKind, detail?: {
|
|
36
39
|
status?: number;
|
|
37
40
|
rateLimit?: RateLimitReading;
|
|
38
41
|
ownKey?: boolean;
|
|
39
42
|
needsCredit?: boolean;
|
|
43
|
+
providerMessage?: string;
|
|
40
44
|
});
|
|
41
45
|
}
|
package/dist/errors.js
CHANGED
|
@@ -9,6 +9,17 @@ export class ProviderError extends Error {
|
|
|
9
9
|
this.name = 'ProviderError';
|
|
10
10
|
}
|
|
11
11
|
}
|
|
12
|
+
/** The human-readable message inside a provider's error body ({"error":{"message":"..."}} or {"message":"..."}), if it has one. */
|
|
13
|
+
export function messageFrom(body) {
|
|
14
|
+
try {
|
|
15
|
+
const j = JSON.parse(body);
|
|
16
|
+
const m = typeof j.error === 'string' ? j.error : j.error?.message ?? j.message;
|
|
17
|
+
return typeof m === 'string' && m.trim() ? m.trim().slice(0, 300) : undefined;
|
|
18
|
+
}
|
|
19
|
+
catch {
|
|
20
|
+
return undefined;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
12
23
|
/** Thrown when no model could answer. `kind` says why, so the caller can decide what
|
|
13
24
|
* to tell the person; `explain()` has a ready-made plain-language message. */
|
|
14
25
|
export class LodestoneError extends Error {
|
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
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';
|
|
2
|
+
export type { Lodestone, LodestoneConfig, CompleteOptions, CompleteResult, Profile, FallbackConfig, AttemptEvent, RouteStep } from './lodestone.js';
|
|
3
|
+
export { LodestoneError, ProviderError, messageFrom } from './errors.js';
|
|
4
4
|
export type { FailureKind } from './errors.js';
|
|
5
5
|
export { explain } from './explain.js';
|
|
6
6
|
export type { ExplainOptions } from './explain.js';
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { createLodestone } from './lodestone.js';
|
|
2
|
-
export { LodestoneError, ProviderError } from './errors.js';
|
|
2
|
+
export { LodestoneError, ProviderError, messageFrom } from './errors.js';
|
|
3
3
|
export { explain } from './explain.js';
|
|
4
4
|
export { readRateLimit } from './rateLimit.js';
|
|
5
5
|
export { pickModels, eligible, ROUTER } from './catalog.js';
|
package/dist/lodestone.d.ts
CHANGED
|
@@ -14,7 +14,7 @@ export interface FallbackConfig {
|
|
|
14
14
|
export interface AttemptEvent {
|
|
15
15
|
provider: string;
|
|
16
16
|
model: string;
|
|
17
|
-
phase: 'free' | 'paid' | 'fallback';
|
|
17
|
+
phase: 'free' | 'paid' | 'fallback' | 'route';
|
|
18
18
|
outcome: 'ok' | 'timeout' | 'failed';
|
|
19
19
|
status?: number;
|
|
20
20
|
ms: number;
|
|
@@ -30,6 +30,8 @@ export interface LodestoneConfig {
|
|
|
30
30
|
/** Replace the OpenRouter adapter (tests, proxies). */
|
|
31
31
|
provider?: Provider;
|
|
32
32
|
};
|
|
33
|
+
/** Provider adapters by name, for `route` steps. Defaults: openrouter, anthropic and google. Replace one (for example `openrouter({ lowReasoning: false })`) or add your own. */
|
|
34
|
+
providers?: Record<string, Provider>;
|
|
33
35
|
/** Other providers, each with its own key, tried after OpenRouter has failed. */
|
|
34
36
|
fallbacks?: FallbackConfig[];
|
|
35
37
|
/** Named tasks, so calls say what they are doing and not which model to use. */
|
|
@@ -50,7 +52,18 @@ export interface LodestoneConfig {
|
|
|
50
52
|
/** Called after every model attempt: for logs and metrics. Never receives prompts or answers. */
|
|
51
53
|
onAttempt?: (e: AttemptEvent) => void;
|
|
52
54
|
}
|
|
55
|
+
/** One attempt in an explicit route: this provider, this model, this key. */
|
|
56
|
+
export interface RouteStep {
|
|
57
|
+
/** A name in `providers` (openrouter, anthropic, google by default). */
|
|
58
|
+
provider: string;
|
|
59
|
+
model: string;
|
|
60
|
+
apiKey: string;
|
|
61
|
+
/** Longest this step may take. Default: most of what is left, keeping some for the steps after it. */
|
|
62
|
+
timeoutMs?: number;
|
|
63
|
+
}
|
|
53
64
|
export interface CompleteOptions {
|
|
65
|
+
/** Skip tiers and phases: try exactly these steps, in order, until one answers. For callers that choose their own provider and model per request. Temperature is left to the provider unless set. */
|
|
66
|
+
route?: RouteStep[];
|
|
54
67
|
/** A key in `profiles`. */
|
|
55
68
|
task?: string;
|
|
56
69
|
/** Overrides the profile's tier. Default: 'vision' if the messages contain an image, else 'fast'. */
|
package/dist/lodestone.js
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
import { createCatalog, pickModels, ROUTER } from './catalog.js';
|
|
2
|
-
import { LodestoneError, ProviderError } from './errors.js';
|
|
2
|
+
import { LodestoneError, messageFrom, ProviderError } from './errors.js';
|
|
3
3
|
import { tryParseJson } from './json.js';
|
|
4
4
|
import { DEFAULT_MODELS, DEFAULT_PAID_MODELS } from './models.js';
|
|
5
5
|
import { readRateLimit } from './rateLimit.js';
|
|
6
|
+
import { anthropic } from './providers/anthropic.js';
|
|
7
|
+
import { google } from './providers/google.js';
|
|
6
8
|
import { openrouter } from './providers/openrouter.js';
|
|
7
9
|
import { memoryStore } from './store.js';
|
|
8
10
|
const hasImage = (messages) => messages.some((m) => Array.isArray(m.content) && m.content.some((p) => p.type === 'image'));
|
|
@@ -22,6 +24,7 @@ export function createLodestone(config = {}) {
|
|
|
22
24
|
const prefs = { ...DEFAULT_MODELS, ...config.openrouter?.models };
|
|
23
25
|
const paidModels = config.openrouter?.paidModels ?? DEFAULT_PAID_MODELS;
|
|
24
26
|
const fallbacks = config.fallbacks ?? [];
|
|
27
|
+
const registry = { openrouter: router, anthropic: anthropic({ fetch: fetchImpl }), google: google({ fetch: fetchImpl }), ...config.providers };
|
|
25
28
|
/** The ids to send for a tier: preferences that still exist, plus current replacements. Never throws, never waits on the network. */
|
|
26
29
|
async function resolveModels(tier) {
|
|
27
30
|
try {
|
|
@@ -41,7 +44,7 @@ export function createLodestone(config = {}) {
|
|
|
41
44
|
const images = hasImage(messages);
|
|
42
45
|
const tier = opts.tier ?? profile?.tier ?? (images ? 'vision' : 'fast');
|
|
43
46
|
const maxTokens = opts.maxTokens ?? profile?.maxTokens ?? 3500;
|
|
44
|
-
const temperature = opts.temperature ?? profile?.temperature ?? 0.2;
|
|
47
|
+
const temperature = opts.temperature ?? profile?.temperature ?? (opts.route ? undefined : 0.2);
|
|
45
48
|
const cacheSlot = opts.cacheKey ? `lodestone:cache:${opts.cacheKey}` : null;
|
|
46
49
|
if (cacheSlot) {
|
|
47
50
|
try {
|
|
@@ -83,7 +86,7 @@ export function createLodestone(config = {}) {
|
|
|
83
86
|
if (name === 'TimeoutError' || name === 'AbortError')
|
|
84
87
|
out = { kind: 'timeout' };
|
|
85
88
|
else if (e instanceof ProviderError)
|
|
86
|
-
out = { kind: 'fail', status: e.status, body: e.body };
|
|
89
|
+
out = { kind: 'fail', status: e.status, body: e.body, message: messageFrom(e.body) };
|
|
87
90
|
else
|
|
88
91
|
out = { kind: 'fail', status: 599, body: e.message };
|
|
89
92
|
}
|
|
@@ -97,6 +100,34 @@ export function createLodestone(config = {}) {
|
|
|
97
100
|
await store.set(cacheSlot, { ...result, at: now() }).catch(() => { });
|
|
98
101
|
return result;
|
|
99
102
|
};
|
|
103
|
+
// An explicit route: exactly the steps the caller named, in order.
|
|
104
|
+
if (opts.route?.length) {
|
|
105
|
+
const steps = opts.route.filter((st) => st.apiKey);
|
|
106
|
+
let firstFail = null;
|
|
107
|
+
for (let i = 0; i < steps.length; i++) {
|
|
108
|
+
const st = steps[i];
|
|
109
|
+
const provider = registry[st.provider];
|
|
110
|
+
if (!provider)
|
|
111
|
+
throw new Error(`Unknown provider "${st.provider}" in route`);
|
|
112
|
+
if (images && !provider.vision)
|
|
113
|
+
continue;
|
|
114
|
+
if (left() <= 0)
|
|
115
|
+
break;
|
|
116
|
+
const isLast = i === steps.length - 1;
|
|
117
|
+
const ms = Math.min(left(), st.timeoutMs ?? (isLast ? left() : Math.max(t.minSlice, Math.floor(left() * 0.6))));
|
|
118
|
+
const out = await attempt(provider, st.apiKey, st.model, 'route', ms);
|
|
119
|
+
if (out.kind === 'ok')
|
|
120
|
+
return finish(provider, st.model, out.reply);
|
|
121
|
+
if (out.kind === 'fail' && !firstFail)
|
|
122
|
+
firstFail = out;
|
|
123
|
+
}
|
|
124
|
+
if (!attempted)
|
|
125
|
+
throw new LodestoneError('not_configured');
|
|
126
|
+
const lastRoute = last;
|
|
127
|
+
if (!firstFail && lastRoute?.kind === 'timeout')
|
|
128
|
+
throw new LodestoneError('slow');
|
|
129
|
+
throw classify(firstFail ?? (lastRoute?.kind === 'fail' ? lastRoute : null), Boolean(opts.apiKey), false, false);
|
|
130
|
+
}
|
|
100
131
|
// Phase 1: OpenRouter's free models. A withdrawn one has already been replaced by resolveModels.
|
|
101
132
|
if (orKey) {
|
|
102
133
|
const models = await resolveModels(tier);
|
|
@@ -152,7 +183,10 @@ export function createLodestone(config = {}) {
|
|
|
152
183
|
const lastFail = last;
|
|
153
184
|
if (!rateLimited && lastFail?.kind === 'timeout')
|
|
154
185
|
throw new LodestoneError('slow');
|
|
155
|
-
|
|
186
|
+
throw classify(rateLimited ?? (lastFail?.kind === 'fail' ? lastFail : null), ownKey, authFailed, needsCredit);
|
|
187
|
+
}
|
|
188
|
+
/** Turns the failure that explains why nothing answered into a LodestoneError. */
|
|
189
|
+
function classify(failure, ownKey, authFailed, needsCredit) {
|
|
156
190
|
const status = failure?.status ?? 0;
|
|
157
191
|
const kind = failure?.unusable ? 'bad_output'
|
|
158
192
|
: authFailed || status === 401 ? 'auth'
|
|
@@ -161,7 +195,7 @@ export function createLodestone(config = {}) {
|
|
|
161
195
|
: status >= 500 ? 'unavailable'
|
|
162
196
|
: 'other';
|
|
163
197
|
const rateLimit = status === 429 && failure ? readRateLimit(failure.body) : undefined;
|
|
164
|
-
|
|
198
|
+
return new LodestoneError(kind, { status, rateLimit, ownKey, needsCredit, providerMessage: failure?.message });
|
|
165
199
|
}
|
|
166
200
|
/** 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
201
|
async function json(opts) {
|
|
@@ -22,7 +22,7 @@ export function anthropic(opts = {}) {
|
|
|
22
22
|
body: JSON.stringify({
|
|
23
23
|
model: req.model,
|
|
24
24
|
max_tokens: req.maxTokens,
|
|
25
|
-
temperature: req.temperature,
|
|
25
|
+
...(req.temperature === undefined ? {} : { temperature: req.temperature }),
|
|
26
26
|
...(req.system ? { system: req.system } : {}),
|
|
27
27
|
messages: req.messages.map(wire),
|
|
28
28
|
}),
|
package/dist/providers/google.js
CHANGED
|
@@ -23,7 +23,7 @@ export function google(opts = {}) {
|
|
|
23
23
|
body: JSON.stringify({
|
|
24
24
|
...(req.system ? { system_instruction: { parts: [{ text: req.system }] } } : {}),
|
|
25
25
|
contents: req.messages.map(wire),
|
|
26
|
-
generationConfig: { maxOutputTokens: req.maxTokens, temperature: req.temperature },
|
|
26
|
+
generationConfig: { maxOutputTokens: req.maxTokens, ...(req.temperature === undefined ? {} : { temperature: req.temperature }) },
|
|
27
27
|
}),
|
|
28
28
|
signal: req.signal,
|
|
29
29
|
});
|
|
@@ -17,7 +17,7 @@ export function openrouter(opts = {}) {
|
|
|
17
17
|
},
|
|
18
18
|
body: JSON.stringify({
|
|
19
19
|
model: req.model,
|
|
20
|
-
temperature: req.temperature,
|
|
20
|
+
...(req.temperature === undefined ? {} : { temperature: req.temperature }),
|
|
21
21
|
max_tokens: req.maxTokens,
|
|
22
22
|
...(opts.lowReasoning === false ? {} : { reasoning: { effort: 'low', exclude: true } }),
|
|
23
23
|
messages: [...(req.system ? [{ role: 'system', content: req.system }] : []), ...req.messages.map(wire)],
|
package/dist/types.d.ts
CHANGED
|
@@ -20,7 +20,8 @@ export interface ProviderRequest {
|
|
|
20
20
|
system?: string;
|
|
21
21
|
messages: Message[];
|
|
22
22
|
maxTokens: number;
|
|
23
|
-
|
|
23
|
+
/** Left out when the caller did not set one, so the provider's own default applies. */
|
|
24
|
+
temperature?: number;
|
|
24
25
|
apiKey: string;
|
|
25
26
|
signal: AbortSignal;
|
|
26
27
|
}
|