Lodestone

Code map

Where each piece lives in src/. This is generated from the files in the repository when the site 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.

candidates.ts

model-candidates/1: the models in use, for an evaluator

catalog.ts+tests

Reads a provider's catalogue; picks and ranks models; drops withdrawn ones

discover.ts+tests

Keeps a provider's list alive and short: prune, then fill within a price limit

errors.ts

LodestoneError, ProviderError and the failure kinds

explain.ts

Turns an error into a sentence a person can read

health.ts+tests

The circuit breaker: skips models that keep failing, shared across instances

index.ts

Public exports

json.ts+tests

Strips code fences and parses; json() uses it to skip bad answers

limiter.ts

createRateLimiter: an allowance for each caller, stored as a hash

lodestone.ts+tests

The core: createLodestone, the phases, the time budget, complete() and json()

models.ts

Default free model lists per tier

rateLimit.ts+tests

Tells the four kinds of 429 apart

scorecard.ts+tests

Reads model-scorecard/1 and orders models by it

spend.ts

createSpendLimit: a daily and monthly limit that takes a hold per attempt, so a burst cannot overshoot

stats.ts+tests

Live success rate and speed per model, as a scorecard

store.ts

A key-value store: memory by default, yours to share between functions

trust.ts+tests

The trust policy: trusted labs, block list, privacy and expiry checks

types.ts

Shared types

util.ts

A hash, a mutex and shape checks, shared by the pieces above

providers/

Adapters: anthropic, google, mock, openaiCompatible, openrouter

stores/

Adapters: Netlify Blobs, Cloudflare KV, Upstash, Deno KV

python/

The Python port (alpha), with its own tests

scripts/

The smoke checks that run on Node, Workers, Deno and Bun

examples/

A Netlify function, the daily check and a multi-provider setup, all type-checked in CI

.github/workflows

Tests, builds and publishes to npm with provenance on a version tag

docs/scorecards.md

The two JSON formats in full