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.

1import { createSDKStore, setNPCInfo, processNPC } from '@forbocai/core';
2import { createNodeCortex } from '@forbocai/node';
3
4const store = createSDKStore();
5const cortex = createNodeCortex('smollm2-135m');
6await cortex.init();
7
8store.dispatch(setNPCInfo({
9  id: 'npc_merchant_001',
10  persona: 'A cautious merchant who protects rare inventory.'
11}));
12
13const response = await store.dispatch(processNPC({
14  npcId: 'npc_merchant_001',
15  text: "I'd like to buy that key.",
16  apiUrl: 'https://api.forboc.ai',
17  apiKey: process.env.FORBOCAI_API_KEY,
18  cortex
19})).unwrap();
20
21console.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