brain-framework 18.1.2__tar.gz → 18.1.4__tar.gz

{brain_framework-18.1.2 → brain_framework-18.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brain-framework
-Version: 18.1.2
+Version: 18.1.4
 Summary: 🧠 Brain Framework: from information to informed actions.
 Keywords: ai,ai-agents,agent-memory,context-engineering,knowledge-management,local-first,mcp,model-context-protocol,python,second-brain
 Author: Médéric Hurier
@@ -29,7 +29,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-framework.svg"
-    alt="Brain Framework: an exposed brain in an opening shell above twin aperture eyes"
+    alt="Brain Framework: a robot head whose shell opens on a brain, above twin aperture eyes"
     width="256"
     height="256"
   >
@@ -62,7 +62,7 @@ Brain Framework (BF) changes the starting point. Create a brain, a plain folder,
 <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/blank-vs-brain.svg">
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/blank-vs-brain.svg"
-    alt="Two fictional sessions ask whether the new website can launch. Opened anywhere, the agent asks you to paste Jira, GitHub and Google Cloud. Opened in a brain, it reads project:new-website and answers: not yet, Jira still blocks launch on accessibility review, citing each record."
+    alt="Two fictional sessions ask whether the new website can launch. Opened anywhere, the agent asks you to paste Jira, GitHub and Google Cloud. Opened in a brain, it reads project:new-website and answers: not yet, Jira still blocks launch on accessibility review, citing each record, then notes the launch hold in the project note."
     width="960"
   >
 </a>
@@ -181,7 +181,7 @@ Reading files gives you one document at a time, and grep finds words, not connec
 bf read project:new-website
 ```
 
-The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs and fields):
+The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs, kinds and statuses):
 
 ```json
 {
@@ -308,7 +308,7 @@ After reviewing your sensors, run `bf watch` to keep them refreshed and see fail
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/watch.svg"
     alt="Watch dashboard for the fictional offline demo: five sensors sorted by state, with a failed sensor's details beside their last success, next due time, item count and record changes."
-    width="720"
+    width="960"
   >
 </a>
 

{brain_framework-18.1.2 → brain_framework-18.1.4}/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-framework.svg"
-    alt="Brain Framework: an exposed brain in an opening shell above twin aperture eyes"
+    alt="Brain Framework: a robot head whose shell opens on a brain, above twin aperture eyes"
     width="256"
     height="256"
   >
@@ -34,7 +34,7 @@ Brain Framework (BF) changes the starting point. Create a brain, a plain folder,
 <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/blank-vs-brain.svg">
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/blank-vs-brain.svg"
-    alt="Two fictional sessions ask whether the new website can launch. Opened anywhere, the agent asks you to paste Jira, GitHub and Google Cloud. Opened in a brain, it reads project:new-website and answers: not yet, Jira still blocks launch on accessibility review, citing each record."
+    alt="Two fictional sessions ask whether the new website can launch. Opened anywhere, the agent asks you to paste Jira, GitHub and Google Cloud. Opened in a brain, it reads project:new-website and answers: not yet, Jira still blocks launch on accessibility review, citing each record, then notes the launch hold in the project note."
     width="960"
   >
 </a>
@@ -153,7 +153,7 @@ Reading files gives you one document at a time, and grep finds words, not connec
 bf read project:new-website
 ```
 
-The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs and fields):
+The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs, kinds and statuses):
 
 ```json
 {
@@ -280,7 +280,7 @@ After reviewing your sensors, run `bf watch` to keep them refreshed and see fail
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/watch.svg"
     alt="Watch dashboard for the fictional offline demo: five sensors sorted by state, with a failed sensor's details beside their last success, next due time, item count and record changes."
-    width="720"
+    width="960"
   >
 </a>
 

{brain_framework-18.1.2 → brain_framework-18.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brain-framework"
-version = "18.1.2"
+version = "18.1.4"
 description = "🧠 Brain Framework: from information to informed actions."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -146,6 +146,8 @@ skip_empty = true
 [dependency-groups]
 dev = [
     "jsonschema>=4.26.0,<5",
+    "markdown>=3.11",
+    "packaging>=26.3",
     "pytest-cov>=7.1.0",
     "pytest-watcher>=0.6.3",
     "pytest>=9.1.1",

{brain_framework-18.1.2 → brain_framework-18.1.4}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 # https://packaging.python.org/en/latest/specifications/pyproject-toml/
 [project]
 name = "brain-framework"
-version = "18.1.2"
+version = "18.1.4"
 description = "🧠 Brain Framework: from information to informed actions."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -56,6 +56,9 @@ module-name = "bf"
 [dependency-groups]
 dev = [
   "jsonschema>=4.26.0,<5",
+  # Imported directly by tests/test_readme.py, as Zensical renders headings, and scripts/notices.py.
+  "markdown>=3.11",
+  "packaging>=26.3",
   "pytest-cov>=7.1.0",
   "pytest-watcher>=0.6.3",
   "pytest>=9.1.1",

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/__init__.py

@@ -2,7 +2,7 @@
 
 import os
 
-__version__ = "18.1.2"
+__version__ = "18.1.4"
 
 
 def main() -> None:

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/cli.py

@@ -591,6 +591,8 @@ def perform(
     if hook:
         _option("--hook", _slug, hook)
         names, args = (), values
+    elif values and not values[0].strip():
+        raise typer.BadParameter("give a routine name; an empty value names none", param_hint="ROUTINE")
     elif values:
         names, args = values[:1], values[1:]
     else:
@@ -855,14 +857,20 @@ def _input() -> bytes:
     return data
 
 
-# Values that choose where a command acts, as help names them. Given empty, as an unset variable gives them, they
-# would silently choose another brain or a directory, so they are invalid input; an omitted one keeps its default.
+# Values that choose where or on what a command acts, as help names them. Given empty, as an unset variable gives
+# them, they would silently choose another brain, directory, window or operation, so they are invalid input; an
+# omitted one keeps its default.
 _GIVEN = {
     "--brain": "give a brain name or path; an empty value would select another brain",
     "--hook": "give an event name; an empty value would run the first argument as a routine",
     "--output": "give a directory; an empty value would name the brain's root",
+    "--reproject": "give a sensor name; an empty value would rebuild the cache instead",
+    "--routine": "give a routine name; an empty value names none",
+    "--sensor": "give a sensor name; an empty value names none",
+    "--since": "give a start time; an empty value would collect the default window",
     "DIR": "give a directory; an empty value would name the working directory",
     "PATH": "give a directory; an empty value would name the working directory",
+    "SENSOR": "give a sensor name from bf.yaml",
 }
 
 
@@ -903,7 +911,8 @@ class _Command(TyperCommand):
         for param in self.params:
             value = given.get(param.name)
             reason = _GIVEN.get(_named(param.get_error_hint(ctx)))
-            if reason and isinstance(value, str) and not value.strip():
+            values = value if isinstance(value, list) else [value]
+            if reason and any(isinstance(item, str) and not item.strip() for item in values):
                 return typer.BadParameter(reason, ctx, param)
         return None
 

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/config.py

@@ -212,20 +212,17 @@ def register(store: Store) -> dict[str, object]:
         replaced = ""
         if (existing := registry.brains.get(name)) and existing.path != str(store.root):
             try:
-                registered = Store(Path(existing.path).expanduser())
+                registered = _registered(existing)
             except Error as error:
-                # Only a missing directory frees the name: an unreachable one may still hold that brain.
-                if not isinstance(error.__cause__, FileNotFoundError):
-                    raise Error(
-                        f"cannot reach the brain registered as {name} at {existing.path}; restore access to it, or "
-                        f"remove that entry from {path}"
-                    ) from error
-            else:
-                if registered.identity != store.identity:
-                    raise Error(
-                        f"another brain is already registered as {name} at {existing.path}; remove that entry from "
-                        f"{path}, or rename one of the brains in its bf.yaml"
-                    )
+                raise Error(
+                    f"cannot reach the brain registered as {name} at {existing.path}; restore access to it, or "
+                    f"remove that entry from {path}"
+                ) from error
+            if registered is not None and registered.identity != store.identity:
+                raise Error(
+                    f"another brain is already registered as {name} at {existing.path}; remove that entry from "
+                    f"{path}, or rename one of the brains in its bf.yaml"
+                )
             replaced = existing.path
         registry.brains[name] = Registration(path=str(store.root))
         document = {"brains": {key: value.model_dump() for key, value in sorted(registry.brains.items())}}
@@ -254,12 +251,30 @@ ABSENT = (
 )
 
 
+UNREACHABLE = "registered brain directory exists but cannot be reached; restore access to it"
+
+
+def _registered(entry: Registration) -> Store | None:
+    """A registered brain, or None when its directory is absent: missing, or no longer a directory.
+
+    One that exists but cannot be reached, such as a locked folder or a disconnected mount, may still hold that
+    brain and return: it fails with UNREACHABLE, so neither selection nor bf register treats it as moved.
+    """
+    try:
+        return Store(Path(entry.path).expanduser())
+    except Error as error:
+        cause = error.__cause__
+        if isinstance(cause, OSError) and not isinstance(cause, FileNotFoundError | NotADirectoryError):
+            raise Error(UNREACHABLE) from cause
+        return None
+
+
 class Selection(list[Store]):
-    """Selected roots, plus the names of registered brains that are absent on this machine."""
+    """Selected roots, plus each registered brain this machine cannot use, by name, with its error."""
 
-    def __init__(self, stores: Iterable[Store] = (), absent: Iterable[str] = ()) -> None:
+    def __init__(self, stores: Iterable[Store] = (), unavailable: dict[str, str] | None = None) -> None:
         super().__init__(stores)
-        self.absent = tuple(absent)
+        self.unavailable = unavailable or {}
 
 
 def related(roots: list[Store]) -> tuple[list[Store], list[dict[str, object]]]:
@@ -272,7 +287,8 @@ def related(roots: list[Store]) -> tuple[list[Store], list[dict[str, object]]]:
         candidates.setdefault(store.identity, store)
     names: dict[str, set[str]] = {}
     problems: list[dict[str, object]] = [
-        {"brain": name, "error": ABSENT} for name in (roots.absent if isinstance(roots, Selection) else ())
+        {"brain": name, "error": error}
+        for name, error in (roots.unavailable.items() if isinstance(roots, Selection) else ())
     ]
     for store in roots:
         try:
@@ -342,14 +358,11 @@ def _located(value: str, *, execute: bool = False) -> Store:
     local, referenced = _claim(value, registered=entry is not None)
     if entry is not None:
         try:
-            store = Store(Path(entry.path).expanduser())
-        except Error as error:
-            # As bf register decides: only a missing directory is absent; an unreachable one may return.
-            if isinstance(error.__cause__, OSError) and not isinstance(
-                error.__cause__, FileNotFoundError | NotADirectoryError
-            ):
-                raise Error(f"cannot reach the brain registered as {value}; restore access to its directory") from None
-            raise Error(f"{value}: {ABSENT}") from None
+            store = _registered(entry)
+        except Error:
+            raise Error(f"cannot reach the brain registered as {value}; restore access to its directory") from None
+        if store is None:
+            raise Error(f"{value}: {ABSENT}")
         if local is not None and local.identity != store.identity:
             raise Error(
                 f"ambiguous brain name {value}: the registry and the enclosing brain name different directories; "
@@ -405,26 +418,32 @@ def select(value: str = "") -> list[Store]:
         return [_located(chosen)]
     if nearest := _nearest():
         return [nearest]
-    # Retrieval reports registered brains absent on this machine instead of silently answering without them.
-    stores, names, absent = [], [], []
+    # Retrieval reports registered brains this machine cannot use instead of silently answering without them.
+    stores: list[Store] = []
+    names: list[str] = []
+    unavailable: dict[str, str] = {}
     for name, entry in sorted(user_config().brains.items()):
-        path = Path(entry.path).expanduser()
-        if path.is_dir():
-            stores.append(Store(path))
-            names.append(name)
+        try:
+            store = _registered(entry)
+        except Error as error:
+            unavailable[name] = str(error)
+            continue
+        if store is None:
+            unavailable[name] = ABSENT
         else:
-            absent.append(name)
-    if absent and not stores:
+            stores.append(store)
+            names.append(name)
+    if unavailable and not stores:
         raise Error(
-            f"registered brains are absent on this machine: {', '.join(absent)}; restore them, run bf register at "
-            "their new place, or remove their registry entries"
+            f"registered brains are unavailable on this machine: {', '.join(unavailable)}; restore them or access to "
+            "them, run bf register at their new place, or remove their registry entries"
         )
     if not stores:
         raise Error("no brain selected; pass --brain, run inside a brain, or register one with bf register")
     # The only registered brain may have lost its bf.yaml: name that before a command reads or caches it. Of several,
     # retrieval reports each one whose bf.yaml does not load.
     only = [_configured(stores[0], f"registered brain {names[0]}")] if len(stores) == 1 else stores
-    return Selection(only, absent)
+    return Selection(only, unavailable)
 
 
 def brain_name(store: Store) -> str:

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/health.py

@@ -8,7 +8,7 @@ from datetime import UTC, datetime, timedelta
 from typing import cast
 
 from bf import index, usage
-from bf.config import ABSENT, Selection, brain_name, load, related
+from bf.config import Selection, brain_name, load, related
 from bf.history import ROUTINES, log_path, state
 from bf.models import CACHE, Config, Error, Program
 from bf.storage import Store
@@ -126,9 +126,8 @@ def attention(store: Store, now: datetime | None = None) -> list[dict[str, objec
 def report(stores: list[Store], now: datetime | None = None) -> dict[str, object]:
     """Per brain: cache, notes, records, source and routine freshness, errors, logs and usage."""
     now = now or datetime.now(UTC)
-    brains: list[dict[str, object]] = [
-        {"brain": name, "error": ABSENT} for name in (stores.absent if isinstance(stores, Selection) else ())
-    ]
+    unavailable = stores.unavailable if isinstance(stores, Selection) else {}
+    brains: list[dict[str, object]] = [{"brain": name, "error": error} for name, error in unavailable.items()]
     healthy = not brains
     for store in stores:
         try:
@@ -185,7 +184,7 @@ def report(stores: list[Store], now: datetime | None = None) -> dict[str, object
         )
     # A reference that retrieval cannot include makes every search and read incomplete, like a skipped file.
     for problem in related(stores)[1]:
-        if problem["error"] == ABSENT:
+        if problem["brain"] in unavailable:
             continue
         healthy = False
         owners = [entry for entry in brains if entry["brain"] == problem["brain"] and "problems" in entry]

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/index.py

@@ -39,7 +39,7 @@ from bf.models import (
 )
 from bf.storage import UNNAMED, BusyError, Store, building, generation, reader, unnamed, writer
 
-SCHEMA = 32
+SCHEMA = 33
 CACHE = ".bf/index.sqlite"
 # A full build fills this file beside the live cache, then renames it over CACHE.
 BUILD = CACHE + ".new"
@@ -1060,9 +1060,10 @@ def _verbatim(snippet: str, original: str) -> str:
     """The original words behind a snippet of a folded passage, so `m²` or `…` never reads as `m2` or `...`.
 
     Folding each whitespace-separated run yields the folded passage, so every snippet position maps to one run.
+    ASCII is already folded, which keeps a large passage with a single `²` or no-break space fast.
     """
     runs = re.findall(r"\s+|\S+", original)
-    forms = [fold(run) for run in runs]
+    forms = [run if run.isascii() else fold(run) for run in runs]
     head = _ELLIPSIS if snippet.startswith(_ELLIPSIS) else ""
     tail = _ELLIPSIS if snippet.endswith(_ELLIPSIS) else ""
     window = snippet.removeprefix(head).removesuffix(tail)
@@ -1071,7 +1072,9 @@ def _verbatim(snippet: str, original: str) -> str:
         return snippet
     end, position, kept = start + len(window), 0, []
     for run, form in zip(runs, forms, strict=True):
-        if start < position + len(form) and position < end:
+        if position >= end:
+            break
+        if start < position + len(form):
             kept.append(run)
         position += len(form)
     return head + "".join(kept) + tail

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/markdown.py

@@ -457,9 +457,12 @@ def note(path: str, data: bytes | Markdown) -> Note:
     # H2+ sections are separate passages, so a search can land on the answering section.
     # Headings rank through each passage's title; its text, and so its excerpt, starts below them.
     # A section also ranks under its parents: `## Vega` then `### Budget` answers "Vega budget".
+    # An H1 after the first section, as in a copied document, is one too, even the title's: it ends the section
+    # above it, as an exact read of that section's ref does, so search never lands on a section without the match.
     source_lines = lines(markdown.text)
-    sections = [h for h in markdown.headings if h.level >= 2]
     titled = next((h for h in markdown.headings if h.level == 1 and h.title == title), None)
+    first = next((n for n, h in enumerate(markdown.headings) if h.level >= 2), len(markdown.headings))
+    sections = markdown.headings[first:]
     hidden = range(titled.line, titled.end) if titled else range(0)
     opening = range(markdown.offset, sections[0].line if sections else len(source_lines))
     introduction = "".join(source_lines[n] for n in opening if n not in hidden)

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/mcp.py

@@ -193,6 +193,8 @@ def server(stores: list[Store] | Callable[[], list[Store]]) -> MCPServer:
         title="Brain Framework",
         version=__version__,
         instructions=INSTRUCTIONS,
+        # The SDK logs each rejected or failed call at INFO on stderr, in its own format: replies already carry them.
+        log_level="WARNING",
         tools=[
             _strict(Tool.from_function(function, name=name, title=title, annotations=annotations), output)
             for name, title, function, output in (

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/models.py

@@ -452,9 +452,12 @@ class Record(Model):
         return value
 
     def readable(self) -> Record:
-        """An exact read pages only `text`: everything else must fit its first page within the reply limit."""
-        size = sum(map(len, (self.id, self.title, self.url, *self.links, *self.aliases)))
-        if size > MAX_FIELDS or size + len(encode(self.attributes)) + len(encode(self.fields)) > MAX_FIELDS:
+        """An exact read pages only `text`: everything else must fit its first page within the reply limit.
+
+        Counted in encoded bytes, as the reply limit is: non-ASCII or escaped characters take more than one.
+        """
+        others = [self.id, self.title, self.url, self.links, self.aliases, self.attributes, self.fields]
+        if len(encode(others)) > MAX_FIELDS:
             raise ValueError("fields other than text exceed 2 MiB; keep bulky content in text")
         return self
 

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/pages.py

@@ -102,6 +102,9 @@ def period(value: str, now: datetime | None = None) -> Period | None:
         if value in {"today", "yesterday"}:
             day = now.date() - timedelta(days=value == "yesterday")
         elif value[-1] in "hdw":
+            # An empty window holds nothing: `0d` would be a page no search scope could match.
+            if not int(value[:-1]):
+                raise ValueError
             start = now - timedelta(hours=int(value[:-1]) * {"h": 1, "d": 24, "w": 168}[value[-1]])
             return Period(timestamp(start.isoformat()), timestamp(now.isoformat()))
         elif ".." in value:

{brain_framework-18.1.2 → brain_framework-18.1.4}/src/bf/retrieve.py

@@ -406,8 +406,8 @@ def _holders(
     for store in selected:
         try:
             value = _read(store, ref)
-        except InputError, NotFoundError:
-            # Malformed input and a missing section are the ref's problems, not a brain's.
+        except InputError:
+            # Malformed input is the ref's problem, not a brain's. A copy without the section is that brain's.
             raise
         except (Error, OSError, sqlite3.DatabaseError) as error:
             if len(selected) == 1: