sorbet-baml 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6ebc9d978b525e29a1a19ef184f073393d6a588e54d84dc2b9fd7034d1fa40c
-  data.tar.gz: f7d5e028fe65a4a4cc9b19c60dc17dd65fd13353634e55201db5189bb457447a
+  metadata.gz: 4de7b80da4ee748d5c22196c22f78ca92e855f9b4983437d4ea6ad02a5201fba
+  data.tar.gz: 22a81719e5d2021b52945d913e3134482ff999e917d655f67ec894a35fa2a40b
 SHA512:
-  metadata.gz: 40b4736cc561b5135ee32e08543148c018ea9963e016c6cbb66697cd346ff7cf30f7438d370853c045b40d062a47f38d7aaa1a9c6c8e92f8e7f6721b495966e0
-  data.tar.gz: 0caf0a19906655bbfae88723bbe5b38301601c1523c3cc3b8dc31a15bf6bdd02ceacb790cf0d4bddf718c1162ba51d7b0fcd08110578616cd7c7ac27272bcd42
+  metadata.gz: d64e1cef217666030c2f34cacd48333d6ce46d5fac40e2a2855c0f73fe43dadf39a620ad01b37df904ca5aa792a7d46cd3a1bdaf45ce797b34f3010ce4a2be12
+  data.tar.gz: 6131b255163a544f2ef7591f58e173ab0436c44426003513888b51ea4d3a35a5ff90d186b491d867035b9d0c86929b176c6ff8bfeb6de7106b87662546ea0c3e

data/CHANGELOG.md

@@ -1,5 +1,64 @@
 ## [Unreleased]
 
+## [0.4.0] - 2025-10-14
+
+### Changed
+
+- **Dramatically reduced gem size from 1.46MB to 20KB (98.6% reduction)**
+  - Excluded development-only Sorbet RBI files (`sorbet/` directory - 11MB)
+  - Excluded documentation site source (`docs-site/` directory - 43MB)
+  - Excluded IDE configuration files (`.idea/` directory)
+  - Excluded documentation output (`docs-output/` directory)
+  - Excluded RSpec configuration files (`.rspec`)
+  - **File count reduced from 134 to 22 essential files**
+
+### Technical Details
+
+The gem now only includes runtime-required files:
+- Core library code (`lib/` directory)
+- Documentation (README.md, LICENSE.txt, CHANGELOG.md)
+- Examples (`examples/` directory)
+
+All Sorbet type checking infrastructure and development tooling remains available in the repository for contributors but is no longer shipped to end users.
+
+### Impact
+
+- **Faster gem installation** - 92% less data to download
+- **Smaller disk footprint** - More efficient for deployed applications
+- **No functionality changes** - All features work exactly as before
+- **Zero breaking changes** - Full backward compatibility maintained
+
+## [0.3.0] - 2025-08-17
+
+### Added
+
+- Comprehensive BAML tool type definitions for agentic workflows
+- `.to_baml_tool()` method for T::Struct classes
+- Automatic DSPy tool conversion when `dspy.rb` is available
+- Tool metadata extraction (`tool_name`, `tool_description`)
+- Support for function calling APIs (OpenAI, Anthropic, etc.)
+
+### Improved
+
+- 80+ test cases with comprehensive coverage
+- Full Sorbet type safety throughout
+- Enhanced documentation with tool examples
+
+## [0.2.0] - 2025-08-16
+
+### Added
+
+- Clean `description:` parameter for `const` and `prop` declarations
+- Smart fallback chain: description parameter → Ruby comments → nil
+- `DescriptionExtension` for T::Struct
+- `DescriptionExtractor` for programmatic access
+
+### Improved
+
+- Better LLM context with rich field descriptions
+- Zero breaking changes to existing APIs
+- Full backward compatibility
+
 ## [0.1.0] - 2025-08-16
 
 - Initial release

data/README.md

@@ -1,5 +1,10 @@
 # sorbet-baml
 
