pinecall 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2a10f0e074b767542af49bb9d9d6ae3251e230b371debee5d5e5628c92f67b2
-  data.tar.gz: 81be17cb2c53a7c5c6fc3d188f7b38abd16f265afafc8c3d0a089933fb126809
+  metadata.gz: e3afca7edf6bc33bb5b6fc9ebed23d76eecac2bb6039fb243d252d379e509e50
+  data.tar.gz: f3a39bb373fa2565bc6f49f04429d8f560dcc5cd8d01f9cc8d874f3ae452808d
 SHA512:
-  metadata.gz: f7baea4bcf9f7b72c71d24e24ddf698e3afa5d06863d60dbd32943b8648705857e8b209b43130fc1c9e435673f03666f50a9ee7694f970c19f6ca2eb868e4ef9
-  data.tar.gz: e966301764b4ce05390cae2821339012f95106dea20593fc0e1ffc00106c48d348ef6e1f56ab46ca5ad6ce0f67fb1bb5072f071334f2d0ac59fdc8309269bdb3
+  metadata.gz: bd6ea499f8cdbe11a9faf6e25715848c470755e8318705beee191db517446096866e79bd830c32ba77ed4c38c7da134ccdacf90ae973c7169d18baa5a58abd93
+  data.tar.gz: 9ee25075169e9581cafd1c58a67eee8b47705cc82bbd3d6aa8568b1a35db6ac20039089bb72de8004bbd973772679725208c3fdca5d469a8b292b2de53badd63

data/CHANGELOG.md

@@ -6,6 +6,27 @@ version number is the human's call.
 
 ## [Unreleased]
 
+## [0.0.6] — A greeting is words or :improvise, a hangup is words or true, and the ears choose who ends the turn (2026-10-10)
+
+- `greeting "…"` (said as written), `greeting :improvise` (the model opens on its prompt) and
+  `greeting improvise("…")` (with an instruction); `interruptible: true` for an opening the caller
+  may cut short, which by default they cannot. The `say:` / `reply:` keywords are gone.
+- `hangup "…"` (when, in your words) or `hangup true` (whenever the model judges); `when:` is gone.
+- `stt "…", end_of_turn: :stt | :livekit | :smart_turn`: who says the caller's turn is over, as
+  @pinecall/agents 0.9.26 says it. Needs runtime 0.1.43.
+
+## [0.0.5] — The class declares its voice, its models and the rest, and wins (2026-10-10)
+
+- **A class declares its environment again, and it wins over the settings.** Class macros `voice
+  "<vendor>", "<id>", model:`, `llm "<vendor>/<model>", temperature:`, `stt "<vendor>/<model>"`,
+  `language`, `greeting`, `hangup`, `turn`, `says`, `hears`, `knowledge`, `docs`, `memory` and
+  `record`, sent on `agent.configure`. A field the class declares is not read from the settings,
+  the console shows it "set by the class", and `pinecall agent set` of it is refused. Needs runtime
+  0.1.42.
+- `builds:` and `options:` on `voice`, `llm` and `stt`: a class of the vendor's plugin and its
+  keyword arguments (`llm "openai/gpt-5.4-mini", builds: "responses.LLM", options: { use_websocket:
+  true }`), only on the org's own key for the vendor. The refusal that named a CLI verb is gone.
+
 ## [0.0.4] — A tool announces itself (2026-10-09)
 
 ### Added

data/lib/pinecall/agent/config.rb

@@ -4,35 +4,54 @@ module Pinecall
   class Agent
     # Class-level configuration (state lives on the instance).
     #
-    # A class declares its contract: tools, state, view. Runtime settings (voice, models,
-    # language, greeting, memory, knowledge) belong to the world and are refused at load with the
-    # CLI command that sets them.
+    # A class declares its contract: tools, state, view. It may also declare its environment —
+    # voice, models, language, greeting, memory, knowledge — and whatever it declares wins over the
+    # agent's settings for that field.
     module Config
       # `phone`, `whatsapp` and `web` are accepted for compatibility but ignored. `channel_rules
       # false` leaves the `<channel>` block out of the prompt.
       AS_WRITTEN = %i[phone whatsapp web channel_rules].freeze
 
