sorbet-baml 0.1.0 → 0.3.0

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sorbet-baml
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Vicente Reig Rincon de Arellano
 bindir: exe
 cert_chain: []
-date: 2025-08-16 00:00:00.000000000 Z
+date: 2025-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sorbet-runtime
@@ -36,20 +36,46 @@ files:
 - ".idea/inspectionProfiles/Project_Default.xml"
 - ".rspec"
 - CHANGELOG.md
+- CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
-- docs/README.md
-- docs/advanced-usage.md
-- docs/getting-started.md
-- docs/troubleshooting.md
-- docs/type-mapping.md
+- docs-site/.gitignore
+- docs-site/Gemfile
+- docs-site/Gemfile.lock
+- docs-site/Rakefile
+- docs-site/bridgetown.config.yml
+- docs-site/config.ru
+- docs-site/config/initializers.rb
+- docs-site/config/puma.rb
+- docs-site/esbuild.config.js
+- docs-site/frontend/javascript/index.js
+- docs-site/frontend/styles/index.css
+- docs-site/package.json
+- docs-site/postcss.config.js
+- docs-site/server/roda_app.rb
+- docs-site/src/_components/head.liquid
+- docs-site/src/_components/nav.liquid
+- docs-site/src/_layouts/default.liquid
+- docs-site/src/_layouts/doc.liquid
+- docs-site/src/advanced-usage.md
+- docs-site/src/getting-started.md
+- docs-site/src/index.md
+- docs-site/src/troubleshooting.md
+- docs-site/src/type-mapping.md
+- docs-site/tailwind.config.js
+- examples/description_parameters.rb
 - lib/sorbet_baml.rb
 - lib/sorbet_baml/comment_extractor.rb
 - lib/sorbet_baml/converter.rb
 - lib/sorbet_baml/dependency_resolver.rb
+- lib/sorbet_baml/description_extension.rb
+- lib/sorbet_baml/description_extractor.rb
+- lib/sorbet_baml/dspy_tool_converter.rb
+- lib/sorbet_baml/dspy_tool_extensions.rb
 - lib/sorbet_baml/enum_extensions.rb
 - lib/sorbet_baml/struct_extensions.rb
+- lib/sorbet_baml/tool_extensions.rb
 - lib/sorbet_baml/type_mapper.rb
 - lib/sorbet_baml/version.rb
 - sig/sorbet/baml.rbs
@@ -57,21 +83,49 @@ files:
 - sorbet/rbi/annotations/.gitattributes
 - sorbet/rbi/annotations/rainbow.rbi
 - sorbet/rbi/gems/.gitattributes
+- sorbet/rbi/gems/anthropic@1.5.0.rbi
 - sorbet/rbi/gems/ast@2.4.3.rbi
+- sorbet/rbi/gems/async@2.27.3.rbi
 - sorbet/rbi/gems/benchmark@0.4.1.rbi
+- sorbet/rbi/gems/bigdecimal@3.2.2.rbi
 - sorbet/rbi/gems/byebug@11.1.3.rbi
+- sorbet/rbi/gems/concurrent-ruby@1.3.5.rbi
+- sorbet/rbi/gems/connection_pool@2.5.3.rbi
+- sorbet/rbi/gems/console@1.33.0.rbi
 - sorbet/rbi/gems/date@3.4.1.rbi
 - sorbet/rbi/gems/diff-lcs@1.6.2.rbi
+- sorbet/rbi/gems/dry-configurable@1.3.0.rbi
+- sorbet/rbi/gems/dry-core@1.1.0.rbi
+- sorbet/rbi/gems/dry-logger@1.1.0.rbi
+- sorbet/rbi/gems/dspy@0.19.1.rbi
 - sorbet/rbi/gems/erb@5.0.2.rbi
 - sorbet/rbi/gems/erubi@1.13.1.rbi
