vsm 0.0.1 → 0.2.0

data/Rakefile

@@ -5,8 +5,4 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]
+task default: %i[spec]

data/examples/01_echo_tool.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "vsm/ports/chat_tty"
+require "securerandom"
+
+class EchoTool < VSM::ToolCapsule
+  tool_name "echo"
+  tool_description "Echoes a message"
+  tool_schema({ type: "object", properties: { text: { type: "string" } }, required: ["text"] })
+
+  def run(args)
+    "you said: #{args["text"]}"
+  end
+end
+
+# Minimal “intelligence” that triggers a tool when user types "echo: ..."
+class DemoIntelligence < VSM::Intelligence
+  def handle(message, bus:, **)
+    case message.kind
+    when :user
+      if message.payload =~ /\Aecho:\s*(.+)\z/
+        bus.emit VSM::Message.new(kind: :tool_call, payload: { tool: "echo", args: { "text" => $1 } }, corr_id: SecureRandom.uuid, meta: message.meta)
+      else
+        bus.emit VSM::Message.new(kind: :assistant, payload: "Try: echo: hello", meta: message.meta)
+      end
+      true
+    when :tool_result
+      # Complete the turn after tool execution
+      bus.emit VSM::Message.new(kind: :assistant, payload: "(done)", meta: message.meta)
+      true
+    else
+      false
+    end
+  end
+end
+
+cap = VSM::DSL.define(:demo) do
+  identity    klass: VSM::Identity,    args: { identity: "demo", invariants: [] }
+  governance  klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: DemoIntelligence
+  monitoring  klass: VSM::Monitoring
+  operations do
+    capsule :echo, klass: EchoTool
+  end
+end
+
+# Use the built-in, customizable ChatTTY port
+banner = ->(io) { io.puts "\e[96mEcho demo\e[0m — type 'echo: hello' (Ctrl-C to exit)" }
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap, banner: banner)])

data/examples/02_openai_streaming.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Example: OpenAI streaming demo (no tools)
+#
+# Usage:
+#   OPENAI_API_KEY=... AIRB_MODEL=gpt-4o-mini ruby examples/02_openai_streaming.rb
+#   VSM_DEBUG_STREAM=1 to see low-level logs
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "securerandom"
+require "vsm"
+
+MODEL = ENV["AIRB_MODEL"] || "gpt-4o-mini"
+
+driver = VSM::Drivers::OpenAI::AsyncDriver.new(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  model: MODEL
+)
+
+system_prompt = <<~PROMPT
+  You are a concise assistant. Answer briefly.
+PROMPT
+
+cap = VSM::DSL.define(:openai_stream_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "openai_stream_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: system_prompt }
+  operations   klass: VSM::Operations
+  monitoring   klass: VSM::Monitoring
+end
+
+if ENV["VSM_LENS"] == "1"
+  VSM::Lens.attach!(cap, port: (ENV["VSM_LENS_PORT"] || 9292).to_i, token: ENV["VSM_LENS_TOKEN"]) rescue nil
+end
+
+class StreamTTY < VSM::Port
+  def should_render?(message)
+    [:assistant_delta, :assistant, :tool_result, :tool_call].include?(message.kind)
+  end
+
+  def loop
+    sid = SecureRandom.uuid
+    puts "openai streaming demo — type to chat (Ctrl-C to exit)"
+    print "You: "
+    while (line = $stdin.gets&.chomp)
+      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: sid })
+      @capsule.roles[:coordination].wait_for_turn_end(sid)
+      print "You: "
+    end
+  end
+
+  def render_out(msg)
+    case msg.kind
+    when :assistant_delta
+      # Stream without newline
+      print msg.payload
+      $stdout.flush
+    when :assistant
+      puts "" # end the line after streaming
+      # The :assistant event carries the full final text again; avoid re-printing it
+      # because we've already streamed the deltas above. Just show the turn marker.
+      puts "(turn #{msg.meta&.dig(:turn_id)})"
+    when :tool_result
+      puts "\nTool> #{msg.payload}"
+    when :tool_call
+      puts "\nTool? #{msg.payload[:tool]}(#{msg.corr_id}) #{msg.payload[:args].inspect}"
+    end
+  end
+end
+
+VSM::Runtime.start(cap, ports: [StreamTTY.new(capsule: cap)])
+

