sorbet-baml 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c97a86bec35a852f1d41ff171d595d2f414c999f0421cb19da7d825bc6af5ea6
+  data.tar.gz: bc9c45e02ac421d272572b4383c10d4bdf5d87db445be05998ea67cec97fdadc
+SHA512:
+  metadata.gz: c0ab662803d02f440767ea8385705ba0f00b4f54cd48343cee0ea067db2569d0b7845bce54882ea60d9a5e50ef3d6ef3688ed063e8720bedc0c5229a23901b95
+  data.tar.gz: e36a8d5726d4ef489e21350827b9b0707382fb4fea29714c0583fb8b58ba7806d10dad9e214e326fc023e3750d2711f59bacd79ffd0f0ce54de7368c032a73de

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-08-16
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vicente Reig Rincon de Arellano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,115 @@
+# sorbet-baml
+
+Convert Sorbet type definitions to BAML (Boundary AI Markup Language) for more efficient LLM prompting.
+
+## What is this?
+
+This gem translates Ruby's Sorbet type definitions (T::Struct, T::Enum) into BAML's concise type definition format. BAML uses approximately 60% fewer tokens than JSON Schema while maintaining complete type information.
+
+## Why?
+
+When working with LLMs, token efficiency matters. Traditional JSON Schema definitions are verbose. BAML provides a more compact representation that LLMs can parse effectively.
+
+### Example
+
+```ruby
+# Your Sorbet types
+class Address < T::Struct
+  const :street, String
+  const :city, String
+  const :zip, T.nilable(String)
+end
+
+# Converts to BAML
+class Address {
+  street string
+  city string
+  zip string?
+}
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'sorbet-baml'
+```
+
+Or install directly:
+
+```bash
+gem install sorbet-baml
+```
+
+## Usage
+
+```ruby
+require 'sorbet-baml'
+
+# Convert a single struct
+baml_definition = SorbetBaml.from_struct(MyStruct)
+
+# Convert multiple related structs
+baml_definitions = SorbetBaml.from_structs([User, Address, Order])
+
+# With options
+baml = SorbetBaml.from_struct(User, 
+  include_descriptions: true,
+  indent_size: 2
+)
+```
+
+## Current Capabilities
+
+✅ **Supported**
+- Basic types (String, Integer, Float, Boolean)
+- T.nilable (optional fields)
+- T::Array
+- Nested T::Struct
+- T::Enum (planned)
+
+⚠️ **Limitations**
+- No T::Hash/map support yet
+- No union types (T.any) yet
+- No type aliases yet
+- No runtime validation of generated BAML
+
+## Type Mapping
+
+| Sorbet | BAML | Status |
+|--------|------|--------|
+| String | string | ✅ |
+| Integer | int | ✅ |
+| Float | float | ✅ |
+| T::Boolean | bool | ✅ |
+| T.nilable(T) | T? | ✅ |
+| T::Array[T] | T[] | ✅ |
+| T::Hash[K,V] | map<K,V> | 🚧 |
+| T.any(T1,T2) | T1 \| T2 | 🚧 |
+| T::Enum | enum Name { ... } | 🚧 |
+
+## Development Status
+
+This gem is in early development (v0.0.1). The API may change. Use in production at your own risk.
+
+### Roadmap
+
+- [ ] Complete T::Enum support
+- [ ] Add T::Hash/map conversion
+- [ ] Support union types
+- [ ] Handle circular references
+- [ ] Add type aliases
+- [ ] Preserve field descriptions from comments
+
+## Credits
+
+This project was inspired by [`sorbet-schema`](https://github.com/maxveldink/sorbet-schema) which provides excellent Sorbet type introspection capabilities. While sorbet-schema focuses on serialization/deserialization, sorbet-baml focuses on generating efficient type definitions for LLM consumption.
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/vicentereig/sorbet-baml
+
+## License
+
+MIT License. See LICENSE.txt for details.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/README.md

@@ -0,0 +1,67 @@
+# sorbet-baml Documentation
+
+Developer documentation for the sorbet-baml gem.
+
+## For Users
+
+If you want to use this gem in your project:
+
+1. **[Getting Started](./getting-started.md)** - Installation and basic usage
+2. **[Type Mapping Reference](./type-mapping.md)** - Complete type conversion table
+3. **[Advanced Usage](./advanced-usage.md)** - Complex scenarios and integrations
+4. **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
+
+## For Contributors
+
+If you want to contribute to this gem:
+
+1. **[Architecture](./architecture.md)** - How the gem is structured
+2. **[Adding Type Support](./adding-types.md)** - How to add new type mappings
+3. **[Testing Guide](./testing.md)** - How to write and run tests
+
+## 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
+require 'sorbet-baml'
+puts SorbetBaml.from_struct(User)
+
+# Output:
+# class User {
+#   name string
+#   age int
+#   email string?
+# }
+```
+
+## Design Goals
+
+1. **Simplicity** - Easy to understand and use
+2. **Accuracy** - Correct type mappings
+3. **Efficiency** - Minimal token usage in output
+4. **Compatibility** - Works with existing Sorbet codebases
+
+## What This Is Not
+
+- Not a BAML runtime or executor
+- Not a JSON Schema generator (use sorbet-schema for that)
+- Not a Sorbet type checker
+- Not a serialization library
+
+## Why BAML?
+
+BAML (Boundary AI Markup Language) provides a concise way to define types for LLM consumption. Compared to JSON Schema:
+
+- ~60% fewer tokens
+- More readable
+- Better LLM comprehension
+- Simpler syntax
+
+Perfect for prompt engineering and structured output generation.

data/docs/advanced-usage.md

@@ -0,0 +1,85 @@
+# Advanced Usage
+
+## Converting Multiple Structs
+
+When you have related structs, convert them together to maintain relationships:
+
+```ruby
+class Address < T::Struct
+  const :street, String
+  const :city, String
+end
+
+class Company < T::Struct
+  const :name, String
+  const :address, Address
+end
+
+class User < T::Struct
+  const :name, String
+  const :company, Company
+end
+
+# Convert all at once
+baml = SorbetBaml.from_structs([Address, Company, User])
+```
+
+## Options
+
+### Include Descriptions
+
+```ruby
+# Future feature - not yet implemented
+baml = SorbetBaml.from_struct(User,
+  include_descriptions: true  # Will add @description annotations
+)
+```
+
+### Custom Indentation
+
+```ruby
+# Future feature - not yet implemented
+baml = SorbetBaml.from_struct(User,
+  indent_size: 4  # Use 4 spaces instead of 2
+)
+```
+
+## Working with Existing BAML Projects
+
+If you're already using BAML, you can generate type definitions to include in your `.baml` files:
+
+```ruby
+# Generate just the class definition
+definition = SorbetBaml.from_struct(MyStruct)
+
+# Write to a BAML file
+File.write("types/my_struct.baml", definition)
+```
+
+## Integration with LLM Libraries
+
+### With OpenAI
+
+```ruby
+require 'openai'
+require 'sorbet-baml'
+
+schema = SorbetBaml.from_struct(ResponseFormat)
+
+response = client.chat(
+  model: "gpt-4",
+  messages: [{
+    role: "system",
+    content: "You must respond with data matching this BAML schema:\n\n#{schema}"
+  }, {
+    role: "user", 
+    content: "Generate a sample user"
+  }]
+)
+```
+
+### With DSPy.rb
+
+```ruby
+# Coming soon - integration with DSPy.rb for automatic schema generation
+```

data/docs/getting-started.md

@@ -0,0 +1,54 @@
+# Getting Started
+
+## Prerequisites
+
+- Ruby 3.2+
+- Sorbet installed in your project
+- Basic familiarity with T::Struct
+
+## Quick Start
+
+### 1. Define your Sorbet types
+
+```ruby
+class User < T::Struct
+  const :id, Integer
+  const :name, String
+  const :email, T.nilable(String)
+end
+```
+
+### 2. Convert to BAML
+
+```ruby
+require 'sorbet-baml'
+
+baml = SorbetBaml.from_struct(User)
+puts baml
+# Output:
+# class User {
+#   id int
+#   name string
+#   email string?
+# }
+```
+
+### 3. Use with your LLM
+
+Include the BAML definition in your prompt:
+
+```ruby
+prompt = <<~PROMPT
+  Generate sample data matching this schema:
+  
+  #{baml}
+  
+  Return 3 examples.
+PROMPT
+```
+
+## Next Steps
+
+- [Type Mapping Reference](./type-mapping.md)
+- [Advanced Usage](./advanced-usage.md)
+- [Troubleshooting](./troubleshooting.md)

data/docs/troubleshooting.md

@@ -0,0 +1,81 @@
+# 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 User
+  attr_reader :name
+end
+
+# ✅ Correct
+class User < T::Struct
+  const :name, String
+end
+```
+
+### Empty output
+
+**Problem**: The struct has no properties defined.
+
+**Solution**: Define at least one property using `const` or `prop`:
+
+```ruby
+class User < T::Struct
+  const :name, String  # Add properties
+end
+```
+
+### Circular dependency detected
+
+**Problem**: Two structs reference each other creating an infinite loop.
+
+**Solution**: This is not yet supported. Consider flattening the structure or using a different approach.
+
+## Type-Specific Issues
+
+### Arrays not converting correctly
+
+Ensure you're using the Sorbet array syntax:
+
+```ruby
+# ❌ Wrong
+const :items, Array
+
+# ✅ Correct
+const :items, T::Array[String]
+```
+
+### Optional fields showing as required
+
+Make sure to use `T.nilable`:
+
+```ruby
+# ❌ Wrong - will be required
+const :email, String
+
+# ✅ Correct - will be optional
+const :email, T.nilable(String)
+```
+
+## Getting Help
+
+1. Check the [Type Mapping Reference](./type-mapping.md)
+2. Review the examples in [Getting Started](./getting-started.md)
+3. File an issue at https://github.com/vicentereig/sorbet-baml/issues
+
+## Debug Mode
+
+To see detailed conversion information:
+
+```ruby
+# Future feature - not yet implemented
+SorbetBaml.debug = true
+baml = SorbetBaml.from_struct(MyStruct)
+```

data/docs/type-mapping.md

@@ -0,0 +1,65 @@
+# Type Mapping Reference
+
+Complete mapping between Sorbet types and BAML output.
+
+## Basic Types
+
+| Sorbet Type | BAML Output | Example |
+|-------------|-------------|---------|
+| `String` | `string` | `name string` |
+| `Integer` | `int` | `age int` |
+| `Float` | `float` | `price float` |
+| `T::Boolean` | `bool` | `active bool` |
+| `NilClass` | `null` | `null` |
+| `Symbol` | `string` | `status string` |
+
+## Optional Types
+
+| Sorbet Type | BAML Output | Example |
+|-------------|-------------|---------|
+| `T.nilable(String)` | `string?` | `email string?` |
+| `T.nilable(Integer)` | `int?` | `age int?` |
+
+## Collection Types
+
+| Sorbet Type | BAML Output | Example |
+|-------------|-------------|---------|
+| `T::Array[String]` | `string[]` | `tags string[]` |
+| `T::Array[T::Struct]` | `StructName[]` | `addresses Address[]` |
+
+## Nested Structures
+
+```ruby
+# Input
+class Address < T::Struct
+  const :street, String
+  const :city, String
+end
+
+class User < T::Struct
+  const :name, String
+  const :address, Address
+end
+
+# Output
+class Address {
+  street string
+  city string
+}
+
+class User {
+  name string
+  address Address
+}
+```
+
+## Not Yet Supported
+
+These types will be added in future versions:
+
+- `T::Hash[K, V]` → `map<K, V>`
+- `T.any(Type1, Type2)` → `Type1 | Type2`
+- `T::Enum` subclasses → `enum Name { ... }`
+- `T.type_alias` → `type Name = ...`
+- `T::Set[T]` → `T[]` (with uniqueness note)
+- `T::Range[T]` → Will need special handling

data/lib/sorbet_baml/converter.rb

@@ -0,0 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetBaml
+  # Main converter class for transforming Sorbet types to BAML
+  class Converter
+    extend T::Sig
+
+    sig { params(klass: T.class_of(T::Struct), options: T::Hash[Symbol, T.untyped]).returns(String) }
+    def self.from_struct(klass, options = {})
+      new(options).convert_struct(klass)
+    end
+
+    sig { params(klasses: T::Array[T.class_of(T::Struct)], options: T::Hash[Symbol, T.untyped]).returns(String) }
+    def self.from_structs(klasses, options = {})
+      converter = new(options)
+      klasses.map { |klass| converter.convert_struct(klass) }.join("\n\n")
+    end
+
+    sig { params(options: T::Hash[Symbol, T.untyped]).void }
+    def initialize(options = {})
+      @options = options
+      @indent_size = T.let(options.fetch(:indent_size, 2), Integer)
+      @include_descriptions = T.let(options.fetch(:include_descriptions, false), T::Boolean)
+    end
+
+    sig { params(klass: T.class_of(T::Struct)).returns(String) }
+    def convert_struct(klass)
+      props = klass.props
+      
+      class_name = klass.name || klass.to_s
+      simple_name = class_name.split('::').last
+      lines = ["class #{simple_name} {"]
+      
+      props.each do |name, prop_info|
+        baml_type = TypeMapper.map_type(prop_info[:type_object])
+        lines << "#{' ' * @indent_size}#{name} #{baml_type}"
+      end
+      
+      lines << "}"
+      lines.join("\n")
+    end
+  end
+end

data/lib/sorbet_baml/type_mapper.rb

@@ -0,0 +1,79 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module SorbetBaml
+  # Maps Sorbet type objects to BAML type strings
+  class TypeMapper
+    extend T::Sig
+
+    sig { params(type_object: T.untyped).returns(String) }
+    def self.map_type(type_object)
+      return "string" if type_object.nil?
+      
+      case type_object
+      when T::Types::Simple
+        map_simple_type(type_object.raw_type)
+      when T::Types::TypedArray
+        map_array_type(type_object)
+      else
+        # Check if it's a union type (T.nilable)
+        if type_object.respond_to?(:types)
+          map_nilable_type(type_object)
+        else
+          # Fallback for unknown types
+          "unknown"
+        end
+      end
+    end
+
+    sig { params(raw_type: T.untyped).returns(String) }
+    def self.map_simple_type(raw_type)
+      case raw_type.name
+      when "String"
+        "string"
+      when "Integer"
+        "int"
+      when "Float"
+        "float"
+      when "TrueClass", "FalseClass"
+        "bool"
+      when "NilClass"
+        "null"
+      when "Symbol"
+        "string"
+      when "Date", "DateTime", "Time"
+        "string"
+      else
+        # Check if it's a T::Struct
+        if raw_type < T::Struct
+          type_name = raw_type.name || raw_type.to_s
+          type_name.split('::').last || "unknown"
+        else
+          "unknown"
+        end
+      end
+    end
+
+    sig { params(type_object: T.untyped).returns(String) }
+    def self.map_nilable_type(type_object)
+      # Extract the non-nil type from the union
+      types = type_object.types
+      non_nil_type = types.find { |t| t.raw_type != NilClass }
+      
+      if non_nil_type
+        base_type = map_type(non_nil_type)
+        "#{base_type}?"
+      else
+        "null"
+      end
+    end
+
+    sig { params(type_object: T.untyped).returns(String) }
+    def self.map_array_type(type_object)
+      element_type = map_type(type_object.type)
+      "#{element_type}[]"
+    end
+  end
+end

data/lib/sorbet_baml/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SorbetBaml
+  VERSION = "0.0.1"
+end

data/lib/sorbet_baml.rb

@@ -0,0 +1,25 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require_relative "sorbet_baml/version"
+require_relative "sorbet_baml/converter"
+require_relative "sorbet_baml/type_mapper"
+
+module SorbetBaml
+  class Error < StandardError; end
+  
+  extend T::Sig
+  
+  # Convert a single T::Struct to BAML definition
+  sig { params(klass: T.class_of(T::Struct), options: T::Hash[Symbol, T.untyped]).returns(String) }
+  def self.from_struct(klass, options = {})
+    Converter.from_struct(klass, options)
+  end
+  
+  # Convert multiple T::Structs to BAML definitions
+  sig { params(klasses: T::Array[T.class_of(T::Struct)], options: T::Hash[Symbol, T.untyped]).returns(String) }
+  def self.from_structs(klasses, options = {})
+    Converter.from_structs(klasses, options)
+  end
+end

data/sig/sorbet/baml.rbs

@@ -0,0 +1,6 @@
+module Sorbet
+  module Baml
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/sorbet/config

@@ -0,0 +1,4 @@
+--dir
+.
+--ignore=tmp/
+--ignore=vendor/

data/sorbet/rbi/annotations/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-vendored=true