brainiac-cli 0.20.44__tar.gz → 0.20.45__tar.gz

{brainiac_cli-0.20.44/src/brainiac_cli.egg-info → brainiac_cli-0.20.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainiac-cli
-Version: 0.20.44
+Version: 0.20.45
 Summary: Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index).
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/Autopsias/brainiac

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
 # check. The IMPORT package stays `brain` and the console script stays
 # `brain` — only the distribution/project name changes.
 name = "brainiac-cli"
-version = "0.20.44"
+version = "0.20.45"
 description = "Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index)."
 readme = "README.md"
 license = "Apache-2.0"

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/_assets/scripts/brain-brief.sh

@@ -61,6 +61,21 @@ if [ -z "$BRAIN_BIN" ]; then
   exit 1
 fi
 
+# YIELD TO THE NIGHTLY MAIL RUN (2026-10-19). Both do model work, and the
+# machine runs at most $BRAIN_MODEL_SLOTS (2) model processes at once. On
+# run374 an hourly maintain ran 02:06-03:04 across the run's grounding window
+# and 58 of 72 sender lookups timed out (0 of 122 the night before). The night
+# runs its own broker after its child exits, so skipping an hour loses
+# nothing: the next hourly run catches up. A hung night also stops this job;
+# the WAT-01 stale-feed alert names it after 2 days.
+# ponytail: process-name match, a pid lock if the night ever runs under
+# another name.
+YIELD_TO="${BRAIN_BRIEF_YIELD_TO:-tools/cos_nightly.sh}"
+if pgrep -f "$YIELD_TO" >/dev/null 2>&1; then
+  echo "=== brain-daily-brief / brain-nightly $(date -u +%Y-%m-%dT%H:%M:%SZ) === SKIP: the nightly mail run is running ($YIELD_TO); next hour catches up" >> "$LOG"
+  exit 0
+fi
+
 # The RUN VALIDATOR needs the mutation toolchain, and the wheel does not carry
 # it (2026-08-22). `brain.cos_runverify.check_plan_binding` imports
 # `cos_mutate.load_frozen_plan` to re-hash a run's frozen plan — one definition

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/_version.py

@@ -9,4 +9,4 @@ pip-installed host, importlib.metadata stays primary; brain/__init__.py reads
 this file only as the fallback before 0.0.0+unknown.
 """
 
-__version__ = "0.20.44"
+__version__ = "0.20.45"

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/embed.py

@@ -50,18 +50,21 @@ ARCTIC_FULL_DIM = 768
 MRL_DIM = 256
 
 
+# Measured 2026-10-19: 4 threads match the all-cores wall time at ~40% of the CPU.
+_DEFAULT_THREADS = 4
+
+
 def _ort_threads() -> int | None:
     """Intra-op thread count for the ONNX session (S11 speed fix).
 
-    Default: all physical cores (Apple Silicon has no SMT, so logical ==
-    physical — on the M4 Pro that is 12). Saturating the batch dimension
-    across cores is the biggest ORT knob for bulk embedding throughput.
+    Default: 4 threads (capped at the core count). More threads spin without
+    cutting wall time; raise it for bulk work.
     Override via ``$BRAIN_EMBED_THREADS``."""
     raw = os.environ.get("BRAIN_EMBED_THREADS")
     if raw and raw.strip().isdigit():
         return int(raw)
     try:
-        return os.cpu_count() or None
+        return min(_DEFAULT_THREADS, os.cpu_count() or _DEFAULT_THREADS)
     except Exception:
         return None
 

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/embed_onnx.py

@@ -8,6 +8,8 @@ import sys as sys
 from dataclasses import dataclass
 from typing import Sequence
 
+from .model_slot import model_slot
+
 # --- Direct-ONNX models (DIST-01: eliminates fastembed) ---------------------
 # Each model owns its pooling, prefixes, dimension and exact file. Keeping the
 # contract here prevents a future model swap from inheriting another model's
@@ -255,9 +257,10 @@ class OnnxEmbedder:
                 t = _ort_threads()
                 if t:
                     so.intra_op_num_threads = t
-                self._sess = ort.InferenceSession(
-                    onnx_path, sess_options=so, providers=_ort_providers()
-                )
+                with model_slot():  # loading peaks well above the weights' size
+                    self._sess = ort.InferenceSession(
+                        onnx_path, sess_options=so, providers=_ort_providers()
+                    )
                 self._in_names = [i.name for i in self._sess.get_inputs()]
                 self._tok = Tokenizer.from_file(os.path.join(base, "tokenizer.json"))
                 # Truncate to the engine's calibrated chunk window BEFORE padding.
@@ -387,7 +390,8 @@ class OnnxEmbedder:
                 feed[nm] = am
             elif "token_type" in low:
                 feed[nm] = np.zeros_like(ii)
-        hidden = self._sess.run(None, feed)[0]  # [batch, seq, dim] float32
+        with model_slot():
+            hidden = self._sess.run(None, feed)[0]  # [batch, seq, dim] float32
         if self._pooling == "cls":
             pooled = hidden[:, 0, :]
         else:

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/index/_search.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from ._shared import *  # noqa: F401,F403
+from ..model_slot import model_slot
 
 
 class _SearchMixin:
@@ -150,11 +151,14 @@ class _SearchMixin:
 
         Retired versions (``is_latest_version: false``) are hidden unless
         ``include_retired`` — see ``search_ranking.generate_candidates``."""
