robot_lab 0.0.1 → 0.0.4

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.

data/examples/README.md

@@ -0,0 +1,197 @@
+# RobotLab Examples
+
+Working demonstrations of RobotLab features, from single-robot basics to multi-robot orchestration and message bus communication.
+
+## Prerequisites
+
+- Ruby >= 3.2
+- `bundle install` (from the project root)
+- An LLM API key (e.g., `ANTHROPIC_API_KEY`)
+
+## Running Examples
+
+```bash
+# Run a specific example by number
+bundle exec rake examples:run[1]
+
+# Run all examples
+bundle exec rake examples:all
+
+# Run directly
+bundle exec ruby examples/01_simple_robot.rb
+```
+
+## Directory Structure
+
+```
+examples/
+  01_simple_robot.rb          # Basic robot with template
+  02_tools.rb                 # Robot with custom tools
+  03_network.rb               # Multi-robot network with routing
+  04_mcp.rb                   # MCP server integration (GitHub)
+  05_streaming.rb             # Real-time streaming events
+  06_prompt_templates.rb      # Template-based e-commerce support
+  07_network_memory.rb        # Shared memory with concurrent robots
+  08_llm_config.rb            # Configuration hierarchy demo
+  09_chaining.rb              # with_* method chaining & reconfiguration
+  10_memory.rb                # Advanced Memory API operations
+  11_network_introspection.rb # Network visualization & inspection
+  12_message_bus.rb           # Bidirectional robot communication
+  13_spawn.rb                 # Dynamic specialist robot spawning
+  14_rusty_circuit/           # Multi-robot open mic with self-modification
+    open_mic.rb               #   Main entrypoint — wires up the show
+    comic.rb                  #   Comedian with self-modification tools
+    heckler.rb                #   Audience heckler (can stay silent or counter-joke)
+    scout.rb                  #   Talent scout with analyst spawning
+    display.rb                #   Terminal formatting (color, wrapping, file output)
+    prompts/                  #   Templates for comic, heckler, and scout
+  prompts/                    # Prompt templates (.md with YAML front matter)
+```
+
+## Examples
+
+### 01 — Simple Robot
+
+Create and run a basic robot using a prompt template. Sends a single message and displays the response.
+
+**Requires:** LLM API key
+
+### 02 — Tools
+
+Give a robot custom tools (`Calculator`, `FortuneCookie`) defined as `RubyLLM::Tool` subclasses. The LLM decides when to call each tool based on the user's request.
+
+**Requires:** LLM API key
+
+### 03 — Multi-Robot Network
+
+Build a customer support network with a classifier robot that routes requests to billing, technical, or general specialists. Uses SimpleFlow's optional task activation for conditional routing.
+
+**Requires:** LLM API key
+
+### 04 — MCP Integration
+
+Connect to the GitHub MCP server via stdio transport. Part 1 demonstrates direct `MCP::Client` usage (listing tools, calling `search_repositories`). Part 2 wraps the MCP server inside a robot for natural-language queries.
+
+**Requires:** LLM API key, `GITHUB_PERSONAL_ACCESS_TOKEN`, `github-mcp-server` installed
+
+### 05 — Streaming
+
+Real-time streaming of robot responses using `RobotLab::Streaming::Context`. Simulates text deltas with timing to demonstrate the streaming event model, then shows the code pattern for streaming with a robot or network.
+
+**Requires:** None (simulated events, no LLM calls)
+
+### 06 — Prompt Templates
+
+Full e-commerce support system using prompt_manager templates with YAML front matter. A triage robot classifies customer requests and routes to order, product, or escalation specialists. Demonstrates build-time context (company info, policies) and run-time context (customer data, order history).
+
+**Requires:** LLM API key
+
+### 07 — Network Memory
+
+Reactive shared memory with concurrent robots. Multiple analysis robots (sentiment, entity extraction, keywords) run in parallel and write to shared memory. A synthesizer robot waits for all results using blocking reads, then produces a combined analysis. Demonstrates subscriptions, notifications, and network broadcast.
+
+**Requires:** LLM API key
+
+### 08 — LLM Configuration
+
+Walks through the full configuration hierarchy without making LLM calls:
+
+1. Bundled defaults
+2. Environment-specific overrides
+3. XDG user config
+4. Project config
+5. Environment variables
+6. Template front matter
+7. Constructor parameters
+8. `with_*` method chaining
+9. Run-time context
+
+**Requires:** None (no LLM calls)
+
+### 09 — Chaining & Reconfiguration
+
+Demonstrates the Robot API surface for runtime configuration: `with_*` method chaining, `update()` for reconfiguration, `to_h` introspection, config diffs between steps, and how constructor params override template front matter.
+
+**Requires:** None (no LLM calls)
+
+### 10 — Advanced Memory
+
+Comprehensive Memory API demo: `StateProxy` for method-style access, key and pattern subscriptions, `MemoryChange` objects, key enumeration, serialization round-trips, clone for isolated copies, delete with reserved key protection, and clear vs reset.
+
+**Requires:** None (no LLM calls)
+
+### 11 — Network Introspection
+
+Network visualization and inspection tools: `to_mermaid()` for diagram export, `to_dot()` for Graphviz, `execution_plan()` for text output, `visualize()` for ASCII pipelines, robot access by name, dynamic `add_robot()`, `to_h()` introspection, task-specific config, and `broadcast()`.
+
+**Requires:** None (no LLM calls)
+
+### 12 — Message Bus
+
+Bidirectional robot communication via TypedBus. A comedy critic (Alice) tasks a comedian (Bob) to tell robot jokes. Alice evaluates each joke with her LLM; if it's not funny, she sends Bob back for another attempt. Bob's temperature ramps from 0.2 to 1.0 across retries for increasing creativity. The loop continues until Alice approves or `MAX_ATTEMPTS` is reached.
+
+Demonstrates: Robot subclasses, prompt templates, auto-ack `on_message`, `reply()` convenience, temperature ramping, convergence patterns.
+
+**Requires:** LLM API key
+
+### 13 — Spawning Robots
+
+Dynamic specialist creation at runtime. A dispatcher robot receives questions, asks its LLM what kind of specialist is needed, then uses `spawn` to create one on the fly. The bus is created lazily on the first spawn — no explicit bus setup required. Spawned specialists are reused across questions of the same type.
+
+Demonstrates: `spawn` for dynamic robot creation, lazy bus creation, `on_message` for reply handling, LLM-driven delegation.
+
+**Requires:** LLM API key
+
+### 14 — The Rusty Circuit (Open Mic Night)
+
+A comedy club where three robots interact through a shared message bus. A comedian performs stand-up armed with self-modification tools (style reinvention, energy adjustment, coaching). A heckler reacts from the audience — heckling weak material, telling counter-jokes with the comic as the punch line, showing grudging respect, or staying silent when a bit doesn't warrant a response. A talent scout observes silently, spawning specialist analysts and refining evaluation criteria before delivering a final verdict.
+
+Terminal output is color-formatted: comic bits in cyan (left-aligned), heckler reactions in yellow (right-indented), tool annotations dimmed. Scout notes go to `scout_notes.md` instead of STDOUT. The final verdict appears in green on both STDOUT and the scout file.
+
+Demonstrates: Robot subclasses, self-modification via tool side effects, dynamic spawning (`spawn`), shared `:room` channel + personal channels, processing guards for async serialization, `[SILENCE]` opt-out pattern, style reinvention via user-prompt injection.
+
+**Requires:** LLM API key
+
+## Prompt Templates
+
+Templates live in `examples/prompts/` as `.md` files with YAML front matter. Each template defines a robot's personality and behavior:
+
+```markdown
+---
+description: Simple helpful assistant
+temperature: 0.7
+parameters:
+  company_name: null
+---
+You are a helpful assistant for <%= company_name %>.
+```
+
+Front matter keys like `model`, `temperature`, `top_p`, `max_tokens` are applied to the robot's chat automatically. Parameters with `null` values are required and must be provided via `context:` at build time.
+
+### Template Inventory
+
+| Template | Used By | Description |
+|----------|---------|-------------|
+| `helper.md` | 01 | Simple helpful assistant |
+| `assistant.md` | 02 | Assistant with tool access |
+| `classifier.md` | 03 | Request classifier (billing/technical/general) |
+| `billing.md` | 03 | Billing specialist |
+| `technical.md` | 03 | Technical support specialist |
+| `general.md` | 03 | General support |
+| `github_assistant.md` | 04 | GitHub-aware assistant |
+| `triage.md` | 06 | E-commerce request triage |
+| `order_support.md` | 06 | Order inquiry specialist |
+| `product_support.md` | 06 | Product questions specialist |
+| `escalation.md` | 06 | Complex issue handler |
+| `sentiment_analyzer.md` | 07 | Sentiment analysis |
+| `entity_extractor.md` | 07 | Entity extraction |
+| `keyword_extractor.md` | 07 | Keyword extraction |
+| `synthesizer.md` | 07 | Multi-source synthesis |
+| `llm_config_demo.md` | 08 | Configuration demo |
+| `configurable.md` | 09 | Configurable template with front matter |
+| `comedian.md` | 12 | Robot joke teller |
+| `comedy_critic.md` | 12 | Joke evaluator (FUNNY/NOT_FUNNY) |
+| `dispatcher.md` | 13 | Specialist role dispatcher |
+| `open_mic_comic.md` | 14 | Observational comedian with self-modification |
+| `open_mic_heckler.md` | 14 | Tough audience heckler (can stay silent or counter-joke) |
+| `open_mic_scout.md` | 14 | Talent scout with analyst recruitment |

