prompt_objects 0.5.0 → 0.7.0

data/templates/music-beginner/objects/voice_pad.md

@@ -0,0 +1,46 @@
+---
+name: voice_pad
+description: Sustained harmony specialist who creates slow, connected chord beds
+tools:
+  - set_instrument
+  - set_voice_level
+  - play_pattern
+  - stop_voice
+---
+
+# Pad voice
+
+You create the harmonic bed. Always read `composition` first.
+
+## Performance contract
+
+When asked to start, join, activate, or revise your part, perform the change in
+that same turn. On first activation call `play_pattern` once with `instrument:
+air_pad`, the chosen `level`, and the complete pattern so setup and playback are
+one operation. On later changes, call every playback tool needed to make the
+requested change real. Do not merely
+draft notation, ask “shall I activate this?”, or wait for confirmation: the
+conductor's request is authorization. A pattern written only in prose makes no
+sound. Save state only after the playback calls return without an error, and
+report the calls you actually completed.
+
+Use voice name `pad`, instrument `air_pad`, and level 0.42-0.62. Write one chord
+event for every chord in the progression, normally one chord every four beats.
+Join simultaneous notes with `+`; do not arpeggiate a chord that should be held.
+Keep voicings between C3 and E4, use three or four notes, and favor inversions
+that move each note only a short distance. Use the optional fourth event field
+as a gate slightly longer than the four-beat step so adjacent chords overlap
+gently instead of exposing a gap.
+
+For Cmaj7 / Am7 / Fmaj7 / G6 at one bar per chord, the structural shape is:
+
+```text
+C3+G3+B3+E4@4@0.58@4.5;C3+E3+G3+A3@4@0.55@4.5;C3+F3+A3+E4@4@0.54@4.5;D3+G3+B3+E4@4@0.56@4.5
+```
+
+Compose your own voicings from the actual contract. Change them sparingly. You
+may insert a full-progression rest only for a deliberate breakdown; normally
+you are the quiet continuity underneath the other voices.
+
+After every submitted playback change, save `voice_pad_state` with instrument,
+level, pattern, voicing intent, and which contract you followed.

data/templates/music-beginner/objects/voice_percussion.md

@@ -0,0 +1,45 @@
+---
+name: voice_percussion
+description: Sample-based percussionist who adds a barely-there pulse only when useful
+tools:
+  - set_instrument
+  - set_voice_level
+  - play_pattern
+  - stop_voice
+---
+
+# Percussion voice
+
+You add pulse, not spectacle. Always read `composition` first.
+
+## Performance contract
+
+When asked to start, join, activate, or revise your part, perform the change in
+that same turn. On first activation call `play_pattern` once with `instrument:
+gentle_kit`, the chosen `level`, and the complete pattern so setup and playback
+are one operation. On later changes, call every playback tool needed to make
+the requested change real. Do not merely
+draft notation, ask “shall I activate this?”, or wait for confirmation: the
+conductor's request is authorization. A pattern written only in prose makes no
+sound. Save state only after the playback calls return without an error, and
+report the calls you actually completed. If the correct musical choice is
+silence, call `stop_voice` rather than merely saying you will remain silent.
+
+Use voice name `percussion`, instrument `gentle_kit`, and level 0.22-0.42. Your
+tokens trigger real Sonic Pi samples: `kick`, `hat`, `snare`, and `tick`. Every
+silent subdivision must be an explicit `R` event.
+
+For talk-safe background music, provide a quiet four-beat pulse like:
+
+```text
+kick@0.5@0.45;R@0.5;hat@0.5@0.28;R@0.5;tick@0.5@0.25;R@0.5;hat@0.5@0.26;R@0.5
+```
+
+Use at most one kick per bar. Hats or ticks may quietly mark alternating beats
+or offbeats; snare is optional and rare. Fills are inappropriate unless the
+conductor explicitly calls for a transition. If keys already carry a clear
+pulse, simplify and lower your level instead of automatically disappearing.
+
+After every submitted playback change, save `voice_percussion_state` with level,
+pattern, density, and why percussion is helping. Stopping yourself is a valid
+musical choice.

data/templates/music-beginner/objects/voice_texture.md

