ruby-mana 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d264315170eee3756db9dc603810cb524ce0a933f15b8897d36e7306c20d25b1
-  data.tar.gz: fc2f36ef0eceec87a7ff9911384db6ed9c6f004eee8c279fc379d3d2c36756fb
+  metadata.gz: ddacfb41b0e2ca07887ffd1c683e211f90529901a4a401393c1c1da91f5da46c
+  data.tar.gz: 33db80124c57c45499b0a8ae392463782d6e3c6f221853e9d1353ac7f64838af
 SHA512:
-  metadata.gz: be603cd3ddfcc6e457b656df9caff5ba8a9de4252dbb74416879daead34c64d7b4c50ad6ea422eaa21b76b92acc780e93b54425250e369e3f14223c0c82fee03
-  data.tar.gz: ae6ea7cb12475dded7d5f6cf1c1f73acfb2bc16b592741cd935b9406d118516e1530651095310bc791d436f0039991936e8074da053f629240f0ec5b2c396143
+  metadata.gz: 2c604e080b7a6d4cf04d54d4782d7c36d9789d76f7e485728c1eb1869757ae320d688a8f222c00d9591116e300fec2f7272d77f04b1d9c402edef714ea628b24
+  data.tar.gz: 2ac2008b69a995bf5d1c4a098d25e3cb89b02b6a83e48c15014a7ba1268efecb3f84ca756a4efd3d53a200b6e160d0c79c38f6571eb581895dac6a9764e343e7

data/README.md

@@ -135,19 +135,133 @@ Mana.configure do |c|
   c.temperature = 0
   c.api_key = ENV["ANTHROPIC_API_KEY"]
   c.max_iterations = 50
+
+  # Memory settings
+  c.namespace = "my-project"      # nil = auto-detect from git/pwd
+  c.context_window = 200_000      # nil = auto-detect from model
+  c.memory_pressure = 0.7         # compact when tokens exceed 70% of context window
+  c.memory_keep_recent = 4        # keep last 4 rounds during compaction
+  c.compact_model = nil           # nil = use main model for compaction
+  c.memory_store = Mana::FileStore.new  # default file-based persistence
 end
+```
+
+### 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.
+
+```ruby
+# No params
+Mana.define_effect :get_time do
+  Time.now.to_s
+end
+
+# With params — keyword args become tool parameters
+Mana.define_effect :query_db do |sql:|
+  ActiveRecord::Base.connection.execute(sql).to_a
+end
+
+# With description (optional, recommended)
+Mana.define_effect :search_web,
+  description: "Search the web for information" do |query:, max_results: 5|
+    WebSearch.search(query, limit: max_results)
+  end
 
-# Or shorthand
-Mana.model = "claude-sonnet-4-20250514"
+# Use in prompts
+~"get the current time and store in <now>"
+~"find recent orders using query_db, store in <orders>"
 ```
 
+Built-in effects (`read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `done`) are reserved and cannot be overridden.
+
+### Memory — automatic context sharing
+
+Consecutive `~"..."` calls automatically share context. No wrapper block needed:
+
+```ruby
+~"remember: always translate to Japanese, casual tone"
+~"translate <text1>, store in <result1>"   # uses the preference
+~"translate <text2>, store in <result2>"   # still remembers
+~"which translation was harder? store in <analysis>"  # can reference both
+```
+
+Memory is per-thread and auto-created on the first `~"..."` call.
+
+#### Long-term memory
+
+The LLM has a `remember` tool that persists facts across script executions:
+
+```ruby
+~"remember that the user prefers concise output"
+# ... later, in a different script execution ...
+~"translate <text>"  # LLM sees the preference in its long-term memory
+```
+
+Manage long-term memory via Ruby:
+
+```ruby
+Mana.memory.long_term          # view all memories
+Mana.memory.forget(id: 2)     # remove a specific memory
+Mana.memory.clear_long_term!   # clear all long-term memories
+Mana.memory.clear_short_term!  # clear conversation history
+Mana.memory.clear!             # clear everything
+```
+
+#### Incognito mode
+
+Run without any memory — nothing is loaded or saved:
+
+```ruby
+Mana.incognito do
+  ~"translate <text>"  # no memory, no persistence
+end
+```
+
+### LLM-compiled methods
+
+`mana def` lets LLM generate a method implementation on first call. The generated code is cached as a real `.rb` file — subsequent calls are pure Ruby with zero API overhead.
+
+```ruby
+mana def fizzbuzz(n)
+  ~"return an array of FizzBuzz results from 1 to n"
+end
+
+fizzbuzz(15)  # first call → LLM generates code → cached → executed
+fizzbuzz(20)  # pure Ruby from .mana_cache/fizzbuzz.rb
+
+# View the generated source
+puts Mana.source(:fizzbuzz)
+# def fizzbuzz(n)
+#   (1..n).map do |i|
+#     if i % 15 == 0 then "FizzBuzz"
+#     elsif i % 3 == 0 then "Fizz"
+#     elsif i % 5 == 0 then "Buzz"
+#     else i.to_s
+#     end
+#   end
+# end
+
+# Works in classes too
+class Converter
+  include Mana::Mixin
+
+  mana def celsius_to_fahrenheit(c)
+    ~"convert Celsius to Fahrenheit"
+  end
+end
+```
+
+Generated files live in `.mana_cache/` (add to `.gitignore`, or commit them to skip LLM on CI).
+
 ## 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
+3. Memory loads long-term facts and prior conversation into the system prompt
+4. The prompt + context is sent to the LLM with tools: `read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `remember`, `done`
+5. LLM responds with tool calls → Mana executes them against the live Ruby binding → sends results back
+6. Loop until LLM calls `done` or returns without tool calls
+7. After completion, memory compaction runs in background if context is getting large
 
 ## Safety
 

data/lib/mana/compiler.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+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"
+  #   end
+  #
+  #   fizzbuzz(15)  # first call → LLM generates code → cached → executed
+  #   fizzbuzz(20)  # subsequent calls → pure Ruby, zero API overhead
+  #
+  #   Mana.source(:fizzbuzz)  # view generated source
+  module Compiler
+    class << self
+      # Registry of compiled method sources: { "ClassName#method" => source_code }
+      def registry
+        @registry ||= {}
+      end
+
+      # Cache directory for generated .rb files
+      def cache_dir
+        @cache_dir || ".mana_cache"
+      end
+
+      attr_writer :cache_dir
+
+      # Get the generated source for a compiled method
+      def source(method_name, owner: nil)
+        key = registry_key(method_name, owner)
+        registry[key]
+      end
+
+      # Compile a method: wrap it so first invocation triggers LLM code generation
+      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
+        prompt = extract_prompt(original)
+
+        # Build parameter signature for the generated method
+        params_desc = describe_params(original)
+
+        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)
+
+          # Store in registry
+          compiler.registry[key] = generated
+
+          # Define the method on the correct owner (not Object) via class_eval
+          target_owner = owner
+          target_owner.class_eval(generated, cache_path, 1)
+
+          # Call the now-native method
+          send(method_name, *args, **kwargs, &blk)
+        end
+      end
+
+      # Generate Ruby method source via LLM
+      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::Engine.run(engine_prompt, b)
+        code
+      end
+
+      # Write generated code to a cache file, return the path
+      def write_cache(method_name, source, owner = 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
+      end
+
+      # Clear all cached files and registry
+      def clear!
+        FileUtils.rm_rf(cache_dir) if Dir.exist?(cache_dir)
+        @registry = {}
+      end
+
+      private
+
+      def registry_key(method_name, owner = nil)
+        if owner && owner != Object
+          "#{owner}##{method_name}"
+        else
+          method_name.to_s
+        end
+      end
+
+      # Extract the prompt string from the original method.
+      # The method body should be a single ~"..." expression.
+      def extract_prompt(unbound_method)
+        source_loc = unbound_method.source_location
+        return nil 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
+        end
+
+        # Extract string content from ~"..." pattern
+        body = body_lines.join
+        match = body.match(/~"([^"]*)"/) || body.match(/~'([^']*)'/)
+        match ? match[1] : body_lines[1...-1].join.strip
+      end
+
+      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
+          end
+        end.join(", ")
+      end
+
+      def underscore(str)
+        return "anonymous" if str.nil? || str.empty?
+
+        str.gsub("::", "_")
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+           .downcase
+      end
+    end
+  end
+end

data/lib/mana/config.rb

@@ -2,7 +2,10 @@
 
 module Mana
   class Config
-    attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url
+    attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url,
+                  :namespace, :memory_store, :memory_path,
+                  :context_window, :memory_pressure, :memory_keep_recent,
+                  :compact_model, :on_compact
 
     def initialize
       @model = "claude-sonnet-4-20250514"
@@ -10,6 +13,14 @@ module Mana
       @api_key = ENV["ANTHROPIC_API_KEY"]
       @max_iterations = 50
       @base_url = "https://api.anthropic.com"
+      @namespace = nil
+      @memory_store = nil
+      @memory_path = nil
+      @context_window = nil
+      @memory_pressure = 0.7
+      @memory_keep_recent = 4
+      @compact_model = nil
+      @on_compact = nil
     end
   end
 end

data/lib/mana/context_window.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Mana
+  module ContextWindow
+    SIZES = {
+      /claude-3-5-sonnet/ => 200_000,
+      /claude-sonnet-4/ => 200_000,
+      /claude-3-5-haiku/ => 200_000,
+      /claude-3-opus/ => 200_000,
+      /claude-opus-4/ => 200_000,
+      /gpt-4o/ => 128_000,
+      /gpt-4-turbo/ => 128_000,
+      /gpt-3\.5/ => 16_385
+    }.freeze
+
+    DEFAULT = 128_000
+
+    def self.detect(model_name)
+      return DEFAULT unless model_name
+
+      SIZES.each do |pattern, size|
+        return size if model_name.match?(pattern)
+      end
+
+      DEFAULT
+    end
+  end
+end

data/lib/mana/effect_registry.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Mana
+  # Registry for custom effect handlers.
+  #
+  # Users define effects that become LLM tools automatically:
+  #
+  #   Mana.define_effect :query_db,
+  #     description: "Execute a SQL query" do |sql:|
+  #       DB.execute(sql)
+  #     end
+  #
+  # The block's keyword parameters become the tool's input schema.
+  # The block's return value is serialized and sent back to the LLM.
+  module EffectRegistry
+    class EffectDefinition
+      attr_reader :name, :description, :handler, :params
+
+      def initialize(name, description: nil, &handler)
+        @name = name.to_s
+        @description = description || @name
+        @handler = handler
+        @params = extract_params(handler)
+      end
+
+      # Convert to LLM tool definition
+      def to_tool
+        properties = {}
+        required = []
+
+        @params.each do |param|
+          properties[param[:name]] = {
+            type: infer_type(param[:default]),
+            description: param[:name]
+          }
+          required << param[:name] if param[:required]
+        end
+
+        tool = {
+          name: @name,
+          description: @description,
+          input_schema: {
+            type: "object",
+            properties: properties
+          }
+        }
+        tool[:input_schema][:required] = required unless required.empty?
+        tool
+      end
+
+      # Call the handler with LLM-provided input
+      def call(input)
+        kwargs = {}
+        @params.each do |param|
+          key = param[:name]
+          if input.key?(key)
+            kwargs[key.to_sym] = input[key]
+          elsif param[:default] != :__mana_no_default__
+            # Use block's default
+          elsif param[:required]
+            raise Mana::Error, "missing required parameter: #{key}"
+          end
+        end
+
+        if kwargs.empty? && @params.empty?
+          @handler.call
+        else
+          @handler.call(**kwargs)
+        end
+      end
+
+      private
+
+      def extract_params(block)
+        return [] unless block
+
+        block.parameters.map do |(type, name)|
+          case type
+          when :keyreq
+            { name: name.to_s, required: true, default: :__mana_no_default__ }
+          when :key
+            # Try to get default value — not possible via reflection,
+            # so we mark it as optional with unknown default
+            { name: name.to_s, required: false, default: nil }
+          when :keyrest
+            # **kwargs — skip, can't generate schema
+            nil
+          else
+            # Positional args — treat as required string params
+            { name: name.to_s, required: true, default: :__mana_no_default__ } if name
+          end
+        end.compact
+      end
+
+      def infer_type(default)
+        case default
+        when Integer then "integer"
+        when Float then "number"
+        when TrueClass, FalseClass then "boolean"
+        when Array then "array"
+        when Hash then "object"
+        else "string"
+        end
+      end
+    end
+
+    RESERVED_EFFECTS = %w[read_var write_var read_attr write_attr call_func done remember].freeze
+
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      def define(name, description: nil, &handler)
+        name_s = name.to_s
+        if RESERVED_EFFECTS.include?(name_s)
+          raise Mana::Error, "cannot override built-in effect: #{name_s}"
+        end
+
+        registry[name_s] = EffectDefinition.new(name, description: description, &handler)
+      end
+
+      def undefine(name)
+        registry.delete(name.to_s)
+      end
+
+      def defined?(name)
+        registry.key?(name.to_s)
+      end
+
+      def get(name)
+        registry[name.to_s]
+      end
+
+      # Generate tool definitions for all registered effects
+      def tool_definitions
+        registry.values.map(&:to_tool)
+      end
+
+      def clear!
+        @registry = {}
+      end
+
+      # Handle a tool call if it matches a registered effect
+      # Returns [handled, result] — handled is true if we processed it
+      def handle(name, input)
+        effect = get(name)
+        return [false, nil] unless effect
+
+        result = effect.call(input)
+        [true, result]
+      end
+    end
+  end
+end