smart_brain 0.1.0

data/lib/smart_brain/memory_store/in_memory.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module SmartBrain
+  module MemoryStore
+    class InMemory
+      OVERWRITE_TYPES = %w[preferences goals tasks].freeze
+
+      def initialize
+        @by_session = Hash.new { |h, k| h[k] = [] }
+        @entities_index = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def upsert(extracted)
+        session_id = extracted.fetch(:session_id)
+        items = extracted.fetch(:items, [])
+        written = []
+        conflicts = []
+
+        items.each do |item|
+          existing = active_item(session_id: session_id, type: item[:type], key: item[:key])
+
+          if existing && item[:status] == 'retracted'
+            existing[:status] = 'retracted'
+            conflicts << { type: 'retract', key: item[:key], previous_memory_item_id: existing[:id] }
+            next
+          end
+
+          if existing && OVERWRITE_TYPES.include?(item[:type])
+            existing[:status] = 'superseded'
+            conflicts << { type: 'overwrite', key: item[:key], previous_memory_item_id: existing[:id] }
+          end
+
+          record = item.merge(id: SecureRandom.uuid, status: item[:status] || 'active')
+          by_session[session_id] << record
+          update_entities(session_id: session_id, record: record)
+          written << record.slice(:id, :type, :key, :status, :confidence)
+        end
+
+        { count: written.size, items: written, conflicts: conflicts }
+      end
+
+      def active_items(session_id:)
+        by_session[session_id].select { |item| item[:status] == 'active' }
+      end
+
+      def entities(session_id:)
+        entities_index[session_id]
+      end
+
+      private
+
+      attr_reader :by_session, :entities_index
+
+      def active_item(session_id:, type:, key:)
+        by_session[session_id].find { |row| row[:type] == type && row[:key] == key && row[:status] == 'active' }
+      end
+
+      def update_entities(session_id:, record:)
+        return unless record[:type] == 'entities'
+
+        value = record[:value_json]
+        canonical = value[:canonical] || value[:name]
+        existing = entities_index[session_id].find { |e| e[:canonical] == canonical && e[:kind] == value[:kind] }
+        return if existing
+
+        entities_index[session_id] << {
+          id: SecureRandom.uuid,
+          name: value[:name] || canonical,
+          kind: value[:kind] || 'other',
+          canonical: canonical,
+          memory_item_id: record[:id]
+        }
+      end
+    end
+  end
+end

data/lib/smart_brain/observability/tracker.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Observability
+    class Tracker
+      def initialize
+        @compose_logs = []
+        @commit_logs = []
+      end
+
+      def log_compose(payload)
+        compose_logs << payload
+      end
+
+      def log_commit(payload)
+        commit_logs << payload
+      end
+
+      def snapshot
+        {
+          compose_logs: compose_logs,
+          commit_logs: commit_logs,
+          metrics: {
+            compose_p95_ms: p95(compose_logs.map { |l| l[:took_ms] }),
+            memory_resource_ratio: memory_resource_ratio,
+            token_over_budget_rate: token_over_budget_rate
+          }
+        }
+      end
+
+      private
+
+      attr_reader :compose_logs, :commit_logs
+
+      def p95(values)
+        values = values.compact.sort
+        return 0 if values.empty?
+
+        index = [(values.length * 0.95).ceil - 1, 0].max
+        values[index]
+      end
+
+      def memory_resource_ratio
+        selected = compose_logs.flat_map { |l| l[:selected_evidence] || [] }
+        return '0/0' if selected.empty?
+
+        memory = selected.count { |e| e[:source] == 'memory' }
+        resource = selected.count { |e| e[:source] == 'resource' }
+        "#{memory}/#{resource}"
+      end
+
+      def token_over_budget_rate
+        return 0.0 if compose_logs.empty?
+
+        over = compose_logs.count { |l| l[:token_used].to_i > l[:token_limit].to_i }
+        (over.to_f / compose_logs.length).round(3)
+      end
+    end
+  end
+end

