smart_brain 0.1.2 → 0.2.0

data/lib/smart_brain/server/http_app.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+require 'json'
+require_relative 'service'
+
+module SmartBrain
+  module Server
+    # Minimal JSON HTTP API over a Service. Endpoints:
+    #   POST /commit   { session_id, turn_events }
+    #   POST /compose  { session_id, user_message, agent_state? }
+    #   POST /search   { session_id, query, limit? }
+    #   GET  /status
+    #   POST /migrate
+    class HttpApp < Sinatra::Base
+      class << self
+        attr_accessor :service
+      end
+
+      set :show_exceptions, false
+      set :raise_errors, false
+
+      before { content_type 'application/json' }
+
+      post '/commit' do
+        b = parse_body
+        ok service.commit(**b.slice(:domain_id, :session_id, :scope_context, :turn_events).merge(turn_events: b[:turn_events] || {}))
+      end
+
+      post '/compose' do
+        b = parse_body
+        ok service.compose(
+          session_id: b[:session_id],
+          user_message: b[:user_message],
+          agent_state: b[:agent_state] || {},
+          domain_id: b[:domain_id], scope_context: b[:scope_context]
+        )
+      end
+
+      post '/search' do
+        b = parse_body
+        ok service.search(**b.slice(:domain_id, :session_id, :scope_context, :query, :limit))
+      end
+
+      get '/status' do
+        ok service.status
+      end
+
+      post '/migrate' do
+        ok(ok: service.migrate)
+      end
+
+      post %r{/knowledge/(distill|gate|promote|demote|retract|promote-to-scope|lineage|events)} do
+        action = params[:captures].first
+        b = parse_body
+        result =
+          case action
+          when 'distill'
+            service.distill(**b.slice(:domain_id, :session_id, :scope_context, :statement, :content, :tier, :supporting_refs, :domain, :field, :reviewer, :key))
+          when 'gate'
+            service.gate(**b.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+          when 'promote'
+            service.promote(**b.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer, :force))
+          when 'demote'
+            service.demote(**b.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reason_type, :reviewer))
+          when 'retract'
+            service.retract(**b.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reviewer))
+          when 'promote-to-scope'
+            service.promote_to_scope(**b.slice(:memory_item_id, :target_scope, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer))
+          when 'lineage'
+            service.promotion_lineage(**b.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+          when 'events'
+            service.knowledge_events(**b.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+          end
+        ok(result)
+      end
+
+      post %r{/kg/(add|query|timeline|invalidate|stats)} do
+        action = params[:captures].first
+        b = parse_body
+        result =
+          case action
+          when 'add' then service.kg_add(**b.slice(:domain_id, :session_id, :scope_context, :scope_ref, :subject, :predicate, :object, :confidence, :source_turn_id))
+          when 'query' then service.kg_query(**b.slice(:domain_id, :session_id, :scope_context, :subject, :predicate, :object, :include_invalid))
+          when 'timeline' then service.kg_timeline(**b.slice(:domain_id, :session_id, :scope_context, :subject))
+          when 'invalidate' then service.kg_invalidate(**b.slice(:edge_id, :reason, :domain_id, :session_id, :scope_context))
+          when 'stats' then service.kg_stats(**b.slice(:domain_id, :session_id, :scope_context))
+          end
+        ok(result)
+      end
+
+      post '/fact-check' do
+        b = parse_body
+        ok(service.fact_check(**b.slice(:domain_id, :session_id, :scope_context, :text)))
+      end
+
+      post '/brief' do
+        b = parse_body
+        ok(service.brief(**b.slice(:domain_id, :session_id, :scope_context, :query)))
+      end
+
+      post '/wake-up' do
+        b = parse_body
+        ok(service.wake_up(**b.slice(:domain_id, :session_id, :scope_context)))
+      end
+
+      error SmartBrain::Governance::LifecycleGateError do
+        status 409
+        ok(error: "gate failed: #{env['sinatra.error'].message}")
+      end
+
+      error ArgumentError do
+        status 400
+        ok(error: env['sinatra.error'].message)
+      end
+
+      error StandardError do
+        status 500
+        ok(error: "#{env['sinatra.error'].class}: #{env['sinatra.error'].message}")
+      end
+
+      error JSON::ParserError do
+        status 400
+        ok(error: "invalid JSON body: #{env['sinatra.error'].message}")
+      end
+
+      private
+
+      def service
+        self.class.service ||= Service.build
+      end
+
+      def parse_body
+        body = request.body.read
+        body.empty? ? {} : JSON.parse(body, symbolize_names: true)
+      end
+
+      def ok(payload)
+        JSON.generate(payload)
+      end
+    end
+  end
+end

data/lib/smart_brain/server/mcp_server.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../../smart_brain'
+require_relative 'service'
+
+module SmartBrain
+  module Server
+    # Model Context Protocol server over stdio (newline-delimited JSON-RPC 2.0).
+    #
+    # No external MCP gem dependency: implements the subset clients actually use
+    # (initialize / notifications/initialized / tools/list / tools/call) so that
+    # Claude Code, Cursor, etc. can drive SmartBrain as a native tool.
+    class McpServer
+      PROTOCOL_VERSION = '2024-11-05'
+
+      INSTRUCTIONS = <<~TXT.strip
+        SmartBrain memory runtime. Available tools:
+        - commit_turn: persist a turn (messages + structured events) and extract durable memory.
+        - compose_context: assemble the minimal sufficient context (summary + recent + evidence) for a user message.
+        - search_memory: full-text recall over the session's persistent memory.
+        - knowledge_distill / knowledge_gate / knowledge_promote / knowledge_demote: the Stage-1 knowledge lifecycle (evidence → candidate → promoted → demoted). Distill reusable rules at tier dao_ren or qi; promote only after enough supporting evidence; demote with a reason_type (contradicted|obsolete|superseded).
+        - kg_add / kg_query / kg_invalidate: knowledge-graph triples (subject-predicate-object) with temporal validity. Run fact_check before asserting entity relations to catch name/contradiction/stale issues.
+        - fact_check: offline, zero-LLM contradiction scan (SimilarNameConflict / RelationContradiction / StaleFact) of a text against the session's entities + KG.
+        - brief / wake_up: deterministic citation-first cognitive snapshot and L0/L1 resume payload.
+        - status: backend, metrics, counts.
+        Always pass a stable session_id per conversation. Prefer compose_context before answering, and commit_turn after each assistant reply.
+      TXT
+
+      SCOPE_PROPERTIES = {
+        domain_id: { type: 'string' },
+        scope_context: { type: 'object' }
+      }.freeze
+
+      TOOLS = [
+        {
+          name: 'commit_turn',
+          description: 'Persist a conversation turn and extract structured memory items (decisions, tasks, goals, entities, preferences).',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              turn_events: {
+                type: 'object',
+                description: 'messages: [{role, content}], plus optional tasks/decisions/goals/entities/preferences/refs arrays.'
+              }
+            ),
+            required: %w[session_id turn_events]
+          }
+        },
+        {
+          name: 'compose_context',
+          description: 'Retrieve evidence and assemble a context package for the latest user message.',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              user_message: { type: 'string' },
+              agent_state: { type: 'object' }
+            ),
+            required: %w[session_id user_message]
+          }
+        },
+        {
+          name: 'search_memory',
+          description: 'Full-text search the session\'s persistent memory; returns ranked evidence.',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              query: { type: 'string' },
+              limit: { type: 'integer' }
+            ),
+            required: %w[session_id query]
+          }
+        },
+        {
+          name: 'status',
+          description: 'SmartBrain diagnostics: storage backend, P95, memory/resource ratio, counts.',
+          inputSchema: { type: 'object', properties: {}, additionalProperties: false }
+        },
+        {
+          name: 'knowledge_distill',
+          description: 'Distill a candidate knowledge item (tier dao_ren or qi) from supporting evidence refs.',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              statement: { type: 'string' },
+              content: { type: 'string' },
+              tier: { type: 'string', enum: %w[dao_ren qi] },
+              supporting_refs: { type: 'array', items: { type: 'string' } },
+              domain: { type: 'string' }, field: { type: 'string' }, reviewer: { type: 'string' }
+            ),
+            required: %w[session_id statement tier]
+          }
+        },
+        {
+          name: 'knowledge_gate',
+          description: 'Read-only check: is a candidate knowledge item ready for promotion?',
+          inputSchema: { type: 'object', properties: SCOPE_PROPERTIES.merge(memory_item_id: { type: 'string' }, session_id: { type: 'string' }), required: %w[memory_item_id] }
+        },
+        {
+          name: 'knowledge_promote',
+          description: 'Gate-enforced promotion of a candidate knowledge item to promoted.',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              memory_item_id: { type: 'string' },
+              verification_refs: { type: 'array', items: { type: 'string' } },
+              reason: { type: 'string' }, reviewer: { type: 'string' }, force: { type: 'boolean' }
+            ),
+            required: %w[memory_item_id verification_refs reason]
+          }
+        },
+        {
+          name: 'knowledge_demote',
+          description: 'Evidence-backed demotion of a knowledge item (reason_type: contradicted|obsolete|superseded).',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              memory_item_id: { type: 'string' },
+              evidence_refs: { type: 'array', items: { type: 'string' } },
+              reason: { type: 'string' },
+              reason_type: { type: 'string', enum: %w[contradicted obsolete superseded] }
+            ),
+            required: %w[memory_item_id evidence_refs reason reason_type]
+          }
+        },
+        {
+          name: 'knowledge_promote_to_scope',
+          description: 'Copy a verified memory item into a writable target scope while preserving provenance.',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' }, memory_item_id: { type: 'string' }, target_scope: { type: 'object' },
+              verification_refs: { type: 'array', items: { type: 'string' } }, reason: { type: 'string' }, reviewer: { type: 'string' }
+            ),
+            required: %w[domain_id session_id scope_context memory_item_id target_scope verification_refs reason]
+          }
+        },
+        {
+          name: 'knowledge_retract',
+          description: 'Retract a memory item with evidence and an audit event.',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' }, memory_item_id: { type: 'string' },
+              evidence_refs: { type: 'array', items: { type: 'string' } }, reason: { type: 'string' }, reviewer: { type: 'string' }
+            ),
+            required: %w[memory_item_id evidence_refs reason]
+          }
+        },
+        {
+          name: 'knowledge_lineage',
+          description: 'Return cross-scope promotion lineage for a memory item.',
+          inputSchema: {
+            type: 'object', properties: SCOPE_PROPERTIES.merge(session_id: { type: 'string' }, memory_item_id: { type: 'string' }),
+            required: %w[memory_item_id]
+          }
+        },
+        {
+          name: 'kg_add',
+          description: 'Add a knowledge-graph triple (subject-predicate-object) with temporal validity.',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              subject: { type: 'string' },
+              predicate: { type: 'string' },
+              object: { type: 'string' },
+              confidence: { type: 'number' },
+              scope_ref: { type: 'object' }
+            ),
+            required: %w[session_id subject predicate object]
+          }
+        },
+        {
+          name: 'kg_query',
+          description: 'Query KG triples (any of subject/predicate/object; include_invalid to see invalidated).',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              session_id: { type: 'string' },
+              subject: { type: 'string' }, predicate: { type: 'string' }, object: { type: 'string' },
+              include_invalid: { type: 'boolean' }
+            ),
+            required: %w[session_id]
+          }
+        },
+        {
+          name: 'kg_invalidate',
+          description: 'Invalidate a KG triple (sets valid_to=now, status=invalidated).',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(
+              edge_id: { type: 'string' }, reason: { type: 'string' }, session_id: { type: 'string' }
+            ),
+            required: %w[edge_id]
+          }
+        },
+        {
+          name: 'kg_timeline',
+          description: 'Return the temporal history of KG edges for a subject across readable scopes.',
+          inputSchema: {
+            type: 'object', properties: SCOPE_PROPERTIES.merge(session_id: { type: 'string' }, subject: { type: 'string' }),
+            required: %w[session_id subject]
+          }
+        },
+        {
+          name: 'kg_stats',
+          description: 'Return KG active and invalidated counts across readable scopes.',
+          inputSchema: {
+            type: 'object', properties: SCOPE_PROPERTIES.merge(session_id: { type: 'string' }), required: %w[session_id]
+          }
+        },
+        {
+          name: 'fact_check',
+          description: 'Offline zero-LLM contradiction scan of text vs session entities + KG (SimilarName/Relation/StaleFact).',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(session_id: { type: 'string' }, text: { type: 'string' }),
+            required: %w[session_id text]
+          }
+        },
+        {
+          name: 'brief',
+          description: 'Deterministic citation-first cognitive snapshot (summary/key_facts/evidence/entities/unresolved/uncertainty/next_actions).',
+          inputSchema: {
+            type: 'object',
+            properties: SCOPE_PROPERTIES.merge(session_id: { type: 'string' }, query: { type: 'string' }),
+            required: %w[session_id]
+          }
+        },
+        {
+          name: 'wake_up',
+          description: 'Minimal L0/L1 importance-ordered resume payload for a session.',
+          inputSchema: { type: 'object', properties: SCOPE_PROPERTIES.merge(session_id: { type: 'string' }), required: %w[session_id] }
+        }
+      ].freeze
+
+      attr_reader :service
+
+      def initialize(service:, in_io: $stdin, out_io: $stdout, err_io: $stderr)
+        @service = service
+        @in = in_io
+        @out = out_io
+        @err = err_io
+      end
+
+      def run
+        @out.sync = true
+        @in.each_line do |raw|
+          line = raw.to_s.strip
+          next if line.empty?
+
+          request = JSON.parse(line)
+          handle(request)
+        rescue JSON::ParserError => e
+          log("ignoring malformed line: #{e.message}")
+        rescue StandardError => e
+          log("handler error: #{e.class}: #{e.message}")
+        end
+      end
+
+      private
+
+      def handle(req)
+        method_name = req['method']
+        id = req['id']
+
+        case method_name
+        when 'initialize'
+          respond(id, {
+                    protocolVersion: PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'smart_brain', version: SmartBrain::VERSION },
+                    instructions: INSTRUCTIONS
+                  })
+        when 'notifications/initialized'
+          # client-ready notification; no response expected
+          nil
+        when 'tools/list'
+          respond(id, { tools: TOOLS })
+        when 'tools/call'
+          respond(id, call_tool(req.fetch('params', {})))
+        else
+          respond_error(id, -32601, "method not found: #{method_name}")
+        end
+      end
+
+      def call_tool(params)
+        name = params['name']
+        # JSON arguments arrive with string keys; SmartBrain internals expect
+        # symbols (e.g. extractor reads events[:decisions]). Deep-symbolize.
+        args = deep_symbolize(params['arguments'] || {})
+
+        result =
+          case name
+          when 'commit_turn'
+            service.commit(**args.slice(:domain_id, :session_id, :scope_context, :turn_events).merge(turn_events: args[:turn_events] || {}))
+          when 'compose_context'
+            service.compose(**args.slice(:domain_id, :session_id, :scope_context, :user_message, :agent_state).merge(agent_state: args[:agent_state] || {}))
+          when 'search_memory'
+            service.search(**args.slice(:domain_id, :session_id, :scope_context, :query, :limit))
+          when 'status'
+            service.status
+          when 'knowledge_distill'
+            service.distill(**args.slice(:domain_id, :session_id, :scope_context, :statement, :content, :tier, :supporting_refs, :domain, :field, :reviewer, :key))
+          when 'knowledge_gate'
+            service.gate(**args.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+          when 'knowledge_promote'
+            service.promote(**args.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer, :force))
+          when 'knowledge_demote'
+            service.demote(**args.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reason_type, :reviewer))
+          when 'knowledge_promote_to_scope'
+            service.promote_to_scope(**args.slice(:memory_item_id, :target_scope, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer))
+          when 'knowledge_retract'
+            service.retract(**args.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reviewer))
+          when 'knowledge_lineage'
+            service.promotion_lineage(**args.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+          when 'kg_add'
+            service.kg_add(**args.slice(:domain_id, :session_id, :scope_context, :scope_ref, :subject, :predicate, :object, :confidence, :source_turn_id))
+          when 'kg_query'
+            service.kg_query(**args.slice(:domain_id, :session_id, :scope_context, :subject, :predicate, :object, :include_invalid))
+          when 'kg_invalidate'
+            service.kg_invalidate(**args.slice(:edge_id, :reason, :domain_id, :session_id, :scope_context))
+          when 'kg_timeline'
+            service.kg_timeline(**args.slice(:domain_id, :session_id, :scope_context, :subject))
+          when 'kg_stats'
+            service.kg_stats(**args.slice(:domain_id, :session_id, :scope_context))
+          when 'fact_check'
+            service.fact_check(**args.slice(:domain_id, :session_id, :scope_context, :text))
+          when 'brief'
+            service.brief(**args.slice(:domain_id, :session_id, :scope_context, :query))
+          when 'wake_up'
+            service.wake_up(**args.slice(:domain_id, :session_id, :scope_context))
+          else
+            return error_result("unknown tool: #{name}")
+          end
+
+        { content: [{ type: 'text', text: JSON.generate(result) }] }
+      rescue StandardError => e
+        error_result("#{e.class}: #{e.message}")
+      end
+
+      def deep_symbolize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize(v) }
+        when Array
+          obj.map { |v| deep_symbolize(v) }
+        else
+          obj
+        end
+      end
+
+      def respond(id, result)
+        return if id.nil? # notification
+
+        write(jsonrpc: '2.0', id: id, result: result)
+      end
+
+      def respond_error(id, code, message)
+        return if id.nil?
+
+        write(jsonrpc: '2.0', id: id, error: { code: code, message: message })
+      end
+
+      def error_result(message)
+        { isError: true, content: [{ type: 'text', text: message }] }
+      end
+
+      def write(payload)
+        @out.puts(JSON.generate(payload))
+      end
+
+      def log(message)
+        @err&.puts("[smart_brain mcp] #{message}")
+      end
+    end
+  end
+end

