@forbocai/core 0.4.4

package/dist/index.d.mts

@@ -0,0 +1,597 @@
+/**
+ * ForbocAI Core Types
+ * The foundational interfaces for the Neuro-Symbolic Protocol.
+ */
+interface CortexConfig {
+    /** The model to load (e.g., 'smollm2-135m', 'llama3-8b-q4') */
+    model: string;
+    /** Optional overrides for model parameters */
+    temperature?: number;
+    maxTokens?: number;
+    gpu?: boolean;
+    /** Connection Config */
+    authKey?: string;
+    apiUrl?: string;
+}
+interface CortexStatus {
+    id: string;
+    model: string;
+    ready: boolean;
+    engine: 'mock' | 'remote' | 'node-llama-cpp' | 'web-llm';
+}
+interface ICortex {
+    init(): Promise<CortexStatus>;
+    complete(prompt: string, options?: CompletionOptions): Promise<string>;
+    completeStream(prompt: string, options?: CompletionOptions): AsyncGenerator<string>;
+}
+interface CompletionOptions {
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+    jsonSchema?: object;
+}
+type Mood = string;
+interface AgentState {
+    [key: string]: unknown;
+}
+interface AgentConfig {
+    id: string;
+    cortex: ICortex;
+    memory: any;
+    persona: string;
+    initialState?: Partial<AgentState>;
+    memoryConfig?: MemoryConfig;
+    apiUrl?: string;
+}
+interface AgentResponse {
+    dialogue: string;
+    action?: AgentAction;
+    thought?: string;
+}
+type MemoryType = string;
+interface MemoryConfig {
+    /** Decay strategy: 'none' | 'temporal' */
+    decay?: 'none' | 'temporal';
+    /** Max memories to keep in active context during retrieval */
+    maxContextWindow?: number;
+}
+interface MemoryItem {
+    id: string;
+    text: string;
+    embedding?: number[];
+    timestamp: number;
+    type: MemoryType;
+    importance: number;
+}
+interface Observation {
+    type: 'event' | 'state' | 'request';
+    timestamp: number;
+    agentId?: string;
+    gameId?: string;
+    content: string;
+    data?: Record<string, unknown>;
+    context?: Record<string, unknown>;
+}
+interface Directive {
+    type: 'system-prompt' | 'action-constraints' | 'behavior-rules' | 'thought';
+    content: string;
+    constraints?: Record<string, unknown>;
+    priority?: 'high' | 'normal' | 'low';
+    expiresAt?: number;
+}
+interface AgentAction {
+    type: string;
+    target?: string;
+    payload?: Record<string, unknown>;
+    reason?: string;
+    confidence?: number;
+    signature?: string;
+}
+interface ValidationContext {
+    agentState?: Record<string, unknown>;
+    worldState?: Record<string, unknown>;
+    constraints?: Record<string, unknown>;
+}
+interface ValidationResult {
+    valid: boolean;
+    reason?: string;
+    correctedAction?: AgentAction;
+}
+interface ValidationRule {
+    id: string;
+    name: string;
+    description: string;
+    actionTypes: string[];
+    validate: (action: AgentAction, context: ValidationContext) => ValidationResult;
+}
+interface Soul {
+    id: string;
+    version: string;
+    name: string;
+    persona: string;
+    memories: MemoryItem[];
+    state: AgentState;
+    signature?: string;
+}
+
+/**
+ * Interface for Agent operations
+ */
+/**
+ * Interface for Agent operations
+ */
+interface IAgent {
+    /**
+     * Processes an input string with optional context to generate a response.
+     * @param input - The input string from the user or system.
+     * @param context - Optional context data to influence the agent's response.
+     * @returns A promise that resolves to the agent's response.
+     */
+    process(input: string, context?: Record<string, unknown>): Promise<AgentResponse>;
+    /**
+     * Retrieves the current state of the agent.
+     * @returns The current AgentState.
+     */
+    getState(): AgentState;
+    /**
+     * Updates the agent's state.
+     * @param newState - The new state to set.
+     */
+    setState(newState: AgentState): void;
+    /**
+     * Exports the agent's data to a Soul object.
+     * @returns A promise resolving to the Soul representation of the agent.
+     */
+    export(): Promise<Soul>;
+}
+/**
+ * Pure function to create initial agent state
+ * @param partial - Optional partial state to initialize with.
+ * @returns The initialized AgentState.
+ */
+declare const createInitialState: (partial?: Partial<AgentState>) => AgentState;
+/**
+ * Pure function to update agent state
+ * Returns new state without mutating original
+ * @param currentState - The current state of the agent.
+ * @param updates - The updates to apply to the state.
+ * @returns A new AgentState object with the updates applied.
+ */
+declare const updateAgentState: (currentState: AgentState, updates: Partial<AgentState>) => AgentState;
+/**
+ * Pure function to process input and generate response
+ * @param currentState - The current state of the agent.
+ * @param input - The input string to process.
+ * @param context - Optional context data.
+ * @returns The agent's response including dialogue and action.
+ */
+declare const processAgentInput: (currentState: AgentState, input: string, context?: Record<string, unknown>) => AgentResponse;
+/**
+ * Pure function to export agent to Soul
+ * @param agentId - The ID of the agent.
+ * @param name - The name of the agent.
+ * @param persona - The persona description of the agent.
+ * @param state - The current state of the agent.
+ * @param memories - The list of memories associated with the agent.
+ * @returns A Soul object representing the agent.
+ */
+declare const exportToSoul: (agentId: string, name: string, persona: string, state: AgentState, memories: MemoryItem[]) => Soul;
+/**
+ * Factory function to create Agent (Functional/Closure based)
+ * @param config - The configuration object for creating the agent.
+ * @returns An instance of IAgent.
+ */
+declare const createAgent: (config: AgentConfig) => IAgent;
+/**
+ * Pure function to import Agent from Soul
+ * @param soul - The Soul object to import from.
+ * @param cortex - The Cortex instance for the agent.
+ * @param memory - Optional memory instance.
+ * @returns An instantiated IAgent.
+ */
+declare const fromSoul: (soul: Soul, cortex: ICortex, memory?: any) => Promise<IAgent>;
+
+/**
+ * Bridge configuration
+ */
+interface BridgeConfig {
+    /** Base URL for the API. */
+    apiUrl?: string;
+    /** If true, reject any unknown action types. */
+    strictMode?: boolean;
+    /** Custom validation rules to apply. */
+    customRules?: ValidationRule[];
+}
+/**
+ * Interface for Bridge operations
+ */
+interface IBridge {
+    /**
+     * Validates an agent action against registered rules.
+     * @param action - The action to validate.
+     * @param context - Optional validation context.
+     * @returns A promise that resolves to the validation result.
+     */
+    validate(action: AgentAction, context?: ValidationContext): Promise<ValidationResult>;
+    /**
+     * Registers a new validation rule.
+     * @param rule - The rule to register.
+     */
+    registerRule(rule: ValidationRule): void;
+    /**
+     * Lists all registered validation rules.
+     * @returns An array of ValidationRule objects.
+     */
+    listRules(): ValidationRule[];
+    /**
+     * Removes a validation rule by its ID.
+     * @param ruleId - The ID of the rule to remove.
+     * @returns True if the rule was removed, false otherwise.
+     */
+    removeRule(ruleId: string): boolean;
+}
+/**
+ * Factory function to create Bridge instance (Functional/Closure based)
+ * @param config - Optional configuration for the Bridge.
+ * @returns An instance of IBridge.
+ */
+declare const createBridge: (config?: BridgeConfig) => IBridge;
+/**
+ * Pure function to validate action (standalone, no class needed)
+ * @param action - The action to validate.
+ * @param rules - The list of rules to validate against.
+ * @param context - Optional validation context.
+ * @returns The result of the validation.
+ */
+declare const validateAction: (action: AgentAction, rules: readonly ValidationRule[], context?: ValidationContext) => ValidationResult;
+
+/**
+ * Soul export configuration
+ */
+interface SoulExportConfig {
+    /** API URL for remote upload/pinning */
+    apiUrl?: string;
+    /** Include memories in export */
+    includeMemories?: boolean;
+    /** Private key for signing/uploading directly to Arweave via Irys */
+    privateKey?: string;
+    /** RPC URL for Irys (defaults to https://node1.irys.xyz) */
+    irysUrl?: string;
+    /** Token/Currency (default: 'solana') */
+    token?: string;
+}
+/**
+ * Soul export result
+ */
+interface SoulExportResult {
+    /** Arweave Transaction ID (TXID) */
+    txId: string;
+    /** Gateway URL to access the soul. */
+    url: string;
+    /** The exported Soul object. */
+    soul: Soul;
+}
+/**
+ * Soul import configuration
+ */
+interface SoulImportConfig {
+    /** API URL for retrieval */
+    apiUrl?: string;
+    /** Gateway URL for Arweave (defaults to https://gateway.irys.xyz) */
+    gatewayUrl?: string;
+}
+/**
+ * Interface for Soul operations
+ */
+interface ISoul {
+    /**
+     * Exports the Soul to Arweave.
+     * @param config - Export configuration.
+     * @returns A promise resolving to the export result.
+     */
+    export(config?: SoulExportConfig): Promise<SoulExportResult>;
+    /**
+     * Returns the raw Soul data object.
+     * @returns The Soul object.
+     */
+    toJSON(): Soul;
+}
+/**
+ * Pure function to create a Soul from agent data
+ */
+declare const createSoul: (id: string, name: string, persona: string, state: AgentState, memories?: MemoryItem[]) => Soul;
+/**
+ * Pure function to serialize Soul to JSON string
+ */
+declare const serializeSoul: (soul: Soul) => string;
+/**
+ * Pure function to deserialize Soul from JSON string
+ */
+declare const deserializeSoul: (json: string) => Soul;
+/**
+ * Pure function to upload Soul to Arweave via Irys
+ */
+declare const uploadToArweave: (soul: Soul, config: SoulExportConfig) => Promise<SoulExportResult>;
+/**
+ * Export agent Soul to Arweave (Irys or API)
+ */
+declare const exportSoul: (agentId: string, soul: Soul, config?: SoulExportConfig) => Promise<SoulExportResult>;
+/**
+ * Import Soul from Arweave by TXID
+ */
+declare const importSoulFromArweave: (txId: string, config?: SoulImportConfig) => Promise<Soul>;
+/**
+ * Soul entry in the listing
+ */
+interface SoulListEntry {
+    txId: string;
+    name: string;
+    agentId?: string;
+    exportedAt: string;
+    url: string;
+}
+/**
+ * Get list of all exported Souls
+ */
+declare const getSoulList: (limit?: number, apiUrl?: string) => Promise<SoulListEntry[]>;
+/**
+ * Factory function to create Soul instance
+ */
+declare const createSoulInstance: (id: string, name: string, persona: string, state: AgentState, memories?: MemoryItem[], initialApiUrl?: string) => ISoul;
+/**
+ * Pure function to validate a Soul object
+ */
+declare const validateSoul: (soul: Soul) => {
+    valid: boolean;
+    errors: string[];
+};
+
+/**
+ * Ghost test configuration
+ */
+/**
+ * Ghost test configuration
+ */
+interface GhostConfig {
+    /** API URL for ghost orchestration */
+    apiUrl?: string;
+    /** Test suite to run */
+    testSuite: 'exploration' | 'combat' | 'dialogue' | 'pathfinding' | 'full';
+    /** Maximum duration in seconds */
+    duration: number;
+    /** Capture screenshots on failure */
+    captureScreenshots?: boolean;
+    /** Custom test parameters */
+    params?: Record<string, unknown>;
+}
+/**
+ * Ghost session status
+ */
+/**
+ * Ghost session status
+ */
+interface GhostStatus {
+    /** The unique ID of the session. */
+    sessionId: string;
+    /** The current status of the session. */
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    /** Progress percentage (0-100). */
+    progress: number;
+    /** ISO timestamp when the session started. */
+    startedAt: string;
+    /** Duration in seconds elapsed. */
+    duration: number;
+    /** Number of errors encountered. */
+    errors: number;
+}
+/**
+ * Individual test result
+ */
+/**
+ * Individual test result
+ */
+interface GhostTestResult {
+    /** Name of the test case. */
+    name: string;
+    /** Whether the test passed. */
+    passed: boolean;
+    /** Duration of the test in milliseconds. */
+    duration: number;
+    /** Error message if the test failed. */
+    error?: string;
+    /** URL or path to a screenshot if captured. */
+    screenshot?: string;
+}
+/**
+ * Complete session results
+ */
+/**
+ * Complete session results
+ */
+interface GhostResults {
+    /** The session ID. */
+    sessionId: string;
+    /** Total number of tests run. */
+    totalTests: number;
+    /** Number of passed tests. */
+    passed: number;
+    /** Number of failed tests. */
+    failed: number;
+    /** Number of skipped tests. */
+    skipped: number;
+    /** Total duration in milliseconds. */
+    duration: number;
+    /** List of individual test results. */
+    tests: GhostTestResult[];
+    /** Code/Feature coverage (0.0-1.0). */
+    coverage: number;
+    /** Additional metrics collected during the session. */
+    metrics: Record<string, number>;
+}
+/**
+ * Interface for Ghost operations
+ */
+/**
+ * Interface for Ghost operations
+ */
+interface IGhost {
+    /**
+     * Starts a Ghost session.
+     * @returns A promise resolving to the session ID.
+     */
+    run(): Promise<string>;
+    /**
+     * Gets the current status of the session.
+     * @returns A promise resolving to the GhostStatus.
+     */
+    status(): Promise<GhostStatus>;
+    /**
+     * Gets the results of the session.
+     * @returns A promise resolving to the GhostResults.
+     */
+    results(): Promise<GhostResults>;
+    /**
+     * Stops the current session.
+     */
+    stop(): Promise<void>;
+    /**
+     * Waits for the session to complete.
+     * @param pollIntervalMs - Polling interval in milliseconds.
+     * @param timeoutMs - Timeout in milliseconds.
+     * @param onProgress - Optional callback for progress updates.
+     * @returns A promise resolving to the GhostResults.
+     */
+    waitForCompletion(pollIntervalMs?: number, timeoutMs?: number, onProgress?: (status: GhostStatus) => void): Promise<GhostResults>;
+}
+/**
+ * Start a Ghost testing session
+ * @param config - The configuration for the Ghost session.
+ * @returns A promise resolving to an object containing the session ID and initial status.
+ */
+declare const startGhostSession: (config: GhostConfig) => Promise<{
+    sessionId: string;
+    status: string;
+}>;
+/**
+ * Get Ghost session status
+ * @param sessionId - The ID of the session to check.
+ * @param apiUrl - Optional API URL override.
+ * @returns A promise resolving to the GhostStatus.
+ */
+declare const getGhostStatus: (sessionId: string, apiUrl?: string) => Promise<GhostStatus>;
+/**
+ * Get Ghost session results
+ * @param sessionId - The ID of the session to retrieve results for.
+ * @param apiUrl - Optional API URL override.
+ * @returns A promise resolving to the GhostResults.
+ */
+declare const getGhostResults: (sessionId: string, apiUrl?: string) => Promise<GhostResults>;
+/**
+ * Poll Ghost session until completion
+ * @param sessionId - The ID of the session to wait for.
+ * @param pollIntervalMs - Polling interval in milliseconds.
+ * @param timeoutMs - Timeout in milliseconds.
+ * @param apiUrl - Optional API URL override.
+ * @param onProgress - Optional callback for progress updates.
+ * @returns A promise resolving to the GhostResults upon completion.
+ */
+declare const waitForGhostCompletion: (sessionId: string, pollIntervalMs?: number, timeoutMs?: number, apiUrl?: string, onProgress?: (status: GhostStatus) => void) => Promise<GhostResults>;
+/**
+ * Stop a running Ghost session
+ * @param sessionId - The ID of the session to stop.
+ * @param apiUrl - Optional API URL override.
+ * @returns A promise resolving to the stop status.
+ */
+declare const stopGhostSession: (sessionId: string, apiUrl?: string) => Promise<{
+    stopped: boolean;
+    status: string;
+}>;
+/**
+ * Get Ghost session history
+ */
+interface GhostHistoryEntry {
+    sessionId: string;
+    testSuite: string;
+    startedAt: string;
+    completedAt?: string;
+    status: string;
+    passRate: number;
+}
+/**
+ * Get Ghost session history
+ * @param limit - Max number of entries to retrieve.
+ * @param apiUrl - Optional API URL override.
+ * @returns A promise resolving to an array of GhostHistoryEntry.
+ */
+declare const getGhostHistory: (limit?: number, apiUrl?: string) => Promise<GhostHistoryEntry[]>;
+/**
+ * Factory function to create Ghost session (Functional/Closure based)
+ * @param config - The configuration for the Ghost session.
+ * @returns An instance of IGhost.
+ */
+declare const createGhost: (config: GhostConfig) => IGhost;
+
+/**
+ * Remote Cortex implementation that proxies inference to the ForbocAI API.
+ * This is environment-agnostic as it only uses the standard fetch API.
+ */
+declare class RemoteCortex implements ICortex {
+    private apiUrl;
+    constructor(apiUrl: string);
+    init(): Promise<CortexStatus>;
+    complete(prompt: string, options?: CompletionOptions): Promise<string>;
+    completeStream(prompt: string, options?: CompletionOptions): AsyncGenerator<string>;
+}
+
+interface RPGAgentState extends AgentState {
+    inventory: string[];
+    hp: number;
+    mana: number;
+    skills: Record<string, number>;
+    relationships: Record<string, number>;
+    mood: string;
+}
+declare const RPG_MOODS: {
+    readonly hostile: "hostile";
+    readonly suspicious: "suspicious";
+    readonly neutral: "neutral";
+    readonly friendly: "friendly";
+    readonly loyal: "loyal";
+};
+declare const RPG_MEMORY_TYPES: {
+    readonly observation: "observation";
+    readonly experience: "experience";
+    readonly knowledge: "knowledge";
+    readonly emotion: "emotion";
+};
+declare const createRPGState: (partial?: Partial<RPGAgentState>) => RPGAgentState;
+declare const movementRule: ValidationRule;
+declare const attackRule: ValidationRule;
+declare const interactRule: ValidationRule;
+declare const speakRule: ValidationRule;
+declare const resourceRule: ValidationRule;
+declare const rpgRules: ValidationRule[];
+declare const spatialRules: ValidationRule[];
+declare const socialRules: ValidationRule[];
+declare const puzzleRules: ValidationRule[];
+
+type index_RPGAgentState = RPGAgentState;
+declare const index_RPG_MEMORY_TYPES: typeof RPG_MEMORY_TYPES;
+declare const index_RPG_MOODS: typeof RPG_MOODS;
+declare const index_attackRule: typeof attackRule;
+declare const index_createRPGState: typeof createRPGState;
+declare const index_interactRule: typeof interactRule;
+declare const index_movementRule: typeof movementRule;
+declare const index_puzzleRules: typeof puzzleRules;
+declare const index_resourceRule: typeof resourceRule;
+declare const index_rpgRules: typeof rpgRules;
+declare const index_socialRules: typeof socialRules;
+declare const index_spatialRules: typeof spatialRules;
+declare const index_speakRule: typeof speakRule;
+declare namespace index {
+  export { type index_RPGAgentState as RPGAgentState, index_RPG_MEMORY_TYPES as RPG_MEMORY_TYPES, index_RPG_MOODS as RPG_MOODS, index_attackRule as attackRule, index_createRPGState as createRPGState, index_interactRule as interactRule, index_movementRule as movementRule, index_puzzleRules as puzzleRules, index_resourceRule as resourceRule, index_rpgRules as rpgRules, index_socialRules as socialRules, index_spatialRules as spatialRules, index_speakRule as speakRule };
+}
+
+declare const SDK_VERSION = "0.4.4";
+
+export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type BridgeConfig, type CompletionOptions, type CortexConfig, type CortexStatus, type Directive, type GhostConfig, type GhostHistoryEntry, type GhostResults, type GhostStatus, type GhostTestResult, type IAgent, type IBridge, type ICortex, type IGhost, type ISoul, type MemoryConfig, type MemoryItem, type MemoryType, type Mood, type Observation, RemoteCortex, SDK_VERSION, type Soul, type SoulExportConfig, type SoulExportResult, type SoulImportConfig, type SoulListEntry, type ValidationContext, type ValidationResult, type ValidationRule, createAgent, createBridge, createGhost, createInitialState, createSoul, createSoulInstance, deserializeSoul, exportSoul, exportToSoul, fromSoul, getGhostHistory, getGhostResults, getGhostStatus, getSoulList, importSoulFromArweave, index as presets, processAgentInput, serializeSoul, startGhostSession, stopGhostSession, updateAgentState, uploadToArweave, validateAction, validateSoul, waitForGhostCompletion };