@ai.ntellect/core 1.0.0 → 1.1.1

package/dist/routing/index.js

@@ -0,0 +1,375 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PetriNet = exports.PostgresPetriCheckpointAdapter = exports.RedisPetriCheckpointAdapter = exports.InMemoryPetriCheckpointAdapter = void 0;
+const matrix_1 = require("./matrix");
+var checkpoint_adapter_1 = require("./checkpoint-adapter");
+Object.defineProperty(exports, "InMemoryPetriCheckpointAdapter", { enumerable: true, get: function () { return checkpoint_adapter_1.InMemoryPetriCheckpointAdapter; } });
+var redis_checkpoint_adapter_1 = require("./redis-checkpoint-adapter");
+Object.defineProperty(exports, "RedisPetriCheckpointAdapter", { enumerable: true, get: function () { return redis_checkpoint_adapter_1.RedisPetriCheckpointAdapter; } });
+var postgres_checkpoint_adapter_1 = require("./postgres-checkpoint-adapter");
+Object.defineProperty(exports, "PostgresPetriCheckpointAdapter", { enumerable: true, get: function () { return postgres_checkpoint_adapter_1.PostgresPetriCheckpointAdapter; } });
+class PetriNet {
+    constructor(name) {
+        this.places = new Map();
+        this.transitions = new Map();
+        this.guardFunctions = new Map();
+        this.name = name;
+        this.state = {
+            marking: new Map(),
+            history: [],
+        };
+    }
+    addPlace(place) {
+        this.places.set(place.id, place);
+        this.state.marking.set(place.id, place.tokens.map(t => (Object.assign({}, t))));
+    }
+    addTransition(transition) {
+        this.transitions.set(transition.id, transition);
+    }
+    registerGuardFunction(name, func) {
+        this.guardFunctions.set(name, func);
+    }
+    setLLMExecutor(executor) {
+        this.llmExecutor = executor;
+    }
+    setActionExecutor(executor) {
+        this.actionExecutor = executor;
+    }
+    getEnabledTransitions(context) {
+        const enabled = [];
+        for (const [tid, transition] of this.transitions) {
+            if (transition.when) {
+                continue;
+            }
+            const hasTokens = transition.from.every(pid => (this.state.marking.get(pid) || []).length > 0);
+            if (!hasTokens)
+                continue;
+            let guardPassed = true;
+            if (transition.guard) {
+                guardPassed = this.evaluateGuard(transition.guard, context || {});
+            }
+            if (guardPassed) {
+                enabled.push(tid);
+            }
+        }
+        return enabled;
+    }
+    getEventDrivenTransitions() {
+        const eventDriven = [];
+        for (const [tid, transition] of this.transitions) {
+            if (transition.when) {
+                eventDriven.push(tid);
+            }
+        }
+        return eventDriven;
+    }
+    evaluateGuard(guard, context) {
+        if (guard.type === 'deterministic') {
+            if (guard.name && this.guardFunctions.has(guard.name)) {
+                return this.guardFunctions.get(guard.name)(context);
+            }
+            if (guard.condition) {
+                try {
+                    const fn = new Function(...Object.keys(context), `'use strict'; return (${guard.condition});`);
+                    return !!fn(...Object.values(context));
+                }
+                catch (_a) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        return true;
+    }
+    getTokenContext(transition) {
+        const context = {};
+        for (const pid of transition.from) {
+            const tokens = this.state.marking.get(pid) || [];
+            if (tokens.length > 0) {
+                Object.assign(context, tokens[0].data);
+            }
+        }
+        return context;
+    }
+    fireTransition(transitionId, tokenData) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const transition = this.transitions.get(transitionId);
+            if (!transition) {
+                return {
+                    success: false,
+                    transitionId,
+                    newMarking: this.cloneMarking(this.state.marking),
+                    consumedTokens: [],
+                    producedTokens: [],
+                    error: `Unknown transition: ${transitionId}`,
+                };
+            }
+            if (transition.when) {
+                return {
+                    success: false,
+                    transitionId,
+                    newMarking: this.cloneMarking(this.state.marking),
+                    consumedTokens: [],
+                    producedTokens: [],
+                    error: `Transition ${transitionId} is event-driven`,
+                };
+            }
+            const hasTokens = transition.from.every(pid => (this.state.marking.get(pid) || []).length > 0);
+            if (!hasTokens) {
+                return {
+                    success: false,
+                    transitionId,
+                    newMarking: this.cloneMarking(this.state.marking),
+                    consumedTokens: [],
+                    producedTokens: [],
+                    error: 'Missing tokens in input places',
+                };
+            }
+            if (transition.guard) {
+                const context = this.getTokenContext(transition);
+                const passed = this.evaluateGuard(transition.guard, context);
+                if (!passed) {
+                    return {
+                        success: false,
+                        transitionId,
+                        newMarking: this.cloneMarking(this.state.marking),
+                        consumedTokens: [],
+                        producedTokens: [],
+                        error: 'Guard condition not met',
+                    };
+                }
+            }
+            const consumed = [];
+            for (const pid of transition.from) {
+                const tokens = this.state.marking.get(pid) || [];
+                if (tokens.length > 0) {
+                    consumed.push(tokens.shift());
+                }
+            }
+            const firstConsumed = consumed[0];
+            const newToken = {
+                id: `${transitionId}_${Date.now()}`,
+                data: tokenData || (firstConsumed ? Object.assign({}, firstConsumed.data) : {}),
+                createdAt: Date.now(),
+            };
+            const toPlaces = Array.isArray(transition.to)
+                ? transition.to
+                : [transition.to];
+            for (const pid of toPlaces) {
+                if (!this.state.marking.has(pid)) {
+                    this.state.marking.set(pid, []);
+                }
+                this.state.marking.get(pid).push(newToken);
+            }
+            this.state.history.push(transitionId);
+            return {
+                success: true,
+                transitionId,
+                newMarking: this.cloneMarking(this.state.marking),
+                consumedTokens: consumed,
+                producedTokens: [newToken],
+            };
+        });
+    }
+    fireTransitionByEvent(transitionId, eventData) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const transition = this.transitions.get(transitionId);
+            if (!transition) {
+                return {
+                    success: false,
+                    transitionId,
+                    newMarking: this.cloneMarking(this.state.marking),
+                    consumedTokens: [],
+                    producedTokens: [],
+                    error: `Unknown transition: ${transitionId}`,
+                };
+            }
+            if (!transition.when) {
+                return {
+                    success: false,
+                    transitionId,
+                    newMarking: this.cloneMarking(this.state.marking),
+                    consumedTokens: [],
+                    producedTokens: [],
+                    error: `Transition ${transitionId} is not event-driven`,
+                };
+            }
+            const hasTokens = transition.from.every(pid => (this.state.marking.get(pid) || []).length > 0);
+            if (!hasTokens) {
+                return {
+                    success: false,
+                    transitionId,
+                    newMarking: this.cloneMarking(this.state.marking),
+                    consumedTokens: [],
+                    producedTokens: [],
+                    error: 'Missing tokens in input places',
+                };
+            }
+            const consumed = [];
+            for (const pid of transition.from) {
+                const tokens = this.state.marking.get(pid) || [];
+                if (tokens.length > 0) {
+                    consumed.push(tokens.shift());
+                }
+            }
+            const firstConsumed = consumed[0];
+            const newToken = {
+                id: `${transitionId}_${Date.now()}`,
+                data: eventData || (firstConsumed ? Object.assign({}, firstConsumed.data) : {}),
+                createdAt: Date.now(),
+            };
+            const toPlaces = Array.isArray(transition.to)
+                ? transition.to
+                : [transition.to];
+            for (const pid of toPlaces) {
+                if (!this.state.marking.has(pid)) {
+                    this.state.marking.set(pid, []);
+                }
+                this.state.marking.get(pid).push(newToken);
+            }
+            this.state.history.push(transitionId);
+            return {
+                success: true,
+                transitionId,
+                newMarking: this.cloneMarking(this.state.marking),
+                consumedTokens: consumed,
+                producedTokens: [newToken],
+            };
+        });
+    }
+    fireTransitionWithAction(transitionId, tokenData) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const transition = this.transitions.get(transitionId);
+            if (!transition) {
+                return {
+                    success: false,
+                    transitionId,
+                    newMarking: this.cloneMarking(this.state.marking),
+                    consumedTokens: [],
+                    producedTokens: [],
+                    error: `Unknown transition: ${transitionId}`,
+                };
+            }
+            const tokenContext = this.getTokenContext(transition);
+            const result = yield this.fireTransition(transitionId, tokenData);
+            if (result.success && transition.action && this.actionExecutor) {
+                const actionContext = transition.action.contextMapper
+                    ? transition.action.contextMapper(tokenContext)
+                    : tokenContext;
+                try {
+                    const actionResult = yield this.actionExecutor(transition.action, actionContext);
+                    return Object.assign(Object.assign({}, result), { actionResult });
+                }
+                catch (error) {
+                    return Object.assign(Object.assign({}, result), { success: false, error: error.message, actionResult: undefined });
+                }
+            }
+            return result;
+        });
+    }
+    detectDeadlock() {
+        const enabled = this.getEnabledTransitions();
+        const eventDriven = this.getEventDrivenTransitions();
+        const hasActiveTokens = this.hasActiveTokens();
+        if (enabled.length > 0)
+            return false;
+        if (eventDriven.length > 0 && hasActiveTokens)
+            return false;
+        return hasActiveTokens;
+    }
+    hasActiveTokens() {
+        return Array.from(this.state.marking.values()).some(tokens => tokens.length > 0);
+    }
+    validateBoundedness() {
+        for (const [tid, t] of this.transitions) {
+            if (t.from.length === 0) {
+                return {
+                    bounded: false,
+                    details: `Transition ${tid} has no input places`,
+                };
+            }
+            const toPlaces = Array.isArray(t.to) ? t.to : [t.to];
+            for (const toPlace of toPlaces) {
+                if (t.from.includes(toPlace) && toPlaces.length > 0) {
+                    return {
+                        bounded: false,
+                        details: `Transition ${tid} has self-loop`,
+                    };
+                }
+            }
+        }
+        const places = Array.from(this.places.keys());
+        const transitions = Array.from(this.transitions.keys());
+        const P = places.length;
+        const T = transitions.length;
+        if (P === 0 || T === 0)
+            return { bounded: true };
+        const Pre = (0, matrix_1.matrixZeros)(P, T);
+        const Post = (0, matrix_1.matrixZeros)(P, T);
+        for (let j = 0; j < T; j++) {
+            const t = this.transitions.get(transitions[j]);
+            for (const pid of t.from) {
+                const i = places.indexOf(pid);
+                if (i !== -1)
+                    Pre[i][j] = 1;
+            }
+            const toArray = Array.isArray(t.to) ? t.to : [t.to];
+            for (const pid of toArray) {
+                const i = places.indexOf(pid);
+                if (i !== -1)
+                    Post[i][j] = 1;
+            }
+        }
+        const C = (0, matrix_1.matrixSubtract)(Post, Pre);
+        const hasInvariant = (0, matrix_1.hasPositiveNullVector)(C);
+        if (hasInvariant) {
+            return { bounded: true };
+        }
+        return { bounded: true, details: 'No P-invariant found' };
+    }
+    toDot() {
+        const lines = [`digraph {`, `  label="${this.name}"`];
+        for (const [pid, place] of this.places) {
+            const tokenCount = (this.state.marking.get(pid) || []).length;
+            const shape = place.type === 'initial'
+                ? 'circle'
+                : place.type === 'final'
+                    ? 'doublecircle'
+                    : 'box';
+            lines.push(`  ${pid} [shape=${shape}, label="${pid}\\n(${tokenCount} tokens)"]`);
+        }
+        for (const [tid, transition] of this.transitions) {
+            const label = transition.description || tid;
+            lines.push(`  ${tid} [shape=box, style=filled, fillcolor=lightgray, label="${label}"]`);
+            for (const fp of transition.from) {
+                lines.push(`  ${fp} -> ${tid}`);
+            }
+            const toPlaces = Array.isArray(transition.to)
+                ? transition.to
+                : [transition.to];
+            for (const tp of toPlaces) {
+                lines.push(`  ${tid} -> ${tp}`);
+            }
+        }
+        lines.push('}');
+        return lines.join('\n');
+    }
+    cloneMarking(marking) {
+        const cloned = new Map();
+        for (const [k, v] of marking) {
+            cloned.set(k, v.map(t => (Object.assign({}, t))));
+        }
+        return cloned;
+    }
+}
+exports.PetriNet = PetriNet;
+//# sourceMappingURL=index.js.map

