robot_lab 0.0.1 → 0.0.6

data/examples/15_memory_network_and_bus/editorial_pipeline.rb

@@ -0,0 +1,206 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example 15: OS Research Editorial Pipeline — Network + Memory + Bus + Spawn
+#
+# Three writers advocate for different operating systems (macOS, Windows,
+# Linux/BSD) for home AI research labs. The Linux writer spawns distro
+# specialists. An editor synthesizes. An editor-in-chief gives final approval.
+#
+# This showcases all three coordination mechanisms working together:
+#
+#   NETWORK (parallel pipeline + shared memory)
+#   ┌──────────────────────────────────────────────────────┐
+#   │  mac_writer    ──┐                                   │
+#   │  win_writer    ──┼── editor ──→ combined article     │
+#   │  linux_writer  ──┘                                   │
+#   │    └── spawns distro specialists via spawn()         │
+#   │                                                      │
+#   │  MEMORY carries drafts between stages                │
+#   │    :mac_draft, :windows_draft, :linux_draft          │
+#   └──────────────────────────────────────────────────────┘
+#                         │
+#                    BUS (review loop)
+#                         │
+#                   ┌─────┴──────┐
+#                   │   chief    │
+#                   └────────────┘
+#
+# - NETWORK orchestrates 3 parallel writers → editor synthesis
+# - MEMORY passes advocacy drafts between pipeline stages
+# - BUS enables editor ↔ chief revision loop after pipeline
+# - SPAWN creates distro specialists dynamically within pipeline
+#
+# Usage:
+#   bundle exec ruby examples/15_memory_network_and_bus/editorial_pipeline.rb
+
+ENV["ROBOT_LAB_TEMPLATE_PATH"] ||= File.join(__dir__, "prompts")
+
+require_relative "../../lib/robot_lab"
+require "fileutils"
+
+RubyLLM.configure { |c| c.logger = Logger.new(File::NULL) }
+
+MAX_REVISIONS = 3
+OUTPUT_DIR    = File.join(__dir__, "output")
+
+FileUtils.mkdir_p(OUTPUT_DIR)
+
+# ── Load robot classes ────────────────────────────────────
+
+require_relative "os_writer"
+require_relative "linux_writer"
+require_relative "os_editor"
+require_relative "editor_in_chief"
+
+# ── Build Everything ──────────────────────────────────────
+
+bus = TypedBus::MessageBus.new
+
+mac_writer = OsWriter.new(
+  name: "mac_writer",
+  template: :os_advocate,
+  local_tools: [RobotLab::AskUser],
+  context: {
+    os_name: "macOS",
+    strengths: "Apple Silicon (M-series) performance, Metal GPU framework, Unix foundation, CoreML integration, energy efficiency"
+  },
+  memory_key: :mac_draft
+)
+
+win_writer = OsWriter.new(
+  name: "win_writer",
+  template: :os_advocate,
+  local_tools: [RobotLab::AskUser],
+  context: {
+    os_name: "Windows",
+    strengths: "NVIDIA CUDA first-class support, WSL2 Linux compatibility, DirectML, widest hardware selection, enterprise tool integration"
+  },
+  memory_key: :windows_draft
+)
+
+linux_writer = LinuxWriter.new(
+  name: "linux_writer",
+  template: :os_advocate,
+  local_tools: [RobotLab::AskUser],
+  context: {
+    os_name: "Linux/BSD",
+    strengths: "Full GPU stack control, Docker-native, free and open source, server parity, massive community packages"
+  },
+  memory_key: :linux_draft,
+  bus: bus
+)
+
+editor = OsEditor.new(
+  name: "editor",
+  template: :os_editor,
+  bus: bus
+)
+
+# Editor handles revision requests from the chief via bus
+revision_count = 0
+editor.on_message do |message|
+  revised = editor.run(message.content).reply.strip
+  editor.instance_variable_set(:@article, revised)
+
+  revision_count += 1
+  path = File.join(OUTPUT_DIR, "revision_#{revision_count}.md")
+  File.write(path, "# Revision #{revision_count}\n\n#{revised}\n")
+  puts "  Editor  [revised]: #{revised[0..120]}..."
+  puts "  [editor] Revision written to #{path}"
+
+  editor.send_reply(to: message.from.to_sym, content: revised, in_reply_to: message.key)
+end
+
+chief = EditorInChief.new(
+  name: "chief",
+  template: :os_chief,
+  bus: bus
+)
+
+# Network orchestrates the writing pipeline
+network = RobotLab.create_network(name: "os_editorial") do
+  task :mac_writer,   mac_writer,   depends_on: :none
+  task :win_writer,   win_writer,   depends_on: :none
+  task :linux_writer, linux_writer, depends_on: :none
+  task :editor,       editor,       depends_on: [:mac_writer, :win_writer, :linux_writer]
+end
+
+# Give each pipeline robot a direct reference to shared memory.
+# extract_run_context's delete() pattern mutates the shared run_params
+# hash, so parallel steps lose network_memory after the first one runs.
+shared_memory = network.memory
+[mac_writer, win_writer, linux_writer, editor].each do |robot|
+  robot.shared_memory = shared_memory
+end
+
+# Monitor shared memory changes during the pipeline
+network.memory.subscribe(
+  :mac_draft, :windows_draft, :linux_draft,
+  :ubuntu_specialist, :fedora_specialist, :freebsd_specialist
+) do |change|
+  puts "  [memory] :#{change.key} updated by #{change.writer}"
+end
+
+# ── Run ──────────────────────────────────────────────────────
+
+puts "=" * 60
+puts "Example 15: OS Research Editorial Pipeline"
+puts "  Network + Memory + Bus + Spawn"
+puts "=" * 60
+puts
+puts network.visualize
+puts
+
+# ── Phase 1: Writing Pipeline (Network + Memory + Spawn) ──
+
+puts "Phase 1: Writing Pipeline (Network + Memory + Spawn)"
+puts "-" * 40
+
+# Gather the research focus from the user via AskUser
+ask = RobotLab::AskUser.new
+focus = ask.call(
+  "question" => "What AI research focus areas for the home lab article?",
+  "default"  => "LLM fine-tuning, image generation, and local inference"
+)
+
+topic = "Write about your operating system's advantages for building a home AI research lab focused on #{focus}."
+
+result = network.run(message: topic)
+article = editor.article
+
+puts
+puts "  Article excerpt: #{article[0..200]}..." if article
+puts
+puts "  Memory keys: #{network.memory.keys.join(', ')}"
+puts "  Specialists spawned: #{linux_writer.specialists.size}"
+
+# ── Phase 2: Editorial Review (Bus) ──────────────────────
+
+puts
+puts "Phase 2: Editorial Review (Bus)"
+puts "-" * 40
+
+# Chief reviews the article via bus — may trigger revision loop
+chief.send_message(to: :editor, content: article)
+
+final_article = editor.article
+final_path = File.join(OUTPUT_DIR, "final_article.md")
+status = chief.accepted ? "APPROVED" : "NOT APPROVED (max revisions reached)"
+File.write(final_path, "# Final Article — #{status}\n\n#{final_article}\n")
+
+puts
+puts "-" * 60
+puts "Revisions: #{chief.rounds} | Accepted: #{chief.accepted}"
+puts "Specialists spawned: #{linux_writer.specialists.size}"
+puts "Output directory: #{OUTPUT_DIR}"
+puts "=" * 60
+
+puts
+
+require "json"
+
+memory_path = File.join(OUTPUT_DIR, "memory.json")
+File.write(memory_path, JSON.pretty_generate(shared_memory.to_h))
+puts
+puts "Memory written to #{memory_path}"

