Lodestone keeps
your AI calls pointing
somewhere that works.

Six ways a cheap AI call breaks

Free and low-cost models come and go, and gateways have bad days. Every tool that calls them ends up rewriting the same defensive code. Lodestone does it once, for all your tools.

Pick a bad day and see what Lodestone does

A call runs through up to three phases until one answers: OpenRouter's free models, a low-cost paid model, then your fallback providers. These are the real rules; the timings and model names are illustrative, except where a scenario says it was measured.

What one bad day looked like

On 28 October 2026 the free OpenRouter models behind a real tool stopped answering, and scoring a job posting ran its whole 24 s budget and failed. These are the measurements that changed how Lodestone's defaults work. One day, one posting and one CV, so read them as an example, not a benchmark.

So reasoning is set per model (openrouter({ reasoning })), a paid-first mode exists (paidFirst), and the free models become the backup. The result for that tool: reading a posting in 2.6–3.1 s and scoring in 4.5–4.9 s, instead of failing after 24 s.

Other providers, each with its own key

Any service that speaks OpenAI's chat API works through openaiCompatible(), and presets exist for the ones Lodestone has been checked against. Here is exactly how far each check went.

"Model list read" means Lodestone's reader was run against the service's real public list and parsed it correctly. No chat call was made to a service without a key, so those paths are tested against fakes of the documented request, not against the service itself. Requesty and LLM API have no free models; they add redundancy on the paid path. Free redundancy comes from providers with free tiers, such as Groq and Cerebras, whose terms Lodestone has not checked.

Discovery that never makes a request slower

A model list that nobody edits goes stale; one that fills itself can grow until it is slow, or admit something you would not choose. Lodestone does the first and bounds the second.

Illustrative: a pool of eight. The two that are down are skipped; the next three live ones are tried.

What the trust policy decides

Verdicts are computed by the library's own vet() as this page is built, on rows shaped like real lists. On 28 Oct 2026, of Requesty's 807 chat models, 205 came from a lab not on the default list and 9 were marked as trained on. LLM API publishes nothing about what happens to prompts, so under a strict policy none of its models can be discovered; models you name yourself still work.

What this is not. There is no vulnerability database for hosted AI models, so Lodestone does not claim to scan one. It checks what providers actually publish, and enforces your rules on it. Those facts are self-reported by providers. SECURITY.md lists exactly what is and is not checked.

Eleven kinds of failure, each with its own advice

complete() and json() throw a LodestoneError with one of these kind values. Tap one to read the sentence explain(err, { product: 'MyApp', settingsHint: 'in Settings' }) gives a person.

The sentences are the library's own: this page calls explain() for each kind when it is built, so they cannot drift from the code.

Scorecards: let measurements choose the order

Two small JSON formats let an evaluator and Lodestone feed each other without sharing code. Naija Eval, which measures translation and speech quality for Hausa, Igbo and Yoruba, is the first to use them. Its scores are translation quality, so they help tasks in those languages, not every task.

• A scorecard only changes the order models are tried in. Nothing is added or dropped.
• Scores from fewer than 30 items, or over a year old, are ignored.
• Unmeasured models keep their slot, so a good unmeasured model is never pushed down.
• An explicit route is never reordered.
• If the scorecard fetch fails or takes over 1.5 s, the order is left alone.
• Live stats keep the last 200 attempts per model and never see prompts or answers.

What a tool writes

// set up once, and share the store
const ai = createLodestone({
  openrouter: { apiKey: OPENROUTER_KEY,
    allowPaid: true, paidFirst: true,
    paidModels: ['anthropic/claude-haiku-5.5'],
    reasoning: (m) => m.startsWith('anthropic/')
      ? { enabled: false } : { effort: 'low', exclude: true } },
  fallbacks: [
    { provider: requesty(), apiKey: REQUESTY_KEY,
      models: ['bedrock/claude-haiku-5-5'],
      discover: { fill: { maxPromptUsdPerMTok: 1,
                          maxCompletionUsdPerMTok: 5 } } },
    { provider: groq(), apiKey: GROQ_KEY,
      models: ['llama-3.3-70b-versatile'], free: true },
  ],
  store, health: createHealth({ store }),
  spend: { allow: underDailyLimit, record: addToLedger },
  trust: { requireNoTraining: true },
});

// each call names a task, not a model
try {
  const { data } = await ai.json({
    prompt, validate: isJob, signal: req.signal,
    private: true });   // a CV: do not keep or train on it
} catch (err) {
  return explain(err, { product: 'MyApp' });
}

What it does not do yet

Where each piece lives in src/

Generated from the files in the repository when this page is built. +tests marks a file with its own test file; the others are covered by a shared one or by the call-path tests.