pinecall 0.0.1

data/lib/pinecall/agent/config.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+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.
+    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
+
+      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"
+      end
+
+      module Declaring
+        # Called with no argument, each reads the (possibly inherited) value.
+        AS_WRITTEN.each do |field|
+          define_method(field) do |value = NOTHING|
+            return config[field] if value.equal?(NOTHING)
+
+            config[field] = value
+          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)
+          end
+        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)
+
+          @pinecall_doc = text
+        end
+
+        # Accept an external event from `:app` (the application's backend) or `:participant`
+        # (a browser). Undeclared events never reach `on_event`.
+        def accepts(name, from:)
+          declared_events[name.to_s] = Array(from).map(&:to_s)
+        end
+
+        def declared_events
+          @declared_events ||= superclass.respond_to?(:declared_events) ? superclass.declared_events.dup : {}
+        end
+
+        # Declared config, including inherited values.
+        def config
+          @config ||= superclass.respond_to?(:config) ? superclass.config.dup : {}
+        end
+
+        # The slug the class names itself, or nil when it names none.
+        def declared_slug = @slug
+
+        # Registration slug; defaults to the class name in kebab-case.
+        def slug(name = NOTHING)
+          return (@slug || default_slug) if name.equal?(NOTHING)
+
+          @slug = name
+        end
+
+        # The AgentConfig sent to the gateway.
+        def wire_config(tools: nil)
+          {
+            prompt: Prompt::FRAMEWORK,
+            tools:,
+            state_fields: state_field_specs,
+            events: event_specs,
+            # Only the name: the panel is drawn on demand, by `view.render`.
+            view: (declared_panel && { name: declared_panel.name }),
+            uses_knowledge: (true if Searching.searches?(self))
+          }.compact
+        end
+
+        def state_field_specs
+          declared = state_visibility
+          return nil if declared.empty?
+
+          declared.map { |name, visibility| { name: name.to_s, visibility: visibility.to_s } }
+        end
+
+        def event_specs
+          return nil if declared_events.empty?
+
+          declared_events.map { |name, from| { name:, from: } }
+        end
+
+        private
+
+        def default_slug
+          (name || "agent").split("::").last
+                           .gsub(/([a-z0-9])([A-Z])/, '\1-\2')
+                           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2')
+                           .downcase
+        end
+      end
+    end
+  end
+end

data/lib/pinecall/agent/doc.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Agent
+    # Reads the comment above a class or method from its source file; that comment is the prompt.
+    #
+    # Ruby drops `#` comments, so this uses `source_location` and walks up from the `def`,
+    # skipping declaration macros in between:
+    #
+    #     # Busca al paciente por nombre y teléfono.
+    #     tool stage: :identify, pii: %i[name phone]
+    #     def find_patient(name:, phone:)
+    #
+    # A class built at runtime has no source file; it declares its text with `doc "…"`.
+    module Doc
+      # Stops the upward walk when no comment was found.
+      ENDS_WHAT_CAME_BEFORE = /\A\s*(end\b|def\b|class\b|module\b)/
+      COMMENT = /\A\s*#(?!\s*(frozen_string_literal|rubocop|:nodoc:))\s?(.*)\z/
+
+      class << self
+        # The comment above the class's `class` line, or nil.
+        def for_class(klass)
+          declared = klass.instance_variable_get(:@pinecall_doc)
+          return declared unless declared.nil?
+          return nil if klass.name.nil?
+
+          where = Object.const_source_location(klass.name)
+          where.nil? ? nil : above(*where)
+        end
+
+        # The comment above one method of a class, or nil.
+        def for_method(klass, name)
+          where = klass.instance_method(name).source_location
+          where.nil? ? nil : above(*where)
+        end
+
+        # The comment block ending just above `line` of `file`, or nil.
+        def above(file, line)
+          lines = source(file)
+          return nil if lines.empty?
+
+          # Skip the declaration lines above the `def`; a blank line ends the walk, so the
+          # comment must sit directly above.
+          at = line - 2
+          at -= 1 while at >= 0 && !lines[at].match?(COMMENT) &&
+                        !lines[at].strip.empty? && !lines[at].match?(ENDS_WHAT_CAME_BEFORE)
+          block = []
+          while at >= 0 && (said = lines[at].match(COMMENT))
+            block.unshift(said[2].rstrip)
+            at -= 1
+          end
+          one_line(block)
+        end
+
+        # A comment as the model reads it: one line, its blank lines dropped, ending at the first
+        # tag line (`@param`). Word for word what the TypeScript package does to a JSDoc.
+        def one_line(block)
+          said = block.map(&:strip).take_while { |line| !line.start_with?("@") }.reject(&:empty?)
+          said.empty? ? nil : said.join(" ")
+        end
+
+        # Cached per process so a running agent never reads the disk between turns.
+        def source(file)
+          @source ||= {}
+          @source[file] ||= File.exist?(file) ? File.readlines(file, chomp: true) : []
+        end
+
+        # Clear the cache; for tests that rewrite and reload a file.
+        def forget = @source = {}
+      end
+    end
+  end
+end