-        return self._hybrid_search_impl(
-            query, k=k, rrf_k=rrf_k, candidate_factor=candidate_factor,
-            rerank=rerank, reranker=reranker, rerank_top=rerank_top,
-            rerank_gate=rerank_gate, trace=None, include_retired=include_retired,
-        )
+        # The slot is taken HERE, before the reranker's 30 s budget starts, so
+        # a queued search waits instead of silently losing its rerank.
+        with model_slot():
+            return self._hybrid_search_impl(
+                query, k=k, rrf_k=rrf_k, candidate_factor=candidate_factor,
+                rerank=rerank, reranker=reranker, rerank_top=rerank_top,
+                rerank_gate=rerank_gate, trace=None, include_retired=include_retired,
+            )
 
     def hybrid_search_with_trace(
         self,
@@ -187,11 +191,12 @@ class _SearchMixin:
             candidate_limit=n,
             result_limit=max(0, k),
         )
-        hits = self._hybrid_search_impl(
-            query, k=k, rrf_k=rrf_k, candidate_factor=candidate_factor,
-            rerank=rerank, reranker=reranker, rerank_top=rerank_top,
-            rerank_gate=rerank_gate, trace=trace, include_retired=include_retired,
-        )
+        with model_slot():  # see hybrid_search
+            hits = self._hybrid_search_impl(
+                query, k=k, rrf_k=rrf_k, candidate_factor=candidate_factor,
+                rerank=rerank, reranker=reranker, rerank_top=rerank_top,
+                rerank_gate=rerank_gate, trace=trace, include_retired=include_retired,
+            )
         return hits, trace
 
     def _hybrid_search_impl(

brainiac_cli-0.20.45/src/brain/model_slot.py

@@ -0,0 +1,110 @@
+"""Machine-wide cap on concurrent model work (load + inference).
+
+WHY. One `brain search` peaks at ~4 GB for a few seconds: loading the fp32
+reranker alone measures 3.0 GB, a 15-pair rerank adds ~1 GB (measured
+2026-10-18, M4 Pro). On 2026-10-18 three subagents ran ten searches at once on
+a 24 GB Mac; macOS recorded ten Python processes at 4.1-6.8 GB each and the
+machine froze until a forced reset. Jetsam stopped only small system daemons,
+never the searches. Nothing in brain bounded how many ran together.
+
+WHAT. `model_slot()` waits for one of `$BRAIN_MODEL_SLOTS` (default 2) slot
+files under `$BRAIN_MODEL_SLOT_DIR` (default ~/.cache/brain-model-slots) and
+holds an exclusive `flock` on it for the duration of the block. The kernel drops
+the lock when the process dies, so a crash never leaks a slot.
+
+RE-ENTRANT PER PROCESS. A search holds a slot and its reranker worker thread
+runs inside it; that work must not wait for a second slot. So the first
+acquire in a process takes a slot, and nested or concurrent acquires in the
+same process ride on it until the depth returns to zero. The cap is therefore
+"processes doing model work", which is what costs memory.
+
+FAIL OPEN. If the slot directory cannot be created or opened (read-only HOME,
+Windows without fcntl), the work runs unguarded: a guard must never stop a
+search from working. ponytail: no Windows lock — add msvcrt when a Windows
+host runs parallel searches.
+"""
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Iterator
+
+try:
+    import fcntl
+except ImportError:  # Windows
+    fcntl = None  # type: ignore[assignment]
+
+_POLL_SECONDS = 0.2
+_gate = threading.Lock()  # a second thread waits here while the first acquires
+_state = threading.Lock()
+_depth = 0
+_fd: int | None = None
+
+
+def slot_count() -> int:
+    raw = os.environ.get("BRAIN_MODEL_SLOTS", "").strip()
+    return int(raw) if raw.isdigit() and int(raw) > 0 else 2
+
+
+def slot_dir() -> Path:
+    raw = os.environ.get("BRAIN_MODEL_SLOT_DIR")
+    return Path(raw) if raw else Path.home() / ".cache" / "brain-model-slots"
+
+
+def _try_take(paths: list[Path]) -> int | None:
+    for path in paths:
+        fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o644)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            os.close(fd)
+            continue
+        return fd
+    return None
+
+
+def _acquire() -> int | None:
+    if fcntl is None:
+        return None
+    try:
+        root = slot_dir()
+        root.mkdir(parents=True, exist_ok=True)
+        paths = [root / f"slot-{i}.lock" for i in range(slot_count())]
+        fd = _try_take(paths)
+        if fd is not None:
+            return fd
+        print(f"brain: waiting for a model slot ({len(paths)} in use on this "
+              "machine; $BRAIN_MODEL_SLOTS sets the cap)", file=sys.stderr, flush=True)
+        while fd is None:
+            time.sleep(_POLL_SECONDS)
+            fd = _try_take(paths)
+        return fd
+    except OSError as exc:
+        print(f"brain: model slot unavailable ({exc}); running unguarded",
+              file=sys.stderr, flush=True)
+        return None
+
+
+@contextlib.contextmanager
+def model_slot() -> Iterator[None]:
+    global _depth, _fd
+    with _gate:
+        with _state:
+            first = _depth == 0
+        fd = _acquire() if first else None  # a KeyboardInterrupt here holds nothing
+        with _state:
+            _depth += 1
+            if first:
+                _fd = fd
+    try:
+        yield
+    finally:
+        with _state:
+            _depth -= 1
+            if _depth == 0 and _fd is not None:
+                os.close(_fd)  # closing the only fd on the file drops the flock
+                _fd = None

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/rerank.py

