vsm 0.0.1 → 0.1.0

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
+      puts msg.payload.to_s unless msg.payload.to_s.empty?
+      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,61 @@
+# 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,
+  streaming: true,
+  transport: :nethttp
+)
+
+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,96 @@
+# 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,
+  streaming: true,
+  transport: :nethttp
+)
+
+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/lib/vsm/async_channel.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module VSM
+  class AsyncChannel
+    attr_reader :context
+
+    def initialize(context: {})
+      @queue = Async::Queue.new
+      @subs  = []
+      @context = context
+    end
+
+    def emit(message)
+      @queue.enqueue(message)
+      @subs.each { |blk| Async { blk.call(message) } }
+    end
+
+    def pop = @queue.dequeue
+    def subscribe(&blk) = @subs << blk
+  end
+end

data/lib/vsm/capsule.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require "async"
+module VSM
+  class Capsule
+    attr_reader :name, :bus, :homeostat, :roles, :children
+
+    def initialize(name:, roles:, children: {})
+      @name     = name.to_sym
+      @roles    = roles
+      @children = children
+      ctx = { operations_children: children.transform_keys(&:to_s) }
+      @bus = AsyncChannel.new(context: ctx)
+      @homeostat = Homeostat.new
+      wire_observers!
+    end
+
+    def run
+      Async do
+        loop do
+          message = @bus.pop
+          roles[:coordination].stage(message)
+          roles[:coordination].drain(@bus) { |m| dispatch(m) }
+        end
+      end
+    end
+
+    def dispatch(message)
+      return roles[:identity].alert(message) if homeostat.alarm?(message)
+      roles[:governance].enforce(message) { route(_1) }
+    end
+
+    def route(message)
+      roles[:operations].handle(message, bus: @bus, children: @children) ||
+      roles[:intelligence].handle(message, bus: @bus) ||
+      roles[:identity].handle(message, bus: @bus)
+    end
+
+    private
+
+    def wire_observers!
+      roles.values.each { |r| r.respond_to?(:observe) && r.observe(@bus) }
+    end
+  end
+end