sorbet-baml 0.2.0 → 0.3.0

data/docs-site/src/getting-started.md

@@ -0,0 +1,170 @@
+---
+layout: doc
+title: "Getting Started"
+description: "Learn how to install and use sorbet-baml to convert your Sorbet types to BAML for efficient LLM prompting."
+---
+
+# Getting Started
+
+## Prerequisites
+
+- Ruby 3.2+
+- Sorbet installed in your project
+- Basic familiarity with T::Struct
+
+## Quick Start
+
+### 1. Define your autonomous workflow types
+
+```ruby
+# Define complex LLM workflow types for research agents
+class TaskType < T::Enum
+  enums do
+    # Literature review and information gathering
+    Research = new('research')
+    # 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
+  # Strategic priority ranking (1-5 scale)
+  const :priority, Integer
+end
+```
+
+### 2. Convert to BAML
+
+```ruby
+require 'sorbet-baml'
+
+# Ruby-idiomatic API (recommended)
+ResearchTask.to_baml
+
+# Legacy API (still supported)  
+baml = SorbetBaml.from_struct(ResearchTask)
+puts baml
+```
+
+**Generated BAML:**
+```baml
+enum TaskType {
+  "research" @description("Literature review and information gathering")
+  "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")
+  priority int @description("Strategic priority ranking (1-5 scale)")
+}
+```
+
+### 3. Field descriptions are included by default
+
+The smart defaults automatically extract field descriptions from your comments:
+
+```ruby
+class ResearchFindings < T::Struct
+  # Detailed analysis results from the research
+  const :findings, String
+  
+  # Key actionable insights extracted from findings
+  const :key_insights, T::Array[String]
+  
+  # Confidence level in the research quality (1-10)
+  const :confidence_score, Integer
+end
+
+# Generate BAML (descriptions included by default!)
+ResearchFindings.to_baml
+```
+
+**Generated BAML with descriptions:**
+```baml
+class ResearchFindings {
+  findings string @description("Detailed analysis results from the research")
+  key_insights string[] @description("Key actionable insights extracted from findings")
+  confidence_score int @description("Confidence level in the research quality (1-10)")
+}
+```
+
+### 4. Use with autonomous research agents
+
+Include the BAML definition in your agent prompts:
+
+```ruby
+baml = ResearchTask.to_baml
+prompt = <<~PROMPT
+  You are an autonomous research agent. Analyze the topic "AI in Healthcare" and break it down into strategic research tasks.
+  
+  Schema for your output:
+  #{baml}
+  
+  Provide a comprehensive task decomposition in JSON format.
+PROMPT
+
+# Use with OpenAI, Anthropic, or any LLM provider
+response = llm_client.chat(prompt)
+result = JSON.parse(response.content)
+```
+
+### 5. Generate Tool Definitions
+
+Create BAML tool specifications for function calling and agentic workflows:
+
+```ruby
+# Define tool parameter structures
+class SearchTool < T::Struct
+  # The search query to execute
+  const :query, String
+  # Maximum number of results to return
+  const :limit, T.nilable(Integer)
+end
+
+class ReplyTool < T::Struct  
+  # The response message to send back to the user
+  const :response, String
+end
+
+# Generate BAML tool definitions
+SearchTool.to_baml_tool
+ReplyTool.to_baml_tool
+
+# Or use module API
+SorbetBaml.from_tool(SearchTool)
+```
+
+**Generated BAML Tool Specifications:**
+```baml
+class SearchTool {
+  query string @description("The search query to execute")
+  limit int? @description("Maximum number of results to return")
+}
+
+class ReplyTool {
+  response string @description("The response message to send back to the user")
+}
+```
+
+**Perfect for LLM function calling schemas:**
+```ruby
+tools = [SearchTool, ReplyTool].map(&:to_baml_tool).join("\n\n")
+
+prompt = <<~PROMPT
+  You have access to these tools:
+  #{tools}
+  
+  Use the appropriate tool to help the user with their request.
+PROMPT
+```
+
+## Next Steps
+
+- [Type Mapping Reference](./type-mapping.md)
+- [Advanced Usage](./advanced-usage.md)
+- [Troubleshooting](./troubleshooting.md)

data/docs-site/src/index.md

