ruby-mana 0.5.8 → 0.5.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5431629c8418ec913228485f8874858561368c88430b246d0a463a4153a4714c
-  data.tar.gz: cc3a8ec9b69aec797c5fc3ceea8db052a9d75726937cf39d5c00f7e4b1cec85a
+  metadata.gz: dec47003f35644ccba81fd005d200be2046c9e32c8a939ce1b4e74d90defc9cc
+  data.tar.gz: 2f7986b4125ca844517002630195c16fedd0ea182a753ae3836d3cd951721d20
 SHA512:
-  metadata.gz: 20ee6065e53a175daadaee4d716c2355b15e312b8f4cf7de064fffbed2f1d8a4ab3a609896817fd9412ee2079a5a4583a0602c1bdae39f54ae56656ba10e5c9d
-  data.tar.gz: 4ba20a60f760a827023e9d18e6f5195d9506a44251124e28d7279e531e08381fa9170bc11144e6c54425858a4e6f389113ca4a5253433328edf1e34f3aa709bb
+  metadata.gz: caa5b68af0f5658f1cc5ff0c053b4b15cb44e88872d07102454171abd4b5d53eacfe39db1d5b8622e76f87a8f45e44944a5e0dfd44055975dfc2324d3af24560
+  data.tar.gz: 202a6b979ecd66f3c8dd4c949d299479ce73ff47e4a6cbc98d06651d103bc1fd5a791bdd0719be9abdfc1bf2aa745fdc5ba73a557119f9c1452d8b37689212ae

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.5.10] - 2026-03-27
+
+### Added
+- `Mana.chat` — interactive REPL mode with streaming output and colored prompts
+- `think` tool — LLM can plan approach before acting on complex tasks
+- Streaming support for Anthropic backend (`chat_stream` with SSE parsing)
+- Agent behavior guidelines in system prompt (think → read → act → verify)
+
+## [0.5.9] - 2026-03-27
+
+### Added
+- `error` tool — LLM can signal task failure, raised as `Mana::LLMError` to the Ruby caller
+- Text-only LLM responses (after nudge) now raise `LLMError` instead of returning `nil`
+
+## [0.5.8] - 2026-03-27
+
+### Added
+- `local_variables` support — LLM can call `local_variables` via `call_func` to discover variables in scope (binding-routed for correct scoping)
+
 ## [0.5.7] - 2026-03-27
 
 ### Security

data/README.md

@@ -1,6 +1,8 @@
 # ruby-mana 🔮
 
