dsh-biocore 0.1.3 → 0.1.4

package/lib/index.js

@@ -106,6 +106,27 @@ function normalizeEmbedding(value) {
   }
 }
 
+export const RERANK_DEFAULTS = Object.freeze({
+  enabled: false,
+  base_url: 'https://api.jina.ai/v1',
+  model: 'jina-reranker-v2-base-multilingual',
+  api_key: '',
+  top_n: 20,
+})
+
+function normalizeRerank(value) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+  const rawTop = Number(source.top_n)
+  const top = Number.isFinite(rawTop) ? Math.max(1, Math.min(100, Math.round(rawTop))) : RERANK_DEFAULTS.top_n
+  return {
+    enabled: source.enabled === true,
+    base_url: String(source.base_url || RERANK_DEFAULTS.base_url).trim().slice(0, 2000),
+    model: String(source.model || RERANK_DEFAULTS.model).trim().slice(0, 200),
+    api_key: typeof source.api_key === 'string' ? source.api_key.trim().slice(0, 4000) : '',
+    top_n: top,
+  }
+}
+
 /** GET must never leak the plaintext key. */
 export function maskApiKey(key) {
   const text = String(key || '')
@@ -114,23 +135,14 @@ export function maskApiKey(key) {
   return text.slice(0, 2) + '••••••' + text.slice(-2)
 }
 
-function readStoredSettings(dataDir) {
-  return readConfig(dataDir)
-}
-
-function writeSettingsFile(file, embedding, expression) {
-  mkdirSync(dirname(file), { recursive: true })
-  writeFileSync(file, JSON.stringify({ embedding, expression }, null, 2) + '\n', {
-    encoding: 'utf8',
-    mode: 0o600,
-  })
-  try { chmodSync(file, 0o600) } catch { /* Windows may ignore POSIX modes */ }
-}
-
 function maskedEmbedding(embedding) {
   return Object.assign({}, embedding, { api_key: maskApiKey(embedding.api_key) })
 }
 
+function maskedRerank(rerank) {
+  return Object.assign({}, rerank, { api_key: maskApiKey(rerank.api_key) })
+}
+
 function defaultEmbedding() {
   const embedding = emptyEmbedding()
   embedding.mode = 'auto'
@@ -144,16 +156,41 @@ function storedEmbedding(stored) {
   return embedding
 }
 
-/** GET/POST /api/biocore/settings: embedding + expression. */
+/** Full config.json projection with defaults for all three sections. */
+export function readFullConfig(dataDir) {
+  let doc = null
+  try {
+    doc = JSON.parse(readFileSync(join(String(dataDir || '').trim(), SETTINGS_FILE_NAME), 'utf8'))
+  } catch { doc = null }
+  const source = doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : {}
+  return {
+    embedding: storedEmbedding(source),
+    rerank: normalizeRerank(source.rerank),
+    expression: normalizeExpression(source.expression),
+  }
+}
+
+function writeFullConfig(file, config) {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify({
+    embedding: config.embedding,
+    rerank: config.rerank,
+    expression: config.expression,
+  }, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 })
+  try { chmodSync(file, 0o600) } catch { /* Windows may ignore POSIX modes */ }
+}
+
+/** GET/POST /api/biocore/settings: embedding + rerank + expression. */
 export async function handleSettings(req, res, dataDir) {
   const paths = settingsPaths(dataDir)
   const method = String((req && req.method) || 'GET').toUpperCase()
   if (method === 'GET') {
-    const stored = readStoredSettings(paths.dir)
+    const config = readFullConfig(paths.dir)
     return sendJson(res, 200, {
       ok: true,
-      embedding: maskedEmbedding(storedEmbedding(stored)),
-      expression: Object.assign({}, EXPRESSION_DEFAULTS, stored.expression || {}),
+      embedding: maskedEmbedding(config.embedding),
+      rerank: maskedRerank(config.rerank),
+      expression: config.expression,
       restart_required: false,
     })
   }
@@ -172,33 +209,133 @@ export async function handleSettings(req, res, dataDir) {
   if (body.confirm !== true) {
     return sendJson(res, 400, { ok: false, reason: 'confirm_required' })
   }
-  const stored = readStoredSettings(paths.dir)
-  let embedding = storedEmbedding(stored)
-  let expression = Object.assign({}, EXPRESSION_DEFAULTS, stored.expression || {})
+  const config = readFullConfig(paths.dir)
   const hasEmbedding = body.embedding && typeof body.embedding === 'object'
+  const hasRerank = body.rerank && typeof body.rerank === 'object'
   const hasExpression = body.expression && typeof body.expression === 'object'
-  if (!hasEmbedding && !hasExpression) {
+  if (!hasEmbedding && !hasRerank && !hasExpression) {
     return sendJson(res, 400, { ok: false, reason: 'no_settings' })
   }
   if (hasEmbedding) {
     const raw = body.embedding
-    embedding = normalizeEmbedding(raw)
+    const embedding = normalizeEmbedding(raw)
     if (!embedding.mode) {
       return sendJson(res, 400, { ok: false, reason: 'bad_mode', allowed: Array.from(EMBEDDING_MODES) })
     }
-    if (!('api_key' in raw)) embedding.api_key = storedEmbedding(stored).api_key
+    if (!('api_key' in raw) || String(raw.api_key || '').startsWith('••')) {
+      embedding.api_key = config.embedding.api_key
+    }
+    config.embedding = embedding
   }
-  if (hasExpression) expression = normalizeExpression(body.expression)
-  writeSettingsFile(paths.file, embedding, expression)
+  if (hasRerank) {
+    const raw = body.rerank
+    const rerank = normalizeRerank(raw)
+    if (!('api_key' in raw) || String(raw.api_key || '').startsWith('••')) {
+      rerank.api_key = config.rerank.api_key
+    }
+    config.rerank = rerank
+  }
+  if (hasExpression) config.expression = normalizeExpression(body.expression)
+  writeFullConfig(paths.file, config)
   return sendJson(res, 200, {
     ok: true,
-    embedding: maskedEmbedding(embedding),
-    expression,
+    embedding: maskedEmbedding(config.embedding),
+    rerank: maskedRerank(config.rerank),
+    expression: config.expression,
     restart_required: true,
     hint: '重启 BioCore 生效',
   })
 }
 
+function notConfigured(kind, detail) {
+  return { ok: false, kind, reason: 'not_configured', detail }
+}
+
+/** One minimal API call; never returns or logs the plaintext key. */
+export async function testApiConnection(kind, config, options) {
+  const opts = options || {}
+  const fetchImpl = typeof opts.fetchImpl === 'function' ? opts.fetchImpl : globalThis.fetch
+  const timeoutMs = Number(opts.timeoutMs) || 6000
+  if (typeof fetchImpl !== 'function') return { ok: false, kind, reason: 'fetch_unavailable' }
+  let url = ''
+  let payload = null
+  if (kind === 'embedding') {
+    const embedding = config && config.embedding ? config.embedding : {}
+    if (embedding.mode === 'off' || embedding.mode === 'local') {
+      return notConfigured(kind, 'embedding mode is ' + embedding.mode)
+    }
+    if (!embedding.base_url || !embedding.model || !embedding.api_key) {
+      return notConfigured(kind, 'embedding base_url/model/api_key missing')
+    }
+    url = String(embedding.base_url).replace(/\/+$/, '') + '/embeddings'
+    payload = { model: embedding.model, input: 'ping' }
+  } else if (kind === 'rerank') {
+    const rerank = config && config.rerank ? config.rerank : {}
+    if (rerank.enabled !== true) return notConfigured(kind, 'rerank disabled')
+    if (!rerank.base_url || !rerank.model || !rerank.api_key) {
+      return notConfigured(kind, 'rerank base_url/model/api_key missing')
+    }
+    url = String(rerank.base_url).replace(/\/+$/, '') + '/rerank'
+    payload = {
+      model: rerank.model,
+      query: 'ping',
+      documents: ['ping'],
+      top_n: 1,
+    }
+  } else {
+    return { ok: false, kind: String(kind || ''), reason: 'bad_kind' }
+  }
+  const key = kind === 'embedding'
+    ? String(config.embedding.api_key || '')
+    : String(config.rerank.api_key || '')
+  const controller = typeof AbortController === 'function' ? new AbortController() : null
+  const timer = controller ? setTimeout(() => controller.abort(), timeoutMs) : null
+  const started = Date.now()
+  try {
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: 'Bearer ' + key },
+      body: JSON.stringify(payload),
+      signal: controller ? controller.signal : undefined,
+    })
+    const status = Number(response && response.status) || 0
+    const elapsed = Date.now() - started
+    if (response && response.ok) {
+      return { ok: true, kind, status_code: status, elapsed_ms: elapsed }
+    }
+    return { ok: false, kind, reason: 'http_error', status_code: status, elapsed_ms: elapsed }
+  } catch (error) {
+    const name = error && error.name ? String(error.name) : ''
+    return {
+      ok: false,
+      kind,
+      reason: name === 'AbortError' ? 'timeout' : 'network_error',
+      elapsed_ms: Date.now() - started,
+    }
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+/** POST /api/biocore/settings/test {kind:'embedding'|'rerank'}. */
+export async function handleSettingsTest(req, res, options) {
+  const opts = options || {}
+  const dataDir = opts.dataDir
+  const method = String((req && req.method) || 'POST').toUpperCase()
+  if (method !== 'POST') return sendJson(res, 405, { ok: false, reason: 'method_not_allowed' })
+  let body = null
+  try { body = await readJsonBody(req) } catch (error) {
+    return sendJson(res, 400, { ok: false, reason: (error && error.reason) || 'bad_payload' })
+  }
+  const kind = String(body && body.kind || '').trim()
+  if (kind !== 'embedding' && kind !== 'rerank') {
+    return sendJson(res, 400, { ok: false, reason: 'bad_kind', allowed: ['embedding', 'rerank'] })
+  }
+  const config = readFullConfig(dataDir)
+  const result = await testApiConnection(kind, config, { fetchImpl: opts.fetchImpl })
+  return sendJson(res, 200, result)
+}
+
 const PERSONA_PREVIEW_FIELDS = [
   ['E', '外向', 2],
   ['A', '宜人', 2],
@@ -692,6 +829,12 @@ export function apply(ctx, config) {
           path: SETTINGS_ROUTE_PATH,
           handler: (req, res) => handleSettings(req, res, dataDir),
         }))
+        // API connection test (embedding / rerank); never logs the key.
+        keep(webServer.register({
+          kind: 'exact',
+          path: SETTINGS_ROUTE_PATH + '/test',
+          handler: (req, res) => handleSettingsTest(req, res, { dataDir }),
+        }))
       })
     }
   } catch { /* headless */ }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-biocore",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "BioCore DSH UI: per-session state tab, standalone instrument panel, /api/biocore/state, session/event one_turn updates, /bio sync.",
   "main": "lib/index.js",

