ruby-mana 0.5.12 → 0.5.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f9221479991a9a07659b6d8aee20d2e0e377f6159e3116fbf01839219d8d011
-  data.tar.gz: dc2caf733e6a7f4e330599edff45c72557b81205c7b29382237dfa9b286c903b
+  metadata.gz: f01dc9677f8c7a7813e0d8df7ec44f0a8fe44c54342d1181f64edd9f34e452a2
+  data.tar.gz: 0da4c67c41015a2ce4bb6727a0aeeb2a0334a8f85da9a38f97e122cb294a3169
 SHA512:
-  metadata.gz: 3389dabca2ba36ab0e3cf2e5ae2f780f9507eadce0f7551c3ebcf22792003342364cf45dc01bd0315713b8998a2c4be0ec5aede5d13eca2adf493339be6bd038
-  data.tar.gz: 876a82b19006c6b12822ffaf264d89ac5d81c0e56871d595d7027a72f94c0aa57ec11251ab7458b76338b80fb6f756a700828064d266aaf8084298cc84e77ab5
+  metadata.gz: 36207a5776806db60df0ce71e4f2d53ad1c48af6bdf43aeb7782035639038457a088fa508cc25afe197cbcaf0f02490503912bbabbda4229131f6e36f8befa9e
+  data.tar.gz: 4055b0f53f20a702e120c23801fd628ddc49643f5ad08b21aa8c02647661bd0516187af8e0a8887e90cf6bd5623efb31435ef5da3143d28f680125fcd6acb97a

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.5.13] - 2026-04-05
+
+### Changed
+- Backends (`Anthropic`, `OpenAI`) now return `{ content: [...], usage: { input_tokens:, output_tokens: } }` instead of a plain content array
+- Anthropic streaming (`chat_stream`) captures usage from `message_start` and `message_delta` events
+- OpenAI backend normalizes `prompt_tokens`/`completion_tokens` to `input_tokens`/`output_tokens`
+
+### Added
+- `Engine#trace_data` — after execution, exposes `{ prompt:, model:, steps:, total_iterations:, timestamp: }` with per-step usage, latency, and tool call details
+- LLM call latency measurement via `Process.clock_gettime` in `Engine#llm_call`
+
 ## [0.5.12] - 2026-04-04
 
 ### Changed

data/README.md

@@ -144,7 +144,7 @@ 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).
+Generated files live in `.ruby-mana/cache/` (add to `.gitignore`, or commit them to skip LLM on CI).
 
 ## Advanced
 
@@ -228,7 +228,7 @@ Mana.configure do |c|
   c.namespace = "my-project"      # nil = auto-detect from git/pwd
   c.context_window = 128_000      # default: 128_000
   c.memory_store = Mana::FileStore.new  # default file-based persistence
-  c.memory_path = ".mana"         # directory for memory files
+  c.memory_path = ".ruby-mana"    # directory for memory files
   c.context_class = nil           # custom context class (e.g. from agent frameworks)
   c.knowledge_provider = nil      # custom knowledge provider
 end
@@ -291,6 +291,31 @@ end
 
 Unmatched prompts raise `Mana::MockError` with a helpful message suggesting the stub to add.
 
+### Execution tracing
+
+After each `execute` call, the engine exposes timing and token usage data:
+
+```ruby
+engine = Mana::Engine.new(binding)
+result = engine.execute("compute <x>")
+
+trace = engine.trace_data
+# => {
+#   prompt: "compute <x>",
+#   model: "claude-sonnet-4-20250514",
+#   timestamp: "2026-04-05T10:30:00+08:00",
+#   total_iterations: 2,
+#   steps: [
+#     { iteration: 1, latency_ms: 800,
+#       usage: { input_tokens: 500, output_tokens: 200 },
+#       tool_calls: [{ name: "read_var", input: {...}, result: "..." }] },
+#     ...
+#   ]
+# }
+```
+
+Backends return usage alongside content: `backend.chat(...)` returns `{ content: [...], usage: { input_tokens:, output_tokens: } }`.
+
 ## How it works
 
 ```
@@ -320,7 +345,7 @@ Unmatched prompts raise `Mana::MockError` with a helpful message suggesting the
 
 3. **Build system prompt** — assembles rules, 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`). 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.
+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`, `knowledge`). 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.
 

data/lib/mana/backends/anthropic.rb

@@ -15,7 +15,10 @@ module Mana
           "x-api-key" => @config.api_key,
           "anthropic-version" => "2023-06-01"
         })
-        parsed[:content] || []
+        {
+          content: parsed[:content] || [],
+          usage: parsed[:usage]
+        }
       end
 
       # Streaming variant — yields {type: :text_delta, text: "..."} events.
@@ -24,6 +27,7 @@ module Mana
         uri = URI("#{@config.effective_base_url}/v1/messages")
         content_blocks = []
         current_block = nil
+        usage = {}
 
         # Anthropic streams SSE events that incrementally build content blocks.
         # We reassemble them into the same format that chat() returns.
@@ -34,6 +38,10 @@ module Mana
           "anthropic-version" => "2023-06-01"
         }) do |event|
           case event[:type]
+          when "message_start"
+            usage[:input_tokens] = event.dig(:message, :usage, :input_tokens)
+          when "message_delta"
+            usage[:output_tokens] = event.dig(:usage, :output_tokens)
           when "content_block_start"
             current_block = event[:content_block].dup
             # Tool input arrives as JSON fragments — accumulate as a string, parse on stop
@@ -60,7 +68,10 @@ module Mana
           end
         end
 
-        content_blocks
+        {
+          content: content_blocks,
+          usage: usage.empty? ? nil : usage
+        }
       end
     end
   end

data/lib/mana/backends/openai.rb

@@ -21,7 +21,10 @@ module Mana
         }, {
           "Authorization" => "Bearer #{@config.api_key}"
         })
-        normalize_response(parsed)
+        {
+          content: normalize_response(parsed),
+          usage: normalize_usage(parsed[:usage])
+        }
       end
 
       private
@@ -124,6 +127,15 @@ module Mana
         end
       end
 
+      # Convert OpenAI usage fields to our standard format.
+      def normalize_usage(usage)
+        return nil unless usage
+        {
+          input_tokens: usage[:prompt_tokens],
+          output_tokens: usage[:completion_tokens]
+        }
+      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.

data/lib/mana/compiler.rb

@@ -25,7 +25,7 @@ module Mana
 
       # Cache directory for generated .rb files
       def cache_dir
-        @cache_dir || ".mana_cache"
+        @cache_dir || File.join(".ruby-mana", "cache")
       end
 
       attr_writer :cache_dir

data/lib/mana/engine.rb

@@ -6,7 +6,7 @@ module Mana
   # The Engine handles ~"..." prompts by calling an LLM with tool-calling
   # to interact with Ruby variables in the caller's binding.
   class Engine
-    attr_reader :config, :binding
+    attr_reader :config, :binding, :trace_data
 
     include Mana::BindingHelpers
     include Mana::PromptBuilder
@@ -187,6 +187,7 @@ module Mana
       iterations = 0
       done_result = nil
       @written_vars = {}  # Track write_var calls for return value
+      @_steps = []        # Trace data: per-iteration usage + timing + tool calls
 
       vlog("═" * 60)
       vlog("🚀 Prompt: #{prompt}")
@@ -241,6 +242,13 @@ module Mana
           { type: "tool_result", tool_use_id: tu[:id], content: result.to_s }
         end
 
+        # Record tool calls in trace step
+        if @_steps.last
+          @_steps.last[:tool_calls] = tool_uses.zip(tool_results).map { |tu, tr|
+            { name: tu[:name], input: tu[:input], result: tr[:content] }
+          }
+        end
+
         # Send tool results back to the LLM as a user message
         messages << { role: "user", content: tool_results }
         # Exit loop when the LLM signals completion via the "done" tool
@@ -252,6 +260,15 @@ module Mana
         messages << { role: "assistant", content: [{ type: "text", text: "Done: #{done_result}" }] }
       end
 
+      # Build trace data for external consumers (e.g. Claw::Trace)
+      @trace_data = {
+        prompt: prompt,
+        model: @config.model,
+        steps: @_steps,
+        total_iterations: iterations,
+        timestamp: Time.now.iso8601
+      }
+
       # Return written variables so Ruby 4.0+ users can capture them:
       #   result = ~"compute average and store in <result>"
       # Single write -> return the value directly; multiple -> return Hash.
@@ -326,7 +343,9 @@ module Mana
       vlog("🔄 LLM call ##{@_iteration} → #{@config.model}")
       backend = Backends::Base.for(@config)
 
-      result = if on_text && backend.respond_to?(:chat_stream)
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      raw = if on_text && backend.respond_to?(:chat_stream)
         backend.chat_stream(
           system: system,
           messages: messages,
@@ -346,6 +365,15 @@ module Mana
         )
       end
 
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
+
+      # Backends return { content: [...], usage: {...} }
+      result = raw[:content]
+      usage = raw[:usage]
+
+      # Record step for trace
+      @_steps << { iteration: @_iteration, usage: usage, latency_ms: latency_ms }
+
       result.each do |block|
         type = block[:type] || block["type"]
         case type

data/lib/mana/knowledge.rb

@@ -179,7 +179,7 @@ module Mana
           - Methods on the receiver (minus Ruby builtins) are also discovered.
           - No registration or JSON schema needed — just define normal Ruby methods.
           - LLM-compiled methods: `mana def method_name` lets the LLM generate the implementation
-            on first call, then caches it on disk (.mana_cache/).
+            on first call, then caches it on disk (.ruby-mana/cache/).
         TEXT
       end
     end

data/lib/mana/logger.rb

@@ -66,16 +66,6 @@ module Mana
       end
     end
 
-    # Log think tool content — full text in distinct italic cyan
-    def vlog_think(content)
-      return unless @config.verbose
-
-      $stderr.puts "\e[2m[mana]\e[0m \e[3;36m💭 Think:\e[0m"
-      content.each_line do |line|
-        $stderr.puts "\e[2m[mana]\e[0m \e[3;36m  #{line.rstrip}\e[0m"
-      end
-    end
-
     # Summarize tool input for compact logging.
     # Multi-line string values are replaced with a brief summary.
     def summarize_input(input)

data/lib/mana/memory_store.rb

@@ -25,7 +25,7 @@ module Mana
 
 
   # Default file-based memory store. Persists memories as JSON files.
-  # Storage path resolution: explicit base_path > config.memory_path > {cwd}/.mana
+  # Storage path resolution: explicit base_path > config.memory_path > {cwd}/.ruby-mana
   class FileStore < MemoryStore
     # Optional base_path overrides default storage location
     def initialize(base_path = nil)
@@ -65,15 +65,15 @@ module Mana
     end
 
     # Resolve the base directory for memory storage.
-    # Priority: explicit base_path > config.memory_path > {cwd}/.mana
+    # Priority: explicit base_path > config.memory_path > {cwd}/.ruby-mana
     def base_dir
       return File.join(@base_path, "memory") if @base_path
 
       custom_path = Mana.config.memory_path
       return File.join(custom_path, "memory") if custom_path
 
-      # Default fallback — project-local .mana directory
-      File.join(Dir.pwd, ".mana")
+      # Default fallback — project-local .ruby-mana directory
+      File.join(Dir.pwd, ".ruby-mana")
     end
   end
 end

data/lib/mana/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.5.12
+  version: 0.5.13
 platform: ruby
 authors:
 - Carl Li
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-05 00:00:00.000000000 Z
+date: 2026-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller