smart_brain 0.1.1 → 0.2.0

data/lib/smart_brain/event_store/postgres.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'time'
+
+module SmartBrain
+  module EventStore
+    # Postgres-backed EventStore. Drop-in replacement for EventStore::InMemory:
+    # writes the truth layer (sessions/turns/messages/refs) and reproduces the
+    # same return shapes so the runtime and diagnostics are backend-agnostic.
+    class Postgres
+      def initialize(db:, clock:)
+        @db = db
+        @clock = clock
+      end
+
+      def append_turn(session_id:, turn_events:, created_at:, domain_id: 'legacy')
+        db.transaction do
+          ensure_session(session_id, domain_id)
+          seq = next_seq(session_id)
+          turn_id = SecureRandom.uuid
+          messages = normalize_messages(turn_id: turn_id, messages: turn_events[:messages] || [], created_at: created_at)
+          refs = normalize_refs(turn_id: turn_id, refs: turn_events[:refs] || [], created_at: created_at)
+          normalized_events = turn_events.merge(messages: messages, refs: refs)
+
+          db[:turns].insert(
+            id: turn_id,
+            session_id: session_id,
+            seq: seq,
+            created_at: time_from(created_at),
+            events_json: Sequel.pg_jsonb(symbolizable(normalized_events))
+          )
+          insert_messages(turn_id, messages)
+          insert_refs(turn_id, refs)
+
+          {
+            id: turn_id,
+            session_id: session_id,
+            seq: seq,
+            created_at: iso8601(created_at),
+            turn_events: normalized_events
+          }
+        end
+      end
+
+      def turns_count(session_id:)
+        db[:turns].where(session_id: session_id).count
+      end
+
+      def recent_turns(session_id:, limit:)
+        last_turn_ids = db[:turns].where(session_id: session_id).order(Sequel.desc(:seq)).limit(limit).select(:id)
+        db[:messages].where(turn_id: last_turn_ids).order(:created_at).map do |m|
+          {
+            turn_id: m[:turn_id],
+            message_id: m[:id],
+            role: m[:role],
+            content: m[:content],
+            created_at: iso8601(m[:created_at])
+          }
+        end
+      end
+
+      def recent_refs(session_id:, limit:)
+        last_turn_ids = db[:turns].where(session_id: session_id).order(Sequel.desc(:seq)).limit(limit).select(:id)
+        db[:refs].where(turn_id: last_turn_ids).order(:created_at).map do |r|
+          {
+            id: r[:id],
+            turn_id: r[:turn_id],
+            ref_type: r[:ref_type],
+            ref_uri: r[:ref_uri],
+            ref_meta_json: symbolize(r[:ref_meta_json]),
+            created_at: iso8601(r[:created_at])
+          }
+        end
+      end
+
+      def entity_frequencies(session_id:, window_turns:)
+        payloads = db[:turns].where(session_id: session_id)
+                             .order(Sequel.desc(:seq))
+                             .limit(window_turns)
+                             .select(:events_json)
+                             .all
+        freq = Hash.new(0)
+        payloads.each do |row|
+          events = symbolize(row[:events_json])
+          Array(events[:entities]).each do |entity|
+            canonical = entity[:canonical] || entity[:name]
+            freq[canonical.to_s.downcase] += 1
+          end
+        end
+        freq
+      end
+
+      def all_turns(session_id:)
+        dataset = session_id.nil? ? db[:turns] : db[:turns].where(session_id: session_id)
+        dataset.order(:session_id, :seq).map do |t|
+          {
+            id: t[:id],
+            session_id: t[:session_id],
+            seq: t[:seq],
+            created_at: iso8601(t[:created_at]),
+            turn_events: symbolize(t[:events_json])
+          }
+        end
+      end
+
+      private
+
+      attr_reader :db, :clock
+
+      def ensure_session(session_id, domain_id)
+        row = db[:sessions].where(id: session_id).first
+        if row && row[:domain_id] != domain_id
+          raise ArgumentError, "session #{session_id} belongs to domain #{row[:domain_id]}"
+        end
+        return if row
+
+        db[:sessions].insert(id: session_id, domain_id: domain_id, created_at: time_from(clock.call), metadata_json: Sequel.pg_jsonb({}))
+      end
+
+      def next_seq(session_id)
+        (db[:turns].where(session_id: session_id).max(:seq) || 0) + 1
+      end
+
+      def insert_messages(turn_id, messages)
+        messages.each do |m|
+          db[:messages].insert(
+            id: m[:id],
+            turn_id: turn_id,
+            role: m[:role],
+            content: m[:content].to_s,
+            model: m[:model],
+            created_at: time_from(m[:created_at]),
+            meta_json: Sequel.pg_jsonb({})
+          )
+        end
+      end
+
+      def insert_refs(turn_id, refs)
+        refs.each do |r|
+          db[:refs].insert(
+            id: r[:id],
+            turn_id: turn_id,
+            ref_type: r[:ref_type].to_s,
+            ref_uri: r[:ref_uri].to_s,
+            ref_meta_json: Sequel.pg_jsonb(symbolizable(r[:ref_meta_json] || {})),
+            created_at: time_from(r[:created_at])
+          )
+        end
+      end
+
+      def normalize_messages(turn_id:, messages:, created_at:)
+        messages.map do |m|
+          m.merge(
+            id: m[:id] || SecureRandom.uuid,
+            turn_id: turn_id,
+            created_at: m[:created_at] || iso8601(created_at)
+          )
+        end
+      end
+
+      def normalize_refs(turn_id:, refs:, created_at:)
+        refs.map do |r|
+          r.merge(
+            id: r[:id] || SecureRandom.uuid,
+            turn_id: turn_id,
+            created_at: r[:created_at] || iso8601(created_at),
+            ref_meta_json: r[:ref_meta_json] || {}
+          )
+        end
+      end
+
+      def time_from(value)
+        case value
+        when Time then value
+        when String then Time.parse(value)
+        else clock.call
+        end
+      end
+
+      def iso8601(value)
+        time = case value
+               when Time then value
+               when String then Time.parse(value)
+               else clock.call
+               end
+        time.iso8601
+      end
+
+      def symbolizable(obj)
+        SmartBrain::DB.stringify_keys(obj)
+      end
+
+      def symbolize(obj)
+        SmartBrain::DB.symbolize_jsonb(obj)
+      end
+    end
+  end
+end

