ruby-mana 0.5.1 → 0.5.7

data/lib/mana/backends/base.rb

@@ -1,17 +1,64 @@
 # frozen_string_literal: true
 
+require "json"
+require "net/http"
+require "uri"
+
 module Mana
   module Backends
+    # Base class for LLM backends. Provides shared HTTP infrastructure
+    # and the factory method for backend resolution.
     class Base
+      # Model name pattern for auto-detecting Anthropic backend
+      ANTHROPIC_PATTERN = /^claude-/i
+
       def initialize(config)
         @config = config
       end
 
-      # Send a chat request, return array of content blocks in Anthropic format
-      # (normalized). Each backend converts its native response to this format.
-      # Returns: [{ type: "text", text: "..." }, { type: "tool_use", id: "...", name: "...", input: {...} }]
+      # Send a chat request. Subclasses must implement this.
       def chat(system:, messages:, tools:, model:, max_tokens: 4096)
-        raise NotImplementedError
+        raise NotImplementedError, "#{self.class}#chat not implemented"
+      end
+
+      # --- Factory method ---
+
+      # Resolve a backend instance from configuration.
+      # Priority: pre-built instance > explicit name > auto-detect from model name.
+      def self.for(config)
+        return config.backend if config.backend.is_a?(Base)
+
+        config.validate!
+
+        case config.backend&.to_s
+        when "openai" then OpenAI.new(config)
+        when "anthropic" then Anthropic.new(config)
+        else
+          config.model.match?(ANTHROPIC_PATTERN) ? Anthropic.new(config) : OpenAI.new(config)
+        end
+      end
+
+      private
+
+      # Shared HTTP POST with error handling and timeout support.
+      # Returns parsed JSON response body.
+      def http_post(uri, body, headers = {})
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @config.timeout
+        http.read_timeout = @config.timeout
+
+        req = Net::HTTP::Post.new(uri)
+        req["Content-Type"] = "application/json"
+        headers.each { |k, v| req[k] = v }
+        req.body = JSON.generate(body)
+
+        res = http.request(req)
+        raise LLMError, "HTTP #{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(res.body, symbolize_names: true)
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise LLMError, "Request timed out: #{e.message}"
       end
     end
   end

data/lib/mana/backends/openai.rb

@@ -1,40 +1,30 @@
 # frozen_string_literal: true
 
-require "json"
-require "net/http"
-require "uri"
-
 module Mana
   module Backends
+    # OpenAI-compatible backend (GPT, Groq, DeepSeek, Ollama, etc.)
+    #
+    # Translates between Mana's internal format (Anthropic-style) and OpenAI's:
+    #   - system prompt: top-level `system` → system message
+    #   - tool calls: `tool_use`/`tool_result` blocks → `tool_calls` + `role: "tool"`
+    #   - response: `choices` → content blocks
     class OpenAI < Base
       def chat(system:, messages:, tools:, model:, max_tokens: 4096)
-        uri = URI("#{@config.base_url}/v1/chat/completions")
-        body = {
+        uri = URI("#{@config.effective_base_url}/v1/chat/completions")
+        parsed = http_post(uri, {
           model: model,
           max_completion_tokens: max_tokens,
           messages: convert_messages(system, messages),
           tools: convert_tools(tools)
-        }
-
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = uri.scheme == "https"
-        http.read_timeout = 120
-
-        req = Net::HTTP::Post.new(uri)
-        req["Content-Type"] = "application/json"
-        req["Authorization"] = "Bearer #{@config.api_key}"
-        req.body = JSON.generate(body)
-
-        res = http.request(req)
-        raise LLMError, "HTTP #{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
-
-        parsed = JSON.parse(res.body, symbolize_names: true)
+        }, {
+          "Authorization" => "Bearer #{@config.api_key}"
+        })
         normalize_response(parsed)
       end
 
       private
 
-      # Convert Anthropic-style messages to OpenAI format
+      # Convert Anthropic-style messages to OpenAI format.
       def convert_messages(system, messages)
         result = [{ role: "system", content: system }]
 