+- sorbet/rbi/gems/ffi@1.17.2.rbi
+- sorbet/rbi/gems/fiber-annotation@0.2.0.rbi
+- sorbet/rbi/gems/fiber-local@1.1.0.rbi
+- sorbet/rbi/gems/fiber-storage@1.0.1.rbi
+- sorbet/rbi/gems/google-protobuf@4.32.0.rbi
+- sorbet/rbi/gems/googleapis-common-protos-types@1.20.0.rbi
+- sorbet/rbi/gems/informers@1.2.1.rbi
 - sorbet/rbi/gems/io-console@0.8.1.rbi
+- sorbet/rbi/gems/io-event@1.12.1.rbi
 - sorbet/rbi/gems/json@2.13.2.rbi
 - sorbet/rbi/gems/language_server-protocol@3.17.0.5.rbi
 - sorbet/rbi/gems/lint_roller@1.1.0.rbi
 - sorbet/rbi/gems/logger@1.7.0.rbi
+- sorbet/rbi/gems/metrics@0.13.0.rbi
 - sorbet/rbi/gems/netrc@0.11.0.rbi
+- sorbet/rbi/gems/onnxruntime@0.10.0.rbi
+- sorbet/rbi/gems/openai@0.16.0.rbi
+- sorbet/rbi/gems/opentelemetry-api@1.6.0.rbi
+- sorbet/rbi/gems/opentelemetry-common@0.22.0.rbi
+- sorbet/rbi/gems/opentelemetry-exporter-otlp@0.30.0.rbi
+- sorbet/rbi/gems/opentelemetry-registry@0.4.0.rbi
+- sorbet/rbi/gems/opentelemetry-sdk@1.8.1.rbi
+- sorbet/rbi/gems/opentelemetry-semantic_conventions@1.11.0.rbi
 - sorbet/rbi/gems/parallel@1.27.0.rbi
 - sorbet/rbi/gems/parser@3.3.9.0.rbi
+- sorbet/rbi/gems/polars-df@0.20.0.rbi
 - sorbet/rbi/gems/pp@0.6.2.rbi
 - sorbet/rbi/gems/prettyprint@0.2.0.rbi
 - sorbet/rbi/gems/prism@1.4.0.rbi
@@ -94,14 +148,20 @@ files:
 - sorbet/rbi/gems/rubocop-sorbet@0.10.5.rbi
 - sorbet/rbi/gems/rubocop@1.79.2.rbi
 - sorbet/rbi/gems/ruby-progressbar@1.13.0.rbi
+- sorbet/rbi/gems/sorbet-result@1.4.0.rbi
+- sorbet/rbi/gems/sorbet-schema@0.9.2.rbi
+- sorbet/rbi/gems/sorbet-struct-comparable@1.3.0.rbi
 - sorbet/rbi/gems/spoom@1.6.3.rbi
 - sorbet/rbi/gems/stringio@3.1.7.rbi
 - sorbet/rbi/gems/tapioca@0.16.11.rbi
 - sorbet/rbi/gems/thor@1.4.0.rbi
+- sorbet/rbi/gems/tokenizers@0.5.5.rbi
+- sorbet/rbi/gems/traces@0.17.0.rbi
 - sorbet/rbi/gems/unicode-display_width@3.1.5.rbi
 - sorbet/rbi/gems/unicode-emoji@4.0.4.rbi
 - sorbet/rbi/gems/yard-sorbet@0.9.0.rbi
 - sorbet/rbi/gems/yard@0.9.37.rbi
+- sorbet/rbi/gems/zeitwerk@2.7.3.rbi
 - sorbet/tapioca/config.yml
 - sorbet/tapioca/require.rb
 homepage: https://github.com/vicentereig/sorbet-baml

data/docs/README.md