@@ -0,0 +1,37 @@
+---
+name: voice_texture
+description: Minimal colorist who places rare, quiet tones around the ensemble
+tools:
+  - set_instrument
+  - set_voice_level
+  - play_pattern
+  - stop_voice
+---
+
+# Texture voice
+
+You provide one glint of color, then disappear. Always read `composition` first.
+
+## Performance contract
+
+When asked to start, join, activate, or revise your part, perform the change in
+that same turn. On first activation call `play_pattern` once with the chosen
+`instrument`, `level`, and complete pattern so setup and playback are one
+operation. On later changes, call every playback tool needed to make the
+requested change real. Do not merely
+draft notation, ask “shall I activate this?”, or wait for confirmation: the
+conductor's request is authorization. A pattern written only in prose makes no
+sound. Save state only after the playback calls return without an error, and
+report the calls you actually completed.
+
+Use voice name `texture`. Choose `felt_pluck`, `sine_glow`, or—very
+sparingly—`glass_bell`, at level 0.3-0.55. Stay around G4-E5. Build a 16- or
+32-beat pattern with one to three attacks and long explicit rests. Use chord
+tones or shared tones between adjacent chords so the accent does not clash.
+
+A shape such as `G4@1@0.4;R@15` demonstrates the right amount of space. Compose
+the actual note and placement from the contract. Never double the keys motif
+continuously and never use rapid bells.
+
+After every submitted playback change, save `voice_texture_state` with
+instrument, level, pattern, and the coloristic purpose of each attack.

data/templates/music-beginner/primitives/play_pattern.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+module PromptObjects
+  module Primitives
+    class PlayPattern < Primitive
+      execution_policy parallel_safe: true, side_effect: :write, resource_keys: ->(arguments, _context, _capability) {
+        ["music:voice:#{arguments[:voice] || arguments['voice']}"]
+      }
+
+      MAX_EVENTS = 32
+      MAX_BEATS = 64.0
+      NOTE = /\A(?:\d{1,3}|[A-Ga-g](?:s|b|#)?-?\d)\z/
+      DRUMS = %w[kick hat snare tick].freeze
+      PRESETS = %w[soft_keys air_pad warm_bass felt_pluck glass_bell sine_glow gentle_kit].freeze
+
+      def name
+        "play_pattern"
+      end
+
+      def description
+        "Activate or replace a voice's repeating pattern at a synchronized boundary. Syntax: semicolon-separated " \
+          "sound@step_beats@amp@gate_beats events; amp and gate are optional. Gate controls how long pitched sound " \
+          "rings independently of the time to the next event. Optional instrument and level make first activation " \
+          "atomic. Sounds are notes (C4), chords (C3+E3+G3), R rests, or gentle_kit tokens."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: { type: "string", description: "Voice that owns this loop" },
+            pattern: {
+              type: "string",
+              description: "Events sound@step_beats@amp@gate_beats separated by semicolons; amp and gate are optional. Up to 32 events / 64 step beats."
+            },
+            instrument: { type: "string", enum: PRESETS, description: "Optional curated instrument to apply with this pattern" },
+            level: { type: "number", minimum: 0.0, maximum: 1.0, description: "Optional voice level to apply with this pattern" }
+          },
+          required: %w[voice pattern]
+        }
+      end
+
+      def receive(message, context:)
+        voice = (message[:voice] || message["voice"]).to_s.strip
+        pattern = (message[:pattern] || message["pattern"]).to_s.strip
+        instrument = message[:instrument] || message["instrument"]
+        level = message.key?(:level) ? message[:level] : message["level"]
+        return "Error: voice cannot be empty" if voice.empty?
+
+        events, error = self.class.validate(pattern)
+        return "Error: #{error}" if error
+        if instrument && !PRESETS.include?(instrument.to_s)
+          return "Error: unknown instrument '#{instrument}'. Choose: #{PRESETS.join(', ')}"
+        end
+        if !level.nil? && (!level.is_a?(Numeric) || !level.to_f.between?(0.0, 1.0))
+          return "Error: level must be a number from 0.0 to 1.0"
+        end
+
+        OscBridge.send_message("/music/instrument", voice, instrument.to_s) if instrument
+        OscBridge.send_message("/music/level", voice, level.to_f) unless level.nil?
+        OscBridge.send_message("/music/pattern", voice, pattern)
+        beats = events.sum { |event| event[:duration] }
+        setup = []
+        setup << instrument.to_s if instrument
+        setup << "level #{level.to_f.round(2)}" unless level.nil?
+        suffix = setup.empty? ? "" : " with #{setup.join(', ')}"
+        "Queued #{events.length}-event / #{beats.round(2)}-beat pattern for #{voice}#{suffix}. It will replace the loop at a synchronized boundary."
+      rescue => e
+        "Error setting pattern: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+
+      def self.validate(pattern)
+        return [nil, "pattern cannot be empty"] if pattern.empty?
+
+        raw_events = pattern.split(";", -1).map(&:strip)
+        return [nil, "pattern contains an empty event"] if raw_events.any?(&:empty?)
+        return [nil, "pattern has more than #{MAX_EVENTS} events"] if raw_events.length > MAX_EVENTS
+
+        events = raw_events.map.with_index do |raw, index|
+          parts = raw.split("@", -1).map(&:strip)
+          return [nil, "event #{index + 1} must be sound@step_beats, sound@step_beats@amp, or sound@step_beats@amp@gate_beats"] unless parts.length.between?(2, 4)
+
+          sound = parts[0]
+          return [nil, "event #{index + 1} has an invalid sound '#{sound}'"] unless valid_sound?(sound)
+
+          duration = Float(parts[1])
+          return [nil, "event #{index + 1} duration must be 0.125..16 beats"] unless duration.between?(0.125, 16.0)
+
+          amp = parts.length == 3 ? Float(parts[2]) : 0.7
+          amp = Float(parts[2]) if parts.length == 4
+          return [nil, "event #{index + 1} amplitude must be 0.0..1.0"] unless amp.between?(0.0, 1.0)
+
+          gate = parts.length == 4 ? Float(parts[3]) : duration
+          return [nil, "event #{index + 1} gate must be 0.05..16 beats"] unless gate.between?(0.05, 16.0)
+
+          { sound: sound, duration: duration, amp: amp, gate: gate }
+        rescue ArgumentError, TypeError
+          return [nil, "event #{index + 1} step, amplitude, and gate must be numbers"]
+        end
+
+        total = events.sum { |event| event[:duration] }
+        return [nil, "pattern is longer than #{MAX_BEATS.to_i} beats"] if total > MAX_BEATS
+
+        [events, nil]
+      end
+
+      def self.valid_sound?(sound)
+        return true if sound.casecmp("R").zero? || DRUMS.include?(sound.downcase)
+
+        notes = sound.split("+")
+        notes.length.between?(1, 6) && notes.all? { |candidate| NOTE.match?(candidate) }
+      end
+      private_class_method :valid_sound?
+    end
+  end
+end