@@ -42,11 +32,7 @@ module Mana
           case msg[:role]
           when "user"
             converted = convert_user_message(msg)
-            if converted.is_a?(Array)
-              result.concat(converted)
-            else
-              result << converted
-            end
+            converted.is_a?(Array) ? result.concat(converted) : result << converted
           when "assistant"
             result << convert_assistant_message(msg)
           end
@@ -58,12 +44,9 @@ module Mana
       def convert_user_message(msg)
         content = msg[:content]
 
-        # Plain text user message
         return { role: "user", content: content } if content.is_a?(String)
 
-        # Array of content blocks — may contain tool_result blocks
-        if content.is_a?(Array) && content.all? { |b| b[:type] == "tool_result" || b["type"] == "tool_result" }
-          # Convert each tool_result to an OpenAI tool message
+        if content.is_a?(Array) && content.all? { |b| (b[:type] || b["type"]) == "tool_result" }
           return content.map do |block|
             {
               role: "tool",
@@ -73,7 +56,6 @@ module Mana
           end
         end
 
-        # Other array content (e.g. text blocks) — join as string
         if content.is_a?(Array)
           texts = content.map { |b| b[:text] || b["text"] }.compact
           return { role: "user", content: texts.join("\n") }
@@ -85,12 +67,8 @@ module Mana
       def convert_assistant_message(msg)
         content = msg[:content]
 
-        # Simple text response
-        if content.is_a?(String)
-          return { role: "assistant", content: content }
-        end
+        return { role: "assistant", content: content } if content.is_a?(String)
 
-        # Array of content blocks — may contain tool_use
         if content.is_a?(Array)
           text_parts = []
           tool_calls = []
@@ -121,7 +99,6 @@ module Mana
         { role: "assistant", content: content.to_s }
       end
 
-      # Convert Anthropic tool definitions to OpenAI function calling format
       def convert_tools(tools)
         tools.map do |tool|
           {
@@ -129,25 +106,23 @@ module Mana
             function: {
               name: tool[:name],
               description: tool[:description] || "",
-              parameters: tool[:input_schema] || {}
+              parameters: (tool[:input_schema] || {}).reject { |k, _| k.to_s == "$schema" }
             }
           }
         end
       end
 
-      # Convert OpenAI response back to Anthropic-style content blocks
+      # Convert OpenAI response to Anthropic-style content blocks.
       def normalize_response(parsed)
         choice = parsed.dig(:choices, 0, :message)
         return [] unless choice
 
         blocks = []
 
-        # Text content
         if choice[:content] && !choice[:content].empty?
           blocks << { type: "text", text: choice[:content] }
         end
 
-        # Tool calls
         if choice[:tool_calls]
           choice[:tool_calls].each do |tc|
             func = tc[:function]

data/lib/mana/compiler.rb

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "digest"
 
 module Mana
   # Compiler for `mana def` — LLM generates method implementations on first call,
   # caches them as real .rb files, and replaces the method with native Ruby.
   #
   # Usage:
-  #   mana def fizzbuzz(n)
-  #     ~"return an array of FizzBuzz results from 1 to n"
+  #   mana def fibonacci(n)
+  #     ~"return an array of the first n Fibonacci numbers"
   #   end
   #
-  #   fizzbuzz(15)  # first call → LLM generates code → cached → executed
-  #   fizzbuzz(20)  # subsequent calls → pure Ruby, zero API overhead
+  #   fibonacci(10)  # first call → LLM generates code → cached → executed
+  #   fibonacci(20)  # subsequent calls → pure Ruby, zero API overhead
   #
-  #   Mana.source(:fizzbuzz)  # view generated source
+  #   Mana.source(:fibonacci)  # view generated source
   module Compiler
     class << self
       # Registry of compiled method sources: { "ClassName#method" => source_code }
@@ -35,55 +36,135 @@ module Mana
         registry[key]
       end
 
-      # Compile a method: wrap it so first invocation triggers LLM code generation
+      # Compile a method: wrap it so first invocation triggers LLM code generation.
+      # On subsequent calls, the generated Ruby code is loaded from cache (zero API cost).
       def compile(owner, method_name)
         original = owner.instance_method(method_name)
         compiler = self
         key = registry_key(method_name, owner)
 
-        # Read the prompt from the original method body
+        # Detect method visibility before we replace it
+        visibility = if owner.private_method_defined?(method_name)
+                       :private
+                     elsif owner.protected_method_defined?(method_name)
+                       :protected
+                     else
+                       :public
+                     end
+
+        # Read the prompt from the original method body (the ~"..." string)
         prompt = extract_prompt(original)
 
         # Build parameter signature for the generated method
         params_desc = describe_params(original)
 
+        # Cache filename based on source file + method name
+        source_file = original.source_location&.first
+        # Include gem version, Ruby version, and sibling function signatures so cache
+        # auto-invalidates when the gem upgrades, Ruby upgrades, or dependency functions change.
+        sibling_methods = begin
+          Mana::Introspect.methods_from_file(source_file)
+            .reject { |m| m[:name] == method_name.to_s }
+            .map { |m| "#{m[:name]}(#{m[:params].join(',')})" }
+            .sort.join(";")
+        rescue
+          ""
+        end
+        prompt_hash = Digest::SHA256.hexdigest("#{Mana::VERSION}:#{RUBY_VERSION}:#{method_name}:#{params_desc}:#{prompt}:#{sibling_methods}")[0, 16]
+        cache_path = cache_file_path(method_name, owner, source_file: source_file)
+
+        # Load from cache if file exists and prompt hash matches
+        if File.exist?(cache_path)
+          first_line = File.open(cache_path, &:readline) rescue ""
+          if first_line.include?(prompt_hash)
+            cached = File.read(cache_path)
+            generated = cached.lines.reject { |l| l.start_with?("#") }.join.strip
+            compiler.registry[key] = generated
+            v, $VERBOSE = $VERBOSE, nil
+            owner.class_eval(generated, cache_path, 1)
+            owner.send(visibility, method_name) unless visibility == :public
+            $VERBOSE = v
+            return
+          end
+          # Prompt changed — cache is stale, will regenerate on first call
+        end
+
+        # Replace the method with a lazy wrapper that generates code on first call
+        old_verbose, $VERBOSE = $VERBOSE, nil
+        p_hash = prompt_hash    # capture for closure
+        p_text = prompt         # capture for closure
+        src_file = source_file  # capture for closure
         owner.define_method(method_name) do |*args, **kwargs, &blk|
           # Generate implementation via LLM
           generated = compiler.generate(method_name, params_desc, prompt)
 
-          # Write to cache file
-          cache_path = compiler.write_cache(method_name, generated, owner)
+          # Write to cache file for future runs
+          cache_path = compiler.write_cache(method_name, generated, owner, prompt_hash: p_hash, prompt: p_text, source_file: src_file)
 
-          # Store in registry
+          # Store in registry so Mana.source() can retrieve it
           compiler.registry[key] = generated
 
           # Define the method on the correct owner (not Object) via class_eval
           target_owner = owner
+          v, $VERBOSE = $VERBOSE, nil
           target_owner.class_eval(generated, cache_path, 1)
+          target_owner.send(visibility, method_name) unless visibility == :public
+          $VERBOSE = v
 
-          # Call the now-native method
+          # Call the now-native method (this wrapper never runs again)
           send(method_name, *args, **kwargs, &blk)
         end
+        # Restore original visibility on the wrapper method
+        owner.send(visibility, method_name) unless visibility == :public
+        $VERBOSE = old_verbose
       end
 
-      # Generate Ruby method source via LLM
+      # Generate Ruby method source via LLM.
+      # Uses an isolated binding so LLM cannot see Compiler internals.
       def generate(method_name, params_desc, prompt)
-        code = nil # pre-declare so binding captures it
-        b = binding
         engine_prompt = "Write a Ruby method definition `def #{method_name}(#{params_desc})` that: #{prompt}. " \
                         "Return ONLY the complete method definition (def...end), no explanation. " \
                         "Store the code as a string in <code>"
 
-        Mana::Engines::LLM.new(b).execute(engine_prompt)
+        # Create isolated binding with only `code` variable visible.
+        # Use eval to avoid "assigned but unused variable" parse-time warning.
+        isolated = Object.new.instance_eval { eval("code = nil; binding") }
+        Mana::Engine.new(isolated).execute(engine_prompt)
+
+        code = isolated.local_variable_get(:code)
+        # LLM may return literal \n instead of real newlines — unescape them
+        code = code.gsub("\\n", "\n").gsub("\\\"", "\"").gsub("\\'", "'") if code.is_a?(String)
         code
       end
 
+      # Path to the cache file for a method.
+      # Includes source file path for uniqueness: lib_foo_calculate.rb
+      # Build the cache file path for a method.
+      # Prefers source-file-based naming for uniqueness; falls back to owner class name.
+      def cache_file_path(method_name, owner = nil, source_file: nil)
+        parts = []
+        if source_file
+          # Convert path relative to pwd: lib/foo.rb -> lib_foo
+          rel = source_file.sub("#{Dir.pwd}/", "").sub(/\.rb$/, "")
+          parts << rel.tr("/", "_")
+        elsif owner && owner != Object
+          # Use underscored class name when source file is unavailable
+          parts << underscore(owner.name)
+        end
+        parts << method_name.to_s
+        File.join(cache_dir, "#{parts.join('_')}.rb")
+      end
+
       # Write generated code to a cache file, return the path
-      def write_cache(method_name, source, owner = nil)
+      def write_cache(method_name, source, owner = nil, prompt_hash: nil, prompt: nil, source_file: nil)
         FileUtils.mkdir_p(cache_dir)
-        prefix = owner && owner != Object ? "#{underscore(owner.name)}_" : ""
-        path = File.join(cache_dir, "#{prefix}#{method_name}.rb")
-        File.write(path, "# Auto-generated by ruby-mana\n# frozen_string_literal: true\n\n#{source}\n")
+        path = cache_file_path(method_name, owner, source_file: source_file)
+        header = "# Auto-generated by ruby-mana v#{Mana::VERSION} | ruby #{RUBY_VERSION} | prompt_hash: #{prompt_hash}\n"
+        if prompt
+          prompt.to_s.each_line { |line| header += "# prompt: #{line.rstrip}\n" }
+        end
+        header += "# frozen_string_literal: true\n\n"
+        File.write(path, "#{header}#{source}\n")
         path
       end
 
@@ -104,45 +185,80 @@ module Mana
       end
 
       # Extract the prompt string from the original method.
-      # The method body should be a single ~"..." expression.
+      # Strategy 1: Parse source file with Prism AST (handles multi-line, heredoc, escapes)
+      # Strategy 2: Extract from instruction sequence (fallback for IRB/eval)
       def extract_prompt(unbound_method)
         source_loc = unbound_method.source_location
-        return nil unless source_loc
+        return extract_prompt_from_iseq(unbound_method) unless source_loc
 
         file, line = source_loc
-        return nil unless file && File.exist?(file)
-
-        lines = File.readlines(file)
-        # Scan from the def line to find the prompt string
-        body_lines = []
-        depth = 0
-        (line - 1...lines.length).each do |i|
-          l = lines[i]
-          depth += l.scan(/\bdef\b|\bdo\b|\bclass\b|\bmodule\b|\bif\b|\bunless\b|\bcase\b|\bwhile\b|\buntil\b|\bbegin\b/).length
-          depth -= l.scan(/\bend\b/).length
-          body_lines << l
-          break if depth <= 0
+        return extract_prompt_from_iseq(unbound_method) unless file && File.exist?(file)
+
+        # Parse with Prism AST — finds ~@ call on a string node
+        source = File.read(file)
+        result = Prism.parse(source)
+
+        # Walk AST to find the DefNode at the right line, then find ~@ inside it
+        prompt = nil
+        queue = [result.value]
+        while (node = queue.shift)
+          next unless node.respond_to?(:compact_child_nodes)
+
+          if node.is_a?(Prism::DefNode) && node.location.start_line == line
+            # Found our method — now find the ~"..." call inside
+            inner_queue = node.compact_child_nodes.dup
+            while (inner = inner_queue.shift)
+              next unless inner.respond_to?(:compact_child_nodes)
+              if inner.is_a?(Prism::CallNode) && inner.name == :~@ && inner.receiver.is_a?(Prism::StringNode)
+                prompt = inner.receiver.unescaped
+                break
+              end
+              inner_queue.concat(inner.compact_child_nodes)
+            end
+            break
+          end
+
+          queue.concat(node.compact_child_nodes)
         end
 
-        # Extract string content from ~"..." pattern
-        body = body_lines.join
-        match = body.match(/~"([^"]*)"/) || body.match(/~'([^']*)'/)
-        match ? match[1] : body_lines[1...-1].join.strip
+        prompt || extract_prompt_from_iseq(unbound_method)
+      end
+
+      # Fallback: extract prompt from method instruction sequence (works in IRB/eval).
+      # Uses iseq.to_a to find the string literal directly — more reliable than disasm
+      # because it preserves real newlines (disasm escapes them as \\n).
+      def extract_prompt_from_iseq(unbound_method)
+        iseq = RubyVM::InstructionSequence.of(unbound_method)
+        return nil unless iseq
+
+        # Walk the flattened instruction array to find putstring/putchilledstring
+        flat = iseq.to_a.flatten
+        flat.each_with_index do |item, i|
+          if (item == :putchilledstring || item == :putstring) && flat[i + 1].is_a?(String)
+            return flat[i + 1]
+          end
+        end
+        nil
+      rescue
+        nil
       end
 
