Skip to main content

⚙️ Core & Factory

@lighthouse-ai/core holds every shared interface plus the createStorage / createEmbedder factory and the self-registration registry. It has zero network dependencies - all I/O lives in the store / embedder / engine packages.

Registry​

Stores and embedders self-register on side-effect import:

import '@lighthouse-ai/store-lighthouse' // calls registerStorage('lh-ipfs-walrus' | 'lh-ipfs-filecoin', …)
import '@lighthouse-ai/embed-local'      // calls registerEmbedder('local', …)
import '@lighthouse-ai/store-local-fs'   // registerStorage('local-fs', …)
import '@lighthouse-ai/store-s3'         // registerStorage('s3', …)
import '@lighthouse-ai/embed-keyword'    // registerEmbedder('keyword', …)

import { createStorage, createEmbedder, registeredStorages, registeredEmbedders } from '@lighthouse-ai/core'

console.log(registeredStorages())  // e.g. ['local-fs', 'lh-ipfs-walrus', 'lh-ipfs-filecoin', 's3', ...aliases]
console.log(registeredEmbedders()) // ['keyword', 'local']

createStorage(name, opts?)​

const storage = await createStorage('lh-ipfs-filecoin', { apiKey: process.env.LIGHTHOUSE_API_KEY })
const local = await createStorage('local-fs', { dir: './blobs' })
const s3 = await createStorage('s3', {}) // reads S3_* from env

Throws Unknown storage "<name>". Registered: [...] if you forgot the side-effect import. Accepted names include short aliases: walrus → lh-ipfs-walrus, filecoin → lh-ipfs-filecoin, lighthouse → follows MEMORY_NETWORK / MEMORY_STORAGE.

createEmbedder(name, opts?)​

const embedder = await createEmbedder('local')   // MiniLM, downloads ~25 MB once
const keyword = await createEmbedder('keyword')  // word-match only

For the batched engine, keyword is equivalent to passing embedder: null - zero deps, fully offline.

registerStorage / registerEmbedder​

Use these when authoring a new adapter:

import { registerStorage, registerEmbedder } from '@lighthouse-ai/core'

registerStorage('my-store', (opts) => new MyStore(opts))
registerEmbedder('my-embed', (opts) => new MyEmbedder(opts))

Factories may be sync or async.

resolveStorage / resolveEmbedder​

Used by the hosted API to honour env defaults:

  • resolveStorage(input, engine) - if input is omitted and engine is batched, defaults to lh-ipfs-filecoin (requires LIGHTHOUSE_API_KEY); if engine is memwal, returns null (relayer owns blobs).
  • resolveEmbedder(input, engine) - if omitted and engine is batched, uses MEMORY_EMBEDDER ?? 'local'; if memwal, returns null (remote embeddings in relayer).
  • Both accept either a live instance ({ uploadJson } / { embed }) or { kind, opts }.