Getting Started

Install shieldkit from npm and wrap your first language model in a few minutes.

Source repository: sakurablush/shieldkit.

Prerequisites

• Node.js ≥ 20
• Vercel AI SDK (ai ≥ 6) and Zod (^3.25 or ^4) as peer dependencies

Installation

npm install shieldkit ai zod

For local models, add an Ollama provider (optional):

npm install ollama-ai-provider-v2

First request

Wrap any LanguageModelV3 with shield() and pass a session ID per request:

import { generateText } from 'ai';
import { ollama } from 'ollama-ai-provider-v2';
import { shield } from 'shieldkit';

const model = shield(ollama('llama3.2'));

const { text } = await generateText({
  model,
  prompt: 'Say hello in one sentence.',
  providerOptions: {
    aiShield: { sessionId: 'demo-session' },
  },
});

With OpenAI or another provider, pass your existing model instead of ollama(...) — the API is the same.

Mode presets

Choose a preset when creating the shielded model:

const model = shield(baseModel, { mode: 'balanced' }); // default
const strict = shield(baseModel, { mode: 'strict' });
const local = shield(baseModel, { mode: 'local' });

Mode	Best for
balanced	General production use
strict	High-sensitivity data, tighter injection threshold
cheap	Low-cost demos, warn-only injection
local	Ollama / self-hosted, track-only budgets
custom	Full manual control over every setting

See Configuration for the full preset table.

Per-request context

Use providerOptions.aiShield on every call:

await generateText({
  model,
  prompt: '...',
  providerOptions: {
    aiShield: {
      sessionId: 'user-123', // cost budget key
      userId: 'auth-id', // audit correlation
      requestId: 'req-optional', // auto-generated if omitted
    },
  },
});

Common workflows

Structured JSON output

import { generateText, Output } from 'ai';
import { z } from 'zod';

const schema = z.object({ answer: z.string() });

const { output } = await generateText({
  model: shield(baseModel, { mode: 'local' }),
  output: Output.object({ schema }),
  prompt: 'Reply as JSON.',
  providerOptions: {
    aiShield: { sessionId: 's1', outputSchema: schema },
  },
});

Details: Structured output

Session budgets

import { createShieldContext, shield } from 'shieldkit';

createShieldContext('user-123');

const model = shield(baseModel, {
  cost: { maxCostPerSession: 0.5 },
});

Details: Cost tracking

Tool policies

import { guardTools, shield } from 'shieldkit';

const tools = guardTools(myTools, {
  allow: ['search'],
  maxCallsPerRequest: 3,
  requestId: 'req-abc',
});

Details: Tool guards

Custom audit sink

const model = shield(baseModel, {
  audit: {
    console: false,
    sink: (log) => myLogger.info(log),
  },
});

Details: Audit logging

Error handling

import {
  ShieldBlockedError,
  ShieldBudgetError,
  ShieldRepairError,
  ShieldToolError,
} from 'shieldkit';

try {
  await generateText({ model, prompt });
} catch (error) {
  if (error instanceof ShieldBlockedError) {
    // Guard blocked the request
  } else if (error instanceof ShieldBudgetError) {
    // Session budget exceeded
  }
}

All shield errors extend AISDKError from the AI SDK.

Full feature demo

From a clone of the repository, run the interactive tour (injection, homoglyph evasion, PII, repair, tools, budgets, optional live Ollama):

npm ci
npm run demo

Nine labeled sections with 31 automated PASS/FAIL checks — sections 1–8 use a mock model; section 9 needs Ollama. Exits 1 on failure. See Examples for the full list and agent-with-tools.ts.

Next steps

Topic	Doc
Architecture	Overview
All features	Features index
API symbols	API reference
Examples	Examples
Testing	Running tests
Contributing	Contributing