/** * LearnManager - central manager for continuous learning capabilities. * * Python parity: praisonaiagents/memory/learn/manager.py * * Coordinates every learning store according to `LearnConfig` and exposes a * single capture / retrieve surface (manager.py:24-40). * * Mode semantics (`LearnConfig.mode`) are not applied inside the Python * manager; the agent applies them in * `agent/memory_mixin.py:704-772` (`_process_auto_learning`). That dispatch * is ported here as {@link LearnManager.processAutoLearning} so the manager * is usable stand-alone: * - DISABLED (default): no automatic extraction, manual capture only. * - AGENTIC: extract and store after each conversation. * - PROPOSE: extract, but queue in `pendingLearnings` for approval. */ import { LearnBackend, LearnMode, LearnScope, type LearnConfig } from '../../config/index'; import { type LearnEntryData, type LearnManagerProtocol, type LearnMessage, type LearnProtocol, type ProcessConversationResult } from './protocols'; import { LearnEntry } from './stores'; /** * Full learn configuration accepted by {@link LearnManager}. * * Extends the package-level {@link LearnConfig} (config/index.ts) with the * fields Python's dataclass has and the TS interface does not yet carry. * Python parity: praisonaiagents/config/feature_configs.py:143-197 (`LearnConfig`) */ export interface LearnManagerConfig extends Omit { /** feature_configs.py:170 */ persona?: boolean; /** feature_configs.py:171 */ insights?: boolean; /** feature_configs.py:172 */ thread?: boolean; /** feature_configs.py:173 */ patterns?: boolean; /** feature_configs.py:174 */ decisions?: boolean; /** feature_configs.py:175 */ feedback?: boolean; /** feature_configs.py:176 */ improvements?: boolean; /** feature_configs.py:179 (`nudge_interval`, 0 = disabled) */ nudgeInterval?: number; /** feature_configs.py:180 (`nudge_min_tool_iters`) */ nudgeMinToolIters?: number; /** feature_configs.py:181 (`propose_skills`) */ proposeSkills?: boolean; /** feature_configs.py:184 (`mode`, default DISABLED) */ mode?: LearnMode | 'disabled' | 'agentic' | 'propose'; /** feature_configs.py:187 (`scope`, default PRIVATE) */ scope?: LearnScope | 'private' | 'shared'; /** feature_configs.py:190 (`backend`, default FILE) */ backend?: LearnBackend | 'file' | 'sqlite' | 'redis' | 'mongodb' | string; /** feature_configs.py:191 (`db_url`) */ dbUrl?: string | null; /** feature_configs.py:192 (`store_path`) */ storePath?: string; /** feature_configs.py:195 (`max_entries`, 0 = unbounded) */ maxEntries?: number; /** feature_configs.py:196 (`retention_days`, 0 = never) */ retentionDays?: number; /** feature_configs.py:199 (`llm` model name for extraction) */ llm?: string | null; } /** `LearnManagerConfig` with every Python default applied. */ export type ResolvedLearnConfig = Required> & { dbUrl: string | null; storePath: string | null; llm: string | null; autoConsolidate: boolean; }; /** * Apply the Python dataclass defaults (feature_configs.py:169-199). */ export declare function resolveLearnConfig(config?: LearnManagerConfig | null): ResolvedLearnConfig; /** * Extraction hook used by `processConversation`. Python's `llm` argument is a * model name; the TypeScript port additionally accepts a function so tests and * hosts can supply their own extractor without a network call. It receives the * extraction prompt and returns the raw JSON text or an already-parsed object. */ export type LearnExtractor = (prompt: string) => Promise> | string | Record; /** A store the manager can drive: built-in or any `LearnProtocol` implementation. */ export type LearnStore = LearnProtocol; /** * Central manager for continuous learning within the memory system. * Python parity: praisonaiagents/memory/learn/manager.py:24-716 (`LearnManager`) */ export declare class LearnManager implements LearnManagerProtocol { readonly config: ResolvedLearnConfig; readonly userId: string; readonly storePath: string | null; private readonly _backend; private readonly _stores; private readonly _customStores; private _pending; /** * manager.py:42-171 * * @param config Enables/disables capabilities; Python defaults applied when omitted. * @param userId Scopes the learnings; `"default"` when omitted (manager.py:78). * @param storePath Custom directory; falls back to `config.storePath` (manager.py:79). * @param customStores Extra or overriding stores keyed by name; must implement `LearnProtocol` * (manager.py:56-58). Custom stores win over built-ins (manager.py:165-168). */ constructor(config?: LearnManagerConfig | null, userId?: string | null, storePath?: string | null, customStores?: Record | null); /** * Create a storage backend from config; `null` means FILE (manager.py:173-216). * Any failure logs a warning and falls back to FILE, exactly like Python. */ private _createBackend; /** manager.py:218-222 */ private _getStorePath; /** The active stores by name (read-only view; Python exposes `_stores`). */ get stores(): ReadonlyMap; /** manager.py:224-228 */ capturePersona(content: string, category?: string): LearnEntry | null; /** manager.py:230-234 */ captureInsight(content: string, source?: string): LearnEntry | null; /** manager.py:236-240 */ captureThread(summary: string, threadId: string): LearnEntry | null; /** manager.py:242-246 */ capturePattern(pattern: string, patternType?: string): LearnEntry | null; /** manager.py:248-257 */ captureDecision(decision: string, reasoning?: string, outcome?: string): LearnEntry | null; /** manager.py:259-268 */ captureFeedback(feedback: string, rating?: number | null, source?: string): LearnEntry | null; /** manager.py:270-279 */ captureImprovement(proposal: string, area?: string, priority?: string): LearnEntry | null; /** Entries from every enabled store, keyed by store name (manager.py:281-292). */ getLearningContext(limitPerStore?: number): Record; /** Search across all enabled stores; stores with no hits are omitted (manager.py:294-301). */ search(query: string, limit?: number): Record; /** manager.py:303-308 */ getPersonaContext(limit?: number): string[]; /** manager.py:310-315 */ getInsightsContext(limit?: number): string[]; /** manager.py:317-322 */ clearAll(): Record; /** * Entry counts per store (manager.py:324-329). Python reads `store._entries`; * custom stores without that attribute count as 0 here instead of throwing. */ getStats(): Record; /** Archive stale/excess entries across all stores (manager.py:331-350). */ prune(): Record; /** Pending learnings awaiting approval - a copy (manager.py:352-355). */ get pendingLearnings(): LearnEntry[]; /** * Queue a learning for user approval (manager.py:357-381). * * @param content The learning content. * @param category Target store name (`persona`, `insights`, `patterns`, ...). * @param metadata Optional metadata; `category` and `status: "pending"` are added. */ addPending(content: string, category?: string, metadata?: Record | null): LearnEntry; /** * Approve a pending learning - move it into its store, or `persona` when the * category has no store (manager.py:383-402). Returns `false` if not found. */ approveLearning(entryId: string): boolean; /** Discard a pending learning (manager.py:404-417). */ rejectLearning(entryId: string): boolean; /** Approve every pending learning; returns the count (manager.py:419-432). */ approveAllLearnings(): number; /** Formatted learnings for system-prompt injection (manager.py:434-492). Threads are excluded. */ toSystemPromptContext(): string; /** manager.py:524-551 - identical prompt text. */ private _buildExtractionPrompt; /** Call the model (manager.py:558-563 `LLM(model).get_response(prompt, output_json=True)`). */ private _extract; private _asList; /** * Process a conversation to extract learnings automatically (manager.py:494-608). * * @param messages `{ role, content }` messages. * @param llm Model name (default `gpt-4o-mini`, manager.py:558) or a {@link LearnExtractor}. * @param extractOnly Extract without storing (used by PROPOSE mode, memory_mixin.py:731-735). */ processConversation(messages: LearnMessage[], llm?: string | LearnExtractor | null, extractOnly?: boolean): Promise; /** * Async version of `processConversation` (manager.py:610-716). Always stores * (Python's async variant has no `extract_only` parameter). */ aprocessConversation(messages: LearnMessage[], llm?: string | LearnExtractor | null): Promise; /** * Apply `config.mode` to a finished exchange. * Python parity: praisonaiagents/agent/memory_mixin.py:704-772 (`_process_auto_learning`) * * - DISABLED (or unknown): no-op, returns `null` (memory_mixin.py:751-754). * - PROPOSE: extract only, then queue persona / insights / patterns as * pending (memory_mixin.py:721-749). Improvements are not queued - Python * does not queue them either. * - AGENTIC: extract and store (memory_mixin.py:756-772). * * `llm` falls back to `config.llm` (memory_mixin.py:733, :770). Errors are * swallowed and logged like Python's `logging.debug`. */ processAutoLearning(messages: LearnMessage[], llm?: string | LearnExtractor | null): Promise; }