@extrafemi-ai/lodestone 0.5.0 → 0.6.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/CHANGELOG.md CHANGED
@@ -2,6 +2,19 @@
2
2
 
3
3
  Versions before 1.0 may change between minor releases; each change that could break a caller is marked **breaking**.
4
4
 
5
+ ## 0.6.0
6
+
7
+ - **Schemas.** `json({ schema })` accepts anything with a `safeParse` method, such as a Zod schema, as well as a hand-written `validate` function. A model whose answer the schema rejects is skipped for the next, as before, and `data` is what the schema returns, so its defaults and transforms apply. Lodestone does not depend on any schema library; the `SafeParser` type is exported.
8
+
9
+ - **Groq's model list no longer includes non-chat models.** A live check on 28 Oct 2026 showed Groq lists speech (whisper), text-to-speech (orpheus) and safety-classifier (prompt-guard, safeguard) models beside its chat models, and `groq()` counted all 11 as chat. `normalizeGroq` leaves them out, so discovery cannot pick one. The same check showed `llama-3.3-70b-versatile` is no longer offered by Groq (a 404, reported as `withdrawn`).
10
+
11
+ ## 0.5.1
12
+
13
+ No change to the library's behaviour.
14
+
15
+ - **Published with npm trusted publishing.** The release workflow no longer holds an npm token: npm trusts this repository and `release.yml` directly, so there is no secret to leak or to expire.
16
+ - The Lodestone site, at https://lodestone.extrafemi.com, built from the real code (failure sentences from `explain()`, trust verdicts from `vet()`, the code map from `src/`) and checked in CI.
17
+
5
18
  ## 0.5.0
6
19
 
7
20
  Redundancy across providers, and model lists that keep themselves alive and safe.
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # Lodestone
2
2
 
