solid_agent 0.0.0 → 0.2.0

data/lib/solid_agent/has_memory.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+# HasMemory gives an agent a persistent, agent-curated summary list — the
+# model decides when to read and write it while interacting with tools,
+# other agents, and users.
+#
+# Memory is scoped to a subject record (any ActiveRecord model) plus a
+# scope name, NOT to the agent class — so a memory written by one agent can
+# be recalled by another operating on the same subject. That makes it a
+# handoff channel: agent A records what it learned/did, agent B picks the
+# subject up and recalls the summary before continuing.
+#
+# The concern is duck-typed against a memory model exposing:
+#   Model.for(memorable, scope:)  -> memory record
+#   memory.remember(content, source_agent:, category:) -> entry
+#   memory.recall(limit:, category:) -> entries (responding to #content)
+# The install generator's AgentMemory implements this contract.
+#
+# @example Give an agent memory tools the model can call
+#   class SupportAgent < ApplicationAgent
+#     include SolidAgent::HasMemory
+#     has_memory
+#
+#     def handle
+#       prompt(message: params[:message], tools: memory_tool_definitions)
+#     end
+#   end
+#
+# @example Handoff between agents sharing a subject
+#   ResearchAgent.with(memorable: project).research.generate_now
+#   # later, a different agent class:
+#   WriterAgent.with(memorable: project).draft.generate_now
+#   # WriterAgent's recall_memory returns ResearchAgent's entries too.
+module SolidAgent
+  module HasMemory
+    extend ActiveSupport::Concern
+
+    DEFAULT_SCOPE = "default"
+
+    # Function-calling schemas (common format) for the two memory tools.
+    # Exposed as a module method so non-agent callers (platform executors,
+    # MCP servers) can reuse the exact same contract.
+    def self.tool_definitions
+      [
+        {
+          name: "save_memory",
+          description: "Persist a short summary note to long-term memory. Use for facts, decisions, task outcomes, or anything a future agent or session should know. Keep each note self-contained.",
+          parameters: {
+            type: "object",
+            properties: {
+              content: { type: "string", description: "The summary note to remember" },
+              category: { type: "string", description: "Optional label, e.g. fact, task, handoff" }
+            },
+            required: [ "content" ]
+          }
+        },
+        {
+          name: "recall_memory",
+          description: "Read back previously saved memory notes for the current subject, most recent first. Use before starting work to pick up prior context or another agent's handoff.",
+          parameters: {
+            type: "object",
+            properties: {
+              category: { type: "string", description: "Only return notes with this label" },
+              limit: { type: "integer", description: "Maximum notes to return (default 20)" }
+            },
+            required: []
+          }
+        }
+      ]
+    end
+
+    included do
+      class_attribute :_memory_config, default: nil
+    end
+
+    class_methods do
+      # Configures memory for this agent.
+      #
+      # @param scope [String, Symbol] memory namespace (default "default")
+      # @param class_name [String] memory model (default "AgentMemory")
+      def has_memory(scope: DEFAULT_SCOPE, class_name: "AgentMemory")
+        self._memory_config = { scope: scope.to_s, class_name: class_name }
+      end
+    end
+
+    # The memory record for the current subject (or nil without a subject).
+    def memory
+      config = self.class._memory_config || { scope: DEFAULT_SCOPE, class_name: "AgentMemory" }
+      subject = memory_subject
+      return nil unless subject
+
+      @memory ||= config[:class_name].constantize.for(subject, scope: config[:scope])
+    end
+
+    # The record memory is attached to. Defaults to params[:memorable],
+    # falling back to the HasContext contextable when present. Override for
+    # custom subjects.
+    def memory_subject
+      return params[:memorable] if respond_to?(:params) && params.is_a?(Hash) && params[:memorable]
+
+      context.contextable if respond_to?(:context) && context.respond_to?(:contextable)
+    rescue StandardError
+      nil
+    end
+
+    def memory_tool_definitions
+      SolidAgent::HasMemory.tool_definitions
+    end
+
+    # Tool implementations — routed here by the provider's tool calls.
+
+    def save_memory(content:, category: nil)
+      return { error: "No memory subject available" } unless memory
+
+      entry = memory.remember(content, source_agent: self.class.name, category: category)
+      { saved: true, id: entry.respond_to?(:id) ? entry.id : nil, content: content }
+    end
+
+    def recall_memory(category: nil, limit: 20)
+      return { error: "No memory subject available" } unless memory
+
+      entries = memory.recall(limit: limit, category: category)
+      {
+        count: entries.size,
+        entries: entries.map do |entry|
+          {
+            content: entry.content,
+            category: (entry.category if entry.respond_to?(:category)),
+            source_agent: (entry.source_agent if entry.respond_to?(:source_agent)),
+            created_at: (entry.created_at.iso8601 if entry.respond_to?(:created_at) && entry.created_at)
+          }.compact
+        end
+      }
+    end
+  end
+end