package/python/biocore_runtime/pipeline.py

@@ -91,6 +91,11 @@ try:
 except Exception:  # pragma: no cover
     _intero_core = None
 
+try:
+    from biocore_runtime import rerank as _rerank_mod
+except Exception:  # pragma: no cover
+    _rerank_mod = None
+
 try:  # self-layer modules (all pure; optional so a stripped checkout still runs)
     from biocore_model import x_directives as _x_directives
     from biocore_model import self_intent as _self_intent
@@ -634,6 +639,26 @@ def tool_call(name, args, store, session_id=None):
             row["score"] = score
             rows.append(row)
         rows.sort(key=lambda row: (-row["score"], -_num(row.get("ts"), 0.0)))
+        rerank_config = args.get("rerank_config")
+        if (_rerank_mod is not None and isinstance(rerank_config, dict)
+                and rerank_config.get("rerank_enabled")):
+            try:
+                reranked = _rerank_mod.rerank_documents(
+                    query, [row.get("text", "") for row in rows], rerank_config)
+                if reranked:
+                    seen = set()
+                    ordered = []
+                    for item in reranked:
+                        index = int(item.get("index", -1))
+                        if 0 <= index < len(rows) and index not in seen:
+                            seen.add(index)
+                            ordered.append(rows[index])
+                    for index, row in enumerate(rows):
+                        if index not in seen:
+                            ordered.append(row)
+                    rows = ordered
+            except Exception:
+                pass  # rerank is optional; recall keeps the local order
         return {"ok": True, "count": min(limit, len(rows)),
                 "results": rows[:limit]}
     target = str(args.get("id") or args.get("query") or "").strip()
