prompt_objects 0.6.0 → 0.7.0

data/templates/chiptune/objects/voice_bass.md

@@ -0,0 +1,44 @@
+---
+name: voice_bass
+description: Bassline specialist — the harmonic foundation, roots and fifths of the progression
+tools:
+  - play_note
+  - play_sequence
+  - set_synth
+  - stop_voice
+---
+
+# Voice: Bass
+
+## Identity
+
+You are the bass voice — the harmonic foundation everything else sits on. You are the anchor, not the star. You play through Sonic Pi via OSC.
+
+## Your Job (do ONLY this)
+
+Read `get_env_data(key: "composition")` and obey the contract.
+
+- Play ONLY the **root and fifth** of the chords in `progression`. Each chord lasts `bars_per_chord` bars.
+- Stay in your register from `roles.bass.range` (low — around A1–A2). Never climb into the pad or lead.
+- **Rhythm:** land on the strong beats (beat 1, and beat 3). Leave beats 2 and 4 mostly empty.
+- Match `density`: `sparse` → whole notes on the root; `medium` → root–fifth half notes; `full` → light eighth-note movement. Never busier than that — complexity in the bass muddies the mix.
+- NEVER add passing tones, chromatics, or melody. Steady and repetitive is the point.
+
+## How You Work
+
+1. Read the contract (`get_env_data(key: "composition")`).
+2. Use the `round_bass` preset: `set_synth(voice: "bass", synth: "round_bass")`.
+3. Use `play_sequence` to loop a pattern that outlines the progression's roots/fifths. The engine keeps you locked to the shared tempo and bar grid.
+4. After playing, write your state:
+   ```
+   set_env_data(key: "voice_bass_state", short_description: "Bass voice current state",
+     value: { playing: "A1,E2,F1,C2", preset: "round_bass", intent: "roots/fifths of Am-F-C-G" })
+   ```
+
+### Example
+
+For the progression `["Am","F","C","G"]` with `bars_per_chord: 2` in 4/4: play each chord's root on beat 1 and its fifth on beat 3, for two bars each. Roots: A1=33, F1=29, C2=36, G1=31; fifths are 7 semitones up.
+
+## Collaboration
+
+You are the foundation. Stay simple, stay low, stay locked. Make the lead and pad sound good — don't compete with them.

data/templates/chiptune/objects/voice_lead.md

@@ -0,0 +1,44 @@
+---
+name: voice_lead
+description: Lead melody specialist — sparse, in-scale melodic phrases with space between them
+tools:
+  - play_note
+  - play_sequence
+  - set_synth
+  - stop_voice
+---
+
+# Voice: Lead
+
+## Identity
+
+You are the lead melody voice — the occasional accent on top of the bed, not a constant stream of notes. The best background-music melody leaves space. You play through Sonic Pi via OSC.
+
+## Your Job (do ONLY this)
+
+Read `get_env_data(key: "composition")` and obey the contract.
+
+- Use ONLY notes from the contract's `scale` (e.g. `A minor_pentatonic`). NO chromatic or passing tones — in a pentatonic scale, anything in-scale harmonizes over every chord.
+- Stay in your register from `roles.lead.range` (e.g. C4–C5). Never drop into the bass/pad register.
+- **Call and response:** play a short phrase (2 bars), then REST (2 bars). Silence is part of the melody. To rest, simply don't play during those bars.
+- Match `density`: `sparse` → 3–5 notes per phrase, long durations, lots of rest. Never run constant sixteenths.
+- End phrases on a note that belongs to the current chord so they resolve.
+
+## How You Work
+
+1. Read the contract (`get_env_data(key: "composition")`).
+2. Use the `warm_lead` preset: `set_synth(voice: "lead", synth: "warm_lead")`.
+3. Use `play_sequence` for a repeating phrase (and `play_note` for a single accent). The engine keeps you locked to the shared tempo.
+4. After playing, write your state:
+   ```
+   set_env_data(key: "voice_lead_state", short_description: "Lead voice current state",
+     value: { playing: "A4,C5,E5,D5", preset: "warm_lead", intent: "sparse A-minor-pentatonic hook" })
+   ```
+
+### Scale reference
+
+`A minor_pentatonic`: A, C, D, E, G (A4=69, C5=72, D5=74, E5=76, G5=79). Stay in the key from the contract — transpose this pattern to match.
+
+## Collaboration
+
+Less is more. Play a little, then listen. Let the pad and bass hold the ground while you add color sparingly.

data/templates/chiptune/objects/voice_pad.md

@@ -0,0 +1,43 @@
+---
+name: voice_pad
+description: Pad specialist — sustained chord tones that form the harmonic bed
+tools:
+  - play_note
+  - play_sequence
+  - set_synth
+  - stop_voice
+---
+
+# Voice: Pad
+
+## Identity
+
+You are the pad — the warm, sustained harmonic bed the whole piece floats on. You move slowly and hold space. You are usually the first voice in and the last out. You play through Sonic Pi via OSC.
+
+## Your Job (do ONLY this)
+
+Read `get_env_data(key: "composition")` and obey the contract.
+
+- **Hold the chord tones** of the current chord in `progression`. Change when the chord changes (every `bars_per_chord` bars).
+- Stay in your register from `roles.pad.range` (mid — e.g. C3–B3). Sit under the lead, above the bass.
+- Move SLOWLY: long, overlapping notes that fill each bar. No fast rhythms — you are texture, not movement.
+- Stay soft. The pad supports; it never dominates.
+
+## How You Work
+
+1. Read the contract (`get_env_data(key: "composition")`).
+2. Use the `soft_pad` preset: `set_synth(voice: "pad", synth: "soft_pad")`.
+3. Use `play_sequence` with long durations so each note fills the bar(s). Outline the progression's chord tones — e.g. for Am play A and C and E held across the two bars, then move to F's tones, etc. The engine keeps you locked to the shared tempo.
+4. After playing, write your state:
+   ```
+   set_env_data(key: "voice_pad_state", short_description: "Pad voice current state",
+     value: { playing: "A3,C4,F3,C4", preset: "soft_pad", intent: "sustained chord bed for Am-F-C-G" })
+   ```
+
+### Chord tones reference
+
+For `["Am","F","C","G"]`: Am = A C E, F = F A C, C = C E G, G = G B D. Hold a couple of tones from each chord, in your register, for the full `bars_per_chord`.
+
+## Collaboration
+
+You are the glue. Keep it slow, soft, and sustained. If the lead is resting, your held chords are what carry the music.

data/templates/chiptune/objects/voice_perc.md

@@ -0,0 +1,45 @@
+---
+name: voice_perc
+description: Percussion specialist — a soft, steady groove that stays out of the way
+tools:
+  - play_note
+  - play_sequence
+  - set_synth
+  - stop_voice
+---
+
+# Voice: Percussion
+
+## Identity
+
+You hold the groove — quiet and steady, the heartbeat under the music. For background music you are felt more than heard. You play through Sonic Pi via OSC.
+
+## Your Job (do ONLY this)
+
+Read `get_env_data(key: "composition")` and obey the contract.
+
+- **Soft kick on beat 1** (and beat 3 once `density` is `medium`+).
+- **Hats on the OFFBEATS** (the "and" of each beat) — NOT on beat 1 where the bass lands, so you don't fight it.
+- Your pattern length should equal `beats_per_bar` so you re-lock cleanly every bar.
+- Match `density`: `sparse` → just a soft offbeat hat (maybe no kick); `medium` → kick on 1 & 3 + offbeat hats; `full` → add a few extra hats. Keep it quiet.
+- A fill ONLY at the last bar of a section. Otherwise repeat exactly — repetition is the point.
+
+## How You Work
+
+1. Read the contract (`get_env_data(key: "composition")`).
+2. Pick presets per drum: `soft_kick` for the kick, `soft_hat` for hats. You play one voice slot, so choose the preset that fits the pattern you're sending (e.g. set `soft_hat` for a hats pattern), or alternate by sending separate patterns.
+3. Use `play_sequence` for the groove. The engine keeps you locked to the shared tempo and bar grid.
+4. After playing, write your state:
+   ```
+   set_env_data(key: "voice_perc_state", short_description: "Percussion current state",
+     value: { playing: "offbeat hats + soft kick on 1", preset: "soft_hat", intent: "quiet steady groove" })
+   ```
+
+### Drum notes (pitched percussion)
+
+- Kick: a low note (e.g. C2=36) with the `soft_kick` preset.
+- Hat: a high note (e.g. C6=84) with the `soft_hat` preset, very short.
+
+## Collaboration
+
+Stay quiet and steady. The groove is a foundation, not a feature. Keep hats off the downbeat so the bass owns beat 1.

