glirastes 0.2.1 → 0.3.1

package/dist/cjs/server/pii-shield/leakage.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectLeakage = detectLeakage;
+const MIN_LENGTH = 3;
+function detectLeakage(text, knownOriginals) {
+    const leaked = [];
+    for (const original of knownOriginals) {
+        if (original.length < MIN_LENGTH)
+            continue;
+        if (text.includes(original)) {
+            leaked.push(original);
+        }
+    }
+    return leaked;
+}

package/dist/cjs/server/pii-shield/session-mapping.d.ts

@@ -0,0 +1,12 @@
+import type { PiiCategory } from '../../types.js';
+export interface Session {
+    getOrCreatePseudonym(original: string, category: PiiCategory | string): string;
+    getPseudonym(original: string): string | undefined;
+    resolveOriginal(pseudonym: string): string | undefined;
+    allOriginals(): string[];
+}
+export interface SessionStore {
+    getOrCreate(sessionId: string): Session;
+    clear(sessionId: string): void;
+}
+export declare function createSessionStore(locale: string): SessionStore;

package/dist/cjs/server/pii-shield/session-mapping.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionStore = createSessionStore;
+const fake_data_js_1 = require("./fake-data.js");
+function seedFromString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        hash = ((hash << 5) - hash + str.charCodeAt(i)) | 0;
+    }
+    return hash || 1;
+}
+function createSession(sessionId, locale) {
+    const forward = new Map();
+    const reverse = new Map();
+    const gen = (0, fake_data_js_1.createFakeDataGenerator)(seedFromString(sessionId), locale);
+    return {
+        getOrCreatePseudonym(original, category) {
+            const existing = forward.get(original);
+            if (existing)
+                return existing;
+            let pseudonym = gen.generate(category);
+            // Collision detection: if this pseudonym already maps to a different original, regenerate
+            const MAX_RETRIES = 10;
+            let retries = 0;
+            while (reverse.has(pseudonym) && reverse.get(pseudonym) !== original) {
+                retries++;
+                if (retries > MAX_RETRIES) {
+                    // Append numeric suffix to guarantee uniqueness
+                    let suffix = 1;
+                    let candidate = `${pseudonym}-${suffix}`;
+                    while (reverse.has(candidate) && reverse.get(candidate) !== original) {
+                        suffix++;
+                        candidate = `${pseudonym}-${suffix}`;
+                    }
+                    pseudonym = candidate;
+                    break;
+                }
+                pseudonym = gen.generate(category);
+            }
+            forward.set(original, pseudonym);
+            reverse.set(pseudonym, original);
+            return pseudonym;
+        },
+        getPseudonym(original) {
+            return forward.get(original);
+        },
+        resolveOriginal(pseudonym) {
+            return reverse.get(pseudonym);
+        },
+        allOriginals() {
+            return [...forward.keys()];
+        },
+    };
+}
+function createSessionStore(locale) {
+    const sessions = new Map();
+    return {
+        getOrCreate(sessionId) {
+            let session = sessions.get(sessionId);
+            if (!session) {
+                session = createSession(sessionId, locale);
+                sessions.set(sessionId, session);
+            }
+            return session;
+        },
+        clear(sessionId) {
+            sessions.delete(sessionId);
+        },
+    };
+}

package/dist/cjs/server/pipeline.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AI pipeline: multi-stage workflow that composes guardrails, intent
+ * classification, tool routing, and model selection into a single
+ * `process()` call. Requires a Lancer client (Glirastes platform).
+ */
+import { type LocalClassifierConfig } from './core/index.js';
+import type { AiPipelineConfig, AiPipeline } from '../types.js';
+import type { DegradationDefaults, Lancer, OnServiceUnavailable } from './lancer/index.js';
+export interface ProPipelineConfig extends AiPipelineConfig {
+    /**
+     * Lancer platform client. Required for the pipeline.
+     * Guardrail checks delegate to Glirastes Warden.
+     */
+    lancer: Lancer;
+    degradation?: DegradationDefaults;
+    onServiceUnavailable?: OnServiceUnavailable;
+    /**
+     * Optional generateText callback (from Vercel AI SDK or compatible).
+     */
+    generateText?: LocalClassifierConfig['generateText'];
+}
+/**
+ * Create an AI pipeline that composes guardrails, classification, routing,
+ * and model selection into a single `process()` call.
+ */
+export declare function createAiPipeline(config: ProPipelineConfig): AiPipeline;

