llmemory 0.2.11 → 0.3.0

data/lib/llmemory/vector_store/openai_embeddings.rb

@@ -14,37 +14,59 @@ module Llmemory
       DEFAULT_MODEL = "text-embedding-3-small"
       DEFAULT_DIMS = 1536
 
-      attr_reader :last_usage
+      attr_reader :last_usage, :model
 
-      def initialize(api_key: nil, model: nil, base_url: nil)
+      def initialize(api_key: nil, model: nil, base_url: nil, dimensions: nil)
         @api_key = api_key || Llmemory.configuration.llm_api_key
         @model = model || DEFAULT_MODEL
+        @dimensions = dimensions || DEFAULT_DIMS
         @base_url = base_url || Llmemory.configuration.llm_base_url || "https://api.openai.com/v1"
         @cache = {}
         @cache_order = []
         @last_usage = Llmemory::LLM::Usage.zero
       end
 
+      def dimensions
+        @dimensions
+      end
+
+      def local?
+        false
+      end
+
       def embed(text)
-        return Array.new(DEFAULT_DIMS, 0.0) if text.to_s.strip.empty?
+        embed_batch([text]).first
+      end
 
-        if Llmemory.configuration.embedding_cache_enabled
-          key = cache_key(text)
-          if @cache.key?(key)
+      def embed_batch(texts)
+        list = Array(texts).map(&:to_s)
+        return [] if list.empty?
+
+        results = list.map do |text|
+          if text.strip.empty?
+            Array.new(dimensions, 0.0)
+          elsif Llmemory.configuration.embedding_cache_enabled && @cache.key?(cache_key(text))
             @last_usage = Llmemory::LLM::Usage.zero
-            return @cache[key].dup
+            @cache[cache_key(text)].dup
+          else
+            :miss
           end
         end
 
-        result = fetch_embedding(text)
-
-        if Llmemory.configuration.embedding_cache_enabled
-          evict_if_needed
-          @cache[cache_key(text)] = result.dup
-          @cache_order << cache_key(text)
+        miss_indices = results.each_index.select { |i| results[i] == :miss }
+        if miss_indices.any?
+          fetched = fetch_embeddings(miss_indices.map { |i| list[i] })
+          miss_indices.each_with_index do |idx, j|
+            vec = fetched[j]
+            results[idx] = vec
+            if Llmemory.configuration.embedding_cache_enabled
+              evict_if_needed
+              @cache[cache_key(list[idx])] = vec.dup
+              @cache_order << cache_key(list[idx])
+            end
+          end
         end
-
-        result
+        results
       end
 
       private
@@ -63,14 +85,16 @@ module Llmemory
         end
       end
 
-      def fetch_embedding(text)
-        result = nil
-        payload = { provider: :openai, model: @model, text_chars: text.to_s.length }
+      def fetch_embeddings(texts)
+        payload = { provider: :openai, model: @model, text_chars: texts.sum(&:length) }
+        vectors = nil
         Llmemory::Instrumentation.instrument(:llm_embed, payload) do
+          body_input = { input: texts.map { |t| t.to_s.strip }, model: @model }
+          body_input[:dimensions] = @dimensions if @dimensions != DEFAULT_DIMS
           response = post_with_resilience(connection, "embeddings") do |req|
             req.headers["Authorization"] = "Bearer #{@api_key}"
             req.headers["Content-Type"] = "application/json"
-            req.body = { input: text.to_s.strip, model: @model }.to_json
+            req.body = body_input.to_json
           end
           raise Llmemory::LLMError, "OpenAI Embeddings API error: #{response.body}" unless response.success?
           body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
@@ -80,9 +104,11 @@ module Llmemory
             output_tokens: @last_usage.output_tokens,
             total_tokens: @last_usage.total_tokens
           )
-          result = body.dig("data", 0, "embedding")&.map(&:to_f) || Array.new(DEFAULT_DIMS, 0.0)
+          vectors = Array(body["data"]).sort_by { |row| row["index"] }.map do |row|
+            row["embedding"]&.map(&:to_f) || Array.new(dimensions, 0.0)
+          end
         end
-        result
+        vectors
       end
 
       def parse_embed_usage(raw)

data/lib/llmemory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Llmemory
-  VERSION = "0.2.11"
+  VERSION = "0.3.0"
 end

