ruby_llm-contract 0.7.1 → 0.8.0

data/examples/03_target_audience.rb

@@ -1,201 +0,0 @@
-# frozen_string_literal: true
-
-# =============================================================================
-# EXAMPLE 3: Target Audience Generation
-#
-# Real-world case: Analyze a product URL and generate audience profiles.
-# This is stage 1 of the pipeline — if it fails, everything downstream
-# breaks (subreddit discovery, thread classification, comment generation).
-# =============================================================================
-
-require_relative "../lib/ruby_llm/contract"
-
-# =============================================================================
-# BEFORE: Legacy approach (prompt + schema in concern, ad-hoc validation)
-# =============================================================================
-#
-# In the legacy codebase, this is in target_audience_prompts.rb:
-#
-# ```ruby
-# def build_audience_profile_prompt(plan, pages)
-#   <<~PROMPT
-#     Analyze this webpage. First, understand what the product/service does.
-#     Then figure out who the TARGET AUDIENCE is.
-#
-#     #{product_input_context(plan, pages)}
-#
-#     ---
-#
-#     Generate:
-#     1. LOCALE: Detect the page language. Return ISO 639-1 code.
-#     2. DESCRIPTION: Write exactly 1 sentence (max 15 words): WHAT it is.
-#     3. Identify 2-3 distinct target audience groups.
-#
-#     CRITICAL: Describe groups by their LIFE SITUATION and EVERYDAY PROBLEMS...
-#     [... 40 more lines of instructions ...]
-#   PROMPT
-# end
-#
-# # Validation is ad-hoc, buried in the caller:
-# def valid_product_context?(context)
-#   context.is_a?(Hash) &&
-#     context["locale"].present? &&
-#     context["description"].present? &&
-#     context["groups"].is_a?(Array) &&
-#     context["groups"].size >= 1
-# end
-# ```
-#
-# PROBLEMS:
-# - 50-line heredoc string — impossible to diff meaningfully
-# - Validation is a separate method, easy to forget to call
-# - If locale is wrong (e.g. "english" instead of "en"), it passes validation
-# - If groups are present but empty/garbage, no way to catch it
-# - Failure here silently poisons all 6 downstream stages
-
-# =============================================================================
-# AFTER: ruby_llm-contract approach
-# =============================================================================
-
-class GenerateTargetAudience < RubyLLM::Contract::Step::Base
-  input_type RubyLLM::Contract::Types::Hash.schema(
-    url: RubyLLM::Contract::Types::String,
-    body_text: RubyLLM::Contract::Types::String,
-    sitemap_pages: RubyLLM::Contract::Types::Array.of(RubyLLM::Contract::Types::Hash)
-  )
-  output_type Hash
-
-  prompt do
-    system "Analyze a product webpage and generate target audience profiles."
-
-    rule "Detect page language, return ISO 639-1 code (e.g. 'en', 'pl', 'de')."
-    rule "Write product description in exactly 1 sentence, max 15 words. Say WHAT, not HOW."
-    rule "Identify 2-3 distinct audience groups based on LIFE SITUATION, not product jargon."
-    rule "Write 'who' as if YOU are that person posting on Reddit, not a marketer."
-    rule "Return JSON with locale, description, and groups array."
-
-    section "GOOD vs BAD EXAMPLES", <<~EXAMPLES
-      Good "who": "I'm 30, trying to lose weight but I hate counting calories"
-      Bad "who": "Adults 25-55 who buy specialty outdoor gear occasionally"
-
-      Good use_case: "I keep checking 5 different shops and it takes forever"
-      Bad use_case: "Track shop promotions across retailers"
-
-      Good thread: "spent way too much on yarn this month lol"
-      Bad thread: "budgeting for craft supplies"
-    EXAMPLES
-
-    user "URL: {url}\n\nBODY TEXT:\n{body_text}\n\nSITEMAP PAGES:\n{sitemap_pages}"
-  end
-
-  validate("locale is valid ISO 639-1") do |o|
-    o[:locale].is_a?(String) && o[:locale].match?(/\A[a-z]{2}\z/)
-  end
-
-  validate("description is present and concise") do |o|
-    desc = o[:description].to_s.strip
-    desc.length > 5 && desc.split.size <= 20
-  end
-
-  validate("has 1-4 audience groups") do |o|
-    o[:groups].is_a?(Array) && o[:groups].size.between?(1, 4)
-  end
-
-  validate("each group has who field") do |o|
-    o[:groups].is_a?(Array) && o[:groups].all? { |g| g[:who].to_s.strip.length > 10 }
-  end
-
-  validate("each group has use_cases") do |o|
-    o[:groups].is_a?(Array) && o[:groups].all? { |g| g[:use_cases].is_a?(Array) && g[:use_cases].size >= 2 }
-  end
-
-  validate("each group has good_fit_threads") do |o|
-    o[:groups].is_a?(Array) && o[:groups].all? do |g|
-      g[:good_fit_threads].is_a?(Array) && g[:good_fit_threads].size >= 2
-    end
-  end
-end
-
-# =============================================================================
-# DEMO: Run with test adapter — showing cascade failure prevention
-# =============================================================================
-
-input = {
-  url: "https://deals.example.com",
-  body_text: "Track deals from niche online shops. Get alerts for price drops on craft supplies, " \
-             "hobby gear, and specialty items. We monitor 200+ small retailers daily.",
-  sitemap_pages: [
-    { url: "/yarn-deals", title: "Yarn & Crochet Deals", description: "Sales on yarn, hooks, patterns" },
-    { url: "/gaming-deals", title: "Gaming Merch Deals", description: "Gaming accessories and merch sales" }
-  ]
-}
-
-# Happy path — good audience profile
-good_response = {
-  locale: "en",
-  description: "Deals aggregator for niche online shops.",
-  groups: [
-    {
-      who: "I'm a crafter who spends too much on supplies every month and my partner is getting annoyed.",
-      use_cases: ["I keep checking 5 different yarn shops", "I always find out about sales after they end"],
-      not_covered: ["Groceries and food delivery", "Air travel"],
-      good_fit_threads: ["spent way too much on yarn this month lol", "anyone else feel guilty about hobby spending?"],
-      bad_fit_threads: ["best grocery cashback apps", "cheap flight deals"]
-    },
-    {
-      who: "I'm a gamer building my setup on a budget and I hate paying full price for peripherals.",
-      use_cases: ["I want to know when my wishlist items go on sale",
-                  "Small shops have better deals but I can't check them all"],
-      not_covered: ["Digital game keys", "Streaming subscriptions"],
-      good_fit_threads: ["just got into minipainting and my wallet hurts", "budget gaming setup thread"],
-      bad_fit_threads: ["best game pass deals", "Netflix vs Disney+"]
-    }
-  ]
-}.to_json
-
-adapter = RubyLLM::Contract::Adapters::Test.new(response: good_response)
-result = GenerateTargetAudience.run(input, context: { adapter: adapter })
-
-puts "=== HAPPY PATH ==="
-puts "Status: #{result.status}"
-puts "Locale: #{result.parsed_output[:locale]}"
-puts "Description: #{result.parsed_output[:description]}"
-puts "Groups: #{result.parsed_output[:groups].size}"
-puts "Validation errors: #{result.validation_errors}"
-puts
-
-# Bad path — invalid locale (legacy code would let "english" pass)
-bad_locale_response = {
-  locale: "english", # Should be "en", not "english"
-  description: "Deals aggregator for niche online shops.",
-  groups: [{ who: "A crafter", use_cases: ["buying yarn"], not_covered: [], good_fit_threads: ["yarn deals"],
-             bad_fit_threads: [] }]
-}.to_json
-
-bad_adapter = RubyLLM::Contract::Adapters::Test.new(response: bad_locale_response)
-result = GenerateTargetAudience.run(input, context: { adapter: bad_adapter })
-
-puts "=== BAD LOCALE (legacy code would let this pass) ==="
-puts "Status: #{result.status}"
-puts "Validation errors: #{result.validation_errors}"
-puts
-
-# Bad path — empty/garbage groups (cascade failure source)
-empty_groups_response = {
-  locale: "en",
-  description: "A website.",
-  groups: []
-}.to_json
-
-empty_adapter = RubyLLM::Contract::Adapters::Test.new(response: empty_groups_response)
-result = GenerateTargetAudience.run(input, context: { adapter: empty_adapter })
-
-puts "=== EMPTY GROUPS (would poison all downstream stages) ==="
-puts "Status: #{result.status}"
-puts "Validation errors: #{result.validation_errors}"
-puts
-
-# The key insight: in a pipeline, you check result.ok? before proceeding
-puts "=== CASCADE PREVENTION ==="
-puts "if result.failed? → don't run SearchExpansion, ThreadClassification, CommentGeneration"
-puts "Legacy code would silently pass bad data to 6 more LLM calls, wasting tokens and producing garbage."

data/examples/04_real_llm.rb

@@ -1,410 +0,0 @@
-# frozen_string_literal: true
-
-# =============================================================================
-# EXAMPLE 4: Real LLM calls via ruby_llm
-#
-# All previous examples used Adapters::Test with canned responses.
-# This example shows how to connect to a real LLM provider
-# (OpenAI, Anthropic, Google, etc.) using Adapters::RubyLLM.
-#
-# REQUIREMENTS:
-#   gem install ruby_llm
-#   export OPENAI_API_KEY=sk-...       # or any provider key
-#
-# RUN:
-#   ruby examples/04_real_llm.rb
-# =============================================================================
-
-require_relative "../lib/ruby_llm/contract"
-
-# =============================================================================
-# STEP 1: Configure — single block, API key auto-creates adapter
-#
-# Just set your API key. The adapter is created automatically.
-# =============================================================================
-
-RubyLLM::Contract.configure do |config|
-  config.openai_api_key = ENV.fetch("OPENAI_API_KEY", nil)
-  # config.anthropic_api_key = ENV.fetch("ANTHROPIC_API_KEY", nil)
-  config.default_model = "gpt-4.1-mini"
-end
-
-# =============================================================================
-# STEP 3: Define a step — identical to what you'd write with Test adapter
-#
-# The step doesn't know or care which adapter runs it.
-# Same types, same prompt, same contract.
-# =============================================================================
-
-class ClassifyIntent < RubyLLM::Contract::Step::Base
-  input_type String
-
-  output_schema do
-    string :intent, enum: %w[sales support billing other]
-    number :confidence, minimum: 0.0, maximum: 1.0
-  end
-
-  prompt do
-    system "You are an intent classifier for a customer support system."
-    rule "Return JSON only, no markdown."
-    example input: "I want to upgrade my plan",
-            output: '{"intent": "sales", "confidence": 0.95}'
-    example input: "My invoice is wrong",
-            output: '{"intent": "billing", "confidence": 0.9}'
-    user "{input}"
-  end
-end
-
-# =============================================================================
-# STEP 4: Run it — real LLM call, full contract enforcement
-#
-# The adapter sends the prompt to the real model.
-# The contract validates the response just like with Test adapter.
-# You get real token usage in the trace.
-# =============================================================================
-
-puts "Calling LLM..."
-result = ClassifyIntent.run("I can't log in to my account")
-
-puts "Status:  #{result.status}"                       # => :ok
-puts "Output:  #{result.parsed_output}"                # => {intent: "support", confidence: 0.95}
-puts "Model:   #{result.trace[:model]}"                # => "gpt-4.1-mini"
-puts "Latency: #{result.trace[:latency_ms]}ms"         # => 823ms (real network time)
-puts "Tokens:  #{result.trace[:usage]}"                # => {input_tokens: 142, output_tokens: 18}
-
-if result.ok?
-  puts "Intent:  #{result.parsed_output[:intent]}"
-else
-  puts "FAILED:  #{result.validation_errors}"
-end
-
-# =============================================================================
-# STEP 5: Override model per call — A/B test different models
-#
-# Use context to try different models without changing the step definition.
-# =============================================================================
-
-puts "\n--- Comparing models ---"
-
-%w[gpt-4.1-mini gpt-4.1-nano].each do |model|
-  r = ClassifyIntent.run("I need a refund", context: { model: model })
-  puts "#{model}: #{r.parsed_output} (#{r.trace[:latency_ms]}ms, #{r.trace[:usage]})"
-end
-
-# =============================================================================
-# STEP 6: Control generation params — temperature, max_tokens
-#
-# Options are forwarded to ruby_llm. Lower temperature = more deterministic.
-# =============================================================================
-
-puts "\n--- With temperature 0 ---"
-result = ClassifyIntent.run(
-  "Do you have an enterprise plan?",
-  context: { model: "gpt-4.1-mini", temperature: 0.0, max_tokens: 50 }
-)
-puts "Output: #{result.parsed_output}"
-
-# =============================================================================
-# STEP 7: Same step, different provider — just change the model
-#
-# If you have an Anthropic key configured, you can switch with one line.
-# The prompt, contract, and invariants are provider-agnostic.
-# =============================================================================
-
-# Uncomment if you have an Anthropic key:
-# puts "\n--- Anthropic ---"
-# result = ClassifyIntent.run(
-#   "I want to cancel my subscription",
-#   context: { model: "claude-sonnet-4-6" }
-# )
-# puts "Output: #{result.parsed_output}"
-
-# =============================================================================
-# STEP 8: Error handling — what happens when things go wrong
-#
-# Contract enforcement works the same with real LLM responses.
-# If the model returns something invalid, you get a clear error.
-# =============================================================================
-
-class StrictClassifier < RubyLLM::Contract::Step::Base
-  input_type String
-
-  output_schema do
-    string :sentiment, enum: %w[positive negative neutral]
-  end
-
-  prompt do
-    system "Classify the sentiment."
-    user "{input}"
-  end
-end
-
-puts "\n--- Strict classifier ---"
-result = StrictClassifier.run("This product is amazing!", context: { model: "gpt-4.1-mini" })
-
-if result.ok?
-  puts "Passed: #{result.parsed_output}"
-else
-  puts "Failed: #{result.status} — #{result.validation_errors}"
-  puts "Raw:    #{result.raw_output}"
-end
-
-# =============================================================================
-# STEP 9: Full power — every prompt feature combined with a real LLM
-#
-# This step uses EVERY feature from 00_basics.rb in a single definition:
-#   - system message (main instruction)
-#   - rules (individual requirements)
-#   - sections (labeled context blocks)
-#   - examples (few-shot input/output pairs)
-#   - Hash input (multi-field auto-interpolation)
-#   - 1-arity invariants (validate output alone)
-#   - 2-arity invariants (cross-validate output against input)
-#
-# All of it running against a real LLM.
-# =============================================================================
-
-class AnalyzeTicket < RubyLLM::Contract::Step::Base
-  input_type RubyLLM::Contract::Types::Hash.schema(
-    title: RubyLLM::Contract::Types::String,
-    body: RubyLLM::Contract::Types::String,
-    product: RubyLLM::Contract::Types::String,
-    customer_tier: RubyLLM::Contract::Types::String
-  )
-  output_type Hash
-
-  prompt do
-    system "You are a support ticket analyzer for a SaaS company."
-
-    rule "Return JSON only, no markdown, no explanation."
-    rule "Include all required fields: category, priority, sentiment, summary, suggested_action."
-    rule "Categories: billing, technical, feature_request, account, other."
-    rule "Priorities: low, medium, high, urgent."
-    rule "Sentiments: positive, negative, neutral, frustrated."
-    rule "Summary must be one sentence, max 100 characters."
-
-    section "PRODUCT CONTEXT", "Product: {product}\nCustomer tier: {customer_tier}"
-
-    section "PRIORITY RULES",
-            "urgent = data loss or security issue\n" \
-            "high = service down or billing error\n" \
-            "medium = feature broken but workaround exists\n" \
-            "low = question, feedback, or cosmetic issue"
-
-    example input: "Title: Can't export CSV\n\nBody: Export button returns 500 error since yesterday.",
-            output: '{"category":"technical","priority":"high","sentiment":"frustrated",' \
-                    '"summary":"CSV export returns 500 error","suggested_action":"escalate to engineering"}'
-
-    example input: "Title: Dark mode request\n\nBody: Would love dark mode for late night work!",
-            output: '{"category":"feature_request","priority":"low","sentiment":"positive",' \
-                    '"summary":"Requests dark mode feature","suggested_action":"add to feature backlog"}'
-
-    user "Title: {title}\n\nBody: {body}"
-  end
-
-  validate("category must be valid") do |o|
-    %w[billing technical feature_request account other].include?(o[:category])
-  end
-
-  validate("priority must be valid") do |o|
-    %w[low medium high urgent].include?(o[:priority])
-  end
-
-  validate("sentiment must be valid") do |o|
-    %w[positive negative neutral frustrated].include?(o[:sentiment])
-  end
-
-  validate("summary must be present") do |o|
-    !o[:summary].to_s.strip.empty?
-  end
-
-  validate("summary must be concise") do |o|
-    o[:summary].to_s.length <= 100
-  end
-
-  validate("suggested_action must be present") do |o|
-    !o[:suggested_action].to_s.strip.empty?
-  end
-
-  # 2-arity: cross-validate output against input
-  validate("urgent priority requires justification in body") do |output, input|
-    next true unless output[:priority] == "urgent"
-
-    body = input[:body].downcase
-    body.include?("data loss") || body.include?("security") ||
-      body.include?("breach") || body.include?("leak") || body.include?("deleted")
-  end
-end
-
-puts "\n--- Full power: AnalyzeTicket ---"
-
-result = AnalyzeTicket.run(
-  {
-    title: "All my projects disappeared",
-    body: "I logged in this morning and all 47 projects are gone. This is a data loss emergency. " \
-          "I have a client demo in 2 hours.",
-    product: "ProjectHub Pro",
-    customer_tier: "enterprise"
-  },
-  context: { model: "gpt-4.1-mini", temperature: 0.0 }
-)
-
-puts "Status:   #{result.status}"
-puts "Category: #{result.parsed_output&.dig(:category)}"
-puts "Priority: #{result.parsed_output&.dig(:priority)}"
-puts "Sentiment:#{result.parsed_output&.dig(:sentiment)}"
-puts "Summary:  #{result.parsed_output&.dig(:summary)}"
-puts "Action:   #{result.parsed_output&.dig(:suggested_action)}"
-puts "Latency:  #{result.trace[:latency_ms]}ms"
-puts "Tokens:   #{result.trace[:usage]}"
-
-puts "ERRORS:   #{result.validation_errors}" if result.failed?
-
-# =============================================================================
-# STEP 10: Full power — Pipeline + output_schema + invariants + real LLM
-#
-# This combines everything: 3-step pipeline where each step has its own
-# output_schema (provider-enforced), cross-validation invariants,
-# and real LLM calls. If any step hallucinates, execution stops.
-#
-# Use case: meeting transcript → follow-up email
-#   Step 1 (listener): extract decisions + action items
-#   Step 2 (critic): flag vague owners/deadlines
-#   Step 3 (writer): generate send-ready follow-up email
-# =============================================================================
-
-class ExtractMeetingItems < RubyLLM::Contract::Step::Base
-  input_type String
-
-  output_schema do
-    array :decisions do
-      string :id
-      string :description
-      string :made_by
-    end
-    array :action_items do
-      string :id
-      string :task
-      string :owner
-      string :deadline
-    end
-  end
-
-  prompt do
-    system "Extract decisions and action items from a meeting transcript."
-    rule "Only include decisions explicitly stated, never infer."
-    rule "Assign sequential IDs: D1, D2... for decisions, A1, A2... for action items."
-    user "{input}"
-  end
-end
-
-class AnalyzeAmbiguities < RubyLLM::Contract::Step::Base
-  input_type Hash
-
-  output_schema do
-    array :decisions do
-      string :id
-      string :description
-      string :made_by
-    end
-    array :action_items do
-      string :id
-      string :task
-      string :owner
-      string :deadline
-    end
-    array :analyses do
-      string :action_item_id
-      string :status, enum: %w[clear ambiguous]
-      array :issues do
-        string :field, enum: %w[owner deadline scope]
-        string :problem
-        string :clarification_question
-      end
-    end
-  end
-
-  prompt do
-    system "Review action items for completeness. Flag vague owners, missing deadlines, unclear scope."
-    rule "Pass through the original decisions and action_items unchanged."
-    rule "Add an analyses array with one entry per action item."
-    user "Decisions: {decisions}\n\nAction items: {action_items}"
-  end
-
-  # Cross-validate: every action item from step 1 must be analyzed
-  validate("all action items analyzed") do |output, input|
-    output[:analyses].map { |a| a[:action_item_id] }.sort ==
-      input[:action_items].map { |a| a[:id] }.sort
-  end
-end
-
-class GenerateMeetingEmail < RubyLLM::Contract::Step::Base
-  input_type Hash
-
-  output_schema do
-    string :subject
-    string :body
-  end
-
-  prompt do
-    system "Write a professional follow-up email. List decisions, clear action items " \
-           "with owners and deadlines, and embed clarification questions for ambiguous items."
-    user "Decisions: {decisions}\nAction items: {action_items}\nAnalyses: {analyses}"
-  end
-
-  validate("subject must be concise") { |o| o[:subject].length <= 80 }
-  validate("body must not be empty") { |o| !o[:body].to_s.strip.empty? }
-end
-
-class MeetingFollowUpPipeline < RubyLLM::Contract::Pipeline::Base
-  step ExtractMeetingItems,  as: :extract
-  step AnalyzeAmbiguities,   as: :analyze
-  step GenerateMeetingEmail, as: :email
-end
-
-transcript = <<~TRANSCRIPT
-  Sarah: Let's go with the new pricing model starting Q3.
-  Tom: I'll update the billing system... at some point.
-  Sarah: Someone should notify the sales team about the changes.
-  Tom: Also, we need to migrate the legacy accounts. Maria, can you handle that?
-  Maria: Sure, I'll look into it.
-TRANSCRIPT
-
-puts "\n--- Full power: Pipeline + Schema + Invariants + Real LLM ---"
-result = MeetingFollowUpPipeline.run(transcript,
-                                     context: { model: "gpt-4.1-mini", temperature: 0.0 })
-
-puts "Pipeline status: #{result.status}"
-puts "Steps run:       #{result.step_results.length}"
-
-if result.ok?
-  puts "\nExtracted:  #{result.outputs_by_step[:extract][:decisions]&.length} decisions, " \
-       "#{result.outputs_by_step[:extract][:action_items]&.length} action items"
-
-  ambiguous = result.outputs_by_step[:analyze][:analyses]&.select { |a| a[:status] == "ambiguous" }
-  puts "Ambiguous:  #{ambiguous&.length} items need clarification"
-  puts "Email subj: #{result.outputs_by_step[:email][:subject]}"
-else
-  puts "FAILED at:  #{result.failed_step}"
-  failed = result.step_results.last[:result]
-  puts "Errors:     #{failed.validation_errors}"
-end
-
-# =============================================================================
-# SUMMARY
-#
-# 1. Configure ruby_llm (API keys)
-# 2. Set adapter: Adapters::RubyLLM.new
-# 3. Define steps exactly as before (types, prompt, contract)
-# 4. Run — real LLM call with full contract enforcement
-# 5. Override model/temperature/max_tokens per call via context
-# 6. Switch providers by changing the model name — everything else stays
-# 7. Combine ALL features in a single step: system, rules, sections,
-#    examples, hash input, 1-arity + 2-arity invariants
-# 8. Error handling — contract enforcement with real LLM responses
-# 9. Full power single step — AnalyzeTicket with every feature
-# 10. Full power pipeline — 3 steps, schemas, invariants, real LLM
-#
-# The step definition is always provider-agnostic.
-# Swap adapters between Test (specs) and RubyLLM (production).
-# =============================================================================