data/lib/smart_brain/fusion/merger.rb

@@ -3,14 +3,19 @@
 module SmartBrain
   module Fusion
     class Merger
-      def initialize(config:)
+      RERANK_THRESHOLD = 4
+      RERANK_MAX = 20
+
+      def initialize(config:, model_provider: nil)
         @config = config
+        @model_provider = model_provider
       end
 
       def merge(query:, memory_evidence:, resource_evidence:)
         combined = (memory_evidence + normalize_resource(resource_evidence))
         deduped = dedupe(combined)
         ranked = deduped.sort_by { |item| -rerank_score(item, query) }
+        ranked = llm_rerank(query, ranked) if llm_rerank_enabled? && ranked.size >= RERANK_THRESHOLD
         diversified, dropped = apply_diversity(ranked)
         selected = apply_budget(diversified)
 
@@ -23,7 +28,31 @@ module SmartBrain
 
       private
 
-      attr_reader :config
+      attr_reader :config, :model_provider
+
+      def llm_rerank_enabled?
+        return false unless model_provider&.llm?
+        return false unless config.llm.fetch(:rerank_enabled, false)
+
+        true
+      end
+
+      # Re-rank the candidate head with the LLM; preserve lexical order for the
+      # tail and on any error (graceful fallback so compose never breaks).
+      def llm_rerank(query, items)
+        head = items.first(RERANK_MAX)
+        docs = head.map { |i| "#{i[:title]}: #{i[:snippet]}" }
+        scored = model_provider.rerank(query: query, documents: docs)
+        scores_by_index = scored.each_with_object({}) { |s, h| h[s[:index]] = s[:score].to_f }
+
+        reordered = head.each_with_index.map do |item, idx|
+          item.merge(_llm: scores_by_index.fetch(idx, 0.0))
+        end.sort_by { |i| -i[:_llm] }
+        reordered.each { |i| i.delete(:_llm) }
+        reordered + items[RERANK_MAX..]
+      rescue StandardError
+        items
+      end
 
       def normalize_resource(items)
         items.map do |item|