package/dist/cjs/server/pipeline.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * AI pipeline: multi-stage workflow that composes guardrails, intent
+ * classification, tool routing, and model selection into a single
+ * `process()` call. Requires a Lancer client (Glirastes platform).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAiPipeline = createAiPipeline;
+const index_js_1 = require("./core/index.js");
+const index_js_2 = require("./lancer/index.js");
+/**
+ * Create an AI pipeline that composes guardrails, classification, routing,
+ * and model selection into a single `process()` call.
+ */
+function createAiPipeline(config) {
+    const { modules, modelSelector: modelSelectorConfig, models: modelsMap, modelInstanceFactory, followups: followupsConfig, relatedModules, confidenceThresholds, onAudit, lancer, generateText, } = config;
+    if (!lancer) {
+        throw new Error('createAiPipeline requires a Lancer client. ' +
+            'Create one with createLancer({ apiKey }) from glirastes/server/lancer.');
+    }
+    const router = (0, index_js_1.createAiRouter)({
+        modules,
+        relatedModules,
+        confidenceThresholds,
+    });
+    const modelSelector = modelsMap && modelInstanceFactory
+        ? (0, index_js_1.createModelSelectorFromMap)(modelsMap, modelInstanceFactory, modules)
+        : modelSelectorConfig
+            ? (0, index_js_1.createModelSelector)(modelSelectorConfig, modules)
+            : null;
+    const classifierModel = modelsMap && modelInstanceFactory
+        ? modelInstanceFactory(modelsMap.fast ?? modelsMap.standard ?? 'default')
+        : undefined;
+    const classifier = (0, index_js_1.createIntentClassifier)({
+        modules,
+        model: classifierModel,
+        generateText,
+        locale: config.classifier?.locale,
+    });
+    const followupsEnabled = followupsConfig?.enabled ?? false;
+    const defaultModel = { modelId: 'default' };
+    return {
+        async process(input, context, _conversationHistory) {
+            const auditCtx = { sessionId: '' };
+            let sanitizedInput = input;
+            let blocked = false;
+            try {
+                const wardenResult = await lancer.warden.check(input, []);
+                if (!wardenResult.passed) {
+                    blocked = true;
+                }
+            }
+            catch (err) {
+                if (err instanceof index_js_2.ServiceBlockedError) {
+                    blocked = true;
+                }
+            }
+            onAudit?.({
+                type: blocked ? 'guardrail.blocked' : 'guardrail.passed',
+                timestamp: new Date().toISOString(),
+                sessionId: auditCtx.sessionId,
+                source: 'server-pro',
+                details: {
+                    inputLength: input.length,
+                    blocked,
+                },
+            });
+            if (blocked) {
+                const ambiguous = { intent: 'ambiguous', confidence: 0 };
+                return {
+                    model: modelSelector?.select(ambiguous, context) ?? defaultModel,
+                    tools: [],
+                    sanitizedInput,
+                    intent: ambiguous,
+                    module: null,
+                    followupsEnabled,
+                    blocked: true,
+                };
+            }
+            let intent = { intent: 'ambiguous', confidence: 0 };
+            const classifyStart = Date.now();
+            try {
+                intent = await classifier.classify(sanitizedInput, context);
+            }
+            catch {
+                // Graceful degradation
+            }
+            onAudit?.({
+                type: 'intent.classified',
+                timestamp: new Date().toISOString(),
+                sessionId: auditCtx.sessionId,
+                source: 'server-pro',
+                details: {
+                    intent: intent.intent,
+                    confidence: intent.confidence,
+                    latencyMs: Date.now() - classifyStart,
+                },
+            });
+            const allToolNames = modules.flatMap((m) => [...m.tools, ...(m.sharedTools ?? [])]);
+            const selected = router.route(intent, allToolNames);
+            onAudit?.({
+                type: 'routing.resolved',
+                timestamp: new Date().toISOString(),
+                sessionId: auditCtx.sessionId,
+                source: 'server-pro',
+                details: {
+                    module: selected.module?.id ?? null,
+                    strategy: selected.strategy,
+                    toolCount: selected.tools.length,
+                },
+            });
+            const tools = [...selected.tools];
+            if (followupsEnabled) {
+                tools.push('suggest_followups');
+            }
+            const model = modelSelector?.select(intent, context) ?? defaultModel;
+            return {
+                model,
+                tools: [...new Set(tools)],
+                sanitizedInput,
+                intent,
+                module: selected.module,
+                followupsEnabled,
+            };
+        },
+    };
+}

