🛡️ Custom Validators in DSOM: Guardrails Architecture & Implementation Blueprint

Reference URL: Guardrails AI Custom Validators Guide
Status: Architectural Reference & How-To Guide for Human Engineers & AI Agents

---

🧭 1. Executive Summary & Philosophy

In modern AI agent engineering, unvalidated LLM output poses severe operational risks: hallucinations, syntax corruptions, security leaks, toxic biases, and broken schema definitions.

Guardrails AI provides a structured pattern for intercepting and validating inputs and outputs using programmatic validators (both deterministic code-based rules and lightweight LLM-evaluated checks).

Within the Deep State of Mind (DSOM) framework, we adopt and map these custom validation concepts directly into our Tri-Phasic Cognitive Pipeline and Subsystem 4 (Metacognition & Guardrails) without taking heavy, bloated runtime dependencies.

┌────────────────────────────────────────────────────────────────────────┐
│                    DSOM VALIDATOR INTERCEPTION PIPELINE                │
├────────────────────────────────────────────────────────────────────────┤
│ 1. Input Guardrail     │ FastMCP Tool Invocations / Prompt Sanitization │
├────────────────────────────────────────────────────────────────────────┤
│ 2. Inline Validator    │ Twilight State AST / Regex / OKF Schema Checks │
├────────────────────────────────────────────────────────────────────────┤
│ 3. Output Guardrail    │ EOD Palace Sync & GitOps Commit Gate (pytest)  │
└────────────────────────────────────────────────────────────────────────┘

---

🏛️ 2. Core Concepts: Anatomy of a Guardrails Custom Validator

In the Guardrails AI ecosystem, a custom validator is defined by: 1. Target Type: Whether it validates strings, JSON objects, lists, or AST code trees. 2. validate(value, metadata) Method: The core evaluation logic returning PassResult or FailResult. 3. On-Fail Actions: Deterministic corrective actions when validation fails: - reask: Prompts the model to regenerate the offending output. - fix: Programmatically corrects the output (e.g., stripping BOM, wrapping unquoted YAML). - filter: Redacts or purges the violating content. - refrain: Suppresses output entirely. - exception: Aborts execution immediately with a defensive error.

---

⚙️ 3. Implementing Custom Validators in DSOM

In DSOM, we enforce validation at three distinct layers: 1. Static / Deterministic Python Validators (Twilight State / pre-commit). 2. FastMCP Request/Response Interceptors (Active State). 3. Pytest Cognitive Test Harness (Deep State / CI/CD).

Architectural Implementation Pattern:

"""
Example: tools/validators/base.py
DSOM Custom Validator Core Schema
"""

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Any, Dict, Optional, Literal

@dataclass
class ValidationResult:
    is_valid: bool
    corrected_value: Optional[Any] = None
    error_message: Optional[str] = None
    action_taken: Literal["pass", "fixed", "blocked", "reask"] = "pass"

