@thetabase/core/dist/index.d.ts

The core cognition engine for Thetabase.

/**
 * Core cognitive building blocks for Thetabase
 *
 * This module defines the structured data types that represent
 * an agent's mental state, beliefs, questions, plans, and thoughts.
 * All types are designed to be serializable, type-safe, and auditable.
 */
/**
 * Base interface for all cognitive objects
 */
interface CognitiveObject {
    /** Unique identifier for this object */
    readonly id: string;
    /** ISO timestamp when this object was created */
    readonly created: string;
    /** ISO timestamp when this object was last updated (optional) */
    readonly updated?: string;
}
/**
 * Confidence level for beliefs and claims
 */
type ConfidenceLevel = 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'very_low' | 'uncertain';
/**
 * Provenance information for beliefs
 */
interface Provenance {
    /** Source of this belief (e.g., 'llm_reasoning', 'user_input', 'tool_result') */
    readonly source: string;
    /** Additional context about how this belief was formed */
    readonly context?: string;
    /** Timestamp when this belief was established */
    readonly established: string;
    /** Optional reference to related thought log entries */
    readonly thoughtLogIds?: readonly string[];
}
/**
 * A claim held by the agent with confidence and provenance
 */
interface Belief extends CognitiveObject {
    /** The claim or statement being believed */
    readonly claim: string;
    /** Confidence level in this belief */
    readonly confidence: ConfidenceLevel;
    /** How this belief was formed */
    readonly provenance: Provenance;
    /** Optional tags for categorization */
    readonly tags?: readonly string[];
    /** Optional evidence supporting this belief */
    readonly evidence?: readonly string[];
}
/**
 * An unresolved inquiry or question the agent is considering
 */
interface Question extends CognitiveObject {
    /** The question being asked */
    readonly question: string;
    /** Current status of this question */
    readonly status: 'open' | 'investigating' | 'answered' | 'abandoned';
    /** Optional priority level */
    readonly priority?: 'low' | 'medium' | 'high' | 'critical';
    /** Related beliefs that inform this question */
    readonly relatedBeliefIds?: readonly string[];
    /** Optional context about why this question matters */
    readonly context?: string;
    /** Optional answer if status is 'answered' */
    readonly answer?: string;
}
/**
 * A structured goal or subgoal with execution status
 */
interface PlanStep extends CognitiveObject {
    /** Description of what this step accomplishes */
    readonly description: string;
    /** Current execution status */
    readonly status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled';
    /** Optional parent plan step ID for hierarchical plans */
    readonly parentId?: string;
    /** Child plan steps */
    readonly childIds?: readonly string[];
    /** Dependencies that must be completed first */
    readonly dependencies?: readonly string[];
    /** Optional result or outcome */
    readonly result?: string;
    /** Optional error message if status is 'failed' */
    readonly error?: string;
}
/**
 * Type of thought log entry
 */
type ThoughtLogType = 'llm_reasoning' | 'tool_use' | 'user_input' | 'system_event' | 'belief_update' | 'plan_update';
/**
 * A log entry recording thoughts, tool use, user edits, etc.
 */
interface ThoughtLogEntry extends CognitiveObject {
    /** Type of thought log entry */
    readonly type: ThoughtLogType;
    /** The content or message */
    readonly content: string;
    /** Optional metadata specific to the type */
    readonly metadata?: Record<string, unknown>;
    /** Related cognitive object IDs */
    readonly relatedIds?: readonly string[];
    /** Optional user or agent identifier */
    readonly actor?: string;
}
/**
 * The complete mental state of an agent
 */
interface AgentState extends CognitiveObject {
    /** All beliefs held by the agent */
    readonly beliefs: readonly Belief[];
    /** All questions the agent is considering */
    readonly questions: readonly Question[];
    /** All plan steps */
    readonly plan: readonly PlanStep[];
    /** All thought log entries */
    readonly logs: readonly ThoughtLogEntry[];
    /** Optional agent metadata */
    readonly metadata?: Record<string, unknown>;
}
/**
 * A partial update to any portion of AgentState
 */
interface AgentDelta {
    /** Optional beliefs to add or update */
    readonly beliefs?: readonly Belief[];
    /** Optional questions to add or update */
    readonly questions?: readonly Question[];
    /** Optional plan steps to add or update */
    readonly plan?: readonly PlanStep[];
    /** Optional log entries to append */
    readonly logs?: readonly ThoughtLogEntry[];
    /** Optional metadata updates */
    readonly metadata?: Record<string, unknown>;
}
/**
 * Type guard to check if an object is a Belief
 */