-      # Settings that moved to the world, and the command that sets each. Must match the
-      # TypeScript package's `THE_WORLDS`.
-      THE_WORLDS = {
-        voice: "pinecall agent set --voice <name>",
-        llm: "pinecall agent set --llm <vendor/model>",
-        stt: "pinecall agent set --stt <vendor>",
-        language: "pinecall agent set --language <tag>",
-        greeting: "pinecall agent set --greeting '…' (or --reply '…')",
-        hangup: "pinecall agent set --hangup '…'",
-        says: "pinecall lexicon add <word> --say '…'",
-        hears: "pinecall lexicon hear <word> …",
-        memory: "pinecall memory policy --remember '…' --forget '…'",
-        record: "pinecall agent set --record on|off",
-        knowledge: "pinecall agent knowledge edit — what the agent knows by heart is a setting, not a file",
-        docs: "pinecall docs push, then pinecall docs attach <base>"
-      }.freeze
+      # The settings a class may declare. Must match the TypeScript package's `ENVIRONMENT`.
+      ENVIRONMENT = %i[language voice llm stt greeting hangup turn says hears knowledge docs memory record].freeze
+
+      # The ones written as the wire's own fields, keyword by keyword: `greeting say: "…"`.
+      AS_KEYWORDS = %i[turn knowledge docs memory].freeze
+
+      NO_VOICE = "a voice the class declares names its vendor and the voice: voice \"<vendor>\", \"<voice id>\""
+
+      NO_OPENING = "a greeting is the words, as a string, or :improvise for the model's own: improvise(\"…\") gives it an instruction"
+      NO_ENDING = "hangup is when the model may end the call, in your words, or true whenever it judges the call done"
+
+      # The model opens the call: on its prompt alone (an empty instruction), or with this one.
+      Improvised = Data.define(:instruction, :interruptible)
 
       NOTHING = Object.new.freeze
 
-      def self.moved_to_the_world(field)
-        "`#{field}` is the world's now, not the class's: #{THE_WORLDS.fetch(field)} — remove it from the class"
+      # An opening as the wire says it: words to `say`, or a `reply` the model opens on.
+      def self.greeting_of(opening, interruptible)
+        said = case opening
+               when :improvise then { reply: "" }
+               when Improvised then { reply: opening.instruction }
+               when String then { say: opening }
+               else raise DeclarationRefused, NO_OPENING
+               end
+        given = opening.is_a?(Improvised) ? opening.interruptible : interruptible
+        given.nil? ? said : { **said, allow_interruptions: given }
+      end
+
+      # When the model may end the call: an empty `when` is whenever it judges.
+      def self.hangup_of(ending)
+        return { when: "" } if ending == true
+        raise DeclarationRefused, NO_ENDING unless ending.is_a?(String) && !ending.strip.empty?
+
+        { when: ending }
+      end
+
+      # `vendor/model`, or a vendor alone; the model id keeps every slash after the vendor's.
+      def self.model_of(named)
+        provider, _slash, model = named.to_s.partition("/")
+        { provider:, model: }
       end
 
       module Declaring
@@ -45,13 +64,81 @@ module Pinecall
           end
         end
 
-        # World settings raise at load, naming the command that sets them.
-        THE_WORLDS.each_key do |field|
-          define_method(field) do |*_said, **_options|
-            raise DeclarationRefused, Config.moved_to_the_world(field)
+        # The voice, by its vendor and the vendor's own id for it. Declared, it wins over the
+        # agent's settings; `builds` and `options` reach the vendor's plugin.
+        def voice(provider = NOTHING, voice_id = nil, model: nil, builds: nil, options: nil)
+          return environment[:voice] if provider.equal?(NOTHING)
+          raise DeclarationRefused, NO_VOICE if voice_id.nil?
+
+          environment[:voice] = { provider:, voice_id:, model:, builds:, options: }.compact
+        end
+
+        # The model that answers, `vendor/model` or a vendor alone:
+        # `llm "openai/gpt-5.4-mini", builds: "responses.LLM", options: { use_websocket: true }`.
+        def llm(model = NOTHING, temperature: nil, builds: nil, options: nil)
+          return environment[:llm] if model.equal?(NOTHING)
+
+          environment[:llm] = { **Config.model_of(model), temperature:, builds:, options: }.compact
+        end
+
+        # The ears, `vendor/model` or a vendor alone, and who says the caller's turn is over:
+        # `end_of_turn: "stt"` the ears themselves (Deepgram Flux), `"livekit"` or `"smart-turn"`.
+        def stt(model = NOTHING, builds: nil, options: nil, end_of_turn: nil)
+          return environment[:stt] if model.equal?(NOTHING)
+
+          ends = end_of_turn&.to_s&.tr("_", "-")
+          environment[:stt] = { **Config.model_of(model), builds:, options:, end_of_turn: ends }.compact
+        end
+
+        # How a call opens: the words, said as written, or :improvise for the model's own. The
+        # caller cannot cut it short unless `interruptible: true`.
+        def greeting(opening = NOTHING, interruptible: nil)
+          return environment[:greeting] if opening.equal?(NOTHING)
+
+          environment[:greeting] = Config.greeting_of(opening, interruptible)
+        end
+
+        # The model opens the call with this instruction: `greeting improvise("…")`.
+        def improvise(instruction = "", interruptible: nil) = Improvised.new(instruction, interruptible)
+
+        # When the model may end the call: in your words, or `true` whenever it judges it done.
+        def hangup(ending = NOTHING)
+          return environment[:hangup] if ending.equal?(NOTHING)
+
+          environment[:hangup] = Config.hangup_of(ending)
+        end
+
+        # `language "es"`, `says [{ word: "GSA", spoken: "ge ese a" }]`, `record false`.
+        %i[language says record].each do |field|
+          define_method(field) do |value = NOTHING|
+            return environment[field] if value.equal?(NOTHING)
+
+            environment[field] = value
+          end
+        end
+
+        # The words the ears must know: `hears "Vidal", "Sanitas"`.
+        def hears(*words)
+          return environment[:hears] if words.empty?
+
+          environment[:hears] = words.flatten
+        end
+
+        # `turn endpointing_ms: 300`, `docs base: "…", k: 4`, `memory remember: […], forget: […]`,
+        # `knowledge path: "…", text: "…"`.
+        AS_KEYWORDS.each do |field|
+          define_method(field) do |**given|
+            return environment[field] if given.empty?
+
+            environment[field] = given
           end
         end
 
