@neuroverseos/governance 0.3.1 → 0.3.3

package/dist/adapters/langchain.d.cts

@@ -0,0 +1,89 @@
+import { G as GuardEvent, a as GuardVerdict, b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, c as PlanProgress } from '../guard-contract-DqFcTScd.cjs';
+import { G as GovernanceBlockedError$1 } from '../shared-B8dvUUD8.cjs';
+
+/**
+ * NeuroVerse Adapter — LangChain
+ *
+ * Wraps the governance engine as a LangChain tool-calling middleware.
+ * Intercepts tool invocations and evaluates them against a world definition
+ * before allowing execution to proceed.
+ *
+ * Usage:
+ *   import { createNeuroVerseCallbackHandler } from 'neuroverse-governance/adapters/langchain';
+ *
+ *   const handler = await createNeuroVerseCallbackHandler('./world/', {
+ *     onBlock: (verdict) => console.log('Blocked:', verdict.reason),
+ *     onPause: (verdict) => requestHumanApproval(verdict),
+ *   });
+ *
+ *   const agent = new AgentExecutor({ ..., callbacks: [handler] });
+ */
+
+interface NeuroVerseHandlerOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called when an action is blocked. */
+    onBlock?: (verdict: GuardVerdict, event: GuardEvent) => void;
+    /** Called when an action requires approval. Return true to allow. */
+    onPause?: (verdict: GuardVerdict, event: GuardEvent) => Promise<boolean> | boolean;
+    /** Called for every evaluation (logging hook). */
+    onEvaluate?: (verdict: GuardVerdict, event: GuardEvent) => void;
+    /** Map a tool call to a GuardEvent. Override for custom tool shapes. */
+    mapToolCall?: (toolName: string, toolInput: Record<string, unknown>) => GuardEvent;
+    /** Active plan overlay for task-scoped governance. */
+    plan?: PlanDefinition;
+    /** Called when plan progress changes. */
+    onPlanProgress?: (progress: PlanProgress) => void;
+    /** Called when all plan steps are completed. */
+    onPlanComplete?: () => void;
+}
+declare class GovernanceBlockedError extends GovernanceBlockedError$1 {
+    readonly event: GuardEvent;
+    constructor(verdict: GuardVerdict, event: GuardEvent);
+}
+/**
+ * A LangChain-compatible callback handler that evaluates tool calls
+ * against a NeuroVerse world definition.
+ *
+ * Implements the BaseCallbackHandler interface shape so it can be
+ * passed directly into LangChain's callbacks array.
+ */
+declare class NeuroVerseCallbackHandler {
+    readonly name = "NeuroVerseGovernance";
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapToolCall;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: NeuroVerseHandlerOptions);
+    /**
+     * Called before a tool is executed.
+     * Evaluates the tool call against the governance world.
+     *
+     * @throws GovernanceBlockedError if the action is BLOCKED
+     * @throws GovernanceBlockedError if the action is PAUSED and onPause returns false
+     */
+    handleToolStart(tool: {
+        name: string;
+    }, input: string): Promise<void>;
+}
+/**
+ * Create a NeuroVerse callback handler from a world path.
+ *
+ * @param worldPath - Path to world directory or .nv-world.zip
+ * @param options - Handler configuration
+ * @returns A callback handler ready to plug into LangChain
+ */
+declare function createNeuroVerseCallbackHandler(worldPath: string, options?: NeuroVerseHandlerOptions): Promise<NeuroVerseCallbackHandler>;
+/**
+ * Create a NeuroVerse callback handler from a pre-loaded world.
+ *
+ * @param world - A loaded WorldDefinition
+ * @param options - Handler configuration
+ * @returns A callback handler ready to plug into LangChain
+ */
+declare function createNeuroVerseCallbackHandlerFromWorld(world: WorldDefinition, options?: NeuroVerseHandlerOptions): NeuroVerseCallbackHandler;
+
+export { GovernanceBlockedError, NeuroVerseCallbackHandler, type NeuroVerseHandlerOptions, createNeuroVerseCallbackHandler, createNeuroVerseCallbackHandlerFromWorld };

package/dist/adapters/langchain.d.ts

