JavaScript library

import { createLibrarium } from 'librarium';

const librarium = createLibrarium();
const question = 'Compare database providers';
const plan = await librarium.research(question, {
  only: ['exa'], dryRun: true,
});
const started = await librarium.research(question, {
  depth: 'deep', only: ['exa'],
  maxCost: '1.00', wait: false,
});
const later = await librarium.get(started.id, { wait: true });
librarium.sources();
if (later !== null) {
  const summary = await librarium.summarize(later);
}

research waits by default. With wait: false, durable work can be finished through get; quick inline work still depends on its process. summarize is a separate budgeted Run with summary_of, not a mutation of the source Run.

Import boundaries

Import	Responsibility
librarium	Node client with v3 config and filesystem storage
librarium/node	Same client plus filesystem store and config loading/saving
librarium/core	Runtime-neutral client; inject config/environment/store, memory by default
librarium/testing	Disposable-store runStoreContract

The root is Node-oriented. Use librarium/core for Workers or browsers; it does not inspect process state or files on import. Preserve a persistent custom client’s handleKey (32 random bytes) outside its store across restarts.

Public Run

JSON uses snake_case, JS options camelCase. The Run records spec, id, question, depth, status, timestamps, cost, results, skipped, and notices. Run status is planned, running, done, partial, or failed; results have queued, running, done, or failed.

Each result keeps a source, observation, Markdown answer, citations, cost, and provenance (provider, variant, model, and retrieval service). Errors are safe { code, message, retryable } values. See costs and limits for money fields and unknown charges.

The shared librarium-spec package owns schemas, source catalog, and semantic fixtures. It does not make private runtimes or task handles interchangeable. See output and evidence.