class BaseDSOMValidator(ABC):
    """Abstract Base Class for all DSOM Custom Validators."""

    name: str = "base_validator"
    on_fail: Literal["fix", "block", "reask"] = "block"

    @abstractmethod
    def validate(self, value: Any, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        """Evaluate value and return ValidationResult."""
        pass

---

🛠️ 4. Concrete DSOM Custom Validator Examples

Validator 1: OKF Frontmatter & Quoting Validator (tools/validators/okf_validator.py)

Ensures all Markdown outputs strictly conform to OKF v0.1/v0.2 standards with BOM-less UTF-8 and double-quoted strings.

import re
from typing import Any, Dict, Optional
from tools.validators.base import BaseDSOMValidator, ValidationResult

class OKFFrontmatterValidator(BaseDSOMValidator):
    name = "okf_frontmatter_validator"
    on_fail = "fix"

    def validate(self, markdown_text: str, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        # Check 1: Must not start with UTF-8 BOM
        if markdown_text.startswith("\ufeff"):
            fixed = markdown_text.lstrip("\ufeff")
            return ValidationResult(
                is_valid=False,
                corrected_value=fixed,
                error_message="Leading UTF-8 BOM detected and stripped.",
                action_taken="fixed"
            )

        # Check 2: Must begin with YAML fence on line 1, column 1
        if not (markdown_text.startswith("---\n") or markdown_text.startswith("---\r\n")):
            return ValidationResult(
                is_valid=False,
                error_message="Document does not start with OKF frontmatter fence (---).",
                action_taken="blocked"
            )

        return ValidationResult(is_valid=True)

---

📦 4. Implementation Path A: Guardrails AI Framework

When integrating with external LLM pipelines, microservices, or chatbot gateways that use the official guardrails-ai Python package, custom validators inherit from Validator and are decorated with @register_validator.

Installation & Environment Setup

Execute in an isolated uv environment:

uv add guardrails-ai

1. Guardrails AI Custom Validator: OKF & Frontmatter Integrity

"""
tools/validators/guardrails_ai_okf_validator.py
Guardrails AI Custom Validator for OKF Compliance
"""

from typing import Any, Dict, Optional
from guardrails.validators import (
    FailResult,
    PassResult,
    ValidationResult,
    Validator,
    register_validator,
)

@register_validator(name="dsom/okf_frontmatter_validator", data_type="string")
class GuardrailsOKFValidator(Validator):
    """
    Validates that LLM output is formatted with valid OKF frontmatter
    and fixes leading UTF-8 BOM characters.
    """

    def __init__(self, on_fail: str = "fix", **kwargs):
        super().__init__(on_fail=on_fail, **kwargs)

    def validate(self, value: Any, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        text = str(value)

        # Check 1: Strip BOM
        if text.startswith("\ufeff"):
            fixed = text.lstrip("\ufeff")
            return FailResult(
                error_message="Leading UTF-8 BOM detected.",
                fix_value=fixed,
            )

        # Check 2: Verify frontmatter boundary
        if not (text.startswith("---\n") or text.startswith("---\r\n")):
            return FailResult(
                error_message="Document must start with OKF frontmatter fence ('---')."
            )

        return PassResult()

2. Guardrails AI Execution Pipeline:

"""
Example execution using Guardrails AI Guard
"""
from guardrails import Guard
from tools.validators.guardrails_ai_okf_validator import GuardrailsOKFValidator

# Initialize Guard with custom validator
guard = Guard().use(
    GuardrailsOKFValidator(on_fail="fix")
)

raw_llm_output = "\ufeff---\nokf_version: 0.2\ntitle: Sample\n---\n# Content"

# Validate output
validation_outcome = guard.validate(raw_llm_output)
print(f"Validated & Fixed Output:\n{validation_outcome.validated_output}")

---

⚡ 5. Implementation Path B: DSOM Native Lightweight Implementation

For sovereign, zero-external-dependency setups, CLI tools, and FastMCP servers, DSOM provides a pure Python AST and Regex validation harness that executes instantly with zero pip dependencies.

Core Schema (tools/validators/base.py):

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Any, Dict, Optional, Literal

@dataclass
class ValidationResult:
    is_valid: bool
    corrected_value: Optional[Any] = None
    error_message: Optional[str] = None
    action_taken: Literal["pass", "fixed", "blocked", "reask"] = "pass"

class BaseDSOMValidator(ABC):
    """Abstract Base Class for all DSOM Custom Validators."""

    name: str = "base_validator"
    on_fail: Literal["fix", "block", "reask"] = "block"

    @abstractmethod
    def validate(self, value: Any, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        """Evaluate value and return ValidationResult."""
        pass

Native Validator 1: Credential & PII Leak Guardian (tools/validators/credential_guardian.py)

Implements Rule 24 (Defensive Credential Handling) to block API keys, private keys, or passwords from touching Git or responses.

import re
from typing import Any, Dict, Optional
from tools.validators.base import BaseDSOMValidator, ValidationResult

class CredentialGuardianValidator(BaseDSOMValidator):
    name = "credential_guardian"
    on_fail = "block"

    PATTERNS = [
        re.compile(r"ghp_[a-zA-Z0-9]{36}"),                # GitHub Classic Token
        re.compile(r"github_pat_[a-zA-Z0-9_]{82}"),        # GitHub Fine-grained Token
        re.compile(r"glpat-[a-zA-Z0-9\-]{20}"),            # GitLab Personal Access Token
        re.compile(r"-----BEGIN (RSA|OPENSSH) PRIVATE KEY-----"), # Private Keys
    ]

    def validate(self, text: str, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        for pattern in self.PATTERNS:
            if pattern.search(text):
                return ValidationResult(
                    is_valid=False,
                    error_message=f"Credential/Key signature detected matching pattern {pattern.pattern}.",
                    action_taken="blocked"
                )
        return ValidationResult(is_valid=True)

Native Validator 2: Python AST UV-Execution Gatekeeper (tools/validators/ast_uv_gatekeeper.py)

Implements Rule 16 (The uv Mandate) by parsing generated terminal commands or scripts to block raw pip install or python calls.

from typing import Any, Dict, Optional
from tools.validators.base import BaseDSOMValidator, ValidationResult

class PythonExecutionValidator(BaseDSOMValidator):
    name = "python_execution_gatekeeper"
    on_fail = "block"

    PROHIBITED_COMMANDS = ["pip install", "python3 ", "python "]

    def validate(self, terminal_command: str, metadata: Optional[Dict[str, Any]] = None) -> ValidationResult:
        trimmed = terminal_command.strip()

        # Prohibit raw pip
        if trimmed.startswith("pip ") or " pip install " in trimmed:
            return ValidationResult(
                is_valid=False,
                error_message="Violation of Rule 16 (uv Mandate): Raw pip execution detected. Use 'uv add' or 'uv run --with'.",
                action_taken="blocked"
            )

        return ValidationResult(is_valid=True)

🔌 6. Integration into the FastMCP Server (tools/mcp/server.py)

Both Guardrails AI and DSOM native validators can be seamlessly connected to our native FastMCP server, verifying arguments before tool execution and sanitizing results before returning to AI IDEs (Cursor/Claude Desktop):

# tools/mcp/server.py snippet
from fastmcp import FastMCP
from tools.validators.credential_guardian import CredentialGuardianValidator

mcp = FastMCP("DSOM Sovereign MCP")
guardian = CredentialGuardianValidator()

@mcp.tool()
def safe_write_knowledge(path: str, content: str) -> str:
    """Writes knowledge to palace with inline guardrail validation."""

    # 1. Run Input Guardrail
    res = guardian.validate(content)
    if not res.is_valid:
        raise ValueError(f"[GUARDRAIL BLOCKED] {res.error_message}")

    # 2. Proceed with idempotent write
    # ... write logic ...
    return f"Successfully validated and written to {path}"

---

📊 7. Comparative Architectural Matrix

Metric / Dimension	📦 Guardrails AI Framework	⚡ DSOM Native Implementation
Primary Use Case	External LLM App Gateways, Pydantic Structured Data, OpenAI/Anthropic API calls.	Internal GitOps, FastMCP Server, AST Command Interception, Sovereign Offline Tooling.
Dependencies	Requires guardrails-ai, pydantic (v2), and optional hub validators.	Standard Library only (re, ast, dataclasses, typing), executed via uv.
Execution Latency	~5–20ms (wrapper overhead).	<0.5ms (instant in-process evaluation).
On-Fail Mechanics	Supports reask, fix, filter, refrain, exception.	Supports fix, block, reask (via episodic anchor rollbacks).
Cognitive State	Active State (Response generation).	Tri-Phasic (Active MCP, Twilight AST, Deep EOD Pytest).
Memory Footprint	Moderate (~80MB environment size).	Zero additional footprint.

---

🚀 8. Strategic Hybrid Adoption: When to Use Which

1. Use Guardrails AI Framework when:
2. Building customer-facing AI agents or chat interfaces connecting directly to OpenAI/Anthropic APIs.
3. You need off-the-shelf Hub validators (e.g., Toxic Language Detection, PII Masking, Hallucination Checks).

4. Validating complex Pydantic JSON schemas returned by structured LLMs.

5. Use DSOM Native Implementation when:

6. Protecting the local repository codebase, FastMCP server, and Git repository.
7. Enforcing internal project constitutions (OKF frontmatter, uv command mandates, no raw credentials).

8. Running in zero-trust, air-gapped, or offline systems engineering environments.

9. Guardrails AI Official Documentation: Custom Validators - Primary guide for building custom guardrails validators.

10. DSOM Tri-Phasic Cognitive Architecture - DSOM cognitive states and subsystem specifications.
11. The Core AI Rulebook - Sovereign rules 2, 6, 16, 20, 24, and 28 governing safety constraints.

---

Deep State of Mind (DSOM) For My AI Protocol | Harisfazillah Jamel (LinuxMalaysia) | 2026-08-21
Standard: UK English | DBP-standard Bahasa Melayu Malaysia (Piawai) | GNU General Public License v3.0