World Books¶

// List world books (paginated)
const { data, total } = await spindle.world_books.list({ limit: 20, offset: 0 })

// Get a single world book
const book = await spindle.world_books.get('world-book-id')
if (book) {
  spindle.log.info(`Found: ${book.name} (${book.description})`)
}

// Create a world book
const newBook = await spindle.world_books.create({
  name: 'My Lorebook',
  description: 'Character knowledge base',
})

// Update a world book
const updated = await spindle.world_books.update(newBook.id, {
  description: 'Updated description',
})

// Delete a world book (cascades all entries)
const deleted = await spindle.world_books.delete(newBook.id)

{
  id: string
  name: string
  description: string
  metadata: Record<string, unknown>
  created_at: number   // unix epoch seconds
  updated_at: number
}

// List entries in a world book (paginated)
const { data, total } = await spindle.world_books.entries.list('world-book-id', {
  limit: 50, offset: 0,
})

// Get a single entry
const entry = await spindle.world_books.entries.get('entry-id')
if (entry) {
  spindle.log.info(`Entry: ${entry.comment} — keys: ${entry.key.join(', ')}`)
}

// Create an entry
const newEntry = await spindle.world_books.entries.create('world-book-id', {
  key: ['dragon', 'dragons'],
  keysecondary: ['fire', 'scales'],
  content: 'Dragons are ancient creatures that breathe fire.',
  comment: 'Dragon lore',
  position: 0,
  selective: true,
})

// Update an entry
const updatedEntry = await spindle.world_books.entries.update(newEntry.id, {
  content: 'Dragons are ancient, intelligent creatures that breathe fire.',
  disabled: false,
})

// Delete an entry
const entryDeleted = await spindle.world_books.entries.delete(newEntry.id)

{
  id: string
  world_book_id: string
  uid: string
  key: string[]                // primary activation keywords
  keysecondary: string[]       // secondary keywords (for selective mode)
  content: string              // the injected text
  comment: string              // human-readable label
  position: number             // injection position (0=before, 1=after, 4=depth, etc.)
  depth: number                // depth for position-based injection
  role: string | null          // "system", "user", or "assistant"
  order_value: number          // sort order within position bucket
  selective: boolean           // require secondary keys to match too
  constant: boolean            // always active (skip keyword check)
  disabled: boolean            // entry is disabled
  group_name: string           // mutual exclusion group
  group_override: boolean      // override group competition
  group_weight: number         // weight for group selection
  probability: number          // activation probability (0-100)
  scan_depth: number | null    // how many messages to scan for keywords
  case_sensitive: boolean      // case-sensitive keyword matching
  match_whole_words: boolean   // match whole words only
  automation_id: string | null // automation identifier
  use_regex: boolean           // treat keys as regex patterns
  prevent_recursion: boolean   // prevent recursive activation
  exclude_recursion: boolean   // exclude from recursion scanning
  delay_until_recursion: boolean
  priority: number             // activation priority
  sticky: number               // stay active for N turns after match
  cooldown: number             // cooldown turns after deactivation
  delay: number                // delay N turns before first activation
  selective_logic: number      // 0=AND all, 1=NOT none, 2=OR any, 3=NOT all for secondary keys
  use_probability: boolean     // whether probability field is active
  vectorized: boolean          // entry has vector embeddings
  extensions: Record<string, unknown>
  created_at: number           // unix epoch seconds
  updated_at: number
}

// Which books are globally active right now?
const globalIds = await spindle.world_books.getGlobal()

// Turn a book on globally (atomic add — safe against concurrent toggles)
await spindle.world_books.activateGlobal('world-book-id')

// Turn it off again (no-op if it wasn't active)
await spindle.world_books.deactivateGlobal('world-book-id')

// Replace the whole set at once
const applied = await spindle.world_books.setGlobal(['book-a', 'book-b'])

const activated = await spindle.world_books.getActivated('chat-id')

spindle.log.info(`${activated.length} entries activated`)

for (const entry of activated) {
  const source = entry.source === 'vector'
    ? `vector (score: ${entry.score?.toFixed(4)})`
    : 'keyword'
  spindle.log.info(`[${source}] ${entry.comment} — keys: ${entry.keys.join(', ')}`)
}