+      # Build a human-readable parameter signature string from method parameters.
+      # Maps each parameter type to its Ruby syntax representation.
       def describe_params(unbound_method)
         unbound_method.parameters.map do |(type, name)|
           case type
-          when :req then name.to_s
-          when :opt then "#{name}=nil"
-          when :rest then "*#{name}"
-          when :keyreq then "#{name}:"
-          when :key then "#{name}: nil"
-          when :keyrest then "**#{name}"
-          when :block then "&#{name}"
-          else name.to_s
+          when :req then name.to_s            # required positional
+          when :opt then "#{name}=nil"         # optional positional
+          when :rest then "*#{name}"           # splat
+          when :keyreq then "#{name}:"         # required keyword
+          when :key then "#{name}: nil"        # optional keyword
+          when :keyrest then "**#{name}"       # double splat
+          when :block then "&#{name}"          # block parameter
+          when :nokey then nil                 # **nil — skip (no keywords accepted)
+          else name&.to_s
           end
-        end.join(", ")
+        end.compact.join(", ")
       end
 
       def underscore(str)

data/lib/mana/config.rb

@@ -1,28 +1,116 @@
 # frozen_string_literal: true
 
 module Mana
+  # Central configuration for Mana. Set via Mana.configure { |c| ... }.
+  #
+  # Key options:
+  #   model            - LLM model name (default: claude-sonnet-4-6)
+  #   api_key          - API key, falls back to ANTHROPIC_API_KEY or OPENAI_API_KEY env vars
+  #   base_url         - Custom API endpoint, falls back to ANTHROPIC_API_URL or OPENAI_API_URL
+  #   backend          - :anthropic, :openai, or nil (auto-detect from model name)
+  #   timeout          - HTTP timeout in seconds (default: 120)
+  #   memory_pressure  - Token ratio (0-1) that triggers memory compaction (default: 0.7)
   class Config
     attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url,