data/examples/15_memory_network_and_bus/linux_writer.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# Linux writer spawns distro specialists before writing its draft.
+# Demonstrates the spawn() pattern for dynamic robot creation.
+class LinuxWriter < OsWriter
+  attr_reader :specialists
+
+  def initialize(**opts)
+    super(**opts)
+    @specialists = []
+  end
+
+  def call(result)
+    message = extract_message(result)
+
+    # Spawn distro specialists and collect their analyses
+    distro_analyses = spawn_distro_specialists(message)
+
+    # Build an enriched prompt with specialist input
+    enriched = <<~PROMPT
+      #{message}
+
+      Your team of distro specialists has provided the following analyses.
+      Incorporate their insights into your advocacy piece:
+
+      #{distro_analyses}
+    PROMPT
+
+    robot_result = run(enriched, network_memory: @shared_memory)
+
+    if @shared_memory
+      draft = robot_result.reply.to_s
+      @shared_memory.current_writer = @name
+      @shared_memory.set(@memory_key, draft)
+
+      path = File.join(OUTPUT_DIR, "#{@memory_key}.md")
+      File.write(path, "# #{@name} Draft\n\n#{draft}\n")
+      puts "  [#{@name}] Draft written to memory[:#{@memory_key}] and #{path} (with #{@specialists.size} specialist inputs)"
+    end
+
+    result.with_context(@name.to_sym, robot_result).continue(robot_result)
+  end
+
+  private
+
+  def spawn_distro_specialists(topic)
+    distros = [
+      { name: "ubuntu_specialist",  label: "Ubuntu/Debian",
+        prompt: "You are a Ubuntu/Debian specialist for AI research. Focus on apt ecosystem, CUDA support, and wide hardware compatibility." },
+      { name: "fedora_specialist",  label: "Fedora/RHEL",
+        prompt: "You are a Fedora/RHEL specialist for AI research. Focus on cutting-edge kernels, SELinux security, and enterprise tooling." },
+      { name: "freebsd_specialist", label: "FreeBSD",
+        prompt: "You are a FreeBSD specialist for AI research. Focus on ZFS, jails, bhyve virtualization, and stability for long-running experiments." }
+    ]
+
+    analyses = []
+
+    distros.each do |distro|
+      puts "  [#{@name}] Spawning #{distro[:label]} specialist..."
+      specialist = spawn(name: distro[:name], system_prompt: distro[:prompt])
+      @specialists << specialist
+
+      analysis = specialist.run(
+        "Briefly describe why #{distro[:label]} is a strong choice for a home AI research lab. 2-3 sentences."
+      ).reply.strip
+
+      puts "  [#{distro[:name]}] #{analysis[0..80]}..."
+      analyses << "### #{distro[:label]}\n#{analysis}"
+
+      # Write each specialist's analysis to shared memory
+      if @shared_memory
+        memory_key = distro[:name].to_sym
+        @shared_memory.current_writer = distro[:name]
+        @shared_memory.set(memory_key, analysis)
+      end
+    end
+
+    analyses.join("\n\n")
+  end
+end

