Interface IGMI

initialize

• initialize(persona, config): Promise<void>

• Parameters

  • persona: IPersonaDefinition
  • config: GMIBaseConfig

  Returns Promise<void>

getPersona

• getPersona(): IPersonaDefinition

• Returns IPersonaDefinition

getCurrentPrimaryPersonaId

• getCurrentPrimaryPersonaId(): string

• Returns string

getGMIId

• getGMIId(): string

• Returns string

getCurrentState

• getCurrentState(): GMIPrimeState

• Returns GMIPrimeState

processTurnStream

• processTurnStream(turnInput): AsyncGenerator<GMIOutputChunk, GMIOutput, undefined>

• Parameters

  • turnInput: GMITurnInput

  Returns AsyncGenerator<GMIOutputChunk, GMIOutput, undefined>

handleToolResult

• handleToolResult(toolCallId, toolName, resultPayload, userId, userApiKeys?, options?): Promise<GMIOutput>

• Parameters

  • toolCallId: string
  • toolName: string
  • resultPayload: ToolResultPayload
  • userId: string
  • Optional userApiKeys: Record<string, string>
  • Optional options: GMIToolResultOptions

  Returns Promise<GMIOutput>

Optional handleToolResults

• handleToolResults(toolResults, userId, userApiKeys?, options?): Promise<GMIOutput>

• Continues the turn with several tool results at once: a batch the host passes, or a pause the host answers in part. For a pause answered in part, the results hold, after the host's, one error result for each call of the pause the host left out (isError: true, errorDetails.code EXTERNAL_TOOL_NOT_RUN), so the GMI's own history answers every call of the pause before it writes again. An IGMI without it takes one result at a time: a pause answered in part continues it through handleToolResult() with the host's result alone, and a batch of several results ends the continuation with an error.

  Parameters

  • toolResults: ToolCallResult[]
  • userId: string
  • Optional userApiKeys: Record<string, string>
  • Optional options: GMIToolResultOptions

  Returns Promise<GMIOutput>

Optional hydrateConversationHistory

• hydrateConversationHistory(conversationHistory): void

• Makes conversationHistory the whole conversation history. The runtime calls it before a resume continues a pause, and before results on the paused stream continue it on a GMI whose own history holds a turn of another conversation, or that replaced the GMI the turn paused on: with the history the paused GMI held of the turn when it paused (what its getConversationHistory() returned, or the conversation's stored history before the turn and what its getLastTurnHistory() returned), with the pause's calls, when the runtime kept one, and with the conversation's stored history otherwise.

  Parameters

  • conversationHistory: ConversationMessage[]

  Returns void

Optional getConversationHistory

• getConversationHistory(): ConversationMessage[]

• The conversation history as the GMI holds it, the calls of its own tool rounds, their results and the assistant turns' thinking blocks included; hydrateConversationHistory() sets it back. With conversational persistence on, the runtime reads it when a turn stops for the host on a GMI whose history holds only that turn's conversation, and keeps it with the turn's stream for the continuation.

  Returns ConversationMessage[]

Optional getLastTurnHistory

• getLastTurnHistory(): ConversationMessage[]

• The messages of the conversation history from the input of the GMI's last turn on, as getConversationHistory() gives them: that input, the assistant turns and tool results of the turn's tool rounds, and what a tool continuation of the turn added; empty when no turn ran, or when the history no longer holds that input. With conversational persistence on, the runtime reads it when a turn stops for the host on a GMI whose history also holds a turn of another conversation, and keeps the conversation's stored history before the turn, followed by these messages, with the turn's stream for the continuation.

  Returns ConversationMessage[]

Optional replaceHistory

• replaceHistory(messages): void

• Makes messages the whole conversation history. An empty array is authoritative. GMI also drops what it recorded about the turns the new history no longer holds (the details of their trace entries, the input excerpts of their sentiment records).

  Parameters

  • messages: ConversationMessage[]

  Returns void

Optional clearHistory

• clearHistory(): void

• Empties the conversation history; GMI drops what it recorded about its turns, as for replaceHistory.

  Returns void

Optional hydrateTurnContext

• hydrateTurnContext(context): void

• Sets the turn a tool continuation goes on with: the session, conversation and organization the continuation runs under, and the sources the paused turn retrieved (ragSources), which its tool calls and reply are judged with. The runtime calls it when it calls hydrateConversationHistory(), and also when the conversation holds no history to set. A blank organization means the turn has none; an empty ragSources means it retrieved none; a field left out keeps what the GMI holds. A conversation other than the one of the GMI's last turn also drops what GMI kept for that turn (its memory scope, tool-call gate, learning preparation, model hop and sources), so the continuation starts as on a GMI built for it.

  Parameters

  • context: {
        sessionId?: string;
        conversationId?: string;
        organizationId?: string;
        ragSources?: RagRetrievedChunk[];
    }

    • Optional sessionId?: string

    • Optional conversationId?: string

    • Optional organizationId?: string

    • Optional ragSources?: RagRetrievedChunk[]

  Returns void

Optional recordUserFeedback

• recordUserFeedback(feedback): Promise<void>

• Records user feedback on this instance's session: a reasoning-trace entry and, when cognitive memory is configured, memories scoped to the user. GMIManager calls it with feedback normalized by normalizeUserFeedback. Optional so that custom IGMI implementations keep compiling.

  Parameters

  • feedback: NormalizedUserFeedback & {
        userId: string;
    }

    Normalized feedback plus the id of the user who sent it.

  Returns Promise<void>

Optional setPersonalityTrait

• setPersonalityTrait(trait, value): void

• Sets one personality trait on this instance without mutating the persona definition shared with other sessions. Used by the self-improvement adapt_personality tool. Optional so that custom IGMI implementations keep compiling; without it, personality adaptation reports that the caller could not be resolved.

  Parameters

  • trait: string

    Trait key, e.g. openness or honesty.
  • value: number

    New trait value.

  Returns void

Optional getLearnerSession

• getLearnerSession(): undefined | ILearnerSession

• The learner session this instance was built with (GMIBaseConfig.learning), or undefined when its host has no learning layer. Optional so that custom IGMI implementations keep compiling.

  Returns undefined | ILearnerSession

getReasoningTrace

• getReasoningTrace(): Readonly<ReasoningTrace>

• Returns Readonly<ReasoningTrace>

getWorkingMemorySnapshot

• getWorkingMemorySnapshot(): Promise<Record<string, any>>

• Returns Promise<Record<string, any>>

getCognitiveMemoryManager

• getCognitiveMemoryManager(): undefined | ICognitiveMemoryManager

• Returns undefined | ICognitiveMemoryManager

_triggerAndProcessSelfReflection

• _triggerAndProcessSelfReflection(): Promise<void>

• Returns Promise<void>

onMemoryLifecycleEvent

• onMemoryLifecycleEvent(event): Promise<LifecycleActionResponse>

• Parameters

  • event: MemoryLifecycleEvent

  Returns Promise<LifecycleActionResponse>

analyzeAndReportMemoryHealth

• analyzeAndReportMemoryHealth(): Promise<undefined | {
      overallStatus: "DEGRADED" | "ERROR" | "OPERATIONAL" | "LIMITED";
      workingMemoryStats?: {
          itemCount: number;
          [key: string]: any;
      };
      ragSystemStats?: {
          isHealthy: boolean;
          details?: any;
      };
      lifecycleManagerStats?: {
          isHealthy: boolean;
          details?: any;
      };
      issues?: {
          severity: "critical" | "info" | "warning";
          description: string;
          component: string;
          details?: any;
      }[];
  }>

• Returns Promise<undefined | {
      overallStatus: "DEGRADED" | "ERROR" | "OPERATIONAL" | "LIMITED";
      workingMemoryStats?: {
          itemCount: number;
          [key: string]: any;
      };
      ragSystemStats?: {
          isHealthy: boolean;
          details?: any;
      };
      lifecycleManagerStats?: {
          isHealthy: boolean;
          details?: any;
      };
      issues?: {
          severity: "critical" | "info" | "warning";
          description: string;
          component: string;
          details?: any;
      }[];
  }>

getOverallHealth

• getOverallHealth(): Promise<GMIHealthReport>

• Returns Promise<GMIHealthReport>

shutdown

• shutdown(): Promise<void>

• Returns Promise<void>

Readonly gmiId

Readonly creationTimestamp