smart_brain 0.1.1 → 0.2.0

data/lib/smart_brain/configuration.rb

@@ -37,5 +37,62 @@ module SmartBrain
     def observability
       policies.fetch(:observability, {})
     end
+
+    def scopes
+      policies.fetch(:scopes, {})
+    end
+
+    def allowed_scope_types
+      scopes.fetch(:allowed_types, %w[global project expert task session]).map(&:to_s)
+    end
+
+    def storage
+      raw.fetch(:storage, {})
+    end
+
+    def llm
+      raw.fetch(:model_provider, {})
+    end
+
+    def llm_provider
+      (ENV['SMARTBRAIN_LLM_PROVIDER'] || llm.fetch(:provider, 'stub')).to_s
+    end
+
+    def tiers
+      raw.fetch(:tiers, {})
+    end
+
+    def lifecycle
+      raw.fetch(:lifecycle, {})
+    end
+
+    def kg
+      raw.fetch(:kg, {})
+    end
+
+    def fact_check
+      raw.fetch(:fact_check, {})
+    end
+
+    def briefing
+      raw.fetch(:briefing, {})
+    end
+
+    def storage_backend
+      (ENV['SMARTBRAIN_BACKEND'] || storage.fetch(:backend, 'memory')).to_s
+    end
+
+    def database_config
+      cfg = (storage.fetch(:database, {}) || {}).dup
+      %i[host port database user password].each do |key|
+        env_key = "SMARTBRAIN_DB_#{key.to_s.upcase}"
+        cfg[key] = ENV[env_key] if ENV.key?(env_key)
+      end
+      cfg
+    end
+
+    def fts_config
+      storage.fetch(:fts_config, nil) || database_config.fetch(:fts_config, 'simple')
+    end
   end
 end

data/lib/smart_brain/consolidator/working_summary.rb

@@ -1,42 +1,103 @@
 # frozen_string_literal: true
 
+require_relative '../model_provider/stub'
+
 module SmartBrain
   module Consolidator
+    # WorkingSummary is store-backed: summaries persist via the MemoryStore
+    # (in-memory hash for MemoryStore::InMemory, the summaries table for
+    # MemoryStore::Postgres), so they survive runtime restarts on the PG path.
+    # The last-summary turn is derived from the persisted summary's source range.
+    #
+    # When a real LLM ModelProvider is wired, the summary text is generated by
+    # the model (qwen3 etc.); otherwise it falls back to the deterministic
+    # template (Stub default), so behavior is stable and offline-friendly.
     class WorkingSummary
-      def initialize(config:, clock:)
+      SUMMARY_SYSTEM = 'You are a memory consolidator. Produce a concise rolling ' \
+                       'summary in the exact section structure given. Skip empty ' \
+                       'sections. No preamble, no markdown fences.'
+
+      def initialize(config:, clock:, memory_store:, model_provider: SmartBrain::ModelProvider::Stub.new)
         @config = config
         @clock = clock
-        @summaries = {}
-        @last_summary_turn = Hash.new(0)
+        @memory_store = memory_store
+        @model_provider = model_provider
       end
 
       def update(session_id:, turn_count:, recent_turns:, memory_items:, stage_event: false)
         reason = trigger_reason(session_id: session_id, turn_count: turn_count, recent_turns: recent_turns, stage_event: stage_event)
-        return latest_summary(session_id).merge(triggered: false, trigger_reason: 'not_triggered') unless reason
+        unless reason
+          return latest_summary(session_id).merge(triggered: false, trigger_reason: 'not_triggered')
+        end
 
+        text, method = build_summary_text(memory_items: memory_items, recent_turns: recent_turns)
         summary = {
           summary_version: next_version(session_id),
           summary_source_turn_range: source_turn_range(turn_count),
           summary_generated_at: clock.call.iso8601,
-          text: build_text(memory_items),
+          text: text,
+          summary_method: method,
           triggered: true,
           trigger_reason: reason
         }
-        summaries[session_id] = summary
-        last_summary_turn[session_id] = turn_count
+        memory_store.save_summary(session_id: session_id, summary: summary)
         summary
       end
 
       def latest_summary(session_id)
-        summaries[session_id] || default_summary
+        memory_store.latest_summary(session_id: session_id) || default_summary
       end
 
       private
 
-      attr_reader :config, :clock, :summaries, :last_summary_turn
+      attr_reader :config, :clock, :memory_store, :model_provider
+
+      def build_summary_text(memory_items:, recent_turns:)
+        if model_provider&.llm?
+          text = llm_summary(memory_items: memory_items, recent_turns: recent_turns)
+          return [text, 'llm'] unless text.nil? || text.strip.empty?
+        end
+
+        [build_text(memory_items), 'template']
+      end
+
+      def llm_summary(memory_items:, recent_turns:)
+        result = model_provider.complete(
+          prompt: summary_prompt(memory_items: memory_items, recent_turns: recent_turns),
+          system: SUMMARY_SYSTEM,
+          temperature: config.llm.fetch(:temperature, 0.2),
+          max_tokens: config.llm.fetch(:summary_max_tokens, 900)
+        )
+        result[:error] ? nil : result[:text]
+      rescue StandardError
+        nil
+      end
+
+      def summary_prompt(memory_items:, recent_turns:)
+        convo = Array(recent_turns).map { |t| "#{t[:role]}: #{t[:content]}" }.join("\n")
+        mem = memory_items.group_by { |i| i[:type] }
+                          .map { |type, items| "#{type}: #{items.first(8).map { |i| i[:key] }.join(', ')}" }
+                          .join("\n")
+        <<~PROMPT
+          <conversation>
+          #{convo}
+          </conversation>
+
+          <memory>
+          #{mem}
+          </memory>
+
+          Write a concise rolling summary of the conversation above using ONLY these sections (omit a section if empty, terse bullets, cite memory keys). Do not echo the input or add preamble:
+          Goals:
+          Decisions:
+          Tasks:
+          Key References:
+          Open Questions:
+        PROMPT
+      end
 
       def trigger_reason(session_id:, turn_count:, recent_turns:, stage_event:)