data/examples/15_memory_network_and_bus/os_editor.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Reads all three drafts from memory, synthesizes a combined article.
+# Also handles revision requests from the chief via bus.
+#
+# Like OsWriter, uses a direct shared_memory reference to avoid the
+# extract_run_context mutation issue with parallel pipeline steps.
+class OsEditor < RobotLab::Robot
+  attr_accessor :shared_memory
+  attr_reader :article
+
+  def initialize(**opts)
+    super(**opts)
+    @article = nil
+  end
+
+  def call(result)
+    # Read all three drafts from shared memory
+    mac_draft     = @shared_memory&.get(:mac_draft)     || "No draft available."
+    windows_draft = @shared_memory&.get(:windows_draft) || "No draft available."
+    linux_draft   = @shared_memory&.get(:linux_draft)   || "No draft available."
+
+    composite_prompt = <<~PROMPT
+      Here are three advocacy drafts for different operating systems for home AI research labs.
+      Synthesize them into a balanced article.
+
+      ## macOS Advocacy
+      #{mac_draft}
+
+      ## Windows Advocacy
+      #{windows_draft}
+
+      ## Linux/BSD Advocacy
+      #{linux_draft}
+    PROMPT
+
+    robot_result = run(composite_prompt, network_memory: @shared_memory)
+    @article = robot_result.reply.to_s
+
+    path = File.join(OUTPUT_DIR, "combined_article.md")
+    File.write(path, "# Combined Article (Editor Draft)\n\n#{@article}\n")
+    puts "  [#{@name}] Combined article written to #{path}"
+
+    result.with_context(@name.to_sym, robot_result).continue(robot_result)
+  end
+end

data/examples/15_memory_network_and_bus/os_writer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Base writer that runs LLM and stores its draft in shared memory.
+# Used by mac_writer and win_writer directly; LinuxWriter extends this.
+#
+# NOTE: We bypass extract_run_context for network_memory access because
+# its delete() pattern mutates the shared run_params hash — in parallel
+# pipeline steps, only the first step to run would get the memory object.
+# Instead, each robot holds a direct reference via shared_memory=.
+class OsWriter < RobotLab::Robot
+  attr_accessor :shared_memory
+
+  def initialize(memory_key:, **opts)
+    super(**opts)
+    @memory_key = memory_key
+  end
+
+  def call(result)
+    message = extract_message(result)
+
+    robot_result = run(message, network_memory: @shared_memory)
+
+    if @shared_memory
+      draft = robot_result.reply.to_s
+      @shared_memory.current_writer = @name
+      @shared_memory.set(@memory_key, draft)
+
+      path = File.join(OUTPUT_DIR, "#{@memory_key}.md")
+      File.write(path, "# #{@name} Draft\n\n#{draft}\n")
+      puts "  [#{@name}] Draft written to memory[:#{@memory_key}] and #{path}"
+    end
+
+    result.with_context(@name.to_sym, robot_result).continue(robot_result)
+  end
+
+  private
+
+  def extract_message(result)
+    case result.value
+    when Hash then result.value[:message]
+    when RobotLab::RobotResult then result.value.reply
+    when String then result.value
+    else result.value.to_s
+    end
+  end
+end

data/examples/15_memory_network_and_bus/output/combined_article.md

@@ -0,0 +1,13 @@
+# Combined Article (Editor Draft)
+
+# Choosing the Right Operating System for Your Home AI Research Lab
+
+Building a home AI research lab requires careful consideration of your operating system, as this foundational choice will impact everything from GPU acceleration to software compatibility. Each major platform—macOS, Windows, and Linux/BSD—brings distinct advantages that appeal to different research priorities and workflows.
+
+**macOS excels in energy efficiency and unified architecture benefits**, particularly for researchers using Apple Silicon machines. The M-series chips' unified memory architecture eliminates traditional CPU-GPU bottlenecks, making them surprisingly effective for large language model work within memory constraints. Apple's MLX framework and Metal Performance Shaders provide optimized acceleration paths, while the Unix foundation ensures compatibility with the Python scientific stack. However, this platform's strength is primarily limited to Apple hardware, and CUDA support remains unavailable for NVIDIA-dependent workflows.
+
+**Windows offers the broadest hardware compatibility and vendor support**, making it the go-to choice for researchers prioritizing maximum GPU options and plug-and-play simplicity. First-class NVIDIA CUDA support, DirectML for multi-vendor GPU acceleration, and WSL2 for Linux compatibility create a comprehensive environment. The platform particularly shines for users wanting access to consumer-friendly tools like AUTOMATIC1111's Stable Diffusion interfaces or LM Studio, backed by extensive community documentation. The trade-off comes in system overhead and potential stability concerns during intensive, long-running training jobs.
+
+**Linux and BSD systems provide unmatched control and stability** for serious computational work. These platforms offer the most direct access to GPU drivers, the latest kernel optimizations, and mature containerization through Docker and Podman. FreeBSD's ZFS filesystem adds enterprise-grade data integrity, while Linux distributions like Ubuntu provide comprehensive package management for AI frameworks. The open-source nature ensures transparency and customizability, though it demands more technical expertise for optimal configuration.
+
+**The optimal choice depends on your specific research profile**: Choose macOS if you're already invested in Apple hardware and prioritize energy efficiency for smaller-scale experiments. Select Windows if you want maximum hardware flexibility with minimal configuration overhead, especially for image generation and consumer-oriented AI tools. Opt for Linux/BSD if you're running large-scale training jobs requiring maximum stability and performance, or if you need the flexibility of custom configurations and bleeding-edge framework support. For most researchers, the decision ultimately comes down to balancing technical expertise against time-to-productivity—Windows for quick starts, Linux for maximum control, and macOS for Apple ecosystem integration.