package/dist/cjs/server/testing/approvals.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Auto-generates approval flag tests from a tool registry.
+ *
+ * Convention:
+ * - Tools with method POST/PATCH/PUT/DELETE should resolve to needsApproval: true
+ *   (this is the default in server-node when needsApproval is omitted)
+ * - Tools with method GET (or no method, i.e. UI tools) should have needsApproval: false/undefined
+ *
+ * This test verifies that mutation tools have not been explicitly set to needsApproval: false.
+ */
+export declare function runApprovalTest(toolRegistry: Record<string, unknown>): void;

package/dist/cjs/server/testing/approvals.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runApprovalTest = runApprovalTest;
+const vitest_1 = require("vitest");
+/**
+ * Auto-generates approval flag tests from a tool registry.
+ *
+ * Convention:
+ * - Tools with method POST/PATCH/PUT/DELETE should resolve to needsApproval: true
+ *   (this is the default in server-node when needsApproval is omitted)
+ * - Tools with method GET (or no method, i.e. UI tools) should have needsApproval: false/undefined
+ *
+ * This test verifies that mutation tools have not been explicitly set to needsApproval: false.
+ */
+function runApprovalTest(toolRegistry) {
+    const tools = Object.entries(toolRegistry);
+    if (tools.length === 0) {
+        return;
+    }
+    const mutationMethods = new Set(['POST', 'PATCH', 'PUT', 'DELETE']);
+    (0, vitest_1.describe)('AI Tool Approval Flags', () => {
+        const mutationTools = tools.filter(([, def]) => def.method && mutationMethods.has(def.method.toUpperCase()));
+        const queryTools = tools.filter(([, def]) => !def.method || def.method.toUpperCase() === 'GET');
+        if (mutationTools.length > 0) {
+            (0, vitest_1.describe)('mutation tools require approval', () => {
+                vitest_1.it.each(mutationTools.map(([name, def]) => [name, def.method]))('%s (%s) has needsApproval: true', (name) => {
+                    const tool = toolRegistry[name];
+                    (0, vitest_1.expect)(tool.needsApproval, `${name} is a mutation tool and should require approval`).toBe(true);
+                });
+            });
+        }
+        if (queryTools.length > 0) {
+            (0, vitest_1.describe)('query/UI tools do not require approval', () => {
+                vitest_1.it.each(queryTools.map(([name]) => [name]))('%s does not require approval', (name) => {
+                    const tool = toolRegistry[name];
+                    (0, vitest_1.expect)(tool.needsApproval, `${name} is a query tool and should not require approval`).toBeFalsy();
+                });
+            });
+        }
+    });
+}

package/dist/cjs/server/testing/combination.d.ts

@@ -0,0 +1,3 @@
+import type { PipelineComponents } from './helpers.js';
+import type { CombinationTestCase, CombinationTestOptions } from './types.js';
+export declare function runCombinationTest(components: PipelineComponents, cases?: CombinationTestCase[], options?: CombinationTestOptions): void;

