holomime 1.8.0 → 1.9.1

package/dist/integrations/langchain.d.ts

@@ -0,0 +1,164 @@
+import { z } from 'zod';
+
+declare const severitySchema: z.ZodEnum<["info", "warning", "concern"]>;
+type Severity = z.infer<typeof severitySchema>;
+interface DetectedPattern {
+    id: string;
+    name: string;
+    severity: Severity;
+    count: number;
+    percentage: number;
+    description: string;
+    examples: string[];
+    prescription?: string;
+}
+
+/**
+ * Composable Guard API — chain behavioral detectors like Guardrails AI chains validators.
+ *
+ * Usage:
+ *   import { Guard } from "holomime";
+ *
+ *   const guard = Guard.create("my-agent")
+ *     .use(detectApologies)
+ *     .use(detectHedging)
+ *     .use(detectSentiment);
+ *
+ *   const result = guard.run(messages);
+ *   if (!result.passed) {
+ *     console.log(result.patterns);  // failing patterns
+ *   }
+ */
+
+interface GuardResult {
+    /** Whether all detectors passed (no warning/concern patterns). */
+    passed: boolean;
+    /** Agent name. */
+    agent: string;
+    /** Total messages analyzed. */
+    messagesAnalyzed: number;
+    /** Patterns that triggered (warning or concern severity). */
+    patterns: DetectedPattern[];
+    /** Healthy patterns (info severity). */
+    healthy: DetectedPattern[];
+    /** All detectors that were run. */
+    detectorsRun: number;
+    /** Timestamp. */
+    timestamp: string;
+    /** Overall severity: "clean" | "warning" | "concern". */
+    severity: "clean" | "warning" | "concern";
+}
+
+/**
+ * LangChain / CrewAI / LlamaIndex Callback Handler
+ *
+ * Monitors LLM responses in real-time and detects behavioral anti-patterns.
+ * Works with any LangChain-compatible framework that supports callback handlers.
+ *
+ * Usage:
+ *   import { HolomimeCallbackHandler } from "holomime/integrations/langchain";
+ *
+ *   const handler = new HolomimeCallbackHandler({
+ *     mode: "monitor",     // "monitor" | "enforce" | "strict"
+ *     personality: ".personality.json",
+ *     onViolation: (v) => console.warn("Behavioral drift:", v),
+ *   });
+ *
+ *   // LangChain
+ *   const chain = prompt.pipe(model).pipe(parser);
+ *   await chain.invoke({ input: "hello" }, { callbacks: [handler] });
+ *
+ *   // CrewAI — pass as LangChain callback on the underlying LLM
+ *   // LlamaIndex — use as a callback handler on the LLM
+ */
+
+type CallbackMode = "monitor" | "enforce" | "strict";
+interface CallbackViolation {
+    patterns: DetectedPattern[];
+    severity: "warning" | "concern";
+    response: string;
+    runId?: string;
+    timestamp: string;
+}
+interface HolomimeCallbackOptions {
+    /** Guard mode. Default: "monitor". */
+    mode?: CallbackMode;
+    /** Path to .personality.json or inline spec object. */
+    personality?: string | object;
+    /** Minimum severity to trigger. Default: "warning". */
+    minSeverity?: "warning" | "concern";
+    /** Callback fired on every violation. */
+    onViolation?: (violation: CallbackViolation) => void;
+    /** Agent name for reports. Default: "langchain-agent". */
+    name?: string;
+    /** Buffer size — number of messages to retain for context. Default: 50. */
+    bufferSize?: number;
+}
+interface CallbackStats {
+    totalResponses: number;
+    passed: number;
+    violated: number;
+    blocked: number;
+    patternCounts: Record<string, number>;
+}
+/**
+ * HolomimeCallbackHandler — behavioral alignment monitor for LangChain-compatible frameworks.
+ *
+ * Implements the LangChain BaseCallbackHandler interface without importing langchain,
+ * keeping it as an optional peer dependency. Works with LangChain, CrewAI, and any
+ * framework that accepts { handleLLMEnd, handleLLMStart, handleLLMError } callbacks.
+ */
+declare class HolomimeCallbackHandler {
+    readonly name = "holomime";
+    readonly lc_serializable = false;
+    private guard;
+    private mode;
+    private minSeverity;
+    private onViolation?;
+    private messageBuffer;
+    private bufferSize;
+    private currentRunMessages;
+    private _stats;
+    constructor(options?: HolomimeCallbackOptions);
+    /**
+     * Called when an LLM starts generating.
+     * Captures the input messages for context.
+     */
+    handleLLMStart(_llm: any, prompts: string[], runId?: string): void;
+    /**
+     * Called when an LLM finishes generating.
+     * Runs behavioral analysis on the response.
+     */
+    handleLLMEnd(output: any, runId?: string): void;
+    /**
+     * Called on LLM errors. Clean up run tracking.
+     */
+    handleLLMError(_error: any, runId?: string): void;
+    /**
+     * Called when a chain starts. Captures input for context.
+     */
+    handleChainStart(_chain: any, inputs: Record<string, any>, runId?: string): void;
+    /**
+     * Get cumulative stats.
+     */
+    stats(): CallbackStats;
+    /**
+     * Reset the message buffer and stats.
+     */
+    reset(): void;
+    /**
+     * Get the current guard result for the buffered conversation.
+     */
+    diagnose(): GuardResult;
+    private severityMeetsMin;
+    private extractResponseText;
+}
+/**
+ * Error thrown in strict mode when a concern-level violation is detected.
+ */
+declare class HolomimeViolationError extends Error {
+    readonly violation: CallbackViolation;
+    constructor(violation: CallbackViolation);
+}
+
+export { type CallbackMode, type CallbackStats, type CallbackViolation, HolomimeCallbackHandler, type HolomimeCallbackOptions, HolomimeViolationError };