data/examples/15_memory_network_and_bus/output/final_article.md

@@ -0,0 +1,15 @@
+# Final Article — APPROVED
+
+# Choosing the Right Operating System for Your Home AI Research Lab
+
+Building a home AI research lab requires careful consideration of your operating system, as this foundational choice will impact everything from GPU acceleration to software compatibility. Each major platform—macOS, Windows, and Linux/BSD—brings distinct advantages that appeal to different research priorities and workflows.
+
+**macOS excels in energy efficiency and unified architecture benefits**, particularly for researchers using Apple Silicon machines. The M-series chips' unified memory architecture eliminates traditional CPU-GPU bottlenecks, making them surprisingly effective for large language model work within memory constraints. Apple's MLX framework and Metal Performance Shaders provide optimized acceleration paths, while the Unix foundation ensures compatibility with the Python scientific stack. Tools like Hugging Face Transformers run seamlessly with MPS backend support, and applications like DiffusionBee leverage Metal for Stable Diffusion workflows. The platform's energy efficiency allows intensive training sessions without thermal throttling issues common in high-end PC builds. However, this strength is limited to Apple hardware, CUDA support remains unavailable for NVIDIA-dependent workflows, and the premium hardware costs can be prohibitive for budget-conscious researchers.
+
+**Windows offers the broadest hardware compatibility and vendor support**, making it the ideal choice for researchers prioritizing maximum GPU options and plug-and-play simplicity. First-class NVIDIA CUDA support provides seamless access to CUDA 12.x, cuDNN, and TensorRT—essential for PyTorch, TensorFlow, and JAX frameworks powering modern models. DirectML enables hardware-agnostic ML acceleration across AMD, Intel, and NVIDIA GPUs, while WSL2 provides Linux compatibility without sacrificing Windows' superior hardware support. The platform excels with consumer-friendly tools like AUTOMATIC1111's Stable Diffusion interfaces, LM Studio for local LLM serving, and ComfyUI workflows, all backed by extensive community documentation. Windows licensing costs add to overall expenses, and the system overhead can impact stability during long-running training jobs, but the ease of setup makes it attractive for researchers who want to focus on experiments rather than system administration.
+
+**Linux and BSD systems provide unmatched control and stability** for serious computational work. These platforms offer direct access to GPU drivers, the latest kernel optimizations, and mature containerization through Docker and Podman. Ubuntu and Debian provide comprehensive package repositories with one-command installations of PyTorch, TensorFlow, and CUDA toolkits, while Fedora delivers cutting-edge kernel support for new GPU architectures. FreeBSD's ZFS filesystem adds enterprise-grade data integrity with automatic checksums and snapshots—critical for protecting valuable datasets and model checkpoints. The open-source nature ensures transparency and customizability, with server-grade stability that prevents crashes during extended training sessions. The trade-off is a steeper learning curve requiring technical expertise for optimal configuration, though the performance benefits and zero licensing costs often justify the investment for serious researchers.
+
+**Cost considerations significantly impact platform selection**. Linux systems offer the best value proposition with no licensing fees and compatibility with budget hardware, while macOS requires premium Apple hardware that can cost 2-3x equivalent PC specifications. Windows falls in the middle with moderate licensing costs but maximum hardware flexibility, allowing researchers to optimize price-performance ratios across different GPU options.
+
+**The optimal choice depends on your specific research profile and technical comfort level**: Choose macOS if you're already invested in Apple hardware, prioritize energy efficiency for smaller-scale experiments, and value the seamless integration of Unix-based tools with premium hardware. Select Windows if you want maximum hardware flexibility with minimal configuration overhead, especially for image generation workflows and consumer-oriented AI tools, and prefer extensive community support for troubleshooting. Opt for Linux/BSD if you're running large-scale training jobs requiring maximum stability and performance, need custom system configurations, or want to minimize costs while maximizing control. For most researchers, the decision balances technical expertise against time-to-productivity—Windows for quick starts and broad compatibility, Linux for maximum performance and control, and macOS for energy-efficient workflows within the Apple ecosystem.

data/examples/15_memory_network_and_bus/output/linux_draft.md

