Serialization

Convert blocks to XML, JSON, and other formats for export, storage, and LLM consumption.

Serialization System

The Serialization system transforms structured block data into various output formats. The primary format is XML for LLM consumption, but the system also supports JSON export, template serialization, and custom formatters.

Key Benefits: Token-efficient XML output, preserves block relationships, supports custom formatting, enables round-trip serialization, and validates output structure.

Output Formats

XML Output

Primary format for LLM consumption - structured and token-efficient

Structure

<prompt version="1.0" id="example-prompt">
  <meta>
    <name>Code Review Assistant</name>
    <description>Expert code analysis and suggestions</description>
    <author>vibecode-team</author>
    <tags>
      <tag>coding</tag>
      <tag>review</tag>
    </tags>
  </meta>

  <system>
    <role>You are a senior software engineer with expertise in code review.</role>
    <capabilities>
      <capability>Identify code issues and bugs</capability>
      <capability>Suggest performance optimizations</capability>
      <capability>Ensure best practices compliance</capability>
    </capabilities>
    <constraints>
      <constraint>Focus on constructive feedback</constraint>
      <constraint>Prioritize security and performance</constraint>
    </constraints>
  </system>

  <instructions>
    <step priority="1">
      <action>Analyze the provided code</action>
      <output>Initial assessment of quality and structure</output>
    </step>
    <step priority="2">
      <action>Identify specific issues</action>
      <output>List of bugs, anti-patterns, and improvements</output>
    </step>
    <step priority="3">
      <action>Provide recommendations</action>
      <output>Actionable suggestions with examples</output>
    </step>
  </instructions>

  <examples>
    <example>
      <input>Review this function for potential issues</input>
      <output>I've identified several areas for improvement...</output>
      <explanation>Example of thorough code review feedback</explanation>
    </example>
  </examples>
</prompt>

JSON Export

Complete block data for backup and transfer

{
  "id": "prompt-export-123",
  "name": "Code Review Assistant",
  "version": "1.0.0",
  "exportedAt": "2024-01-15T10:30:00Z",
  "blocks": [
    {
      "id": "role-1",
      "type": "role",
      "content": "You are a senior software engineer with expertise in code review.",
      "metadata": {
        "createdAt": "2024-01-15T09:00:00Z",
        "category": "core"
      }
    },
    {
      "id": "instructions-1",
      "type": "instructions",
      "content": {
        "steps": [
          "Analyze the provided code",
          "Identify specific issues",
          "Provide recommendations"
        ]
      },
      "metadata": {
        "createdAt": "2024-01-15T09:05:00Z"
      }
    }
  ],
  "metadata": {
    "author": "vibecode-team",
    "tags": ["coding", "review"],
    "description": "Expert code analysis and suggestions"
  }
}

Implementation

XML Generator Implementation

Core XML generation logic for blocks

lib/xml-generator.ts

import type { Block, BlockType } from '@/types/prompt-blocks';

export interface XMLOptions {
  version?: string;
  minify?: boolean;
  validate?: boolean;
  includeMetadata?: boolean;
}

export class XMLGenerator {
  private options: XMLOptions;

  constructor(options: XMLOptions = {}) {
    this.options = {
      version: '1.0',
      minify: false,
      validate: true,
      includeMetadata: true,
      ...options
    };
  }

  generate(blocks: Block[], promptMeta?: any): string {
    const xml: string[] = [];
    
    // XML declaration
    xml.push(`<?xml version="${this.options.version}" encoding="UTF-8"?>`);
    
    // Root element with metadata
    const promptId = promptMeta?.id || `prompt-${Date.now()}`;
    xml.push(`<prompt version="${this.options.version}" id="${promptId}">`);
    
    // Add metadata section
    if (this.options.includeMetadata && promptMeta) {
      xml.push('  <meta>');
      this.addMetadataElements(xml, promptMeta);
      xml.push('  </meta>');
    }
    
    // Process blocks by category
    this.addSystemSection(xml, blocks);
    this.addInstructionsSection(xml, blocks);
    this.addExamplesSection(xml, blocks);
    this.addVariablesSection(xml, blocks);
    
    xml.push('</prompt>');
    
    const result = this.options.minify 
      ? this.minifyXML(xml.join('\n'))
      : xml.join('\n');
    
    if (this.options.validate) {
      this.validateXML(result);
    }
    
    return result;
  }

  // ... rest of implementation
}

Performance Optimization

Token Efficiency

XML output is optimized for minimal token usage while maintaining structure and readability:

Compact structure: No unnecessary whitespace or verbose tags
Semantic grouping: Related blocks are grouped to reduce redundancy
Minification option: Remove all unnecessary whitespace for production
Content deduplication: Avoid repeating similar content across blocks

Streaming & Caching

// Streaming XML generation for large prompts
export class StreamingXMLGenerator extends XMLGenerator {
  async *generateStream(blocks: Block[]): AsyncGenerator<string> {
    yield '<?xml version="1.0" encoding="UTF-8"?>\n';
    yield '<prompt>\n';
    
    for (const block of blocks) {
      yield this.processBlock(block);
      yield '\n';
    }
    
    yield '</prompt>';
  }
}

// Caching system for frequently used blocks
export class SerializationCache {
  private cache = new Map<string, string>();
  
  getCachedXML(blockHash: string): string | undefined {
    return this.cache.get(blockHash);
  }
  
  setCachedXML(blockHash: string, xml: string): void {
    this.cache.set(blockHash, xml);
  }
  
  private getBlockHash(block: Block): string {
    return btoa(JSON.stringify(block)).substring(0, 16);
  }
}

Best Practices

Validate XML output before sending to LLMs
Use minification for production LLM requests
Cache serialization results for frequently used blocks
Properly escape all user-generated content

Don't

Generate XML without validation - it may cause LLM errors
Include sensitive information in exported data
Ignore format-specific limitations (file size, structure)
Serialize without considering the target use case