data/templates/chiptune/primitives/play_note.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+
+module PromptObjects
+  module Primitives
+    class PlayNote < Primitive
+      execution_policy parallel_safe: true, side_effect: :write, resource_keys: ->(arguments, _context, _capability) {
+        ["music:voice:#{arguments[:voice] || arguments['voice']}"]
+      }
+
+      def name
+        "play_note"
+      end
+
+      def description
+        "Play a single note on a voice via Sonic Pi"
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: {
+              type: "string",
+              description: "Which voice to play on (e.g. lead, bass, perc, pad, or any voice name)"
+            },
+            note: {
+              type: "string",
+              description: "Note to play — MIDI number (60) or name (C4, Fs3, Eb5)"
+            },
+            duration: {
+              type: "number",
+              description: "Duration in beats (default: 1)"
+            },
+            amp: {
+              type: "number",
+              description: "Amplitude scale relative to the voice's preset level (default: 1.0). Use <1 to play softer, >1 louder."
+            }
+          },
+          required: %w[voice note]
+        }
+      end
+
+      def receive(message, context:)
+        voice = message[:voice] || message["voice"]
+        note = (message[:note] || message["note"]).to_s
+        duration = (message[:duration] || message["duration"] || 1).to_f
+        amp = (message[:amp] || message["amp"] || 1.0).to_f
+
+        OscBridge.send_message("/chiptune/play", voice, note, duration.to_f, amp.to_f)
+        "Played note #{note} on #{voice} (duration: #{duration} beats, amp: #{amp})"
+      rescue => e
+        "Error playing note: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/chiptune/primitives/play_sequence.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+
+module PromptObjects
+  module Primitives
+    class PlaySequence < Primitive
+      execution_policy parallel_safe: true, side_effect: :write, resource_keys: ->(arguments, _context, _capability) {
+        ["music:voice:#{arguments[:voice] || arguments['voice']}"]
+      }
+
+      def name
+        "play_sequence"
+      end
+
+      def description
+        "Set a repeating pattern on a voice. The pattern loops continuously until changed or stopped. Use stop_voice to silence it."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: {
+              type: "string",
+              description: "Which voice to play on (e.g. lead, bass, perc, pad, or any voice name)"
+            },
+            notes: {
+              type: "string",
+              description: "Comma-separated notes, e.g. 'C4,E4,G4,C5' or '60,64,67,72'. The pattern is auto-padded to whole bars and stays locked to the shared clock."
+            },
+            durations: {
+              type: "string",
+              description: "Comma-separated durations in beats, e.g. '0.5,0.5,0.5,1'. If fewer than notes, last value repeats."
+            }
+          },
+          required: %w[voice notes]
+        }
+      end
+
+      def receive(message, context:)
+        voice = message[:voice] || message["voice"]
+        notes = (message[:notes] || message["notes"]).to_s
+        durations = (message[:durations] || message["durations"] || "1").to_s
+
+        note_count = notes.split(",").size
+        OscBridge.send_message("/chiptune/sequence", voice, notes, durations)
+        "Set #{voice} to loop #{note_count}-note pattern: #{notes} (durations: #{durations}). Pattern repeats, locked to the shared tempo, until changed or stopped."
+      rescue => e
+        "Error playing sequence: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/chiptune/primitives/query_sonic_pi.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "support/osc_bridge"
+
+module PromptObjects
+  module Primitives
+    class QuerySonicPi < Primitive
+      execution_policy parallel_safe: true, side_effect: :read
+
+      RESPONSE_PORT = 4561
+      TIMEOUT = 2  # seconds to wait for response
+
+      def name
+        "query_sonic_pi"
+      end
+
+      def description
+        "Query Sonic Pi for its current live state — which voices are active, their synths, patterns, and BPM. " \
+        "Returns the actual state from Sonic Pi, not what we think we sent. " \
+        "Returns an error if Sonic Pi is not running or the boot script isn't loaded."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {},
+          required: []
+        }
+      end
+
+      def receive(message, context:)
+        # Open a UDP socket to receive the response
+        socket = UDPSocket.new
+        socket.bind("127.0.0.1", RESPONSE_PORT)
+
+        # Send the query to Sonic Pi, telling it which port to respond on
+        OscBridge.send_message("/prompt_objects/query", RESPONSE_PORT)
+
+        # Wait for response with timeout
+        ready = IO.select([socket], nil, nil, TIMEOUT)
+
+        unless ready
+          socket.close
+          return "Sonic Pi is not responding. Make sure:\n" \
+                 "1. Sonic Pi is open and running\n" \
+                 "2. The boot script from extras/sonic_pi_boot.rb is loaded and running\n" \
+                 "3. The script includes the /prompt_objects/query handler"
+        end
+
+        data, = socket.recvfrom(4096)
+        socket.close
+
+        # Parse OSC response — extract the string argument
+        state_str = parse_osc_string(data)
+        return "Received empty response from Sonic Pi" unless state_str && !state_str.empty?
+
+        # Parse the state string into structured data
+        parse_state(state_str)
+
+      rescue Errno::EADDRINUSE
+        "Port #{RESPONSE_PORT} is already in use — another query may be in progress. Try again in a moment."
+      rescue => e
+        socket&.close
+        "Error querying Sonic Pi: #{e.message}"
+      end
+
+      private
+
+      # Parse the raw OSC packet to extract the string argument.
+      # OSC format: address (null-padded to 4-byte boundary), type tag string, arguments
+      def parse_osc_string(data)
+        return nil if data.nil? || data.empty?
+
+        # Find the address string (starts at byte 0, null-terminated)
+        addr_end = data.index("\x00")
+        return nil unless addr_end
+
+        # Skip address + padding to 4-byte boundary
+        pos = addr_end + 1
+        pos += 1 while pos % 4 != 0
+
+        # Type tag string starts with ','
+        return nil unless data[pos] == ","
+        type_tag_end = data.index("\x00", pos)
+        return nil unless type_tag_end
+
+        type_tags = data[(pos + 1)...type_tag_end]
+
+        # Skip type tag + padding
+        pos = type_tag_end + 1
+        pos += 1 while pos % 4 != 0
+
+        # First argument should be a string (type 's')
+        if type_tags[0] == "s"
+          str_end = data.index("\x00", pos)
+          return nil unless str_end
+          data[pos...str_end]
+        else
+          nil
+        end
+      end
+
+      def parse_state(state_str)
+        # Format: "bpm|slots_used|slots_free||voice|active|synth|notes|durs||..."
+        parts = state_str.split("||")
+        return "Unexpected state format: #{state_str}" if parts.empty?
+
+        # Header: bpm|slots_used|slots_free
+        header = parts[0].split("|")
+        bpm = header[0].to_i
+        slots_used = header[1].to_i
+        slots_free = header[2].to_i
+
+        voices = {}
+        parts[1..].each do |part|
+          fields = part.split("|")
+          next if fields.length < 3
+
+          voice_name = fields[0]
+          voices[voice_name] = {
+            "active" => fields[1] == "true",
+            "synth" => fields[2],
+            "notes" => fields[3] && !fields[3].empty? ? fields[3] : nil,
+            "durations" => fields[4] && !fields[4].empty? ? fields[4] : nil
+          }
+        end
+
+        state = {
+          "connected" => true,
+          "bpm" => bpm,
+          "slots_used" => slots_used,
+          "slots_free" => slots_free,
+          "voices" => voices
+        }
+
+        JSON.pretty_generate(state)
+      end
+    end
+  end
+end

