@cortexa/core 0.7.0

package/dist/index.d.ts

@@ -0,0 +1,670 @@
+import { EventEmitter } from 'node:events';
+
+interface RetryConfig {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+    retryableStatusCodes?: number[];
+}
+
+interface LLMResponse {
+    content: string;
+    tokensUsed: {
+        prompt: number;
+        completion: number;
+    };
+    model: string;
+}
+interface LLMChatOptions {
+    jsonMode?: boolean;
+    maxTokens?: number;
+}
+interface LLMProvider {
+    chat(prompt: string, options?: LLMChatOptions): Promise<LLMResponse>;
+}
+interface LLMConfig {
+    provider: string;
+    apiKey?: string;
+    model?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    retry?: RetryConfig;
+}
+
+interface WorkflowConfig {
+    stateColumn: string;
+    expectedTransitions: string[];
+    stuckThreshold?: string;
+}
+type InsightType = 'transition_skip' | 'transition_unexpected' | 'transition_stuck' | 'correlation_divergence' | 'correlation_timing' | 'distribution_shift' | 'temporal_shift';
+type Severity = 'low' | 'medium' | 'high' | 'critical';
+interface StateTransition {
+    entity: string;
+    tableName: string;
+    primaryKey: string | number;
+    fromState: string;
+    toState: string;
+    durationMs: number;
+    timestamp: Date;
+    expected: boolean;
+}
+interface TransitionStats {
+    entity: string;
+    fromState: string;
+    toState: string;
+    count: number;
+    avgDurationMs: number;
+    minDurationMs: number;
+    maxDurationMs: number;
+}
+interface Insight {
+    entity: string;
+    insightType: InsightType;
+    severity: Severity;
+    message: string;
+    context: Record<string, unknown>;
+    timestamp: Date;
+}
+interface ReasoningConfig {
+    workflows: Record<string, WorkflowConfig>;
+}
+
+interface CorrelationConfig {
+    entities: [string, string];
+    timeWindow: string;
+}
+interface DistributionConfig {
+    columns: string[];
+    temporalBuckets: 'hourly' | 'daily';
+}
+interface AnalyticsConfig {
+    correlations?: Record<string, CorrelationConfig>;
+    distributions?: Record<string, DistributionConfig>;
+}
+interface CorrelationStatus {
+    name: string;
+    entities: [string, string];
+    rateRatio: number;
+    baselineRatio: number;
+    coOccurrenceRate: number;
+    baselineCoOccurrence: number;
+    healthy: boolean;
+}
+interface DistributionSummary {
+    entity: string;
+    columnName: string;
+    bucketCount: number;
+    baselineSamples: number;
+    currentShift: number | null;
+    shifted: boolean;
+}
+
+type NodeType = 'entity' | 'event' | 'anomaly' | 'insight';
+type EdgeType = 'contains' | 'causes' | 'correlates' | 'transitions_to' | 'detected_on';
+interface KnowledgeNode {
+    id: number;
+    nodeType: NodeType;
+    refId: string;
+    label: string;
+    metadata: Record<string, unknown>;
+    timestamp: string;
+}
+interface KnowledgeEdge {
+    id: number;
+    sourceId: number;
+    targetId: number;
+    edgeType: EdgeType;
+    weight: number;
+    metadata: Record<string, unknown>;
+    timestamp: string;
+}
+interface EntityIntelligenceResult {
+    entityName: string;
+    tableCount: number;
+    totalEvents: number;
+    anomalyCount: number;
+    topCorrelations: Array<{
+        entity: string;
+        weight: number;
+    }>;
+    recentInsights: KnowledgeNode[];
+    riskScore: number;
+}
+interface KnowledgeConfig {
+    enabled: boolean;
+}
+interface GraphSummary {
+    totalNodes: number;
+    totalEdges: number;
+    entities: number;
+    events: number;
+    anomalies: number;
+    insights: number;
+}
+interface GraphExport {
+    nodes: KnowledgeNode[];
+    edges: KnowledgeEdge[];
+}
+
+type GovernanceLevel = 'auto_approve' | 'require_approval' | 'never_automate';
+type RecommendationStatus = 'pending' | 'approved' | 'rejected' | 'executed' | 'failed' | 'blocked';
+interface ActionContext {
+    insight: Insight;
+    entity: string;
+    recommendation: Recommendation;
+}
+interface ActionHandler {
+    name: string;
+    handler: (context: ActionContext) => Promise<void>;
+    description?: string;
+}
+interface ActionRule {
+    action: string;
+    when: {
+        insightType?: string[];
+        severity?: string[];
+        entity?: string[];
+    };
+    confidence?: number;
+}
+interface Recommendation {
+    id: number;
+    action: string;
+    reason: string;
+    confidence: number;
+    status: RecommendationStatus;
+    governance: GovernanceLevel;
+    insightId: string | null;
+    entity: string;
+    context: Record<string, unknown>;
+    createdAt: string;
+    resolvedAt: string | null;
+    resolvedBy: string | null;
+}
+interface RecommendationSummary {
+    total: number;
+    executed: number;
+    pending: number;
+    approved: number;
+    rejected: number;
+    blocked: number;
+    failed: number;
+}
+interface ActionsConfig {
+    enabled: boolean;
+    rules?: ActionRule[];
+    governance?: Record<string, GovernanceLevel>;
+}
+
+type NotificationTrigger = 'anomaly' | 'insight' | 'recommendation' | 'action:executed' | 'action:failed';
+interface WebhookTarget {
+    url: string;
+    headers?: Record<string, string>;
+    type?: 'generic' | 'slack';
+}
+interface NotificationFilter {
+    severity?: Array<'low' | 'medium' | 'high' | 'critical'>;
+    entity?: string[];
+}
+interface NotificationRule {
+    triggers: NotificationTrigger[];
+    targets: WebhookTarget[];
+    filter?: NotificationFilter;
+}
+interface NotificationsConfig {
+    enabled: boolean;
+    rules: NotificationRule[];
+}
+
+type LlmConfig = LLMConfig;
+interface ConnectionConfig {
+    type: 'postgres' | 'mysql' | 'mariadb' | 'cockroachdb' | 'sqlite' | 'mongodb' | 'mssql';
+    url?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    path?: string;
+}
+interface CortexaConfig {
+    connection: ConnectionConfig;
+    llm?: LLMConfig;
+    reasoning?: ReasoningConfig;
+    analytics?: AnalyticsConfig;
+    knowledge?: KnowledgeConfig;
+    actions?: ActionsConfig;
+    notifications?: NotificationsConfig;
+    batchSize?: number;
+}
+declare function defineConfig(config: CortexaConfig): CortexaConfig;
+
+interface RawColumn {
+    columnName: string;
+    dataType: string;
+    isNullable: boolean;
+    columnDefault: string | null;
+}
+interface RawForeignKey {
+    columnName: string;
+    referencedTable: string;
+    referencedColumn: string;
+}
+interface RawIndex {
+    indexName: string;
+    columns: string[];
+    isUnique: boolean;
+}
+interface RawTable {
+    tableName: string;
+    tableSchema: string;
+    columns: RawColumn[];
+    foreignKeys: RawForeignKey[];
+    indexes: RawIndex[];
+    sampleRows: Record<string, unknown>[];
+    rowCount: number;
+}
+interface RawSchema {
+    tables: RawTable[];
+    discoveredAt: string;
+}
+interface ClassifiedColumn {
+    columnName: string;
+    label: string;
+    meaning: string;
+}
+type EntityType = 'master' | 'transaction' | 'reference' | 'junction';
+interface ClassifiedEntity {
+    tableName: string;
+    entityLabel: string;
+    entityType: EntityType;
+    description: string;
+    confidence: number;
+    columns: ClassifiedColumn[];
+}
+interface Relationship {
+    sourceEntity: string;
+    targetEntity: string;
+    relationship: string;
+    sourceColumn: string;
+    targetColumn: string;
+    inferred: boolean;
+    confidence: number;
+}
+interface EntityGraph {
+    entities: ClassifiedEntity[];
+    relationships: Relationship[];
+}
+interface DiscoveryOptions {
+    /** Tables to exclude from discovery (e.g., ['passwords', 'api_keys', 'sessions']) */
+    excludeTables?: string[];
+    /** Columns to exclude from LLM prompt across all tables (e.g., ['ssn', 'credit_card', 'password_hash']) */
+    excludeColumns?: string[];
+    /** Whether to include sample rows from actual data. Default: true. Set to false to send only metadata to LLM. */
+    includeSampleData?: boolean;
+    /** Max number of sample rows per table. Default: 5. */
+    sampleRowLimit?: number;
+}
+interface DiscoveryResult {
+    entities: ClassifiedEntity[];
+    relationships: Relationship[];
+    raw: RawSchema;
+}
+
+interface RawChange {
+    tableName: string;
+    tableSchema: string;
+    operation: 'INSERT' | 'UPDATE' | 'DELETE';
+    primaryKey: string | number;
+    newData?: Record<string, unknown>;
+    oldData?: Record<string, unknown>;
+    changedColumns?: string[];
+    detectedAt: Date;
+}
+interface BusinessEvent {
+    entity: string;
+    entityType: EntityType;
+    type: 'created' | 'updated' | 'deleted';
+    table: string;
+    primaryKey: string | number;
+    timestamp: Date;
+    changedColumns?: string[];
+    metadata: Record<string, unknown>;
+}
+type AnomalyType = 'rate_spike' | 'rate_drop' | 'stuck_record';
+interface Anomaly {
+    entity: string;
+    anomalyType: AnomalyType;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    expected: number;
+    actual: number;
+    message: string;
+    timestamp: Date;
+}
+interface Baseline {
+    entity: string;
+    metric: string;
+    mean: number;
+    stddev: number;
+    sampleSize: number;
+}
+interface StreamCapability {
+    canStream: boolean;
+    reason: string;
+}
+interface WatchOptions {
+    interval?: number;
+    excludeTables?: string[];
+    excludeColumns?: string[];
+    stuckThreshold?: number;
+    anomalyThreshold?: number;
+    preferPolling?: boolean;
+    stuckCheckInterval?: number;
+    once?: boolean;
+}
+
+interface GraphStoreStorage {
+    saveKgNode(node: {
+        nodeType: string;
+        refId: string;
+        label: string;
+        metadata: string;
+    }): number;
+    getKgNode(id: number): {
+        id: number;
+        nodeType: string;
+        refId: string;
+        label: string;
+        metadata: string;
+        timestamp: string;
+    } | undefined;
+    getKgNodeByRef(nodeType: string, refId: string): {
+        id: number;
+        nodeType: string;
+        refId: string;
+        label: string;
+        metadata: string;
+        timestamp: string;
+    } | undefined;
+    getKgNodesByType(nodeType: string): Array<{
+        id: number;
+        nodeType: string;
+        refId: string;
+        label: string;
+        metadata: string;
+        timestamp: string;
+    }>;
+    getAllKgNodes(): Array<{
+        id: number;
+        nodeType: string;
+        refId: string;
+        label: string;
+        metadata: string;
+        timestamp: string;
+    }>;
+    deleteKgNode(id: number): void;
+    saveKgEdge(edge: {
+        sourceId: number;
+        targetId: number;
+        edgeType: string;
+        weight: number;
+        metadata: string;
+    }): number;
+    getKgEdgesFrom(nodeId: number, edgeType?: string): Array<{
+        id: number;
+        sourceId: number;
+        targetId: number;
+        edgeType: string;
+        weight: number;
+        metadata: string;
+        timestamp: string;
+    }>;
+    getKgEdgesTo(nodeId: number, edgeType?: string): Array<{
+        id: number;
+        sourceId: number;
+        targetId: number;
+        edgeType: string;
+        weight: number;
+        metadata: string;
+        timestamp: string;
+    }>;
+    getAllKgEdges(): Array<{
+        id: number;
+        sourceId: number;
+        targetId: number;
+        edgeType: string;
+        weight: number;
+        metadata: string;
+        timestamp: string;
+    }>;
+    getKgSummary(): {
+        totalNodes: number;
+        totalEdges: number;
+        entities: number;
+        events: number;
+        anomalies: number;
+        insights: number;
+    };
+}
+declare class GraphStore {
+    private readonly storage;
+    constructor(storage: GraphStoreStorage);
+    upsertNode(nodeType: NodeType, refId: string, label: string, metadata?: Record<string, unknown>): number;
+    getNode(id: number): KnowledgeNode | undefined;
+    getNodeByRef(nodeType: NodeType, refId: string): KnowledgeNode | undefined;
+    getNodesByType(nodeType: NodeType): KnowledgeNode[];
+    getAllNodes(): KnowledgeNode[];
+    deleteNode(id: number): void;
+    addEdge(sourceId: number, targetId: number, edgeType: EdgeType, weight?: number, metadata?: Record<string, unknown>): number;
+    getEdgesFrom(nodeId: number, edgeType?: EdgeType): KnowledgeEdge[];
+    getEdgesTo(nodeId: number, edgeType?: EdgeType): KnowledgeEdge[];
+    getAllEdges(): KnowledgeEdge[];
+    neighbors(nodeId: number): KnowledgeNode[];
+    getSummary(): GraphSummary;
+}
+
+interface ExplainTarget {
+    type: 'anomaly' | 'insight' | 'event' | 'entity';
+    id: number;
+}
+interface ExplainOptions {
+    maxContextEvents?: number;
+    maxGraphDepth?: number;
+    includeRecommendations?: boolean;
+}
+interface Evidence {
+    type: 'event' | 'baseline' | 'transition' | 'correlation' | 'graph_node';
+    description: string;
+    data: Record<string, unknown>;
+    relevance: number;
+}
+interface CausalStep {
+    order: number;
+    description: string;
+    confidence: number;
+}
+interface RecommendedAction {
+    action: string;
+    reason: string;
+    priority: 'low' | 'medium' | 'high';
+}
+interface ExplainResult {
+    explanationId: string;
+    target: ExplainTarget;
+    summary: string;
+    confidence: number;
+    evidence: Evidence[];
+    causalChain: CausalStep[];
+    recommendedActions: RecommendedAction[];
+    generatedAt: string;
+}
+
+interface AskOptions {
+    maxContextEvents?: number;
+    maxGraphDepth?: number;
+    entityHint?: string;
+}
+type SignalType = 'baselineDeviation' | 'anomaly' | 'insight' | 'eventCluster' | 'transition' | 'correlation' | 'graphRelation';
+interface SupportingSignal {
+    type: SignalType;
+    entity: string;
+    description: string;
+    data: Record<string, unknown>;
+}
+interface AskResult {
+    askId: string;
+    question: string;
+    answer: string;
+    confidence: number;
+    supportingSignals: SupportingSignal[];
+    relatedEntities: string[];
+    recommendedActions: string[];
+    generatedAt: string;
+}
+
+interface ChangeStream {
+    start(onChange: (change: RawChange) => void): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    cleanup(): Promise<void>;
+}
+
+declare class KnowledgeGraph {
+    private readonly store;
+    private readonly traversal;
+    private readonly entityIntelligence;
+    constructor(store: GraphStore);
+    causesOf(nodeId: number, maxDepth?: number): KnowledgeNode[];
+    impactOf(nodeId: number, maxDepth?: number): KnowledgeNode[];
+    timeline(nodeId: number): KnowledgeNode[];
+    entity(refId: string): {
+        intelligence: () => EntityIntelligenceResult | undefined;
+    };
+    getNode(id: number): KnowledgeNode | undefined;
+    getNodeByRef(nodeType: NodeType, refId: string): KnowledgeNode | undefined;
+    getEdges(nodeId: number, edgeType?: EdgeType): KnowledgeEdge[];
+    neighbors(nodeId: number): KnowledgeNode[];
+    getSummary(): GraphSummary;
+    export(rootNodeId?: number): GraphExport;
+}
+interface CortexaOptions extends CortexaConfig {
+    projectRoot?: string;
+    llmProvider?: LLMProvider;
+}
+interface CortexaStatus {
+    connected: boolean;
+    tables: number;
+    db: string;
+    watching: boolean;
+}
+declare class Cortexa extends EventEmitter {
+    private readonly config;
+    private connector;
+    private storage;
+    private readonly logger;
+    private llmProvider;
+    private watcher;
+    private knowledgeGraph;
+    private actionRegistry;
+    private discoveredTables;
+    private _status;
+    constructor(config: CortexaOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    discover(options?: DiscoveryOptions): Promise<DiscoveryResult>;
+    entity(tableName: string): ClassifiedEntity | undefined;
+    exportGraph(): EntityGraph;
+    watch(options?: WatchOptions): Promise<void>;
+    unwatch(): void;
+    cleanupStream(): Promise<void>;
+    getEvents(filter?: {
+        entity?: string;
+        last?: number;
+        operation?: 'INSERT' | 'UPDATE' | 'DELETE';
+        eventType?: string;
+    }): Array<{
+        id: number;
+        eventType: string;
+        entity: string;
+        tableName: string;
+        operation: 'INSERT' | 'UPDATE' | 'DELETE';
+        rowId: string | null;
+        rowData: string | null;
+        timestamp: string;
+    }>;
+    getBaselines(): Array<{
+        entity: string;
+        metric: string;
+        mean: number;
+        stddev: number;
+        sampleSize: number;
+    }>;
+    getAnomalies(filter?: {
+        last?: number;
+        entity?: string;
+        severity?: Severity;
+        anomalyType?: AnomalyType;
+    }): Array<{
+        id: number;
+        entity: string;
+        anomalyType: AnomalyType;
+        severity: Severity;
+        expected: number;
+        actual: number;
+        message: string;
+        timestamp: string;
+    }>;
+    getInsights(filter?: {
+        entity?: string;
+        last?: number;
+        insightType?: InsightType;
+        severity?: Severity;
+    }): Array<{
+        id: number;
+        entity: string;
+        insightType: InsightType;
+        severity: Severity;
+        message: string;
+        context: Record<string, unknown>;
+        timestamp: string;
+    }>;
+    getTransitions(entity?: string): Array<{
+        entity: string;
+        fromState: string;
+        toState: string;
+        count: number;
+        avgDurationMs: number;
+        minDurationMs: number;
+        maxDurationMs: number;
+    }>;
+    getCorrelations(): CorrelationStatus[];
+    getDistributions(entity?: string): DistributionSummary[];
+    graph(): KnowledgeGraph;
+    explain(target: ExplainTarget, options?: ExplainOptions): Promise<ExplainResult>;
+    ask(question: string, options?: AskOptions): Promise<AskResult>;
+    registerAction(name: string, handler: (context: ActionContext) => Promise<void>, description?: string): void;
+    approveRecommendation(id: number): void;
+    rejectRecommendation(id: number): void;
+    getRecommendations(filter?: {
+        status?: string;
+        action?: string;
+        last?: number;
+    }): Array<{
+        id: number;
+        action: string;
+        reason: string;
+        confidence: number;
+        status: string;
+        governance: string;
+        insightId: string | null;
+        entity: string;
+        context: string;
+        createdAt: string;
+        resolvedAt: string | null;
+        resolvedBy: string | null;
+    }>;
+    get status(): CortexaStatus;
+}
+
+export { type ActionContext, type ActionHandler, type ActionRule, type ActionsConfig, type AnalyticsConfig, type Anomaly, type AnomalyType, type AskOptions, type AskResult, type Baseline, type BusinessEvent, type CausalStep, type ChangeStream, type ClassifiedEntity, type ConnectionConfig, type CorrelationConfig, type CorrelationStatus, Cortexa, type CortexaConfig, type CortexaOptions, type CortexaStatus, type DiscoveryOptions, type DiscoveryResult, type DistributionConfig, type DistributionSummary, type EdgeType, type EntityGraph, type EntityIntelligenceResult, type Evidence, type ExplainOptions, type ExplainResult, type ExplainTarget, type GovernanceLevel, type GraphExport, type GraphSummary, type Insight, type InsightType, type KnowledgeConfig, type KnowledgeEdge, KnowledgeGraph, type KnowledgeNode, type LLMProvider, type LlmConfig, type NodeType, type NotificationFilter, type NotificationRule, type NotificationTrigger, type NotificationsConfig, type RawSchema, type ReasoningConfig, type Recommendation, type RecommendationStatus, type RecommendationSummary, type RecommendedAction, type Relationship, type Severity, type SignalType, type StateTransition, type StreamCapability, type SupportingSignal, type TransitionStats, type WatchOptions, type WebhookTarget, type WorkflowConfig, defineConfig };