@@ -40,18 +40,21 @@ import os
 from typing import Protocol, Sequence, runtime_checkable
 
 
+# Measured 2026-10-19: 4 threads match the all-cores wall time at ~40% of the CPU.
+_DEFAULT_THREADS = 4
+
+
 def _ort_threads() -> int | None:
     """Intra-op thread count for the reranker ONNX session (S11 speed fix).
 
-    Default: all physical cores. The reranker cross-encodes the top-N
-    (query, passage) pairs in ONE batched forward pass, so saturating the
-    batch dimension across cores is what keeps query p95 interactive.
+    Default: 4 threads (capped at the core count). More threads spin without
+    cutting wall time; raise it for bulk work.
     Override via ``$BRAIN_RERANK_THREADS``."""
     raw = os.environ.get("BRAIN_RERANK_THREADS")
     if raw and raw.strip().isdigit():
         return int(raw)
     try:
-        return os.cpu_count() or None
+        return min(_DEFAULT_THREADS, os.cpu_count() or _DEFAULT_THREADS)
     except Exception:
         return None
 

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/rerank_onnx.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 import os
 from typing import Sequence
 
+from .model_slot import model_slot
+
 # --- Fully-open reranker of record (replaces the CC-BY-NC jina-reranker-v2) ---
 # gte-multilingual-reranker-base is Apache-2.0, an XLM-R ENCODER cross-encoder
 # (~306M). It is the best QUALITY among the latency-affordable fully-open
@@ -178,9 +180,10 @@ class OnnxReranker:
                 t = _ort_threads()
                 if t:
                     so.intra_op_num_threads = t
-                self._sess = ort.InferenceSession(
-                    onnx_path, sess_options=so, providers=_ort_providers()
-                )
+                with model_slot():  # this load alone peaks at 3.0 GB
+                    self._sess = ort.InferenceSession(
+                        onnx_path, sess_options=so, providers=_ort_providers()
+                    )
                 self._in_names = [i.name for i in self._sess.get_inputs()]
                 self._tok = Tokenizer.from_file(os.path.join(base, "tokenizer.json"))
                 # Clamp (query, passage) pairs to the cross-encoder's context
@@ -222,6 +225,20 @@ class OnnxReranker:
         if not passages:
             return []
         self._ensure()
+        # Score in small batches, not all passages at once. Working memory
+        # grows with batch x seq^2 (self-attention over 1024-token pairs):
+        # one 15-20 pair batch peaked a search at ~4 GB, a long-lived MCP
+        # server retained 12 GB after 15 searches, and ten parallel searches
+        # froze a 24 GB Mac (2026-10-18). Scores are unchanged: each pad
+        # position is masked out of attention. Override via
+        # $BRAIN_RERANK_BATCH.
+        size = _rerank_batch()
+        scores: list[float] = []
+        for start in range(0, len(passages), size):
+            scores.extend(self._score(query, passages[start:start + size]))
+        return scores
+
+    def _score(self, query: str, passages: Sequence[str]) -> list[float]:
         import numpy as np
 
         enc = self._tok.encode_batch([(query, p) for p in passages])