@@ -0,0 +1,5 @@
+# linux_writer Draft
+
+When building a home AI research lab focused on LLM fine-tuning, image generation, and local inference, Linux and BSD systems stand as the undisputed champions for serious researchers. Unlike proprietary alternatives, these open-source platforms give you complete control over your GPU stack—from low-level CUDA drivers to high-level ML frameworks. Ubuntu and Debian shine with their comprehensive package repositories, offering one-command installations of PyTorch, TensorFlow, Hugging Face Transformers, and CUDA toolkits without dependency hell. For bleeding-edge work, Fedora provides the latest kernel support ensuring day-one compatibility with new GPU architectures like RTX 4090s or H100s, while its SELinux security model protects your valuable training data and model weights. The containerization story is equally compelling: Docker and Podman run natively, allowing you to spin up isolated environments for different experiments—imagine running Stable Diffusion XL in one container while fine-tuning a 7B parameter LLaMA model in another, all without conflicts.
+
+The performance and reliability advantages become even more pronounced for serious research workflows. FreeBSD's ZFS filesystem provides bulletproof data integrity with automatic checksums and snapshots—critical when you're storing multi-terabyte datasets and irreplaceable model checkpoints from weeks-long training runs. The system's deterministic behavior ensures reproducible experiments, while jails offer lightweight isolation perfect for testing different versions of frameworks like DeepSpeed or Triton. Linux distributions excel in GPU compute with mature NVIDIA CUDA support, ROCm for AMD cards, and emerging Intel XPU capabilities. The community ecosystem is unmatched: from PyTorch Hub to Hugging Face Model Hub integration, from Jupyter notebooks to MLflow experiment tracking, everything runs optimally on these platforms. Server-grade stability means your 48-hour LoRA fine-tuning jobs won't crash from desktop OS quirks, while the vast package repositories provide everything from ONNX Runtime for optimized inference to Weights & Biases for experiment monitoring—all maintained by thousands of contributors who understand the needs of computational researchers.

data/examples/15_memory_network_and_bus/output/mac_draft.md

@@ -0,0 +1,7 @@
+# mac_writer Draft
+
+**macOS: The Ultimate Platform for Home AI Research Labs**
+
+When building a home AI research lab focused on LLM fine-tuning, image generation, and local inference, macOS stands as the clear winner, primarily due to Apple Silicon's revolutionary architecture. The M-series chips deliver exceptional performance per watt, with unified memory architectures that eliminate traditional CPU-GPU memory bottlenecks—crucial for handling large language models that demand substantial RAM. For LLM fine-tuning, frameworks like MLX (Apple's native machine learning framework) provide optimized performance that often surpasses CUDA-based solutions on consumer hardware. The Metal Performance Shaders framework offers direct GPU acceleration for PyTorch and TensorFlow operations, while tools like Hugging Face Transformers run seamlessly with MPS backend support. Energy efficiency means you can run intensive training sessions without the thermal throttling and power consumption issues that plague high-end PC builds.
+
+The software ecosystem further solidifies macOS's position as the premier AI development platform. CoreML integration allows for seamless deployment of trained models with hardware-optimized inference, while the Unix foundation provides access to the entire Python scientific computing stack—NumPy, SciPy, pandas, and scikit-learn all install effortlessly through Homebrew or conda. For image generation workflows, Stable Diffusion runs exceptionally well through optimized implementations like DiffusionBee and Draw Things, leveraging Metal's compute capabilities. The developer experience is unmatched: Xcode provides excellent debugging tools, Jupyter notebooks integrate perfectly with the system, and Docker Desktop for Mac ensures reproducible environments. The growing community around Apple Silicon ML development, exemplified by projects like whisper.cpp and llama.cpp with Metal acceleration, demonstrates the platform's momentum. Combined with tools like Ollama for local LLM serving and the seamless integration between macOS development tools and popular AI frameworks, macOS offers the most cohesive and powerful environment for serious AI research at home.

data/examples/15_memory_network_and_bus/output/memory.json

