semem/dist/types/index.d.ts

Semantic Memory for Intelligent Agents

/**
 * Semem TypeScript Declarations
 * Main entry point for all type definitions
 */

import { EventEmitter } from 'events';

// ======================
// BASIC TYPE DEFINITIONS
// ======================

export type Vector = number[];

export interface ChatMessage {
  role: 'system' | 'user' | 'assistant';
  content: string;
}

export interface LLMOptions {
  temperature?: number;
  max_tokens?: number;
  top_p?: number;
  [key: string]: any;
}

export interface Interaction {
  id: string;
  prompt: string;
  output: string;
  embedding: Vector;
  timestamp: number;
  accessCount: number;
  concepts: string[];
  decayFactor: number;
  metadata?: Record<string, any>;
}

export interface RetrievalResult {
  similarity: number;
  interaction: Interaction;
  concepts: string[];
}

export interface ContextOptions {
  maxTokens: number;
  maxTimeWindow?: number;
  relevanceThreshold?: number;
  maxContextSize?: number;
  overlapRatio?: number;
}

export interface CacheOptions {
  maxSize: number;
  ttl: number;
}

// ======================
// PROVIDER INTERFACES
// ======================

export interface LLMProvider {
  generateEmbedding(model: string, input: string): Promise<Vector>;
  generateChat(model: string, messages: ChatMessage[], options?: LLMOptions): Promise<string>;
  generateCompletion(model: string, prompt: string, options?: LLMOptions): Promise<string>;
  initialize?(): Promise<void>;
  dispose?(): Promise<void>;
}

export interface StorageProvider {
  loadHistory(): Promise<[Interaction[], Interaction[]]>;
  saveMemoryToHistory(store: any): Promise<void>;
  beginTransaction(): Promise<void>;
  commitTransaction(): Promise<void>;
  rollbackTransaction(): Promise<void>;
  verify(): Promise<boolean>;
  close(): Promise<void>;
}

// ======================
// CORE CLASSES
// ======================

export interface MemoryManagerConfig {
  llmProvider: LLMProvider;
  embeddingProvider?: LLMProvider;
  chatModel?: string;
  embeddingModel?: string;
  storage?: StorageProvider;
  dimension?: number;
  contextOptions?: ContextOptions;
  cacheOptions?: CacheOptions;
}

export declare class MemoryManager extends EventEmitter {
  constructor(config: MemoryManagerConfig);
  
  init(): Promise<void>;
  addInteraction(prompt: string, response: string, embedding?: Vector, concepts?: string[]): Promise<void>;
  retrieveRelevantInteractions(query: string, threshold?: number, excludeLastN?: number): Promise<RetrievalResult[]>;
  generateResponse(prompt: string, context?: Interaction[], memory?: RetrievalResult[]): Promise<string>;
  generateEmbedding(text: string): Promise<Vector>;
  extractConcepts(text: string): Promise<string[]>;
  dispose(): Promise<void>;
}

export declare class LLMHandler {
  constructor(llmProvider: LLMProvider, chatModel: string, temperature?: number);
  
  generateResponse(prompt: string, context: string, options?: any): Promise<string>;
  extractConcepts(text: string): Promise<string[]>;
  validateModel(model: string): boolean;
}

export declare class EmbeddingHandler {
  constructor(llmProvider: LLMProvider, model: string, dimension: number, cacheManager?: any);
  
  generateEmbedding(text: string): Promise<Vector>;
  validateEmbedding(embedding: Vector): boolean;
  calculateSimilarity(embedding1: Vector, embedding2: Vector): number;
}

// ======================
// RAGNO TYPES
// ======================

export interface EntityConfig {
  id?: string;
  name?: string;
  isEntryPoint?: boolean;
  subType?: string;
  relevance?: number;
  confidence?: number;
  [key: string]: any;
}

export declare class Entity {
  constructor(config: EntityConfig);
  
  getPrefLabel(): string;
  isEntryPoint(): boolean;
  getSubType(): string;
  getRelevance(): number;
  getConfidence(): number;
}

export declare class SemanticUnit {
  constructor(config: any);
  
  getContent(): string;
  getSummary(): string;
  getEntities(): Entity[];
  addEntity(entity: Entity): void;
}

export declare class Relationship {
  constructor(config: any);
  