data/examples/02b_anthropic_streaming.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Example: Anthropic streaming demo (no tools)
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "securerandom"
+require "vsm"
+
+MODEL = ENV["AIRB_MODEL"] || "claude-sonnet-4-0"
+
+driver = VSM::Drivers::Anthropic::AsyncDriver.new(
+  api_key: ENV.fetch("ANTHROPIC_API_KEY"),
+  model: MODEL
+)
+
+system_prompt = "You are a concise assistant. Answer briefly."
+
+cap = VSM::DSL.define(:anthropic_stream_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "anthropic_stream_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: system_prompt }
+  operations   klass: VSM::Operations
+  monitoring   klass: VSM::Monitoring
+end
+
+class StreamTTY < VSM::Port
+  def should_render?(message)
+    [:assistant_delta, :assistant].include?(message.kind) || message.kind == :tool_calls
+  end
+
+  def loop
+    sid = SecureRandom.uuid
+    puts "anthropic streaming demo — type to chat (Ctrl-C to exit)"
+    print "You: "
+    while (line = $stdin.gets&.chomp)
+      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: sid })
+      @capsule.roles[:coordination].wait_for_turn_end(sid)
+      print "You: "
+    end
+  end
+
+  def render_out(msg)
+    case msg.kind
+    when :assistant_delta
+      print msg.payload
+      $stdout.flush
+    when :assistant
+      puts ""
+      puts "(turn #{msg.meta&.dig(:turn_id)})"
+    when :tool_calls
+      puts "\n(tool_calls #{msg.payload&.size || 0})"
+    end
+  end
+end
+
+VSM::Runtime.start(cap, ports: [StreamTTY.new(capsule: cap)])
+

data/examples/02c_gemini_streaming.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Example: Gemini streaming demo (no tools)
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "securerandom"
+require "vsm"
+
+MODEL = ENV["AIRB_MODEL"] || "gemini-2.5-flash"
+
+driver = VSM::Drivers::Gemini::AsyncDriver.new(
+  api_key: ENV.fetch("GEMINI_API_KEY"),
+  model: MODEL,
+  streaming: true
+)
+
+system_prompt = "You are a concise assistant. Answer briefly."
+
+cap = VSM::DSL.define(:gemini_stream_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "gemini_stream_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: system_prompt }
+  operations   klass: VSM::Operations
+  monitoring   klass: VSM::Monitoring
+end
+
+class StreamTTY < VSM::Port
+  def should_render?(message)
+    [:assistant_delta, :assistant].include?(message.kind) || message.kind == :tool_calls
+  end
+
+  def loop
+    sid = SecureRandom.uuid
+    puts "gemini streaming demo — type to chat (Ctrl-C to exit)"
+    print "You: "
+    while (line = $stdin.gets&.chomp)
+      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: sid })
+      @capsule.roles[:coordination].wait_for_turn_end(sid)
+      print "You: "
+    end
+  end
+
+  def render_out(msg)
+    case msg.kind
+    when :assistant_delta
+      print msg.payload
+      $stdout.flush
+    when :assistant
+      puts ""
+      puts "(turn #{msg.meta&.dig(:turn_id)})"
+    when :tool_calls
+      puts "\n(tool_calls #{msg.payload&.size || 0})"
+    end
+  end
+end
+
+VSM::Runtime.start(cap, ports: [StreamTTY.new(capsule: cap)])
+
+