data/lib/pinecall/agent/knowledge.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# What a class reaches its bases through: one verb, answered by the gateway for the call in hand.
+
+module Pinecall
+  class Agent
+    # `knowledge.search("…", k: 3)` inside a tool: the bases attached to the agent, searched for
+    # this call by the gateway, which logs what it found.
+    class Knowledge
+      def initialize(agent)
+        @agent = agent
+      end
+
+      # The chunks found, each a `CallWorld::Found`.
+      def search(query, k: nil) = @agent.call.search(query, k:)
+    end
+  end
+end

data/lib/pinecall/agent/searching.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "ripper"
+
+# Whether a class searches its knowledge bases, read off its own source with Ripper's tokens.
+
+module Pinecall
+  class Agent
+    # A token walk, not a regex: `knowledge.search` inside a string or a comment is one token of
+    # another kind, and does not count. Any method of the file counts, not only tools.
+    module Searching
+      SEARCHES = [%w[knowledge . search], %w[call . search]].freeze
+
+      module_function
+
+      # Whether the class's file calls `knowledge.search` or `call.search`. Sent at registration as
+      # `uses_knowledge`, so a world with no base attached is refused when the agent registers.
+      def searches?(klass)
+        file = Object.const_source_location(klass.name.to_s)&.first
+        return false if file.nil? || !File.exist?(file)
+
+        in_source?(File.read(file))
+      end
+
+      def in_source?(source)
+        words = Ripper.lex(source).filter_map do |(_, kind, token)|
+          token if %i[on_ident on_period on_op].include?(kind) || (kind == :on_kw && token == "self")
+        end
+        words.each_cons(3).any? { |three| SEARCHES.include?(three) }
+      end
+    end
+  end
+end

