Type Mapping Reference

Complete mapping between Sorbet types and BAML output for autonomous LLM workflows. All listed types are fully supported with automatic field descriptions.

Basic Types

Optional Types (T.nilable)

Collection Types

Hash/Map Types

Union Types (T.any)

Complex Collection Types

Structured Types

T::Struct to BAML Classes (Research Workflow Example)

class ConfidenceLevel < T::Enum
  enums do
    # Low confidence, requires further verification
    Low = new('low')
    # High confidence, strongly supported by evidence
    High = new('high')
  end
end

class ResearchFindings < T::Struct
  # Detailed research findings and analysis
  const :findings, String
  # Key actionable insights extracted
  const :key_insights, T::Array[String]
  # Assessment of evidence quality
  const :evidence_quality, ConfidenceLevel
  # Confidence score (1-10 scale)
  const :confidence_score, Integer
end

ResearchFindings.to_baml

Generated BAML:

enum ConfidenceLevel {
  "low" @description("Low confidence, requires further verification")
  "high" @description("High confidence, strongly supported by evidence")
}

class ResearchFindings {
  findings string @description("Detailed research findings and analysis")
  key_insights string[] @description("Key actionable insights extracted")
  evidence_quality ConfidenceLevel @description("Assessment of evidence quality")
  confidence_score int @description("Confidence score (1-10 scale)")
}

T::Enum to BAML Enums (Task Classification)

class TaskType < T::Enum
  enums do
    # Literature review and information gathering
    Research = new('research')
    # Data analysis and statistical interpretation
    Analysis = new('analysis')
    # Combining multiple sources into coherent insights
    Synthesis = new('synthesis')
  end
end

class ResearchTask < T::Struct
  # Clear description of the research objective
  const :objective, String
  # Type of research task to be performed
  const :task_type, TaskType
end

[TaskType, ResearchTask].map(&:to_baml).join("\n\n")

Generated BAML:

enum TaskType {
  "research" @description("Literature review and information gathering")
  "analysis" @description("Data analysis and statistical interpretation")
  "synthesis" @description("Combining multiple sources into coherent insights")
}

class ResearchTask {
  objective string @description("Clear description of the research objective")
  task_type TaskType @description("Type of research task to be performed")
}

Complex Real-World Example (Autonomous Research Agent)

class ComplexityLevel < T::Enum
  enums do
    # Basic analysis requiring straightforward research
    Basic = new('basic')
    # Advanced analysis requiring deep domain expertise
    Advanced = new('advanced')
  end
end

class TaskDecomposition < T::Struct
  # The main research topic being investigated
  const :research_topic, String
  # Target complexity level for the decomposition
  const :complexity_level, ComplexityLevel
  # Autonomously generated list of research subtasks
  const :subtasks, T::Array[String]
  # Strategic priority rankings (1-5 scale) for each subtask
  const :priority_order, T::Array[Integer]
  # Task dependency relationships for optimal sequencing
  const :dependencies, T::Array[String]
  # Key-value metadata for agent coordination
  const :agent_metadata, T::Hash[String, T.any(String, Integer)]
end

[ComplexityLevel, TaskDecomposition].map(&:to_baml).join("\n\n")

Generated BAML:

enum ComplexityLevel {
  "basic" @description("Basic analysis requiring straightforward research")
  "advanced" @description("Advanced analysis requiring deep domain expertise")
}

class TaskDecomposition {
  research_topic string @description("The main research topic being investigated")
  complexity_level ComplexityLevel @description("Target complexity level for the decomposition")
  subtasks string[] @description("Autonomously generated list of research subtasks")
  priority_order int[] @description("Strategic priority rankings (1-5 scale) for each subtask")
  dependencies string[] @description("Task dependency relationships for optimal sequencing")
  agent_metadata map<string, string | int> @description("Key-value metadata for agent coordination")
}

Advanced Features

Dependency Management

# Dependencies automatically included with smart defaults
TaskDecomposition.to_baml
# Outputs ComplexityLevel enum, then TaskDecomposition class in correct order

Field Descriptions (Included by Default)

# Smart defaults extract field descriptions from comments
TaskDecomposition.to_baml
# Outputs BAML with @description() annotations for LLM context

Custom Formatting

# Smart defaults include dependencies and descriptions automatically
TaskDecomposition.to_baml(indent_size: 4)
# Disable features if needed:
TaskDecomposition.to_baml(include_descriptions: false)

✅ Completed Features

• ✅ T::Struct → class Name { ... } with field descriptions
• ✅ T::Enum → enum Name { ... } with value descriptions
• ✅ Automatic dependency resolution and ordering
• ✅ Smart defaults (descriptions and dependencies enabled)
• ✅ Full type safety with Sorbet type checking

Future Enhancements (Optional)

• T.type_alias → type Name = ...
• Custom naming strategies (snake_case ↔ camelCase)
• Self-referential type handling