data/lib/llmemory/zero_mem/answer_calibrator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class AnswerCalibrator
+      def calibrate(answer, evidence_result:)
+        answer = answer.to_s
+        evidence = Array(evidence_result&.evidence)
+        checks = []
+        unsupported = []
+
+        if list_like?(answer)
+          checks << "list_answer"
+          return unchanged(answer, checks, unsupported)
+        end
+
+        scalar = extract_scalar_candidate(answer)
+        if scalar
+          matches = evidence.select { |ev| ev.content.to_s.include?(scalar) }
+          checks << "scalar_support"
+          if matches.size == 1
+            return {
+              answer: scalar,
+              changed: answer.strip != scalar,
+              checks: checks,
+              unsupported_fragments: unsupported
+            }
+          end
+
+          checks << "ambiguous_scalar"
+          return unchanged(answer, checks, unsupported)
+        end
+
+        checks << "free_text"
+        unchanged(answer, checks, unsupported)
+      end
+
+      private
+
+      def unchanged(answer, checks, unsupported)
+        {
+          answer: answer,
+          changed: false,
+          checks: checks,
+          unsupported_fragments: unsupported
+        }
+      end
+
+      def extract_scalar_candidate(answer)
+        stripped = answer.strip
+        return stripped if stripped.match?(/\A[\d.]+\z/)
+        return stripped if stripped.length <= 32 && stripped !~ /\s/
+
+        m = stripped.match(/\b([A-Z]{1,3})\b/)
+        m&.[](1)
+      end
+
+      def list_like?(answer)
+        answer.include?(",") || answer.match?(/\b(and|y)\b/i)
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/backfill.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Llmemory
+  module ZeroMem
+    class Backfill
+      WARNING = "Backfill only covers messages still present in the checkpoint; " \
+                "text removed by prior LLM compaction cannot be reconstructed."
+
+      def initialize(storage:, indexer: nil)
+        @storage = storage
+        @indexer = indexer || Indexer.new(storage)
+      end
+
+      def run!(user_id:, session_id:, messages:, id_prefix: "backfill")
+        created = []
+        Array(messages).each_with_index do |msg, idx|
+          role = msg[:role] || msg["role"]
+          content = msg[:content] || msg["content"]
+          next if content.to_s.empty?
+
+          sequence = @storage.next_sequence(user_id, session_id)
+          trace = Trace.build(
+            user_id: user_id,
+            session_id: session_id,
+            role: role,
+            content: content,
+            sequence: sequence,
+            idempotency_key: "#{id_prefix}-#{idx}-#{Digest::SHA256.hexdigest(content.to_s)[0, 12]}"
+          )
+          next if @storage.find_by_idempotency_key(user_id, trace.idempotency_key)
+
+          @storage.write_trace(trace)
+          @indexer.after_trace_write(trace: trace)
+          created << trace.id
+        end
+
+        { created_trace_ids: created, warning: WARNING }
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/budget_assembler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class BudgetAssembler
+      RESERVE_TOKENS = 64
+
+      def assemble(evidence, max_tokens:, local_reserve: RESERVE_TOKENS, atomic_groups: nil)
+        budget = max_tokens&.to_i
+        return evidence if budget.nil? || budget <= 0
+
+        reserve = [local_reserve, budget / 4].min
+        remaining = budget - reserve
+        selected = []
+        used_ids = {}
+
+        groups = build_atomic_groups(evidence, atomic_groups)
+        ungrouped = evidence.reject { |ev| groups.any? { |g| g.include?(ev.trace_id) } }
+
+        groups.each do |group|
+          members = group.map { |id| evidence.find { |ev| ev.trace_id == id } }.compact
+          cost = members.sum { |ev| token_cost(ev) }
+          next if cost > remaining
+
+          members.each do |ev|
+            selected << ev
+            used_ids[ev.trace_id] = true
+          end
+          remaining -= cost
+        end
+
+        ungrouped.each do |ev|
+          next if used_ids[ev.trace_id]
+
+          cost = token_cost(ev)
+          next if cost > remaining && !selected.empty?
+
+          if cost <= remaining
+            selected << ev
+            remaining -= cost
+          end
+        end
+
+        selected
+      end
+
+      def build_atomic_groups(evidence, explicit_groups)
+        ids = evidence.map(&:trace_id)
+        Array(explicit_groups).map do |group|
+          Array(group).map(&:to_s).select { |id| ids.include?(id) }
+        end.reject(&:empty?)
+      end
+
+      private
+
+      def token_cost(evidence)
+        line = "[#{evidence.trace_id}] #{evidence.role}: #{evidence.content}"
+        (Llmemory::Tokenizer.tokenize(line).size + 4)
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/circuit_breaker.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    class CircuitBreaker
+      def initialize(failure_threshold: 3, cool_down_seconds: 30)
+        @failure_threshold = failure_threshold.to_i
+        @cool_down_seconds = cool_down_seconds.to_i
+        @failures = 0
+        @opened_at = nil
+      end
+
+      def allow_request?
+        return true if @opened_at.nil?
+        return false if (Time.now - @opened_at) < @cool_down_seconds
+
+        @opened_at = nil
+        @failures = 0
+        true
+      end
+
+      def record_success
+        @failures = 0
+        @opened_at = nil
+      end
+
+      def record_failure
+        @failures += 1
+        @opened_at = Time.now if @failures >= @failure_threshold
+      end
+
+      def open?
+        !allow_request?
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/embedding_provider.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module ZeroMem
+    module EmbeddingProvider
+      def embed(texts)
+        raise NotImplementedError
+      end
+
+      def model
+        raise NotImplementedError
+      end
+
+      def dimensions
+        raise NotImplementedError
+      end
+
+      def local?
+        false
+      end
+
+      def last_usage
+        Llmemory::LLM::Usage.zero
+      end
+
+      def embed_one(text)
+        embed([text]).first
+      end
+    end
+
+    # Deterministic vectors for tests (no HTTP).
+    class FakeEmbeddingProvider
+      include EmbeddingProvider
+
+      attr_reader :calls
+
+      def initialize(dimensions: 8, model: "fake-embed")
+        @dimensions = dimensions
+        @model = model
+        @calls = 0
+      end
+
+      def embed(texts)
+        @calls += 1
+        Array(texts).map { |text| vector_for(text) }
+      end
+
+      def model
+        @model
+      end
+
+      def dimensions
+        @dimensions
+      end
+
+      def local?
+        true
+      end
+
+      private
+
+      def vector_for(text)
+        seed = Digest::SHA256.hexdigest(text.to_s)
+        @dimensions.times.map do |i|
+          byte = seed.bytes[i % seed.bytes.length] || 0
+          (byte / 255.0)
+        end
+      end
+    end
+  end
+end
+
+require "digest"

