@eryv/core

Core engine for the eryv agentic AI conversation platform. Multi-provider LLM orchestration with structured persona management, branching conversations, prompt assembly, and streaming. No UI dependency — works in Node.js and browsers.

Install

npm install @eryv/core
# or
pnpm add @eryv/core

Quick Start

import {
  Engine,
  OpenAICompatibleProvider,
  ProviderRouter,
  parseCardJSON,
} from "@eryv/core";

// Set up a provider
const provider = new OpenAICompatibleProvider({
  id: "openai",
  apiKey: process.env.OPENAI_API_KEY!,
  baseUrl: "https://api.openai.com/v1",
  defaultModel: "gpt-4o",
});

const router = new ProviderRouter([provider], {
  primaryProvider: "openai",
});

// Load a character card (V2 spec)
const card = parseCardJSON(myCardJson);

// Create and run the engine
const engine = new Engine({ router, card });

engine.on("stream_chunk", (event) => {
  if (event.type === "stream_chunk") {
    process.stdout.write(event.content);
  }
});

await engine.send("Hello!");

Features

Providers

Connect to any OpenAI-compatible API or Anthropic. Built-in routing, fallback, and retry with exponential backoff.

import {
  OpenAICompatibleProvider,
  AnthropicProvider,
  ProviderRouter,
  withRetry,
} from "@eryv/core";

• OpenAICompatibleProvider — OpenAI, local servers (llama.cpp, Ollama, LM Studio), and any compatible API
• AnthropicProvider — Claude models via the Anthropic API
• ProviderRouter — primary/fallback routing between providers
• withRetry — retry wrapper with configurable backoff and error filtering

Character Cards

Full Character Card V2 spec support. Parse from JSON or PNG (embedded metadata), with extensions preserved.

import { parseCardJSON, parseCardPNG, replaceMacros } from "@eryv/core";

const card = parseCardJSON(jsonData);
const cardFromImage = parseCardPNG(pngBuffer);

const text = replaceMacros("Hello {{char}}!", { char: card.data.name });

Conversation Tree

Branching conversation history with edit/fork, regeneration (sibling branches), and full serialization.

import { ConversationTree } from "@eryv/core";

const tree = new ConversationTree({ characterId: "my-char" });
tree.addMessage({ role: "user", content: "Hello" });
tree.addMessage({ role: "assistant", content: "Hi there!" });

// Edit creates a fork — original branch is preserved
tree.editMessage(nodeId, { role: "user", content: "Hey!" });

// Serialize/restore
const saved = tree.serialize();
const restored = ConversationTree.deserialize(saved);

Prompt Assembly

Template engine with variable interpolation, conditionals, and loops. The assembler builds the final message array with system prompt, persona, conversation history, and examples — all within token budget.

import { PromptAssembler, renderTemplate } from "@eryv/core";

const assembler = new PromptAssembler(provider, assemblyConfig);
const { messages, tokenCount } = await assembler.assemble({
  card,
  conversation: tree,
  userPersona,
});

Engine

Top-level orchestrator tying everything together. Event-driven with streaming support and full session save/restore.

import { Engine, loadWithMigration } from "@eryv/core";

const engine = new Engine({ router, card, userPersona, config });

// Event-driven streaming
engine.on("stream_start", () => {});
engine.on("stream_chunk", (e) => process.stdout.write(e.content));
engine.on("stream_end", (e) => console.log(e.fullContent));
engine.on("error", (e) => console.error(e.error));

await engine.send("Tell me a story", { temperature: 0.9 });

// Save and restore sessions
const session = engine.saveSession();
const restored = Engine.fromSession(session, router);

Examples

Runnable examples in examples/core/:

| Example | What it covers | |---|---| | 01-card-parsing | JSON/PNG parsing, V2 spec, extensions, round-tripping | | 02-conversation-tree | Branching, edit/fork, regeneration, serialization | | 03-templates-and-assembly | Template engine, prompt assembler, token budgets | | 04-providers-and-streaming | Provider setup, streaming, mock server | | 05-error-handling | Error taxonomy, retry, fallback | | 06-full-engine | End-to-end: engine setup, conversation, save/restore |

Run any example:

npx tsx examples/core/01-card-parsing.ts

API Reference

Types

Core types are fully exported — see src/types.ts for the complete list, including:

• CharacterCard, CharacterBook, CharacterBookEntry — V2 card spec
• Message, CompletionRequest, CompletionResponse, StreamChunk — provider I/O
• EngineConfig, ProviderConfig, RoutingConfig, AssemblyConfig, RetryConfig — configuration
• EngineEvent, EngineEventType — event system
• SerializedTree, SerializedSession — persistence
• UserPersona — user identity

Interfaces

• IProvider — LLM provider (complete, stream, countTokens, listModels)
• IProviderRouter — Routes requests across providers
• IPromptAssembler — Builds final prompt from context

License

AGPL-3.0-only