data/examples/03_openai_tools.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Example: OpenAI tool-calling demo (list_files/read_file)
+#
+# Usage:
+#   OPENAI_API_KEY=... AIRB_MODEL=gpt-4o-mini ruby examples/03_openai_tools.rb
+#   VSM_DEBUG_STREAM=1 to see low-level logs
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "securerandom"
+require "json"
+require "vsm"
+
+MODEL = ENV["AIRB_MODEL"] || "gpt-4o-mini"
+
+# Simple file tools scoped to current working directory
+class ListFiles < VSM::ToolCapsule
+  tool_name "list_files"
+  tool_description "List files in a directory"
+  tool_schema({ type: "object", properties: { path: { type: "string" } }, required: [] })
+  def run(args)
+    path = args["path"].to_s.strip
+    path = "." if path.empty?
+    entries = Dir.children(path).sort.take(200)
+    entries.join("\n")
+  rescue => e
+    "ERROR: #{e.class}: #{e.message}"
+  end
+end
+
+class ReadFile < VSM::ToolCapsule
+  tool_name "read_file"
+  tool_description "Read a small text file"
+  tool_schema({ type: "object", properties: { path: { type: "string" } }, required: ["path"] })
+  def run(args)
+    path = args["path"].to_s
+    raise "path required" if path.empty?
+    raise "too large" if File.size(path) > 200_000
+    File.read(path)
+  rescue => e
+    "ERROR: #{e.class}: #{e.message}"
+  end
+end
+
+driver = VSM::Drivers::OpenAI::AsyncDriver.new(
+  api_key: ENV.fetch("OPENAI_API_KEY"),
+  model: MODEL
+)
+
+system_prompt = <<~PROMPT
+  You are a coding assistant with two tools: list_files and read_file.
+  Prefer to call tools when appropriate. Keep answers brief.
+PROMPT
+
+cap = VSM::DSL.define(:openai_tools_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "openai_tools_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: system_prompt }
+  monitoring   klass: VSM::Monitoring
+  operations do
+    capsule :list_files, klass: ListFiles
+    capsule :read_file,  klass: ReadFile
+  end
+end
+
+if ENV["VSM_LENS"] == "1"
+  VSM::Lens.attach!(cap, port: (ENV["VSM_LENS_PORT"] || 9292).to_i, token: ENV["VSM_LENS_TOKEN"]) rescue nil
+end
+
+class ToolTTY < VSM::Port
+  def should_render?(message)
+    [:assistant_delta, :assistant, :tool_result, :tool_call].include?(message.kind)
+  end
+
+  def loop
+    sid = SecureRandom.uuid
+    puts "openai tools demo — type to chat (Ctrl-C to exit)"
+    print "You: "
+    while (line = $stdin.gets&.chomp)
+      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: sid })
+      @capsule.roles[:coordination].wait_for_turn_end(sid)
+      print "You: "
+    end
+  end
+
+  def render_out(msg)
+    case msg.kind
+    when :assistant_delta
+      print msg.payload
+      $stdout.flush
+    when :assistant
+      puts ""
+      puts "(turn #{msg.meta&.dig(:turn_id)})"
+    when :tool_call
+      puts "\nTool? #{msg.payload[:tool]}(#{msg.corr_id})"
+    when :tool_result
+      puts "\nTool> (completed)"
+    end
+  end
+end
+
+VSM::Runtime.start(cap, ports: [ToolTTY.new(capsule: cap)])
+
+
+

data/examples/03b_anthropic_tools.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+# Example: Anthropic tool-calling demo (list_files/read_file)
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "securerandom"
+require "vsm"
+
+MODEL = ENV["AIRB_MODEL"] || "claude-sonnet-4-0"
+
+class ListFiles < VSM::ToolCapsule
+  tool_name "list_files"
+  tool_description "List files in a directory"
+  tool_schema({ type: "object", properties: { path: { type: "string" } }, required: [] })
+  def run(args)
+    path = args["path"].to_s.strip
+    path = "." if path.empty?
+    Dir.children(path).sort.take(200).join("\n")
+  rescue => e
+    "ERROR: #{e.class}: #{e.message}"
+  end
+end
+
+class ReadFile < VSM::ToolCapsule
+  tool_name "read_file"
+  tool_description "Read a small text file"
+  tool_schema({ type: "object", properties: { path: { type: "string" } }, required: ["path"] })
+  def run(args)
+    path = args["path"].to_s
+    raise "path required" if path.empty?
+    raise "too large" if File.size(path) > 200_000
+    File.read(path)
+  rescue => e
+    "ERROR: #{e.class}: #{e.message}"
+  end
+end
+
+driver = VSM::Drivers::Anthropic::AsyncDriver.new(
+  api_key: ENV.fetch("ANTHROPIC_API_KEY"),
+  model: MODEL
+)
+
+system_prompt = <<~PROMPT
+  You are a coding assistant with two tools: list_files and read_file.
+  Prefer to call tools when appropriate. Keep answers brief.
+PROMPT
+
+cap = VSM::DSL.define(:anthropic_tools_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "anthropic_tools_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: system_prompt }
+  monitoring   klass: VSM::Monitoring
+  operations do
+    capsule :list_files, klass: ListFiles
+    capsule :read_file,  klass: ReadFile
+  end
+end
+
+class ToolTTY < VSM::Port
+  def should_render?(message)
+    [:assistant_delta, :assistant, :tool_result, :tool_call].include?(message.kind)
+  end
+
+  def loop
+    sid = SecureRandom.uuid
+    puts "anthropic tools demo — type to chat (Ctrl-C to exit)"
+    print "You: "
+    while (line = $stdin.gets&.chomp)
+      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: sid })
+      @capsule.roles[:coordination].wait_for_turn_end(sid)
+      print "You: "
+    end
+  end
+
+  def render_out(msg)
+    case msg.kind
+    when :assistant_delta
+      print msg.payload
+      $stdout.flush
+    when :assistant
+      puts ""
+      puts "(turn #{msg.meta&.dig(:turn_id)})"
+    when :tool_call
+      puts "\nTool? #{msg.payload[:tool]}(#{msg.corr_id})"
+    when :tool_result
+      puts "\nTool> (completed)"
+    end
+  end
+end
+
+VSM::Runtime.start(cap, ports: [ToolTTY.new(capsule: cap)])
+