data/lib/smart_brain/governance/briefing.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative 'tiers'
+
+module SmartBrain
+  module Governance
+    # Deterministic, citation-first briefing (mempal parity). No LLM, no DB
+    # writes — assembles purely from memory_store/event_store. Two modes:
+    #   - brief: full cognitive snapshot (summary/key_facts/evidence/entities/
+    #     unresolved/uncertainty/next_actions), every fact carries a citation.
+    #   - wake_up: minimal L0/L1 importance-ordered resume payload.
+    class Briefing
+      KEY_FACT_TYPES = %w[decisions goals patterns].freeze
+
+      def initialize(memory_store:, event_store:, config:)
+        @memory_store = memory_store
+        @event_store = event_store
+        @config = config
+      end
+
+      def brief(session_id:, query: nil, scope_ids: nil, domain_id: 'legacy', scope_context: nil)
+        items = memory_store.active_items(session_id: session_id, scope_ids: scope_ids)
+        recent = event_store.recent_turns(session_id: session_id, limit: briefing_recent_turns)
+        search_query = query || last_user_message(recent) || ''
+
+        {
+          session_id: session_id,
+          domain_id: domain_id,
+          scope_context: scope_context,
+          summary: summary_text(session_id),
+          key_facts: key_facts(items),
+          evidence: evidence(session_id: session_id, scope_ids: scope_ids, query: search_query),
+          entities: memory_store.entities(session_id: session_id, scope_ids: scope_ids),
+          unresolved: unresolved(items),
+          uncertainty: uncertainty(items),
+          next_actions: next_actions(items),
+          generated_at: Time.now.utc.iso8601
+        }
+      end
+
+      def wake_up(session_id:, scope_ids: nil, domain_id: 'legacy', scope_context: nil)
+        items = memory_store.active_items(session_id: session_id, scope_ids: scope_ids)
+        summary = memory_store.latest_summary(session_id: session_id)
+
+        {
+          session_id: session_id,
+          domain_id: domain_id,
+          scope_context: scope_context,
+          l0: {
+            identity: items.select { |i| i[:type] == 'profile' },
+            principles: items.select { |i| i[:tier] == 'dao_tian' },
+            preferences: items.select { |i| i[:type] == 'preferences' }
+          },
+          l1: {
+            goals_decisions: items.select { |i| %w[goals decisions].include?(i[:type]) },
+            summary: summary ? summary[:text] : nil
+          },
+          generated_at: Time.now.utc.iso8601
+        }
+      end
+
+      def resume(query:)
+        matches = event_store.all_turns(session_id: nil)
+                  .map { |t| t[:session_id] }.uniq
+                  .select { |sid| sid.to_s.downcase.include?(query.to_s.downcase) }
+        matches.map do |sid|
+          items = memory_store.active_items(session_id: sid)
+          {
+            session_id: sid,
+            recent_decisions: items.select { |i| i[:type] == 'decisions' }.first(5).map { |i| fact_citation(i) },
+            next_actions: next_actions(items)
+          }
+        end
+      end
+
+      private
+
+      attr_reader :memory_store, :event_store, :config
+
+      def summary_text(session_id)
+        summary = memory_store.latest_summary(session_id: session_id)
+        summary ? summary[:text] : nil
+      end
+
+      def key_facts(items)
+        selected = items.select { |i| KEY_FACT_TYPES.include?(i[:type]) }
+        Tiers.sort_by_tier(selected).first(briefing_key_facts_max).map { |i| fact_citation(i) }
+      end
+
+      def fact_citation(item)
+        {
+          memory_item_id: item[:id],
+          type: item[:type],
+          key: item[:key],
+          tier: item[:tier] || Tiers.tier_for(item[:type]),
+          confidence: item[:confidence],
+          source_turn_id: item[:source_turn_id],
+          status: item[:status],
+          lifecycle_status: item[:lifecycle_status]
+        }
+      end
+
+      def evidence(session_id:, scope_ids:, query:)
+        return [] if query.to_s.strip.empty?
+
+        memory_store.search_memory(query: query, session_id: session_id, scope_ids: scope_ids, limit: briefing_key_facts_max)
+      rescue StandardError
+        []
+      end
+
+      def unresolved(items)
+        items.select { |i| i[:type] == 'tasks' && %w[todo doing blocked].include?(task_status(i)) }
+             .map { |i| fact_citation(i) }
+      end
+
+      def uncertainty(items)
+        items.select { |i| (i[:confidence] || 1.0) < uncertainty_threshold }.map { |i| fact_citation(i) }
+      end
+
+      def next_actions(items)
+        items.select { |i| i[:type] == 'tasks' && %w[todo doing].include?(task_status(i)) }
+             .map { |i| fact_citation(i) }
+      end
+
+      def task_status(item)
+        item.dig(:value_json, :status).to_s
+      end
+
+      def last_user_message(recent)
+        recent.reverse.find { |t| t[:role] == 'user' } && recent.reverse.find { |t| t[:role] == 'user' }[:content]
+      end
+
+      def briefing_key_facts_max
+        config.briefing.fetch(:key_facts_max, 8) rescue 8
+      end
+
+      def uncertainty_threshold
+        config.briefing.fetch(:uncertainty_threshold, 0.6) rescue 0.6
+      end
+
+      def briefing_recent_turns
+        config.briefing.fetch(:recent_turns, 6) rescue 6
+      end
+    end
+  end
+end

data/lib/smart_brain/governance/fact_check.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative '../support/levenshtein'
+
+module SmartBrain
+  module Governance
+    # Offline, zero-LLM, zero-network contradiction detector (mempal parity).
+    # Scans a piece of text against a session's entities + KG edges and reports
+    # three finding types:
+    #   - SimilarNameConflict: a token within Levenshtein <= N of a known entity
+    #   - RelationContradiction: text mentions both endpoints of an active edge
+    #     alongside a negation/contrary cue (may contradict the relation)
+    #   - StaleFact: text references an edge whose valid_to < now (invalidated)
+    #
+    # Heuristic by design — surfaces candidates for human/agent review.
+    class FactCheck
+      TOKEN_RE = /[[:alnum:]_\-\p{Han}]+/.freeze
+
+      def initialize(memory_store:, config:)
+        @memory_store = memory_store
+        @config = config
+      end
+
+      def check(session_id:, text:, now: Time.now.utc, scope_ids: nil)
+        now = Time.parse(now).utc if now.is_a?(String)
+        text_l = text.to_s.downcase
+        tokens = text.to_s.downcase.scan(TOKEN_RE)
+
+        findings = []
+        findings.concat(similar_name_conflicts(session_id:, scope_ids:, tokens: tokens))
+        findings.concat(relation_contradictions(session_id:, scope_ids:, text_l: text_l))
+        findings.concat(stale_facts(session_id:, scope_ids:, text_l: text_l, now: now))
+
+        { findings: findings, checked_at: Time.now.utc.iso8601,
+          counts: { total: findings.size,
+                    similar_name: findings.count { |f| f[:type] == 'SimilarNameConflict' },
+                    relation_contradiction: findings.count { |f| f[:type] == 'RelationContradiction' },
+                    stale_fact: findings.count { |f| f[:type] == 'StaleFact' } } }
+      end
+
+      private
+
+      attr_reader :memory_store, :config
+
+      def similar_name_conflicts(session_id:, scope_ids:, tokens:)
+        distance = config.fact_check.fetch(:similar_name_distance, 2) rescue 2
+        names = memory_store.entities(session_id: session_id, scope_ids: scope_ids).each_with_object([]) do |e, acc|
+          acc << { name: e[:canonical].to_s, entity: e } unless e[:canonical].to_s.empty?
+          acc << { name: e[:name].to_s, entity: e } unless e[:name].to_s.empty?
+        end
+
+        tokens.product(names).each_with_object([]) do |(token, named), acc|
+          next if token.length < 3 || named[:name].length < 3
+          next if token == named[:name]
+
+          d = Support::Levenshtein.distance(token, named[:name])
+          next unless d.between?(1, distance)
+
+          acc << { type: 'SimilarNameConflict', severity: 'warning',
+                   detail: "'#{token}' is within Levenshtein #{d} of entity '#{named[:name]}'",
+                   refs: { token: token, entity: named[:name], entity_id: named[:entity][:id], distance: d } }
+        end
+      end
+
+      def relation_contradictions(session_id:, scope_ids:, text_l:)
+        cues = negation_cues
+        edges = safe_edges(session_id, scope_ids).select { |e| e[:status] == 'active' }
+        return [] if edges.empty? || cues.empty?
+
+        edges.each_with_object([]) do |edge, acc|
+          s, o = edge[:subject].downcase, edge[:object].downcase
+          next unless text_l.include?(s) && text_l.include?(o)
+          next unless cues.any? { |cue| text_l.include?(cue.to_s.downcase) }
+
+          acc << { type: 'RelationContradiction', severity: 'warning',
+                   detail: "text may contradict relation '#{edge[:subject]} #{edge[:predicate]} #{edge[:object]}'",
+                   refs: { edge_id: edge[:id], subject: edge[:subject], predicate: edge[:predicate], object: edge[:object] } }
+        end
+      end
+
+      def stale_facts(session_id:, scope_ids:, text_l:, now:)
+        safe_edges(session_id, scope_ids).select { |e| e[:status] == 'invalidated' && e[:valid_to] }
+          .each_with_object([]) do |edge, acc|
+            valid_to = Time.parse(edge[:valid_to].to_s).utc rescue next
+            next if valid_to >= now
+
+            s, o = edge[:subject].downcase, edge[:object].downcase
+            next unless text_l.include?(s) || text_l.include?(o)
+
+            acc << { type: 'StaleFact', severity: 'info',
+                     detail: "text references invalidated fact '#{edge[:subject]} #{edge[:predicate]} #{edge[:object]}' (valid_to #{edge[:valid_to]})",
+                     refs: { edge_id: edge[:id], subject: edge[:subject], object: edge[:object], valid_to: edge[:valid_to] } }
+          end
+      end
+
+      def safe_edges(session_id, scope_ids)
+        return [] unless memory_store.respond_to?(:query_edges)
+
+        memory_store.query_edges(session_id: session_id, scope_ids: scope_ids, include_invalid: true)
+      rescue StandardError
+        []
+      end
+
+      def negation_cues
+        config.fact_check.fetch(:negation_cues, []) rescue []
+      end
+    end
+  end
+end