+        # What the class declares of its environment, including inherited values.
+        def environment
+          @environment ||= superclass.respond_to?(:environment) ? superclass.environment.dup : {}
+        end
+
         # Set the class docstring explicitly, for classes with no source file.
         def doc(text = NOTHING)
           return Doc.for_class(self) if text.equal?(NOTHING)
@@ -84,9 +171,10 @@ module Pinecall
           @slug = name
         end
 
-        # The AgentConfig sent to the gateway.
+        # The AgentConfig sent to the gateway: the contract, and the environment the class declares.
         def wire_config(tools: nil)
           {
+            **environment,
             prompt: Prompt::FRAMEWORK,
             tools:,
             state_fields: state_field_specs,

data/lib/pinecall/version.rb

@@ -2,5 +2,5 @@
 
 module Pinecall
   # Set by the maintainer at release time.
-  VERSION = "0.0.4"
+  VERSION = "0.0.6"
 end

data/lib/pinecall/wire/shapes_config.rb

@@ -14,12 +14,17 @@ module Pinecall
           name: { kind: :str },
           provider: { kind: :str },
           model: { kind: :str },
-          voice_id: { kind: :str }
+          voice_id: { kind: :str },
+          builds: { kind: :str },
+          options: { kind: :json }
         }.freeze,
         "ModelConfig" => {
           provider: { kind: :str, required: true },
           model: { kind: :str, required: true },
-          temperature: { kind: :float }
+          temperature: { kind: :float },
+          builds: { kind: :str },
+          options: { kind: :json },
+          end_of_turn: { kind: :enum, values: %w[stt livekit smart-turn] }
         }.freeze,
         "TurnConfig" => {
           min_interruption_words: { kind: :int },

data/lib/pinecall/wire/shapes_doors.rb

@@ -18,6 +18,7 @@ module Pinecall
         }.freeze,
         "AgentConfig" => {
           prompt: { kind: :list, items: { kind: :ref, ref: "PromptBlockSpec" } },
+          language: { kind: :str },
           greeting: { kind: :ref, ref: "GreetingConfig" },
           voice: { kind: :ref, ref: "VoiceConfig" },
           llm: { kind: :ref, ref: "ModelConfig" },

data/sig/pinecall.rbs

@@ -84,18 +84,22 @@ module Pinecall
     def self.panel: (?String) { (Panel::Who) -> void } -> Panel::Declared
     def self.declared_panel: () -> Panel::Declared?
 
-    # the world's, refused at load with the verb that sets each
-    def self.voice: (*untyped, **untyped) -> bot
-    def self.llm: (*untyped, **untyped) -> bot
-    def self.stt: (*untyped, **untyped) -> bot
-    def self.greeting: (*untyped, **untyped) -> bot
-    def self.hangup: (*untyped, **untyped) -> bot
-    def self.says: (*untyped, **untyped) -> bot
-    def self.hears: (*untyped, **untyped) -> bot
-    def self.memory: (*untyped, **untyped) -> bot
-    def self.record: (*untyped, **untyped) -> bot
-    def self.knowledge: (*untyped, **untyped) -> bot
-    def self.docs: (*untyped, **untyped) -> bot
+    # the environment the class declares, each over the agent's settings
+    def self.voice: (?String, ?String?, ?model: String?, ?builds: String?, ?options: Hash[untyped, untyped]?) -> untyped
+    def self.llm: (?String, ?temperature: Float?, ?builds: String?, ?options: Hash[untyped, untyped]?) -> untyped
+    def self.stt: (?String, ?builds: String?, ?options: Hash[untyped, untyped]?, ?end_of_turn: (String | Symbol)?) -> untyped
+    def self.language: (?String) -> untyped
+    def self.says: (?Array[Hash[Symbol, String]]) -> untyped
+    def self.record: (?bool) -> untyped
+    def self.hears: (*String | Array[String]) -> untyped
+    def self.greeting: (?(String | Symbol | untyped), ?interruptible: bool?) -> untyped
+    def self.improvise: (?String, ?interruptible: bool?) -> untyped
+    def self.hangup: (?(String | true)) -> untyped
+    def self.turn: (**untyped) -> untyped
+    def self.knowledge: (**untyped) -> untyped
+    def self.docs: (**untyped) -> untyped
+    def self.memory: (**untyped) -> untyped
+    def self.environment: () -> Hash[Symbol, untyped]
 
     def self.doc: (?String) -> String?
     def self.slug: (?String) -> String

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinecall
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.6
 platform: ruby
 authors:
 - Pinecall