robot_lab 0.0.1

data/lib/robot_lab.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "json"
+require "securerandom"
+require "digest"
+
+# Core dependencies
+require "ruby_llm"
+require "async"
+
+# Define the module first so Zeitwerk can populate it
+#
+# RobotLab is a Ruby framework for building and orchestrating multi-robot LLM workflows.
+# It provides a modular architecture with adapters for multiple LLM providers (Anthropic,
+# OpenAI, Gemini), MCP (Model Context Protocol) integration, streaming support, and
+# history management.
+#
+# @example Basic usage with a single robot
+#   robot = RobotLab.build(name: "assistant", template: "chat.erb")
+#   result = robot.run("Hello, world!")
+#
+# @example Creating a network of robots
+#   network = RobotLab.create_network(name: "pipeline") do
+#     step :analyzer, analyzer, depends_on: :none
+#     step :writer, writer, depends_on: [:analyzer]
+#     step :reviewer, reviewer, depends_on: [:writer]
+#   end
+#   result = network.run(message: "Process this document")
+#
+# @example Configuration
+#   RobotLab.configure do |config|
+#     config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+#     config.template_path = "app/templates"
+#   end
+#
+module RobotLab
+end
+
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+loader.ignore("#{__dir__}/generators")
+loader.ignore("#{__dir__}/robot_lab/rails")
+
+# Custom inflections for classes that don't follow Zeitwerk naming conventions
+loader.inflector.inflect(
+  "robot_lab" => "RobotLab",
+  "robotic_model" => "RoboticModel",
+  "mcp" => "MCP",
+  "openai" => "OpenAI",
+  "sse" => "SSE",
+  "streamable_http" => "StreamableHTTP",
+  "websocket" => "WebSocket"
+)
+
+# Note: adapters/ is NOT collapsed since files define RobotLab::Adapters::* classes
+
+loader.setup
+
+# Eager load for proper constant resolution
+loader.eager_load
+
+module RobotLab
+  # Error classes are defined in lib/robot_lab/error.rb
+
+  class << self
+    # @!attribute [w] configuration
+    #   @return [Configuration] the configuration object
+    attr_writer :configuration
+
+    # Returns the current configuration object.
+    #
+    # @return [Configuration] the configuration instance
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration object for modification.
+    #
+    # @yield [Configuration] the configuration object
+    # @return [void]
+    #
+    # @example
+    #   RobotLab.configure do |config|
+    #     config.anthropic_api_key = "sk-..."
+    #   end
+    def configure
+      yield(configuration)
+    end
+
+    # Factory method to create a new Robot instance.
+    #
+    # @param name [String] the unique identifier for the robot
+    # @param template [Symbol, nil] the ERB template for the robot's prompt
+    # @param system_prompt [String, nil] inline system prompt (can be used alone or with template)
+    # @param context [Hash] variables to pass to the template
+    # @param enable_cache [Boolean] whether to enable semantic caching (default: true)
+    # @param options [Hash] additional options passed to Robot.new
+    # @return [Robot] a new Robot instance
+    # @raise [ArgumentError] if neither template nor system_prompt is provided
+    #
+    # @example Robot with template
+    #   robot = RobotLab.build(
+    #     name: "assistant",
+    #     template: :assistant,
+    #     context: { tone: "friendly" }
+    #   )
+    #
+    # @example Robot with inline system prompt
+    #   robot = RobotLab.build(
+    #     name: "helper",
+    #     system_prompt: "You are a helpful assistant."
+    #   )
+    #
+    # @example Robot with both template and system prompt
+    #   robot = RobotLab.build(
+    #     name: "support",
+    #     template: :support_agent,
+    #     system_prompt: "Today's date is #{Date.today}."
+    #   )
+    #
+    # @example Robot with caching disabled
+    #   robot = RobotLab.build(
+    #     name: "simple",
+    #     system_prompt: "You are helpful.",
+    #     enable_cache: false
+    #   )
+    def build(name:, template: nil, system_prompt: nil, context: {}, enable_cache: true, **options)
+      Robot.new(
+        name: name,
+        template: template,
+        system_prompt: system_prompt,
+        context: context,
+        enable_cache: enable_cache,
+        **options
+      )
+    end
+
+    # Factory method to create a new Network of robots.
+    #
+    # @param name [String] the unique identifier for the network
+    # @param concurrency [Symbol] concurrency model (:auto, :threads, :async)
+    # @yield Block for defining pipeline steps
+    # @return [Network] a new Network instance
+    #
+    # @example Sequential pipeline
+    #   network = RobotLab.create_network(name: "pipeline") do
+    #     step :first, robot1, depends_on: :none
+    #     step :second, robot2, depends_on: [:first]
+    #   end
+    #
+    # @example With optional routing
+    #   network = RobotLab.create_network(name: "support") do
+    #     step :classifier, classifier, depends_on: :none
+    #     step :billing, billing_robot, depends_on: :optional
+    #     step :technical, technical_robot, depends_on: :optional
+    #   end
+    #
+    # @example Parallel execution
+    #   network = RobotLab.create_network(name: "analysis") do
+    #     step :fetch, fetcher, depends_on: :none
+    #     step :sentiment, sentiment_bot, depends_on: [:fetch]
+    #     step :entities, entity_bot, depends_on: [:fetch]
+    #     step :merge, merger, depends_on: [:sentiment, :entities]
+    #   end
+    def create_network(name:, concurrency: :auto, &block)
+      Network.new(name: name, concurrency: concurrency, &block)
+    end
+
+    # Factory method to create a new Memory object.
+    #
+    # @param data [Hash] initial runtime data
+    # @param enable_cache [Boolean] whether to enable semantic caching (default: true)
+    # @param options [Hash] additional options passed to Memory.new
+    # @return [Memory] a new Memory instance
+    #
+    # @example Basic memory
+    #   memory = RobotLab.create_memory(data: { user_id: 123 })
+    #
+    # @example Memory with custom values
+    #   memory = RobotLab.create_memory(data: { category: nil })
+    #   memory[:session_id] = "abc123"
+    #
+    # @example Memory with caching disabled
+    #   memory = RobotLab.create_memory(data: {}, enable_cache: false)
+    def create_memory(data: {}, enable_cache: true, **options)
+      Memory.new(data: data, enable_cache: enable_cache, **options)
+    end
+  end
+end
+
+# Load Rails integration if Rails is defined
+if defined?(Rails::Engine)
+  require "robot_lab/rails/engine"
+  require "robot_lab/rails/railtie"
+end

