smart_brain 0.1.2 → 0.2.0

data/lib/smart_brain/contracts/scope_context.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative 'scope_ref'
+
+module SmartBrain
+  module Contracts
+    class ScopeContext
+      LEGACY_DOMAIN_ID = 'legacy'
+
+      def self.normalize(domain_id:, session_id:, scope_context:, allowed_types: ScopeRef::DEFAULT_ALLOWED_TYPES)
+        normalized_domain = domain_id.to_s.strip
+        if normalized_domain.empty? && scope_context
+          raise ArgumentError, 'domain_id is required when scope_context is provided'
+        end
+        normalized_domain = LEGACY_DOMAIN_ID if normalized_domain.empty?
+        raise ArgumentError, 'session_id is required' if session_id.to_s.strip.empty?
+
+        raw = scope_context || legacy_context(session_id)
+        read = Array(raw[:read] || raw['read']).map { |ref| ScopeRef.normalize(ref, allowed_types: allowed_types) }
+        raise ArgumentError, 'scope_context.read must not be empty' if read.empty?
+
+        keys = read.map { |ref| "#{ref[:type]}:#{ref[:id]}" }
+        duplicates = keys.tally.select { |_key, count| count > 1 }.keys
+        raise ArgumentError, "duplicate scope refs: #{duplicates.join(', ')}" unless duplicates.empty?
+
+        default_write = ScopeRef.normalize(raw[:default_write] || raw['default_write'], allowed_types: allowed_types)
+        write_raw = raw.key?(:write) ? raw[:write] : raw['write']
+        write = Array(write_raw || [default_write]).map { |ref| ScopeRef.normalize(ref, allowed_types: allowed_types) }
+        write_keys = write.map { |ref| "#{ref[:type]}:#{ref[:id]}" }
+        write_duplicates = write_keys.tally.select { |_key, count| count > 1 }.keys
+        raise ArgumentError, "duplicate writable scope refs: #{write_duplicates.join(', ')}" unless write_duplicates.empty?
+        raise ArgumentError, 'scope_context.write must be included in read' unless write_keys.all? { |key| keys.include?(key) }
+        unless write_keys.include?("#{default_write[:type]}:#{default_write[:id]}")
+          raise ArgumentError, 'scope_context.default_write must be included in write'
+        end
+
+        { domain_id: normalized_domain, read: read, write: write, default_write: default_write }
+      end
+
+      def self.legacy_context(session_id)
+        ref = { type: 'session', id: session_id.to_s }
+        { read: [ref], write: [ref], default_write: ref }
+      end
+    end
+  end
+end

data/lib/smart_brain/contracts/scope_ref.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Contracts
+    class ScopeRef
+      DEFAULT_ALLOWED_TYPES = %w[global project expert task session].freeze
+
+      def self.normalize(value, allowed_types: DEFAULT_ALLOWED_TYPES)
+        raise ArgumentError, 'scope ref must be an object' unless value.respond_to?(:[])
+
+        type = (value[:type] || value['type']).to_s
+        external_id = (value[:id] || value['id']).to_s
+        raise ArgumentError, "invalid scope type: #{type}" unless Array(allowed_types).map(&:to_s).include?(type)
+        raise ArgumentError, 'scope id is required' if external_id.strip.empty?
+
+        { type: type, id: external_id }
+      end
+
+      def self.key(value)
+        ref = normalize(value)
+        "#{ref[:type]}:#{ref[:id]}"
+      end
+    end
+  end
+end

