ruby-mana 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66fae9938dbde50412ea78e15f01724b7ce584395e0f3d0e0d591041e183fa97
-  data.tar.gz: ecb38c4f7a943724caed5c6d01da58ed7bf93b210fb5e3bd0bcb710ed6b938e4
+  metadata.gz: 04d7095024d30500930422b72e86fcdb1a27b1fa9a9f62ca70c9c124c2ceab77
+  data.tar.gz: 6e264f8292e908d45776481aa6af33bed5eb7d9113874d13e72f3a3cde513107
 SHA512:
-  metadata.gz: d207d98300ee79db472a0d07a2127ccb5fe0e9f6101b9187c4e83b8add90bcdd88cb4b3de3daff3d4eaa1344d7eab747f85a0cb12edf37648683450d53777aa6
-  data.tar.gz: e70a43679205f5e8768a415fe020862c175b17f00eff0f479b5f9c5aaf053d62493f98cd09b7eaa3817f663e6d66d72f166bb6aef386de77b324154adee905cb
+  metadata.gz: 470e54537747878bbe07c6825a12bf515a2909af872ee4908e0eb07a0e58b31187dacadb6b20d988782a8f9a2bfaf12c4523ae09c149dc764ad90c2b8a420871
+  data.tar.gz: 1c322b45e74e8fa67aab109c10a5a7cac2d6546d1de61912157192e9f15330b8c2520bd5e90b4c70b942d36b7de4ecabfc165c2774be4b8489936e68e14614a0

data/CHANGELOG.md

@@ -1,6 +1,46 @@
 # Changelog
 
-## [0.1.0] - Unreleased
+## [0.5.0] - 2026-02-22
+
+### Added
+- **Polyglot engine architecture** — run Ruby, JavaScript, and Python code side by side
+- JavaScript engine via `mini_racer` with automatic variable bridging
+- Python engine via `pycall` with automatic variable bridging
+- Bidirectional Python ↔ Ruby calling through pycall bridge
+- Engine interface abstraction (`Mana::Engines::Base`)
+- Language auto-detection for polyglot dispatch
+
+### Changed
+- Refactored LLM logic into `Engines::LLM`, extracted from monolithic core
+
+### Fixed
+- Polyglot engine bug fixes (CodeRabbit review feedback)
+
+## [0.4.0] - 2026-02-22
+
+- Multi-LLM backend — Anthropic + OpenAI-compatible APIs
+- Test mode — `Mana.mock` + `mock_prompt` for stubbing LLM responses
+
+## [0.3.1] - 2026-02-21
+
+- Nested prompts — LLM calling LLM
+- Lambda `call_func` support
+- Expanded test coverage
+
+## [0.3.0] - 2026-02-21
+
+- Automatic memory — context sharing across LLM calls
+- Incognito mode
+- Persistent long-term memory
+- `Mana.session` — shared conversation context across prompts
+
+## [0.2.0] - 2026-02-20
+
+- Custom effect handlers — user-defined LLM tools
+- `mana def` — LLM-compiled methods with file caching
+- Auto-discover functions via Prism introspection
+
+## [0.1.0] - 2026-02-19
 
 - Initial release
 - `~"..."` syntax for embedding LLM prompts in Ruby

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,115 @@ Mana.incognito do
 end
 ```
 
+### Polyglot — Cross-Language Interop
+
+`~"..."` is a universal operator. It detects whether the code is JavaScript, Python, Ruby, or natural language, and routes to the appropriate engine. Variables bridge automatically.
+
+#### JavaScript
+
+```ruby
+require "mana"
+
+data = [1, 2, 3, 4, 5]
+
+# JavaScript — auto-detected from syntax
+~"const evens = data.filter(n => n % 2 === 0)"
+puts evens  # => [2, 4]
+
+# Multi-line with heredoc
+~<<~JS
+  const sum = evens.reduce((a, b) => a + b, 0)
+  const avg = sum / evens.length
+JS
+puts avg  # => 3.0
+```
+
+#### Python
+
+```ruby
+# Python — auto-detected
+~"evens = [n for n in data if n % 2 == 0]"
+puts evens  # => [2, 4]
+
+# Multi-line
+~<<~PY
+  import statistics
+  mean = statistics.mean(data)
+  stdev = statistics.stdev(data)
+PY
+puts mean   # => 3.0
+```
+
+#### Natural language (LLM) — existing behavior
+
+```ruby
+~"analyze <data> and find outliers, store in <result>"
+puts result
+```
+
+#### How detection works
+
+- Auto-detects from code syntax (token patterns)
+- Context-aware: consecutive `~"..."` calls tend to stay in the same language
+- Override with `Mana.engine = :javascript` or `Mana.with(:python) { ... }`
+- Detection rules are defined in `data/lang-rules.yml` — transparent, no black box
+
+#### Variable bridging
+
+- Simple types (numbers, strings, booleans, nil, arrays, hashes) are copied
+- Each engine maintains a persistent context (V8 for JS, Python interpreter for Python)
+- Variables created in one `~"..."` call persist for the next call in the same engine
+
+#### Setup
+
+```ruby
+# Gemfile
+gem "mana"
+gem "mini_racer"  # for JavaScript support (optional)
+gem "pycall"      # for Python support (optional)
+```
+
+### 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/data/lang-rules.yml

@@ -0,0 +1,196 @@
+version: 1
+languages:
+  javascript:
+    strong:
+      - "const "
+      - "let "
+      - "=> "
+      - "=== "
+      - "!== "
+      - "console.log"
+      - "console.error"
+      - ".filter("
+      - ".map("
+      - ".reduce("
+      - ".forEach("
+      - ".indexOf("
+      - ".push("
+      - "function "
+      - "async "
+      - "await "
+      - "require("
+      - "module.exports"
+      - "export "
+      - "import "
+      - "new Promise"
+      - "document."
+      - "window."
+      - "JSON.parse"
+      - "JSON.stringify"
+      - "typeof "
+      - "undefined"
+      - "null;"
+    weak:
+      - "var "
+      - "return "
+      - "true"
+      - "false"
+      - "null"
+      - "this."
+    anti:
+      - "let me"
+      - "let us"
+      - "let's"
+      - "const ant"
+      - "import ant"
+      - "import this"
+    patterns:
+      - "\\bfunction\\s+\\w+\\s*\\("
+      - "\\(\\s*\\w+\\s*\\)\\s*=>"
+      - "\\bclass\\s+\\w+\\s*\\{"
+
+  python:
+    strong:
+      - "elif "
+      - "print("
+      - "__init__"
+      - "__name__"
+      - "self."
+      - "import numpy"
+      - "import pandas"
+      - "lambda "
+      - "except "
+      - "finally:"
+      - "nonlocal "
+    weak:
+      - "def "
+      - "from "
+      - "yield "
+      - "raise "
+      - "assert "
+      - "global "
+      - "import "
+      - "return "
+      - "class "
+      - "for "
+      - "while "
+      - "if "
+      - "is not"
+      - "not in"
+      - "pass"
+    anti:
+      - "import this"
+      - "import that"
+      - "from here"
+      - "from there"
+      - "for example"
+      - "for instance"
+      - "while I"
+      - "while we"
+      - "if you"
+      - "if we"
+      - "with you"
+      - "with the"
+      - "with a "
+      - "with my"
+      - "and the"
+      - "and I"
+      - "and we"
+      - "or the"
+      - "or a "
+      - "or I"
+      - "or False"
+      - "True or"
+      - "as a "
+      - "as the"
+      - "as I"
+      - "pass the"
+      - "pass it"
+      - "pass on"
+    patterns:
+      - "\\[.+\\bfor\\b.+\\bin\\b.+\\]"
+      - "\\bdef\\s+\\w+\\s*\\("
+      - "\\bclass\\s+\\w+\\s*[:(]"
+      - "^\\s{4}"
+
+  ruby:
+    strong:
+      - "puts "
+      - "require "
+      - "require_relative"
+      - "attr_accessor"
+      - "attr_reader"
+      - "attr_writer"
+      - ".each "
+      - ".map "
+      - ".select "
+      - ".reject "
+      - "do |"
+      - "def "
+      - "module "
+      - "rescue "
+      - "ensure "
+      - "unless "
+      - "until "
+      - "elsif "
+      - "nil"
+      - "p "
+      - "pp "
+      - "Proc.new"
+      - "lambda {"
+      - "-> {"
+    weak:
+      - "end"
+      - "begin"
+      - "class "
+      - "return "
+      - "if "
+      - "for "
+      - "while "
+    anti:
+      - "the end"
+      - "in the end"
+      - "at the end"
+      - "begin with"
+      - "begin to"
+    patterns:
+      - "\\bdo\\s*\\|\\w+\\|"
+      - "\\bdef\\s+\\w+[?!]?"
+      - "\\bend\\b"
+
+  natural_language:
+    strong:
+      - "please "
+      - "analyze "
+      - "summarize "
+      - "translate "
+      - "explain "
+      - "find "
+      - "calculate "
+      - "generate "
+      - "create "
+      - "write "
+      - "describe "
+      - "compare "
+      - "store in <"
+      - "save in <"
+      - "put in <"
+      - ", store "
+      - ", save "
+    weak:
+      - "the "
+      - "a "
+      - "an "
+      - "is "
+      - "are "
+      - "was "
+      - "were "
+      - "what "
+      - "how "
+      - "why "
+      - "when "
+      - "where "
+      - "which "
+    anti: []
+    patterns:
+      - "<\\w+>"

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/compiler.rb

@@ -74,7 +74,7 @@ module Mana
                         "Return ONLY the complete method definition (def...end), no explanation. " \
                         "Store the code as a string in <code>"
 
-        Mana::Engine.run(engine_prompt, b)
+        Mana::Engines::LLM.new(b).execute(engine_prompt)
         code
       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