robot_lab 0.3.0 → 0.5.0

data/examples/30_ractor_network.rb

@@ -1,252 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 30: Ractor Network Scheduler
-#
-# Demonstrates Track 2 of RobotLab's Ractor parallelism: running a
-# multi-robot pipeline under RactorNetworkScheduler, which dispatches
-# independent tasks in parallel waves and respects depends_on ordering.
-#
-# Concepts covered:
-#   - Network.new(parallel_mode: :ractor) — opt the network into Ractor dispatch
-#   - Dependency waves                    — independent tasks run concurrently,
-#                                           dependent tasks wait for their wave
-#   - RobotSpec                           — frozen, Ractor-shareable robot descriptor
-#   - RactorNetworkScheduler              — direct use for testing / custom wiring
-#   - Result Hash                         — run_pipeline returns { name => result }
-#
-# Part 1 — simulated scheduler, no LLM traffic.
-#   Overrides execute_spec with a sleep-based stub so the wave ordering and
-#   timing characteristics are visible without real LLM calls.
-#
-# Part 2 — Network.new(parallel_mode: :ractor) API walkthrough.
-#   Shows how to configure the network and inspects the dependency graph.
-#   No run() call is made, so no LLM traffic either.
-#
-# Part 3 — live LLM run (opt-in via RUN_LIVE).
-#   Expected to fail against ruby_llm today; the rescue clauses explain why.
-#
-# Usage:
-#   bundle exec ruby examples/30_ractor_network.rb            # Parts 1 & 2
-#   RUN_LIVE=1 bundle exec ruby examples/30_ractor_network.rb # Parts 1, 2 & 3
-
-require_relative "common"
-require "robot_lab/ractor"
-
-banner "Ractor Network Scheduler"
-
-DIVIDER = ("─" * 54).freeze
-
-# =============================================================================
-# Part 1: Simulated scheduler — dependency waves and timing
-# =============================================================================
-#
-# Pipeline topology:
-#
-#   headline_finder  ─────────────────────────────────┐
-#                                                      ├──► report_writer
-#   background_brief ─────────────────────────────────┤
-#                                                      │
-#   fact_checker     ─────────────────────────────────┘
-#
-# Wave 1 — headline_finder, background_brief, fact_checker: parallel (none depend on each other)
-# Wave 2 — report_writer: sequential (depends on all three)
-#
-# Simulated latencies (seconds):
-LATENCIES = {
-  "headline_finder"   => 0.60,
-  "background_brief"  => 0.50,
-  "fact_checker"      => 0.40,
-  "report_writer"     => 0.70
-}.freeze
-#
-# Expected times:
-#   Parallel   — wave1 = max(0.60, 0.50, 0.40) = 0.60s
-#                wave2 = 0.70s
-#                total ≈ 1.30s
-#
-#   Sequential — 0.60 + 0.50 + 0.40 + 0.70 = 2.20s
-#
-#   Speedup    ≈ 1.7×
-
-section "Part 1: Simulated Parallel Run (no LLM traffic)"
-
-# SimulatedScheduler overrides execute_spec so that instead of
-# constructing a real Robot and calling the LLM, it just sleeps for
-# the robot's configured latency and returns a synthetic result string.
-# All dependency-ordering and wave-dispatch logic is inherited unchanged.
-class SimulatedScheduler < RobotLab::RactorNetworkScheduler
-  private
-
-  def execute_spec(spec, _message)
-    delay = LATENCIES[spec.name] || 0.30
-    sleep delay
-    "#{spec.name}: completed after #{delay}s".freeze
-  end
-end
-
-# Build RobotSpec objects directly.
-# (Normally Network#run_with_ractor_scheduler builds these from Task wrappers.)
-def make_spec(name, deps = :none)
-  spec = RobotLab::RobotSpec.new(
-    name:          name.freeze,
-    template:      nil,
-    system_prompt: "You are the #{name} robot.".freeze,
-    config_hash:   {}.freeze
-  )
-  { spec: spec, depends_on: deps }
-end
-
-specs_with_deps = [
-  make_spec("headline_finder"),
-  make_spec("background_brief"),
-  make_spec("fact_checker"),
-  make_spec("report_writer", ["headline_finder", "background_brief", "fact_checker"])
-]
-
-memory    = RobotLab::Memory.new
-scheduler = SimulatedScheduler.new(memory: memory)
-
-topic = "artificial intelligence regulation in 2025"
-
-t0      = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-results = scheduler.run_pipeline(specs_with_deps, message: topic)
-elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
-
-scheduler.shutdown
-
-sequential_total = LATENCIES.values.sum
-
-puts "  Pipeline topology:"
-puts "    Wave 1 (parallel): headline_finder · background_brief · fact_checker"
-puts "    Wave 2 (sequential): report_writer  ← waits for all three"
-puts
-
-puts "  Results (Hash { name => result_string }):"
-results.each { |name, val| puts "    \"#{name}\" => #{val.inspect}" }
-puts
-
-puts "  Wall time:         #{"%.3f" % elapsed}s"
-puts "  Sequential equiv:  #{"%.3f" % sequential_total}s  (#{LATENCIES.map { |n, d| "#{n}=#{d}" }.join(' + ')})"
-puts "  Speedup:           #{(sequential_total / elapsed).round(1)}×"
-puts
-
-# =============================================================================
-# Part 2: Network.new(parallel_mode: :ractor) API
-# =============================================================================
-
-section "Part 2: Network.new(parallel_mode: :ractor)"
-
-# When parallel_mode: :ractor is set on a Network, network.run(message:)
-# routes through RactorNetworkScheduler instead of SimpleFlow::Pipeline.
-# The default mode is :async (unchanged SimpleFlow behavior).
-
-network = RobotLab::Network.new(name: "research_pipeline", parallel_mode: :ractor) do
-  task :headline_finder,  RobotLab.build(name: "headline_finder",
-                                          system_prompt: "Find the 3 most relevant news headlines. Be concise.",
-                                          **llm_opts),
-       depends_on: :none
-
-  task :background_brief, RobotLab.build(name: "background_brief",
-                                          system_prompt: "Provide a 2-sentence background on the topic.",
-                                          **llm_opts),
-       depends_on: :none
-
-  task :fact_checker,     RobotLab.build(name: "fact_checker",
-                                          system_prompt: "List 3 verifiable facts about the topic.",
-                                          **llm_opts),
-       depends_on: :none
-
-  task :report_writer,    RobotLab.build(name: "report_writer",
-                                          system_prompt: "Synthesize the provided context into a 3-sentence report.",
-                                          **llm_opts),
-       depends_on: ["headline_finder", "background_brief", "fact_checker"]
-end
-
-puts "  network.name          => #{network.name.inspect}"
-puts "  network.parallel_mode => #{network.parallel_mode.inspect}"
-puts
-puts "  Dependency graph (from network.pipeline.step_dependencies):"
-
-network.pipeline.step_dependencies.each do |step, deps|
-  dep_str = deps.empty? ? "(entry point — Wave 1)" : "depends on: #{deps.join(', ')}"
-  puts "    :#{step.to_s.ljust(18)}  #{dep_str}"
-end
-puts
-puts "  When network.run(message: ...) is called:"
-puts "    • RactorNetworkScheduler is created with the network's memory"
-puts "    • Each task is converted to a frozen RobotSpec"
-puts "    • Wave 1 tasks are dispatched concurrently (Thread per task)"
-puts "    • Each Thread submits a RactorJob to the worker queue"
-puts "    • A Ractor worker pops the job, constructs a fresh Robot from the"
-puts "      spec, calls robot.run(message), and returns the frozen result"
-puts "    • Wave 2 begins once all Wave 1 results are available"
-puts "    • Return value is a Hash { robot_name => result_string }"
-puts
-
-# =============================================================================
-# Part 3: Live LLM run (opt-in via RUN_LIVE=1)
-# =============================================================================
-
-unless ENV["RUN_LIVE"]
-  section "Part 3: Live LLM Run"
-  puts "   Set RUN_LIVE=1 (with LM Studio running) to attempt the real pipeline."
-  puts "   Expected behavior: headline_finder, background_brief, and"
-  puts "   fact_checker run in parallel; report_writer follows."
-  puts
-  puts "   Heads-up: this is expected to fail today — see the rescue clauses"
-  puts "   below. ruby_llm keeps Procs in class-level state, which cannot"
-  puts "   cross a Ractor boundary. Part 1 shows the wave ordering that Part 3"
-  puts "   will exercise once ruby_llm is Ractor-safe."
-  puts
-  hr
-  puts "Example 30 complete."
-  exit 0
-end
-
-require_lms!
-
-section "Part 3: Live LLM Run (RUN_LIVE set)"
-
-puts "  Running 4-robot research pipeline on:"
-puts "  \"#{topic}\""
-puts
-puts "  Wave 1 (parallel): headline_finder · background_brief · fact_checker"
-puts "  Wave 2:            report_writer"
-puts
-
-t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-begin
-  result = network.run(message: topic)
-  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
-
-  puts "  Completed in #{"%.2f" % elapsed}s"
-  puts
-  puts "  Results:"
-  result.each do |name, text|
-    snippet = text.to_s.strip.lines.first.to_s.strip
-    puts "    [#{name}]  #{snippet[0..90]}#{snippet.length > 90 ? '…' : ''}"
-  end
-
-rescue Ractor::IsolationError, Ractor::Error => e
-  puts "  Ractor error: #{e.class}: #{e.message[0..100]}"
-  puts
-  puts "  ruby_llm is not yet Ractor-safe: it uses Procs in class"
-  puts "  definitions that cannot cross Ractor boundaries."
-  puts "  Track this at: https://github.com/crmne/ruby_llm"
-
-rescue RobotLab::Error => e
-  if e.message.include?("un-shareable Proc")
-    puts "  Live LLM runs require ruby_llm to be Ractor-safe."
-    puts "  ruby_llm stores Procs in class-level hooks that cannot cross"
-    puts "  Ractor boundaries. Part 1 (SimulatedScheduler) demonstrates wave"
-    puts "  ordering today; Part 3 will work once ruby_llm gains Ractor support."
-  else
-    puts "  RobotLab::Error: #{e.message}"
-  end
-end
-
-puts
-hr
-puts "Example 30 complete."

data/examples/31_launch_assessment.rb

@@ -1,246 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 31: Product Launch Assessment — 6 Parallel Analysts, Cap of 4
-#
-# Six specialist robots evaluate a product launch simultaneously.
-# max_concurrent_robots: 4 ensures at most 4 LLM API calls are in-flight
-# at once. Robots 5 and 6 queue behind the Async::Semaphore and start as
-# soon as any of the first 4 finishes — providing natural back-pressure
-# without slowing the pipeline more than necessary.
-#
-# Architecture:
-#
-#   ┌──────────────────────────────────────────────────────────────────────┐
-#   │          PARALLEL ANALYSIS PHASE  (max_concurrent_robots: 4)        │
-#   │                                                                      │
-#   │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │
-#   │  │  Market  │  │  Compet. │  │   Tech   │  │   Risk   │  slots 1-4 │
-#   │  │ Analyst  │  │ Analyst  │  │ Reviewer │  │ Assessor │            │
-#   │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘            │
-#   │       │             │             │             │                    │
-#   │    start          start         start         start                 │
-#   │                                                                      │
-#   │  ┌──────────┐  ┌──────────┐                                         │
-#   │  │Financial │  │  Legal   │  queued — start when a slot opens       │
-#   │  │ Reviewer │  │ Reviewer │                                         │
-#   │  └────┬─────┘  └────┬─────┘                                         │
-#   │       │             │                                                │
-#   │    (deferred)    (deferred)                                          │
-#   │                                                                      │
-#   │  ┌─────────────────────────────────────────────────────────────┐    │
-#   │  │                  SHARED MEMORY                               │    │
-#   │  │  :market  :competitive  :tech  :risk  :financial  :legal     │    │
-#   │  └─────────────────────────────────────────────────────────────┘    │
-#   │                              │                                       │
-#   │                              ▼                                       │
-#   │  ┌─────────────────────────────────────────────────────────────┐    │
-#   │  │                 Launch Director                               │    │
-#   │  │   Blocks on reactive memory until all 6 findings arrive,     │    │
-#   │  │   then issues a GO / NO-GO recommendation.                   │    │
-#   │  └─────────────────────────────────────────────────────────────┘    │
-#   └──────────────────────────────────────────────────────────────────────┘
-#
-# Key config:
-#   RunConfig.new(max_concurrent_robots: 4)
-#
-# Usage:
-#   ruby examples/31_launch_assessment.rb
-
-require_relative "common"
-
-# ── AnalystRobot ────────────────────────────────────────────────────────────────
-#
-# Runs its LLM call, writes the verdict to shared memory, and logs a timing line
-# so you can see when the semaphore releases robots 5 and 6.
-
-class AnalystRobot < RobotLab::Robot
-  attr_reader :memory_key
-  attr_writer :shared_memory
-
-  def initialize(name:, memory_key:, role:)
-    super(
-      name:          name,
-      **llm_opts,
-      system_prompt: "You are a #{role}. " \
-                     "Review the product brief in 2-3 crisp sentences from your area of expertise. " \
-                     "Close with a one-word verdict: READY or NOT-READY."
-    )
-    @memory_key = memory_key
-  end
-
-  def call(result)
-    brief   = extract_brief(result)
-    started = Time.now
-    puts "  [#{name}] started at +#{"%.1f" % (started - $run_start)}s"
-
-    verdict = run(brief).reply.strip
-
-    elapsed = "%.1f" % (Time.now - started)
-    puts "  [#{name}] finished in #{elapsed}s — #{verdict.split.last(2).join(" ")}"
-
-    if @shared_memory
-      @shared_memory.current_writer = name
-      @shared_memory.set(@memory_key, verdict)
-    end
-
-    result.with_context(name.to_sym, verdict).continue(verdict)
-  end
-
-  private
-
-  def extract_brief(result)
-    case result.value
-    when Hash                  then result.value[:message].to_s
-    when RobotLab::RobotResult then result.value.reply.to_s
-    else                            result.value.to_s
-    end
-  end
-end
-
-# ── LaunchDirector ──────────────────────────────────────────────────────────────
-#
-# Waits for all 6 findings via reactive memory, then issues the final call.
-# SimpleFlow guarantees the six analyst tasks are done before this task runs,
-# so the memory.get is effectively a non-blocking read by the time we arrive here.
-
-class LaunchDirector < RobotLab::Robot
-  attr_writer :shared_memory
-
-  FINDING_KEYS = %i[market competitive tech risk financial legal].freeze
-
-  def call(result)
-    puts "  [#{name}] reading all findings from shared memory..."
-    findings = collect_findings
-
-    prompt = <<~PROMPT
-      Six specialist analysts have reviewed our product launch readiness.
-      Based on their findings, issue a final GO or NO-GO recommendation
-      in 3-5 sentences. Be direct and specific about the key deciding factors.
-
-      Market analysis:      #{findings[:market]      || "(not received)"}
-      Competitive analysis: #{findings[:competitive] || "(not received)"}
-      Technical review:     #{findings[:tech]        || "(not received)"}
-      Risk assessment:      #{findings[:risk]        || "(not received)"}
-      Financial review:     #{findings[:financial]   || "(not received)"}
-      Legal review:         #{findings[:legal]       || "(not received)"}
-
-      Begin your response with "GO -" or "NO-GO -".
-    PROMPT
-
-    recommendation = run(prompt).reply.strip
-    @shared_memory.set(:recommendation, recommendation)
-    puts "  [#{name}] recommendation ready"
-
-    result.with_context(:recommendation, recommendation).continue(recommendation)
-  end
-
-  private
-
-  # Memory#get(wait:) RAISES RobotLab::AwaitTimeout on expiry — it never
-  # returns a :timeout sentinel. Rescue it and re-read without wait:, which
-  # never blocks and omits keys that were never written, so a stalled analyst
-  # degrades the recommendation instead of killing the director.
-  def collect_findings
-    @shared_memory.get(*FINDING_KEYS, wait: 120)
-  rescue RobotLab::AwaitTimeout => e
-    puts "  [#{name}] WARNING: #{e.message}"
-    partial = @shared_memory.get(*FINDING_KEYS)
-    missing = FINDING_KEYS - partial.keys
-    puts "  [#{name}] Proceeding without: #{missing.join(', ')}" if missing.any?
-    partial
-  end
-end
-
-# ── Product Brief ───────────────────────────────────────────────────────────────
-
-PRODUCT_BRIEF = <<~BRIEF
-  Product: "Orion" — an AI-powered project management tool that auto-generates
-  sprint plans from Jira backlogs, detects scope creep in real-time, and integrates
-  with GitHub and Slack via webhooks. SaaS pricing: $25/seat/month, 14-day free trial.
-  Target: mid-size engineering teams (20-200 developers). Launch date: 6 weeks out.
-  Beta: 12 paying customers, 94% satisfaction, 0 critical bugs open. SOC 2 Type I
-  certification in progress, expected within 30 days.
-BRIEF
-
-# ── Build the six analysts ───────────────────────────────────────────────────────
-
-ANALYSTS = [
-  { name: "market_analyst",      key: :market,      role: "market opportunity analyst"             },
-  { name: "competitive_analyst", key: :competitive, role: "competitive intelligence analyst"       },
-  { name: "tech_reviewer",       key: :tech,        role: "technical readiness and quality reviewer" },
-  { name: "risk_assessor",       key: :risk,        role: "product risk assessment specialist"    },
-  { name: "financial_reviewer",  key: :financial,   role: "financial viability and pricing analyst" },
-  { name: "legal_reviewer",      key: :legal,       role: "legal, compliance, and IP reviewer"    },
-].freeze
-
-analyst_robots = ANALYSTS.map do |spec|
-  AnalystRobot.new(name: spec[:name], memory_key: spec[:key], role: spec[:role])
-end
-
-director = LaunchDirector.new(
-  name:          "launch_director",
-  **llm_opts,
-  system_prompt: "You are the VP of Product making the final launch call."
-)
-
-# ── Network — note the concurrency cap ──────────────────────────────────────────
-
-config = RobotLab::RunConfig.new(max_concurrent_robots: 4)
-
-analyst_names = analyst_robots.map { |r| r.name.to_sym }
-
-network = RobotLab.create_network(name: "launch_assessment", config: config) do
-  analyst_robots.each do |robot|
-    task robot.name.to_sym, robot, depends_on: :none
-  end
-
-  task :launch_director, director, depends_on: analyst_names
-end
-
-# Assign shared memory so each robot can write to it directly
-shared_memory = network.memory
-(analyst_robots + [director]).each { |r| r.shared_memory = shared_memory }
-
-# Subscribe for a memory-level audit trail
-analyst_robots.each do |robot|
-  network.memory.subscribe(robot.memory_key) do |change|
-    puts "  [memory] :#{change.key} written by #{change.writer}"
-  end
-end
-
-# ── Run ─────────────────────────────────────────────────────────────────────────
-
-banner "Product Launch Assessment"
-puts "  6 specialist analysts in parallel, max_concurrent_robots: 4"
-puts
-puts "Pipeline:"
-puts network.visualize
-puts
-puts "Concurrency config: #{config.inspect}"
-puts
-puts "Product brief:"
-puts PRODUCT_BRIEF.strip.gsub(/^/, "  ")
-puts
-section "Running — Analysts 5 and 6 Queue Until a Semaphore Slot Opens"
-
-$run_start = Time.now
-result     = network.run(message: PRODUCT_BRIEF)
-elapsed    = "%.1f" % (Time.now - $run_start)
-
-puts
-hr
-puts "All analysts complete. Total wall time: #{elapsed}s"
-hr
-
-section "Launch Director Recommendation"
-puts network.memory[:recommendation]
-puts
-section "Individual Analyst Verdicts"
-analyst_robots.each do |robot|
-  label  = robot.name.gsub("_", " ").upcase
-  finding = network.memory.get(robot.memory_key).to_s
-  puts "#{label}"
-  puts finding
-  puts
-end

data/examples/32_newsletter_reader.rb

@@ -1,193 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Example 32: Newsletter Issue Retriever
-#
-# NOTE: this is a plain utility script, not a RobotLab demo — it uses no part
-# of the library. It lives here as the content feeder for other experiments.
-# Read examples 01-31 for library capabilities.
-#
-# Fetches all unprocessed issues from multiple Ruby newsletters via RSS
-# and saves each as a Markdown file in a Markdown clippings folder.
-#
-# - Processes oldest unprocessed issue first (across all feeds)
-# - Filename: <newsletter-name>_YYYYMMDD.md
-# - Includes YAML frontmatter with source URL (compatible with Clippings workflow)
-# - Tracks processed issue URLs in ~/.robot_lab/newsletter_processed.yaml
-#
-# Usage:
-#   ruby examples/32_newsletter_reader.rb
-#   CLIPPINGS_DIR=~/Notes/Clippings ruby examples/32_newsletter_reader.rb
-
-require "net/http"
-require "open3"
-require "time"
-require "uri"
-require "yaml"
-require "fileutils"
-require "rexml/document"
-require "rexml/xpath"
-
-NEWSLETTER_RSS_URLS = [
-  "https://rss.beehiiv.com/feeds/MTJunJRFxo.xml",       # Ruby AI News
-  "https://cprss.s3.amazonaws.com/rubyweekly.com.xml"   # Ruby Weekly
-].freeze
-
-CLIPPINGS_DIR        = File.expand_path(ENV.fetch("CLIPPINGS_DIR", "~/Documents/Clippings"))
-PROCESSED_STATE_FILE = File.join(Dir.home, ".robot_lab", "newsletter_processed.yaml")
-
-# Tracks which newsletter issue URLs have been saved.
-class ProcessedIssues
-  def initialize(path: PROCESSED_STATE_FILE)
-    @path = path
-    @urls = load_urls
-  end
-
-  def processed?(url)
-    @urls.include?(url)
-  end
-
-  def mark_processed(url)
-    @urls << url
-    FileUtils.mkdir_p(File.dirname(@path))
-    File.write(@path, YAML.dump(@urls.uniq))
-  end
-
-  def count = @urls.size
-
-  private
-
-  def load_urls
-    return [] unless File.exist?(@path)
-    Array(YAML.safe_load(File.read(@path)) || [])
-  end
-end
-
-# Fetches a single RSS feed URL and returns its items (unsorted).
-# Each item: { title:, url:, pub_date:, published_at:, html:, channel_name: }
-def fetch_rss_items(url)
-  uri      = URI(url)
-  response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |h| h.get(uri.request_uri) }
-  raise "HTTP #{response.code}: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
-
-  doc  = REXML::Document.new(response.body)
-  ns   = { "content" => "http://purl.org/rss/1.0/modules/content/" }
-
-  channel_title = REXML::XPath.first(doc, "//channel/title")&.text&.strip || "newsletter"
-
-  REXML::XPath.match(doc, "//channel/item").filter_map do |item|
-    item_url = REXML::XPath.first(item, "link")&.text&.strip
-    title    = REXML::XPath.first(item, "title")&.text&.strip
-    pub_date = REXML::XPath.first(item, "pubDate")&.text&.strip
-    html     = REXML::XPath.first(item, "content:encoded", ns)&.text ||
-               REXML::XPath.first(item, "description")&.text || ""
-
-    next unless item_url && title && pub_date
-
-    {
-      title:        title,
-      url:          item_url,
-      pub_date:     pub_date,
-      published_at: Time.parse(pub_date),
-      html:         html,
-      channel_name: channel_title
-    }
-  end
-end
-
-# Fetches all configured RSS feeds and returns items sorted oldest-first.
-def fetch_all_rss_items
-  NEWSLETTER_RSS_URLS.flat_map do |feed_url|
-    print "  #{feed_url}... "
-    items = fetch_rss_items(feed_url)
-    puts "#{items.size} issues"
-    items
-  end.sort_by { |item| item[:published_at] }
-end
-
-# Converts HTML to Markdown via html2markdown CLI, stripping UTM params.
-def html_to_markdown(html)
-  md, = Open3.capture3(
-    "html2markdown",
-    stdin_data: html
-  )
-  md.gsub(/\]\(([^)]+)\)/) do
-    url = $1
-    if url.include?("?")
-      base, query = url.split("?", 2)
-      kept = query.split("&").reject { |p| p.start_with?("utm_") }
-      "](#{kept.empty? ? base : "#{base}?#{kept.join("&")}"})"
-    else
-      "](#{url})"
-    end
-  end
-end
-
-# Builds the output filename: <newsletter-name>_YYYYMMDD.md
-def output_filename(channel_name, published_at)
-  safe_name = channel_name.downcase.gsub(/[^a-z0-9]+/, "_").delete_suffix("_")
-  date_str  = published_at.strftime("%Y%m%d")
-  "#{safe_name}_#{date_str}.md"
-end
-
-# Wraps markdown content in YAML frontmatter compatible with the Clippings workflow.
-def wrap_with_frontmatter(title:, url:, pub_date:, body:)
-  date = Time.parse(pub_date).strftime("%Y-%m-%d")
-  <<~MD
-    ---
-    source: #{url}
-    title: "#{title.gsub('"', '\\"')}"
-    date: #{date}
-    ---
-
-    # #{title}
-
-    #{body.strip}
-  MD
-end
-
-# ── Main ──────────────────────────────────────────────────────────────────────
-
-puts "=" * 60
-puts "Example 32: Newsletter Issue Retriever"
-puts "=" * 60
-puts
-
-FileUtils.mkdir_p(CLIPPINGS_DIR)
-state = ProcessedIssues.new
-
-puts "Fetching #{NEWSLETTER_RSS_URLS.size} RSS feeds..."
-all_items = fetch_all_rss_items
-pending   = all_items.reject { |item| state.processed?(item[:url]) }
-puts "#{all_items.size} total issues found across all feeds."
-
-if pending.empty?
-  puts "All issues already saved. Nothing to do."
-  exit
-end
-
-puts "#{pending.size} unprocessed (#{state.count} already done). Saving oldest-first."
-puts
-
-pending.each_with_index do |item, idx|
-  filename = output_filename(item[:channel_name], item[:published_at])
-  filepath = File.join(CLIPPINGS_DIR, filename)
-
-  print "[#{idx + 1}/#{pending.size}] #{item[:title]} (#{item[:published_at].strftime("%Y-%m-%d")})... "
-
-  body     = html_to_markdown(item[:html])
-  content  = wrap_with_frontmatter(
-    title:    item[:title],
-    url:      item[:url],
-    pub_date: item[:pub_date],
-    body:     body
-  )
-
-  File.write(filepath, content)
-  state.mark_processed(item[:url])
-
-  puts "saved → #{filename}"
-end
-
-puts
-puts "Done. #{pending.size} issue(s) saved to #{CLIPPINGS_DIR}"