package/dist/cjs/server/testing/combination.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCombinationTest = runCombinationTest;
+const vitest_1 = require("vitest");
+const helpers_js_1 = require("./helpers.js");
+function runCombinationTest(components, cases, options) {
+    const { modules } = components;
+    (0, vitest_1.describe)('AI Tool Combinations', () => {
+        // ── Auto-generated: shared tool availability ──────────────────────
+        const modulesWithSharedTools = modules.filter((mod) => mod.sharedTools && mod.sharedTools.length > 0);
+        if (modulesWithSharedTools.length > 0) {
+            (0, vitest_1.describe)('shared tool availability', () => {
+                for (const mod of modulesWithSharedTools) {
+                    for (const sharedTool of mod.sharedTools) {
+                        (0, vitest_1.it)(`${sharedTool} available in ${mod.id} (shared tool)`, () => {
+                            const result = (0, helpers_js_1.simulatePipeline)(components, `test ${mod.id}`, {
+                                intent: mod.id,
+                                confidence: 0.95,
+                            });
+                            (0, vitest_1.expect)(result.tools, `${sharedTool} should be in ${mod.id} tool set`).toContain(sharedTool);
+                        });
+                    }
+                }
+            });
+        }
+        // ── Auto-generated: core tools present at high confidence ────────
+        (0, vitest_1.describe)('core tool availability', () => {
+            for (const mod of modules) {
+                (0, vitest_1.it)(`${mod.id} includes all declared core tools at high confidence`, () => {
+                    const result = (0, helpers_js_1.simulatePipeline)(components, `test ${mod.id}`, {
+                        intent: mod.id,
+                        confidence: 0.95,
+                    });
+                    for (const tool of mod.tools) {
+                        (0, vitest_1.expect)(result.tools, `Core tool "${tool}" should be in ${mod.id}`).toContain(tool);
+                    }
+                });
+            }
+        });
+        // ── User-defined workflow chains ─────────────────────────────────
+        if (cases && cases.length > 0) {
+            (0, vitest_1.describe)('workflow chains', () => {
+                for (const testCase of cases) {
+                    const confidence = testCase.confidence ?? 0.95;
+                    (0, vitest_1.it)(`${testCase.name}: all tools available`, () => {
+                        const result = (0, helpers_js_1.simulatePipeline)(components, testCase.name, {
+                            intent: testCase.intent,
+                            confidence,
+                        });
+                        (0, vitest_1.expect)(result.blocked).toBe(false);
+                        for (const tool of testCase.requiredToolChain) {
+                            (0, vitest_1.expect)(result.tools, `Workflow "${testCase.name}" requires "${tool}" in ${testCase.intent}`).toContain(tool);
+                        }
+                    });
+                }
+            });
+            // ── HTTP execution chains (optional) ─────────────────────────
+            const executor = options?.toolExecutor;
+            const casesWithExecution = cases.filter((c) => c.execution && c.execution.length > 0);
+            if (executor && casesWithExecution.length > 0) {
+                (0, vitest_1.describe)('HTTP execution chains', () => {
+                    for (const testCase of casesWithExecution) {
+                        (0, vitest_1.it)(`${testCase.name}: mock execution succeeds`, () => {
+                            const results = [];
+                            for (const step of testCase.execution) {
+                                const result = executor.execute(step.tool, step.input, step.mockResponse);
+                                results.push({ tool: step.tool, success: result.success });
+                                if (result.validationError) {
+                                    vitest_1.expect.fail(`Tool "${step.tool}" input validation failed: ${result.validationError}`);
+                                }
+                            }
+                            if (testCase.expect?.allToolsSucceeded) {
+                                for (const r of results) {
+                                    (0, vitest_1.expect)(r.success, `${r.tool} should succeed`).toBe(true);
+                                }
+                            }
+                        });
+                    }
+                });
+            }
+        }
+    });
+}

package/dist/cjs/server/testing/create-test-suite.d.ts

@@ -0,0 +1,29 @@
+import type { TestSuiteConfig, AiTestSuite } from './types.js';
+/**
+ * Create an AI test suite for testing pipeline behavior without LLM calls.
+ *
+ * Each method registers `describe`/`it` blocks via Vitest globals.
+ * Call the methods at the top level of your test file (outside `describe`).
+ *
+ * @example
+ * ```ts
+ * import { createAiTestSuite } from './index.js';
+ * import { modules } from '@/lib/ai/module-definitions';
+ *
+ * const suite = createAiTestSuite({
+ *   modules,
+ *   pipeline: {
+ *     guardrails: { enableInjectionDetection: true, maxInputLength: 4000 },
+ *     confidenceThresholds: { high: 0.85, medium: 0.65 },
+ *   },
+ * });
+ *
+ * suite.smokeTest();
+ * suite.guardrailsTest();
+ *
+ * suite.routingTest([
+ *   { input: 'show my tasks', expectModule: 'task_query', expectTools: ['list_tasks'] },
+ * ]);
+ * ```
+ */
+export declare function createAiTestSuite(config: TestSuiteConfig): AiTestSuite;

