API Reference

Public exports from the shieldkit npm package (src/index.ts).

Functions

shield(model, config?)

Wraps a LanguageModelV3 with the full middleware chain.

Parameter	Type	Description
model	LanguageModel	Base model from any AI SDK provider
config	ShieldConfig?	Optional shield configuration

Returns: LanguageModel — use with generateText, streamText, etc.

See: Architecture overview · Verification matrix

---

shieldGenerateText(params)

Like generateText, with extra retry handling when NoObjectGeneratedError is thrown.

Parameter	Type	Description
params	GenerateTextParams	Standard AI SDK params
params.model	LanguageModel	Shield-wrapped model
params.config	ShieldConfig?	Repair config override
params.outputSchema	z.ZodType?	Schema for validation/repair
params.maxRepairAttempts	number?	Override maxAttempts

Returns: Promise<GenerateTextResult>

Throws: ShieldRepairError when retries are exhausted

See: Structured output

---

shieldStreamText(params)

Like streamText, merging outputSchema into providerOptions.aiShield.

Parameter	Type	Description
params	StreamTextParams	Standard AI SDK params
params.model	LanguageModel	Shield-wrapped model
params.outputSchema	z.ZodType?	Schema for repair middleware

Returns: StreamTextResult

Note: No dedicated test coverage — see verification matrix.

---

guardTools(tools, options?)

Wraps tool execute functions with invocation policies.

Parameter	Type	Description
tools	Record<string, Tool>	AI SDK tool definitions
options	ToolGuardOptions?	Allow/deny, limits, approval

Returns: Same tool record shape with wrapped execute functions.

See: Tool guards

---

resolveConfig(config?)

Resolves ShieldConfig to a fully merged ResolvedShieldConfig without wrapping a model.

See: Configuration

---

Session helpers

Function	Description
createShieldContext(sessionId?)	Initialize or reset session state (default ID: "default")
getOrCreateSession(sessionId?)	Get existing session or create new
resetSession(sessionId)	Delete session from store
createRequestContext(options)	Build per-request context from ShieldProviderOptions
sessionStore	In-memory Map<string, SessionState> (advanced use)

See: Cost tracking

---

Error classes

All extend AISDKError from @ai-sdk/provider.

ShieldBlockedError

Guard blocked the request (input or output).

Property	Type	Description
guard	string	Guard name (injection, pii, keywords)
summary	string	Human-readable reason

---

ShieldBudgetError

Session cost budget exceeded.

Property	Type	Description
sessionId	string	Session key
totalCostUsd	number	Current or projected total
maxCostUsd	number	Configured limit

---

ShieldRepairError

Structured output repair exhausted all attempts.

Property	Type	Description
partialText	string	Last model output
attempts	number	Total attempts made
lastError	string	Final validation error
usage	object?	Merged token usage

---

ShieldToolError

Tool policy violation.

Property	Type	Description
toolName	string	Blocked tool
reason	string	Policy reason

---

Types

ShieldConfig

Top-level configuration passed to shield().

interface ShieldConfig {
  mode?: ShieldMode;
  guardrails?: GuardrailsConfig;
  cost?: CostConfig;
  audit?: AuditConfig;
}

ShieldMode

'balanced' | 'strict' | 'cheap' | 'local' | 'custom'

GuardAction

'block' | 'redact' | 'warn'

GuardrailsConfig

interface GuardrailsConfig {
  input?: {
    injection?: InjectionGuardConfig;
    pii?: PiiGuardConfig;
    keywords?: KeywordsGuardConfig;
  };
  output?: {
    repair?: RepairConfig;
    pii?: PiiGuardConfig;
    keywords?: KeywordsGuardConfig;
  };
}

RepairConfig

interface RepairConfig {
  enabled?: boolean;
  maxAttempts?: number;
  includePartialInRetry?: boolean; // default: true
}

CostConfig

interface CostConfig {
  maxCostPerSession?: number;
  trackOnly?: boolean;
  warnAtPercent?: number;
  pricing?: Record<string, ModelPricing>;
  defaultPricing?: ModelPricing;
}

AuditConfig

interface AuditConfig {
  enabled?: boolean;
  logLevel?: 'basic' | 'detailed';
  sink?: (log: AuditLog) => void | Promise<void>;
  console?: boolean;
}

ShieldProviderOptions

Per-request options via providerOptions.aiShield:

interface ShieldProviderOptions {
  sessionId?: string;
  userId?: string;
  requestId?: string;
  approved?: boolean;
  metadata?: Record<string, unknown>;
  outputSchema?: z.ZodType;
}

SessionState

interface SessionState {
  sessionId: string;
  totalCostUsd: number;
  totalInputTokens: number;
  totalOutputTokens: number;
  requestCount: number;
  budgetExceeded: boolean;
}

AuditLog

interface AuditLog {
  type: AuditEventType;
  timestamp: string;
  sessionId?: string;
  userId?: string;
  requestId?: string;
  modelId?: string;
  details?: Record<string, unknown>;
}

AuditEventType

'request.start' | 'request.complete' | 'request.blocked' | 'guard.triggered' | 'repair.attempt' | 'repair.success' | 'repair.failed' | 'cost.recorded' | 'budget.exceeded' | 'budget.warn' | 'tool.executed' | 'tool.blocked'

ToolGuardOptions

interface ToolGuardOptions {
  allow?: string[];
  deny?: string[];
  maxCallsPerRequest?: number;
  requireApproval?: boolean;
  requestId?: string;
  sessionId?: string;
  userId?: string;
  onBlocked?: (toolName: string, reason: string) => void;
  auditSink?: (log: AuditLog) => void | Promise<void>;
}

Other exported types

| Type | Description | | ---------------------- | ------------------------------------------ | ----------- | | ResolvedShieldConfig | Fully merged config from resolveConfig() | | RequestContext | Internal per-request state | | GuardResult | Result from a guard function | | ModelPricing | { inputPer1M?, outputPer1M? } | | LanguageModel | Alias for LanguageModelV3 | | ShieldRuntime | Shared middleware runtime (advanced) | | AuditLogLevel | 'basic' | 'detailed' |

Feature cross-reference

Symbol	Feature doc
Input guards	input-guardrails.md
Output guards	output-guardrails.md
Repair	structured-output.md
Cost	cost-tracking.md
Audit	audit-logging.md
Tools	tool-guards.md