data/templates/music-beginner/primitives/query_music_engine.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require_relative "support/osc_bridge"
+
+module PromptObjects
+  module Primitives
+    class QueryMusicEngine < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
+      RESPONSE_PORT = 4561
+      TIMEOUT = 2
+
+      def name
+        "query_music_engine"
+      end
+
+      def description
+        "Query the actual Sonic Pi engine state: tempo, voice instruments, levels, active flags, and patterns."
+      end
+
+      def parameters
+        { type: "object", properties: {}, required: [] }
+      end
+
+      def receive(message, context:)
+        socket = UDPSocket.new
+        socket.bind("127.0.0.1", RESPONSE_PORT)
+        OscBridge.send_message("/music/query", RESPONSE_PORT)
+        ready = IO.select([socket], nil, nil, TIMEOUT)
+        return no_response(socket) unless ready
+
+        data, = socket.recvfrom(8192)
+        socket.close
+        state = parse_osc_string(data)
+        return "Received an empty response from Sonic Pi." if state.nil? || state.empty?
+
+        format_state(state)
+      rescue Errno::EADDRINUSE
+        "Port #{RESPONSE_PORT} is busy; another query may be in progress. Try again shortly."
+      rescue => e
+        socket&.close
+        "Error querying Sonic Pi: #{e.message}"
+      end
+
+      private
+
+      def no_response(socket)
+        socket.close
+        "Sonic Pi is not responding. Open Sonic Pi and run extras/sonic_pi_boot.rb with run_file."
+      end
+
+      def parse_osc_string(data)
+        address_end = data.index("\x00")
+        return unless address_end
+
+        position = address_end + 1
+        position += 1 while position % 4 != 0
+        return unless data[position] == ","
+
+        tag_end = data.index("\x00", position)
+        return unless tag_end && data[position + 1] == "s"
+
+        position = tag_end + 1
+        position += 1 while position % 4 != 0
+        string_end = data.index("\x00", position)
+        data[position...string_end] if string_end
+      end
+
+      def format_state(state)
+        parts = state.split("||")
+        header = parts.shift.to_s.split("|", -1)
+        voices = parts.each_with_object({}) do |part, result|
+          name, active, instrument, level, pattern = part.split("|", 5)
+          result[name] = {
+            "active" => active == "true",
+            "instrument" => instrument,
+            "level" => level.to_f,
+            "pattern" => pattern
+          }
+        end
+
+        JSON.pretty_generate(
+          "connected" => true,
+          "bpm" => header[0].to_i,
+          "slots_used" => header[1].to_i,
+          "slots_free" => header[2].to_i,
+          "voices" => voices
+        )
+      end
+    end
+  end
+end

data/templates/music-beginner/primitives/set_instrument.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+module PromptObjects
+  module Primitives
+    class SetInstrument < Primitive
+      execution_policy parallel_safe: true, side_effect: :write, resource_keys: ->(arguments, _context, _capability) {
+        ["music:voice:#{arguments[:voice] || arguments['voice']}"]
+      }
+
+      PRESETS = %w[soft_keys air_pad warm_bass felt_pluck glass_bell sine_glow gentle_kit].freeze
+
+      def name
+        "set_instrument"
+      end
+
+      def description
+        "Choose a curated, level-matched instrument: #{PRESETS.join(', ')}. " \
+          "gentle_kit accepts kick, hat, snare, and tick pattern tokens."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: { type: "string", description: "Stable voice name, such as keys, pad, bass, percussion, or texture" },
+            instrument: { type: "string", enum: PRESETS, description: "A curated instrument preset" }
+          },
+          required: %w[voice instrument]
+        }
+      end
+
+      def receive(message, context:)
+        voice = (message[:voice] || message["voice"]).to_s.strip
+        instrument = (message[:instrument] || message["instrument"]).to_s.strip
+        return "Error: voice cannot be empty" if voice.empty?
+        return "Error: unknown instrument '#{instrument}'. Choose: #{PRESETS.join(', ')}" unless PRESETS.include?(instrument)
+
+        OscBridge.send_message("/music/instrument", voice, instrument)
+        "Set #{voice} to #{instrument}; the change takes effect at its next synchronized pattern boundary."
+      rescue => e
+        "Error setting instrument: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/music-beginner/primitives/set_tempo.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+module PromptObjects
+  module Primitives
+    class SetTempo < Primitive
+      execution_policy parallel_safe: false, side_effect: :exclusive
+
+      MIN_BPM = 50
+      MAX_BPM = 120
+
+      def name
+        "set_tempo"
+      end
+
+      def description
+        "Set the ensemble's shared tempo to 50-120 BPM. Every voice stays on the same bar clock."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            bpm: { type: "integer", minimum: MIN_BPM, maximum: MAX_BPM,
+                   description: "Shared tempo. For background music, prefer 65-82 BPM." }
+          },
+          required: ["bpm"]
+        }
+      end
+
+      def receive(message, context:)
+        bpm = (message[:bpm] || message["bpm"]).to_i
+        return "Error: bpm must be between #{MIN_BPM} and #{MAX_BPM}" unless bpm.between?(MIN_BPM, MAX_BPM)
+
+        OscBridge.send_message("/music/tempo", bpm)
+        "Tempo will change to #{bpm} BPM on the shared clock."
+      rescue => e
+        "Error setting tempo: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/music-beginner/primitives/set_voice_level.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+module PromptObjects
+  module Primitives
+    class SetVoiceLevel < Primitive
+      execution_policy parallel_safe: true, side_effect: :write, resource_keys: ->(arguments, _context, _capability) {
+        ["music:voice:#{arguments[:voice] || arguments['voice']}"]
+      }
+
+      def name
+        "set_voice_level"
+      end
+
+      def description
+        "Set a voice's mix level from 0.0 (silent) to 1.0 (preset maximum). Prefer 0.35-0.75."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: { type: "string", description: "Voice to mix" },
+            level: { type: "number", minimum: 0.0, maximum: 1.0, description: "Safe scale within the preset's baked-in level" }
+          },
+          required: %w[voice level]
+        }
+      end
+
+      def receive(message, context:)
+        voice = (message[:voice] || message["voice"]).to_s.strip
+        level = Float(message[:level] || message["level"])
+        return "Error: voice cannot be empty" if voice.empty?
+        return "Error: level must be between 0.0 and 1.0" unless level.between?(0.0, 1.0)
+
+        OscBridge.send_message("/music/level", voice, level)
+        "Set #{voice} level to #{level.round(2)}."
+      rescue ArgumentError, TypeError
+        "Error: level must be a number between 0.0 and 1.0"
+      rescue => e
+        "Error setting voice level: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/music-beginner/primitives/stop_voice.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+module PromptObjects
+  module Primitives
+    class StopVoice < Primitive
+      execution_policy parallel_safe: false, side_effect: :exclusive
+
+      def name
+        "stop_voice"
+      end
+
+      def description
+        "Stop one voice at its next boundary, or use voice 'all' for immediate ensemble silence."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: { voice: { type: "string", description: "Voice name, or all" } },
+          required: ["voice"]
+        }
+      end
+
+      def receive(message, context:)
+        voice = (message[:voice] || message["voice"]).to_s.strip
+        return "Error: voice cannot be empty" if voice.empty?
+
+        OscBridge.send_message("/music/stop", voice)
+        voice == "all" ? "Stopped all music." : "Queued stop for #{voice}."
+      rescue => e
+        "Error stopping voice: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/music-beginner/primitives/support/osc_bridge.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "osc-ruby"
+
+module PromptObjects
+  module Primitives
+    module OscBridge
+      SONIC_PI_HOST = ENV.fetch("SONIC_PI_HOST", "127.0.0.1")
+      SONIC_PI_PORT = ENV.fetch("SONIC_PI_PORT", "4560").to_i
+
+      @client = nil
+      @mutex = Mutex.new
+
+      def self.client
+        @mutex.synchronize do
+          @client ||= OSC::Client.new(SONIC_PI_HOST, SONIC_PI_PORT)
+        end
+      end
+
+      def self.send_message(path, *args)
+        client.send(OSC::Message.new(path, *args))
+      end
+    end
+  end
+end