-Embed LLM as native Ruby. Write natural language, it just runs.
+[![Gem Version](https://badge.fury.io/rb/ruby-mana.svg)](https://rubygems.org/gems/ruby-mana) · [Website](https://twokidscarl.github.io/ruby-mana/) · [RubyGems](https://rubygems.org/gems/ruby-mana) · [GitHub](https://github.com/twokidsCarl/ruby-mana)
+
+Embed LLM as native Ruby. Write natural language, it just runs. Not an API wrapper — a language construct that weaves LLM into your code.
 
 ```ruby
 require "mana"
@@ -10,12 +12,6 @@ numbers = [1, "2", "three", "cuatro", "五"]
 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
@@ -91,9 +87,11 @@ puts email.priority   # => "high"
 
 ### Calling Ruby functions
 
-LLM can call functions in your scope:
+LLM discovers and calls your Ruby functions automatically. Add YARD comments for better understanding:
 
 ```ruby
+# Look up stock price by symbol
+# @param symbol [String] ticker symbol
 def fetch_price(symbol)
   { "AAPL" => 189.5, "GOOG" => 141.2, "TSLA" => 248.9 }[symbol] || 0
 end
@@ -108,6 +106,46 @@ portfolio = ["AAPL", "GOOG", "TSLA", "MSFT"]
 puts total  # => 579.6
 ```
 
+The LLM sees your functions with descriptions and types:
+```
+Available Ruby functions:
+  fetch_price(symbol) — Look up stock price by symbol
+  send_alert(msg)
+```
+
+Both positional and keyword arguments are supported. Functions are discovered from the source file (via Prism AST) and from methods defined on `self`.
+
+### 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 fibonacci(n)
+  ~"return an array of the first n Fibonacci numbers"
+end
+
+fibonacci(10)  # first call → LLM generates code → cached
+fibonacci(20)  # second call → loads from cache, no LLM, no waiting
+
+# View the generated source
+puts Mana.source(:fibonacci)
+
+# Works in classes too
+class Converter
+  include Mana::Mixin
+
+  mana def celsius_to_fahrenheit(c)
+    ~"convert Celsius to Fahrenheit"
+  end
+end
+
+puts Mana.source(:celsius_to_fahrenheit, owner: Converter)
+```
+
+Generated files live in `.mana_cache/` (add to `.gitignore`, or commit them to skip LLM on CI).
+
+## Advanced
+
 ### Mixed control flow
 
 Ruby handles the structure, LLM handles the decisions:
@@ -150,39 +188,50 @@ lint = ->(code) { ~"check #{code} for style issues, store in <issues>" }
 
 Each nested call gets its own conversation context. The outer LLM only sees the function's return value, keeping its context clean.
 
-### LLM-compiled methods
+### Memory
 
-`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.
+Mana has two types of memory:
+
+- **Short-term memory** — conversation history within the current process. Each `~"..."` call appends to it, so consecutive calls share context. Cleared when the process exits.
+- **Long-term memory** — persistent facts stored on disk (`~/.mana/`). Survives across script executions. The LLM can save facts via the `remember` tool.
 
 ```ruby
-mana def fibonacci(n)
-  ~"return an array of the first n Fibonacci numbers"
-end
+~"translate <text1> to Japanese, store in <result1>"
+~"translate <text2> to the same language, store in <result2>"   # remembers "Japanese"
 
-fibonacci(10)  # first call → LLM generates code → cached → executed
-fibonacci(20)  # pure Ruby from .mana_cache/
+~"remember that the user prefers concise output"
+# persists to ~/.mana/ — available in future script runs
+```
 
-# View the generated source
-puts Mana.source(:fibonacci)
-# def fibonacci(n)
-#   return [] if n <= 0
-#   return [0] if n == 1
-#   fib = [0, 1]
-#   (2...n).each { |i| fib << fib[i-1] + fib[i-2] }
-#   fib
-# end
+```ruby
+Mana.memory.short_term         # view conversation history
+Mana.memory.long_term          # view persisted facts
+Mana.memory.forget(id: 2)     # remove a specific fact
+Mana.memory.clear!             # clear everything
+```
 
-# Works in classes too
-class Converter
-  include Mana::Mixin
+#### Compaction
 
-  mana def celsius_to_fahrenheit(c)
-    ~"convert Celsius to Fahrenheit"
-  end
+When conversation history grows large, Mana automatically compacts old messages into summaries:
+
+```ruby
+Mana.configure do |c|
+  c.memory_pressure = 0.7       # compact when tokens > 70% of context window
+  c.memory_keep_recent = 4      # keep last 4 rounds, summarize the rest
+  c.compact_model = nil          # nil = use main model for summarization
+  c.on_compact = ->(summary) { puts "Compacted: #{summary}" }
 end
 ```
 
-Generated files live in `.mana_cache/` (add to `.gitignore`, or commit them to skip LLM on CI).
+#### Incognito mode
+
+Run without any memory — nothing is loaded or saved:
+
+```ruby
+Mana.incognito do
+  ~"translate <text>"  # no memory, no persistence
+end
+```
 
 ## Configuration
 
@@ -196,7 +245,6 @@ export MANA_MODEL=claude-sonnet-4-6                  # default model
 export MANA_VERBOSE=true                             # show LLM interactions
 export MANA_TIMEOUT=120                              # HTTP timeout in seconds
 export MANA_BACKEND=anthropic                        # force backend (anthropic/openai)
-export MANA_SECURITY=standard                        # security level (0-4 or name)
 ```
 
 | Environment Variable | Config | Default | Description |
@@ -209,7 +257,6 @@ export MANA_SECURITY=standard                        # security level (0-4 or na
 | `MANA_VERBOSE` | `c.verbose` | `false` | Log LLM calls to stderr |
 | `MANA_TIMEOUT` | `c.timeout` | `120` | HTTP timeout (seconds) |
 | `MANA_BACKEND` | `c.backend` | auto-detect | Force `anthropic` or `openai` |
-| `MANA_SECURITY` | `c.security` | `:standard` (2) | Security level: `sandbox`, `strict`, `standard`, `permissive`, `danger` |
 
 Programmatic config (overrides env vars):
 
@@ -220,7 +267,6 @@ Mana.configure do |c|
   c.api_key = "sk-..."
   c.verbose = true
   c.timeout = 120
-  c.security = :strict            # security level (0-4 or symbol)
 
   # Memory settings
   c.namespace = "my-project"      # nil = auto-detect from git/pwd
@@ -232,160 +278,7 @@ 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-6"
-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.
-
-### Security policy
-
-Mana restricts what the LLM can call via security levels (higher = more permissions):
-
-| Level | Name | What LLM Can Do | What's Blocked |
-|-------|------|-----------------|----------------|
-| 0 | `:sandbox` | Read/write variables, call user-defined functions only | Everything else |
-| 1 | `:strict` | + safe stdlib (`Time.now`, `Date.today`, `Math.*`) | Filesystem, network, system calls, eval |
-| **2** | **`:standard`** (default) | + read filesystem (`File.read`, `Dir.glob`) | Write/delete files, network, eval |
-| 3 | `:permissive` | + write files, network, require | eval, system/exec/fork |
-| 4 | `:danger` | No restrictions | Nothing |
-
-Default is **level 2 (`:standard`)**. Set via config or env var:
-
-```ruby
-Mana.configure { |c| c.security = :standard }
-# or
-Mana.configure { |c| c.security = 2 }
-```
-
-Fine-grained overrides:
-
-```ruby
-Mana.configure do |c|
-  c.security = :strict
-  c.security.allow_receiver "File", only: %w[read exist?]
-  c.security.block_method "puts"
-  c.security.block_receiver "Net::HTTP"
-end
-```
-
-### Function discovery
-
-Mana automatically discovers your Ruby functions and makes them available to the LLM. Add comments above your functions for better LLM understanding:
-
-```ruby
-# Query the database and return results
-# @param sql [String] the SQL query
-# @param limit [Integer] maximum rows to return
-def query_db(sql:, limit: 10)
-  ActiveRecord::Base.connection.execute(sql).first(limit)
-end
-
-# Search the web for information
-# @param query [String] search keywords
-def search_web(query:)
-  WebSearch.search(query)
-end
-
-~"use query_db to find recent orders, store in <orders>"
-~"search_web for 'ruby mana gem', store in <results>"
-```
-
-The LLM sees:
-```
-Available Ruby functions:
-  query_db(sql:, limit: ...) — Query the database and return results
-  search_web(query:) — Search the web for information
-```
-
-Both positional and keyword arguments are supported. Functions are discovered from the source file (via Prism AST) and from methods defined on `self`.
-
-### Memory
-
-Mana has two types of memory:
-
-- **Short-term memory** — conversation history within the current process. Each `~"..."` call appends to it, so consecutive calls share context. Cleared when the process exits.
-- **Long-term memory** — persistent facts stored on disk. Survives across script executions. The LLM can save facts via the `remember` tool.
-
-#### Short-term memory (conversation context)
-
-Consecutive `~"..."` calls automatically share context. No wrapper block needed:
-
-```ruby
-~"translate <text1> to Japanese, store in <result1>"
-~"translate <text2> to the same language, store in <result2>"   # remembers "Japanese"
-~"which translation was harder? store in <analysis>"            # can reference both
-```
-
-Short-term memory is per-thread and auto-created on the first `~"..."` call.
-
-```ruby
-Mana.memory.short_term         # view conversation history
-Mana.memory.clear_short_term!  # clear conversation history
-```
-
-#### Long-term memory (persistent facts)
-
-The LLM has a `remember` tool that persists facts to disk. These survive across script executions:
-
-```ruby
-# script_1.rb
-~"remember that the user prefers concise output"
-
-# script_2.rb (later, separate execution)
-~"translate <text>"  # LLM sees "user prefers concise output" in long-term memory
-```
-
-Identical content is automatically deduplicated.
-
-```ruby
-Mana.memory.long_term          # view all persisted facts
-Mana.memory.forget(id: 2)     # remove a specific fact
-Mana.memory.clear_long_term!   # clear all long-term memory
-Mana.memory.clear!             # clear both short-term and long-term
-```
-
-#### Incognito mode
-
-Run without any memory — nothing is loaded or saved:
-
-```ruby
-Mana.incognito do
-  ~"translate <text>"  # no memory, no persistence
-end
-```
-
-
-### Testing
+## Testing
 
 Use `Mana.mock` to test code that uses `~"..."` without calling any API:
 
@@ -444,13 +337,39 @@ Unmatched prompts raise `Mana::MockError` with a helpful message suggesting the
 
 ## How it works
 
-1. `~"..."` calls `String#~@`, which captures the caller's `Binding`
-2. Mana parses `<var>` references and reads existing variables as context
-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
+```
+  Your Ruby code                        LLM (Claude/GPT/...)
+  ─────────────                         ────────────────────
+  numbers = [1, 2, 3]
+  ~"average of <numbers>,          ──→  system prompt:
+    store in <result>"                    - rules + tools
+                                          - memory (short/long-term)
+                                          - variables: numbers = [1,2,3]
+                                          - available functions
+
+                                    ←──  tool_call: read_var("numbers")
+  return [1, 2, 3]                 ──→
+
+                                    ←──  tool_call: write_var("result", 2.0)
+  binding.local_variable_set       ──→   ok
+
+                                    ←──  tool_call: done(result: 2.0)
+  result == 2.0 ✓
+```
+
+**Step by step:**
+
+1. **`~"..."` triggers `String#~@`** — captures the caller's `Binding` via `binding_of_caller`, giving Mana access to local variables, methods, and objects in scope.
+
+2. **Build context** — parses `<var>` references from the prompt, reads their current values, discovers available functions via Prism AST (with YARD descriptions if present).
+
+3. **Build system prompt** — assembles rules, memory (short-term conversation + long-term facts + compaction summaries), variable values, and function signatures into a single system prompt.
+
+4. **LLM tool-calling loop** — sends prompt to the LLM with built-in tools (`read_var`, `write_var`, `read_attr`, `write_attr`, `call_func`, `done`, `error`, `eval`, `think`, `knowledge`, `remember`). The LLM responds with tool calls, Mana executes them against the live Ruby binding, and sends results back. This loops until `done` is called or no more tool calls are returned.
+
+5. **Return value** — single `write_var` returns the value directly; multiple writes return a Hash. On Ruby 4.0+, a singleton method fallback ensures variables are accessible in the caller's scope.
+
+6. **Background compaction** — if short-term memory exceeds the token pressure threshold, old messages are summarized by the LLM in a background thread and replaced with a compact summary.
 
 
 ## License

data/exe/mana

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "dotenv/load"
+rescue LoadError
+  # dotenv not installed — skip
+end
+
+require "mana"
+
+Mana::Chat.start(TOPLEVEL_BINDING)

data/lib/mana/backends/anthropic.rb

@@ -7,6 +7,8 @@ module Mana
     # Sends requests directly to the Anthropic Messages API (/v1/messages).
     # No format conversion needed — Mana's internal format matches Anthropic's.
     class Anthropic < Base
+      # Non-streaming request. Returns content blocks directly since our internal
+      # format already matches Anthropic's — no normalization needed (unlike OpenAI).
       def chat(system:, messages:, tools:, model:, max_tokens: 4096)
         uri = URI("#{@config.effective_base_url}/v1/messages")
         parsed = http_post(uri, { model:, max_tokens:, system:, tools:, messages: }, {
@@ -15,6 +17,51 @@ module Mana
         })
         parsed[:content] || []
       end
+
+      # Streaming variant — yields {type: :text_delta, text: "..."} events.
+      # Returns the complete content blocks array (same format as chat).
+      def chat_stream(system:, messages:, tools:, model:, max_tokens: 4096, &on_event)
+        uri = URI("#{@config.effective_base_url}/v1/messages")
+        content_blocks = []
+        current_block = nil
+
+        # Anthropic streams SSE events that incrementally build content blocks.
+        # We reassemble them into the same format that chat() returns.
+        http_post_stream(uri, {
+          model:, max_tokens:, system:, tools:, messages:, stream: true
+        }, {
+          "x-api-key" => @config.api_key,
+          "anthropic-version" => "2023-06-01"
+        }) do |event|
+          case event[:type]
+          when "content_block_start"
+            current_block = event[:content_block].dup
+            # Tool input arrives as JSON fragments — accumulate as a string, parse on stop
+            current_block[:input] = +"" if current_block[:type] == "tool_use"
+          when "content_block_delta"
+            delta = event[:delta]
+            if delta[:type] == "text_delta"
+              current_block[:text] = (current_block[:text] || +"") << delta[:text]
+              on_event&.call(type: :text_delta, text: delta[:text])
+            elsif delta[:type] == "input_json_delta"
+              current_block[:input] << delta[:partial_json]
+            end
+          when "content_block_stop"
+            # Parse the accumulated JSON string into a Ruby hash for tool_use blocks
+            if current_block && current_block[:type] == "tool_use"
+              current_block[:input] = begin
+                JSON.parse(current_block[:input], symbolize_names: true)
+              rescue JSON::ParserError
+                {}
+              end
+            end
+            content_blocks << current_block if current_block
+            current_block = nil
+          end
+        end
+
+        content_blocks
+      end
     end
   end
 end

data/lib/mana/backends/base.rb

@@ -60,6 +60,47 @@ module Mana
       rescue Net::OpenTimeout, Net::ReadTimeout => e
         raise LLMError, "Request timed out: #{e.message}"
       end
+
+      # Streaming HTTP POST — yields parsed SSE events as hashes.
+      # Used by chat_stream for real-time output.
+      def http_post_stream(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)
+
+        http.request(req) do |res|
+          raise LLMError, "HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+
+          buffer = +""
+          res.read_body do |chunk|
+            buffer << chunk
+            while (idx = buffer.index("\n\n"))
+              line = buffer.slice!(0, idx + 2).strip
+              next if line.empty?
+
+              # Parse SSE: "event: type\ndata: {...}"
+              data_line = line.split("\n").find { |l| l.start_with?("data: ") }
+              next unless data_line
+
+              json_str = data_line.sub("data: ", "")
+              next if json_str == "[DONE]"
+
+              event = JSON.parse(json_str, symbolize_names: true)
+              yield event if block_given?
+            end
+          end
+        end
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise LLMError, "Request timed out: #{e.message}"
+      rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        raise LLMError, "Connection failed: #{e.message}"
+      end
     end
   end
 end

data/lib/mana/backends/openai.rb

@@ -9,6 +9,8 @@ module Mana
     #   - tool calls: `tool_use`/`tool_result` blocks → `tool_calls` + `role: "tool"`
     #   - response: `choices` → content blocks
     class OpenAI < Base
+      # Translates to OpenAI format, posts, then normalizes back to Anthropic format.
+      # Uses max_completion_tokens (not max_tokens) per OpenAI's newer API convention.
       def chat(system:, messages:, tools:, model:, max_tokens: 4096)
         uri = URI("#{@config.effective_base_url}/v1/chat/completions")
         parsed = http_post(uri, {
@@ -41,6 +43,11 @@ module Mana
         result
       end
 
+      # Handles three cases for user messages:
+      # 1. Plain string — pass through
+      # 2. Array of tool_result blocks — convert to OpenAI's "tool" role messages
+      #    (OpenAI uses separate messages per tool result, not an array in one message)
+      # 3. Array of text blocks — merge into a single string
       def convert_user_message(msg)
         content = msg[:content]
 
@@ -64,6 +71,9 @@ module Mana
         { role: "user", content: content.to_s }
       end
 
+      # Splits Anthropic-style content blocks into OpenAI's separate fields:
+      # text goes into :content, tool_use blocks become :tool_calls with JSON-encoded args.
+      # OpenAI requires tool call arguments as JSON strings, not parsed objects.
       def convert_assistant_message(msg)
         content = msg[:content]
 
@@ -99,6 +109,8 @@ module Mana
         { role: "assistant", content: content.to_s }
       end
 
+      # Anthropic uses input_schema with optional $schema key; OpenAI uses parameters
+      # without it. Strip $schema to avoid OpenAI validation errors.
       def convert_tools(tools)
         tools.map do |tool|
           {
@@ -113,6 +125,8 @@ module Mana
       end
 
       # Convert OpenAI response to Anthropic-style content blocks.
+      # This normalization lets the rest of the engine work with a single format
+      # regardless of which backend was used.
       def normalize_response(parsed)
         choice = parsed.dig(:choices, 0, :message)
         return [] unless choice
@@ -123,6 +137,7 @@ module Mana
           blocks << { type: "text", text: choice[:content] }
         end
 
+        # Parse JSON argument strings back into Ruby hashes for tool_use blocks
         if choice[:tool_calls]
           choice[:tool_calls].each do |tc|
             func = tc[:function]