ruby-mana 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66fae9938dbde50412ea78e15f01724b7ce584395e0f3d0e0d591041e183fa97
-  data.tar.gz: ecb38c4f7a943724caed5c6d01da58ed7bf93b210fb5e3bd0bcb710ed6b938e4
+  metadata.gz: c5998b08056a2657d73e7ab5382fd9ad3a96a53c9cbaa3268a98f6798c7290da
+  data.tar.gz: 82326fc68f9c15694f70dcbea19b43b321674f766497864c824ee574023a7f1c
 SHA512:
-  metadata.gz: d207d98300ee79db472a0d07a2127ccb5fe0e9f6101b9187c4e83b8add90bcdd88cb4b3de3daff3d4eaa1344d7eab747f85a0cb12edf37648683450d53777aa6
-  data.tar.gz: e70a43679205f5e8768a415fe020862c175b17f00eff0f479b5f9c5aaf053d62493f98cd09b7eaa3817f663e6d66d72f166bb6aef386de77b324154adee905cb
+  metadata.gz: a612ba5f45d2bd5abf09fd68e7225945e5d3defa70f0bd5298e55215010bfe71dd1a7f53adf415e126fe3a97c654fa209812e8db8b3720d8258355054767eb7d
+  data.tar.gz: 3649cc64a401d6d8e92b16ae8cc05999b9a6e5813a16d25a62c7661573827e3086b30e49f9d62e0c57c48a2ea6d081307a053d64d53e5de4d565db607dc76574

data/README.md

@@ -28,10 +28,12 @@ Or in your Gemfile:
 gem "ruby-mana"
 ```
 
-Requires Ruby 3.3+ and an Anthropic API key:
+Requires Ruby 3.3+ and an API key (Anthropic, OpenAI, or compatible):
 
 ```bash
 export ANTHROPIC_API_KEY=your_key_here
+# or
+export OPENAI_API_KEY=your_key_here
 ```
 
 ## Usage
@@ -146,6 +148,41 @@ Mana.configure do |c|
 end
 ```
 
+### Multiple LLM backends
+
+Mana supports Anthropic and OpenAI-compatible APIs (including Ollama, DeepSeek, Groq, etc.):
+
+```ruby
+# Anthropic (default for claude-* models)
+Mana.configure do |c|
+  c.api_key = ENV["ANTHROPIC_API_KEY"]
+  c.model = "claude-sonnet-4-20250514"
+end
+
+# OpenAI
+Mana.configure do |c|
+  c.api_key = ENV["OPENAI_API_KEY"]
+  c.base_url = "https://api.openai.com"
+  c.model = "gpt-4o"
+end
+
+# Ollama (local, no API key needed)
+Mana.configure do |c|
+  c.api_key = "unused"
+  c.base_url = "http://localhost:11434"
+  c.model = "llama3"
+end
+
+# Explicit backend override
+Mana.configure do |c|
+  c.backend = :openai  # force OpenAI format
+  c.base_url = "https://api.groq.com/openai"
+  c.model = "llama-3.3-70b-versatile"
+end
+```
+
+Backend is auto-detected from model name: `claude-*` → Anthropic, everything else → OpenAI.
+
 ### Custom effect handlers
 
 Define your own tools that the LLM can call. Each effect becomes an LLM tool automatically — the block's keyword parameters define the tool's input schema.
@@ -217,6 +254,47 @@ Mana.incognito do
 end
 ```
 
+### Testing
+
+Use `Mana.mock` to test code that uses `~"..."` without calling any API:
+
+```ruby
+require "mana/test"
+
+RSpec.describe MyApp do
+  include Mana::TestHelpers
+
+  it "analyzes code" do
+    mock_prompt "analyze", bugs: ["XSS"], score: 8.5
+
+    result = MyApp.analyze("user_input")
+    expect(result[:bugs]).to include("XSS")
+  end
+
+  it "translates with dynamic response" do
+    mock_prompt(/translate.*to\s+\w+/) do |prompt|
+      { output: prompt.include?("Chinese") ? "你好" : "hello" }
+    end
+
+    expect(MyApp.translate("hi", "Chinese")).to eq("你好")
+  end
+end
+```
+
+Block mode for inline tests:
+
+```ruby
+Mana.mock do
+  prompt "summarize", summary: "A brief overview"
+
+  text = "Long article..."
+  ~"summarize <text> and store in <summary>"
+  puts summary  # => "A brief overview"
+end
+```
+
+Unmatched prompts raise `Mana::MockError` with a helpful message suggesting the stub to add.
+
 ### Nested prompts
 
 Functions called by LLM can themselves contain `~"..."` prompts:

data/lib/mana/backends/anthropic.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Mana
+  module Backends
+    class Anthropic < Base
+      def chat(system:, messages:, tools:, model:, max_tokens: 4096)
+        uri = URI("#{@config.base_url}/v1/messages")
+        body = {
+          model: model,
+          max_tokens: max_tokens,
+          system: system,
+          tools: tools,
+          messages: messages
+        }
+
+        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["x-api-key"] = @config.api_key
+        req["anthropic-version"] = "2023-06-01"
+        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)
+        parsed[:content] || []
+      end
+    end
+  end
+end

data/lib/mana/backends/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mana
+  module Backends
+    class Base
+      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: {...} }]
+      def chat(system:, messages:, tools:, model:, max_tokens: 4096)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/mana/backends/openai.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Mana
+  module Backends
+    class OpenAI < Base
+      def chat(system:, messages:, tools:, model:, max_tokens: 4096)
+        uri = URI("#{@config.base_url}/v1/chat/completions")
+        body = {
+          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)
+        normalize_response(parsed)
+      end
+
+      private
+
+      # Convert Anthropic-style messages to OpenAI format
+      def convert_messages(system, messages)
+        result = [{ role: "system", content: system }]
+
+        messages.each do |msg|
+          case msg[:role]
+          when "user"
+            converted = convert_user_message(msg)
+            if converted.is_a?(Array)
+              result.concat(converted)
+            else
+              result << converted
+            end
+          when "assistant"
+            result << convert_assistant_message(msg)
+          end
+        end
+
+        result
+      end
+
+      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
+          return content.map do |block|
+            {
+              role: "tool",
+              tool_call_id: block[:tool_use_id] || block["tool_use_id"],
+              content: (block[:content] || block["content"]).to_s
+            }
+          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") }
+        end
+
+        { role: "user", content: content.to_s }
+      end
+
+      def convert_assistant_message(msg)
+        content = msg[:content]
+
+        # Simple text response
+        if content.is_a?(String)
+          return { role: "assistant", content: content }
+        end
+
+        # Array of content blocks — may contain tool_use
+        if content.is_a?(Array)
+          text_parts = []
+          tool_calls = []
+
+          content.each do |block|
+            type = block[:type] || block["type"]
+            case type
+            when "text"
+              text_parts << (block[:text] || block["text"])
+            when "tool_use"
+              tool_calls << {
+                id: block[:id] || block["id"],
+                type: "function",
+                function: {
+                  name: block[:name] || block["name"],
+                  arguments: JSON.generate(block[:input] || block["input"] || {})
+                }
+              }
+            end
+          end
+
+          msg_hash = { role: "assistant" }
+          msg_hash[:content] = text_parts.join("\n") unless text_parts.empty?
+          msg_hash[:tool_calls] = tool_calls unless tool_calls.empty?
+          return msg_hash
+        end
+
+        { role: "assistant", content: content.to_s }
+      end
+
+      # Convert Anthropic tool definitions to OpenAI function calling format
+      def convert_tools(tools)
+        tools.map do |tool|
+          {
+            type: "function",
+            function: {
+              name: tool[:name],
+              description: tool[:description] || "",
+              parameters: tool[:input_schema] || {}
+            }
+          }
+        end
+      end
+
+      # Convert OpenAI response back 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]
+            blocks << {
+              type: "tool_use",
+              id: tc[:id],
+              name: func[:name],
+              input: JSON.parse(func[:arguments], symbolize_names: true)
+            }
+          end
+        end
+
+        blocks
+      end
+    end
+  end
+end

data/lib/mana/backends/registry.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mana
+  module Backends
+    ANTHROPIC_PATTERNS = /^(claude-)/i
+    OPENAI_PATTERNS = /^(gpt-|o1-|o3-|chatgpt-|dall-e|tts-|whisper-)/i
+
+    def self.for(config)
+      return config.backend if config.backend.is_a?(Base)
+
+      case config.backend&.to_s
+      when "openai" then OpenAI.new(config)
+      when "anthropic" then Anthropic.new(config)
+      else
+        # Auto-detect from model name
+        case config.model
+        when ANTHROPIC_PATTERNS then Anthropic.new(config)
+        else OpenAI.new(config) # Default to OpenAI (most compatible)
+        end
+      end
+    end
+  end
+end

data/lib/mana/config.rb

@@ -3,6 +3,7 @@
 module Mana
   class Config
     attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url,
+                  :backend,
                   :namespace, :memory_store, :memory_path,
                   :context_window, :memory_pressure, :memory_keep_recent,
                   :compact_model, :on_compact
@@ -13,6 +14,7 @@ module Mana
       @api_key = ENV["ANTHROPIC_API_KEY"]
       @max_iterations = 50
       @base_url = "https://api.anthropic.com"
+      @backend = nil
       @namespace = nil
       @memory_store = nil
       @memory_path = nil

data/lib/mana/engine.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 require "json"
-require "net/http"
-require "uri"
 
 module Mana
   class Engine
@@ -120,6 +118,9 @@ module Mana
     end
 
     def execute
+      # Mock mode: match prompt and return stubbed values, no API calls
+      return handle_mock(@prompt) if Mana.mock_active?
+
       Thread.current[:mana_depth] ||= 0
       Thread.current[:mana_depth] += 1
       nested = Thread.current[:mana_depth] > 1
@@ -184,11 +185,46 @@ module Mana
       if nested && !@incognito
         Thread.current[:mana_memory] = outer_memory
       end
-      Thread.current[:mana_depth] -= 1
+      Thread.current[:mana_depth] -= 1 if Thread.current[:mana_depth]
     end
 
     private
 
+    # --- Mock Handling ---
+
+    def handle_mock(prompt)
+      mock = Mana.current_mock
+      stub = mock.match(prompt)
+
+      unless stub
+        truncated = prompt.length > 60 ? "#{prompt[0..57]}..." : prompt
+        raise MockError, "No mock matched: \"#{truncated}\"\n  Add: mock_prompt \"#{truncated}\", _return: \"...\""
+      end
+
+      values = if stub.block
+        stub.block.call(prompt)
+      else
+        stub.values.dup
+      end
+
+      return_value = values.delete(:_return)
+
+      values.each do |name, value|
+        write_local(name.to_s, value)
+      end
+
+      # Record in short-term memory if not incognito
+      if !@incognito
+        memory = Memory.current
+        if memory
+          memory.short_term << { role: "user", content: prompt }
+          memory.short_term << { role: "assistant", content: [{ type: "text", text: "Done: #{return_value || values.inspect}" }] }
+        end
+      end
+
+      return_value || values.values.first
+    end
+
     # --- Context Building ---
 
     def build_context(prompt)
@@ -410,30 +446,14 @@ module Mana
     # --- LLM Client ---
 
     def llm_call(system, messages)
-      uri = URI("#{@config.base_url}/v1/messages")
-      body = {
-        model: @config.model,
-        max_tokens: 4096,
+      backend = Backends.for(@config)
+      backend.chat(
         system: system,
+        messages: messages,
         tools: self.class.all_tools,
-        messages: messages
-      }
-
-      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["x-api-key"] = @config.api_key
-      req["anthropic-version"] = "2023-06-01"
-      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)
-      parsed[:content] || []
+        model: @config.model,
+        max_tokens: 4096
+      )
     end
 
     def extract_tool_uses(content)

data/lib/mana/mock.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mana
+  class Mock
+    Stub = Struct.new(:pattern, :values, :block, keyword_init: true)
+
+    attr_reader :stubs
+
+    def initialize
+      @stubs = []
+    end
+
+    def prompt(pattern, **values, &block)
+      @stubs << Stub.new(pattern: pattern, values: values, block: block)
+    end
+
+    def match(prompt_text)
+      @stubs.find do |stub|
+        case stub.pattern
+        when Regexp then prompt_text.match?(stub.pattern)
+        when String then prompt_text.include?(stub.pattern)
+        end
+      end
+    end
+  end
+
+  class << self
+    def mock(&block)
+      old_mock = Thread.current[:mana_mock]
+      m = Mock.new
+      Thread.current[:mana_mock] = m
+      m.instance_eval(&block)
+    ensure
+      Thread.current[:mana_mock] = old_mock
+    end
+
+    def mock!
+      Thread.current[:mana_mock] = Mock.new
+    end
+
+    def unmock!
+      Thread.current[:mana_mock] = nil
+    end
+
+    def mock_active?
+      !Thread.current[:mana_mock].nil?
+    end
+
+    def current_mock
+      Thread.current[:mana_mock]
+    end
+  end
+end

data/lib/mana/test.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "mana"
+
+module Mana
+  module TestHelpers
+    def self.included(base)
+      base.before { Mana.mock! }
+      base.after { Mana.unmock! }
+    end
+
+    def mock_prompt(pattern, **values, &block)
+      raise Mana::MockError, "Mana mock mode not active. Call Mana.mock! first" unless Mana.mock_active?
+
+      Mana.current_mock.prompt(pattern, **values, &block)
+    end
+  end
+end

data/lib/mana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mana
-  VERSION = "0.3.1"
+  VERSION = "0.4.0"
 end

data/lib/mana.rb

@@ -2,6 +2,10 @@
 
 require_relative "mana/version"
 require_relative "mana/config"
+require_relative "mana/backends/base"
+require_relative "mana/backends/anthropic"
+require_relative "mana/backends/openai"
+require_relative "mana/backends/registry"
 require_relative "mana/effect_registry"
 require_relative "mana/namespace"
 require_relative "mana/memory_store"
@@ -17,6 +21,7 @@ module Mana
   class Error < StandardError; end
   class MaxIterationsError < Error; end
   class LLMError < Error; end
+  class MockError < Error; end
 
   class << self
     def config
@@ -40,6 +45,7 @@ module Mana
       @config = Config.new
       EffectRegistry.clear!
       Thread.current[:mana_memory] = nil
+      Thread.current[:mana_mock] = nil
     end
 
     # Define a custom effect that becomes an LLM tool
@@ -73,3 +79,5 @@ module Mana
     end
   end
 end
+
+require_relative "mana/mock"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Carl
@@ -37,6 +37,10 @@ files:
 - LICENSE
 - README.md
 - lib/mana.rb
+- lib/mana/backends/anthropic.rb
+- lib/mana/backends/base.rb
+- lib/mana/backends/openai.rb
+- lib/mana/backends/registry.rb
 - lib/mana/compiler.rb
 - lib/mana/config.rb
 - lib/mana/context_window.rb
@@ -46,8 +50,10 @@ files:
 - lib/mana/memory.rb
 - lib/mana/memory_store.rb
 - lib/mana/mixin.rb
+- lib/mana/mock.rb
 - lib/mana/namespace.rb
 - lib/mana/string_ext.rb
+- lib/mana/test.rb
 - lib/mana/version.rb
 homepage: https://github.com/carlnoah6/ruby-mana
 licenses: