Skip to navigation
Getting Started

Introduction

Store/thunk runtime for autonomous NPC protocol execution
View as Markdown

ForbocAI sdk@0.6.3 is a Redux Toolkit-based runtime for executing the NPC multi-round protocol.

This page reflects the current SDK source (packages/core, packages/node, packages/browser) and CLI implementation, not legacy factory APIs.

What the SDK Is

  • @forbocai/core: protocol types, API client slice, state slices, and thunks
  • @forbocai/node: Node runtime slices + createNodeCortex() + CLI (forbocai)
  • @forbocai/browser: browser runtime slices/thunks for WebLLM + memory/vector state

Canonical Runtime Pattern

For core integration, create a store, register NPC metadata, then dispatch protocol thunks.

import { createSDKStore, setNPCInfo, processNPC } from '@forbocai/core';
import { createNodeCortex } from '@forbocai/node';
const store = createSDKStore();
const cortex = createNodeCortex('smollm2-135m');
await cortex.init();
store.dispatch(setNPCInfo({
  id: 'npc_merchant_001',
  persona: 'A cautious merchant who protects rare inventory.'
}));
const response = await store.dispatch(processNPC({
  npcId: 'npc_merchant_001',
  text: "I'd like to buy that key.",
  apiUrl: 'https://api.forboc.ai',
  apiKey: process.env.FORBOCAI_API_KEY,
  cortex
})).unwrap();
console.log(response.dialogue);

Protocol Flow (Implemented)

processNPC executes the multi-round API-directed loop:

Primary path (current SDK runtime):

  1. POST /npcs/{npcId}/process with { tape, lastResult }
  2. execute returned instruction locally (identify actor / recall / infer)
  3. repeat /process until finalize instruction is returned
  4. apply finalize memory store + state delta instructions

Compatibility path (also supported by API):

  1. POST /npcs/{npcId}/directive
  2. local memory recall (only if instructed)
  3. POST /npcs/{npcId}/context
  4. local cortex completion
  5. POST /npcs/{npcId}/verdict
  6. local memory store + state delta application

The SDK fails fast when required runtime components are missing (persona, cortex, and memory when API requires memory operations).

CLI Quick Start

# health/config
npx forbocai status
npx forbocai doctor
npx forbocai config set apiUrl https://api.forboc.ai
# npc lifecycle
npx forbocai npc create "A suspicious innkeeper"
npx forbocai npc process <npcId> "Do you have rooms?"
# memory/bridge/soul/ghost
npx forbocai memory list <npcId>
npx forbocai bridge rules
npx forbocai soul list
npx forbocai ghost history

Next Pages