data/lib/llmemory/zero_mem/engine.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require_relative "../retrieval/bm25_scorer"
+
+module Llmemory
+  module ZeroMem
+    class Engine
+      def initialize(trace_store:, user_id:, config: nil, profiler: nil, retriever: nil,
+                     graph_retriever: nil, calibrator: nil, assembler: nil, entity_index: nil,
+                     embedding_provider: nil, router: nil, fusion: nil, closure: nil, **options)
+        if options.key?(:llm) || options.key?("llm")
+          raise ArgumentError, "ZeroMem::Engine does not accept an llm client"
+        end
+
+        @storage = trace_store
+        @user_id = user_id
+        @config = config || Llmemory.configuration
+        @profiler = profiler || QueryProfiler.new
+        @retriever = retriever || HierarchyRetriever.new(@storage, config: @config)
+        @entity_index = entity_index || EntityIndex.new(@storage)
+        @embedding_provider = embedding_provider
+        @graph_retriever = graph_retriever || GraphRetriever.new(
+          @storage,
+          entity_index: @entity_index,
+          embedding_provider: @embedding_provider,
+          config: @config
+        )
+        @calibrator = calibrator || EvidenceCalibrator.new(@storage)
+        @assembler = assembler || BudgetAssembler.new
+        @router = router || Router.new
+        @fusion = fusion || EvidenceFusion.new
+        @closure = closure || EvidenceClosure.new(@storage, config: @config)
+        @bm25 = Retrieval::Bm25Scorer.new
+      end
+
+      def retrieve_evidence(query, top_k: nil, max_tokens: nil, boundary: nil, explain: false,
+                            current_trace_id: nil, skip_closure: false, skip_calibration: false,
+                            fusion_weights: nil)
+        effective_k = effective_top_k(top_k, nil)
+        metrics = { llm_calls: 0, encoder_calls: 0, encoder_duration_ms: 0.0, stages: {} }
+
+        profile = nil
+        Llmemory::Instrumentation.instrument(:zero_mem_profile, user_id: @user_id, query_chars: query.to_s.length) do
+          profile = @profiler.profile(query, boundary: boundary)
+        end
+        effective_k = effective_top_k(top_k, profile)
+
+        retrieval = nil
+        Llmemory::Instrumentation.instrument(:zero_mem_hierarchy_retrieve, user_id: @user_id, workload: profile.workload_class) do
+          retrieval = @retriever.retrieve(user_id: @user_id, query: query, profile: profile, top_k: effective_k)
+        end
+
+        graph = nil
+        Llmemory::Instrumentation.instrument(:zero_mem_graph_retrieve, user_id: @user_id) do
+          graph = @graph_retriever.retrieve(user_id: @user_id, query: query, profile: profile, top_k: effective_k)
+        end
+
+        degraded = (retrieval[:degraded] + graph[:degraded]).uniq
+        degraded << :dense unless @embedding_provider
+        degraded.uniq!
+
+        hierarchy_scores = hierarchy_trace_scores(query, retrieval[:traces])
+        graph_scores = graph[:trace_scores] || {}
+        routing = @router.route(profile, hierarchy_scores: hierarchy_scores, graph_scores: graph_scores, config: @config)
+        weights = fusion_weights || routing[:weights]
+
+        fused = @fusion.fuse(graph_scores: graph_scores, hierarchy_scores: hierarchy_scores, weights: weights)
+        seed_rows = fused.first(effective_k)
+        seed_ids = seed_rows.map { |r| r[:trace_id] }
+
+        closure_result = if skip_closure
+                           { seed_trace_ids: seed_ids, closure_trace_ids: [], bridges: [], atomic_groups: [] }
+                         else
+                           Llmemory::Instrumentation.instrument(:zero_mem_closure, user_id: @user_id, seeds: seed_ids.size) do
+                             @closure.expand(
+                               user_id: @user_id,
+                               profile: profile,
+                               seed_trace_ids: seed_ids,
+                               fused_ranking: fused
+                             )
+                           end
+                         end
+
+        ordered_ids = (seed_ids + closure_result[:closure_trace_ids]).uniq
+        traces = ordered_ids.map { |id| @storage.get_trace(@user_id, id) }.compact
+
+        calibration = if skip_calibration
+                        { traces: traces, excluded: [], conflict_trace_ids: [], seed_ids: seed_ids,
+                          closure_ids: closure_result[:closure_trace_ids] }
+                      else
+                        Llmemory::Instrumentation.instrument(:zero_mem_calibrate, user_id: @user_id, trace_count: traces.size) do
+                          @calibrator.calibrate(
+                            user_id: @user_id,
+                            traces: traces,
+                            profile: profile,
+                            current_trace_id: current_trace_id,
+                            fusion_rows: fused,
+                            seed_ids: seed_ids,
+                            closure_ids: closure_result[:closure_trace_ids]
+                          )
+                        end
+                      end
+
+        fusion_by_id = fused.each_with_object({}) { |row, acc| acc[row[:trace_id].to_s] = row }
+        conflict_ids = calibration[:conflict_trace_ids].to_h { |id| [id.to_s, true] }
+
+        evidence = calibration[:traces].map do |trace|
+          row = fusion_by_id[trace.id]
+          score = row ? row[:final] : 0.5
+          Evidence.new(
+            trace_id: trace.id,
+            content: trace.content,
+            role: trace.role,
+            session_id: trace.session_id,
+            occurred_at: trace.occurred_at,
+            confidence: score.clamp(0.0, 1.0),
+            score: score.clamp(0.0, 1.0),
+            sources: row ? row[:sources] : [],
+            conflict: conflict_ids[trace.id] == true,
+            seed: seed_ids.include?(trace.id),
+            closure: closure_result[:closure_trace_ids].include?(trace.id),
+            content_sha256: trace.content_sha256
+          )
+        end
+
+        seed_evidence = evidence.select(&:seed)
+        closure_evidence = evidence.select(&:closure)
+
+        packed = @assembler.assemble(
+          evidence,
+          max_tokens: max_tokens,
+          atomic_groups: closure_result[:atomic_groups]
+        )
+
+        explain_payload = if explain
+                              build_explain(
+                                profile: profile,
+                                routing: routing,
+                                weights: weights,
+                                effective_k: effective_k,
+                                graph: graph,
+                                retrieval: retrieval,
+                                fused: fused,
+                                calibration: calibration,
+                                closure_result: closure_result,
+                                degraded: degraded,
+                                warnings: graph[:warnings]
+                              )
+                            end
+
+        result = EvidenceSet.new(
+          route: routing[:route],
+          profile: profile,
+          evidence: packed,
+          seed_evidence: seed_evidence.select { |ev| packed.any? { |p| p.trace_id == ev.trace_id } },
+          closure_evidence: closure_evidence.select { |ev| packed.any? { |p| p.trace_id == ev.trace_id } },
+          metrics: metrics.merge(
+            degraded: degraded,
+            seed_recall: seed_evidence.map(&:trace_id),
+            closure_recall: (seed_evidence + closure_evidence).map(&:trace_id).uniq
+          ),
+          explain: explain_payload,
+          degraded: degraded,
+          relational_trace_scores: graph_scores,
+          hierarchy_traces: retrieval[:traces],
+          relational_traces: graph[:traces],
+          warnings: graph[:warnings]
+        )
+
+        Llmemory::Instrumentation.instrument(
+          :zero_mem_retrieve,
+          user_id: @user_id,
+          evidence_count: packed.size,
+          degraded: degraded,
+          seed_count: seed_evidence.size,
+          closure_count: closure_evidence.size
+        )
+
+        result
+      end
+
+      def to_context(query, **opts)
+        retrieve_evidence(query, **opts).to_context
+      end
+
+      private
+
+      def effective_top_k(explicit, profile)
+        base = explicit || @config.zero_mem_top_k
+        need = profile ? [base, profile.expected_evidence_count].max : base
+        [need, @config.zero_mem_max_top_k].min
+      end
+
+      def hierarchy_trace_scores(query, traces)
+        docs = traces.map { |t| { id: t.id, text: t.content } }
+        return {} if docs.empty?
+
+        @bm25.score_documents(query, docs).to_h { |d| [d[:id], d[:normalized_bm25].to_f] }
+      end
+
+      def build_explain(profile:, routing:, weights:, effective_k:, graph:, retrieval:, fused:,
+                        calibration:, closure_result:, degraded:, warnings:)
+        {
+          profile: profile.to_h,
+          route: routing[:route],
+          weights: weights,
+          thresholds: {
+            rho: routing[:rho],
+            gamma: @config.zero_mem_pagerank_damping,
+            top_k: effective_k
+          },
+          graph: {
+            seeds: graph[:trace_scores]&.keys&.first(5),
+            nodes_visited: graph[:traces]&.size,
+            truncated: warnings.include?(:pagerank_truncated),
+            boosts: []
+          },
+          hierarchy: {
+            episodes: retrieval[:stage_scores][:episodes],
+            windows: retrieval[:stage_scores][:windows],
+            turns: retrieval[:stage_scores][:turns]
+          },
+          fusion: {
+            per_trace: fused.first(effective_k).map do |row|
+              {
+                id: row[:trace_id],
+                graph: row[:graph],
+                hierarchy: row[:hierarchy],
+                final: row[:final],
+                sources: row[:sources]
+              }
+            end
+          },
+          included: calibration[:traces].map(&:id),
+          excluded: calibration[:excluded],
+          closure: {
+            seed_ids: closure_result[:seed_trace_ids],
+            closure_ids: closure_result[:closure_trace_ids],
+            bridges: closure_result[:bridges]
+          },
+          warnings: warnings,
+          degraded: degraded
+        }
+      end
+    end
+  end
+end

data/lib/llmemory/zero_mem/entity.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Llmemory
+  module ZeroMem
+    class Entity
+      attr_reader :id, :user_id, :normalized_key, :display_name, :entity_type, :ambiguous
+
+      def self.build(user_id:, normalized_key:, display_name: nil, entity_type: :entity, id: nil, ambiguous: false)
+        new(
+          id: id || "ent_#{Digest::SHA256.hexdigest([user_id, normalized_key].join(':'))[0, 16]}",
+          user_id: user_id.to_s,
+          normalized_key: normalized_key.to_s,
+          display_name: display_name || normalized_key.to_s,
+          entity_type: entity_type.to_sym,
+          ambiguous: ambiguous
+        )
+      end
+
+      def initialize(id:, user_id:, normalized_key:, display_name:, entity_type:, ambiguous:)
+        @id = id
+        @user_id = user_id
+        @normalized_key = normalized_key
+        @display_name = display_name
+        @entity_type = entity_type
+        @ambiguous = ambiguous
+      end
+    end
+  end
+end