declare function isBelief(obj: unknown): obj is Belief;
/**
 * Type guard to check if an object is a Question
 */
declare function isQuestion(obj: unknown): obj is Question;
/**
 * Type guard to check if an object is a PlanStep
 */
declare function isPlanStep(obj: unknown): obj is PlanStep;
/**
 * Type guard to check if an object is a ThoughtLogEntry
 */
declare function isThoughtLogEntry(obj: unknown): obj is ThoughtLogEntry;
/**
 * Type guard to check if an object is an AgentState
 */
declare function isAgentState(obj: unknown): obj is AgentState;
/**
 * Type guard to check if an object is an AgentDelta
 */
declare function isAgentDelta(obj: unknown): obj is AgentDelta;

/**
 * State management for Thetabase agent cognition
 *
 * This module provides pure functions for updating agent state
 * through delta operations, ensuring immutability and idempotency.
 */

/**
 * Apply a delta to an agent state, returning a new state object
 *
 * This function is idempotent - reapplying the same delta will not
 * change the result. It handles different field types appropriately:
 *
 * - logs: append only
 * - beliefs, questions, plan: merge or replace by id
 * - metadata: shallow merge
 *
 * @param state The current agent state
 * @param delta The delta to apply
 * @returns A new agent state with the delta applied
 */
declare function applyDelta(state: AgentState, delta: AgentDelta): AgentState;
/**
 * Create an empty agent state
 *
 * @param id Optional ID for the agent state (defaults to 'agent')
 * @returns A new empty agent state
 */
declare function createEmptyAgentState(id?: string): AgentState;
/**
 * Check if two agent states are equal
 *
 * @param state1 First agent state
 * @param state2 Second agent state
 * @returns True if the states are equal
 */
declare function areStatesEqual(state1: AgentState, state2: AgentState): boolean;
/**
 * Get a belief by ID
 *
 * @param state The agent state
 * @param id The belief ID
 * @returns The belief or undefined if not found
 */
declare function getBeliefById(state: AgentState, id: string): Belief | undefined;
/**
 * Get a question by ID
 *
 * @param state The agent state
 * @param id The question ID
 * @returns The question or undefined if not found
 */
declare function getQuestionById(state: AgentState, id: string): Question | undefined;
/**
 * Get a plan step by ID
 *
 * @param state The agent state
 * @param id The plan step ID
 * @returns The plan step or undefined if not found
 */
declare function getPlanStepById(state: AgentState, id: string): PlanStep | undefined;
/**
 * Get all beliefs with a specific tag
 *
 * @param state The agent state
 * @param tag The tag to search for
 * @returns Array of beliefs with the specified tag
 */
declare function getBeliefsByTag(state: AgentState, tag: string): readonly Belief[];
/**
 * Get all questions with a specific status
 *
 * @param state The agent state
 * @param status The status to filter by
 * @returns Array of questions with the specified status
 */
declare function getQuestionsByStatus(state: AgentState, status: Question['status']): readonly Question[];
/**
 * Get all plan steps with a specific status
 *
 * @param state The agent state
 * @param status The status to filter by
 * @returns Array of plan steps with the specified status
 */
declare function getPlanStepsByStatus(state: AgentState, status: PlanStep['status']): readonly PlanStep[];
/**
 * Get thought log entries by type
 *
 * @param state The agent state
 * @param type The type to filter by
 * @returns Array of thought log entries with the specified type
 */
declare function getLogsByType(state: AgentState, type: ThoughtLogEntry['type']): readonly ThoughtLogEntry[];
/**
 * Get the most recent thought log entries
 *
 * @param state The agent state
 * @param count Number of entries to return (default: 10)
 * @returns Array of the most recent thought log entries
 */
declare function getRecentLogs(state: AgentState, count?: number): readonly ThoughtLogEntry[];

export { type AgentDelta, type AgentState, type Belief, type CognitiveObject, type ConfidenceLevel, type PlanStep, type Provenance, type Question, type ThoughtLogEntry, type ThoughtLogType, applyDelta, areStatesEqual, createEmptyAgentState, getBeliefById, getBeliefsByTag, getLogsByType, getPlanStepById, getPlanStepsByStatus, getQuestionById, getQuestionsByStatus, getRecentLogs, isAgentDelta, isAgentState, isBelief, isPlanStep, isQuestion, isThoughtLogEntry };