Blueprint Validation Service

[mathaix]

User Story

As a developer
I want a validation service that checks blueprint integrity
So that invalid blueprints never reach production agents

Acceptance Criteria

Validation Layers

Layer 1: Schema Validation

• All required fields present
• Field types correct
• Enum values valid
• Nested objects validate recursively

Layer 2: Referential Integrity

• Question IDs in flows exist in question list
• Entity types in relationships exist in entities
• Goal IDs referenced exist
• Agent IDs are unique within blueprint

Layer 3: Semantic Validation

• At least one agent defined
• Each agent has at least 3 questions
• System prompt length ≥ 500 characters
• Extraction schema has examples for each entity
• No circular references in question flow

Layer 4: Quality Validation

• Persona has warmth in tone
• Goals have success criteria
• Questions have purposes
• Max 15 required fields per entity

Validation Response

class ValidationResult(BaseModel):
    valid: bool
    score: int  # 0-100
    errors: list[ValidationError]  # Block deployment
    warnings: list[ValidationWarning]  # Allow with acknowledgment
    info: list[ValidationInfo]  # Suggestions

class ValidationError(BaseModel):
    code: str
    path: str  # JSON path to error
    message: str
    suggestion: str | None

API Requirements

• POST /api/v1/blueprints/validate - Validate blueprint JSON
• Validation runs automatically on save
• Validation runs before activation
• Activation blocked if errors present

Error Codes

Define standardized error codes:

• BP001: Missing required field
• BP002: Invalid field type
• BP003: Invalid enum value
• BP004: Reference not found
• BP005: Circular reference
• BP006: Insufficient questions
• BP007: System prompt too short
• BP008: Missing entity examples
• etc.

Technical Notes

• Use Pydantic validators for schema layer
• Custom validators for semantic layer
• Validation should be fast (< 500ms)
• Cache validation results with blueprint hash

Definition of Done

• All validation layers implemented
• Comprehensive error codes defined
• API endpoint working
• Auto-validation on save
• Code reviewed and merged

---

🤖 Generated with Claude Code