package/dist/routing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../routing/index.ts"],"names":[],"mappings":"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"}

package/dist/routing/intent-classifier.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Structured result returned by an intent classification pass.
+ */
+export interface IntentResult {
+    /** Canonical intent label (one of the registered intents, or `"UNKNOWN"`). */
+    intent: string;
+    /** Confidence score in [0, 1]. Values below the configured threshold trigger clarification. */
+    confidence: number;
+    /** Free-form entity map extracted alongside the intent. */
+    entities: Record<string, any>;
+    /** Turn history that was fed to the classifier, useful for debugging. */
+    turnHistory?: string[];
+    /**
+     * Optional list of multiple intents when the message contains several actions.
+     * Each entry has its own intent label and confidence.
+     * When present, the orchestrator will execute them sequentially.
+     */
+    intents?: Array<{
+        intent: string;
+        confidence: number;
+        entities?: Record<string, any>;
+    }>;
+}
+/**
+ * Function-form of an intent classifier, compatible with `CortexFlowOrchestrator.setIntentClassifier`.
+ *
+ * @param message - Raw user message.
+ * @param context - Optional context carrying recent turn history.
+ * @returns Resolved intent result.
+ */
+export type IntentClassifierFn = (message: string, context?: {
+    turnHistory?: string[];
+}) => Promise<IntentResult>;
+/**
+ * Shared interface implemented by both `IntentClassifier` (LLM-backed) and
+ * `HybridIntentClassifier` (rules-first, LLM fallback).
+ *
+ * The orchestrator depends only on this interface, never on a concrete class.
+ */
+export interface IIntentClassifier {
+    classify(message: string, context?: {
+        turnHistory?: string[];
+    }): Promise<IntentResult>;
+    generateClarification(originalMessage: string): Promise<string>;
+    getConfidenceThreshold(): number;
+}
+/**
+ * A single keyword rule used by `HybridIntentClassifier`.
+ *
+ * A rule fires when at least one keyword matches. The confidence is scaled by
+ * the fraction of keywords that matched, so rules with more keywords and more
+ * matches score higher — making partial matches detectable but less trusted.
+ */
+export interface KeywordRule {
+    /** Intent label to return when this rule matches. */
+    intent: string;
+    /** Keywords or phrases to look for (case-insensitive substring match). */
+    keywords: string[];
+    /**
+     * Base confidence when ALL keywords match. Partial matches are scored
+     * proportionally: `baseConfidence × (matchedCount / keywords.length)`.
+     * Defaults to `0.95`.
+     */
+    confidence?: number;
+    /**
+     * Optional negation terms. If any negation term is found in the message,
+     * this rule is skipped entirely.
+     */
+    negations?: string[];
+}
+/**
+ * LLM-backed intent classifier for the CortexFlow orchestration layer.
+ *
+ * The classifier sends a single prompt to an LLM and expects a JSON reply
+ * conforming to `{ intent, confidence, entities }`. The response is validated
+ * with Zod; any parse failure falls back to `UNKNOWN` with zero confidence.
+ *
+ * Keeping classification to **one LLM call per user turn** is a core design
+ * principle — all subsequent routing is done deterministically by the Petri net.
+ *
+ * @example
+ * ```ts
+ * const classifier = new IntentClassifier(llmFn, {
+ *   intents: ['FETCH_MAILS', 'SUMMARIZE', 'ARCHIVE'],
+ *   confidenceThreshold: 0.7,
+ * });
+ *
+ * const result = await classifier.classify('Please fetch my latest 5 emails');
+ * // { intent: 'FETCH_MAILS', confidence: 0.95, entities: { maxMails: 5 } }
+ * ```
+ */
+export declare class IntentClassifier implements IIntentClassifier {
+    private llmCall;
+    private intents;
+    private confidenceThreshold;
+    /**
+     * @param llmCall - Function that forwards a prompt to an LLM and returns its text response.
+     * @param options.intents - List of valid intent labels the LLM must choose from.
+     * @param options.confidenceThreshold - Minimum confidence to avoid triggering clarification.
+     *   Defaults to `0.6`.
+     */
+    constructor(llmCall: (prompt: string) => Promise<string>, options?: {
+        intents?: string[];
+        confidenceThreshold?: number;
+    });
+    /**
+     * Classifies a user message into one of the registered intents via one LLM call.
+     *
+     * Supports multi-intent detection: if the LLM returns an `intents` array,
+     * the result will include multiple intents to be executed sequentially.
+     *
+     * On JSON parse failure or Zod validation error, returns a safe fallback
+     * `{ intent: "UNKNOWN", confidence: 0, entities: {} }` rather than throwing.
+     */
+    classify(message: string, context?: {
+        turnHistory?: string[];
+    }): Promise<IntentResult>;
+    /** Returns the current confidence threshold. */
+    getConfidenceThreshold(): number;
+    /** Overrides the confidence threshold at runtime. */
+    setConfidenceThreshold(threshold: number): void;
+    /**
+     * Converts this classifier instance into a plain `IntentClassifierFn`
+     * suitable for `CortexFlowOrchestrator.setIntentClassifier`.
+     */
+    static toFn(classifier: IIntentClassifier): IntentClassifierFn;
+    /**
+     * Generates a short clarifying question when the user's intent is ambiguous.
+     *
+     * Falls back to a generic question listing available intents if the LLM call fails.
+     */
+    generateClarification(originalMessage: string): Promise<string>;
+}
+/**
+ * A hybrid intent classifier that tries keyword rules first and only invokes
+ * the LLM when no rule reaches the configured confidence threshold.
+ *
+ * **Why this matters for performance**: intent classification is on the
+ * critical path of every user turn. For well-defined, unambiguous commands
+ * ("fetch my mails", "archive all newsletters") keyword rules resolve in
+ * microseconds at confidence ≥ 0.9, eliminating the first LLM call entirely.
+ * The LLM is reserved for genuinely ambiguous messages.
+ *
+ * The confidence of a rule is computed as:
+ * `baseConfidence × (matchedKeywords / totalKeywords)`.
+ * This means a rule with 4 keywords where 3 match scores 0.95 × 0.75 = 0.71,
+ * which may still exceed the threshold for coarse intents.
+ *
+ * @example
+ * ```ts
+ * const classifier = new HybridIntentClassifier(
+ *   [
+ *     { intent: 'TRIAGE_MAILS', keywords: ['fetch', 'mail', 'urgent', 'archive'], confidence: 0.95 },
+ *     { intent: 'FETCH_MAILS',  keywords: ['fetch', 'email'],                     confidence: 0.90 },
+ *   ],
+ *   { intents: ['TRIAGE_MAILS', 'FETCH_MAILS', 'UNKNOWN'], confidenceThreshold: 0.6 },
+ *   llmFn, // optional — omit for pure keyword mode
+ * );
+ *
+ * // "Fetch my 5 mails and flag the urgent ones" → keyword match, 0 LLM calls
+ * // "Do the thing with the emails maybe?"       → LLM fallback
+ * ```
+ */
+export declare class HybridIntentClassifier implements IIntentClassifier {
+    private rules;
+    private confidenceThreshold;
+    private intents;
+    private llmClassifier?;
+    /**
+     * @param rules - Ordered list of keyword rules. Rules are evaluated in order;
+     *   the highest-scoring match wins.
+     * @param options.intents - Valid intent labels (used for LLM fallback prompt and clarification).
+     * @param options.confidenceThreshold - Minimum confidence to accept a result without LLM fallback.
+     * @param llmFn - Optional LLM function. If omitted, unmatched messages return `UNKNOWN`.
+     */
+    constructor(rules: KeywordRule[], options: {
+        intents: string[];
+        confidenceThreshold?: number;
+    }, llmFn?: (prompt: string) => Promise<string>);
+    /** Returns the current confidence threshold. */
+    getConfidenceThreshold(): number;
+    /**
+     * Classifies a message using keyword rules first.
+     *
+     * If the best keyword rule score meets the threshold, the result is returned
+     * immediately — no LLM call is made. Otherwise, the LLM classifier is invoked
+     * as a fallback (if configured). Messages that match no rule and have no LLM
+     * fallback return `UNKNOWN` with confidence 0.
+     */
+    classify(message: string, context?: {
+        turnHistory?: string[];
+    }): Promise<IntentResult>;
+    /**
+     * Generates a clarifying question for ambiguous messages.
+     * Delegates to the LLM classifier if available; otherwise returns a generic
+     * question listing the known intents.
+     */
+    generateClarification(originalMessage: string): Promise<string>;
+    /**
+     * Converts this classifier into a plain `IntentClassifierFn`.
+     * Works identically to `IntentClassifier.toFn`.
+     */
+    static toFn(classifier: IIntentClassifier): IntentClassifierFn;
+    private applyRules;
+}
+//# sourceMappingURL=intent-classifier.d.ts.map

package/dist/routing/intent-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-classifier.d.ts","sourceRoot":"","sources":["../../routing/intent-classifier.ts"],"names":[],"mappings":"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"}