data/lib/smart_brain/retrieval_planner/planner.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module RetrievalPlanner
+    class Planner
+      RESOURCE_HINTS = ['查资料', '引用', 'reference', 'research', '标准', '论文', '文档', 'compare', '对比', '来源'].freeze
+
+      def initialize(config:)
+        @config = config
+      end
+
+      def plan(request_id:, session_id:, user_message:, agent_state:, recent_turns:, refs:)
+        queries = build_queries(user_message)
+        plan = {
+          version: '0.1',
+          request_id: request_id,
+          purpose: infer_purpose(user_message),
+          queries: queries,
+          global_filters: {},
+          budget: {
+            top_k: config.retrieval.fetch(:top_k, 30),
+            candidate_k: config.retrieval.fetch(:candidate_k, 200),
+            per_mode_k: {
+              exact: 10,
+              semantic: 10,
+              hybrid: config.retrieval.fetch(:top_k, 30),
+              relational: 10,
+              associative: 8
+            },
+            diversity: {
+              by_document: config.composition.dig(:diversity, :by_document) || 3,
+              by_source: config.composition.dig(:diversity, :by_source_uri) || 2
+            }
+          },
+          output: {
+            include_snippets: true,
+            max_snippet_chars: config.composition.fetch(:max_snippet_chars, 800)
+          },
+          resource_retrieval: {
+            enabled: resource_retrieval_enabled?(user_message: user_message, recent_turns: recent_turns, refs: refs),
+            reason: resource_reason(user_message: user_message, refs: refs)
+          },
+          debug: {
+            trace: config.observability.fetch(:trace, true),
+            caller: { app: 'smart_brain', session_id: session_id },
+            recent_turns_count: recent_turns.size,
+            agent_state: agent_state,
+            ignored_fields: []
+          }
+        }
+
+        attach_filter_hints!(plan: plan, user_message: user_message)
+        plan
+      end
+
+      private
+
+      attr_reader :config
+
+      def build_queries(user_message)
+        queries = [{ text: user_message, mode: 'hybrid', weight: 1.0, filters: {}, hints: {} }]
+        return queries unless config.retrieval.dig(:query_expansion, :enabled)
+
+        max = config.retrieval.dig(:query_expansion, :max_queries) || 8
+        expansions = expansion_terms(user_message).first([max - 1, 0].max)
+        queries.concat(expansions.map.with_index do |text, idx|
+          { text: text, mode: 'associative', weight: 0.8 - (idx * 0.05), filters: {}, hints: { expanded: true } }
+        end)
+        queries
+      end
+
+      def expansion_terms(user_message)
+        tokens = user_message.to_s.scan(/[[:alnum:]_\-\p{Han}]+/).uniq
+        return [] if tokens.size < 2
+
+        phrases = []
+        phrases << tokens.first(3).join(' ')
+        phrases << tokens.last(3).join(' ')
+        phrases << tokens.sort.join(' ')
+        phrases.uniq.reject { |p| p == user_message }
+      end
+
+      def infer_purpose(user_message)
+        lowered = user_message.downcase
+        return 'research' if RESOURCE_HINTS.any? { |hint| lowered.include?(hint) }
+
+        'qa'
+      end
+
+      def resource_retrieval_enabled?(user_message:, recent_turns:, refs:)
+        mode = config.retrieval.fetch(:enable_resource_retrieval, 'auto')
+        return true if mode == true
+        return false if mode == false
+
+        lowered = user_message.downcase
+        return true if RESOURCE_HINTS.any? { |hint| lowered.include?(hint) }
+        return true if refs.any?
+
+        recent_turns.any? { |turn| turn[:content].to_s.match?(%r{https?://|\.(md|rb|txt)}) }
+      end
+
+      def resource_reason(user_message:, refs:)
+        lowered = user_message.downcase
+        return 'user_requested_external_evidence' if RESOURCE_HINTS.any? { |hint| lowered.include?(hint) }
+        return 'has_recent_refs' if refs.any?
+
+        'auto_disabled_or_not_needed'
+      end
+
+      def attach_filter_hints!(plan:, user_message:)
+        text = user_message.downcase
+        if text.include?('最近') || text.include?('recent')
+          plan[:global_filters][:time_range] = { from: (Time.now.utc - 7 * 24 * 3600).iso8601, to: Time.now.utc.iso8601 }
+        end
+
+        if text.include?('smart_rag')
+          plan[:global_filters][:source_uri_prefix] = ['smart_rag']
+        end
+      end
+    end
+  end
+end

data/lib/smart_brain/retrievers/exact_retriever.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Retrievers
+    class ExactRetriever
+      def retrieve(query:, memory_items:, recent_turns:, limit:)
+        terms = tokenize(query)
+
+        memory_hits = memory_items.filter_map do |item|
+          haystack = "#{item[:key]} #{item[:value_json]}".downcase
+          score = overlap_score(terms, haystack)
+          next if score <= 0
+
+          {
+            id: item[:id],
+            source: 'memory',
+            source_uri: "smartbrain://memory/#{item[:id]}",
+            title: item[:key],
+            snippet: item[:value_json].to_s,
+            mode: 'exact',
+            score: score + (item[:confidence] || 0.5),
+            ref: { memory_item_id: item[:id] }
+          }
+        end
+
+        turn_hits = recent_turns.filter_map.with_index do |turn, idx|
+          haystack = turn[:content].to_s.downcase
+          score = overlap_score(terms, haystack)
+          next if score <= 0
+
+          {
+            id: "turn-#{idx}",
+            source: 'memory',
+            source_uri: 'smartbrain://recent_turn',
+            title: 'Recent Turn',
+            snippet: turn[:content].to_s,
+            mode: 'exact',
+            score: score,
+            ref: { turn_id: turn[:turn_id], message_id: turn[:message_id] }
+          }
+        end
+
+        (memory_hits + turn_hits).sort_by { |h| -h[:score] }.first(limit)
+      end
+
+      private
+
+      def tokenize(text)
+        text.to_s.downcase.scan(/[[:alnum:]_\-\p{Han}]+/).uniq
+      end
+
+      def overlap_score(terms, haystack)
+        return 0.0 if terms.empty?
+
+        hits = terms.count { |t| haystack.include?(t) }
+        return 0.0 if hits.zero?
+
+        hits.to_f / terms.length
+      end
+    end
+  end
+end

data/lib/smart_brain/retrievers/memory_retriever.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'exact_retriever'
+require_relative 'relational_retriever'
+
+module SmartBrain
+  module Retrievers
+    class MemoryRetriever
+      def initialize(config:)
+        @config = config
+        @exact = ExactRetriever.new
+        @relational = RelationalRetriever.new(config: config)
+      end
+
+      def retrieve(query:, memory_items:, recent_turns:, entities:, refs:)
+        limit = config.composition.fetch(:evidence_max_items, 12)
+        exact_hits = exact.retrieve(query: query, memory_items: memory_items, recent_turns: recent_turns, limit: limit)
+        relational_hits = relational.retrieve(query: query, entities: entities, refs: refs, limit: limit)
+
+        (exact_hits + relational_hits)
+          .sort_by { |h| -h.fetch(:score, 0.0) }
+          .first(limit)
+      end
+
+      private
+
+      attr_reader :config, :exact, :relational
+    end
+  end
+end

data/lib/smart_brain/retrievers/relational_retriever.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Retrievers
+    class RelationalRetriever
+      def initialize(config:)
+        @config = config
+      end
+
+      def retrieve(query:, entities:, refs:, limit:)
+        terms = query.to_s.downcase.scan(/[[:alnum:]_\-\p{Han}]+/)
+        entity_hits = entities.filter_map do |entity|
+          score = terms.count { |t| entity[:canonical].to_s.downcase.include?(t) || entity[:name].to_s.downcase.include?(t) }
+          next if score.zero?
+
+          {
+            id: "entity-#{entity[:id]}",
+            source: 'memory',
+            source_uri: "smartbrain://entity/#{entity[:id]}",
+            title: entity[:name],
+            snippet: "Entity #{entity[:kind]}: #{entity[:canonical]}",
+            mode: 'relational',
+            score: score.to_f,
+            ref: { memory_item_id: entity[:memory_item_id] }
+          }
+        end
+
+        ref_hits = refs.filter_map do |ref|
+          value = ref[:ref_uri].to_s.downcase
+          score = terms.count { |t| value.include?(t) }
+          next if score.zero?
+
+          {
+            id: "ref-#{ref[:id]}",
+            source: 'memory',
+            source_uri: ref[:ref_uri],
+            title: ref[:ref_type],
+            snippet: ref[:ref_meta_json].to_s,
+            mode: 'relational',
+            score: (score * 0.8).to_f,
+            ref: { turn_id: ref[:turn_id] }
+          }
+        end
+
+        (entity_hits + ref_hits).sort_by { |h| -h[:score] }.first(limit)
+      end
+
+      private
+
+      attr_reader :config
+    end
+  end
+end

data/lib/smart_brain/runtime.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'contracts/retrieval_plan'
+require_relative 'contracts/evidence_pack'
+require_relative 'contracts/context_package'
+require_relative 'observability/tracker'
+require_relative 'event_store/in_memory'
+require_relative 'memory_store/in_memory'
+require_relative 'memory_extractor/extractor'
+require_relative 'consolidator/working_summary'
+require_relative 'retrieval_planner/planner'
+require_relative 'retrievers/memory_retriever'
+require_relative 'adapters/smart_rag/null_client'
+require_relative 'fusion/merger'
+require_relative 'context_composer/composer'
+
+module SmartBrain
+  class Runtime
+    def self.build(config:, smart_rag_client: nil, clock:)
+      event_store = EventStore::InMemory.new
+      memory_store = MemoryStore::InMemory.new
+      new(
+        config: config,
+        clock: clock,
+        event_store: event_store,
+        memory_store: memory_store,
+        extractor: MemoryExtractor::Extractor.new(config: config),
+        consolidator: Consolidator::WorkingSummary.new(config: config, clock: clock),
+        planner: RetrievalPlanner::Planner.new(config: config),
+        memory_retriever: Retrievers::MemoryRetriever.new(config: config),
+        smart_rag_client: smart_rag_client || Adapters::SmartRag::NullClient.new,
+        merger: Fusion::Merger.new(config: config),
+        composer: ContextComposer::Composer.new(config: config, clock: clock),
+        tracker: Observability::Tracker.new
+      )
+    end
+
+    def initialize(config:, clock:, event_store:, memory_store:, extractor:, consolidator:, planner:, memory_retriever:, smart_rag_client:, merger:, composer:, tracker:)
+      @config = config
+      @clock = clock
+      @event_store = event_store
+      @memory_store = memory_store
+      @extractor = extractor
+      @consolidator = consolidator
+      @planner = planner
+      @memory_retriever = memory_retriever
+      @smart_rag_client = smart_rag_client
+      @merger = merger
+      @composer = composer
+      @tracker = tracker
+    end
+
+    def commit_turn(session_id:, turn_events:)
+      started_at = monotonic_time
+      now = clock.call
+      turn = event_store.append_turn(session_id: session_id, turn_events: turn_events, created_at: now)
+      entity_frequencies = event_store.entity_frequencies(
+        session_id: session_id,
+        window_turns: config.retention.dig(:entity_gate, :window_turns) || 20
+      )
+
+      extracted = extractor.extract(session_id: session_id, turn: turn, entity_frequencies: entity_frequencies)
+      write_result = memory_store.upsert(extracted)
+      turn_count = event_store.turns_count(session_id: session_id)
+      recent_turns = event_store.recent_turns(session_id: session_id, limit: config.composition.fetch(:recent_turns_max, 8))
+      stage_event = extracted[:items].any? { |item| item[:type] == 'decisions' || (item[:type] == 'tasks' && item.dig(:value_json, :status) == 'done') }
+      summary = consolidator.update(
+        session_id: session_id,
+        turn_count: turn_count,
+        recent_turns: recent_turns,
+        memory_items: memory_store.active_items(session_id: session_id),
+        stage_event: stage_event
+      )
+
+      result = {
+        ok: true,
+        commit_id: SecureRandom.uuid,
+        session_id: session_id,
+        turn_id: turn[:id],
+        memory_written: write_result,
+        summary: summary,
+        explain: {
+          retention: extracted.fetch(:explain, []),
+          conflicts: write_result.fetch(:conflicts, []),
+          summary: {
+            triggered: summary[:triggered],
+            reason: summary[:trigger_reason]
+          }
+        }
+      }
+
+      tracker.log_commit(
+        commit_id: result[:commit_id],
+        session_id: session_id,
+        turn_id: turn[:id],
+        memory_items: write_result[:items],
+        conflicts: write_result[:conflicts],
+        summary_triggered: summary[:triggered],
+        summary_reason: summary[:trigger_reason],
+        took_ms: elapsed_ms(started_at)
+      )
+      result
+    end
+
+    def compose_context(session_id:, user_message:, agent_state: {})
+      started_at = monotonic_time
+      recent_turns = event_store.recent_turns(session_id: session_id, limit: config.composition.fetch(:recent_turns_max, 8))
+      refs = event_store.recent_refs(session_id: session_id, limit: config.composition.fetch(:recent_turns_max, 8))
+      request_id = SecureRandom.uuid
+      plan = planner.plan(
+        request_id: request_id,
+        session_id: session_id,
+        user_message: user_message,
+        agent_state: agent_state,
+        recent_turns: recent_turns,
+        refs: refs
+      )
+      Contracts::RetrievalPlan.validate!(plan)
+
+      memory_evidence = memory_retriever.retrieve(
+        query: user_message,
+        memory_items: memory_store.active_items(session_id: session_id),
+        recent_turns: recent_turns,
+        entities: memory_store.entities(session_id: session_id),
+        refs: refs
+      )
+
+      resource_pack = if plan.dig(:resource_retrieval, :enabled)
+                        smart_rag_client.retrieve(plan)
+                      else
+                        {
+                          version: '0.1',
+                          request_id: request_id,
+                          plan_id: "local-#{request_id}",
+                          generated_at: clock.call.iso8601,
+                          evidences: [],
+                          explain: { ignored_fields: [] },
+                          warnings: ['resource retrieval disabled by planner']
+                        }
+                      end
+
+      Contracts::EvidencePack.validate!(resource_pack)
+      merged_bundle = merger.merge(
+        query: user_message,
+        memory_evidence: memory_evidence,
+        resource_evidence: resource_pack.fetch(:evidences, [])
+      )
+      merged_bundle[:ignored_fields] = Array(merged_bundle[:ignored_fields]) + Array(resource_pack.dig(:explain, :ignored_fields))
+
+      context = composer.compose(
+        session_id: session_id,
+        user_message: user_message,
+        plan: plan,
+        plan_id: resource_pack[:plan_id],
+        summary: consolidator.latest_summary(session_id),
+        recent_turns: recent_turns,
+        evidence_bundle: merged_bundle
+      )
+      Contracts::ContextPackage.validate!(context)
+
+      took_ms = elapsed_ms(started_at)
+      token_budget = context.dig(:constraints, :token_budget) || {}
+      tracker.log_compose(
+        context_id: context[:context_id],
+        session_id: session_id,
+        request_id: request_id,
+        plan_id: resource_pack[:plan_id],
+        selected_evidence: context[:evidence],
+        ignored_fields: context.dig(:debug, :ignored),
+        token_used: token_budget[:used_estimate] || 0,
+        token_limit: token_budget[:limit] || config.composition.fetch(:token_limit, 8192),
+        took_ms: took_ms
+      )
+      context
+    end
+
+    def diagnostics
+      tracker.snapshot.merge(turns: event_store.all_turns(session_id: nil))
+    end
+
+    private
+
+    attr_reader :config, :clock, :event_store, :memory_store, :extractor, :consolidator,
+                :planner, :memory_retriever, :smart_rag_client, :merger, :composer, :tracker
+
+    def monotonic_time
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def elapsed_ms(start)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+    end
+  end
+end

data/lib/smart_brain/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  VERSION = "0.1.0"
+end

data/lib/smart_brain.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'time'
+require_relative 'smart_brain/version'
+require_relative 'smart_brain/configuration'
+require_relative 'smart_brain/runtime'
+
+module SmartBrain
+  class << self
+    attr_writer :runtime
+
+    def configure(config_path: nil, smart_rag_client: nil, clock: -> { Time.now.utc })
+      config = Configuration.load(config_path)
+      @runtime = Runtime.build(config: config, smart_rag_client: smart_rag_client, clock: clock)
+    end
+
+    def commit_turn(session_id:, turn_events:)
+      runtime.commit_turn(session_id: session_id, turn_events: turn_events)
+    end
+
+    def compose_context(session_id:, user_message:, agent_state: {})
+      runtime.compose_context(session_id: session_id, user_message: user_message, agent_state: agent_state)
+    end
+
+    def diagnostics
+      runtime.diagnostics
+    end
+
+    private
+
+    def runtime
+      @runtime ||= Runtime.build(config: Configuration.load, clock: -> { Time.now.utc })
+    end
+  end
+end

data/templates/brain_assistant.erb

@@ -0,0 +1,5 @@
+You are given a context package produced by SmartBrain.
+
+<%= text %>
+
+Please answer only the latest user request.

data/workers/brain_assistant.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+SmartPrompt.define_worker :brain_assistant_worker do
+  use 'silicon_flow'
+  model 'Pro/moonshotai/Kimi-K2.5'
+  sys_msg 'You are a concise assistant. Use the provided context to answer the latest user message. If evidence exists, prioritize it.'
+  prompt :brain_assistant, { text: params[:text] }
+  send_msg
+end