dsh-biocore 0.1.3 → 0.1.5

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,44 @@ 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),
+    sanitize_reply: source.sanitize_reply !== false,
+  }
+}
+
+function writeFullConfig(file, config) {
+  mkdirSync(dirname(file), { recursive: true })
+  writeFileSync(file, JSON.stringify({
+    embedding: config.embedding,
+    rerank: config.rerank,
+    expression: config.expression,
+    sanitize_reply: config.sanitize_reply !== false,
+  }, 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,
+      sanitize_reply: config.sanitize_reply !== false,
       restart_required: false,
     })
   }
@@ -172,33 +212,136 @@ 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) {
+  const hasSanitize = typeof body.sanitize_reply === 'boolean'
+  if (!hasEmbedding && !hasRerank && !hasExpression && !hasSanitize) {
     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)
+  if (hasSanitize) config.sanitize_reply = body.sanitize_reply === true
+  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,
+    sanitize_reply: config.sanitize_reply !== false,
     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 +835,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/lib/modules/core-turn.js

@@ -26,6 +26,11 @@ import { applyGateText, assistantTextOf } from './safety-gate.js'
 import { defaultStoreDir } from './trace.js'
 import { runtimeAction, runTurn } from '../py-bridge.js'
 import { EXPRESSION_DEFAULTS, readExpressionSettings } from './expression-config.js'
+import {
+  readSanitizeReplySetting,
+  sanitizeReply,
+  sanitizeReplyEnabled,
+} from './sanitize-reply.js'
 
 export const TURN_CONTEXT_NAME = 'biocore-expression-turn'
 export const TURN_CONTEXT_ORDER = -190
@@ -118,6 +123,7 @@ export function turnEndPayload(options) {
     store: opts.store || defaultStoreDir(),
     capture: false,
     memoryEnabled: false,
+    sanitize_reply: opts.sanitizeReply !== false,
     diagnostics,
   }, diagnostics, {
     modules_trace: diagnostics.modules,
@@ -135,6 +141,9 @@ export function makeCoreSessionListener(options) {
   const getExpression = typeof opts.getExpression === 'function'
     ? opts.getExpression
     : () => readExpressionSettings(stateDir)
+  const getSanitizeReply = typeof opts.getSanitizeReply === 'function'
+    ? opts.getSanitizeReply
+    : () => readSanitizeReplySetting(stateDir)
   const store = opts.store || defaultStoreDir()
   const log = typeof opts.log === 'function' ? opts.log : (line) => {
     try { console.error(line) } catch { /* noop */ }
@@ -186,9 +195,11 @@ export function makeCoreSessionListener(options) {
         }).catch(() => null)
         return
       }
-      // assistant/message: gate + trace via one turn_end call.
+      // assistant/message: sanitize -> gate + trace via one turn_end call.
       const original = assistantTextOf(event)
       if (!original) return
+      const sanitizeEnabled = sanitizeReplyEnabled(getSanitizeReply())
+      const cleaned = sanitizeEnabled ? sanitizeReply(original) : original
       const userText = lastUser.get(sessionId) || ''
       void (async () => {
         try {
@@ -198,11 +209,12 @@ export function makeCoreSessionListener(options) {
           const state = read && !read.error && !read.missing ? read.state : {}
           const payload = turnEndPayload({
             sessionId,
-            assistantText: original,
+            assistantText: cleaned,
             userText,
             switches,
             store,
             state,
+            sanitizeReply: sanitizeEnabled,
           })
           const result = await runAction('turn_end', payload)
           if (!result || result.ok !== true) return
@@ -216,6 +228,9 @@ export function makeCoreSessionListener(options) {
               + ' blocked=' + (gate.blocked === true ? '1' : '0')
               + ' rule=' + stringId(gate.rule || '')
               + ' chars=' + original.length + '->' + gate.text.length)
+          } else if (cleaned !== original) {
+            // No gate rewrite: still write the sanitized text back.
+            applyGateText(event, cleaned)
           }
           if (result.trace_file) {
             logLine(log, CORE_TRACE_PREFIX + ' session=' + sessionId

package/lib/modules/sanitize-reply.js

@@ -0,0 +1,60 @@
+/** Strip BioCore output markers from assistant replies (task-223).
+ *
+ * Removes:
+ *   - <bc>...</bc> and <biocore>...</biocore> blocks (also unclosed to EOL/EOS)
+ *   - bare compact JSON objects that only carry e/i[/n] keys
+ *   - extra whitespace; empty result stays empty (never falls back to input)
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const DEFAULT_SANITIZE_REPLY = true
+
+const TAG_RE = /<(bc|biocore)\b[^>]*>/gi
+const BARE_JSON_RE = /\{\s*"e"\s*:\s*"[^"\\]*(?:\\.[^"\\]*)*"\s*,\s*"i"\s*:\s*-?\d+(?:\.\d+)?(?:\s*,\s*"n"\s*:\s*-?\d+(?:\.\d+)?)?\s*\}/g
+
+function stripClosedTags(text) {
+  return String(text)
+    .replace(/<bc\b[^>]*>[\s\S]*?<\/bc\s*>/gi, '')
+    .replace(/<biocore\b[^>]*>[\s\S]*?<\/biocore\s*>/gi, '')
+}
+
+function stripUnclosedTags(text) {
+  // Until line end or a Chinese/ASCII sentence terminator; the terminator stays.
+  return String(text)
+    .replace(/<bc\b[^>]*>[\s\S]*?(?:[\n。！？!?]|$)/gi, '')
+    .replace(/<biocore\b[^>]*>[\s\S]*?(?:[\n。！？!?]|$)/gi, '')
+}
+
+function normalizeWhitespace(text) {
+  return String(text)
+    .replace(/[ \t]{2,}/g, ' ')
+    .replace(/[ \t]*\n[ \t]*/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+/** Main entry: returns the cleaned reply (may be ''); never reverts to input. */
+export function sanitizeReply(text, options) {
+  const opts = options || {}
+  if (opts.enabled === false) return String(text == null ? '' : text)
+  const source = String(text == null ? '' : text)
+  let out = stripClosedTags(source)
+  out = stripUnclosedTags(out)
+  out = out.replace(BARE_JSON_RE, '')
+  return normalizeWhitespace(out)
+}
+
+/** Config.json top-level flag: only an explicit false disables cleaning. */
+export function readSanitizeReplySetting(dataDir) {
+  try {
+    const doc = JSON.parse(readFileSync(join(String(dataDir || '').trim(), 'config.json'), 'utf8'))
+    if (doc && typeof doc === 'object' && doc.sanitize_reply === false) return false
+  } catch { /* missing/bad config -> default on */ }
+  return DEFAULT_SANITIZE_REPLY
+}
+
+/** Payload helper: sanitize_reply defaults to true unless explicitly false. */
+export function sanitizeReplyEnabled(value) {
+  return value !== false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-biocore",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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"]