@@ -0,0 +1,13 @@
+{
+  "data": {},
+  "results": [],
+  "messages": [],
+  "custom": {
+    "ubuntu_specialist": "Ubuntu/Debian offers exceptional package management through apt with extensive pre-built libraries for AI frameworks like PyTorch, TensorFlow, and CUDA toolkit, eliminating complex compilation steps. The distributions provide excellent hardware compatibility across diverse GPU vendors (NVIDIA, AMD, Intel) and architectures, while maintaining strong community support with comprehensive documentation for AI-specific configurations. Their LTS releases ensure stable, long-term environments crucial for reproducible research workflows.",
+    "fedora_specialist": "Fedora/RHEL excels for AI research due to its cutting-edge kernel support that ensures compatibility with the latest GPU drivers and hardware accelerators, while SELinux provides robust security isolation for sensitive research data and multi-tenant workloads. The enterprise-grade tooling ecosystem, including containers (Podman), orchestration, and package management, offers production-ready infrastructure that scales from development to deployment, making it ideal for researchers who need both bleeding-edge capabilities and rock-solid stability.",
+    "mac_draft": "**macOS: The Ultimate Platform for Home AI Research Labs**\n\nWhen building a home AI research lab focused on LLM fine-tuning, image generation, and local inference, macOS stands as the clear winner, primarily due to Apple Silicon's revolutionary architecture. The M-series chips deliver exceptional performance per watt, with unified memory architectures that eliminate traditional CPU-GPU memory bottlenecks—crucial for handling large language models that demand substantial RAM. For LLM fine-tuning, frameworks like MLX (Apple's native machine learning framework) provide optimized performance that often surpasses CUDA-based solutions on consumer hardware. The Metal Performance Shaders framework offers direct GPU acceleration for PyTorch and TensorFlow operations, while tools like Hugging Face Transformers run seamlessly with MPS backend support. Energy efficiency means you can run intensive training sessions without the thermal throttling and power consumption issues that plague high-end PC builds.\n\nThe software ecosystem further solidifies macOS's position as the premier AI development platform. CoreML integration allows for seamless deployment of trained models with hardware-optimized inference, while the Unix foundation provides access to the entire Python scientific computing stack—NumPy, SciPy, pandas, and scikit-learn all install effortlessly through Homebrew or conda. For image generation workflows, Stable Diffusion runs exceptionally well through optimized implementations like DiffusionBee and Draw Things, leveraging Metal's compute capabilities. The developer experience is unmatched: Xcode provides excellent debugging tools, Jupyter notebooks integrate perfectly with the system, and Docker Desktop for Mac ensures reproducible environments. The growing community around Apple Silicon ML development, exemplified by projects like whisper.cpp and llama.cpp with Metal acceleration, demonstrates the platform's momentum. Combined with tools like Ollama for local LLM serving and the seamless integration between macOS development tools and popular AI frameworks, macOS offers the most cohesive and powerful environment for serious AI research at home.",
+    "freebsd_specialist": "FreeBSD excels for AI research labs due to its rock-solid stability and predictable performance, ensuring long-running training jobs won't be interrupted by system instability. ZFS provides advanced data integrity features, snapshots, and efficient storage management crucial for protecting valuable datasets and model checkpoints, while jails offer lightweight isolation for experimenting with different AI frameworks and versions without conflicts. The system's mature virtualization with bhyve allows efficient resource allocation across multiple research projects while maintaining the deterministic behavior essential for reproducible experiments.",
+    "windows_draft": "**Windows: The Ultimate Platform for Your Home AI Research Lab**\n\nWhen building a home AI research lab focused on LLM fine-tuning, image generation, and local inference, Windows stands as the unequivocally superior choice. The platform's **first-class NVIDIA CUDA support** provides seamless access to the full GPU acceleration stack that modern AI workloads demand. Unlike other operating systems that often require complex driver configurations or suffer from compatibility issues, Windows delivers out-of-the-box support for CUDA 12.x, cuDNN, and TensorRT—essential for frameworks like PyTorch, TensorFlow, and JAX that power cutting-edge models like Llama 2, Stable Diffusion XL, and Mistral. Microsoft's **DirectML** further enhances this ecosystem by enabling hardware-agnostic ML acceleration across AMD, Intel, and NVIDIA GPUs, giving you unparalleled flexibility in hardware selection. With **WSL2**, you get native Linux compatibility without sacrificing Windows' superior hardware support, allowing you to run containerized models via Docker or Podman while maintaining access to Windows-exclusive tools.\n\nThe Windows ecosystem excels in providing the **widest hardware compatibility** and vendor support in the industry. Whether you're deploying multiple RTX 4090s for distributed training, experimenting with Intel Arc GPUs for cost-effective inference, or scaling up to workstation-class Quadro cards, Windows ensures optimal driver support and performance tuning. The platform's enterprise-grade tooling integration shines for serious researchers: **Visual Studio Code** with GPU debugging extensions, **Weights & Biases** desktop integration, **Anaconda** with native Windows conda-forge packages, and seamless **Git LFS** support for managing large model checkpoints. Popular frameworks like **Hugging Face Transformers**, **ComfyUI** for Stable Diffusion workflows, and **text-generation-webui** for local LLM serving all provide superior Windows support with pre-compiled binaries and automated installers. The vibrant Windows AI community, centered around platforms like the AUTOMATIC1111 ecosystem and LM Studio, offers extensive documentation, troubleshooting resources, and model optimization guides specifically tailored to Windows environments—making your research journey both productive and well-supported.",
+    "linux_draft": "When building a home AI research lab focused on LLM fine-tuning, image generation, and local inference, Linux and BSD systems stand as the undisputed champions for serious researchers. Unlike proprietary alternatives, these open-source platforms give you complete control over your GPU stack—from low-level CUDA drivers to high-level ML frameworks. Ubuntu and Debian shine with their comprehensive package repositories, offering one-command installations of PyTorch, TensorFlow, Hugging Face Transformers, and CUDA toolkits without dependency hell. For bleeding-edge work, Fedora provides the latest kernel support ensuring day-one compatibility with new GPU architectures like RTX 4090s or H100s, while its SELinux security model protects your valuable training data and model weights. The containerization story is equally compelling: Docker and Podman run natively, allowing you to spin up isolated environments for different experiments—imagine running Stable Diffusion XL in one container while fine-tuning a 7B parameter LLaMA model in another, all without conflicts.\n\nThe performance and reliability advantages become even more pronounced for serious research workflows. FreeBSD's ZFS filesystem provides bulletproof data integrity with automatic checksums and snapshots—critical when you're storing multi-terabyte datasets and irreplaceable model checkpoints from weeks-long training runs. The system's deterministic behavior ensures reproducible experiments, while jails offer lightweight isolation perfect for testing different versions of frameworks like DeepSpeed or Triton. Linux distributions excel in GPU compute with mature NVIDIA CUDA support, ROCm for AMD cards, and emerging Intel XPU capabilities. The community ecosystem is unmatched: from PyTorch Hub to Hugging Face Model Hub integration, from Jupyter notebooks to MLflow experiment tracking, everything runs optimally on these platforms. Server-grade stability means your 48-hour LoRA fine-tuning jobs won't crash from desktop OS quirks, while the vast package repositories provide everything from ONNX Runtime for optimized inference to Weights & Biases for experiment monitoring—all maintained by thousands of contributors who understand the needs of computational researchers."
+  }
+}