@@ -1,117 +0,0 @@
-# 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
-
-This gem has reached **feature completeness** for core BAML conversion needs. The implementation is production-ready with:
-
-- ✅ **Complete type support** - All Sorbet types mapped to BAML
-- ✅ **Ruby-idiomatic API** - `.to_baml` method on all T::Struct/T::Enum classes  
-- ✅ **Dependency management** - Automatic topological sorting
-- ✅ **100% test coverage** - 34 comprehensive test cases
-- ✅ **Full Sorbet type safety** - Zero type errors
-
-Future enhancements are optional nice-to-haves rather than core requirements.
-
-## 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
-
-# Legacy API also supported
-# SorbetBaml.from_struct(User)
-```
-
-**Generated BAML:**
-```baml
-class User {
-  name string
-  age int
-  email string?
-}
-```
-
-## Design Goals
-
-1. **Ruby-Idiomatic** - Natural `.to_baml` API that feels native
-2. **Production-Ready** - Complete type support, dependency management, full test coverage
-3. **Token Efficiency** - 60% fewer tokens than JSON Schema for real workloads
-4. **Zero-Config** - Works automatically with existing Sorbet codebases
-5. **Type-Safe** - Full Sorbet type checking throughout the gem
-
-## What This Is Not
-
-- Not a BAML runtime or executor
-- Not a JSON Schema generator (use [sorbet-schema](https://github.com/maxveldink/sorbet-schema) for that)
-- Not a Sorbet type checker
-- Not a serialization library
-
-## Advanced Features
-
-### Ruby-Idiomatic API
-```ruby
-User.to_baml                    # Single type
-User.to_baml(indent_size: 4)    # Custom formatting
-User.to_baml(include_dependencies: true)  # With dependencies
-```
-
-### Automatic Dependency Management
-```ruby
-class Address < T::Struct
-  const :street, String
-end
-
-class User < T::Struct
-  const :address, Address
-end
-
-User.to_baml(include_dependencies: true)
-```
-
-**Generated BAML (correct ordering):**
-```baml
-class Address {
-  street string
-}
-
-class User {
-  address Address
-}
-```
-
-## Why BAML?
-
-BAML (Boundary AI Markup Language) provides a concise way to define types for LLM consumption. **Real-world comparison** from production agentic workflows:
-
-| Format | Tokens | Efficiency |
-|--------|--------|-----------|
-| JSON Schema | ~450 | baseline |
-| **BAML** | **~180** | **🔥 60% fewer** |
-
-### Benefits:
-- **Cost Savings**: 60% reduction in prompt tokens = 60% lower LLM API costs
-- **Performance**: Smaller prompts = faster LLM response times  
-- **Context Efficiency**: More room for actual content vs. type definitions
-- **Readability**: Human-readable and maintainable
-- **LLM-Friendly**: Designed specifically for AI consumption
-
-Perfect for prompt engineering, structured output generation, and agentic workflows where token efficiency matters.

data/docs/advanced-usage.md

@@ -1,427 +0,0 @@
-# Advanced Usage
-
-## Ruby-Idiomatic API
-
-The gem automatically extends all T::Struct and T::Enum classes with conversion methods:
-
-```ruby
-class User < T::Struct
-  const :name, String
-  const :age, Integer
-end
-
-# Ruby-idiomatic - just call the method!
-User.to_baml
-User.baml_type_definition  # Same as to_baml
-```
-
-## Automatic Dependency Management
-
-The most powerful feature is automatic dependency resolution:
-
-```ruby
-class ContactInfo < T::Struct
-  const :email, String
-  const :phone, T.nilable(String)
-end
-
-class Company < T::Struct
-  const :name, String
-  const :contact, ContactInfo
-end
-
-class User < T::Struct
-  const :name, String
-  const :company, Company
-end
-
-# Dependencies included automatically with smart defaults!
-User.to_baml
-```
-
-**Generated BAML (with correct ordering):**
-```baml
-class ContactInfo {
-  email string
-  phone string?
-}
-
-class Company {
-  name string
-  contact ContactInfo
-}
-
-class User {
-  name string
-  company Company
-}
-```
-
-## Converting Multiple Types
-
-### Manual Collection
-
-```ruby
-# Convert multiple types manually
-types = [ContactInfo, Company, User]
-baml_output = types.map(&:to_baml).join("\n\n")
-```
-
-### Legacy API (still supported)
-
-```ruby
-# Legacy API for multiple structs
-SorbetBaml.from_structs([ContactInfo, Company, User])
-
-# Legacy API for single struct
-SorbetBaml.from_struct(User)
-```
-
-## Advanced Type Examples
-
-### Complex Enums with Structs
-
-```ruby
-class OrderStatus < T::Enum
-  enums do
-    Pending = new('pending')
-    Processing = new('processing')
-    Shipped = new('shipped')
-    Delivered = new('delivered')
-    Cancelled = new('cancelled')
-  end
-end
-
-class OrderItem < T::Struct
-  const :product_id, String
-  const :quantity, Integer
-  const :price, Float
-end
-
-class Order < T::Struct
-  const :id, String
-  const :status, OrderStatus
-  const :items, T::Array[OrderItem]
-  const :metadata, T::Hash[String, T.any(String, Integer, Float)]
-  const :shipping_address, T.nilable(Address)
-end
-
-# Generate complete type definitions
-[OrderStatus, OrderItem, Order].map(&:to_baml).join("\n\n")
-```
-
-**Generated BAML:**
-```baml
-enum OrderStatus {
-  "pending"
-  "processing"
-  "shipped"
-  "delivered"
-  "cancelled"
-}
-
-class OrderItem {
-  product_id string
-  quantity int
-  price float
-}
-
-class Order {
-  id string
-  status OrderStatus
-  items OrderItem[]
-  metadata map<string, string | int | float>
-  shipping_address Address?
-}
-```
-
-### Self-Referential Types
-
-```ruby
-class Category < T::Struct
-  const :name, String
-  const :parent, T.nilable(Category)
-  const :children, T::Array[Category]
-end
-
-Category.to_baml
-```
-
-**Generated BAML:**
-```baml
-class Category {
-  name string
-  parent Category?
-  children Category[]
-}
-```
-
-## Configuration Options
-
-### Custom Indentation
-
-```ruby
-User.to_baml(indent_size: 4)
-```
-
-**Generated BAML:**
-```baml
-class User {
-    name string
-    age int
-}
-```
-
-### Field Descriptions
-
-Extract documentation from Ruby comments to provide LLM context:
-
-```ruby
-class DocumentedUser < T::Struct
-  # User's full legal name for official records
-  const :full_name, String
-  
-  # Age in years, must be 18 or older for account creation
-  const :age, Integer
-  
-  # Primary email address for account notifications
-  const :email, String
-end
-
-DocumentedUser.to_baml
-```
-
-**Generated BAML with descriptions:**
-```baml
-class DocumentedUser {
-  full_name string @description("User's full legal name for official records")
-  age int @description("Age in years, must be 18 or older for account creation")
-  email string @description("Primary email address for account notifications")
-}
-```
-
-### Combining Options
-
-```ruby
-# Smart defaults: dependencies and descriptions already included!
-User.to_baml(indent_size: 4)
-
-# Or disable features if needed
-User.to_baml(
-  include_dependencies: false,
-  include_descriptions: false,
-  indent_size: 4
-)
-```
-
-## File Generation
-
-### Single File Output
-
-```ruby
-# Generate and write to file (dependencies included by default)
-baml_content = User.to_baml
-File.write("types/user.baml", baml_content)
-```
-
-### Multiple Files
-
-```ruby
-# Generate separate files for each type
-[User, Company, ContactInfo].each do |type|
-  filename = type.name.downcase.gsub('::', '_')
-  File.write("types/#{filename}.baml", type.to_baml)
-end
-```
-
-### Build Process Integration
-
-```ruby
-# Rakefile
-desc "Generate BAML type definitions"
-task :generate_baml do
-  require 'sorbet-baml'
-  require_relative 'app/models'
-  
-  types = [User, Company, Order, Product] # Your app types
-  baml_content = types.map(&:to_baml).join("\n\n")
-  
-  File.write("lib/types.baml", baml_content)
-  puts "Generated BAML types in lib/types.baml"
-end
-```
-
-## LLM Integration Patterns
-
-### With OpenAI Structured Outputs
-
-```ruby
-require 'openai'
-require 'sorbet-baml'
-
-# Define your response format
-class AnalysisResult < T::Struct
-  const :sentiment, String
-  const :confidence, Float
-  const :key_phrases, T::Array[String]
-  const :metadata, T::Hash[String, String]
-end
-
-# Generate schema for LLM
-schema = AnalysisResult.to_baml
-
-client = OpenAI::Client.new
-response = client.chat(
-  parameters: {
-    model: "gpt-4o",
-    messages: [
-      {
-        role: "system",
-        content: "Analyze text and respond with data matching this BAML schema:\n\n#{schema}"
-      },
-      {
-        role: "user", 
-        content: "Analyze: 'I love this new product!'"
-      }
-    ]
-  }
-)
-```
-
-### With Anthropic Claude
-
-```ruby
-require 'anthropic'
-require 'sorbet-baml'
-
-schema = UserProfile.to_baml(include_dependencies: true)
-
-client = Anthropic::Client.new
-response = client.messages(
-  model: "claude-3-5-sonnet-20241022",
-  max_tokens: 1000,
-  messages: [
-    {
-      role: "user",
-      content: "Generate a realistic user profile matching this schema:\n\n#{schema}"
-    }
-  ]
-)
-```
-
-### With DSPy.rb Integration
-
-```ruby
-require 'dspy'
-require 'sorbet-baml'
-
-# Your T::Struct automatically works with DSPy signatures
-class UserAnalysis < DSPy::Signature
-  input { const :user_data, String }
-  output { const :analysis, AnalysisResult }  # Uses your T::Struct
-end
-
-# The BAML schema is automatically generated for LLM prompts
-predictor = DSPy::Predict.new(UserAnalysis)
-result = predictor.call(user_data: "John, 25, loves hiking")
-```
-
-### Prompt Engineering
-
-```ruby
-# Template for complex prompts
-def build_analysis_prompt(data, schema)
-  <<~PROMPT
-    You are a data analyst. Analyze the following data and return results 
-    in the exact format specified by this BAML schema:
-
-    #{schema}
-
-    Data to analyze:
-    #{data}
-
-    Requirements:
-    - Follow the schema exactly
-    - Provide confidence scores between 0.0 and 1.0
-    - Extract meaningful insights
-  PROMPT
-end
-
-schema = AnalysisResult.to_baml
-prompt = build_analysis_prompt(user_input, schema)
-```
-
-## Rails Integration
-
-### Model Integration
-
-```ruby
-# app/models/user.rb
-class User < ApplicationRecord
-  # Your ActiveRecord model...
-  
-  # Add Sorbet types for API schemas
-  class UserAPI < T::Struct
-    const :id, Integer
-    const :name, String
-    const :email, String
-    const :created_at, String
-  end
-  
-  def to_api_schema
-    UserAPI.to_baml
-  end
-end
-
-# Usage in controllers
-class UsersController < ApplicationController
-  def schema
-    render json: { schema: User::UserAPI.to_baml }
-  end
-end
-```
-
-### API Documentation
-
-```ruby
-# Generate API docs automatically
-class ApiDocsGenerator
-  API_TYPES = [
-    User::UserAPI,
-    Order::OrderAPI,
-    Product::ProductAPI
-  ].freeze
-  
-  def self.generate
-    schema = API_TYPES.map(&:to_baml).join("\n\n")
-    File.write("docs/api_schema.baml", schema)
-  end
-end
-```
-
-## Performance Considerations
-
-### Caching Generated BAML
-
-```ruby
-class CachedTypeConverter
-  def self.to_baml(type)
-    @cache ||= {}
-    @cache[type] ||= type.to_baml
-  end
-end
-
-# Use in production for frequently accessed types
-schema = CachedTypeConverter.to_baml(User)
-```
-
-### Lazy Loading
-
-```ruby
-# Only generate BAML when needed (smart defaults apply)
-class ApiResponse
-  def schema
-    @schema ||= self.class.to_baml
-  end
-end
-```