chore: generate span annotations via plpgsql

[RogerHYang]

Add PL/pgSQL-based Span Annotations Generation

Overview

This PR introduces a PL/pgSQL-based solution for generating random span annotations, leveraging PostgreSQL's native capabilities for efficient data generation. The implementation consists of:

• A PL/pgSQL script (generate_span_annotations.sql) that handles the core data generation logic
• A Python wrapper (generate_span_annotations.py) that provides a CLI interface

PL/pgSQL Implementation Highlights

• Uses TABLESAMPLE SYSTEM (1) for efficient random sampling of approximately 1% of spans
• Implements a single bulk INSERT operation using CTEs (Common Table Expressions) for optimal performance:
  • annotation_names: Converts input string to array for random selection
  • sampled_spans: Efficiently samples spans with random annotation counts
  • span_repeats: Generates multiple annotations per span with missing value probabilities
• Leverages PostgreSQL's native functions:
  • random() for generating random values
  • jsonb_build_object() for structured metadata
  • generate_series() for creating multiple annotations per span
  • array_length() and array indexing for random name selection
• Implements ON CONFLICT DO NOTHING for handling duplicate annotations
• Uses parameterized queries with :variable syntax for dynamic configuration

Features

• Generates random annotations with configurable parameters:
  • Number of spans to sample (default: 10,000)
  • Maximum annotations per span (default: 10)
  • Configurable probabilities for missing fields (labels, scores, explanations, metadata)
  • Customizable annotation names
• Supports both human and LLM annotators
• Generates realistic metadata including model parameters and context
• Maintains referential integrity with spans

Technical Details

• Efficient bulk insertion using PostgreSQL's native capabilities
• Handles duplicate annotations gracefully with ON CONFLICT DO NOTHING
• Provides comprehensive command-line interface with sensible defaults
• Includes detailed documentation and usage examples

Usage

# Use default parameters
python generate_span_annotations.py