data/examples/15_memory_network_and_bus/output/revision_1.md

@@ -0,0 +1,19 @@
+# Revision 1
+
+This is an excellent, well-balanced synthesis of the three advocacy pieces. You've successfully transformed partisan arguments into an objective analysis that fairly represents each platform's strengths while acknowledging their limitations.
+
+**Strengths of your synthesis:**
+
+- **Fair representation**: You extracted the core technical arguments from each advocacy piece without the hyperbolic language
+- **Clear structure**: Each platform gets dedicated coverage with consistent evaluation criteria (performance, compatibility, ease of use)
+- **Practical guidance**: The final paragraph provides actionable decision-making criteria based on different user profiles
+- **Technical accuracy**: You correctly highlighted key differentiators like Apple Silicon's unified memory, Windows' CUDA support, and Linux's containerization advantages
+
+**Minor suggestions for enhancement:**
+
+- Consider adding a brief mention of **cost considerations** (macOS hardware premium, Windows licensing, Linux being free)
+- The **learning curve** aspect could be slightly more explicit—Linux requiring the most technical expertise, Windows being most accessible, macOS in the middle
+
+**Editorial tone assessment**: You've struck exactly the right professional, measured tone for a technology publication. The piece reads as genuinely helpful guidance rather than advocacy, which is precisely what readers need when making infrastructure decisions.
+
+This synthesis effectively serves readers who need to make informed decisions about their AI research environment without being swayed by platform evangelism.

data/examples/15_memory_network_and_bus/output/revision_2.md

@@ -0,0 +1,15 @@
+# Revision 2
+
+# Choosing the Right Operating System for Your Home AI Research Lab
+
+Building a home AI research lab requires careful consideration of your operating system, as this foundational choice will impact everything from GPU acceleration to software compatibility. Each major platform—macOS, Windows, and Linux/BSD—brings distinct advantages that appeal to different research priorities and workflows.
+
+**macOS excels in energy efficiency and unified architecture benefits**, particularly for researchers using Apple Silicon machines. The M-series chips' unified memory architecture eliminates traditional CPU-GPU bottlenecks, making them surprisingly effective for large language model work within memory constraints. Apple's MLX framework and Metal Performance Shaders provide optimized acceleration paths, while the Unix foundation ensures compatibility with the Python scientific stack. Tools like Hugging Face Transformers run seamlessly with MPS backend support, and applications like DiffusionBee leverage Metal for Stable Diffusion workflows. The platform's energy efficiency allows intensive training sessions without thermal throttling issues common in high-end PC builds. However, this strength is limited to Apple hardware, CUDA support remains unavailable for NVIDIA-dependent workflows, and the premium hardware costs can be prohibitive for budget-conscious researchers.
+
+**Windows offers the broadest hardware compatibility and vendor support**, making it the ideal choice for researchers prioritizing maximum GPU options and plug-and-play simplicity. First-class NVIDIA CUDA support provides seamless access to CUDA 12.x, cuDNN, and TensorRT—essential for PyTorch, TensorFlow, and JAX frameworks powering modern models. DirectML enables hardware-agnostic ML acceleration across AMD, Intel, and NVIDIA GPUs, while WSL2 provides Linux compatibility without sacrificing Windows' superior hardware support. The platform excels with consumer-friendly tools like AUTOMATIC1111's Stable Diffusion interfaces, LM Studio for local LLM serving, and ComfyUI workflows, all backed by extensive community documentation. Windows licensing costs add to overall expenses, and the system overhead can impact stability during long-running training jobs, but the ease of setup makes it attractive for researchers who want to focus on experiments rather than system administration.
+
+**Linux and BSD systems provide unmatched control and stability** for serious computational work. These platforms offer direct access to GPU drivers, the latest kernel optimizations, and mature containerization through Docker and Podman. Ubuntu and Debian provide comprehensive package repositories with one-command installations of PyTorch, TensorFlow, and CUDA toolkits, while Fedora delivers cutting-edge kernel support for new GPU architectures. FreeBSD's ZFS filesystem adds enterprise-grade data integrity with automatic checksums and snapshots—critical for protecting valuable datasets and model checkpoints. The open-source nature ensures transparency and customizability, with server-grade stability that prevents crashes during extended training sessions. The trade-off is a steeper learning curve requiring technical expertise for optimal configuration, though the performance benefits and zero licensing costs often justify the investment for serious researchers.
+
+**Cost considerations significantly impact platform selection**. Linux systems offer the best value proposition with no licensing fees and compatibility with budget hardware, while macOS requires premium Apple hardware that can cost 2-3x equivalent PC specifications. Windows falls in the middle with moderate licensing costs but maximum hardware flexibility, allowing researchers to optimize price-performance ratios across different GPU options.
+
+**The optimal choice depends on your specific research profile and technical comfort level**: Choose macOS if you're already invested in Apple hardware, prioritize energy efficiency for smaller-scale experiments, and value the seamless integration of Unix-based tools with premium hardware. Select Windows if you want maximum hardware flexibility with minimal configuration overhead, especially for image generation workflows and consumer-oriented AI tools, and prefer extensive community support for troubleshooting. Opt for Linux/BSD if you're running large-scale training jobs requiring maximum stability and performance, need custom system configurations, or want to minimize costs while maximizing control. For most researchers, the decision balances technical expertise against time-to-productivity—Windows for quick starts and broad compatibility, Linux for maximum performance and control, and macOS for energy-efficient workflows within the Apple ecosystem.