data/lib/solid_agent/has_reasons.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  # HasReasons provides reasoning/thinking trace collection for agents.
+  #
+  # This concern enables agents to capture and track extended thinking
+  # from LLMs that support it (Claude's extended thinking, OpenAI o1, etc.).
+  #
+  # Reasoning traces are captured separately from the main response content,
+  # allowing for:
+  # - Transparent AI decision-making
+  # - Debugging and analysis of AI behavior
+  # - Audit trails for compliance
+  # - Cost tracking (reasoning tokens)
+  #
+  # @example Basic usage
+  #   class ResearchAgent < ApplicationAgent
+  #     include SolidAgent::HasReasons
+  #
+  #     def analyze
+  #       result = prompt(
+  #         messages: research_messages,
+  #         extended_thinking: true  # Enable extended thinking
+  #       )
+  #
+  #       # Reasoning is automatically captured
+  #       last_reasoning.content  #=> "Let me analyze this systematically..."
+  #       total_reasoning_tokens  #=> 450
+  #     end
+  #   end
+  #
+  # @example Configuring reasoning capture
+  #   class AnalysisAgent < ApplicationAgent
+  #     include SolidAgent::HasReasons
+  #
+  #     has_reasons(
+  #       auto_capture: true,        # Auto-capture from all generations
+  #       persist: true,             # Persist to database
+  #       budget_tokens: 10000       # Default reasoning token budget
+  #     )
+  #   end
+  #
+  # @example Accessing reasoning history
+  #   agent.reasons                  # All captured reasons
+  #   agent.reasoning_chain          # Formatted reasoning chain
+  #   agent.total_reasoning_tokens   # Sum of all reasoning tokens
+  #
+  module HasReasons
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_reasons_config, default: {
+        auto_capture: true,
+        persist: false,
+        budget_tokens: nil,
+        redact_on_persist: false
+      }
+
+      # Storage for captured reasons
+      attr_accessor :_captured_reasons
+    end
+
+    class_methods do
+      # Configure reasoning behavior for this agent
+      #
+      # @param auto_capture [Boolean] Automatically capture reasoning from responses
+      # @param persist [Boolean] Persist reasoning to context (requires HasContext)
+      # @param budget_tokens [Integer, nil] Default reasoning token budget
+      # @param redact_on_persist [Boolean] Redact reasoning content when persisting
+      def has_reasons(auto_capture: true, persist: false, budget_tokens: nil, redact_on_persist: false)
+        self._reasons_config = {
+          auto_capture: auto_capture,
+          persist: persist,
+          budget_tokens: budget_tokens,
+          redact_on_persist: redact_on_persist
+        }
+      end
+    end
+
+    # Get all captured reasons for this agent instance
+    #
+    # @return [Array<Reasonable::Reason>]
+    def reasons
+      @_captured_reasons ||= []
+    end
+
+    # Get the last captured reason
+    #
+    # @return [Reasonable::Reason, nil]
+    def last_reasoning
+      reasons.last
+    end
+
+    # Get the total reasoning tokens used
+    #
+    # @return [Integer]
+    def total_reasoning_tokens
+      reasons.sum(&:tokens)
+    end
+
+    # Check if any reasoning has been captured
+    #
+    # @return [Boolean]
+    def has_reasoning?
+      reasons.any?(&:extended_thinking?)
+    end
+
+    # Get a formatted reasoning chain (all reasoning in sequence)
+    #
+    # @param separator [String] Separator between reasons
+    # @return [String]
+    def reasoning_chain(separator: "\n\n---\n\n")
+      reasons
+        .select(&:extended_thinking?)
+        .reject(&:redacted?)
+        .map(&:content)
+        .join(separator)
+    end
+
+    # Get reasoning statistics
+    #
+    # @return [Hash]
+    def reasoning_stats
+      {
+        count: reasons.count,
+        total_tokens: total_reasoning_tokens,
+        total_thinking_time_ms: reasons.sum { |r| r.thinking_time_ms || 0 },
+        redacted_count: reasons.count(&:redacted?),
+        models: reasons.map(&:model).compact.uniq
+      }
+    end
+
+    # Capture reasoning from an LLM response
+    #
+    # @param response [Object] LLM response object
+    # @return [Reasonable::Reason, nil] The captured reason
+    def capture_reasoning(response)
+      reason = Reasonable::Reason.from_response(response)
+      return nil unless reason&.extended_thinking?
+
+      @_captured_reasons ||= []
+      @_captured_reasons << reason
+
+      # Persist if configured and HasContext is available
+      persist_reasoning(reason) if _reasons_config[:persist]
+
+      reason
+    end
+
+    # Manually add a reason
+    #
+    # @param content [String] Reasoning content
+    # @param tokens [Integer] Token count
+    # @param metadata [Hash] Additional metadata
+    # @return [Reasonable::Reason]
+    def add_reason(content:, tokens: 0, **metadata)
+      reason = Reasonable::Reason.new(
+        content: content,
+        tokens: tokens,
+        model: current_model,
+        **metadata
+      )
+
+      @_captured_reasons ||= []
+      @_captured_reasons << reason
+
+      persist_reasoning(reason) if _reasons_config[:persist]
+
+      reason
+    end
+
+    # Clear all captured reasons
+    def clear_reasons!
+      @_captured_reasons = []
+    end
+
+    # Get default prompt options with reasoning configuration
+    #
+    # @return [Hash]
+    def reasoning_prompt_options
+      options = {}
+
+      if _reasons_config[:budget_tokens]
+        options[:reasoning_budget_tokens] = _reasons_config[:budget_tokens]
+      end
+
+      options[:extended_thinking] = true if _reasons_config[:auto_capture]
+
+      options
+    end
+
+    private
+
+    def persist_reasoning(reason)
+      return unless respond_to?(:context) && context.respond_to?(:generations)
+
+      # Find the most recent generation and store reasoning
+      generation = context.generations.order(created_at: :desc).first
+      return unless generation
+
+      if generation.respond_to?(:store_reason!)
+        # If generation includes Reasonable
+        persisted_reason = if _reasons_config[:redact_on_persist]
+          Reasonable::Reason.new(
+            content: "[Redacted]",
+            tokens: reason.tokens,
+            model: reason.model,
+            thinking_time_ms: reason.thinking_time_ms,
+            redacted: true,
+            metadata: reason.metadata
+          )
+        else
+          reason
+        end
+
+        generation.store_reason!(persisted_reason)
+      end
+    rescue StandardError => e
+      # Log but don't fail if persistence fails
+      Rails.logger.warn "[SolidAgent::HasReasons] Failed to persist reasoning: #{e.message}" if defined?(Rails)
+    end
+
+    def current_model
+      return @model if defined?(@model)
+      return prompt_options[:model] if respond_to?(:prompt_options) && prompt_options[:model]
+
+      nil
+    end
+  end
+end

data/lib/solid_agent/has_tools.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+# HasTools provides a DSL for defining and loading tool schemas in ActiveAgent agents.
+#
+# This concern enables declarative tool registration with automatic schema loading
+# from JSON view templates or inline definitions.
+#
+# @example Auto-discover tools from views
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     has_tools  # Discovers all tools from app/views/my_agent/tools/*.json.erb
+#   end
+#
+# @example Explicit tool list
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     has_tools :search, :fetch, :analyze
+#   end
+#
+# @example Inline tool definition
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     tool :get_weather do
+#       description "Get current weather for a location"
+#       parameter :location, type: :string, required: true, description: "City name"
+#       parameter :units, type: :string, enum: %w[celsius fahrenheit], default: "celsius"
+#     end
+#   end
+#
+# @example Mixed approach
+#   class MyAgent < ApplicationAgent
+#     include SolidAgent::HasTools
+#     has_tools :navigate, :click  # Load from templates
+#     tool :custom_action do       # Define inline
+#       description "A custom action"
+#       parameter :input, type: :string, required: true
+#     end
+#   end
+module SolidAgent
+  module HasTools
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_tool_names, default: []
+      class_attribute :_inline_tools, default: {}
+      class_attribute :_tools_auto_discover, default: false
+    end
+
+    class_methods do
+      # Declares which tools this agent uses.
+      #
+      # Without arguments, enables auto-discovery of tools from view templates.
+      # With arguments, explicitly lists tools to load from templates.
+      #
+      # @param tool_names [Array<Symbol, String>] explicit list of tools to load
+      # @return [void]
+      #
+      # @example Auto-discover
+      #   has_tools
+      #
+      # @example Explicit list
+      #   has_tools :navigate, :click, :fill_form
+      def has_tools(*tool_names)
+        if tool_names.empty?
+          self._tools_auto_discover = true
+        else
+          self._tool_names = tool_names.map(&:to_sym)
+        end
+      end
+
+      # Defines a tool inline using a DSL block.
+      #
+      # The tool name should match a method in the agent class that will be
+      # called when the LLM invokes this tool.
+      #
+      # @param name [Symbol, String] tool name (must match an instance method)
+      # @yield block for defining tool schema using ToolBuilder DSL
+      # @return [void]
+      #
+      # @example
+      #   tool :search do
+      #     description "Search for documents"
+      #     parameter :query, type: :string, required: true
+      #     parameter :limit, type: :integer, default: 10
+      #   end
+      def tool(name, &block)
+        builder = ToolBuilder.new(name)
+        builder.instance_eval(&block) if block_given?
+        self._inline_tools = _inline_tools.merge(name.to_sym => builder.to_schema)
+      end
+    end
+
+    # Returns all tool schemas for this agent.
+    #
+    # Combines tools from:
+    # 1. Auto-discovered JSON templates (if has_tools called without args)
+    # 2. Explicitly listed tools (if has_tools called with args)
+    # 3. Inline tool definitions (from tool blocks)
+    #
+    # @return [Array<Hash>] array of tool schemas in OpenAI format
+    def tools
+      @_tools_cache ||= begin
+        schemas = []
+
+        # Load from templates
+        if _tools_auto_discover
+          schemas.concat(discover_tool_templates)
+        elsif _tool_names.any?
+          schemas.concat(_tool_names.map { |name| load_tool_schema(name) })
+        end
+
+        # Add inline tools
+        schemas.concat(_inline_tools.values)
+
+        schemas
+      end
+    end
+
+    # Reloads tools, clearing any cached schemas.
+    #
+    # Useful when tool templates may have changed during development.
+    #
+    # @return [Array<Hash>] freshly loaded tool schemas
+    def reload_tools!
+      @_tools_cache = nil
+      tools
+    end
+
+    private
+
+    # Discovers tool templates from the agent's views directory.
+    #
+    # Looks for JSON templates in:
+    # - app/views/{agent_name}/tools/*.json.erb
+    # - app/views/agents/{agent_without_suffix}/tools/*.json.erb
+    #
+    # @return [Array<Hash>] discovered tool schemas
+    def discover_tool_templates
+      tool_schemas = []
+      tools_path = Rails.root.join("app", "views", agent_name, "tools")
+
+      if tools_path.exist?
+        tools_path.glob("*.json.erb").each do |template_path|
+          tool_name = template_path.basename(".json.erb").to_s
+          tool_schemas << load_tool_schema(tool_name)
+        end
+      end
+
+      # Also check nested structure: app/views/agents/{name}/tools/
+      nested_path = Rails.root.join("app", "views", "agents", agent_name.delete_suffix("_agent"), "tools")
+      if nested_path.exist?
+        nested_path.glob("*.json.erb").each do |template_path|
+          tool_name = template_path.basename(".json.erb").to_s
+          # Avoid duplicates
+          next if tool_schemas.any? { |t| t[:name] == tool_name }
+          tool_schemas << load_tool_schema(tool_name)
+        end
+      end
+
+      tool_schemas
+    end
+
+    # Loads a single tool schema from its JSON view template.
+    #
+    # @param tool_name [Symbol, String] name of the tool
+    # @return [Hash] tool schema with symbolized keys
+    # @raise [ActionView::MissingTemplate] if template not found
+    # @raise [JSON::ParserError] if template produces invalid JSON
+    def load_tool_schema(tool_name)
+      template_path = "tools/#{tool_name}"
+
+      json_content = render_to_string(
+        template: "#{agent_name}/#{template_path}",
+        formats: [:json],
+        layout: false
+      )
+
+      JSON.parse(json_content, symbolize_names: true)
+    rescue JSON::ParserError => e
+      Rails.logger.error "[#{self.class.name}] Invalid JSON in tool template: #{template_path}"
+      raise e
+    end
+
+    # DSL builder for inline tool definitions.
+    #
+    # Provides a clean API for defining tool schemas programmatically:
+    #
+    #   tool :my_tool do
+    #     description "Does something useful"
+    #     parameter :input, type: :string, required: true
+    #   end
+    class ToolBuilder
+      def initialize(name)
+        @name = name.to_s
+        @description = ""
+        @parameters = {}
+        @required = []
+      end
+
+      # Sets the tool description.
+      #
+      # @param text [String] human-readable description of what the tool does
+      # @return [void]
+      def description(text)
+        @description = text
+      end
+
+      # Defines a parameter for the tool.
+      #
+      # @param name [Symbol, String] parameter name
+      # @param type [Symbol, String] JSON Schema type (:string, :integer, :boolean, :array, :object)
+      # @param required [Boolean] whether this parameter is required (default: false)
+      # @param description [String] parameter description
+      # @param enum [Array] allowed values (for string type)
+      # @param items [Hash] item schema (for array type)
+      # @param properties [Hash] nested properties (for object type)
+      # @param default [Object] default value
+      # @return [void]
+      #
+      # @example Simple string parameter
+      #   parameter :query, type: :string, required: true
+      #
+      # @example Enum parameter
+      #   parameter :format, type: :string, enum: %w[json xml csv]
+      #
+      # @example Array parameter
+      #   parameter :tags, type: :array, items: { type: :string }
+      def parameter(name, type:, required: false, description: nil, enum: nil, items: nil, properties: nil, default: nil)
+        param_schema = { type: type.to_s }
+        param_schema[:description] = description if description
+        param_schema[:enum] = enum if enum
+        param_schema[:items] = items if items
+        param_schema[:properties] = properties if properties
+        param_schema[:default] = default if default
+
+        @parameters[name.to_s] = param_schema
+        @required << name.to_s if required
+      end
+
+      # Converts the builder state to an OpenAI-compatible tool schema.
+      #
+      # @return [Hash] tool schema
+      def to_schema
+        {
+          type: "function",
+          name: @name,
+          description: @description,
+          parameters: {
+            type: "object",
+            properties: @parameters,
+            required: @required
+          }.compact
+        }
+      end
+    end
+  end
+end

