ruby-mana 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d264315170eee3756db9dc603810cb524ce0a933f15b8897d36e7306c20d25b1
+  data.tar.gz: fc2f36ef0eceec87a7ff9911384db6ed9c6f004eee8c279fc379d3d2c36756fb
+SHA512:
+  metadata.gz: be603cd3ddfcc6e457b656df9caff5ba8a9de4252dbb74416879daead34c64d7b4c50ad6ea422eaa21b76b92acc780e93b54425250e369e3f14223c0c82fee03
+  data.tar.gz: ae6ea7cb12475dded7d5f6cf1c1f73acfb2bc16b592741cd935b9406d118516e1530651095310bc791d436f0039991936e8074da053f629240f0ec5b2c396143

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0] - Unreleased
+
+- Initial release
+- `~"..."` syntax for embedding LLM prompts in Ruby
+- Effect system: read_var, write_var, read_attr, write_attr, call_func
+- Anthropic Claude backend
+- Variable binding via `<var>` convention

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 carlnoah6
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,158 @@
+# ruby-mana 🔮
+
+Embed LLM as native Ruby. Write natural language, it just runs.
+
+```ruby
+require "mana"
+
+numbers = [1, "2", "three", "cuatro", "五"]
+~"compute the semantic average of <numbers> and store in <result>"
+puts result  # => 3.0
+```
+
+## What is this?
+
+Mana turns LLM into a Ruby co-processor. Your natural language strings can read and write Ruby variables, call Ruby functions, manipulate objects, and control program flow — all from a single `~"..."`.
+
+Not an API wrapper. Not prompt formatting. Mana weaves LLM into your Ruby code as a first-class construct.
+
+## Install
+
+```bash
+gem install ruby-mana
+```
+
+Or in your Gemfile:
+
+```ruby
+gem "ruby-mana"
+```
+
+Requires Ruby 3.3+ and an Anthropic API key:
+
+```bash
+export ANTHROPIC_API_KEY=your_key_here
+```
+
+## Usage
+
+Prefix any string with `~` to make it an LLM prompt:
+
+```ruby
+require "mana"
+
+numbers = [1, 2, 3, 4, 5]
+~"compute the average of <numbers> and store in <result>"
+puts result
+```
+
+### Variables
+
+Use `<var>` to reference variables. Mana figures out read vs write:
+
+- Variable exists in scope → Mana reads it and passes to LLM
+- Variable doesn't exist → LLM creates it via `write_var`
+
+```ruby
+name = "Alice"
+scores = [85, 92, 78, 95, 88]
+
+~"analyze <scores> for <name>, store the mean in <average>, the highest in <best>, and a short comment in <comment>"
+
+puts average  # => 87.6
+puts best     # => 95
+puts comment  # => "Excellent and consistent performance"
+```
+
+### Object manipulation
+
+LLM can read and write object attributes:
+
+```ruby
+class Email
+  attr_accessor :subject, :body, :category, :priority
+end
+
+email = Email.new
+email.subject = "URGENT: Server down"
+email.body = "Database connection pool exhausted..."
+
+~"read <email> subject and body, then set its category and priority"
+
+puts email.category  # => "urgent"
+puts email.priority   # => "high"
+```
+
+### Calling Ruby functions
+
+LLM can call functions in your scope:
+
+```ruby
+def fetch_price(symbol)
+  { "AAPL" => 189.5, "GOOG" => 141.2, "TSLA" => 248.9 }[symbol] || 0
+end
+
+def send_alert(msg)
+  puts "[ALERT] #{msg}"
+end
+
+portfolio = ["AAPL", "GOOG", "TSLA", "MSFT"]
+
+~"iterate <portfolio>, call fetch_price for each, send_alert if price > 200, store the sum in <total>"
+puts total  # => 579.6
+```
+
+### Mixed control flow
+
+Ruby handles the structure, LLM handles the decisions:
+
+```ruby
+player_hp = 100
+enemy_hp = 80
+inventory = ["sword", "potion", "shield"]
+
+while player_hp > 0 && enemy_hp > 0
+  ~"player HP=<player_hp>, enemy HP=<enemy_hp>, inventory=<inventory>, choose an action and store in <action>"
+
+  case action
+  when "attack" then enemy_hp -= rand(15..25)
+  when "defend" then nil
+  when "use_item"
+    ~"pick a healing item from <inventory> and store its name in <item_name>"
+    inventory.delete(item_name)
+    player_hp += 25
+  end
+
+  player_hp -= action == "defend" ? rand(5..10) : rand(10..20)
+end
+```
+
+## Configuration
+
+```ruby
+Mana.configure do |c|
+  c.model = "claude-sonnet-4-20250514"
+  c.temperature = 0
+  c.api_key = ENV["ANTHROPIC_API_KEY"]
+  c.max_iterations = 50
+end
+
+# Or shorthand
+Mana.model = "claude-sonnet-4-20250514"
+```
+
+## How it works
+
+1. `~"..."` calls `String#~@`, which captures the caller's `Binding`
+2. Mana parses `<var>` references and reads existing variables as context
+3. The prompt + context is sent to the LLM with tools: `read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `done`
+4. LLM responds with tool calls → Mana executes them against the live Ruby binding → sends results back
+5. Loop until LLM calls `done` or returns without tool calls
+
+## Safety
+
+⚠️ Mana executes LLM-generated operations against your live Ruby state. Use with the same caution as `eval`.
+
+## License
+
+MIT

data/lib/mana/config.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Mana
+  class Config
+    attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url
+
+    def initialize
+      @model = "claude-sonnet-4-20250514"
+      @temperature = 0
+      @api_key = ENV["ANTHROPIC_API_KEY"]
+      @max_iterations = 50
+      @base_url = "https://api.anthropic.com"
+    end
+  end
+end

data/lib/mana/effects.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Mana
+  module Effects
+    ReadVar   = Struct.new(:name)
+    WriteVar  = Struct.new(:name, :value)
+    ReadAttr  = Struct.new(:obj_name, :attr)
+    WriteAttr = Struct.new(:obj_name, :attr, :value)
+    CallFunc  = Struct.new(:name, :args)
+    Done      = Struct.new(:result)
+  end
+end

data/lib/mana/engine.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Mana
+  class Engine
+    TOOLS = [
+      {
+        name: "read_var",
+        description: "Read a variable value from the Ruby scope.",
+        input_schema: {
+          type: "object",
+          properties: { name: { type: "string", description: "Variable name" } },
+          required: ["name"]
+        }
+      },
+      {
+        name: "write_var",
+        description: "Write a value to a variable in the Ruby scope. Creates the variable if it doesn't exist.",
+        input_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Variable name" },
+            value: { description: "Value to assign (any JSON type)" }
+          },
+          required: %w[name value]
+        }
+      },
+      {
+        name: "read_attr",
+        description: "Read an attribute from a Ruby object.",
+        input_schema: {
+          type: "object",
+          properties: {
+            obj: { type: "string", description: "Variable name holding the object" },
+            attr: { type: "string", description: "Attribute name to read" }
+          },
+          required: %w[obj attr]
+        }
+      },
+      {
+        name: "write_attr",
+        description: "Set an attribute on a Ruby object.",
+        input_schema: {
+          type: "object",
+          properties: {
+            obj: { type: "string", description: "Variable name holding the object" },
+            attr: { type: "string", description: "Attribute name to set" },
+            value: { description: "Value to assign" }
+          },
+          required: %w[obj attr value]
+        }
+      },
+      {
+        name: "call_func",
+        description: "Call a Ruby method/function available in the current scope.",
+        input_schema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Function/method name" },
+            args: { type: "array", description: "Arguments to pass", items: {} }
+          },
+          required: ["name"]
+        }
+      },
+      {
+        name: "done",
+        description: "Signal that the task is complete.",
+        input_schema: {
+          type: "object",
+          properties: {
+            result: { description: "Optional return value" }
+          }
+        }
+      }
+    ].freeze
+
+    class << self
+      def run(prompt, caller_binding)
+        new(prompt, caller_binding).execute
+      end
+
+      def handler_stack
+        Thread.current[:mana_handlers] ||= []
+      end
+
+      def with_handler(handler = nil, **opts, &block)
+        handler_stack.push(handler)
+        block.call
+      ensure
+        handler_stack.pop
+      end
+    end
+
+    def initialize(prompt, caller_binding)
+      @prompt = prompt
+      @binding = caller_binding
+      @config = Mana.config
+    end
+
+    def execute
+      context = build_context(@prompt)
+      system_prompt = build_system_prompt(context)
+      messages = [{ role: "user", content: @prompt }]
+
+      iterations = 0
+      done_result = nil
+
+      loop do
+        iterations += 1
+        raise MaxIterationsError, "exceeded #{@config.max_iterations} iterations" if iterations > @config.max_iterations
+
+        response = llm_call(system_prompt, messages)
+        tool_uses = extract_tool_uses(response)
+
+        break if tool_uses.empty?
+
+        # Append assistant message
+        messages << { role: "assistant", content: response }
+
+        # Process each tool use
+        tool_results = tool_uses.map do |tu|
+          result = handle_effect(tu)
+          done_result = tu[:input]["result"] if tu[:name] == "done"
+          { type: "tool_result", tool_use_id: tu[:id], content: result.to_s }
+        end
+
+        messages << { role: "user", content: tool_results }
+
+        break if tool_uses.any? { |t| t[:name] == "done" }
+      end
+
+      done_result
+    end
+
+    private
+
+    # --- Context Building ---
+
+    def build_context(prompt)
+      var_names = prompt.scan(/<(\w+)>/).flatten.uniq
+      ctx = {}
+      var_names.each do |name|
+        val = resolve(name)
+        ctx[name] = serialize_value(val)
+      rescue NameError
+        # Variable doesn't exist yet — will be created by LLM
+      end
+      ctx
+    end
+
+    def build_system_prompt(context)
+      parts = [
+        "You are embedded inside a Ruby program. You interact with the program's live state using the provided tools.",
+        "",
+        "Rules:",
+        "- Use read_var / read_attr to inspect variables and objects.",
+        "- Use write_var to create or update variables in the Ruby scope.",
+        "- Use write_attr to set attributes on Ruby objects.",
+        "- Use call_func to call Ruby methods available in scope.",
+        "- Call done when the task is complete.",
+        "- When the user references <var>, that's a variable in scope.",
+        "- If a referenced variable doesn't exist yet, the user expects you to create it with write_var.",
+        "- Be precise with types: use numbers for numeric values, arrays for lists, strings for text."
+      ]
+
+      unless context.empty?
+        parts << ""
+        parts << "Current variable values:"
+        context.each { |k, v| parts << "  #{k} = #{v}" }
+      end
+
+      parts.join("\n")
+    end
+
+    # --- Effect Handling ---
+
+    def handle_effect(tool_use)
+      name = tool_use[:name]
+      input = tool_use[:input] || {}
+      # Normalize keys to strings for consistent access
+      input = input.transform_keys(&:to_s) if input.is_a?(Hash)
+
+      # Check handler stack first
+      handler = self.class.handler_stack.last
+      return handler.call(name, input) if handler && handler.respond_to?(:call)
+
+      case name
+      when "read_var"
+        serialize_value(resolve(input["name"]))
+
+      when "write_var"
+        var_name = input["name"]
+        value = input["value"]
+        write_local(var_name, value)
+        "ok: #{var_name} = #{value.inspect}"
+
+      when "read_attr"
+        obj = resolve(input["obj"])
+        validate_name!(input["attr"])
+        serialize_value(obj.public_send(input["attr"]))
+
+      when "write_attr"
+        obj = resolve(input["obj"])
+        validate_name!(input["attr"])
+        obj.public_send("#{input['attr']}=", input["value"])
+        "ok: #{input['obj']}.#{input['attr']} = #{input['value'].inspect}"
+
+      when "call_func"
+        func = input["name"]
+        validate_name!(func)
+        args = input["args"] || []
+        result = @binding.receiver.method(func.to_sym).call(*args)
+        serialize_value(result)
+
+      when "done"
+        input["result"].to_s
+
+      else
+        "error: unknown tool #{name}"
+      end
+    rescue => e
+      "error: #{e.class}: #{e.message}"
+    end
+
+    # --- Binding Helpers ---
+
+    VALID_IDENTIFIER = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+    def validate_name!(name)
+      raise Mana::Error, "invalid identifier: #{name.inspect}" unless name.match?(VALID_IDENTIFIER)
+    end
+
+    def resolve(name)
+      validate_name!(name)
+      if @binding.local_variable_defined?(name.to_sym)
+        @binding.local_variable_get(name.to_sym)
+      elsif @binding.receiver.respond_to?(name.to_sym, true)
+        @binding.receiver.send(name.to_sym)
+      else
+        raise NameError, "undefined variable or method '#{name}'"
+      end
+    end
+
+    def write_local(name, value)
+      validate_name!(name)
+      @binding.local_variable_set(name.to_sym, value)
+    end
+
+    def serialize_value(val)
+      case val
+      when String, Integer, Float, TrueClass, FalseClass, NilClass
+        val.inspect
+      when Symbol
+        val.to_s.inspect
+      when Array
+        "[#{val.map { |v| serialize_value(v) }.join(', ')}]"
+      when Hash
+        pairs = val.map { |k, v| "#{serialize_value(k)} => #{serialize_value(v)}" }
+        "{#{pairs.join(', ')}}"
+      else
+        ivars = val.instance_variables
+        obj_repr = ivars.map do |ivar|
+          attr_name = ivar.to_s.delete_prefix("@")
+          "#{attr_name}: #{val.instance_variable_get(ivar).inspect}" rescue nil
+        end.compact.join(", ")
+        "#<#{val.class} #{obj_repr}>"
+      end
+    end
+
+    # --- LLM Client ---
+
+    def llm_call(system, messages)
+      uri = URI("#{@config.base_url}/v1/messages")
+      body = {
+        model: @config.model,
+        max_tokens: 4096,
+        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
+
+    def extract_tool_uses(content)
+      return [] unless content.is_a?(Array)
+
+      content
+        .select { |block| block[:type] == "tool_use" }
+        .map { |block| { id: block[:id], name: block[:name], input: block[:input] || {} } }
+    end
+  end
+end

data/lib/mana/llm/anthropic.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Mana
+  module LLM
+    class Anthropic < Base
+      API_URL = "https://api.anthropic.com/v1/messages"
+      API_VERSION = "2023-06-01"
+
+      def initialize(config = Mana.config)
+        super(config)
+        @api_key = config.api_key
+        @model = config.model
+      end
+
+      def chat(system:, messages:, tools:)
+        raise Mana::Error, "Anthropic API key not set" unless @api_key
+
+        body = {
+          model: @model,
+          max_tokens: 4096,
+          temperature: @config.temperature,
+          system: system,
+          messages: messages,
+          tools: tools
+        }
+
+        response = post(body)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          parsed = JSON.parse(response.body) rescue nil
+          error_msg = parsed&.dig("error", "message") || response.body
+          raise Mana::Error, "Anthropic API error (#{response.code}): #{error_msg}"
+        end
+
+        parsed = JSON.parse(response.body)
+        parsed["content"].map { |block| symbolize_keys(block) }
+      end
+
+      private
+
+      def post(body)
+        uri = URI(API_URL)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 30
+        http.read_timeout = 120
+        http.write_timeout = 30
+
+        request = Net::HTTP::Post.new(uri)
+        request["x-api-key"] = @api_key
+        request["anthropic-version"] = API_VERSION
+        request["content-type"] = "application/json"
+        request.body = JSON.generate(body)
+
+        http.request(request)
+      end
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) do |(k, v), acc|
+          acc[k.to_sym] = v.is_a?(Hash) ? symbolize_keys(v) : v
+        end
+      end
+    end
+  end
+end

data/lib/mana/llm/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Mana
+  module LLM
+    # Base interface for LLM clients.
+    # Subclass and implement #chat to add new providers.
+    class Base
+      def initialize(config)
+        @config = config
+      end
+
+      # Send a chat request with tools.
+      # Returns an array of content blocks (tool_use / text).
+      def chat(system:, messages:, tools:)
+        raise NotImplementedError, "#{self.class}#chat not implemented"
+      end
+    end
+  end
+end

data/lib/mana/mixin.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Mana
+  # Include in classes to use ~"..." in instance methods.
+  # binding_of_caller handles scope automatically, so this
+  # is mainly a semantic marker + future extension point.
+  module Mixin
+    def self.included(base)
+      # Reserved for future: auto-expose methods, etc.
+    end
+  end
+end

data/lib/mana/string_ext.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "binding_of_caller"
+
+class String
+  # ~"natural language prompt" → execute via Mana engine
+  def ~@
+    Mana::Engine.run(self, binding.of_caller(1))
+  end
+end

data/lib/mana/version.rb

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

data/lib/mana.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "mana/version"
+require_relative "mana/config"
+require_relative "mana/effects"
+require_relative "mana/engine"
+require_relative "mana/string_ext"
+require_relative "mana/mixin"
+
+module Mana
+  class Error < StandardError; end
+  class MaxIterationsError < Error; end
+  class LLMError < Error; end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield(config) if block_given?
+      config
+    end
+
+    def model=(model)
+      config.model = model
+    end
+
+    def handle(handler = nil, **opts, &block)
+      Engine.with_handler(handler, **opts, &block)
+    end
+
+    def reset!
+      @config = Config.new
+    end
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: ruby-mana
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Carl
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: binding_of_caller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  Mana lets you write natural language strings in Ruby that execute via LLM
+  with full access to your program's live state. Read/write variables, call
+  functions, manipulate objects — all from a simple ~"..." syntax.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/mana.rb
+- lib/mana/config.rb
+- lib/mana/effects.rb
+- lib/mana/engine.rb
+- lib/mana/llm/anthropic.rb
+- lib/mana/llm/base.rb
+- lib/mana/mixin.rb
+- lib/mana/string_ext.rb
+- lib/mana/version.rb
+homepage: https://github.com/carlnoah6/ruby-mana
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/carlnoah6/ruby-mana
+  source_code_uri: https://github.com/carlnoah6/ruby-mana
+  changelog_uri: https://github.com/carlnoah6/ruby-mana/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Embed LLM as native Ruby — write natural language, it just runs
+test_files: []