brain-framework 9.0.1__py3-none-any.whl

bf/config.py

@@ -0,0 +1,152 @@
+"""Strict YAML, one brain configuration, and the user's brain registry."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import cast
+
+import yaml
+import yaml.resolver
+from pydantic import ValidationError
+
+from bf.models import Config, Error, Registration, UserConfig, explain
+from bf.storage import Store, writer
+
+
+class _Loader(yaml.SafeLoader):
+    """Reject duplicate mappings rather than accepting a hidden override."""
+
+
+def _mapping(loader: _Loader, node: yaml.MappingNode) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key_node, value_node in node.value:
+        key = loader.construct_object(key_node)
+        if not isinstance(key, str) or key in result:
+            raise Error("YAML mapping keys must be unique strings")
+        result[key] = loader.construct_object(value_node)
+    return result
+
+
+_Loader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _mapping)
+# Dates are validated by their owning models; YAML must not turn them into other types.
+_Loader.add_constructor("tag:yaml.org,2002:timestamp", lambda loader, node: loader.construct_scalar(node))
+
+
+def yaml_object(data: bytes) -> dict[str, object]:
+    """No aliases, anchors, duplicate keys, deep documents or large node graphs."""
+    if len(data) > 1 << 20:
+        raise Error("YAML exceeds 1 MiB")
+    try:
+        depth = 0
+        for count, event in enumerate(yaml.parse(data), 1):
+            if isinstance(event, yaml.AliasEvent) or getattr(event, "anchor", None):
+                raise Error("YAML anchors and aliases are not supported")
+            if isinstance(event, (yaml.MappingStartEvent, yaml.SequenceStartEvent)):
+                depth += 1
+            if isinstance(event, (yaml.MappingEndEvent, yaml.SequenceEndEvent)):
+                depth -= 1
+            if depth > 32 or count > 20_000:
+                raise Error("YAML structure exceeds its limit")
+        value = yaml.load(data, Loader=_Loader)  # noqa: S506 - restricted SafeLoader subclass
+    except (yaml.YAMLError, UnicodeError) as error:
+        raise Error("invalid YAML") from error
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise Error("YAML must contain one mapping")
+    return cast(dict[str, object], value)
+
+
+def load(store: Store) -> Config:
+    value = yaml_object(store.read("bf.yaml", 1 << 20))
+    try:
+        return Config.model_validate(value)
+    except ValidationError as error:
+        raise Error("invalid bf.yaml: " + explain(error)) from error
+
+
+def user_path() -> Path:
+    root = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(root).expanduser() / "bf" / "config.yaml"
+
+
+def user_config() -> UserConfig:
+    """The optional user registry; a missing file means no registered brains."""
+    path = user_path()
+    try:
+        with path.open("rb") as stream:
+            data = stream.read((1 << 20) + 1)
+    except FileNotFoundError:
+        return UserConfig()
+    try:
+        return UserConfig.model_validate(yaml_object(data))
+    except ValidationError as error:
+        raise Error(f"invalid {path}: " + explain(error)) from error
+
+
+def register(store: Store, *, collect: bool) -> dict[str, object]:
+    """Add or update this brain in the user registry, keyed by its configured name."""
+    name = load(store).name
+    path = user_path()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    registry_store = Store(path.parent)
+    # Registration is one shared read/modify/write transaction, independent of each brain's lock.
+    with writer(registry_store, wait=30):
+        registry = user_config()
+        for other, entry in registry.brains.items():
+            if other != name and Path(entry.path).expanduser().resolve() == store.root:
+                raise Error(f"this directory is already registered as {other}")
+        existing = registry.brains.get(name)
+        if existing and Path(existing.path).expanduser().resolve() != store.root:
+            raise Error(f"another brain is already registered as {name}; rename one of them in bf.yaml")
+        registry.brains[name] = Registration(path=str(store.root), collect=collect)
+        document = {"brains": {key: value.model_dump() for key, value in sorted(registry.brains.items())}}
+        registry_store.write(
+            path.name,
+            ("# https://fmind.github.io/brain-framework/\n" + yaml.safe_dump(document, sort_keys=True)).encode(),
+        )
+    return {"brain": name, "path": str(store.root), "collect": collect, "config": str(path)}
+
+
+def _located(value: str) -> Store:
+    registry = user_config()
+    if value in registry.brains:
+        return Store(Path(registry.brains[value].path).expanduser())
+    return Store(Path(value).expanduser())
+
+
+def _nearest() -> Store | None:
+    for candidate in (Path.cwd(), *Path.cwd().parents):
+        if (candidate / "bf.yaml").is_file():
+            return Store(candidate)
+    return None
+
+
+def select(value: str = "") -> list[Store]:
+    """--brain NAME|PATH, then BF_BRAIN, then the enclosing brain, then every registered brain."""
+    chosen = value or os.environ.get("BF_BRAIN", "")
+    if chosen:
+        return [_located(chosen)]
+    if nearest := _nearest():
+        return [nearest]
+    # A shared user configuration may list brains that exist only on some machines; skip absent ones.
+    paths = [Path(entry.path).expanduser() for _, entry in sorted(user_config().brains.items())]
+    stores = [Store(path) for path in paths if path.is_dir()]
+    if not stores:
+        raise Error("no brain selected; pass --brain, run inside a brain, or register one with bf register")
+    return stores
+
+
+def one(value: str = "") -> Store:
+    stores = select(value)
+    if len(stores) != 1:
+        raise Error("several brains are registered; pass --brain NAME")
+    return stores[0]
+
+
+def may_collect(store: Store) -> bool:
+    return any(
+        entry.collect and Path(entry.path).expanduser().resolve() == store.root
+        for entry in user_config().brains.values()
+    )

bf/evaluate.py

@@ -0,0 +1,84 @@
+"""Owner-written retrieval cases: the questions a brain must keep answering."""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, cast
+
+from pydantic import Field, ValidationError
+
+from bf.config import yaml_object
+from bf.markdown import authored, split_ref
+from bf.models import Error, Model, Query, Status, explain, moment
+from bf.retrieve import search
+from bf.storage import Store
+
+
+class Case(Model):
+    name: str
+    query: str = ""
+    since: str = ""
+    until: str = ""
+    source: str = ""
+    type: str = ""
+    status: Status = ""
+    recent: bool = False
+    changed_since: str = ""
+    current: bool = False
+    limit: Annotated[int, Field(ge=1, le=50)] = 10
+    # A note path without #fragment matches any of its sections.
+    expect: list[str] = Field(default_factory=list)
+    forbid: list[str] = Field(default_factory=list)
+    # Each text must appear in a returned title or excerpt: the answer is delivered, not only its location.
+    text: list[str] = Field(default_factory=list)
+    empty: bool = False
+
+
+class Suite(Model):
+    version: Literal[3] = 3
+    cases: Annotated[list[Case], Field(min_length=1, max_length=200)]
+
+
+def _matches(expected: str, refs: list[str]) -> bool:
+    return any(ref == expected or (authored(expected) and split_ref(ref)[0] == expected) for ref in refs)
+
+
+def evaluate(store: Store, path: str = "queries.yaml") -> dict[str, object]:
+    try:
+        suite = Suite.model_validate(yaml_object(store.read(path, 1 << 20)))
+    except ValidationError as error:
+        raise Error(f"invalid {path}: " + explain(error)) from error
+    results = []
+    for case in suite.cases:
+        if case.empty == bool(case.expect or case.text):
+            raise Error(f"case {case.name}: use expect/text, or empty: true")
+        query = Query(
+            text=case.query,
+            since=moment(case.since) if case.since else "",
+            until=moment(case.until) if case.until else "",
+            source=case.source,
+            type=case.type,
+            status=case.status,
+            limit=case.limit,
+            recent=case.recent,
+            changed_since=moment(case.changed_since) if case.changed_since else "",
+            current=case.current,
+        )
+        reply = search([store], query, counted=False)
+        items = cast("list[dict[str, object]]", reply["items"])
+        refs = [str(item["ref"]) for item in items]
+        delivered = "\n".join(f"{item.get('title', '')}\n{item.get('excerpt', '')}" for item in items)
+        missing = [ref for ref in case.expect if not _matches(ref, refs)]
+        forbidden = [ref for ref in case.forbid if _matches(ref, refs)]
+        absent = [text for text in case.text if text.casefold() not in delivered.casefold()]
+        passed = not (missing or forbidden or absent or reply.get("problems") or reply.get("stale")) and (
+            not case.empty or not items
+        )
+        result: dict[str, object] = {"name": case.name, "passed": passed}
+        if not passed:
+            result.update(missing=missing, forbidden=forbidden, absent=absent, returned=refs)
+            for field in ("problems", "stale"):
+                if field in reply:
+                    result[field] = reply[field]
+        results.append(result)
+    passed = sum(bool(r["passed"]) for r in results)
+    return {"passed": passed == len(results), "score": f"{passed}/{len(results)}", "cases": results}

bf/health.py

@@ -0,0 +1,48 @@
+"""Collection coverage shared by status and retrieval; freshness never implies complete history."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime, timedelta
+
+from bf.collect import state
+from bf.config import load, may_collect
+from bf.storage import Store
+
+
+def source_health(
+    store: Store, names: Iterable[str] = (), *, now: datetime | None = None
+) -> dict[str, dict[str, object]]:
+    """Describe active, disabled and historical sources without running them or exposing logs."""
+    now = now or datetime.now(UTC)
+    config, history, trusted = load(store), state(store), may_collect(store)
+    result: dict[str, dict[str, object]] = {}
+    for name in sorted({*config.sensors, *names}):
+        settings = config.sensors.get(name)
+        entry = history.get(name, {})
+        success = str(entry.get("success", ""))
+        item: dict[str, object] = {
+            "state": "historical" if settings is None else "active" if settings.enabled else "disabled",
+            "freshness": "unknown",
+        }
+        if success:
+            item["last_collected"] = success
+        if settings is not None:
+            item["mode"] = settings.mode
+        if (settings is None or settings.mode == "window") and entry.get("start") and entry.get("end"):
+            item["window"] = {"since": entry["start"], "until": entry["end"]}
+        if entry.get("error"):
+            item["failed"] = True
+        if settings is not None and settings.enabled:
+            if not settings.refresh:
+                item["freshness"] = "manual"
+            elif trusted:
+                item["freshness"] = (
+                    "never"
+                    if not success
+                    else "stale"
+                    if datetime.fromisoformat(success) < now - timedelta(seconds=2 * settings.refresh)
+                    else "fresh"
+                )
+        result[name] = item
+    return result