@@ -0,0 +1,89 @@
+import { G as GuardEvent, a as GuardVerdict, b as GuardEngineOptions, P as PlanDefinition, W as WorldDefinition, c as PlanProgress } from '../guard-contract-DqFcTScd.js';
+import { G as GovernanceBlockedError$1 } from '../shared-Dr5Wiay8.js';
+
+/**
+ * NeuroVerse Adapter — LangChain
+ *
+ * Wraps the governance engine as a LangChain tool-calling middleware.
+ * Intercepts tool invocations and evaluates them against a world definition
+ * before allowing execution to proceed.
+ *
+ * Usage:
+ *   import { createNeuroVerseCallbackHandler } from 'neuroverse-governance/adapters/langchain';
+ *
+ *   const handler = await createNeuroVerseCallbackHandler('./world/', {
+ *     onBlock: (verdict) => console.log('Blocked:', verdict.reason),
+ *     onPause: (verdict) => requestHumanApproval(verdict),
+ *   });
+ *
+ *   const agent = new AgentExecutor({ ..., callbacks: [handler] });
+ */
+
+interface NeuroVerseHandlerOptions {
+    /** Include full evaluation trace in verdicts. Default: false. */
+    trace?: boolean;
+    /** Enforcement level override. */
+    level?: 'basic' | 'standard' | 'strict';
+    /** Called when an action is blocked. */
+    onBlock?: (verdict: GuardVerdict, event: GuardEvent) => void;
+    /** Called when an action requires approval. Return true to allow. */
+    onPause?: (verdict: GuardVerdict, event: GuardEvent) => Promise<boolean> | boolean;
+    /** Called for every evaluation (logging hook). */
+    onEvaluate?: (verdict: GuardVerdict, event: GuardEvent) => void;
+    /** Map a tool call to a GuardEvent. Override for custom tool shapes. */
+    mapToolCall?: (toolName: string, toolInput: Record<string, unknown>) => GuardEvent;
+    /** Active plan overlay for task-scoped governance. */
+    plan?: PlanDefinition;
+    /** Called when plan progress changes. */
+    onPlanProgress?: (progress: PlanProgress) => void;
+    /** Called when all plan steps are completed. */
+    onPlanComplete?: () => void;
+}
+declare class GovernanceBlockedError extends GovernanceBlockedError$1 {
+    readonly event: GuardEvent;
+    constructor(verdict: GuardVerdict, event: GuardEvent);
+}
+/**
+ * A LangChain-compatible callback handler that evaluates tool calls
+ * against a NeuroVerse world definition.
+ *
+ * Implements the BaseCallbackHandler interface shape so it can be
+ * passed directly into LangChain's callbacks array.
+ */
+declare class NeuroVerseCallbackHandler {
+    readonly name = "NeuroVerseGovernance";
+    private world;
+    private options;
+    engineOptions: GuardEngineOptions;
+    private mapToolCall;
+    activePlan?: PlanDefinition;
+    constructor(world: WorldDefinition, options?: NeuroVerseHandlerOptions);
+    /**
+     * Called before a tool is executed.
+     * Evaluates the tool call against the governance world.
+     *
+     * @throws GovernanceBlockedError if the action is BLOCKED
+     * @throws GovernanceBlockedError if the action is PAUSED and onPause returns false
+     */
+    handleToolStart(tool: {
+        name: string;
+    }, input: string): Promise<void>;
+}
+/**
+ * Create a NeuroVerse callback handler from a world path.
+ *
+ * @param worldPath - Path to world directory or .nv-world.zip
+ * @param options - Handler configuration
+ * @returns A callback handler ready to plug into LangChain
+ */
+declare function createNeuroVerseCallbackHandler(worldPath: string, options?: NeuroVerseHandlerOptions): Promise<NeuroVerseCallbackHandler>;
+/**
+ * Create a NeuroVerse callback handler from a pre-loaded world.
+ *
+ * @param world - A loaded WorldDefinition
+ * @param options - Handler configuration
+ * @returns A callback handler ready to plug into LangChain
+ */
+declare function createNeuroVerseCallbackHandlerFromWorld(world: WorldDefinition, options?: NeuroVerseHandlerOptions): NeuroVerseCallbackHandler;
+
+export { GovernanceBlockedError, NeuroVerseCallbackHandler, type NeuroVerseHandlerOptions, createNeuroVerseCallbackHandler, createNeuroVerseCallbackHandlerFromWorld };

package/dist/adapters/langchain.js

@@ -0,0 +1,17 @@
+import {
+  GovernanceBlockedError,
+  NeuroVerseCallbackHandler,
+  createNeuroVerseCallbackHandler,
+  createNeuroVerseCallbackHandlerFromWorld
+} from "../chunk-3WQLXYTP.js";
+import "../chunk-5U2MQO5P.js";
+import "../chunk-W7LLXRGY.js";
+import "../chunk-QLPTHTVB.js";
+import "../chunk-CTZHONLA.js";
+import "../chunk-QWGCMQQD.js";
+export {
+  GovernanceBlockedError,
+  NeuroVerseCallbackHandler,
+  createNeuroVerseCallbackHandler,
+  createNeuroVerseCallbackHandlerFromWorld
+};