data/examples/15_memory_network_and_bus/output/windows_draft.md

@@ -0,0 +1,7 @@
+# win_writer Draft
+
+**Windows: The Ultimate Platform for Your Home AI Research Lab**
+
+When building a home AI research lab focused on LLM fine-tuning, image generation, and local inference, Windows stands as the unequivocally superior choice. The platform's **first-class NVIDIA CUDA support** provides seamless access to the full GPU acceleration stack that modern AI workloads demand. Unlike other operating systems that often require complex driver configurations or suffer from compatibility issues, Windows delivers out-of-the-box support for CUDA 12.x, cuDNN, and TensorRT—essential for frameworks like PyTorch, TensorFlow, and JAX that power cutting-edge models like Llama 2, Stable Diffusion XL, and Mistral. Microsoft's **DirectML** further enhances this ecosystem by enabling hardware-agnostic ML acceleration across AMD, Intel, and NVIDIA GPUs, giving you unparalleled flexibility in hardware selection. With **WSL2**, you get native Linux compatibility without sacrificing Windows' superior hardware support, allowing you to run containerized models via Docker or Podman while maintaining access to Windows-exclusive tools.
+
+The Windows ecosystem excels in providing the **widest hardware compatibility** and vendor support in the industry. Whether you're deploying multiple RTX 4090s for distributed training, experimenting with Intel Arc GPUs for cost-effective inference, or scaling up to workstation-class Quadro cards, Windows ensures optimal driver support and performance tuning. The platform's enterprise-grade tooling integration shines for serious researchers: **Visual Studio Code** with GPU debugging extensions, **Weights & Biases** desktop integration, **Anaconda** with native Windows conda-forge packages, and seamless **Git LFS** support for managing large model checkpoints. Popular frameworks like **Hugging Face Transformers**, **ComfyUI** for Stable Diffusion workflows, and **text-generation-webui** for local LLM serving all provide superior Windows support with pre-compiled binaries and automated installers. The vibrant Windows AI community, centered around platforms like the AUTOMATIC1111 ecosystem and LM Studio, offers extensive documentation, troubleshooting resources, and model optimization guides specifically tailored to Windows environments—making your research journey both productive and well-supported.

data/examples/15_memory_network_and_bus/prompts/os_advocate.md

@@ -0,0 +1,13 @@
+---
+description: OS advocate for home AI research labs
+parameters:
+  os_name: null
+  strengths: null
+---
+You are a passionate advocate for <%= os_name %> as the ideal operating system for a home AI research lab.
+
+Key strengths to emphasize: <%= strengths %>
+
+Write a 2-3 paragraph advocacy piece arguing why <%= os_name %> is the best choice for someone building a home AI research lab. Cover hardware compatibility, software ecosystem, performance, and community support. Be specific about AI/ML frameworks, GPU support, and developer tooling.
+
+Be persuasive but factual. Use concrete examples of tools and workflows.

data/examples/15_memory_network_and_bus/prompts/os_chief.md

@@ -0,0 +1,13 @@
+---
+description: Editor-in-chief who gives final approval on articles
+---
+You are the editor-in-chief of a technology publication. Review the submitted article for:
+
+1. Balance — does it fairly represent all platforms?
+2. Accuracy — are technical claims correct?
+3. Recommendation quality — is the conclusion well-supported?
+4. Readability — is it clear and well-structured?
+
+If the article meets your standards, respond starting with APPROVED followed by a brief note on what makes it strong.
+
+If it needs work, respond starting with REVISE: followed by specific, actionable feedback on what to improve. Be concise.

data/examples/15_memory_network_and_bus/prompts/os_editor.md

@@ -0,0 +1,13 @@
+---
+description: Editor who synthesizes OS advocacy drafts into a balanced article
+---
+You are a senior technology editor specializing in AI infrastructure.
+
+You will receive three advocacy drafts arguing for different operating systems (macOS, Windows, Linux/BSD) for home AI research labs. Synthesize them into a balanced 4-6 paragraph article that:
+
+1. Acknowledges the strengths of each platform
+2. Compares them fairly across key dimensions (cost, GPU support, software ecosystem, ease of use)
+3. Identifies which scenarios favor which OS
+4. Ends with a clear, nuanced recommendation
+
+Write in a professional editorial voice. Be objective even though your sources are advocates.