@@ -236,9 +253,16 @@ class OnnxReranker:
                 feed[nm] = am
             elif "token_type" in low:
                 feed[nm] = np.zeros_like(ii)
-        logits = self._sess.run(None, feed)[0]
+        with model_slot():
+            logits = self._sess.run(None, feed)[0]
         return [float(x[0]) if hasattr(x, "__len__") else float(x) for x in logits]
 
+
+def _rerank_batch() -> int:
+    """Pairs per reranker run (default 4). See `OnnxReranker.rerank`."""
+    raw = os.environ.get("BRAIN_RERANK_BATCH", "")
+    return int(raw) if raw.strip().isdigit() and int(raw) > 0 else 4
+
 # Parent-namespace binds, deferred past this module's own defs (circular-import
 # safety, whichever of brain.rerank / brain.rerank_onnx loads first).
 from .rerank import RerankerUnavailable as RerankerUnavailable  # noqa: E402

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brain/update_channels.py

@@ -31,6 +31,12 @@ from .update_cos_guard import (
 #: old version — silently, because the crash pre-empted the report.
 WORKSPACE_SYNC_TIMEOUT_S = 1800
 
+#: The engine reinstall is a real pip/uv/pipx install, and it too borrowed the
+#: shared 120s default. Measured 2026-10-17 on the v0.20.44 release: the venv
+#: install of the checkout (new mcp dependency set) took 6m39s, so `brain
+#: update` returned {"error": "TimeoutExpired"} before it re-staged anything.
+ENGINE_INSTALL_TIMEOUT_S = 1800
+
 Runner = Callable[..., subprocess.CompletedProcess[str]]
 ChannelDetector = Callable[[Optional[Path]], str]
 VenvBinResolver = Callable[[Path, str], Path]
@@ -63,12 +69,12 @@ def _read_installed_version(
 
 def upgrade_uv_tool(run: Runner) -> subprocess.CompletedProcess[str]:
     """Upgrade the uv-managed distribution."""
-    return run(["uv", "tool", "upgrade", "brainiac-cli"])
+    return run(["uv", "tool", "upgrade", "brainiac-cli"], timeout=ENGINE_INSTALL_TIMEOUT_S)
 
 
 def upgrade_pipx(run: Runner) -> subprocess.CompletedProcess[str]:
     """Upgrade the pipx-managed distribution."""
-    return run(["pipx", "upgrade", "brainiac-cli"])
+    return run(["pipx", "upgrade", "brainiac-cli"], timeout=ENGINE_INSTALL_TIMEOUT_S)
 
 
 def upgrade_pip_user(
@@ -84,7 +90,7 @@ def upgrade_pip_user(
         "--user",
         "--upgrade",
         "brainiac-cli[mcp]",
-    ])
+    ], timeout=ENGINE_INSTALL_TIMEOUT_S)
 
 
 def upgrade_venv_wheel(
@@ -93,7 +99,7 @@ def upgrade_venv_wheel(
     target: str,
 ) -> subprocess.CompletedProcess[str]:
     """Upgrade a non-editable wheel inside the legacy venv."""
-    return run([str(pip_path), "install", "--upgrade", target])
+    return run([str(pip_path), "install", "--upgrade", target], timeout=ENGINE_INSTALL_TIMEOUT_S)
 
 
 def upgrade_editable(
@@ -102,7 +108,7 @@ def upgrade_editable(
     engine_src: Path,
 ) -> subprocess.CompletedProcess[str]:
     """Upgrade the editable checkout inside the legacy venv."""
-    return run([str(pip_path), "install", "--upgrade", "-e", f"{engine_src}[mcp]"])
+    return run([str(pip_path), "install", "--upgrade", "-e", f"{engine_src}[mcp]"], timeout=ENGINE_INSTALL_TIMEOUT_S)
 
 
 def refresh_engine_channel(

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45/src/brainiac_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainiac-cli
-Version: 0.20.44
+Version: 0.20.45
 Summary: Brainiac — local any-LLM second-brain core engine + brain CLI (Markdown truth, derived SQLite index).
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/Autopsias/brainiac

{brainiac_cli-0.20.44 → brainiac_cli-0.20.45}/src/brainiac_cli.egg-info/SOURCES.txt

@@ -138,6 +138,7 @@ src/brain/mcp_housekeeping_verbs.py
 src/brain/mcp_mediation.py
 src/brain/mcp_supersede_verbs.py
 src/brain/mcp_verbs.py
+src/brain/model_slot.py
 src/brain/multihop.py
 src/brain/notes.py
 src/brain/originals_resolve.py