aven 0.0.3

data/app/services/aven/agentic/tool_result_formatter.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Aven
+  module Agentic
+    class ToolResultFormatter
+      MAX_RESULT_LENGTH = 50_000
+
+      class << self
+        # Format tool result for LLM consumption
+        # @param tool_name [String] Name of the tool
+        # @param result [Object] Raw result from tool execution
+        # @return [String] Formatted result string
+        def format(tool_name, result)
+          formatted = case result
+          when Array
+            format_array(result)
+          when Hash
+            format_hash(result)
+          when nil
+            "No results found."
+          else
+            result.to_s
+          end
+
+          truncate_if_needed(formatted)
+        end
+
+        private
+
+          def format_array(results)
+            return "No results found." if results.empty?
+
+            items = results.map.with_index do |item, idx|
+              case item
+              when Hash
+                format_hash_item(item, idx + 1)
+              else
+                "#{idx + 1}. #{item}"
+              end
+            end
+
+            "Found #{results.size} result(s):\n\n#{items.join("\n\n")}"
+          end
+
+          def format_hash(result)
+            result.map { |k, v| "#{k}: #{format_value(v)}" }.join("\n")
+          end
+
+          def format_hash_item(item, index)
+            lines = item.map { |k, v| "  #{k}: #{format_value(v)}" }
+            "#{index}.\n#{lines.join("\n")}"
+          end
+
+          def format_value(value)
+            case value
+            when Array
+              value.join(", ")
+            when Hash
+              value.to_json
+            when nil
+              "N/A"
+            else
+              value.to_s
+            end
+          end
+
+          def truncate_if_needed(text)
+            return text if text.length <= MAX_RESULT_LENGTH
+
+            truncated = text[0, MAX_RESULT_LENGTH]
+            "#{truncated}\n\n[Result truncated - showing first #{MAX_RESULT_LENGTH} characters]"
+          end
+      end
+    end
+  end
+end

