🛡️ node-ai-guard

The safety layer for AI Agents. Validate, sanitize, and govern AI-generated intents before they hit your production APIs.

The Problem: AI Hallucinations & Excessive Agency

Large Language Models (LLMs) are great at calling tools, but they are unpredictable. When you give an AI Agent access to your APIs (Stripe, Slack, Database), you face critical risks:

1. Hallucinations: The AI sends parameters that don't exist or are formatted incorrectly.
2. Excessive Agency: The AI tries to refund $10,000 instead of $10 because it misread the prompt.
3. Security Risks: A user tricks your AI into executing destructive commands via prompt injection.

node-ai-guard provides a Zod-powered guardrail wrapper designed specifically for AI-generated JSON payloads. It ensures every action is structurally sound and follows strict business safety rules.

🚀 Installation

npm install node-ai-guard zod

🛠️ Quick Start

Define a Guard with a schema and custom safety rules. If the AI violates a rule, the guard returns a clear error that you can feed back to the AI for self-correction.

import { createGuard } from 'node-ai-guard';
import { z } from 'zod';

// 1. Define your safety guard
const refundGuard = createGuard({
  name: "process_refund",
  description: "Used to issue a refund to a customer.",
  schema: z.object({
    orderId: z.string(),
    amount: z.number(),
    reason: z.string()
  }),
  // Hard safety rules the AI cannot bypass
  rules: [
    {
      check: (data) => data.amount <= 100,
      message: "Refunds over $100 require manual manager intervention."
    }
  ]
});

// 2. Validate the AI's intent (e.g., from an LLM tool call)
const aiIntent = { orderId: "ORD-99", amount: 500, reason: "Defective" };

const result = await refundGuard.validate(aiIntent);

if (!result.success) {
  console.log("🚫 Action Blocked:", result.error); 
  // Output: "Refunds over $100 require manual manager intervention."
}

✨ Key Features

• ✅ Type-Safe Validation: Full TypeScript support with Zod integration.
• 🛡️ Business Rule Engine: Go beyond data types. Set custom logic for risk scores and safety limits.
• 🤖 AI Self-Correction: Returns detailed error messages designed to help LLMs realize their mistake and retry.
• 📦 Lightweight & Fast: Zero bloat, optimized for high-throughput Node.js environments like Express or AWS Lambda.
• 📜 Audit Trail Ready: Easily logs attempts to MongoDB or PostgreSQL for compliance and debugging.

🗺️ Roadmap (Phase 1 & 2)

• [x] Core Zod Wrapper
• [x] Custom Safety Rules Engine
• [ ] Middleware Support: First-class support for Express.js and Fastify.
• [ ] Human-in-the-Loop: Built-in hooks for Slack/Discord "Approve/Deny" buttons.
• [ ] Tool Definition Generator: Automatically export OpenAI-compatible JSON tool definitions from your guards.

🤝 Contributing

This is an early-stage project built to solve AI trust issues. If you have ideas for safety patterns (Human-in-the-loop, rate limiting for agents, etc.), feel free to open an issue!

📄 License

MIT © [josephallwin1996]