data/lib/smart_brain/server/service.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative '../../smart_brain'
+
+module SmartBrain
+  module Server
+    # Shared facade over the SmartBrain runtime. The HTTP app, MCP server, and
+    # CLI all go through a Service instance so behavior is identical across
+    # every front-end and only the transport differs.
+    class Service
+      class << self
+        # Configure the singleton runtime and return a Service bound to it.
+        def build(config_path: nil, smart_rag_client: nil)
+          SmartBrain.configure(config_path: config_path, smart_rag_client: smart_rag_client)
+          new
+        end
+      end
+
+      def initialize
+        raise 'SmartBrain runtime not configured; call Service.build first' unless SmartBrain.instance_variable_get(:@runtime)
+      end
+
+      def commit(session_id:, turn_events:, domain_id: nil, scope_context: nil)
+        SmartBrain.commit_turn(session_id: session_id, turn_events: turn_events, domain_id: domain_id, scope_context: scope_context)
+      end
+
+      def compose(session_id:, user_message:, agent_state: {}, domain_id: nil, scope_context: nil)
+        SmartBrain.compose_context(
+          session_id: session_id, user_message: user_message, agent_state: agent_state,
+          domain_id: domain_id, scope_context: scope_context
+        )
+      end
+
+      def search(session_id:, query:, limit: nil, domain_id: nil, scope_context: nil)
+        SmartBrain.search_memory(
+          session_id: session_id, query: query, limit: limit, domain_id: domain_id, scope_context: scope_context
+        )
+      end
+
+      def status
+        SmartBrain.diagnostics
+      end
+
+      def migrate
+        SmartBrain.migrate
+      rescue StandardError => e
+        { ok: false, error: "#{e.class}: #{e.message}" }
+      end
+
+      def backend
+        SmartBrain.storage_backend
+      end
+
+      # --- knowledge lifecycle (Stage-1) ---
+      def distill(session_id:, statement:, content: nil, tier:, supporting_refs: [], **opts)
+        SmartBrain.distill(session_id: session_id, statement: statement, content: content,
+                           tier: tier, supporting_refs: supporting_refs, **opts)
+      end
+
+      def gate(memory_item_id:, **opts)
+        SmartBrain.gate(memory_item_id: memory_item_id, **opts)
+      end
+
+      def promote(memory_item_id:, verification_refs:, reason:, **opts)
+        SmartBrain.promote(memory_item_id: memory_item_id, verification_refs: verification_refs,
+                           reason: reason, **opts)
+      end
+
+      def demote(memory_item_id:, evidence_refs:, reason:, reason_type:, **opts)
+        SmartBrain.demote(memory_item_id: memory_item_id, evidence_refs: evidence_refs,
+                          reason: reason, reason_type: reason_type, **opts)
+      end
+
+      def retract(memory_item_id:, evidence_refs:, reason:, **opts)
+        SmartBrain.retract(memory_item_id: memory_item_id, evidence_refs: evidence_refs, reason: reason, **opts)
+      end
+
+      def promote_to_scope(**args)
+        SmartBrain.promote_to_scope(**args)
+      end
+
+      def promotion_lineage(memory_item_id:, **opts)
+        SmartBrain.promotion_lineage(memory_item_id: memory_item_id, **opts)
+      end
+
+      def knowledge_events(memory_item_id:, **opts)
+        SmartBrain.knowledge_events(memory_item_id: memory_item_id, **opts)
+      end
+
+      # --- knowledge graph ---
+      def kg_add(session_id:, subject:, predicate:, object:, **opts)
+        SmartBrain.kg_add(session_id: session_id, subject: subject, predicate: predicate, object: object, **opts)
+      end
+
+      def kg_query(session_id:, **opts)
+        SmartBrain.kg_query(session_id: session_id, **opts)
+      end
+
+      def kg_timeline(session_id:, subject:, **opts)
+        SmartBrain.kg_timeline(session_id: session_id, subject: subject, **opts)
+      end
+
+      def kg_invalidate(edge_id:, reason: nil, **opts)
+        SmartBrain.kg_invalidate(edge_id: edge_id, reason: reason, **opts)
+      end
+
+      def kg_stats(session_id:, **opts)
+        SmartBrain.kg_stats(session_id: session_id, **opts)
+      end
+
+      # --- fact-check / briefing ---
+      def fact_check(session_id:, text:, **opts)
+        SmartBrain.fact_check(session_id: session_id, text: text, **opts)
+      end
+
+      def brief(session_id:, query: nil, **opts)
+        SmartBrain.brief(session_id: session_id, query: query, **opts)
+      end
+
+      def wake_up(session_id:, **opts)
+        SmartBrain.wake_up(session_id: session_id, **opts)
+      end
+
+      def resume(query:)
+        SmartBrain.resume(query: query)
+      end
+    end
+  end
+end

data/lib/smart_brain/support/levenshtein.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Support
+    # Pure-Ruby Levenshtein edit distance (no native dep). Used by FactCheck
+    # for SimilarNameConflict detection.
+    module Levenshtein
+      module_function
+
+      def distance(a, b)
+        a = a.to_s
+        b = b.to_s
+        return b.length if a.empty?
+        return a.length if b.empty?
+
+        # Iterative two-row DP.
+        previous = (0..b.length).to_a
+        current = Array.new(b.length + 1, 0)
+        (1..a.length).each do |i|
+          current[0] = i
+          (1..b.length).each do |j|
+            cost = a[i - 1] == b[j - 1] ? 0 : 1
+            current[j] = [
+              previous[j] + 1,       # deletion
+              current[j - 1] + 1,    # insertion
+              previous[j - 1] + cost # substitution
+            ].min
+          end
+          previous, current = current, previous
+        end
+        previous[b.length]
+      end
+    end
+  end
+end