sorbet-baml 0.0.1 → 0.1.0

data/docs/advanced-usage.md

@@ -1,18 +1,33 @@
 # Advanced Usage
 
-## Converting Multiple Structs
+## Ruby-Idiomatic API
 
-When you have related structs, convert them together to maintain relationships:
+The gem automatically extends all T::Struct and T::Enum classes with conversion methods:
 
 ```ruby
-class Address < T::Struct
-  const :street, String
-  const :city, String
+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 :address, Address
+  const :contact, ContactInfo
 end
 
 class User < T::Struct
@@ -20,66 +35,393 @@ class User < T::Struct
   const :company, Company
 end
 
-# Convert all at once
-baml = SorbetBaml.from_structs([Address, Company, User])
+# Dependencies included automatically with smart defaults!
+User.to_baml
 ```
 
-## Options
+**Generated BAML (with correct ordering):**
+```baml
+class ContactInfo {
+  email string
+  phone string?
+}
+
+class Company {
+  name string
+  contact ContactInfo
+}
+
+class User {
+  name string
+  company Company
+}
+```
 
-### Include Descriptions
+## Converting Multiple Types
+
+### Manual Collection
 
 ```ruby
-# Future feature - not yet implemented
-baml = SorbetBaml.from_struct(User,
-  include_descriptions: true  # Will add @description annotations
-)
+# 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
-# Future feature - not yet implemented
-baml = SorbetBaml.from_struct(User,
-  indent_size: 4  # Use 4 spaces instead of 2
+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
 )
 ```
 
-## Working with Existing BAML Projects
+## File Generation
 
-If you're already using BAML, you can generate type definitions to include in your `.baml` files:
+### Single File Output
 
 ```ruby
-# Generate just the class definition
-definition = SorbetBaml.from_struct(MyStruct)
+# Generate and write to file (dependencies included by default)
+baml_content = User.to_baml
+File.write("types/user.baml", baml_content)
+```
 
-# Write to a BAML file
-File.write("types/my_struct.baml", definition)
+### 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
 ```
 
-## Integration with LLM Libraries
+### Build Process Integration
 
-### With OpenAI
+```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'
 
-schema = SorbetBaml.from_struct(ResponseFormat)
+# 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(
-  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"
-  }]
+  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 DSPy.rb
+### 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
-# Coming soon - integration with DSPy.rb for automatic schema generation
+# 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
 ```

data/docs/getting-started.md

@@ -23,27 +23,64 @@ end
 ```ruby
 require 'sorbet-baml'
 
+# Ruby-idiomatic API (recommended)
+User.to_baml
+
+# Legacy API (still supported)  
 baml = SorbetBaml.from_struct(User)
 puts baml
-# Output:
-# class User {
-#   id int
-#   name string
-#   email string?
-# }
 ```
 
-### 3. Use with your LLM
+**Generated BAML:**
+```baml
+class User {
+  id int
+  name string
+  email string?
+}
+```
+
+### 3. Add field descriptions (optional)
+
+Document your fields with comments for better LLM understanding:
+
+```ruby
+class User < T::Struct
+  # Unique identifier for the user account
+  const :id, Integer
+  
+  # User's display name, visible to other users
+  const :name, String
+  
+  # Optional email for notifications and login
+  const :email, T.nilable(String)
+end
+
+# Generate BAML (descriptions included by default!)
+User.to_baml
+```
+
+**Generated BAML with descriptions:**
+```baml
+class User {
+  id int @description("Unique identifier for the user account")
+  name string @description("User's display name, visible to other users")
+  email string? @description("Optional email for notifications and login")
+}
+```
+
+### 4. Use with your LLM
 
 Include the BAML definition in your prompt:
 
 ```ruby
+baml = User.to_baml
 prompt = <<~PROMPT
   Generate sample data matching this schema:
   
   #{baml}
   
-  Return 3 examples.
+  Return 3 realistic examples.
 PROMPT
 ```