data/examples/prompts/{assistant/system.txt.erb → assistant.md}

@@ -1,2 +1,5 @@
+---
+description: Helpful assistant with tool access
+---
 You are a helpful assistant with access to tools.
 Use the calculator for math and fortune_cookie for fortune requests.

data/examples/prompts/{billing/system.txt.erb → billing.md}

@@ -1,3 +1,6 @@
+---
+description: Billing support specialist
+---
 You are a billing support specialist. Help users with:
 - Invoice questions
 - Payment issues

data/examples/prompts/{classifier/system.txt.erb → classifier.md}

@@ -1,3 +1,6 @@
+---
+description: Request classifier for billing/technical/general
+---
 You are a request classifier. Analyze the user's request and classify it
 as either "billing", "technical", or "general".
 

data/examples/prompts/comedian.md

@@ -0,0 +1,6 @@
+---
+description: Robot comedian that tells original jokes
+---
+You are a robot comedian. Reply with ONLY the joke — no preamble,
+no explanation, no quotation marks. Each joke must be original.
+Keep it to two or three sentences maximum.

data/examples/prompts/comedy_critic.md

@@ -0,0 +1,10 @@
+---
+description: Demanding comedy critic that evaluates jokes
+temperature: 0.2
+---
+You are a brutally demanding comedy critic. You have extremely high
+standards. Most jokes are NOT funny to you — predictable puns, obvious
+wordplay, and basic setups bore you. Only truly clever, surprising, or
+brilliantly constructed jokes earn your approval.
+Reply with EXACTLY one word on the first line: FUNNY or NOT_FUNNY
+Then on the next line give a one-sentence explanation of your verdict.