@@ -0,0 +1,183 @@
+---
+layout: default
+title: "sorbet-baml"
+description: "Ruby-idiomatic conversion from Sorbet types to BAML for efficient LLM prompting. 60% fewer tokens than JSON Schema while maintaining complete type information."
+---
+
+<div class="text-center mb-12">
+  <h1 class="text-4xl font-bold text-gray-900 mb-4">sorbet-baml</h1>
+  <p class="text-xl text-gray-600 max-w-3xl mx-auto">
+    Ruby-idiomatic conversion from Sorbet types to BAML (Boundary AI Markup Language) for efficient LLM prompting.
+  </p>
+  
+  <div class="flex flex-wrap justify-center gap-4 mt-8">
+    <img src="https://img.shields.io/gem/v/sorbet-baml" alt="Gem Version" />
+    <img src="https://img.shields.io/gem/dt/sorbet-baml" alt="Total Downloads" />
+    <img src="https://img.shields.io/github/license/vicentereig/sorbet-baml" alt="License" />
+    <img src="https://img.shields.io/badge/Sorbet-compatible-blue" alt="Sorbet Compatible" />
+  </div>
+  
+  <div class="flex flex-wrap justify-center gap-4 mt-6">
+    <a href="/sorbet-baml/getting-started/" class="bg-blue-600 text-white px-6 py-3 rounded-lg font-medium hover:bg-blue-700 transition-colors">
+      Get Started
+    </a>
+    <a href="https://github.com/vicentereig/sorbet-baml" class="bg-gray-100 text-gray-700 px-6 py-3 rounded-lg font-medium hover:bg-gray-200 transition-colors">
+      View on GitHub
+    </a>
+  </div>
+</div>
+
+## Why BAML?
+
+BAML uses approximately **60% fewer tokens** than JSON Schema while maintaining complete type information, making your LLM interactions more efficient and cost-effective.
+
+<div class="bg-blue-50 border border-blue-200 rounded-lg p-6 my-8">
+  <h3 class="text-lg font-semibold text-blue-900 mb-3">🚀 Token Efficiency Comparison</h3>
+  <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+    <div>
+      <strong>JSON Schema:</strong> ~680 tokens
+    </div>
+    <div>
+      <strong>BAML:</strong> ~320 tokens <span class="text-blue-600 font-semibold">(53% reduction)</span>
+    </div>
+  </div>
+  <p class="text-blue-800 mt-3">
+    Real-world comparison from production agentic workflows using complex nested types, enums, and arrays.
+  </p>
+</div>
+
+## Quick Example
+
+```ruby
+# Define a Sorbet struct
+class User < T::Struct
+  const :name, String
+  const :age, Integer
+  const :email, T.nilable(String)
+end
+
+# Convert to BAML (Ruby-idiomatic API)
+require 'sorbet-baml'
+User.to_baml
+```
+
+**Generated BAML:**
+```baml
+class User {
+  name string
+  age int
+  email string?
+}
+```
+
+## Key Features
+
+<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 my-8">
+  <div class="bg-white p-6 rounded-lg border border-gray-200">
+    <h3 class="font-semibold text-gray-900 mb-2">🎯 Ruby-Idiomatic API</h3>
+    <p class="text-gray-600">Every T::Struct and T::Enum gets a natural <code>.to_baml</code> method that feels native to Ruby.</p>
+  </div>
+  
+  <div class="bg-white p-6 rounded-lg border border-gray-200">
+    <h3 class="font-semibold text-gray-900 mb-2">🧠 Smart Defaults</h3>
+    <p class="text-gray-600">Field descriptions and dependencies included automatically for better LLM understanding.</p>
+  </div>
+  
+  <div class="bg-white p-6 rounded-lg border border-gray-200">
+    <h3 class="font-semibold text-gray-900 mb-2">📝 Field Descriptions</h3>
+    <p class="text-gray-600">Extracts comments from source code to provide crucial context for autonomous agents.</p>
+  </div>
+  
+  <div class="bg-white p-6 rounded-lg border border-gray-200">
+    <h3 class="font-semibold text-gray-900 mb-2">🔗 Dependency Management</h3>
+    <p class="text-gray-600">Automatically includes all referenced types with proper topological sorting.</p>
+  </div>
+  
+  <div class="bg-white p-6 rounded-lg border border-gray-200">
+    <h3 class="font-semibold text-gray-900 mb-2">✅ Type-Safe</h3>
+    <p class="text-gray-600">Full Sorbet type checking throughout the gem with 100% test coverage.</p>
+  </div>
+  
+  <div class="bg-white p-6 rounded-lg border border-gray-200">
+    <h3 class="font-semibold text-gray-900 mb-2">🛠️ Tool Definitions</h3>
+    <p class="text-gray-600">Generate BAML tool specifications for function calling and agentic workflows.</p>
+  </div>
+  
+  <div class="bg-white p-6 rounded-lg border border-gray-200">
+    <h3 class="font-semibold text-gray-900 mb-2">🏁 Production Ready</h3>
+    <p class="text-gray-600">Complete type support, dependency management, and comprehensive test coverage.</p>
+  </div>
+</div>
+
+## Complete Type Support
+
+### Basic Types
+- `String` → `string`
+- `Integer` → `int` 
+- `Float` → `float`
+- `T::Boolean` → `bool`
+- `Symbol` → `string`
+- `Date/DateTime/Time` → `string`
+
+### Complex Types
+- `T.nilable(T)` → `T?` (optional types)
+- `T::Array[T]` → `T[]` (arrays)
+- `T::Hash[K,V]` → `map<K,V>` (hash maps)
+- `T.any(T1, T2)` → `T1 | T2` (union types)
+
+### Structured Types
+- `T::Struct` → `class Name { ... }` (classes with fields)
+- `T::Enum` → `enum Name { "value1" "value2" }` (enums)
+- Nested structs with proper reference handling
+- **Automatic dependency resolution** with topological sorting
+
+## Perfect for Agentic Workflows
+
+```ruby
+# Define your autonomous research workflow types
+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]
+end
+
+# Generate BAML for LLM agents
+prompt = <<~PROMPT
+  You are an autonomous research agent. Analyze this topic and decompose it.
+  
+  Schema for your output:
+  #{TaskDecomposition.to_baml}
+  
+  Topic: "Impact of AI on healthcare delivery systems"
+PROMPT
+
+# Use with any LLM provider
+response = llm_client.chat(prompt)
+result = TaskDecomposition.from_json(response.content)
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'sorbet-baml'
+```
+
+Or install directly:
+
+```bash
+gem install sorbet-baml
+```
+
+---
+
+<div class="text-center mt-12">
+  <h2 class="text-2xl font-bold text-gray-900 mb-4">Ready to get started?</h2>
+  <a href="/sorbet-baml/getting-started/" class="bg-blue-600 text-white px-8 py-3 rounded-lg font-medium hover:bg-blue-700 transition-colors inline-block">
+    Read the Getting Started Guide →
+  </a>
+</div>