3
+ **[lodestone.extrafemi.com](https://lodestone.extrafemi.com)**: an interactive walkthrough of what it does.
4
+
3
5
  Calls AI models so your tool keeps working when a model is withdrawn, slow or rate-limited.
4
6
 
5
7
  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.
@@ -36,6 +38,13 @@ try {
36
38
  }
37
39
  ```
38
40
 
41
+ `validate` is a type guard you write. Or pass a schema, anything with `safeParse` (Zod, for example), and `data` is what it returns:
42
+
43
+ ```ts
44
+ const Job = z.object({ title: z.string(), remote: z.boolean().default(false) });
45
+ const { data } = await ai.json({ task: 'extract-job', prompt, schema: Job }); // data: { title: string; remote: boolean }
46
+ ```
47
+
39
48
  `import { anthropic, google, openrouter, mock } from '@extrafemi-ai/lodestone'` for the provider adapters.
40
49
 
41
50
  ### Tiers
@@ -187,7 +196,7 @@ npm test
187
196
  npm run build
188
197
  ```
189
198
 
190
- 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.
199
+ 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 uses npm trusted publishing, so there is no token to keep: npm trusts this repository and `release.yml` directly (set up under the package's Settings on npmjs.com).
191
200
 
192
201
  ## Licence
193
202
 
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export { createLodestone } from './lodestone.js';
2
- export type { Lodestone, LodestoneConfig, CompleteOptions, CompleteResult, Profile, FallbackConfig, AttemptEvent, RouteStep, SpendControl, CheckResult } from './lodestone.js';
2
+ export type { Lodestone, LodestoneConfig, CompleteOptions, CompleteResult, SafeParser, Profile, FallbackConfig, AttemptEvent, RouteStep, SpendControl, CheckResult } from './lodestone.js';
3
3
  export { LodestoneError, ProviderError, messageFrom } from './errors.js';
4
4
  export type { FailureKind } from './errors.js';
5
5
  export { explain } from './explain.js';
@@ -24,7 +24,7 @@ export { CANDIDATES_SCHEMA } from './candidates.js';
24
24
  export type { Candidates, Candidate } from './candidates.js';
25
25
  export { createHealth } from './health.js';
26
26
  export type { Health, HealthOptions, ModelHealth } from './health.js';
27
- export { openaiCompatible, requesty, llmapi, groq, cerebras, openai, mistral, together, ollama, normalizeRequesty, normalizeLlmapi } from './providers/openaiCompatible.js';
27
+ export { openaiCompatible, requesty, llmapi, groq, cerebras, openai, mistral, together, ollama, normalizeRequesty, normalizeLlmapi, normalizeGroq } from './providers/openaiCompatible.js';
28
28
  export type { OpenAICompatibleOptions, PresetOptions } from './providers/openaiCompatible.js';
29
29
  export { vet, publisherOf, DEFAULT_PUBLISHERS } from './trust.js';
30
30
  export type { TrustPolicy, Verdict } from './trust.js';
package/dist/index.js CHANGED
@@ -14,6 +14,6 @@ export { SCORECARD_SCHEMA, ScorecardError, parseScorecard, fetchScorecard, rankM
14
14
  export { createStats } from './stats.js';
15
15
  export { CANDIDATES_SCHEMA } from './candidates.js';
16
16
  export { createHealth } from './health.js';
17
- export { openaiCompatible, requesty, llmapi, groq, cerebras, openai, mistral, together, ollama, normalizeRequesty, normalizeLlmapi } from './providers/openaiCompatible.js';
17
+ export { openaiCompatible, requesty, llmapi, groq, cerebras, openai, mistral, together, ollama, normalizeRequesty, normalizeLlmapi, normalizeGroq } from './providers/openaiCompatible.js';
18
18
  export { vet, publisherOf, DEFAULT_PUBLISHERS } from './trust.js';
19
19
  export { resolveProviderModels } from './discover.js';
@@ -113,6 +113,15 @@ export interface RouteStep {
113
113
  /** Longest this step may take. Default: most of what is left, keeping some for the steps after it. */
114
114
  timeoutMs?: number;
115
115
  }
116
+ /** What `json({ schema })` needs from a schema: Zod, Valibot (via its adapter) and ArkType-style libraries have it. */
117
+ export interface SafeParser<T> {
118
+ safeParse(value: unknown): {
119
+ success: true;
120
+ data: T;
121
+ } | {
122
+ success: false;
123
+ };
124
+ }
116
125
  export interface CompleteOptions {
117
126
  /** 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. */
118
127
  route?: RouteStep[];
@@ -167,6 +176,7 @@ export declare function createLodestone(config?: LodestoneConfig): {
167
176
  complete: (opts: CompleteOptions) => Promise<CompleteResult>;
168
177
  json: <T = unknown>(opts: CompleteOptions & {
169
178
  validate?: (value: unknown) => value is T;
179
+ schema?: SafeParser<T>;
170
180
  }) => Promise<CompleteResult & {
171
181
  data: T;
172
182
  }>;
package/dist/lodestone.js CHANGED
@@ -360,16 +360,27 @@ export function createLodestone(config = {}) {
360
360
  const rateLimit = status === 429 && failure ? readRateLimit(failure.body) : undefined;
361
361
  return new LodestoneError(kind, { status, rateLimit, ownKey, needsCredit, providerMessage: failure?.message });
362
362
  }
363
- /** Like complete(), but the answer must be JSON (and pass `validate`, if given). A model whose answer isn't is skipped for the next. */
363
+ /** Like complete(), but the answer must be JSON, and pass `validate` or `schema` if given. A model whose answer
364
+ * isn't is skipped for the next. `schema` is anything with a `safeParse` method, such as a Zod schema; `data`
365
+ * is then what the schema returns, so its defaults and transforms apply. */
364
366
  async function json(opts) {
365
- const ok = (text) => {
367
+ const parse = (text) => {
366
368
  const v = tryParseJson(text);
367
- return v !== undefined && (!opts.validate || opts.validate(v));
369
+ if (v === undefined)
370
+ return { ok: false };
371
+ if (opts.validate && !opts.validate(v))
372
+ return { ok: false };
373
+ if (opts.schema) {
374
+ const r = opts.schema.safeParse(v);
375
+ return r.success ? { ok: true, data: r.data } : { ok: false };
376
+ }
377
+ return { ok: true, data: v };
368
378
  };
369
- const { validate: _v, ...rest } = opts;
370
- const accept = opts.accept ? (s) => ok(s) && opts.accept(s) : ok;
379
+ const { validate: _v, schema: _s, ...rest } = opts;
380
+ const accept = opts.accept ? (s) => parse(s).ok && opts.accept(s) : (s) => parse(s).ok;
371
381
  const result = await complete({ ...rest, accept });
372
- return { ...result, data: tryParseJson(result.text) };
382
+ const done = parse(result.text);
383
+ return { ...result, data: (done.ok ? done.data : tryParseJson(result.text)) };
373
384
  }
374
385
  /** Fetches and saves OpenRouter's current catalogue. Run it daily. */
375
386
  const refreshCatalog = () => catalog.refresh();
@@ -23,6 +23,8 @@ export declare function openaiCompatible(o: OpenAICompatibleOptions): Provider;
23
23
  export declare const normalizeRequesty: (r: Record<string, unknown>) => CatalogModel | null;
24
24
  /** LLM API lists chat, image, video, speech and embedding models together: only "chat" is kept. */
25
25
  export declare const normalizeLlmapi: (r: Record<string, unknown>) => CatalogModel | null;
26
+ /** Groq lists speech, text-to-speech and safety-classifier models beside its chat models (seen 28 Oct 2026: whisper, orpheus, prompt-guard, safeguard). Those are not chat models, so they are left out. */
27
+ export declare const normalizeGroq: (r: Record<string, unknown>) => CatalogModel | null;
26
28
  export interface PresetOptions {
27
29
  fetch?: typeof fetch;
28
30
  headers?: Record<string, string>;
@@ -77,12 +77,18 @@ export const normalizeLlmapi = (r) => {
77
77
  ...(str(r.family) ? { publisher: labOf(str(r.family)) } : {}),
78
78
  };
79
79
  };
80
+ /** Groq lists speech, text-to-speech and safety-classifier models beside its chat models (seen 28 Oct 2026: whisper, orpheus, prompt-guard, safeguard). Those are not chat models, so they are left out. */
81
+ export const normalizeGroq = (r) => {
82
+ if (typeof r.id !== 'string' || r.active === false || /whisper|orpheus|tts|guard|embed/i.test(r.id))
83
+ return null;
84
+ return { id: r.id, ...(num(r.context_window) !== undefined ? { context_length: num(r.context_window) } : {}) };
85
+ };
80
86
  /** https://www.requesty.ai: a gateway to 800+ models, with failover between providers. `region: 'eu'` keeps prompts in the EU. */
81
87
  export const requesty = (o = {}) => openaiCompatible({ name: 'requesty', baseUrl: o.region === 'eu' ? 'https://router.eu.requesty.ai/v1' : 'https://router.requesty.ai/v1', normalize: normalizeRequesty, ...o });
82
88
  /** https://llmapi.ai: a gateway to 150+ chat models. */
83
89
  export const llmapi = (o = {}) => openaiCompatible({ name: 'llmapi', baseUrl: 'https://api.llmapi.ai/v1', normalize: normalizeLlmapi, ...o });
84
90
  /** https://groq.com: fast inference with a free developer tier. */
85
- export const groq = (o = {}) => openaiCompatible({ name: 'groq', baseUrl: 'https://api.groq.com/openai/v1', ...o });
91
+ export const groq = (o = {}) => openaiCompatible({ name: 'groq', baseUrl: 'https://api.groq.com/openai/v1', normalize: normalizeGroq, ...o });
86
92
  /** https://cerebras.ai: fast inference with a free tier. */
87
93
  export const cerebras = (o = {}) => openaiCompatible({ name: 'cerebras', baseUrl: 'https://api.cerebras.ai/v1', ...o });
88
94
  export const openai = (o = {}) => openaiCompatible({ name: 'openai', baseUrl: 'https://api.openai.com/v1', ...o });
package/package.json CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "name": "@extrafemi-ai/lodestone",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
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",
8
8
  "url": "git+https://github.com/obasaolorunfemi-ai/lodestone.git"
9
9
  },
10
- "homepage": "https://github.com/obasaolorunfemi-ai/lodestone#readme",
10
+ "homepage": "https://lodestone.extrafemi.com",
11
11
  "bugs": {
12
12
  "url": "https://github.com/obasaolorunfemi-ai/lodestone/issues"
13
13
  },
@@ -39,7 +39,8 @@
39
39
  "typecheck": "tsc --noEmit",
40
40
  "test": "vitest run",
41
41
  "prepublishOnly": "npm run typecheck && npm run typecheck:examples && npm test && npm run build",
42
- "typecheck:examples": "tsc -p tsconfig.examples.json"
42
+ "typecheck:examples": "tsc -p tsconfig.examples.json",
43
+ "site": "npm run build && node site/build.mjs"
43
44
  },
44
45
  "devDependencies": {
45
46
  "@types/node": "^22.10.0",