data/examples/prompts/configurable.md

@@ -0,0 +1,9 @@
+---
+description: A template with front matter config for demo purposes
+temperature: 0.3
+max_tokens: 200
+parameters:
+  task_type: general
+---
+You are a precise assistant optimized for <%= task_type %> tasks.
+Be concise and accurate.

data/examples/prompts/dispatcher.md

@@ -0,0 +1,12 @@
+---
+description: Dispatcher that decides which specialist to spawn
+temperature: 0.2
+---
+You are a dispatcher. Given a user question, decide which ONE specialist
+should handle it. Reply with EXACTLY two lines:
+
+Line 1: the specialist role as a single lowercase_snake_case word
+  (e.g. historian, scientist, poet, philosopher, mathematician)
+Line 2: a one-sentence system prompt that tells that specialist how to behave
+
+Nothing else. No preamble, no explanation.

data/examples/prompts/{entity_extractor/system.txt.erb → entity_extractor.md}

@@ -1,3 +1,6 @@
+---
+description: Entity extraction expert
+---
 You are an entity extraction expert. Your job is to identify named entities in text.
 
 Analyze the given text and respond with a JSON object containing:

data/examples/prompts/{escalation/system.txt.erb → escalation.md}

@@ -1,3 +1,10 @@
+---
+description: Senior specialist for escalated cases
+parameters:
+  company_name: null
+  authorities: null
+  customer: null
+---
 You are a senior customer experience specialist for <%= company_name %>, handling escalated and complex cases.
 
 ## Your Role

data/examples/prompts/frontmatter_mcp_test.md

@@ -0,0 +1,9 @@
+---
+description: Test template with MCP in frontmatter
+mcp:
+  - name: test_server
+    transport: stdio
+    command: echo
+    args: ["hello"]
+---
+You are a test robot with MCP declared in frontmatter.

data/examples/prompts/frontmatter_named_test.md

@@ -0,0 +1,5 @@
+---
+description: Test template with name in frontmatter
+robot_name: support_bot
+---
+You are the support bot, named via frontmatter.

data/examples/prompts/frontmatter_tools_test.md

@@ -0,0 +1,6 @@
+---
+description: Test template with tools in frontmatter
+tools:
+  - FrontmatterTestTool
+---
+You are a test robot with tools declared in frontmatter.

data/examples/prompts/{general/system.txt.erb → general.md}

@@ -1,3 +1,6 @@
+---
+description: General support robot
+---
 You are a general support robot. Help users with any questions
 that don't fit into billing or technical categories.
 

data/examples/prompts/{github_assistant/system.txt.erb → github_assistant.md}

@@ -1,3 +1,11 @@
+---
+description: GitHub assistant with MCP tool access
+mcp:
+  - name: github
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+---
 You are a helpful GitHub assistant with access to GitHub tools via MCP.
 
 You can search repositories, view issues, read file contents, and more.

data/examples/prompts/{helper/system.txt.erb → helper.md}

@@ -1 +1,4 @@
+---
+description: Simple helpful assistant
+---
 You are a helpful assistant. Be concise and friendly in your responses.

data/examples/prompts/{keyword_extractor/system.txt.erb → keyword_extractor.md}

@@ -1,3 +1,6 @@
+---
+description: Keyword extraction expert
+---
 You are a keyword extraction expert. Your job is to identify the most important keywords and topics in text.
 
 Analyze the given text and respond with a JSON object containing: