Skip to main content

​
Overview

PromptValidator validates builder configuration and provides helpful error messages, warnings, and suggestions. It catches common configuration issues before you build the prompt, helping ensure your prompt is complete and well-structured.

​
Factory Function

​
createValidator()

Creates a validator with optional custom configuration. 
import { createValidator } from "promptsmith-ts/validation";

const validator = createValidator();

// With custom configuration
const customValidator = createValidator({
  checkDuplicateTools: true,
  checkIdentity: false // Don't warn about missing identity
});
​
config
ValidatorConfig
Optional validator configuration
Returns: A new PromptValidator instance

​
Constructor

const validator = new PromptValidator(config?: ValidatorConfig);
​
config
ValidatorConfig
Optional configuration object

​
ValidatorConfig

Configuration options for customizing validation behavior. 
type ValidatorConfig = {
  checkDuplicateTools?: boolean;      // Check for duplicate tool names (default: true)
  checkIdentity?: boolean;            // Check for missing identity (default: true)
  checkRecommendations?: boolean;     // Check for recommended sections (default: true)
  checkConstraintConflicts?: boolean; // Check for conflicting constraints (default: true)
  checkEmptySections?: boolean;       // Check for empty sections (default: true)
}
​
checkDuplicateTools
boolean
default:"true"
Whether to check for duplicate tool names
​
checkIdentity
boolean
default:"true"
Whether to check for missing identity
​
checkRecommendations
boolean
default:"true"
Whether to check for recommended sections (e.g., examples for tools, guardrails)
​
checkConstraintConflicts
boolean
default:"true"
Whether to check for conflicting constraints
​
checkEmptySections
boolean
default:"true"
Whether to check for empty sections (capabilities, constraints)

​
Methods

​
validate()

Validates the builder state and returns detailed results. 
validate(state: {
  identity: string;
  capabilities: string[];
  tools: ExecutableToolDefinition[];
  constraints: Constraint[];
  examples: Example[];
  guardrailsEnabled: boolean;
  forbiddenTopics: string[];
  context: string;
  tone: string;
  outputFormat: string;
  errorHandling: string;
}): ValidationResult
​
state
object
required
The builder state to validate. Usually passed from SystemPromptBuilder.validate()
Returns:
​
ValidationResult
object
Result of the validation check
​
valid
boolean
True if no errors were found, false otherwise
​
errors
ValidationIssue[]
Array of error-level issues that prevent valid configuration
​
warnings
ValidationIssue[]
Array of warning-level issues that suggest improvements
​
info
ValidationIssue[]
Array of informational suggestions for best practices

​
Type Definitions

​
ValidationIssue

Represents a single validation issue found in the configuration. 
type ValidationIssue = {
  severity: "error" | "warning" | "info";
  code: string;
  message: string;
  suggestion?: string;
}
​
severity
'error' | 'warning' | 'info'
required
The severity level of the issue
​
code
string
required
Machine-readable code identifying the issue type (e.g., “DUPLICATE_TOOL”, “MISSING_IDENTITY”)
​
message
string
required
Human-readable description of the issue
​
suggestion
string
Optional suggestion for how to fix the issue
Issue Codes: Errors:
  • DUPLICATE_TOOL: Duplicate tool name detected
Warnings:
  • MISSING_IDENTITY: No identity set
  • EMPTY_CAPABILITIES: No capabilities defined
  • EMPTY_CONSTRAINTS: No behavioral constraints defined
  • CONFLICTING_CONSTRAINTS: Potentially conflicting constraints detected
Info:
  • TOOLS_WITHOUT_EXAMPLES: Tools defined without usage examples
  • TOOLS_WITHOUT_GUARDRAILS: Tools defined without security guardrails
  • NO_MUST_CONSTRAINTS: No “must” constraints defined

​
ValidationSeverity

type ValidationSeverity = "error" | "warning" | "info";
  • error: Prevents valid configuration, must be fixed
  • warning: Suggests improvements, should be addressed
  • info: Best practice recommendations, optional

​
Helper Functions

​
formatValidationResult()

Formats validation results as a human-readable string. 
import { formatValidationResult } from "promptsmith-ts/validation";

function formatValidationResult(result: ValidationResult): string
​
result
ValidationResult
required
The validation result to format
Returns: Formatted string with all errors, warnings, and info messages

​
Usage Examples

​
Basic Validation

import { createPromptBuilder } from "promptsmith-ts";

const builder = createPromptBuilder()
  .withIdentity("You are a helpful assistant")
  .withCapability("Answer questions");

const result = builder.validate();

if (!result.valid) {
  console.error("Validation failed!");
  for (const error of result.errors) {
    console.error(`[${error.code}] ${error.message}`);
    if (error.suggestion) {
      console.error(`  → ${error.suggestion}`);
    }
  }
}

if (result.warnings.length > 0) {
  console.warn("Warnings:");
  for (const warning of result.warnings) {
    console.warn(`[${warning.code}] ${warning.message}`);
  }
}

​
Using formatValidationResult()

import { createPromptBuilder } from "promptsmith-ts";
import { formatValidationResult } from "promptsmith-ts/validation";

const builder = createPromptBuilder()
  .withIdentity("Assistant")
  .withCapability("Help users");

const result = builder.validate();
console.log(formatValidationResult(result));

// Output:
// ✓ Validation passed
// 
// Warnings (2):
//   ⚠ [EMPTY_CONSTRAINTS] No behavioral constraints defined
//     → Add constraints with .withConstraint() to define behavioral guidelines
//   ⚠ [...]

​
Custom Validator Configuration

import { createValidator } from "promptsmith-ts/validation";

const validator = createValidator({
  checkDuplicateTools: true,
  checkIdentity: false,        // Don't warn about missing identity
  checkRecommendations: false  // Don't check best practices
});

const builder = createPromptBuilder()
  .withCapability("Answer questions");

const result = validator.validate({
  identity: "",
  capabilities: builder.getCapabilities(),
  tools: builder.getTools(),
  // ... other state
});

​
Validation with Builder

import { createPromptBuilder } from "promptsmith-ts";

const builder = createPromptBuilder()
  .withIdentity("Customer service assistant")
  .withValidatorConfig({
    checkDuplicateTools: true,
    checkConstraintConflicts: true
  });

// Validate with configured validator
const result = builder.validate();

// Or override configuration
const customResult = builder.validate({
  checkRecommendations: false
});

​
Detecting Duplicate Tools

import { createPromptBuilder } from "promptsmith-ts";
import { z } from "zod";

const builder = createPromptBuilder()
  .withTool({
    name: "search",
    description: "Search the web",
    schema: z.object({ query: z.string() })
  })
  .withTool({
    name: "search", // Duplicate!
    description: "Search database",
    schema: z.object({ query: z.string() })
  });

const result = builder.validate();

if (!result.valid) {
  console.error(result.errors);
  // [
  //   {
  //     severity: "error",
  //     code: "DUPLICATE_TOOL",
  //     message: "Duplicate tool name: 'search'",
  //     suggestion: "Tool names must be unique. Rename one of the 'search' tools."
  //   }
  // ]
}

​
Comprehensive Validation

import { createPromptBuilder } from "promptsmith-ts";
import { formatValidationResult } from "promptsmith-ts/validation";
import { z } from "zod";

const builder = createPromptBuilder()
  .withIdentity("You are a coding assistant")
  .withCapabilities([
    "Write code",
    "Explain concepts",
    "Debug issues"
  ])
  .withTool({
    name: "run_code",
    description: "Execute code",
    schema: z.object({
      code: z.string(),
      language: z.string()
    })
  })
  .withConstraint("must", "Always explain the code you write")
  .withConstraint("must_not", "Never execute untrusted code")
  .withGuardrails();

const result = builder.validate();

console.log(formatValidationResult(result));

// Might output:
// ✓ Validation passed
//
// Info (1):
//   ℹ [TOOLS_WITHOUT_EXAMPLES] Tools defined without usage examples
//     → Add examples with .withExamples() to demonstrate proper tool usage

if (result.info.some(i => i.code === "TOOLS_WITHOUT_EXAMPLES")) {
  builder.withExamples([
    {
      user: "Write a hello world in Python",
      assistant: "I'll write a simple Python hello world program.",
      explanation: "Shows basic code writing task"
    }
  ]);
}

​
Pre-Build Validation

import { createPromptBuilder } from "promptsmith-ts";
import { formatValidationResult } from "promptsmith-ts/validation";

function buildValidatedPrompt(builder: SystemPromptBuilder): string {
  const result = builder.validate();
  
  if (!result.valid) {
    throw new Error(
      `Invalid prompt configuration:\n${formatValidationResult(result)}`
    );
  }
  
  if (result.warnings.length > 0) {
    console.warn("Validation warnings:");
    console.warn(formatValidationResult(result));
  }
  
  return builder.build();
}

const builder = createPromptBuilder()
  .withIdentity("Assistant")
  .withCapability("Help users");

try {
  const prompt = buildValidatedPrompt(builder);
  console.log("Prompt built successfully!");
} catch (error) {
  console.error(error.message);
}

​
Best Practices

Validate Before Building:
  • Always validate your builder configuration before calling .build()
  • Address errors immediately - they indicate broken configuration
  • Consider warnings carefully - they often highlight missing best practices
Use Custom Validation for Special Cases:
  • Disable specific checks if they don’t apply to your use case
  • Create custom validators for domain-specific requirements
  • Document why you’re disabling default checks
Don’t Ignore Errors:
  • Errors (like duplicate tools) will cause runtime issues
  • Fix errors before deploying to production
  • Warnings about missing sections often indicate incomplete prompts

​
Validation Checks

​
Error Checks

  1. Duplicate Tool Names: Ensures all tool names are unique (required for AI SDK)

​
Warning Checks

  1. Missing Identity: Warns if no identity is set
  2. Empty Capabilities: Warns if no capabilities are defined
  3. Empty Constraints: Warns if no behavioral constraints are defined
  4. Conflicting Constraints: Warns about potentially conflicting must/must_not rules

​
Info Checks

  1. Tools Without Examples: Suggests adding examples when tools are present
  2. Tools Without Guardrails: Suggests enabling guardrails when tools are present
  3. No Must Constraints: Suggests adding critical “must” constraints

Build docs developers (and LLMs) love

Get started for freeTalk to us