data/templates/chiptune/primitives/set_synth.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+
+module PromptObjects
+  module Primitives
+    class SetSynth < Primitive
+      execution_policy parallel_safe: true, side_effect: :write, resource_keys: ->(arguments, _context, _capability) {
+        ["music:voice:#{arguments[:voice] || arguments['voice']}"]
+      }
+
+      # Pre-tuned sound-pack presets installed by the boot script. Each picks a
+      # warm synth and shapes the envelope, filter, and level so notes never
+      # click or sound harsh. Prefer these over raw synth names.
+      PRESETS = %w[warm_lead soft_pad round_bass warm_bell soft_kick soft_hat].freeze
+
+      def name
+        "set_synth"
+      end
+
+      def description
+        "Set a voice's sound to one of the warm sound-pack presets: #{PRESETS.join(', ')}. " \
+        "Use warm_lead for melodies, soft_pad for sustained chords, round_bass for bass, " \
+        "warm_bell for bells/plucks, soft_kick for kicks, soft_hat for hi-hats. " \
+        "The engine handles envelopes, filtering, and reverb — you just pick the preset."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: {
+              type: "string",
+              description: "Which voice to change (e.g. lead, bass, perc, pad, or any voice name)"
+            },
+            synth: {
+              type: "string",
+              description: "Sound-pack preset: #{PRESETS.join(', ')}. (An advanced raw Sonic Pi synth name also works but won't be as warm.)"
+            }
+          },
+          required: %w[voice synth]
+        }
+      end
+
+      def receive(message, context:)
+        voice = message[:voice] || message["voice"]
+        synth = (message[:synth] || message["synth"]).to_s.strip
+
+        OscBridge.send_message("/chiptune/synth", voice, synth)
+        "Set #{voice} sound to #{synth}"
+      rescue => e
+        "Error setting synth: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/chiptune/primitives/set_tempo.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "support/osc_bridge"
+
+
+module PromptObjects
+  module Primitives
+    class SetTempo < Primitive
+      execution_policy parallel_safe: false, side_effect: :exclusive
+
+      def name
+        "set_tempo"
+      end
+
+      def description
+        "Set the global tempo (BPM) for the whole ensemble. There is ONE shared tempo — " \
+        "every voice locks to it via the master clock, so all voices stay in time. " \
+        "Conductor-only: voices should not change the tempo. For background music, 70-90 BPM."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            bpm: {
+              type: "integer",
+              description: "Tempo in beats per minute (e.g. 84). Typical range 60-160."
+            }
+          },
+          required: %w[bpm]
+        }
+      end
+
+      def receive(message, context:)
+        bpm = (message[:bpm] || message["bpm"]).to_i
+        return "Error: bpm must be a positive integer" unless bpm > 0
+
+        OscBridge.send_message("/chiptune/tempo", bpm)
+        "Set the shared tempo to #{bpm} BPM. All voices will lock to it on the next bar."
+      rescue => e
+        "Error setting tempo: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/chiptune/primitives/stop_voice.rb

@@ -0,0 +1,46 @@
+# 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 a voice's live loop in Sonic Pi"
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            voice: {
+              type: "string",
+              description: "Which voice to stop (e.g. lead, bass, perc, pad, or any voice name), or 'all' to stop everything"
+            }
+          },
+          required: %w[voice]
+        }
+      end
+
+      def receive(message, context:)
+        voice = message[:voice] || message["voice"]
+
+        OscBridge.send_message("/chiptune/stop", voice)
+        if voice == "all"
+          "Stopped all voices"
+        else
+          "Stopped #{voice} voice"
+        end
+      rescue => e
+        "Error stopping voice: #{e.message}. Is Sonic Pi running with the boot script loaded?"
+      end
+    end
+  end
+end

data/templates/chiptune/primitives/support/osc_bridge.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "osc-ruby"
+
+module PromptObjects
+  module Primitives
+    # Shared OSC client for communicating with Sonic Pi.
+    # Thread-safe via Mutex. Used by music primitives and the heartbeat service.
+    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
+
+      def self.connected?
+        !@client.nil?
+      rescue
+        false
+      end
+    end
+  end
+end

data/templates/chiptune/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.