@geekist/llm-core

Build real AI products with recipes, interactions, and adapters.

Runtime-agnostic core for deterministic workflows and UI-ready interactions.

Docs

• Docs: https://llm-core.geekist.co
• Guide (hero path): https://llm-core.geekist.co/guide/interaction-single-turn
• API: https://llm-core.geekist.co/reference/recipes-api

Install

bun add @geekist/llm-core
pnpm add @geekist/llm-core
npm install @geekist/llm-core
yarn add @geekist/llm-core

deno add npm:@geekist/llm-core

Quick start (interaction, single turn)

import { fromAiSdkModel } from "@geekist/llm-core/adapters";
import { openai } from "@ai-sdk/openai";
import {
  createInteractionPipelineWithDefaults,
  runInteractionPipeline,
} from "@geekist/llm-core/interaction";

const model = fromAiSdkModel(openai("gpt-4o-mini"));
const pipeline = createInteractionPipelineWithDefaults();

const result = await runInteractionPipeline(pipeline, {
  input: { message: { role: "user", content: "Hello!" } },
  adapters: { model },
});

if ("__paused" in result && result.__paused) {
  throw new Error("Interaction paused.");
}

console.log(result.artefact.messages[1]?.content);

Quick start (workflow recipe)

import { recipes } from "@geekist/llm-core/recipes";
import { fromAiSdkModel } from "@geekist/llm-core/adapters";
import { openai } from "@ai-sdk/openai";

const model = fromAiSdkModel(openai("gpt-4o-mini"));
const workflow = recipes.agent().defaults({ adapters: { model } }).build();

const result = await workflow.run({ input: "Draft a short README for a new SDK." });

if (result.status === "ok") {
  console.log(result.artefact);
}

Build paths

• Production chat UI: https://llm-core.geekist.co/guide/interaction-single-turn

• Sessions + transport: https://llm-core.geekist.co/guide/interaction-sessions

• End-to-end UI: https://llm-core.geekist.co/guide/end-to-end-ui

• Workflow orchestration: https://llm-core.geekist.co/guide/hello-world

• Recipes: https://llm-core.geekist.co/recipes/simple-chat

• Adapters: https://llm-core.geekist.co/adapters/

• State validation

  • Optional recipe-level state validator:

    • Recipe.flow("rag").use(pack).state(validate).build();

  • On ok outcomes, the validator can annotate diagnostics and emit a recipe.state.invalid trace event if something looks off.

• Event conventions

  • Helper to emit recipe events into both:

    • The adapter event stream (eventStream.emit / emitMany).
    • A state.events array for later inspection in tests or tools.

• Human-in-the-loop (HITL) gate

  • Built-in hitl-gate recipe and pack:

    • Emits pause tokens and pauseKind: "human".
    • Lets you pause a flow, wait for a human decision, and resume.

• Testability

  • Runtime and helpers are designed to be extremely test-friendly.
  • The repo ships with high coverage (see Codecov badge) and static analysis (SonarCloud).

Adapters today

You can use llm-core with:

• LangChain

  • Models, embeddings, text splitters, memory, vector stores.
  • Trace integration for LangChain runs.

• LlamaIndex

  • Document stores, vector stores, embeddings, memory.

• AI SDK

  • Models and embeddings, plugged in as adapters.

• Core primitives

  • KV store
  • Cache
  • Event stream
  • Text splitter
  • Loader
  • Vector store
  • Memory

Adapters are pluggable; you can write your own functions that match the adapter types and wire in any provider you like.

See the docs site for up-to-date adapter details and examples.

Docs

• Docs site: https://llm-core.geekist.co/

• Workflow & recipes: docs/workflow-api.md, docs/reference/packs-and-recipes.md

• Adapters: docs/adapters-api.md

• Examples:

  • ETL: docs/examples/etl-pipeline.ts
  • Agent / RAG examples (and more) on the docs site

Development

bun install

# Static checks
bun run lint
bun run typecheck

# Tests
bun test

The CI pipeline also runs coverage and static analysis (Codecov + SonarCloud).

Status

Active development. APIs are reasonably stable but may still evolve as more adapters and recipes land. Check the docs site and CHANGELOG for breaking changes.

Licence

Licensed under the Apache License, Version 2.0.

See the LICENSE file for details.