-                  :backend,
+                  :backend, :verbose,
                   :namespace, :memory_store, :memory_path,
                   :context_window, :memory_pressure, :memory_keep_recent,
                   :compact_model, :on_compact
+    attr_reader :timeout
 
+    DEFAULT_ANTHROPIC_URL = "https://api.anthropic.com"
+    DEFAULT_OPENAI_URL = "https://api.openai.com"
+
+    # All config options can be set via environment variables:
+    #   MANA_MODEL, MANA_VERBOSE, MANA_TIMEOUT, MANA_BACKEND
+    #   ANTHROPIC_API_KEY / OPENAI_API_KEY
+    #   ANTHROPIC_API_URL / OPENAI_API_URL
     def initialize
-      @model = "claude-sonnet-4-20250514"
+      @model = ENV["MANA_MODEL"] || "claude-sonnet-4-6"
       @temperature = 0
-      @api_key = ENV["ANTHROPIC_API_KEY"]
+      @api_key = ENV["ANTHROPIC_API_KEY"] || ENV["OPENAI_API_KEY"]
       @max_iterations = 50
-      @base_url = "https://api.anthropic.com"
-      @backend = nil
+      @base_url = ENV["ANTHROPIC_API_URL"] || ENV["OPENAI_API_URL"]
+      self.timeout = (ENV["MANA_TIMEOUT"] || 120).to_i
+      @verbose = %w[1 true yes].include?(ENV["MANA_VERBOSE"]&.downcase)
+      @backend = ENV["MANA_BACKEND"]&.to_sym
+      sec = ENV["MANA_SECURITY"]
+      @security = SecurityPolicy.new(sec ? sec.to_sym : :standard)
       @namespace = nil
       @memory_store = nil
       @memory_path = nil
-      @context_window = nil
+      @context_window = 128_000
       @memory_pressure = 0.7
       @memory_keep_recent = 4
       @compact_model = nil
       @on_compact = nil
     end
+
+    # Set timeout; must be a positive number
+    def timeout=(value)
+      unless value.is_a?(Numeric) && value.positive?
+        raise ArgumentError, "timeout must be a positive number, got #{value.inspect}"
+      end
+
+      @timeout = value
+    end
+
+    # Read the current security policy
+    def security
+      @security
+    end
+
+    # Accept Symbol (:strict), Integer (1), or SecurityPolicy instance
+    def security=(value)
+      case value
+      when SecurityPolicy
+        @security = value
+      when Symbol, Integer
+        @security = SecurityPolicy.new(value)
+      else
+        raise ArgumentError, "security must be a Symbol, Integer, or SecurityPolicy, got #{value.class}"
+      end
+    end
+
+    # Resolve the effective base URL based on the configured or auto-detected backend.
+    # Falls back to the appropriate default when no explicit URL is set.
+    def effective_base_url
+      # Return user-configured URL if explicitly set
+      return @base_url if @base_url
+
+      # Otherwise pick the default URL based on backend type
+      if anthropic_backend?
+        DEFAULT_ANTHROPIC_URL
+      else
+        DEFAULT_OPENAI_URL
+      end
+    end
+
+    # Validate configuration and raise early if something is wrong.
+    # Called automatically by Mana.configure, or manually via Mana.config.validate!
+    def validate!
+      if @api_key.nil? || @api_key.to_s.strip.empty?
+        raise ConfigError,
+          "API key is not configured. Set it via environment variable or Mana.configure:\n\n" \
+          "  export ANTHROPIC_API_KEY=your_key_here\n" \
+          "  # or\n" \
+          "  export OPENAI_API_KEY=your_key_here\n" \
+          "  # or\n" \
+          "  Mana.configure { |c| c.api_key = \"your_key_here\" }\n"
+      end
+      true
+    end
+
+    private
+
+    # Determine whether the current backend is Anthropic
+    def anthropic_backend?
+      case @backend&.to_s
+      when "anthropic" then true
+      when "openai" then false
+      # No explicit backend; auto-detect from model name pattern
+      else @model.match?(Backends::Base::ANTHROPIC_PATTERN)
+      end
+    end
   end
 end