  getSource(): Entity;
  getTarget(): Entity;
  getRelationshipType(): string;
  getConfidence(): number;
}

export interface TextChunk {
  content: string;
  source: string;
  metadata?: Record<string, any>;
}

export interface DecompositionOptions {
  extractRelationships?: boolean;
  maxEntitiesPerChunk?: number;
  minConfidence?: number;
  deduplicateEntities?: boolean;
}

export interface DecompositionResult {
  units: SemanticUnit[];
  entities: Entity[];
  relationships: Relationship[];
  dataset: any;
  metadata: {
    processingTime: number;
    chunksProcessed: number;
    totalEntities: number;
    totalRelationships: number;
    errors: number;
  };
}

export declare function decomposeCorpus(
  textChunks: TextChunk[],
  llmHandler: LLMHandler,
  options?: DecompositionOptions
): Promise<DecompositionResult>;

// ======================
// ZPT TYPES
// ======================

export type ZoomLevel = 'entity' | 'unit' | 'text' | 'community' | 'corpus';
export type TiltRepresentation = 'keywords' | 'embedding' | 'graph' | 'temporal';
export type TransformFormat = 'json' | 'markdown' | 'structured' | 'conversational';

export interface ZoomConfig {
  level: ZoomLevel;
  granularity: number;
  targetTypes: string[];
}

export interface TiltConfig {
  representation: TiltRepresentation;
  outputFormat: string;
  processingType: string;
}

export interface TransformConfig {
  maxTokens: number;
  format: TransformFormat;
  tokenizer: string;
  includeMetadata: boolean;
  chunkStrategy: string;
}

export interface ZPTParameters {
  zoom: ZoomConfig;
  pan?: any;
  tilt: TiltConfig;
  transform: TransformConfig;
}

export declare class CorpuscleSelector {
  constructor(ragnoCorpus: any, options?: any);
  
  select(parameters: ZPTParameters): Promise<any>;
}

// ======================
// MCP TYPES
// ======================

export interface MCPServerOptions {
  transport?: 'stdio' | 'http' | 'sse';
  port?: number;
  configPath?: string;
}

export declare function createMCPServer(options?: MCPServerOptions): Promise<{
  server: any;
  transport: any;
  close(): Promise<void>;
}>;

// ======================
// STORAGE TYPES
// ======================

export declare class BaseStore implements StorageProvider {
  loadHistory(): Promise<[Interaction[], Interaction[]]>;
  saveMemoryToHistory(store: any): Promise<void>;
  beginTransaction(): Promise<void>;
  commitTransaction(): Promise<void>;
  rollbackTransaction(): Promise<void>;
  verify(): Promise<boolean>;
  close(): Promise<void>;
}

export declare class InMemoryStore extends BaseStore {}
export declare class JSONStore extends BaseStore {
  constructor(filePath: string);
}
export declare class SPARQLStore extends BaseStore {
  constructor(config: any);
}

// ======================
// CONNECTOR TYPES
// ======================

export declare class ClientConnector implements LLMProvider {
  generateEmbedding(model: string, input: string): Promise<Vector>;
  generateChat(model: string, messages: ChatMessage[], options?: LLMOptions): Promise<string>;
  generateCompletion(model: string, prompt: string, options?: LLMOptions): Promise<string>;
}

export declare class OllamaConnector extends ClientConnector {
  constructor(config?: any);
}

export declare class ClaudeConnector extends ClientConnector {
  constructor(config: any);
}

export declare class MistralConnector extends ClientConnector {
  constructor(config: any);
}

// ======================
// UTILITY TYPES
// ======================

export declare class Config {
  constructor(configPath?: string);
  
  init(): Promise<void>;
  get(key: string): any;
  set(key: string, value: any): void;
  getConfig(): Record<string, any>;
}

export declare class Utils {
  static generateId(): string;
  static normalizeText(text: string): string;
  static calculateCosineSimilarity(a: Vector, b: Vector): number;
  static estimateTokens(text: string): number;
}

export declare class PromptTemplates {
  static formatChatPrompt(model: string, systemPrompt: string, context: string, query: string): ChatMessage[];
  static formatCompletionPrompt(context: string, query: string): string;
  static formatConceptPrompt(model: string, text: string): string;
}