data/app/services/aven/agentic/tools/base.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Aven
+  module Agentic
+    module Tools
+      class Base
+        # Parameter definition structure
+        Parameter = Struct.new(:name, :type, :description, :required, :constraints, keyword_init: true) do
+          def to_h
+            super.compact
+          end
+        end
+
+        class << self
+          # Tool name for registry
+          def tool_name
+            name.demodulize.underscore
+          end
+
+          # Default description (must be overridden in subclasses)
+          def default_description
+            raise NotImplementedError, "#{name} must define default_description"
+          end
+
+          # Parameter definitions - override in subclasses
+          # @return [Array<Parameter>]
+          def parameters
+            @parameters ||= []
+          end
+
+          # DSL for defining parameters
+          def param(name, type:, desc:, required: false, **constraints)
+            parameters << Parameter.new(
+              name:,
+              type:,
+              description: desc,
+              required:,
+              constraints: constraints.presence
+            )
+          end
+
+          # Get parameter by name
+          def parameter(name)
+            parameters.find { |p| p.name == name.to_sym }
+          end
+
+          # Main entry point - override in subclasses
+          def call(**params)
+            raise NotImplementedError, "#{name} must define call"
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/aven/agentic/tools/concerns/boolean_filtering.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Aven
+  module Agentic
+    module Tools
+      module Concerns
+        module BooleanFiltering
+          extend ActiveSupport::Concern
+
+          class_methods do
+            # Define boolean filter parameters
+            def boolean_filterable(name, column:, desc: nil)
+              @boolean_filters ||= {}
+              @boolean_filters[name] = { column: }
+
+              param name, type: :boolean, desc: desc || "Filter by #{name}", required: false
+            end
+
+            def boolean_filters
+              @boolean_filters || {}
+            end
+          end
+
+          # Apply boolean filtering to a scope
+          def apply_boolean_filters(scope, **params)
+            self.class.boolean_filters.each do |name, config|
+              value = params[name]
+              next if value.nil?
+
+              column = config[:column]
+              scope = scope.where(column => value)
+            end
+
+            scope
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/aven/agentic/tools/concerns/enum_filtering.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Aven
+  module Agentic
+    module Tools
+      module Concerns
+        module EnumFiltering
+          extend ActiveSupport::Concern
+
+          class_methods do
+            # Define enum filter parameters
+            def enum_filterable(name, column:, values:, desc: nil)
+              @enum_filters ||= {}
+              @enum_filters[name] = {
+                column:,
+                values:
+              }
+
+              param name, type: :string, desc: desc || "Filter by #{name}", required: false
+            end
+
+            def enum_filters
+              @enum_filters || {}
+            end
+          end
+
+          # Apply enum filtering to a scope
+          def apply_enum_filters(scope, **params)
+            self.class.enum_filters.each do |name, config|
+              value = params[name]
+              next if value.blank?
+
+              column = config[:column]
+              allowed = config[:values]
+
+              if allowed.include?(value)
+                scope = scope.where(column => value)
+              end
+            end
+
+            scope
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/aven/agentic/tools/concerns/geo_filtering.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Aven
+  module Agentic
+    module Tools
+      module Concerns
+        module GeoFiltering
+          extend ActiveSupport::Concern
+
+          class_methods do
+            # Define geo search parameters
+            def geo_searchable(lat_column: :latitude, lng_column: :longitude)
+              @geo_config = {
+                lat_column:,
+                lng_column:
+              }
+
+              param :latitude, type: :number, desc: "Latitude for geo search"
+              param :longitude, type: :number, desc: "Longitude for geo search"
+              param :radius_km, type: :number, desc: "Search radius in kilometers", required: false
+            end
+
+            def geo_config
+              @geo_config || {}
+            end
+          end
+
+          # Apply geo filtering to a scope
+          def apply_geo_filter(scope, lat:, lng:, radius_km: 50)
+            return scope if lat.blank? || lng.blank?
+
+            config = self.class.geo_config
+            lat_col = config[:lat_column]
+            lng_col = config[:lng_column]
+
+            # Haversine distance formula in SQL
+            distance_sql = <<~SQL.squish
+              (6371 * acos(
+                cos(radians(?)) *
+                cos(radians(#{lat_col})) *
+                cos(radians(#{lng_col}) - radians(?)) +
+                sin(radians(?)) *
+                sin(radians(#{lat_col}))
+              ))
+            SQL
+
+            scope
+              .where("#{lat_col} IS NOT NULL AND #{lng_col} IS NOT NULL")
+              .where("#{distance_sql} <= ?", lat, lng, lat, radius_km)
+              .order(Arel.sql("#{distance_sql} ASC").gsub("?", lat.to_s).gsub("?", lng.to_s))
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/aven/agentic/tools/concerns/range_filtering.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Aven
+  module Agentic
+    module Tools
+      module Concerns
+        module RangeFiltering
+          extend ActiveSupport::Concern
+
+          class_methods do
+            # Define range filter parameters (min/max)
+            def range_filterable(name, column:, type: :integer, desc: nil)
+              @range_filters ||= {}
+              @range_filters[name] = { column: }
+
+              param_type = type == :integer ? :number : :number
+
+              param "#{name}_min".to_sym,
+                type: param_type,
+                desc: desc || "Minimum #{name}",
+                required: false
+
+              param "#{name}_max".to_sym,
+                type: param_type,
+                desc: desc || "Maximum #{name}",
+                required: false
+            end
+
+            def range_filters
+              @range_filters || {}
+            end
+          end
+
+          # Apply range filtering to a scope
+          def apply_range_filters(scope, **params)
+            self.class.range_filters.each do |name, config|
+              column = config[:column]
+              min_val = params["#{name}_min".to_sym]
+              max_val = params["#{name}_max".to_sym]
+
+              scope = scope.where("#{column} >= ?", min_val) if min_val.present?
+              scope = scope.where("#{column} <= ?", max_val) if max_val.present?
+            end
+
+            scope
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/aven/chat/broadcaster.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Aven
+  module Chat
+    class Broadcaster
+      def initialize(thread)
+        @thread = thread
+      end
+
+      # Broadcast message update
+      def broadcast_update(message, **extras)
+        broadcast({
+          type: "message_updated",
+          message: message.as_json.merge(extras)
+        })
+      end
+
+      # Broadcast tool call started
+      def broadcast_tool_call(message)
+        broadcast({
+          type: "tool_call",
+          message: {
+            id: message.id,
+            tool_name: message.tool_call&.dig("name"),
+            status: "calling"
+          }
+        })
+      end
+
+      # Broadcast tool result
+      def broadcast_tool_result(message)
+        broadcast({
+          type: "tool_result",
+          message: {
+            id: message.id,
+            tool_call: message.tool_call
+          }
+        })
+      end
+
+      # Broadcast streaming content
+      def broadcast_streaming(message, content)
+        broadcast({
+          type: "message_streaming",
+          message: {
+            id: message.id,
+            content:
+          }
+        })
+      end
+
+      private
+
+        def broadcast(payload)
+          Aven::Chat::ThreadChannel.broadcast_to(@thread, payload)
+        end
+    end
+  end
+end

data/app/services/aven/chat/config.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Aven
+  module Chat
+    class Config
+      DEFAULT_MODEL = "claude-sonnet-4-5-20250929"
+      DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant."
+
+      class << self
+        def model
+          Aven.configuration.agentic&.default_model || DEFAULT_MODEL
+        end
+
+        def system_prompt(user: nil, thread: nil)
+          parts = [base_system_prompt]
+
+          # Inject locked documents OCR content into system prompt
+          if thread&.documents_locked?
+            docs = thread.locked_documents
+            if docs.any?
+              docs_content = docs.map do |doc|
+                "### #{doc.filename}\n\n#{doc.ocr_content}"
+              end.join("\n\n---\n\n")
+
+              parts << <<~TEXT
+                ## Reference Documents
+
+                The following documents are provided as context for this conversation.
+                Use them to answer the user's questions.
+
+                #{docs_content}
+              TEXT
+            end
+          end
+
+          parts.compact.join("\n\n")
+        end
+
+        # Returns tools available for a thread.
+        # - If thread.tools is nil: all tools are available (free-form chat)
+        # - If thread.tools is an array: only those tools are available (locked by agent)
+        def tools(thread = nil)
+          workspace = thread&.workspace
+          all_tools = Aven::Agentic::DynamicToolBuilder.build_all(workspace:)
+
+          return all_tools unless thread&.tools_locked?
+
+          locked_names = thread.tools
+          return [] if locked_names.empty?
+
+          all_tools.select { |tool| locked_names.include?(tool.tool_name) }
+        end
+
+        # Calculate cost in USD based on token counts.
+        def calculate_cost(input_tokens:, output_tokens:, model_id:)
+          pricing = pricing_for(model_id)
+          return nil unless pricing
+
+          input_cost = (input_tokens.to_f / 1_000_000) * pricing[:input]
+          output_cost = (output_tokens.to_f / 1_000_000) * pricing[:output]
+          input_cost + output_cost
+        end
+
+        private
+
+          def base_system_prompt
+            configured = Aven.configuration.agentic&.system_prompt
+            return configured.call if configured.respond_to?(:call)
+
+            configured || DEFAULT_SYSTEM_PROMPT
+          end
+
+          def pricing_for(model_id)
+            Rails.cache.fetch("aven/llm_pricing/#{model_id}", expires_in: 24.hours) do
+              fetch_pricing(model_id)
+            end
+          end
+
+          def fetch_pricing(model_id)
+            return nil unless defined?(RubyLLM)
+
+            model = RubyLLM.models.find(model_id)
+            tier = model&.pricing&.text_tokens&.standard
+            return nil unless tier
+
+            { input: tier.input_per_million, output: tier.output_per_million }
+          rescue
+            nil
+          end
+      end
+    end
+  end
+end

data/app/services/aven/chat/message_builder.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Aven
+  module Chat
+    class MessageBuilder
+      def initialize(thread)
+        @thread = thread
+      end
+
+      # Build message array for LLM from thread history
+      # @return [Array<Hash>] Messages in LLM format
+      def build
+        @thread.messages
+          .chronological
+          .where.not(role: :tool)  # Tool messages handled separately
+          .where(status: :success)
+          .map { |msg| format_message(msg) }
+          .compact
+      end
+
+      private
+
+        def format_message(message)
+          return nil if message.content.blank? && !message.role_system?
+
+          {
+            role: llm_role(message.role),
+            content: message.content || ""
+          }
+        end
+
+        def llm_role(role)
+          case role.to_sym
+          when :user then :user
+          when :assistant then :assistant
+          when :system then :system
+          else :user
+          end
+        end
+    end
+  end
+end

data/app/services/aven/chat/orchestrator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Aven
+  module Chat
+    class Orchestrator
+      def initialize(thread)
+        @thread = thread
+      end
+
+      # Run chat for a user message
+      # @param user_message [Aven::Chat::Message] The user's message
+      def run(user_message)
+        assistant_message = create_assistant_message(user_message)
+        generate_title_if_first_message(user_message)
+
+        begin
+          messages = MessageBuilder.new(@thread).build
+          response = Runner.new(@thread, assistant_message).run(messages)
+
+          assistant_message.mark_completed!(
+            content: response.content,
+            model: response.model_id,
+            tokens: {
+              input: response.input_tokens,
+              output: response.output_tokens,
+              total: response.input_tokens + response.output_tokens
+            }
+          )
+
+          # Calculate cost async
+          CalculateCostJob.perform_later(assistant_message.id)
+        rescue => e
+          assistant_message.mark_failed!(e.message)
+          raise
+        end
+      end
+
+      private
+
+        def create_assistant_message(user_message)
+          message = @thread.messages.create!(
+            role: :assistant,
+            parent: user_message,
+            status: :pending
+          )
+          message.mark_started!
+          message
+        end
+
+        def generate_title_if_first_message(user_message)
+          return unless first_user_message?(user_message)
+
+          # Generate title in background thread
+          ::Thread.new do
+            TitleGenerator.new(@thread, user_message).call
+          rescue => e
+            Rails.logger.error("[Aven::Chat] Title generation error: #{e.message}")
+          end
+        end
+
+        def first_user_message?(user_message)
+          @thread.messages
+            .where(role: :user)
+            .where.not(id: user_message.id)
+            .none?
+        end
+    end
+  end
+end

data/app/services/aven/chat/runner.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Aven
+  module Chat
+    class Runner
+      def initialize(thread, assistant_message)
+        @thread = thread
+        @assistant_message = assistant_message
+        @broadcaster = Broadcaster.new(thread)
+        @full_content = ""
+        @current_tool_call = nil
+      end
+
+      # Run LLM chat with streaming
+      # @param messages [Array<Hash>] Message history
+      # @return [OpenStruct] Response with content, model_id, tokens
+      def run(messages)
+        chat = build_chat
+
+        # Add conversation history (all messages except the last)
+        messages[0..-2].each do |msg|
+          chat.add_message(role: msg[:role].to_sym, content: msg[:content])
+        end
+
+        # Ask with the last message
+        response = chat.ask(messages.last[:content]) do |chunk|
+          handle_stream_chunk(chunk)
+        end
+
+        build_response(response)
+      end
+
+      private
+
+        def build_chat
+          chat = RubyLLM.chat(model: Config.model)
+            .with_instructions(Config.system_prompt(thread: @thread))
+            .with_tools(*Config.tools(@thread))
+
+          chat.on_tool_call do |tool_call|
+            handle_tool_call(tool_call)
+          end
+
+          chat.on_tool_result do |result|
+            handle_tool_result(result)
+          end
+
+          chat
+        end
+
+        def handle_stream_chunk(chunk)
+          return unless chunk.content
+
+          @full_content += chunk.content
+          @assistant_message.append_content!(chunk.content)
+        end
+
+        def handle_tool_call(tool_call)
+          @current_tool_call = tool_call
+
+          tool_message = @thread.messages.create!(
+            role: :tool,
+            parent: @assistant_message.parent,
+            status: :streaming,
+            content: tool_call.name,
+            tool_call: {
+              id: tool_call.id,
+              name: tool_call.name,
+              arguments: tool_call.arguments,
+              status: "calling"
+            }
+          )
+
+          @broadcaster.broadcast_tool_call(tool_message)
+          tool_message
+        end
+
+        def handle_tool_result(result)
+          return unless @current_tool_call
+
+          tool_message = @thread.messages.by_tool_call_id(@current_tool_call.id).first
+          return unless tool_message
+
+          tool_message.update!(
+            status: :success,
+            tool_call: tool_message.tool_call.merge(
+              "result" => result,
+              "status" => "completed"
+            )
+          )
+
+          @broadcaster.broadcast_tool_result(tool_message)
+        end
+
+        def build_response(response)
+          OpenStruct.new(
+            content: @full_content,
+            model_id: response.model_id,
+            input_tokens: response.input_tokens || 0,
+            output_tokens: response.output_tokens || 0
+          )
+        end
+    end
+  end
+end