package/dist/cjs/server/testing/create-test-suite.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAiTestSuite = createAiTestSuite;
+const helpers_js_1 = require("./helpers.js");
+const smoke_js_1 = require("./smoke.js");
+const routing_js_1 = require("./routing.js");
+const guardrails_js_1 = require("./guardrails.js");
+const approvals_js_1 = require("./approvals.js");
+const combination_js_1 = require("./combination.js");
+const edge_cases_js_1 = require("./edge-cases.js");
+const schema_consistency_js_1 = require("./schema-consistency.js");
+const regression_js_1 = require("./regression.js");
+/**
+ * Create an AI test suite for testing pipeline behavior without LLM calls.
+ *
+ * Each method registers `describe`/`it` blocks via Vitest globals.
+ * Call the methods at the top level of your test file (outside `describe`).
+ *
+ * @example
+ * ```ts
+ * import { createAiTestSuite } from './index.js';
+ * import { modules } from '@/lib/ai/module-definitions';
+ *
+ * const suite = createAiTestSuite({
+ *   modules,
+ *   pipeline: {
+ *     guardrails: { enableInjectionDetection: true, maxInputLength: 4000 },
+ *     confidenceThresholds: { high: 0.85, medium: 0.65 },
+ *   },
+ * });
+ *
+ * suite.smokeTest();
+ * suite.guardrailsTest();
+ *
+ * suite.routingTest([
+ *   { input: 'show my tasks', expectModule: 'task_query', expectTools: ['list_tasks'] },
+ * ]);
+ * ```
+ */
+function createAiTestSuite(config) {
+    const { modules, tools: toolRegistry, pipeline, } = config;
+    const components = (0, helpers_js_1.buildPipelineComponents)(modules, pipeline?.guardrails, pipeline?.confidenceThresholds);
+    return {
+        smokeTest() {
+            (0, smoke_js_1.runSmokeTest)(modules, toolRegistry);
+        },
+        routingTest(cases) {
+            (0, routing_js_1.runRoutingTest)(components, cases);
+        },
+        guardrailsTest(options) {
+            (0, guardrails_js_1.runGuardrailsTest)(pipeline?.guardrails, options);
+        },
+        approvalTest() {
+            if (!toolRegistry) {
+                throw new Error('approvalTest() requires a tool registry. Pass `tools` to createAiTestSuite().');
+            }
+            (0, approvals_js_1.runApprovalTest)(toolRegistry);
+        },
+        simulatePipeline(input, intent) {
+            return (0, helpers_js_1.simulatePipeline)(components, input, intent);
+        },
+        combinationTest(cases, options) {
+            (0, combination_js_1.runCombinationTest)(components, cases, options);
+        },
+        edgeCaseTest(options) {
+            if (!toolRegistry) {
+                throw new Error('edgeCaseTest() requires a tool registry. Pass `tools` to createAiTestSuite().');
+            }
+            (0, edge_cases_js_1.runEdgeCaseTest)(toolRegistry, options);
+        },
+        schemaConsistencyTest(options) {
+            if (!toolRegistry) {
+                throw new Error('schemaConsistencyTest() requires a tool registry. Pass `tools` to createAiTestSuite().');
+            }
+            (0, schema_consistency_js_1.runSchemaConsistencyTest)(toolRegistry, options);
+        },
+        regressionTest(cases) {
+            (0, regression_js_1.runRegressionTest)(components, toolRegistry ?? {}, cases);
+        },
+    };
+}

package/dist/cjs/server/testing/edge-cases.d.ts

@@ -0,0 +1,8 @@
+import type { EdgeCaseTestOptions } from './types.js';
+/**
+ * Auto-generates edge case tests from tool Zod schemas + custom cases.
+ *
+ * For each tool with an `inputSchema`, introspects the Zod schema to generate
+ * boundary tests for required fields, enums, arrays with limits, etc.
+ */
+export declare function runEdgeCaseTest(toolRegistry: Record<string, unknown>, options?: EdgeCaseTestOptions): void;