data/templates/music-beginner/vendor/osc-ruby-1.1.5/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Colin Harris
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in
+ all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ THE SOFTWARE.

data/templates/music-beginner/vendor/osc-ruby-1.1.5/lib/osc-ruby/address_pattern.rb

@@ -0,0 +1,58 @@
+module OSC
+  class AddressPattern
+    def initialize(pattern)
+      @pattern = pattern
+
+      generate_regex_from_pattern
+    end
+
+    def match?(address)
+      !!(@re.nil? || @re.match(address))
+    end
+
+    private
+
+    def generate_regex_from_pattern
+      case @pattern
+      when nil
+        @re = @pattern
+      when Regexp
+        @re = @pattern
+      when String
+        # i'm unsure what this does
+        # @pattern.gsub!(/[.^(|)]/, '\\1')
+
+        # handles osc single char wildcard matching
+        @pattern.gsub!(/\?/, '[^/]')
+
+        # handles ** - used in creating osc routers
+        # TODO: turns out the OSC 1.1 spec says that we shoudl use "//"
+        # this will be implemented in the next major release of this gem
+        #@pattern.gsub!(/\*\*/, '.*' )
+
+        # handles osc * - 0 or more matching
+        @pattern.gsub!(/\*[^\*]/, '[^/]*')
+
+        # handles [!] matching
+        @pattern.gsub!(/\[!/, '[^')
+
+        # handles {} matching
+        @pattern.gsub!(/\{/, '(')
+        @pattern.gsub!(/,/, '|')
+        @pattern.gsub!(/\}/, ')')
+
+
+        # keeps from matching before the begining of the pattern
+        @pattern.gsub!(/\A/, '\A')
+
+        # keeps from matching beyond the end,
+        # eg. pattern /hi does not match /hidden
+        @pattern.gsub!(/\z/, '\z')
+
+        @re = Regexp.new(@pattern)
+      else
+        raise(ArgumentError, 'invalid pattern')
+      end
+    end
+  end
+end

data/templates/music-beginner/vendor/osc-ruby-1.1.5/lib/osc-ruby/broadcast_client.rb

@@ -0,0 +1,24 @@
+require 'ipaddr'
+
+module OSC
+  class BroadcastClient
+
+    BROADCAST_ADDRESS = '<broadcast>'
+
+    attr_reader :port
+
+    def initialize(port, local_ip = nil)
+      @port = port
+      @so = UDPSocket.new
+      @so.setsockopt Socket::SOL_SOCKET, Socket::SO_BROADCAST, true
+      if local_ip
+        @so.setsockopt Socket::IPPROTO_IP, Socket::IP_MULTICAST_IF, IPAddr.new(local_ip).hton
+        @so.bind(local_ip, 0)
+      end
+    end
+
+    def send(mesg)
+      @so.send(mesg.encode, 0, BROADCAST_ADDRESS, @port)
+    end
+  end
+end