data/examples/03c_gemini_tools.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Example: Gemini tool-calling demo (list_files/read_file) with streaming enabled
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "securerandom"
+require "vsm"
+
+MODEL = ENV["AIRB_MODEL"] || "gemini-2.5-flash"
+
+class ListFiles < VSM::ToolCapsule
+  tool_name "list_files"
+  tool_description "List files in a directory"
+  tool_schema({ type: "object", properties: { path: { type: "string" } }, required: [] })
+  def run(args)
+    path = args["path"].to_s.strip
+    path = "." if path.empty?
+    Dir.children(path).sort.take(200).join("\n")
+  rescue => e
+    "ERROR: #{e.class}: #{e.message}"
+  end
+end
+
+class ReadFile < VSM::ToolCapsule
+  tool_name "read_file"
+  tool_description "Read a small text file"
+  tool_schema({ type: "object", properties: { path: { type: "string" } }, required: ["path"] })
+  def run(args)
+    path = args["path"].to_s
+    raise "path required" if path.empty?
+    raise "too large" if File.size(path) > 200_000
+    File.read(path)
+  rescue => e
+    "ERROR: #{e.class}: #{e.message}"
+  end
+end
+
+driver = VSM::Drivers::Gemini::AsyncDriver.new(
+  api_key: ENV.fetch("GEMINI_API_KEY"),
+  model: MODEL,
+  streaming: true
+)
+
+system_prompt = <<~PROMPT
+  You are a coding assistant with two tools: list_files and read_file.
+  Prefer to call tools when appropriate. Keep answers brief.
+PROMPT
+
+cap = VSM::DSL.define(:gemini_tools_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "gemini_tools_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: VSM::Intelligence, args: { driver: driver, system_prompt: system_prompt }
+  monitoring   klass: VSM::Monitoring
+  operations do
+    capsule :list_files, klass: ListFiles
+    capsule :read_file,  klass: ReadFile
+  end
+end
+
+class ToolTTY < VSM::Port
+  def should_render?(message)
+    [:assistant_delta, :assistant, :tool_result, :tool_call].include?(message.kind)
+  end
+
+  def loop
+    sid = SecureRandom.uuid
+    puts "gemini tools demo — type to chat (Ctrl-C to exit)"
+    print "You: "
+    while (line = $stdin.gets&.chomp)
+      @capsule.bus.emit VSM::Message.new(kind: :user, payload: line, meta: { session_id: sid })
+      @capsule.roles[:coordination].wait_for_turn_end(sid)
+      print "You: "
+    end
+  end
+
+  def render_out(msg)
+    case msg.kind
+    when :assistant_delta
+      print msg.payload
+      $stdout.flush
+    when :assistant
+      puts ""
+      puts "(turn #{msg.meta&.dig(:turn_id)})"
+    when :tool_call
+      puts "\nTool? #{msg.payload[:tool]}(#{msg.corr_id})"
+    when :tool_result
+      puts "\nTool> (completed)"
+    end
+  end
+end
+
+VSM::Runtime.start(cap, ports: [ToolTTY.new(capsule: cap)])
+
+

data/examples/05_mcp_server_and_chattty.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "securerandom"
+require "vsm/ports/chat_tty"
+require "vsm/ports/mcp/server_stdio"
+
+# A simple local tool we can expose to both ChatTTY and MCP stdio.
+class EchoTool < VSM::ToolCapsule
+  tool_name "echo"
+  tool_description "Echoes back the provided text"
+  tool_schema({ type: "object", properties: { text: { type: "string" } }, required: ["text"] })
+  def run(args)
+    "you said: #{args["text"]}"
+  end
+end
+
+# Minimal intelligence that triggers the echo tool when user types: echo: ...
+class DemoIntelligence < VSM::Intelligence
+  def handle(message, bus:, **)
+    case message.kind
+    when :user
+      if message.payload =~ /\Aecho:\s*(.+)\z/
+        bus.emit VSM::Message.new(kind: :tool_call, payload: { tool: "echo", args: { "text" => $1 } }, corr_id: SecureRandom.uuid, meta: message.meta)
+      else
+        bus.emit VSM::Message.new(kind: :assistant, payload: "Try: echo: hello", meta: message.meta)
+      end
+      true
+    when :tool_result
+      bus.emit VSM::Message.new(kind: :assistant, payload: "(done)", meta: message.meta)
+      true
+    else
+      false
+    end
+  end
+end
+
+cap = VSM::DSL.define(:demo_mcp_server_and_chat) do
+  identity     klass: VSM::Identity,     args: { identity: "demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: DemoIntelligence
+  monitoring   klass: VSM::Monitoring
+  operations do
+    capsule :echo, klass: EchoTool
+  end
+end
+
+# Run both ports together: MCP stdio (machine) + ChatTTY (human).
+banner = ->(io) { io.puts "\e[96mVSM demo\e[0m — type 'echo: hi' (Ctrl-C to exit)" }
+ports = [VSM::Ports::MCP::ServerStdio.new(capsule: cap)]
+if $stdout.tty?
+  # Only enable interactive ChatTTY when attached to a TTY to avoid
+  # interfering when this example is spawned as a background MCP server.
+  begin
+    tty = File.open("/dev/tty", "r+")
+  rescue StandardError
+    tty = nil
+  end
+  ports << VSM::Ports::ChatTTY.new(capsule: cap, banner: banner, input: tty, output: tty)
+end
+
+VSM::Runtime.start(cap, ports: ports)

data/examples/06_mcp_mount_reflection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "vsm"
+require "vsm/dsl_mcp"
+require "vsm/ports/chat_tty"
+require "securerandom"
+
+# This example mounts a remote MCP server (we use example 05 as the server)
+# and exposes its tools locally via dynamic reflection. Type: echo: hello
+
+class DemoIntelligence < VSM::Intelligence
+  def handle(message, bus:, **)
+    case message.kind
+    when :user
+      if message.payload =~ /\Aecho:\s*(.+)\z/
+        bus.emit VSM::Message.new(kind: :tool_call, payload: { tool: "echo", args: { "text" => $1 } }, corr_id: SecureRandom.uuid, meta: message.meta)
+      else
+        bus.emit VSM::Message.new(kind: :assistant, payload: "Try: echo: hello", meta: message.meta)
+      end
+      true
+    when :tool_result
+      bus.emit VSM::Message.new(kind: :assistant, payload: "(done)", meta: message.meta)
+      true
+    else
+      false
+    end
+  end
+end
+
+server_cmd = "ruby #{File.expand_path("05_mcp_server_and_chattty.rb", __dir__)}"
+
+cap = VSM::DSL.define(:mcp_mount_demo) do
+  identity     klass: VSM::Identity,     args: { identity: "mcp_mount_demo", invariants: [] }
+  governance   klass: VSM::Governance
+  coordination klass: VSM::Coordination
+  intelligence klass: DemoIntelligence
+  monitoring   klass: VSM::Monitoring
+  operations do
+    # Reflect the remote server's tools; include only :echo and expose as local name "echo"
+    mcp_server :demo_server, cmd: server_cmd, include: %w[echo]
+  end
+end
+
+banner = ->(io) { io.puts "\e[96mMCP mount demo\e[0m — type 'echo: hi' (Ctrl-C to exit)" }
+VSM::Runtime.start(cap, ports: [VSM::Ports::ChatTTY.new(capsule: cap, banner: banner)])