Foil Engine TypeScript SDK

TypeScript SDK for the Foil Engine NPC API. Add AI-powered NPC conversations to your Node.js, web, Deno, or Bun project.

Installation

npm install @foilengine/sdk

Quick Start

import { FoilEngineClient } from '@foilengine/sdk';

const client = new FoilEngineClient({
  apiKey: 'pk_live_...',
  llmApiKey: 'sk-...',   // your LLM provider API key
  llmModel: 'gpt-4o',    // any LiteLLM-supported model
});

// Discover your personas
const personas = await client.personas.list();

// Initialize a session
const session = await client.chat.initSession(personas[0].id, {
  userSessionId: 'player-001',
  playerName: 'Alex',
  playerGender: 'non-binary',
});
console.log(session.message); // NPC's greeting

// Send a message
const response = await client.chat.sendMessage(personas[0].id, {
  message: 'What do you recommend?',
  userSessionId: 'player-001',
});
console.log(response.message);       // NPC's reply
console.log(response.current_state); // State machine state
console.log(response.score);         // Session score

Configuration

const client = new FoilEngineClient({
  apiKey: 'pk_live_...',             // required
  llmApiKey: 'sk-...',              // required – your LLM provider API key
  llmModel: 'gpt-4o',              // optional – default LLM model
  baseUrl: 'http://localhost:8000',  // default: https://api.foilengine.io
  timeout: 30000,                    // default: 30000ms
  maxRetries: 3,                     // default: 3
});

LLM Configuration (BYOK)

SDK chat endpoints require your own LLM API key. Foil Engine uses LiteLLM under the hood, so any supported provider and model string works.

// Override models per pipeline step
const client = new FoilEngineClient({
  apiKey: 'pk_live_...',
  llmApiKey: 'sk-...',
  llmModel: 'gpt-4o',
  llmEvalModel: 'gpt-4o-mini',          // cheaper model for evaluation
  llmResponseModel: 'gpt-4o',           // main model for NPC responses
  llmSummarizationModel: 'gpt-4o-mini', // cheaper model for summaries
});

Documentation

Full documentation at foilengine.io/docs/sdk/typescript

License

MIT