data/lib/smart_brain/governance/knowledge_graph.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Governance
+    # Knowledge graph: typed triples (subject-predicate-object) with temporal
+    # validity (valid_from/valid_to) over a MemoryStore. Orthogonal to the
+    # Stage-1 lifecycle and to memory_items — edges live in kg_edges and are
+    # added explicitly (via turn_events[:edges] extraction) or by the agent.
+    class KnowledgeGraph
+      def initialize(memory_store:, config:)
+        @memory_store = memory_store
+        @config = config
+      end
+
+      def add(session_id:, subject:, predicate:, object:, source_turn_id: nil,
+              source_memory_item_id: nil, confidence: nil, valid_from: nil,
+              scope_id: nil, scope: nil, source_session_id: nil)
+        memory_store.add_edge(
+          session_id: session_id,
+          scope_id: scope_id,
+          scope: scope,
+          source_session_id: source_session_id,
+          edge: {
+            subject: subject, predicate: predicate, object: object,
+            source_turn_id: source_turn_id, source_memory_item_id: source_memory_item_id,
+            confidence: confidence || default_confidence, valid_from: valid_from
+          }
+        )
+      end
+
+      def query(session_id: nil, scope_ids: nil, subject: nil, predicate: nil, object: nil, include_invalid: false)
+        memory_store.query_edges(session_id: session_id, scope_ids: scope_ids, subject: subject,
+                                 predicate: predicate, object: object,
+                                 include_invalid: include_invalid)
+      end
+
+      def timeline(session_id: nil, scope_ids: nil, subject:)
+        memory_store.edges_for_subject(session_id: session_id, scope_ids: scope_ids, subject: subject)
+      end
+
+      def invalidate(edge_id:, reason: nil)
+        memory_store.invalidate_edge(id: edge_id, reason: reason)
+      end
+
+      def stats(session_id: nil, scope_ids: nil)
+        memory_store.edge_stats(session_id: session_id, scope_ids: scope_ids)
+      end
+
+      private
+
+      attr_reader :memory_store, :config
+
+      def default_confidence
+        config.kg.fetch(:default_confidence, 0.6)
+      rescue StandardError
+        0.6
+      end
+    end
+  end
+end