@@ -1835,6 +1860,23 @@ def dispatch(action, payload=None):
             current = normalize_switches(data.get("switches"))
             current[key] = bool(data.get("value"))
             return {"ok": True, "switches": current}
+        if action == "recall":
+            query = str(data.get("query") or "").strip()
+            documents = data.get("documents")
+            if not isinstance(documents, list):
+                documents = data.get("docs") if isinstance(data.get("docs"), list) else []
+            fallback = [{"index": index,
+                         "document": str((item.get("text") or item.get("document"))
+                                         if isinstance(item, dict) else (item or "")).strip()}
+                        for index, item in enumerate(documents)]
+            if _rerank_mod is None:
+                return {"ok": True, "reranked": False, "results": fallback,
+                        "reason": "unavailable"}
+            config = data.get("config") if isinstance(data.get("config"), dict) else data
+            result = _rerank_mod.rerank_documents(query, documents, config)
+            if not result:
+                return {"ok": True, "reranked": False, "results": fallback}
+            return {"ok": True, "reranked": True, "results": result}
         if action == "trace":
             session_id = str(data.get("session_id") or "").strip()
             if not session_id:

package/python/biocore_runtime/rerank.py

@@ -0,0 +1,201 @@
+# -*- coding: utf-8 -*-
+"""Optional remote cross-encoder rerank (stdlib only, silent degradation).
+
+Config keys (all optional, defaults shown):
+  rerank_enabled  False
+  rerank_base_url ""
+  rerank_model    ""
+  rerank_api_key  ""
+  rerank_timeout  8.0 seconds
+  rerank_top_n    20
+
+Two common wire protocols are tried automatically:
+  POST {base_url}/rerank      {"model", "query", "documents", "top_n"}
+  POST {base_url}/v1/rerank   same payload
+
+A disabled call, missing config, timeout, non-2xx response, bad JSON or an
+invalid result list returns None and records a short reason; callers keep the
+original ordering. Only stdlib urllib is used.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import math
+import socket
+import urllib.error
+import urllib.request
+
+logger = logging.getLogger(__name__)
+
+DEFAULTS = {
+    "rerank_enabled": False,
+    "rerank_base_url": "",
+    "rerank_model": "",
+    "rerank_api_key": "",
+    "rerank_timeout": 8.0,
+    "rerank_top_n": 20,
+}
+
+
+def _num(value, default=0.0):
+    try:
+        number = float(value)
+    except Exception:
+        return float(default)
+    return number if math.isfinite(number) else float(default)
+
+
+def _as_bool(value, default=False):
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in ("1", "true", "yes", "on"):
+            return True
+        if lowered in ("0", "false", "no", "off", ""):
+            return False
+    return bool(default)
+
+
+def normalize_config(config=None):
+    """Merge caller config with defaults and clamp timeout/top_n."""
+    data = config if isinstance(config, dict) else {}
+    out = dict(DEFAULTS)
+    out["rerank_enabled"] = _as_bool(data.get("rerank_enabled"), False)
+    for key in ("rerank_base_url", "rerank_model", "rerank_api_key"):
+        out[key] = str(data.get(key) or "").strip()
+    timeout = _num(data.get("rerank_timeout"), DEFAULTS["rerank_timeout"])
+    out["rerank_timeout"] = max(0.1, min(60.0, timeout))
+    top_n = int(_num(data.get("rerank_top_n"), DEFAULTS["rerank_top_n"]))
+    out["rerank_top_n"] = max(1, min(1000, top_n))
+    return out
+
+
+def _document_text(item):
+    if isinstance(item, dict):
+        return str(item.get("text") or item.get("document") or "").strip()
+    return str(item or "").strip()
+
+
+def _candidate_urls(base_url):
+    base = str(base_url or "").strip().rstrip("/")
+    if not base:
+        return []
+    if base.endswith("/rerank"):
+        return [base]
+    urls = [base + "/rerank"]
+    if not base.endswith("/v1"):
+        urls.append(base + "/v1/rerank")
+    return urls
+
+
+def _urllib_transport(url, payload, timeout, headers):
+    request = urllib.request.Request(
+        url, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+        headers=headers, method="POST")
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        status = int(getattr(response, "status", 200) or 200)
+        body = response.read()
+    return status, body
+
+
+def _notify(callback, reason):
+    try:
+        logger.info("[rerank] fallback: %s", reason)
+    except Exception:
+        pass
+    if callable(callback):
+        try:
+            callback(reason)
+        except Exception:
+            pass
+
+
+def rerank_documents(query, documents, config=None, transport=None,
+                     on_reason=None):
+    """Return [{index, document, relevance_score}] sorted/truncated, or None."""
+    cfg = normalize_config(config)
+    if not cfg["rerank_enabled"]:
+        _notify(on_reason, "disabled")
+        return None
+    if not cfg["rerank_base_url"] or not cfg["rerank_model"]:
+        _notify(on_reason, "missing_config")
+        return None
+    text = str(query or "").strip()
+    if not text:
+        _notify(on_reason, "empty_query")
+        return None
+    text_docs = []
+    for index, item in enumerate(documents or []):
+        content = _document_text(item)
+        if content:
+            text_docs.append((index, content))
+    if not text_docs:
+        _notify(on_reason, "empty_documents")
+        return None
+    top_n = min(cfg["rerank_top_n"], len(text_docs))
+    payload = {
+        "model": cfg["rerank_model"],
+        "query": text,
+        "documents": [content for _index, content in text_docs],
+        "top_n": top_n,
+    }
+    headers = {"Content-Type": "application/json"}
+    if cfg["rerank_api_key"]:
+        headers["Authorization"] = "Bearer " + cfg["rerank_api_key"]
+    call = transport or _urllib_transport
+    reason = "failed"
+    for url in _candidate_urls(cfg["rerank_base_url"]):
+        try:
+            status, body = call(url, payload, cfg["rerank_timeout"], headers)
+        except (TimeoutError, socket.timeout):
+            _notify(on_reason, "timeout")
+            return None
+        except urllib.error.HTTPError as error:
+            reason = "http_%s" % getattr(error, "code", "error")
+            continue
+        except Exception:
+            _notify(on_reason, "request_failed")
+            return None
+        try:
+            status = int(status)
+        except Exception:
+            status = 0
+        if status < 200 or status >= 300:
+            reason = "http_%s" % status
+            continue
+        try:
+            if isinstance(body, bytes):
+                body = body.decode("utf-8", "replace")
+            data = json.loads(body)
+        except Exception:
+            reason = "bad_json"
+            continue
+        results = data.get("results") if isinstance(data, dict) else None
+        if not isinstance(results, list):
+            reason = "bad_results"
+            continue
+        parsed = []
+        by_index = dict(text_docs)
+        for item in results:
+            if not isinstance(item, dict):
+                continue
+            try:
+                index = int(item.get("index"))
+                score = float(item.get("relevance_score"))
+            except Exception:
+                continue
+            if index not in by_index or not math.isfinite(score):
+                continue
+            parsed.append({"index": index, "document": by_index[index],
+                           "relevance_score": round(score, 6)})
+        if not parsed:
+            reason = "empty_results"
+            continue
+        parsed.sort(key=lambda row: (-row["relevance_score"], row["index"]))
+        return parsed[:top_n]
+    _notify(on_reason, reason)
+    return None

package/python/mindbase/__init__.py

@@ -0,0 +1,18 @@
+"""mindbase: a layered, paper-grounded base for a human-like agent.
+
+Layers:
+  L0 substrate/noise  -> noise.py
+  L1 drives/allostasis -> drives.py, clock.py
+  L2 affect/appraisal  -> appraisal.py, affect.py
+  L3 attention/WM      -> attention.py, working_memory.py
+  L4 memory            -> memory.py
+  L5 social/persona/self/meta/autonomy -> social.py, persona.py, self_model.py, meta.py, autonomy.py
+  L6 expression        -> (not implemented; LLM adapter later)
+"""
+
+from .config import MindConfig
+from .actions import Action
+from .types import Event, Appraisal, Outcome, Feedback, LLMRequest
+from .engine import MindBase
+
+__all__ = ["MindConfig", "Event", "Appraisal", "Outcome", "LLMRequest", "Feedback", "Action", "MindBase"]

package/python/mindbase/__main__.py

@@ -0,0 +1,3 @@
+from .demo import main
+
+main()

package/python/mindbase/actions.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+ACTION_KINDS = (
+    "communicate",
+    "approach",
+    "avoid",
+    "explore",
+    "rest",
+    "repair",
+    "protect",
+    "seek_help",
+    "give_help",
+    "withdraw",
+    "appraise",
+    "forage",
+    "drink",
+    "heal",
+)
+MODALITIES = ("text", "voice", "gesture", "none")
+
+STYLE_TO_KIND = {
+    "speak": "communicate",
+    "silence": "withdraw",
+    "ask": "seek_help",
+    "repair": "repair",
+    "avoid": "avoid",
+    "approach": "approach",
+    "appraise": "appraise",
+    "forage": "forage",
+    "rest": "rest",
+    "socialize": "approach",
+    "drink": "drink",
+    "heal": "heal",
+}
+
+
+def kind_for_style(style: str) -> str:
+    return STYLE_TO_KIND.get(str(style or "").lower(), "communicate")
+
+
+@dataclass
+class Action:
+    """A domain-general action, not a chat token.
+
+    kind: what the base does
+    modality: how it is expressed (chat is only communicate/text)
+    style: optional sub-style for language (speak/repair/avoid...)
+    """
+    kind: str = "communicate"
+    modality: str = "text"
+    style: str = ""
+
+    def as_dict(self) -> dict:
+        return {"kind": self.kind, "modality": self.modality, "style": self.style}

package/python/mindbase/active_inference.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Dict
+
+
+def expected_free_energy(load: float, pred_err: float, social: float, energy: float, action: str, activity: float = 0.0) -> float:
+    """Expected free energy for a binary action (speak/silence).
+
+    risk     = expected allostatic deviation after action
+    ambiguity= self-prediction uncertainty
+    cost     = action cost
+    """
+    if action == "speak":
+        risk = max(0.0, load - 0.10 * social)
+        cost = 0.05 + 0.05 * max(0.0, 0.3 - energy) + 0.10 * max(0.0, float(activity))
+    else:
+        risk = load + 0.08 * social
+        cost = 0.02
+    ambiguity = pred_err * pred_err
+    return risk + 0.5 * ambiguity + cost
+
+
+def choose(load: float, pred_err: float, social: float, energy: float) -> Dict[str, object]:
+    speak = expected_free_energy(load, pred_err, social, energy, "speak")
+    silence = expected_free_energy(load, pred_err, social, energy, "silence")
+    action = "speak" if speak < silence else "silence"
+    return {"action": action, "efe_speak": round(speak, 4), "efe_silence": round(silence, 4)}
+
+
+class ActiveInference:
+    def __init__(self):
+        self.w_risk = 1.0
+        self.w_amb = 0.5
+        self.w_cost = 1.0
+        self.lr = 0.005
+
+    def choose(self, load: float, pred_err: float, social: float, energy: float, activity: float = 0.0, valence: float = 0.0):
+        def efe(action: str) -> float:
+            if action == "speak":
+                risk = max(0.0, load - 0.10 * social - 0.15 * float(valence))
+                cost = 0.05 + 0.05 * max(0.0, 0.3 - energy) + 0.10 * max(0.0, float(activity))
+            else:
+                risk = load + 0.08 * social + 0.10 * float(valence)
+                cost = 0.02
+            return self.w_risk * risk + self.w_amb * pred_err * pred_err + self.w_cost * cost
+        s, q = efe("speak"), efe("silence")
+        return {"action": "speak" if s < q else "silence", "efe_speak": round(s, 4), "efe_silence": round(q, 4)}
+
+    def learn(self, rpe: float, load: float, pred_err: float) -> None:
+        self.w_risk = max(0.1, min(3.0, self.w_risk - self.lr * float(rpe) * float(load)))
+        self.w_amb = max(0.05, min(3.0, self.w_amb - self.lr * float(rpe) * float(pred_err) ** 2))
+
+    def snapshot(self) -> dict:
+        return {"w_risk": round(self.w_risk, 4), "w_amb": round(self.w_amb, 4), "w_cost": self.w_cost}