-        turns_since_last = turn_count - last_summary_turn[session_id]
+        turns_since_last = turn_count - last_summary_turn(session_id)
         threshold = config.retention.fetch(:summarize_after_turns, 12)
         return 'turn_threshold' if turns_since_last >= threshold
 
@@ -48,13 +109,20 @@ module SmartBrain
         nil
       end
 
+      def last_summary_turn(session_id)
+        summary = memory_store.latest_summary(session_id: session_id)
+        return 0 unless summary
+
+        (summary[:summary_source_turn_range] || {})[:to].to_i
+      end
+
       def estimate_tokens(recent_turns)
         recent_turns.sum { |t| t[:content].to_s.length / 4 }
       end
 
       def next_version(session_id)
-        previous = summaries[session_id]
-        previous ? previous[:summary_version] + 1 : 1
+        previous = memory_store.latest_summary(session_id: session_id)
+        previous ? previous[:summary_version].to_i + 1 : 1
       end
 
       def source_turn_range(turn_count)

data/lib/smart_brain/context_composer/composer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require_relative '../governance/tiers'
 
 module SmartBrain
   module ContextComposer
@@ -10,9 +11,10 @@ module SmartBrain
         @clock = clock
       end
 
-      def compose(session_id:, user_message:, plan:, plan_id:, summary:, recent_turns:, evidence_bundle:)
+      def compose(session_id:, user_message:, plan:, plan_id:, summary:, recent_turns:, evidence_bundle:,
+                  domain_id: 'legacy', scope_context: nil)
         context_id = SecureRandom.uuid
-        evidence = evidence_bundle.fetch(:selected, [])
+        evidence = apply_tier_order(evidence_bundle.fetch(:selected, []))
         used_estimate = estimate_tokens(summary: summary[:text], recent_turns: recent_turns, evidence: evidence, user_message: user_message)
         token_limit = config.composition.fetch(:token_limit, 8192)
 
@@ -20,6 +22,8 @@ module SmartBrain
           version: '0.1',
           context_id: context_id,
           session_id: session_id,
+          domain_id: domain_id,
+          scope_context: scope_context,
           created_at: clock.call.iso8601,
           system_blocks: [],
           developer_blocks: [],
@@ -54,7 +58,14 @@ module SmartBrain
             },
             why_selected: evidence.map { |e| "#{e[:id]} score=#{e[:score]} source=#{e[:source]}" },
             ignored: evidence_bundle[:ignored_fields] || [],
-            dropped: (evidence_bundle[:dropped] || []).map { |e| { id: e[:id], reason: e[:drop_reason] } }
+            dropped: (evidence_bundle[:dropped] || []).map { |e| { id: e[:id], reason: e[:drop_reason] } },
+            scopes_read: Array(scope_context && scope_context[:read]),
+            scope_stats: evidence_bundle[:scope_stats] || {},
+            shadowed: (evidence_bundle[:shadowed] || []).map do |e|
+              e.slice(:id, :memory_type, :memory_key, :scope, :shadow_reason, :shadowed_by)
+            end,
+            scope_budget: evidence_bundle[:scope_budget] || {},
+            scope_filter_warnings: evidence_bundle[:scope_filter_warnings] || []
           }
         }
       end
@@ -70,6 +81,32 @@ module SmartBrain
         text_size += user_message.to_s.length
         (text_size / 4.0).ceil
       end
+
+      # Order evidence by mind-model tier (dao_tian → dao_ren → shu → qi →
+      # evidence), preserving score order within a tier, and cap immutable
+      # dao_tian principles at dao_tian_limit.
+      def apply_tier_order(evidence)
+        dao_tian_limit = begin
+                           Governance::Tiers.dao_tian_limit(config)
+                         rescue StandardError
+                           1
+                         end
+        stable = evidence.each_with_index
+        sorted = stable.sort_by do |e, idx|
+          [Governance::Tiers.priority(e[:tier] || 'evidence'), -(e[:score] || 0.0), idx]
+        end
+        result = []
+        dao_tian_count = 0
+        sorted.each do |e, _idx|
+          if (e[:tier] || 'evidence') == 'dao_tian'
+            next if dao_tian_count >= dao_tian_limit
+
+            dao_tian_count += 1
+          end
+          result << e
+        end
+        result
+      end
     end
   end
 end

data/lib/smart_brain/contracts/retrieval_plan.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'scope_context'
+
 module SmartBrain
   module Contracts
     class RetrievalPlan
@@ -10,6 +12,14 @@ module SmartBrain
         raise ArgumentError, "invalid retrieval plan: missing #{missing.join(', ')}" unless missing.empty?
         raise ArgumentError, 'invalid retrieval plan: queries must not be empty' if Array(plan[:queries]).empty?
 
+        if plan[:scope_context]
+          ScopeContext.normalize(
+            domain_id: plan.dig(:debug, :caller, :domain_id),
+            session_id: plan.dig(:debug, :caller, :session_id) || plan[:session_id],
+            scope_context: plan[:scope_context]
+          )
+        end
+
         true
       end
     end

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)