data/lib/solid_agent/model_naming.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SolidAgent
+  # The one place that knows how a context class name maps to its message and
+  # generation class names.
+  #
+  # Two callers derive these names — HasContext#infer_class_names at runtime and
+  # the context generator when writing files — and they used to implement the
+  # rule independently, which is how they drifted.
+  module ModelNaming
+    # Suffixes a context class may end with. Only the first match is stripped:
+    # chaining +delete_suffix+ reduces "SessionContext" to "" and produces a
+    # bare "Message"/"Generation" pair that collides across every context.
+    CONTEXT_SUFFIXES = %w[Context Session].freeze
+
+    class << self
+      # The stem a context class name contributes to its siblings.
+      #
+      # @param class_name [String, Symbol, Class]
+      # @return [String]
+      #
+      # @example
+      #   base_for("ChatSession")     #=> "Chat"
+      #   base_for("SessionContext")  #=> "Session"
+      #   base_for("Conversation")    #=> "Conversation"
+      def base_for(class_name)
+        name = class_name.to_s
+        suffix = CONTEXT_SUFFIXES.find { |candidate| name.end_with?(candidate) && name != candidate }
+
+        suffix ? name.delete_suffix(suffix) : name
+      end
+
+      # @param class_name [String, Symbol, Class]
+      # @return [String]
+      def message_class_for(class_name) = "#{base_for(class_name)}Message"
+
+      # @param class_name [String, Symbol, Class]
+      # @return [String]
+      def generation_class_for(class_name) = "#{base_for(class_name)}Generation"
+    end
+  end
+end