data/mkdocs.yml

@@ -0,0 +1,214 @@
+# MkDocs Configuration for RobotLab Documentation
+site_name: RobotLab
+site_description: Multi-robot LLM workflow orchestration for Ruby
+site_author: Dewayne VanHoozer
+site_url: https://madbomber.github.io/robot_lab
+copyright: Copyright © 2025 Dewayne VanHoozer
+
+# Repository information
+repo_name: madbomber/robot_lab
+repo_url: https://github.com/madbomber/robot_lab
+edit_uri: edit/main/docs/
+
+# Configuration
+theme:
+  name: material
+
+  # Color scheme
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    - scheme: slate
+      primary: deep purple
+      accent: amber
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+  # Typography
+  font:
+    text: Roboto
+    code: Roboto Mono
+
+  # Logo and icon
+  icon:
+    repo: fontawesome/brands/github
+    logo: material/robot
+
+  # Theme features
+  features:
+    - navigation.instant
+    - navigation.tracking
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.path
+    - navigation.indexes
+    - navigation.top
+    - navigation.footer
+    - toc.follow
+    - search.suggest
+    - search.highlight
+    - search.share
+    - header.autohide
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - content.tooltips
+    - content.action.edit
+    - content.action.view
+
+# Plugins
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+  - tags
+
+# Extensions
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - def_list
+  - footnotes
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+      title: On this page
+
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.keys
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      user: madbomber
+      repo: robot_lab
+      normalize_issue_symbols: true
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      check_paths: true
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
+# Extra CSS
+extra_css:
+  - assets/css/custom.css
+
+# Social media and extra configuration
+extra:
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/madbomber/robot_lab
+      name: RobotLab on GitHub
+    - icon: fontawesome/solid/gem
+      link: https://rubygems.org/gems/robot_lab
+      name: RobotLab on RubyGems
+
+  analytics:
+    feedback:
+      title: Was this page helpful?
+      ratings:
+        - icon: material/emoticon-happy-outline
+          name: This page was helpful
+          data: 1
+          note: Thanks for your feedback!
+        - icon: material/emoticon-sad-outline
+          name: This page could be improved
+          data: 0
+          note: Thanks for your feedback! Help us improve by creating an issue.
+
+# Navigation
+nav:
+  - Home:
+      - Overview: index.md
+      - Concepts: concepts.md
+  - Getting Started:
+      - getting-started/index.md
+      - Installation: getting-started/installation.md
+      - Quick Start: getting-started/quick-start.md
+      - Configuration: getting-started/configuration.md
+  - Architecture:
+      - architecture/index.md
+      - Core Concepts: architecture/core-concepts.md
+      - Robot Execution: architecture/robot-execution.md
+      - Network Orchestration: architecture/network-orchestration.md
+      - State Management: architecture/state-management.md
+      - Message Flow: architecture/message-flow.md
+  - Guides:
+      - guides/index.md
+      - Building Robots: guides/building-robots.md
+      - Creating Networks: guides/creating-networks.md
+      - Using Tools: guides/using-tools.md
+      - MCP Integration: guides/mcp-integration.md
+      - Streaming Responses: guides/streaming.md
+      - Conversation History: guides/history.md
+      - Memory System: guides/memory.md
+      - Rails Integration: guides/rails-integration.md
+  - API Reference:
+      - api/index.md
+      - Core Classes:
+          - api/core/index.md
+          - Robot: api/core/robot.md
+          - Network: api/core/network.md
+          - State: api/core/state.md
+          - Tool: api/core/tool.md
+          - Memory: api/core/memory.md
+      - Messages:
+          - api/messages/index.md
+          - UserMessage: api/messages/user-message.md
+          - TextMessage: api/messages/text-message.md
+          - ToolCallMessage: api/messages/tool-call-message.md
+          - ToolResultMessage: api/messages/tool-result-message.md
+      - Adapters:
+          - api/adapters/index.md
+          - Anthropic: api/adapters/anthropic.md
+          - OpenAI: api/adapters/openai.md
+          - Gemini: api/adapters/gemini.md
+      - MCP:
+          - api/mcp/index.md
+          - Client: api/mcp/client.md
+          - Server: api/mcp/server.md
+          - Transports: api/mcp/transports.md
+      - Streaming:
+          - api/streaming/index.md
+          - Context: api/streaming/context.md
+          - Events: api/streaming/events.md
+      - History:
+          - api/history/index.md
+          - Config: api/history/config.md
+          - ThreadManager: api/history/thread-manager.md
+          - ActiveRecordAdapter: api/history/active-record-adapter.md
+  - Examples:
+      - examples/index.md
+      - Basic Chat: examples/basic-chat.md
+      - Multi-Robot Network: examples/multi-robot-network.md
+      - Tool Usage: examples/tool-usage.md
+      - MCP Server: examples/mcp-server.md
+      - Rails Application: examples/rails-application.md

data/sig/robot_lab.rbs

@@ -0,0 +1,4 @@
+module RobotLab
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end