useProcessManager

The useProcessManager hook provides access to an API for managing the current MentalProcess of the soul.

exampleProcess.ts

import { useProcessManager, useActions } from "@opensouls/engine";
import aDifferentMentalProcess from "./mentalProcesses/aDifferentMentalProcess"
 
const manageProcess: MentalProcess = async ({ workingMemory }) => {
  const { log } = useActions()
  const { 
    previousMentalProcess,
    invocationCount,
    wait,
    pendingScheduledEvents,
    cancelScheduledEvent,
  } = useProcessManager();
 
  log(`Coming from aDifferentMentalProcess?`, previousMentalprocess === aDifferentMentalProcess);
  log(`Invocation Count: ${invocationCount}`);
 
  await wait(500); // wait for 500 ms
 
  log("pending scheduled events: ", pendingScheduledEvents) // this is an array of scheduled pending events
  cancelScheduledEvent(pendingScheduledEvents[0].id) // cancels the pending scheduled event by id1
 
  // Continue with the rest of the mental process logic
  // ...
 
  return workingMemory;
};
 
export default manageProcess;

async wait(numberOfMiliseconds: number)

wait is an asynchronous function that pauses the execution of the current mental process for the specified number of milliseconds.

await wait(1000) // wait 1 second

previousMentalProcess

previousMentalProcess holds a reference to the mental process that was executed before the current one. This is particularly useful for managing state transitions and understanding the flow of mental processes within a soul. By accessing previousMentalProcess, developers can make decisions based on what the soul was previously thinking or doing, allowing for more nuanced and context-aware mental process management.

If the current mental process has been invoked more than once the previousMentalProcess will continue to hold a reference to the older (different) mental process. If this mental process is the initialProcess then previousMentalProcess is undefined.

invocationCount

The invocationCount is a number that represents the count of invocations of a mental process

ℹ️

The invocation count resets whenever the soul transitions to a new MentalProcess.

pendingScheduledEvents

pendingScheduledEvents returns an array sorted by soonest to latest of PendingCognitiveEvent.

  export interface PendingCognitiveEvent {
    // The id of the event, which is used to cancel the event.
    id: string
    // when the event will fire
    when: Date
    // which mental process will handle the event
    process: MentalProcess<any>
    // the perception associated with the event
    perception: InternalPerception
    // optional params to pass to the mental process
    params?: Json
  }

cancelScheduledEvent

cancelScheduledEvent will cancel a PendingCognitiveEvent using an id. An id is obtained from examining the list of pendingScheduledEvents or from storing the id returned from scheduleEvent

Putting it all together

Here's an example process that makes use of the invocationCount and a switch into a different mentalProcess in order to define a compelling stateful behavior:

provokesSpeaker.js

import { MentalProcess, useProcessManager, useActions } from "@opensouls/engine";
import { brainstorm, decision, externalDialog, mentalQuery } from "./lib/cognitiveSteps.js";
import playsVictim from "./playsVictim.js";
 
const provokesSpeaker: MentalProcess = async ({ workingMemory }) => {
  const { speak } = useActions()
  const { invocationCount } = useProcessManager()
 
  let response;
  // compute a line of dialog
  [workingMemory, response] = await externalDialog(workingMemory, "Try to provoke the speaker")
  speak(response)
 
  // decide if it's time to move on
  const [, didProvokeTheUser] = await mentalQuery(workingMemory, "Has samantha successfully provoked the speaker?")
 
 
  // move to a new mental process if the soul decides it's time to move on
  // and it's not the first invocation
  if (didProvokeTheUser && invocationCount > 0) {
    // schedule the next mental process via reference to playsVictim
    return [workingMemory, playsVictim]
  }
 
  return workingMemory
}
 
export default provokesSpeaker

useProcessMemory useSoulMemory