data/docs-site/src/troubleshooting.md

@@ -0,0 +1,317 @@
+---
+layout: doc
+title: "Troubleshooting"
+description: "Common issues and solutions when using sorbet-baml. Find quick fixes for installation, conversion, and usage problems."
+---
+
+# Troubleshooting
+
+## Common Issues
+
+### "undefined method `props' for Class"
+
+**Problem**: The class you're trying to convert is not a T::Struct.
+
+**Solution**: Ensure your class inherits from `T::Struct`:
+
+```ruby
+# ❌ Wrong
+class ResearchAgent
+  attr_reader :domain_expertise
+end
+
+# ✅ Correct
+class ResearchAgent < T::Struct
+  # Agent's specialized domain of expertise
+  const :domain_expertise, String
+end
+
+# Generate BAML (descriptions included by default!)
+ResearchAgent.to_baml
+```
+
+**Generated BAML:**
+```baml
+class ResearchAgent {
+  domain_expertise string @description("Agent's specialized domain of expertise")
+}
+```
+
+### Empty output
+
+**Problem**: The struct has no properties defined.
+
+**Solution**: Define at least one property using `const` or `prop`:
+
+```ruby
+class ResearchAgent < T::Struct
+  # Agent's specialized domain of expertise
+  const :domain_expertise, String
+  # Maximum concurrent research tasks
+  const :task_capacity, Integer
+end
+
+ResearchAgent.to_baml
+```
+
+**Generated BAML:**
+```baml
+class ResearchAgent {
+  domain_expertise string @description("Agent's specialized domain of expertise")
+  task_capacity int @description("Maximum concurrent research tasks")
+}
+```
+
+### Self-referential types work fine
+
+**Problem**: You think self-referential types aren't supported.
+
+**Solution**: They actually work perfectly! Self-referential types are fully supported:
+
+```ruby
+class ResearchHierarchy < T::Struct
+  # Name of the research domain or subdomain
+  const :domain_name, String
+  # Parent research domain for hierarchical organization
+  const :parent_domain, T.nilable(ResearchHierarchy)
+  # Child research subdomains
+  const :subdomains, T::Array[ResearchHierarchy]
+end
+
+ResearchHierarchy.to_baml
+```
+
+**Generated BAML:**
+```baml
+class ResearchHierarchy {
+  domain_name string @description("Name of the research domain or subdomain")
+  parent_domain ResearchHierarchy? @description("Parent research domain for hierarchical organization")
+  subdomains ResearchHierarchy[] @description("Child research subdomains")
+}
+```
+
+## Type-Specific Issues
+
+### Arrays not converting correctly
+
+Ensure you're using the Sorbet array syntax:
+
+```ruby
+# ❌ Wrong
+class ResearchAgent < T::Struct
+  const :research_methods, Array  # Generic Array won't work
+end
+
+# ✅ Correct
+class ResearchAgent < T::Struct
+  # List of research methodologies the agent can employ
+  const :research_methods, T::Array[String]
+end
+
+ResearchAgent.to_baml
+```
+
+**Generated BAML:**
+```baml
+class ResearchAgent {
+  research_methods string[] @description("List of research methodologies the agent can employ")
+}
+```
+
+### Optional fields showing as required
+
+Make sure to use `T.nilable`:
+
+```ruby
+# ❌ Wrong - will be required
+class ResearchAgent < T::Struct
+  # Peer review notes
+  const :peer_review, String
+end
+
+# ✅ Correct - will be optional
+class ResearchAgent < T::Struct
+  # Optional peer review notes
+  const :peer_review, T.nilable(String)
+end
+
+ResearchAgent.to_baml
+```
+
+**Generated BAML:**
+```baml
+class ResearchAgent {
+  peer_review string? @description("Optional peer review notes")
+}
+```
+
+### Union types not working
+
+Ensure you're using `T.any` for union types:
+
+```ruby
+# ❌ Wrong
+class ResearchConfig < T::Struct
+  const :parameter_value, String || Integer  # Ruby OR, not Sorbet union
+end
+
+# ✅ Correct
+class ResearchConfig < T::Struct
+  # Configuration parameter supporting multiple value types
+  const :parameter_value, T.any(String, Integer)
+end
+
+ResearchConfig.to_baml
+```
+
+**Generated BAML:**
+```baml
+class ResearchConfig {
+  parameter_value string | int @description("Configuration parameter supporting multiple value types")
+}
+```
+
+### Hash types not mapping correctly
+
+Use the full `T::Hash[K, V]` syntax:
+
+```ruby
+# ❌ Wrong
+class ResearchAgent < T::Struct
+  const :agent_metadata, Hash  # Generic Hash won't work
+end
+
+# ✅ Correct
+class ResearchAgent < T::Struct
+  # Agent coordination metadata with flexible value types
+  const :agent_metadata, T::Hash[String, T.any(String, Integer)]
+end
+
+ResearchAgent.to_baml
+```
+
+**Generated BAML:**
+```baml
+class ResearchAgent {
+  agent_metadata map<string, string | int> @description("Agent coordination metadata with flexible value types")
+}
+```
+
+## Dependency Issues
+
+### Missing dependencies in output
+
+Dependencies are included by default! Smart defaults make this automatic:
+
+```ruby
+class TaskType < T::Enum
+  enums do
+    # Literature review and information gathering
+    Research = new('research')
+  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
+
+# ✅ Smart defaults: outputs both TaskType and ResearchTask automatically
+ResearchTask.to_baml
+
+# ❌ Only if you explicitly disable dependencies
+ResearchTask.to_baml(include_dependencies: false)
+```
+
+**Generated BAML (with dependencies by default):**
+```baml
+enum TaskType {
+  "research" @description("Literature review and information gathering")
+}
+
+class ResearchTask {
+  objective string @description("Clear description of the research objective")
+  task_type TaskType @description("Type of research task to be performed")
+}
+```
+
+### Wrong dependency order
+
+The gem automatically handles dependency ordering using topological sorting. Dependencies always come before the types that reference them.
+
+## Enum Issues
+
+### Enums not converting
+
+Ensure you're using the correct T::Enum syntax:
+
+```ruby
+# ❌ Wrong
+class ResearchStatus
+  ACTIVE = 'active'
+  COMPLETED = 'completed'
+end
+
+# ✅ Correct
+class ResearchStatus < T::Enum
+  enums do
+    # Research is actively in progress
+    Active = new('active')
+    # Research has been completed successfully
+    Completed = new('completed')
+  end
+end
+
+ResearchStatus.to_baml
+```
+
+**Generated BAML:**
+```baml
+enum ResearchStatus {
+  "active" @description("Research is actively in progress")
+  "completed" @description("Research has been completed successfully")
+}
+```
+
+## Getting Help
+
+1. Check the [Type Mapping Reference](./type-mapping.md) for complete type support
+2. Review examples in [Getting Started](./getting-started.md) and [Advanced Usage](./advanced-usage.md)
+3. File an issue at https://github.com/vicentereig/sorbet-baml/issues
+
+## Advanced Debugging
+
+### Inspect Sorbet type information
+
+```ruby
+# See what Sorbet sees for your struct
+MyStruct.props
+# => {name: String, age: Integer, ...}
+
+# Check if a class is a T::Struct
+MyStruct < T::Struct
+# => true
+
+# See enum values
+MyEnum.values
+# => [#<MyEnum:0x... @serialize="value1">, ...]
+```
+
+### Testing your BAML output
+
+```ruby
+# Verify the output looks correct (dependencies included by default)
+baml = ResearchTask.to_baml
+puts baml
+
+# Check that all expected types are included
+expected_types = ['class ResearchTask', 'enum TaskType']
+expected_types.all? { |type| baml.include?(type) }
+# => true
+
+# Verify descriptions are included
+baml.include?('@description')
+# => true
+```