data/lib/smart_brain/db.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'sequel'
+require 'json'
+Sequel.extension :pg_json
+
+module SmartBrain
+  # SmartBrain::DB owns the Sequel/Postgres connection and schema migration.
+  #
+  # Backed by config/brain.yml `storage.database` (overridable via
+  # SMARTBRAIN_DB_{HOST,PORT,NAME,USER,PASSWORD} env). Connections are memoized
+  # per connection signature so the runtime, server, and CLI share one pool.
+  module DB
+    SCHEMA_SQL_PATH = File.expand_path('../../db/migrate/001_init.sql', __dir__)
+    MIGRATIONS_DIR = File.expand_path('../../db/migrate', __dir__)
+    DEFAULT_ADAPTER = 'postgres'
+
+    class << self
+      # Returns a memoized Sequel::Database for the given config (or config hash).
+      def connect(config)
+        opts = connection_opts(config)
+        signature = opts.hash
+        return pools[signature] if pools.key?(signature)
+
+        db = Sequel.connect(opts)
+        db.sql_log_level = :error if db.respond_to?(:sql_log_level=)
+        db.extension(:pg_json) rescue nil
+        pools[signature] = db
+      end
+
+      # Run all bundled migration SQL files in order (each is idempotent:
+      # CREATE TABLE/INDEX IF NOT EXISTS, ADD COLUMN IF NOT EXISTS).
+      def migrate(db)
+        Dir.glob(File.join(MIGRATIONS_DIR, '*.sql')).sort.each do |path|
+          db.run(File.read(path))
+        end
+        true
+      end
+
+      # True if a Postgres connection can be established for the given config.
+      def reachable?(config)
+        db = Sequel.connect(connection_opts(config))
+        begin
+          db.test_connection
+        rescue StandardError
+          false
+        else
+          true
+        ensure
+          db.disconnect if db
+        end
+      end
+
+      # Drop all memoized connections (used by tests / reconfigure).
+      def disconnect!
+        pools.each_value(&:disconnect)
+        pools.clear
+      end
+
+      # Recursively symbolize a JSONB value read from Postgres. Robust whether
+      # the adapter returns a parsed Hash/Array, a Sequel JSONBHash/JSONBArray
+      # wrapper (NOT a Hash subclass in recent Sequel), or a raw JSON String.
+      def symbolize_jsonb(obj)
+        case obj
+        when String
+          begin
+            parsed = JSON.parse(obj)
+            parsed.is_a?(Hash) || parsed.is_a?(Array) ? symbolize_jsonb(parsed) : obj
+          rescue JSON::ParserError, TypeError
+            obj
+          end
+        when ->(o) { o.respond_to?(:to_hash) }
+          obj.to_hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize_jsonb(v) }
+        when ->(o) { !o.nil? && !o.is_a?(String) && o.respond_to?(:to_a) }
+          obj.to_a.map { |v| symbolize_jsonb(v) }
+        else
+          obj
+        end
+      end
+
+      # Stringify keys for storage into a JSONB column (Sequel pg_json stores
+      # string keys; symbol keys round-trip fine but strings are canonical).
+      def stringify_keys(obj)
+        return obj unless obj.is_a?(Hash)
+
+        obj.transform_keys(&:to_s)
+      end
+
+      private
+
+      def pools
+        @pools ||= {}
+      end
+
+      def connection_opts(config)
+        cfg = config.respond_to?(:database_config) ? config.database_config : config.fetch(:database, {})
+        adapter = (cfg[:adapter] || DEFAULT_ADAPTER).to_sym
+        opts = { adapter: adapter }
+        opts[:host] = cfg[:host].to_s if cfg[:host]
+        opts[:port] = cfg[:port].to_i if cfg[:port]
+        opts[:database] = cfg[:database].to_s if cfg[:database]
+        opts[:user] = cfg[:user].to_s if cfg[:user]
+        opts[:password] = cfg[:password].to_s if cfg[:password]
+        opts[:max_connections] = (cfg[:max_connections] || 4).to_i
+        opts
+      end
+    end
+  end
+end

data/lib/smart_brain/event_store/in_memory.rb

@@ -9,8 +9,12 @@ module SmartBrain
         @sessions = {}
       end
 
-      def append_turn(session_id:, turn_events:, created_at:)
-        session = sessions[session_id] ||= { seq: 0, turns: [] }
+      def append_turn(session_id:, turn_events:, created_at:, domain_id: 'legacy')
+        session = sessions[session_id]
+        if session && session[:domain_id] != domain_id
+          raise ArgumentError, "session #{session_id} belongs to domain #{session[:domain_id]}"
+        end
+        session ||= sessions[session_id] = { domain_id: domain_id, seq: 0, turns: [] }
         session[:seq] += 1
         turn_id = SecureRandom.uuid
         messages = normalize_messages(turn_id: turn_id, messages: turn_events[:messages] || [], created_at: created_at)

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