+[![Gem Version](https://img.shields.io/gem/v/sorbet-baml)](https://rubygems.org/gems/sorbet-baml)
+[![Total Downloads](https://img.shields.io/gem/dt/sorbet-baml)](https://rubygems.org/gems/sorbet-baml)
+[![License](https://img.shields.io/github/license/vicentereig/sorbet-baml)](https://github.com/vicentereig/sorbet-baml/blob/main/LICENSE.txt)
+[![Sorbet Compatible](https://img.shields.io/badge/Sorbet-compatible-blue)](https://sorbet.org)
+
 Ruby-idiomatic conversion from Sorbet types to BAML (Boundary AI Markup Language) for efficient LLM prompting.
 
 ## What is this?
@@ -142,7 +147,29 @@ SorbetBaml.from_structs([ResearchSynthesis, ResearchFindings])
 
 ## 🎯 Field Descriptions for LLM Context
 
-Add crucial context to your BAML types by documenting fields with comments - essential for autonomous agents and complex workflows:
+Add crucial context to your BAML types by documenting fields - essential for autonomous agents and complex workflows. The gem supports **two ways** to provide field descriptions:
+
+### Method 1: Comments (Traditional)
+```ruby
+class ResearchTask < T::Struct
+  # Clear description of the research objective
+  const :objective, String
+  # Strategic priority ranking (1-5 scale)
+  const :priority, Integer
+end
+```
+
+### Method 2: Description Parameter (New in v0.2.0+)
+```ruby
+class ResearchTask < T::Struct
+  const :objective, String, description: "Clear description of the research objective"
+  const :priority, Integer, description: "Strategic priority ranking (1-5 scale)"
+end
+```
+
+Both methods produce identical BAML output with `@description` annotations. The `description:` parameter provides a more explicit, Sorbet-native way to document fields.
+
+### Complete Example
 
 ```ruby
 class TaskType < T::Enum
@@ -193,6 +220,112 @@ ResearchSubtask.to_baml
 
 **Why descriptions matter**: LLMs use field descriptions to understand context and generate more accurate, meaningful data. This is crucial for complex domains where field names alone aren't sufficient.
 
+## 🛠️ Tool Type Definitions
+
+Generate BAML tool specifications for agentic workflows, function calling, and structured LLM interactions:
+
+### T::Struct-based Tools
+
+```ruby
+class ReplyTool < T::Struct
+  # The response message to send back to the user
+  const :response, String
+end
+
+class SearchTool < T::Struct
+  # Using description: parameter (both methods work)
+  const :query, String, description: "The search query to execute"
+  const :limit, T.nilable(Integer), description: "Maximum number of results to return"
+end
+
+# Generate BAML tool definitions
+ReplyTool.to_baml_tool
+# =>
+# class ReplyTool {
+#   response string @description("The response message to send back to the user")
+# }
+
+SearchTool.to_baml_tool
+# =>
+# class SearchTool {
+#   query string @description("The search query to execute")
+#   limit int? @description("Maximum number of results to return")
+# }
+
+# Module API also available
+SorbetBaml.from_tool(ReplyTool)
+```
+
+### DSPy-style Tools (Optional)
+
+When `dspy.rb` is available, automatically convert DSPy tools with rich metadata:
+
+```ruby
+class CalculatorTool < DSPy::Tools::Base
+  extend T::Sig
+  
+  tool_name 'calculator'
+  tool_description 'Performs basic arithmetic operations'
+
+  sig { params(operation: String, num1: Float, num2: Float).returns(T.any(Float, String)) }
+  def call(operation:, num1:, num2:)
+    case operation.downcase
+    when 'add' then num1 + num2
+    when 'subtract' then num1 - num2
+    when 'multiply' then num1 * num2
+    when 'divide'
+      return "Error: Cannot divide by zero" if num2 == 0
+      num1 / num2
+    else
+      "Error: Unknown operation '#{operation}'. Use add, subtract, multiply, or divide"
+    end
+  end
+end
+
+# Automatic extraction of tool metadata and parameter types
+CalculatorTool.to_baml
+# =>
+# // Performs basic arithmetic operations
+# class calculator {
+#   operation string @description("Parameter operation")
+#   num1 float @description("Parameter num1")
+#   num2 float @description("Parameter num2")
+# }
+
+# Optional parameters handled correctly
+class SearchTool < DSPy::Tools::Base
+  extend T::Sig
+  
+  tool_name 'search'
+  tool_description 'Search for information'
+
+  sig { params(query: String, limit: T.nilable(Integer)).returns(T::Array[String]) }
+  def call(query:, limit: nil)
+    # Implementation...
+  end
+end
+
+SearchTool.to_baml
+# =>
+# // Search for information
+# class search {
+#   query string @description("Parameter query")
+#   limit int? @description("Parameter limit (optional)")
+# }
+
+# Module API also available
+SorbetBaml.from_dspy_tool(CalculatorTool)
+```
+
+**Tool Features:**
+- ✅ **T::Struct tools**: Convert any struct to BAML tool definition
+- ✅ **DSPy integration**: Automatic extraction from DSPy::Tools::Base classes
+- ✅ **Parameter types**: Full Sorbet type support (string, int, float, arrays, maps, etc.)
+- ✅ **Optional parameters**: Automatically detect and mark with `?`
+- ✅ **Descriptions**: Extract from comments or `description:` parameter (T::Struct) or automatic generation (DSPy)
+- ✅ **Tool metadata**: Names, descriptions, and parameter documentation
+- ✅ **Ruby-idiomatic**: `.to_baml_tool()` and `.to_baml()` methods
+
 ## 🎯 Complete Type Support
 
 ### ✅ Fully Supported
@@ -222,8 +355,10 @@ ResearchSubtask.to_baml
 ### 🚀 Advanced Features
 
 - **Ruby-idiomatic API**: Every T::Struct and T::Enum gets `.to_baml` method
+- **Tool definitions**: Generate BAML tool specs for function calling and agentic workflows
+- **DSPy integration**: Automatic tool conversion from DSPy::Tools::Base classes
 - **Smart defaults**: Field descriptions and dependencies included automatically
-- **Field descriptions**: Extracts comments from source code for LLM context
+- **Field descriptions**: Extracts from comments or `description:` parameter for LLM context
 - **Dependency management**: Automatically includes all referenced types
 - **Proper ordering**: Dependencies are sorted topologically (no forward references needed)
 - **Circular reference handling**: Won't get stuck in infinite loops
@@ -249,29 +384,34 @@ ResearchSubtask.to_baml
 
 ## 🏁 Production Ready
 
-This gem has reached **feature completeness** for core BAML conversion needs. The Ruby-idiomatic API is stable and thoroughly tested with **50+ test cases** covering all type combinations and edge cases.
+This gem has reached **feature completeness** for core BAML conversion needs. The Ruby-idiomatic API is stable and thoroughly tested with **80 test cases** covering all type combinations, tool definitions, and edge cases.
 
 ### 📊 Quality Metrics
 
-- ✅ **100% Test Coverage** - All features comprehensively tested
+- ✅ **Comprehensive Test Coverage** - All features thoroughly tested
 - ✅ **Full Sorbet Type Safety** - Zero type errors throughout codebase  
-- ✅ **50+ Test Cases** - Covering basic types, complex combinations, and edge cases
+- ✅ **80 Test Cases** - Covering basic types, complex combinations, tool definitions, and edge cases
 - ✅ **TDD Development** - All features built test-first
 - ✅ **Field Descriptions** - Automatic comment extraction for LLM context
+- ✅ **Tool Definitions** - BAML tool specifications for function calling and agentic workflows
+- ✅ **DSPy Integration** - Automatic tool conversion from DSPy::Tools::Base classes
 - ✅ **Smart Defaults** - Dependencies and descriptions included by default
 - ✅ **Zero Breaking Changes** - Maintains backward compatibility
 
 ### ✅ Complete Feature Set
 
 - ✅ **Ruby-idiomatic API**: Every T::Struct and T::Enum gets `.to_baml` method
+- ✅ **Tool definitions**: Generate BAML tool specifications from T::Struct classes
+- ✅ **DSPy integration**: Automatic tool conversion from DSPy::Tools::Base classes
 - ✅ **Smart defaults**: Field descriptions and dependencies included automatically
-- ✅ **Field descriptions**: Extract documentation from comments for LLM context
+- ✅ **Field descriptions**: Extract documentation from comments or `description:` parameter for LLM context
 - ✅ **Dependency management**: Automatically includes all referenced types
 - ✅ **Proper ordering**: Dependencies are sorted topologically
 - ✅ **Type safety**: Full Sorbet type checking throughout
 
 ### 🗺️ Future Enhancements (Optional)
 
+- [ ] **DSPy-independent tool API**: Tools shouldn't require DSPy, just follow the same API pattern
 - [ ] **Type aliases**: `T.type_alias { String }` → `type Alias = string`
 - [ ] **Custom naming**: Convert between snake_case ↔ camelCase
 - [ ] **CLI tool**: `sorbet-baml convert MyStruct` command
@@ -282,6 +422,8 @@ This gem has reached **feature completeness** for core BAML conversion needs. Th
 
 - **v0.0.1** - Initial implementation with basic type support
 - **v0.1.0** - Complete type system + Ruby-idiomatic API + field descriptions + smart defaults
+- **v0.2.0** - Description parameter support and enhanced field extraction
+- **v0.3.0** - Tool type definitions + DSPy integration + 80+ test cases + comprehensive documentation
 
 ## 🌟 Real-World Usage: Autonomous Research Agents
 

data/Rakefile

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

data/examples/description_parameters.rb

@@ -3,15 +3,15 @@
 
 require_relative '../lib/sorbet_baml'
 
-puts "🎯 Description Parameter Support Demo"
-puts "=" * 50
+puts '🎯 Description Parameter Support Demo'
+puts '=' * 50
 
 # Example 1: Basic description parameters
 class User < T::Struct
   const :name, String, description: "User's full legal name"
-  prop :age, Integer, description: "Age in years"
-  const :email, T.nilable(String), description: "Optional email address for notifications"
-  const :interests, T::Array[String], description: "List of user hobbies and interests"
+  prop :age, Integer, description: 'Age in years'
+  const :email, T.nilable(String), description: 'Optional email address for notifications'
+  const :interests, T::Array[String], description: 'List of user hobbies and interests'
 end
 
 puts "\n1. Basic T::Struct with description parameters:"
@@ -21,13 +21,13 @@ puts User.to_baml
 class Product < T::Struct
   # This comment will be used as fallback
   const :id, String
-  
-  const :name, String, description: "Product name for display"
-  
+
+  const :name, String, description: 'Product name for display'
+
   # Price in USD cents
   prop :price_cents, Integer
-  
-  const :category, String, description: "Product category classification"
+
+  const :category, String, description: 'Product category classification'
 end
 
 puts "\n2. Mixed description sources (parameters take priority):"
@@ -35,15 +35,15 @@ puts Product.to_baml
 
 # Example 3: Complex nested types with descriptions
 class Order < T::Struct
-  const :id, String, description: "Unique order identifier"
-  const :customer, User, description: "Customer who placed the order"
-  const :items, T::Array[Product], description: "List of ordered products"
-  const :total_cents, Integer, description: "Total order value in USD cents"
-  const :status, String, description: "Current order processing status"
+  const :id, String, description: 'Unique order identifier'
+  const :customer, User, description: 'Customer who placed the order'
+  const :items, T::Array[Product], description: 'List of ordered products'
+  const :total_cents, Integer, description: 'Total order value in USD cents'
+  const :status, String, description: 'Current order processing status'
 end
 
 puts "\n3. Complex nested types with dependencies:"
 puts Order.to_baml
 
 puts "\n✨ Beautiful, readable, and LLM-friendly!"
-puts "🚀 Perfect for DSPy.rb, autonomous agents, and structured LLM outputs"
+puts '🚀 Perfect for DSPy.rb, autonomous agents, and structured LLM outputs'

data/lib/sorbet_baml/comment_extractor.rb

@@ -10,67 +10,63 @@ module SorbetBaml
     def self.extract_field_comments(klass)
       # First try to get descriptions from the description extractor (extra field)
       descriptions = DescriptionExtractor.extract_prop_descriptions(klass)
-      
+
       # Then fall back to comment-based extraction for any missing descriptions
       comments = {}
       source_file = find_source_file(klass)
-      
+
       if source_file && File.exist?(source_file)
         lines = File.readlines(source_file)
         extract_comments_from_lines(lines, T.must(T.must(klass.name).split('::').last), comments)
       end
-      
+
       # Merge with priority: description parameters > comments
-      descriptions.merge(comments) { |key, desc_param, comment| desc_param }
+      descriptions.merge(comments) { |_key, desc_param, _comment| desc_param }
     end
 
     sig { params(klass: T.class_of(T::Enum)).returns(T::Hash[String, T.nilable(String)]) }
     def self.extract_enum_comments(klass)
       comments = {}
       source_file = find_source_file(klass)
-      
+
       return comments unless source_file && File.exist?(source_file)
-      
+
       lines = File.readlines(source_file)
       extract_enum_comments_from_lines(lines, T.must(T.must(klass.name).split('::').last), comments)
-      
+
       comments
     end
 
-    private
-
     sig { params(klass: T::Class[T.anything]).returns(T.nilable(String)) }
     def self.find_source_file(klass)
       # Try to find where the class was defined
       # This is a heuristic approach since Ruby doesn't provide reliable source location for classes
-      
+
       # Method 1: Check if any methods have source location
       begin
         if klass.respond_to?(:new) && klass.method(:new).respond_to?(:source_location)
           location = klass.method(:new).source_location
           return location[0] if location
         end
-      rescue
+      rescue StandardError
         # Ignore errors
       end
-      
+
       # Method 2: Look at the current call stack for files that might contain the class
       caller_locations.each do |location|
         file_path = location.absolute_path || location.path
         next unless file_path && File.exist?(file_path)
-        
+
         # Read the file and check if it contains the class definition
         begin
           content = File.read(file_path)
           class_name = T.must(klass.name).split('::').last
-          if content.match(/class\s+#{Regexp.escape(T.must(class_name))}\s*</)
-            return file_path
-          end
-        rescue
+          return file_path if content.match(/class\s+#{Regexp.escape(T.must(class_name))}\s*</)
+        rescue StandardError
           # Ignore file read errors
         end
       end
-      
+
       nil
     end
 
@@ -79,28 +75,26 @@ module SorbetBaml
       in_target_class = T.let(false, T::Boolean)
       current_comment = T.let(nil, T.nilable(String))
       brace_depth = 0
-      
+
       lines.each do |line|
         stripped = line.strip
-        
+
         # Check if we're entering the target class
         if stripped.match(/^class\s+#{Regexp.escape(class_name)}\s*<\s*T::Struct/)
           in_target_class = true
           brace_depth = 0
           next
         end
-        
+
         next unless in_target_class
-        
+
         # Track brace depth to handle nested classes
         brace_depth += stripped.count('{')
         brace_depth -= stripped.count('}')
-        
+
         # Exit when we reach the end of the class
-        if stripped == 'end' && brace_depth == 0
-          break
-        end
-        
+        break if stripped == 'end' && brace_depth == 0
+
         # Extract comment
         if stripped.start_with?('#')
           comment_text = T.must(stripped[1..-1]).strip
@@ -121,37 +115,35 @@ module SorbetBaml
       in_target_class = T.let(false, T::Boolean)
       in_enums_block = T.let(false, T::Boolean)
       current_comment = T.let(nil, T.nilable(String))
-      
+
       lines.each do |line|
         stripped = line.strip
-        
+
         # Check if we're entering the target enum class
         if stripped.match(/^class\s+#{Regexp.escape(class_name)}\s*<\s*T::Enum/)
           in_target_class = true
           next
         end
-        
+
         next unless in_target_class
-        
+
         # Check if we're in the enums block
         if stripped == 'enums do'
           in_enums_block = true
           next
         end
-        
+
         # Exit enums block
         if in_enums_block && stripped == 'end'
           in_enums_block = false
           next
         end
-        
+
         # Exit class
-        if stripped == 'end' && !in_enums_block
-          break
-        end
-        
+        break if stripped == 'end' && !in_enums_block
+
         next unless in_enums_block
-        
+
         # Extract comment
         if stripped.start_with?('#')
           comment_text = T.must(stripped[1..-1]).strip
@@ -167,4 +159,4 @@ module SorbetBaml
       end
     end
   end
-end
+end