data/lib/pinecall/agent/spec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Agent
+    # Builds and validates a tool's wire spec.
+    #
+    # A model fills arguments by name, so tools take keyword arguments only. Names come from the
+    # method signature, types from `params:`.
+    module Spec
+      A_NAME_A_MODEL_CAN_CALL = /\A[A-Za-z][A-Za-z0-9_]*\z/
+
+      # Schema for a parameter with no declared type.
+      TEXT = { type: "string" }.freeze
+
+      class << self
+        # Rewrite `stage:` as a `when`, so visibility has a single form.
+        def lower(klass, name, options)
+          wanted = options[:stage]
+          return options if wanted.nil?
+
+          wanted = Array(wanted).map(&:to_sym)
+          refuse_a_stage_the_class_does_not_declare(klass, name, wanted)
+          asked = options[:when]
+          in_stage = ->(state) { wanted.include?(state[:stage]) && (asked.nil? || Tools.ask(asked, state)) }
+          options.merge(when: in_stage)
+        end
+
+        # Build the wire spec, refusing what the gateway would refuse.
+        def build(klass, name, options)
+          refuse_a_name_no_model_can_call(name)
+          method = klass.instance_method(name)
+          spec = {
+            name: name.to_s,
+            description: description!(klass, name, options),
+            parameters: parameters(method, options[:params] || {}),
+            side_effect: options[:confirm] ? "irreversible" : "read"
+          }
+          spec[:confirm] = options[:confirm] if options[:confirm]
+          spec[:pii] = pii!(options, spec) if options[:pii]
+          spec[:timeout_s] = options[:timeout].to_f if options[:timeout]
+          Wire::Validate.call!("ToolSpec", spec, where: "tool #{name}")
+          spec.freeze
+        end
+
+        # JSON Schema from the method's keyword names and declared types.
+        def parameters(method, declared)
+          properties = {}
+          required = []
+          method.parameters.each do |kind, called|
+            next if kind == :block
+
+            refuse_an_argument_a_model_cannot_fill(method, kind, called)
+            properties[called] = schema_of(declared[called])
+            required << called.to_s if kind == :keyreq
+          end
+          { type: "object", properties:, required:, additionalProperties: false }
+        end
+
+        # Accepts a class, a one-element array of a class, or a raw JSON Schema hash.
+        def schema_of(declared)
+          case declared
+          when nil then TEXT
+          when Hash then declared
+          when Array then { type: "array", items: schema_of(declared.first) }
+          when Class then of_class(declared)
+          else TEXT
+          end
+        end
+
+        def of_class(klass)
+          case klass.name
+          when "Integer" then { type: "integer" }
+          when "Float", "Numeric" then { type: "number" }
+          when "TrueClass", "FalseClass" then { type: "boolean" }
+          when "Array" then { type: "array", items: TEXT }
+          when "Hash" then { type: "object", additionalProperties: true }
+          else TEXT
+          end
+        end
+
+        # ── validation ─────────────────────────────────────────────────────────
+
+        def description!(klass, name, options)
+          said = options[:doc] || Doc.for_method(klass, name)
+          return said unless said.nil? || said.empty?
+
+          raise DeclarationRefused,
+                "tool #{name}: without a docstring no model can choose it; write a `# one line` " \
+                "comment above it, or pass doc: \"…\" for a class with no source to read"
+        end
+
+        def pii!(options, spec)
+          wanted = Array(options[:pii]).map(&:to_sym)
+          unknown = wanted - spec[:parameters][:properties].keys
+          return wanted.map(&:to_s) if unknown.empty?
+
+          raise DeclarationRefused,
+                "tool #{spec[:name]}: pii names parameters the tool has; unknown: #{unknown.join(", ")}"
+        end
+
+        def refuse_a_name_no_model_can_call(name)
+          return if A_NAME_A_MODEL_CAN_CALL.match?(name.to_s)
+
+          raise DeclarationRefused, "a tool name is one word a model can call, not #{name}"
+        end
+
+        def refuse_an_argument_a_model_cannot_fill(method, kind, called)
+          return if %i[key keyreq].include?(kind)
+
+          raise DeclarationRefused,
+                "tool #{method.name}: a model fills a JSON object by name, so a tool takes " \
+                "keyword arguments; #{called || kind} is not one"
+        end
+
+        def refuse_a_stage_the_class_does_not_declare(klass, name, wanted)
+          declared = klass.stages
+          if declared.nil?
+            raise DeclarationRefused,
+                  "tool #{name}: stage names a value of this agent's own stage field, and " \
+                  "#{klass.name || "this class"} declares none; add `stage :identify, :book` to " \
+                  "the class, or ask `when:` instead"
+          end
+          unknown = wanted - declared
+          return if unknown.empty?
+
+          raise DeclarationRefused,
+                "tool #{name}: #{unknown.join(", ")} is not one of this agent's stages " \
+                "(#{declared.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/lib/pinecall/agent/state.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Agent
+    # One recorded field assignment.
+    Change = Data.define(:seq, :field, :prev, :next, :author, :at)
+
+    # One named entry the agent appended to the call's log.
+    LogEntry = Data.define(:seq, :name, :data, :at)
+
+    # Declared state fields. The writer each `state` macro generates records every change.
+    module State
+      module Declaring
+        # Declare a state field and its initial value.
+        #
+        #     state :patient, visibility: :pii  # nil until a tool finds one
+        #     state :slots, []                  # a list of its own, per call
+        #     state(:identified) { !patient.nil? }
+        #
+        # A block makes the field derived: readable like any other, never assignable.
+        #
+        # @param visibility [Symbol] `:public`, `:tenant` or `:pii`; omitted means the wire
+        #   default (`tenant`) and nothing is sent.
+        def state(name, default = nil, visibility: nil, &derived)
+          name = name.to_sym
+          refuse_a_name_that_is_taken(name)
+          state_visibility[name] = visibility unless visibility.nil?
+          if derived
+            derived_state[name] = derived
+            define_method(name) { instance_exec(&self.class.derived_state[name]) }
+            return name
+          end
+          declared_state[name] = default
+          define_method(name) { @state[name] }
+          define_method(:"#{name}=") { |value| write_state(name, value) }
+          name
+        end
+
+        # Declare the `stage` field and its values; the first is the initial one.
+        #
+        #     stage :identify, :choose, :book, :done
+        #
+        # A tool's `stage:` naming an undeclared stage is refused at load, since that tool
+        # could never be visible.
+        def stage(*names)
+          raise DeclarationRefused, "stage names the values the stage may hold; give at least one" if names.empty?
+
+          @stages = names.map(&:to_sym)
+          state(:stage, @stages.first)
+          @stages
+        end
+
+        # The declared stage values, inherited if not declared here.
+        def stages
+          @stages || (superclass.respond_to?(:stages) ? superclass.stages : nil)
+        end
+
+        # Declared fields and initial values, including inherited ones.
+        def declared_state
+          @declared_state ||= inherit(:declared_state)
+        end
+
+        # Derived fields by name.
+        def derived_state
+          @derived_state ||= inherit(:derived_state)
+        end
+
+        # Visibility by field, for fields that declared one.
+        def state_visibility
+          @state_visibility ||= inherit(:state_visibility)
+        end
+
+        def state_names = declared_state.keys + derived_state.keys
+
+        private
+
+        def inherit(what)
+          superclass.respond_to?(what) ? superclass.public_send(what).dup : {}
+        end
+
+        def refuse_a_name_that_is_taken(name)
+          return unless declared_state.key?(name) || derived_state.key?(name)
+
+          raise DeclarationRefused, "#{self.name || "this agent"} declares #{name} twice"
+        end
+      end
+
+      # ── instance methods ─────────────────────────────────────────────────────
+
+      # A copy of the current state, derived fields included.
+      def snapshot
+        kept = @state.dup
+        self.class.derived_state.each_key { |name| kept[name] = public_send(name) }
+        kept
+      end
+
+      # Replace the state with a snapshot; fields missing from it are cleared. A stage that came
+      # back as JSON is a string, and is the declared stage it names.
+      def restore(state)
+        state = state.transform_keys(&:to_sym)
+        Author.with(Author.current || "restore") do
+          self.class.declared_state.each_key do |name|
+            value = state.key?(name) ? state[name] : nil
+            write_state(name, name == :stage ? declared_stage(value) : value)
+          end
+        end
+        self
+      end
+
+
+      # Merge the given fields over the current state (unlike `restore`, which clears the rest).
+      def start_in(state)
+        restore(snapshot.merge(state.transform_keys(&:to_sym)))
+      end
+
+      # Fields that differ between two snapshots.
+      def diff(before, after = snapshot)
+        (before.keys | after.keys).filter_map do |field|
+          { field:, prev: before[field], next: after[field] } if before[field] != after[field]
+        end
+      end
+
+      # Replace the change log with one summary entry; the state itself is untouched.
+      def collapse(summary)
+        at = now
+        @changes.clear
+        @changes << Change.new(seq: next_seq, field: "@summary", prev: nil, next: summary,
+                               author: "collapse", at:)
+        @changes.last
+      end
+
+      # Recorded changes, oldest first.
+      def changes = @changes.dup
+
+      # Subscribe to changes; the returned lambda unsubscribes.
+      def on_change(&listener)
+        @change_listeners << listener
+        -> { @change_listeners.delete(listener) }
+      end
+
+      # Start recording changes; earlier writes are the baseline.
+      def seal
+        @sealed = true
+        self
+      end
+
+      def sealed? = @sealed
+
+      private
+
+      def declared_stage(value)
+        named = self.class.stages&.find { |stage| stage.to_s == value.to_s }
+        named.nil? ? value : named
+      end
+
+      # Every state write goes through here; after `seal` a write without an author raises.
+      def write_state(field, value)
+        if @sealed
+          author = Author.current
+          raise UnauthoredWrite, field if author.nil?
+
+          previous = @state[field]
+          @state[field] = value
+          # An equal value is not a change: no re-render, no log entry.
+          return value if previous == value
+
+          record(Change.new(seq: next_seq, field:, prev: previous, next: value, author:, at: now))
+        else
+          @state[field] = value
+        end
+        value
+      end
+
+      def record(change)
+        @changes << change
+        @change_listeners.each { |listener| listener.call(change) }
+        change
+      end
+
+      def next_seq = @seq += 1
+
+      def now = Time.now.to_f
+    end
+  end
+end

data/lib/pinecall/agent/tools.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Agent
+    # One declared tool: its local options and the spec sent on the wire.
+    Declaration = Data.define(:name, :options, :spec)
+
+    # Tool declaration and visibility. `tool` marks the next method defined, like Sorbet's `sig`.
+    module Tools
+      module Declaring
+        # Declare the next method as a tool.
+        #
+        #     # Reserva la hora que el paciente ya ha confirmado.
+        #     tool stage: :book, confirm: "Le reservo el {{chosen}}. ¿Lo confirmo?"
+        #     def book(chosen:)
+        #
+        # @param when [Proc] visibility predicate, evaluated against the state
+        # @param stage [Symbol, Array<Symbol>] shorthand for a `when` on the stage field
+        # @param confirm [String] read-back spoken before running; marks the tool irreversible
+        # @param preview [Integer] rows of a list result the model sees
+        # @param pii [Array<Symbol>] parameters with personal data, masked in the log
+        # @param timeout [Numeric] seconds the platform waits for the method
+        # @param params [Hash{Symbol=>Object}] parameter types, e.g. `{ day: String, how_many: Integer }`
+        def tool(**options)
+          unknown = options.keys - %i[when stage confirm preview pii timeout params doc]
+          raise DeclarationRefused, "@tool takes no #{unknown.join(", ")}" unless unknown.empty?
+
+          @pending_tool = options
+        end
+
+        # Attaches a pending `tool` declaration to the method just defined.
+        def method_added(name)
+          super
+          options = @pending_tool
+          return if options.nil?
+
+          @pending_tool = nil
+          declare_tool(name, options)
+        end
+
+        # Declared tools by name, including inherited ones.
+        def declared_tools
+          @declared_tools ||= superclass.respond_to?(:declared_tools) ? superclass.declared_tools.dup : {}
+        end
+
+        def tool_named(name) = declared_tools[name.to_sym]
+
+        # Validate at load what the gateway would refuse later.
+        def declare_tool(name, options)
+          options = Spec.lower(self, name, options)
+          spec = Spec.build(self, name, options)
+          declared_tools[name.to_sym] = Declaration.new(name: name.to_sym, options:, spec:)
+        end
+      end
+
+      # ── instance methods ─────────────────────────────────────────────────────
+
+      # The class comment, sent as the top of the prompt.
+      def doc = Doc.for_class(self.class)
+
+      # Every declared tool spec, visible or not.
+      def tools = self.class.declared_tools.values.map(&:spec)
+
+      # Tool specs whose `when` holds for the current state.
+      def visible_tools = visible_declarations.map(&:spec)
+
+      def visible_declarations
+        state = snapshot
+        self.class.declared_tools.values.select { |declared| Tools.shows?(declared, state) }
+      end
+
+      # Run a tool as the bridge does, with its writes attributed to it.
+      def run_tool(name, arguments = {})
+        declared = self.class.tool_named(name)
+        raise ToolFailed, "#{name}: this agent declares no such tool" if declared.nil?
+
+        Tools.run(self, declared, arguments)
+      end
+
+      class << self
+        # `stage:` was already lowered to a `when` at declaration.
+        def shows?(declared, state)
+          asked = declared.options[:when]
+          asked.nil? || ask(asked, state)
+        end
+
+        # A `when` may take the state as an argument (`->(s) { s.slots.any? }`) or be evaluated
+        # against it (`-> { slots.any? }`).
+        def ask(asked, state)
+          reading = state.is_a?(Reading) ? state : Reading.new(state)
+          asked.arity.zero? ? reading.instance_exec(&asked) : asked.call(reading)
+        end
+
+        # Check arguments, run the method with its writes attributed, and trim to `preview`.
+        def run(agent, declared, arguments)
+          named = arguments.to_h { |key, value| [key.to_sym, value] }
+          refuse_arguments_the_tool_never_asked_for(declared, named)
+          result = Author.with(declared.name.to_s) { agent.public_send(declared.name, **named) }
+          preview(result, declared.options[:preview])
+        end
+
+        # Trims only what the model sees; state keeps every row.
+        def preview(result, rows)
+          return result unless rows.is_a?(Integer) && result.is_a?(Array) && result.size > rows
+
+          result.first(rows)
+        end
+
+        def refuse_arguments_the_tool_never_asked_for(declared, named)
+          declared_names = (declared.spec[:parameters][:properties] || {}).keys
+          unknown = named.keys - declared_names
+          return if unknown.empty?
+
+          raise ToolFailed, "#{declared.name}: it takes no #{unknown.join(", ")}"
+        end
+      end
+    end
+  end
+end